diff --git a/i18n/.pending/es/docs/development/migrations.md b/i18n/.pending/es/docs/development/migrations.md
new file mode 100644
index 0000000000..59bf277b6c
--- /dev/null
+++ b/i18n/.pending/es/docs/development/migrations.md
@@ -0,0 +1,151 @@
+
+> Esta página es una traducción automática de la [página en inglés](https://github.com/ClickHouse/loom/blob/main/docs/development/migrations.md), que prevalece.
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/development/migrations.md), which is authoritative.
+
+
+
+# Migraciones
+
+Esta página contiene las reglas para escribir una migración. La forma en que un despliegue las aplica, y los pasos de actualización y reversión, están en [actualizaciones](https://github.com/ClickHouse/loom/blob/main/docs/operations/upgrades.md#how-migrations-run). [`schemas/README.md`](https://github.com/ClickHouse/loom/blob/main/schemas/README.md) describe el directorio `schemas/` y enumera las herramientas del operador.
+
+
+
+## El journal y el ledger
+
+- El esquema es un journal de archivos SQL numerados en `schemas/migrations/`, aplicados en
+ orden de prefijo numérico por `server/core/schema/migrate.py`. `000_migrations.sql` crea el ledger;
+ `016_baseline.sql` es el esquema inicial; cada archivo posterior es un delta.
+- Cada archivo aplicado se registra en `loom._migrations` con el SHA-256 de su contenido.
+ Una nueva ejecución aplica solo los archivos nuevos. Un archivo modificado es **checksum drift** (deriva de checksum) y un archivo que el
+ repositorio ya no tiene es una **fila solo del ledger**; `loom migrate --dry-run --strict`
+ (un paso de CI y la verificación previa al despliegue) falla en ambos casos. Un archivo renombrado con su texto
+ sin cambios no es una fila solo del ledger: su SHA-256 lo identifica, y se registra con el nuevo
+ nombre sin ejecutarse de nuevo.
+- Cada archivo usa `loom.
` y `loom_telemetry.`. El runner los asigna
+ a `LOOM_CH_DATABASE` y `LOOM_CH_TELEMETRY_DATABASE` al enviar cada sentencia
+ (`server/core/ch_names.py`), de modo que el checksum se calcula sobre el archivo tal como está escrito. Una base de datos
+ se compara por valor como `currentDatabase()` o un nombre enlazado, nunca como un literal `'loom'`
+ (`tests/unit/test_ch_names.py`). Un archivo que cambia la clave o el TTL de una tabla cuyo
+ nombre empieza con `_`, o que renombra o intercambia una, también actualiza su fila en [disposición del
+ almacenamiento](https://github.com/ClickHouse/loom/blob/main/docs/architecture/storage-layout.md) y la protección de remodelado de
+ `tests/unit/test_storage_layout_rows.py`.
+
+
+
+## Numeración
+
+Un archivo se llama `NNN_description.sql`. El runner ordena por el prefijo entero, no por el
+nombre (`server/core/schema/journal.py`, `migration_order`), de modo que `1030_x.sql` se ejecuta después de `220_y.sql`. Toma el siguiente número libre, revisando `main`
+y los pull requests abiertos, y consérvalo: dos archivos con el mismo número se aplican igualmente, pero en el
+orden léxico de sus sufijos, que no es el orden que nadie pretendía, y un rebase
+que renombra uno no vuelve a aplicar nada. `tests/unit/test_migration_numeric_order.py` falla si
+se comparte un número.
+
+
+
+## Reglas para escribir una migración
+
+- **Nunca edites ni elimines una migración ya fusionada.** Los registros de los despliegues guardan su hash. Una corrección es un archivo nuevo.
+- **Solo cambios aditivos.** Añade tablas, columnas, índices, projections y vistas; elimina un índice de omisión (skip index) o una projection que ningún código bajo `server/`, `scripts/`, `bench/` o `dev/` nombre (la compilación anterior pierde una optimización, nunca una columna); cambia codecs, valores por defecto o ajustes de tabla; amplía tipos; extiende un enum. Nunca elimines ni renombres una tabla o una columna, y nunca intercambies tablas. `tests/unit/test_migrations_additive.py` lo hace cumplir. De las vistas y las tablas, solo permite `DROP VIEW IF EXISTS` de una vista materializada que actúa al insertar y `DROP TABLE IF EXISTS` de una tabla reemplazada, en cada caso cuando ningún archivo bajo `server/`, `scripts/`, `bench/` o `dev/` la nombra: ni una compilación en servicio ni una herramienta de operador (que se ejecutan contra el servicio de producción) la lee. Restringir un tipo queda como cuestión de revisión, ya que una expresión regular no puede distinguirlo de una ampliación.
+- **Retira una columna en dos versiones.** Primero publica una versión cuyo código ya no la lea ni la escriba; elimínala solo cuando ninguna compilación en servicio la nombre.
+- **Todo escritor lleva una columna nueva.** Añadir una columna a `loom.memory` o `loom.shared` implica actualizar los constructores de filas en `server/memory/store/rows.py` (`build_memory_version_row`, `build_embedding_row`) y cada projection que los alimenta en el mismo cambio: son tablas `ReplacingMergeTree(version)` que se leen con `FINAL`, y una fila de versión que omite una columna la pone a cero en silencio para todos los lectores. Una columna nueva de `loom.memory` también debe añadirse a `loom.memory_versions` y al `SELECT` de la vista `memory_versions_mv` en la misma migración; de lo contrario, el historial deja de registrarla (`tests/unit/test_memory_versions_schema.py` compara las listas de columnas).
+- **Una tabla que pueda contener contenido de memoria** necesita además un paso en la saga de borrado y una fila en el censo de residuos (`server/erasure/store/census.py`, `_CENSUS`); `tests/unit/test_every_table_is_classified.py` falla ante una tabla nueva que no figure en ninguna lista ([añadir una tabla](https://github.com/ClickHouse/loom/blob/main/docs/development/adding-a-table.md)).
+- **DDL portable entre motores.** Declara las columnas vectoriales como `Array(BFloat16) CODEC(NONE)`; donde el codec `Quantized` pueda estar activo, el runner las crea ya codificadas ([ajustes restringidos](../architecture/clickhouse.md#gated-clickhouse-settings)). Usa nombres de motor `MergeTree` simples, que ClickHouse Cloud ejecuta como `SharedMergeTree`.
+
+**Por qué aditivo.** La compilación que estaba en servicio antes de ejecutar una migración debe poder seguir leyendo y escribiendo después todas las tablas que conocía. Eso convierte un rollback blue/green en un cambio de proxy en lugar de un rollback de esquema, y permite que el color anterior siga sirviendo mientras el nuevo aplica las migraciones al arrancar. El precio se paga aquí: dos versiones para retirar una columna y reconstrucciones en lugar de `ALTER` para los cambios de clave.
+
+
+
+## Directivas del runner
+
+Un archivo de migración puede llevar directivas en comentarios que el runner lee:
+
+| Directiva | Efecto |
+| ----------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `-- loom: tolerate-error ` | el archivo sobrevive a un error del servidor con nombre (por ejemplo, un setting que solo aceptan algunos servidores) |
+| `-- loom: rebuild-if-empty ` | declara una clave de ordenación o de partición objetivo para `` (abajo) |
+| `-- loom: baseline covers N` | el archivo reemplaza a todos los archivos numerados N o menos que el repositorio ya no incluye |
+
+**Baselines.** Un baseline lleva el número N, posterior al del archivo más reciente que reemplaza. Una base de datos nueva lo ejecuta. Una base de datos cuyo ledger contiene el archivo N lo registra sin ejecutarlo y conserva las filas reemplazadas, que el modo estricto informa como reemplazadas (superseded) y no como errores. Así, una compactación (squash) no requiere editar a mano ningún ledger, y una compilación anterior a ella sigue encontrando aplicados todos sus propios archivos. Una base de datos cuyo ledger contiene algunos archivos reemplazados pero no el archivo N se detuvo a medio camino: `loom migrate` la rechaza (`stranded`) y no cambia nada, ya que ejecutar el baseline omitiría los archivos que le faltan y registrarlo daría por hecho su esquema. Aplica los archivos que faltan con una compilación anterior a la compactación y vuelve a migrar. Compacta en una versión, no en cada cambio; la compactación construye el baseline a partir de `schemas/schema.sql` (el cuerpo del volcado sin los objetos que crean los archivos que conserva) y lo comprueba en un servidor nuevo, en un ledger totalmente migrado y en uno a medio migrar.
+
+El runner también adapta sentencias al aplicarlas sin cambiar los archivos ni sus checksums: elimina el flag experimental de NLP donde el servidor lo prohíbe, crea las columnas vectoriales con el códec `Quantized` donde puede estar activo, quitando un códec general encadenado después de él donde `allow_suspicious_codecs` no puede estarlo (`server/core/schema/vector_codec_ddl.py`), crea cada vista con el usuario que ejecuta la migración (`DEFINER = CURRENT_USER`: el volcado nombra a su propio usuario, que otro servidor puede no tener) y espera a que termine cada mutación que emite un archivo antes de registrarlo (`LOOM_MIGRATE_MUTATION_WAIT_S`).
+
+**Verificaciones previas.** Un archivo que no debe ejecutarse mientras los datos contengan algo que el archivo por sí solo no puede ver registra una verificación en `server/core/schema/prechecks.py`, indexada por su nombre sin el número, de modo que un archivo renumerado la conserva. El runner ejecuta la verificación antes del archivo, también en una ejecución de prueba (dry run); una verificación que rechaza detiene la ejecución con su mensaje y no ejecuta nada del archivo. `097_mirror_names_reserved.sql` usa una: rechaza mientras un espacio de nombres con la forma reservada de espejo esté registrado o contenga filas vivas.
+
+
+
+## Cambiar una clave de ordenación o una clave de partición
+
+ClickHouse no cambia ninguna de las dos en el lugar, así que una migración declara el destino y la tabla se reconstruye, nunca se altera:
+
+```sql
+-- loom: rebuild-if-empty code_test_facets
+CREATE TABLE loom.code_test_facets ( ...every column, unchanged... ) ... ORDER BY (...);
+```
+
+Esa sentencia es la única copia del DDL de destino. El runner (`server/core/schema/table_rebuild.py`) compara el `sorting_key` y el `partition_key` de la tabla en vivo con ella: si coinciden, registra el archivo; una tabla vacía (una instalación nueva) se intercambia al instante por una gemela con el DDL de destino; y una tabla con filas hace fallar el arranque con un mensaje que nombra la herramienta. Un arranque nunca copia filas. En un despliegue con datos, el operador ejecuta primero la herramienta, una tabla a la vez:
+
+```bash
+python -P -m scripts.ops.table_rebuild --table code_test_facets --dry-run
+python -P -m scripts.ops.table_rebuild --table code_test_facets --yes
+```
+
+Toda acción que modifica algo (`--yes` solo, `--rollback`, `--drop-pre-rebuild`) imprime el ClickHouse con el que se comunica y su plan, y no cambia nada sin `--yes`. La herramienta copia todas las filas (sin FINAL) a `loom._rebuild` en lotes acotados, copia las partes escritas entretanto, comprueba el número de filas bajo FINAL y la versión más reciente de una muestra de claves, intercambia con `EXCHANGE TABLES` y conserva la tabla antigua como `loom._pre_rebuild` para `--rollback` hasta `--drop-pre-rebuild`. Se niega a intercambiar, conservando la gemela, cuando un `ALTER` cambió la tabla en vivo durante la copia: sale con 6 si ClickHouse lo ejecuta como mutación (eliminar, renombrar o cambiar el tipo de una columna, eliminar un índice, un TTL) y con 3 si solo mueve el tiempo de sus metadatos (un índice, un ajuste, el valor por defecto o el códec de una columna). Una columna añadida hace fallar la copia (salida 1, sin intercambio), o la ejecución sale con 3 tras la última pasada de verificación. Una reconstrucción no arrastra un `ALTER`: vuelve a expresarlo en la sentencia de destino y ejecuta de nuevo con `--restart`. Además, rechaza una tabla que ninguna migración declara.
+`loom migrate --dry-run --strict` falla mientras una tabla declarada siga teniendo filas en la disposición antigua, de modo que la comprobación previa al despliegue detecta un paso omitido.
+
+El destino conserva las columnas de la tabla (así el intercambio es aditivo), y su clave de ordenación conserva las columnas de la clave antigua, reordenadas: esa clave es también la que usa un `ReplacingMergeTree` para fusionar. Una clave con otras columnas fusiona otras filas y se lista con su motivo en `tests/unit/test_migrations_additive.py`. Nombra la reconstrucción en las notas de la versión como un paso del operador ([proceso de publicación](https://github.com/ClickHouse/loom/blob/main/docs/development/release-process.md#release-notes)).
+
+
+
+## Migraciones de Postgres
+
+Los archivos `schemas/pg_migrations/NNN_*.sql` siguen las mismas reglas: están numerados, son aditivos, nunca se editan una vez fusionados, y cada `CREATE`, `ALTER` o `DROP` de una tabla nombra `loom.`, salvo el nombre nuevo de un renombrado, donde Postgres no admite esquema (`tests/unit/test_storage_layout_rows.py`). Un arranque los aplica bajo un bloqueo consultivo (advisory lock) de Postgres, cada archivo en una transacción junto con su fila del registro. Una migración espera como máximo 5 s a un bloqueo de tabla (`lock_timeout`, y luego reintenta), de modo que un `ALTER` nunca deja en cola todas las consultas de la tabla detrás de una transacción larga. Una compilación sirve con un registro que contiene archivos de una compilación posterior, con una advertencia que los nombra; un archivo del registro que no incluye, numerado igual o por debajo de su propio último archivo, o uno cuyo checksum cambió, rechaza el arranque.
+
+Cada archivo se ejecuta en una transacción, por lo que una migración no crea índices en una tabla grande: la creación bloquearía las escrituras de la tabla, y cada commit respondería 503, hasta que termine. Un índice así necesita `CREATE INDEX CONCURRENTLY` fuera de una transacción, y un arranque que espera el bloqueo consultivo entra en interbloqueo con él (una sesión en espera mantiene un snapshot que la creación debe esperar a que termine): un cambio que añade un archivo de ese tipo también toma el bloqueo reintentando `pg_try_advisory_lock`. Cuando la primera versión que escribe en una tabla incluye el archivo, la tabla es pequeña dondequiera que se ejecute el archivo, y su índice puede crearse en la transacción del archivo (`010_revision_delivered_at.sql`).
+
+
+
+## Volcado y verificación del esquema
+
+`schemas/schema.sql` es el resultado volcado de aplicar todas las migraciones: léelo para
+entender la forma actual, nunca lo edites a mano. Después de cambiar una migración, regénéralo
+contra un ClickHouse nuevo de la versión que prueba CI (`clickhouse/clickhouse-server:latest`):
+
+```bash
+bash dev/ci_start_clickhouse.sh # that image with Loom's server config
+make migrate
+make schema-dump # rewrites schemas/schema.sql only when the dump differs
+make schema-check # exit 1 with the head of the diff; writes nothing
+```
+
+Si el volcado falla, el archivo queda como estaba. Otra versión de ClickHouse, un servidor donde el
+códec `Quantized` o su cadena `LZ4` no se pueden activar, o una base de datos que contiene gemelas de reconstrucción producen un volcado
+distinto, y por eso importa el contenedor fijado. Las tablas internas (`_migrations`, nombres que empiezan por `_` o `.`)
+se excluyen. El job `schema-check` de CI reproduce todas las migraciones en un servidor nuevo, ejecuta
+la prueba en seco estricta y después `make schema-check`.
+
+CI sigue `latest`, así que una nueva versión de ClickHouse que imprima el DDL de otra forma pone
+`schema-check` en rojo sin ningún cambio en Loom. Lee la diferencia que imprime el job: cuando solo es
+de formato, ejecuta los cuatro comandos anteriores (descargan la nueva versión) y confirma
+`schemas/schema.sql` por separado. Un cambio de significado (un tipo, un valor por defecto, un ajuste
+del motor) es un cambio de comportamiento de ClickHouse que conviene investigar antes de volcar encima;
+`LOOM_CLICKHOUSE_IMAGE=clickhouse/clickhouse-server:A.B.C.D` ejecuta los comandos anteriores sobre la
+última versión que se volcó sin diferencias, para comparar.
+
+
+
+## Lista de verificación
+
+1. Toma el siguiente número libre; escribe el archivo de forma aditiva.
+2. Actualiza los constructores de filas, `loom.memory_versions`, el censo de borrado y los casos del analizador si el cambio los afecta.
+3. Ejecuta `make migrate` contra un ClickHouse local, luego `make schema-dump` y confirma `schemas/schema.sql` junto con la migración.
+4. Ejecuta `make test-unit` (las pruebas de aditividad, numeración y clasificación del esquema) y la suite de integración para las rutas que leen la nueva forma.
+5. Anota cualquier paso del operador (una reconstrucción, un backfill) para las notas de la versión.
+
+
+
+## Relacionado
+
+- [Actualizaciones](https://github.com/ClickHouse/loom/blob/main/docs/operations/upgrades.md): cómo el runner aplica los archivos en un despliegue
+- [ClickHouse](../architecture/clickhouse.md)
+- [Referencia del esquema](https://github.com/ClickHouse/loom/blob/main/docs/reference/schema.md)
diff --git a/i18n/.pending/es/docs/features/memory/retention-and-erasure.md b/i18n/.pending/es/docs/features/memory/retention-and-erasure.md
new file mode 100644
index 0000000000..710b294d5e
--- /dev/null
+++ b/i18n/.pending/es/docs/features/memory/retention-and-erasure.md
@@ -0,0 +1,292 @@
+
+> Esta página es una traducción automática de la [página en inglés](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/retention-and-erasure.md), que prevalece.
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/retention-and-erasure.md), which is authoritative.
+
+
+
+# Retención y borrado
+
+Loom no elimina ninguna memoria a menos que lo solicite quien la escribió, el propietario del espacio de nombres o el operador. La memoria no tiene una vida útil por defecto. Los datos salen de tres maneras: una expiración o eliminación hecha por quien escribe, una retención que configuró un propietario u operador, y un borrado que elimina un ámbito en todos los lugares donde Loom lo guarda.
+
+
+
+## Qué se conserva y por cuánto tiempo
+
+Ninguna tabla de memoria, embeddings, historial de versiones, conversaciones, entidades, resúmenes, memoria de trabajo o conocimiento tiene un TTL en `schemas/schema.sql`, y ningún worker retira filas por antigüedad.
+Las tablas de enlaces `entity_triple_rows` y `entity_edge_rows` siguen a `entity_triples` y
+`entity_edges`: sin TTL. Una eliminación definitiva (erasure) borra los enlaces de las memorias que elimina, y
+`loom erasure-re-verify --completed-since … --resume` borra los enlaces huérfanos que dejó la eliminación de una compilación anterior.
+Una fila sale del conjunto servido solo cuando:
+
+- **la elimina quien la escribió**: `memory.delete`, una reescritura con la misma clave que la sustituye,
+ `memory.apply`, `memory.clear`, `conflicts.resolve`, `blacklist.add(sweep=true)`;
+- **quien la escribió definió una caducidad**: `ttl_seconds` o `valid_to` en `memory.set`,
+ `memory.touch`, `run.complete(retain="expire")`, el `expires_in_days` de una reflexión;
+- **el propietario o el operador configuró una**: consulta la [retención configurada](#configured-retention).
+
+Las tablas operativas (telemetría, cachés, colas) tienen TTL fijos: `loom.search_trace_log`
+y `loom.memory_exposures` 180 días; `loom.erasure_requests` y
+`loom.policy_decisions` 90 días; `loom.memory_drops`, `loom.memory_extraction_queue`,
+`loom.events` y `loom.embedding_cache` 30 días; `loom.llm_response_cache` 7 días. La
+[referencia del esquema](https://github.com/ClickHouse/loom/blob/main/docs/reference/schema.md) lista el TTL de cada tabla.
+
+Un worker elimina datos según un temporizador: `namespace_gc` purga los espacios de nombres de
+`kind = 'bench'` (identificados por `LOOM_NAMESPACE_BENCH_PREFIXES` en el registro automático) sin
+escrituras durante `LOOM_NAMESPACE_GC_IDLE_HOURS`, mediante una saga de eliminación definitiva. Nunca toca
+otros tipos. Consulta [espacios de nombres y uso compartido](https://github.com/ClickHouse/loom/blob/main/docs/features/namespaces-and-sharing.md).
+
+
+
+### Borrar no es eliminar definitivamente
+
+Una lápida (tombstone) es una nueva versión con `tombstoned_at` definido. Las lecturas dejan de servirla de inmediato, pero
+la fila y sus versiones anteriores en `loom.memory_versions` siguen en disco:
+
+- `memory.restore` revive una clave con lápida dentro de 14 días (después responde
+ `expired=true`). También revierte una sustitución automática.
+- `memory.clear` (admin) pone una lápida a todas las memorias de un agente o usuario en un espacio de nombres;
+ `confirm_subject` debe repetir el `user_id` o `agent` concreto (ni `'*'` ni `'-'`
+ confirman). `agent="*"` con un `user_id` borra las filas de ese usuario bajo cualquier agente, y
+ `user_id="*"` con un `agent` borra las filas de ese agente para todos los usuarios. Se rechaza un alcance que no nombre a nadie
+ salvo `'-'`, igual que un borrado de todo el espacio de nombres. Las filas bloqueadas permanecen y se cuentan en
+ `locked_skipped`. Las claves borradas se reviven del mismo modo.
+
+Para eliminar los bytes, usa una [eliminación definitiva](#erasure). Para quitar un valor pero conservar la fila y el
+rastro de auditoría, usa [`memory.redact`](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/history-and-provenance.md#scrubbing-history-memoryredact).
+
+
+
+### Caducidad definida por el escritor
+
+Una fila se oculta de las lecturas en el momento en que pasa su `expires_at`. Después, el worker
+`memory_expiry_sweep` aplica el `on_expire` del escritor como una nueva versión:
+
+| `on_expire` | Efecto |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `tombstone` (predeterminado) | Se le pone lápida, con la ventana de restauración de 14 días. |
+| `demote` | Se borra la caducidad; confianza × `LOOM_MEMORY_EXPIRY_DEMOTE_FACTOR` (0.5), nunca por debajo de `LOOM_MEMORY_EXPIRY_DEMOTE_FLOOR` (0.05). |
+| `anonymize` | El valor se reemplaza por un marcador y se descartan los embeddings; la fila permanece como prueba de que existió. |
+
+`memory.touch` cambia solo la caducidad de una fila, para una clave o hasta 1,000 (`memory_keys`): un
+nuevo `ttl_seconds`, `clear_expiry=true` o un nuevo `on_expire`. `memory.sweep_expired`
+(admin) ejecuta un barrido para un espacio de nombres bajo demanda, con `dry_run`. Una edición de otros campos
+mantiene una caducidad vigente.
+
+
+
+### Retención configurada
+
+Todo está desactivado de forma predeterminada (0 = conservar siempre).
+
+| Dónde | Se define con | Efecto |
+| ---------------------------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Un tipo de memoria en un espacio de nombres | `retention_days` en una entrada `tag_registry` de `namespace.register` | Una fila que `memory.set` escribe sin caducidad vigente, `ttl_seconds` ni `clear_expiry` recibe `expires_at = now + N days`; una fila `read_only` reafirmada no recibe ninguna. |
+| Filas sensibles | `LOOM_MEMORY_SENSITIVE_RETENTION_DAYS`, `LOOM_MEMORY_SENSITIVE_ON_EXPIRE` (predeterminado `anonymize`) | Las filas nuevas de sensibilidad `medium` / `high` reciben una caducidad; prevalece una caducidad más corta del llamante. |
+| Las escrituras de una ejecución | `LOOM_MEMORY_RUN_COMPLETE_RETAIN` (`keep`, `demote`, `expire`), `LOOM_MEMORY_RUN_COMPLETE_EXPIRE_DAYS` (7) | Lo que `run.complete` hace con las filas de la ejecución cuando la llamada no lo indica. Las filas fijadas, verificadas, promovidas, bloqueadas, episódicas y de reflexión siempre se conservan. |
+| Un espacio de nombres completo | `retention_days`, `warm_days` en `namespace.register` | Un TTL de tabla (y traslado al nivel cálido) para las filas de ese espacio de nombres. |
+| El despliegue | `LOOM_RETENTION__DAYS`, `LOOM_TIERING__WARM_DAYS` | Un TTL de tabla (y traslado al nivel cálido) en `audit_log`, `agent_events`, `memory`, `memory_embeddings`, `conversations`, `chunks`, `documents`. |
+
+Bajo la autoridad de Postgres, ninguna de las dos últimas filas pone un TTL de retención en
+`memory`, `memory_embeddings` ni `documents`: eliminaría la copia en ClickHouse de filas que
+Postgres aún sirve, por lo que el arranque rechaza `LOOM_RETENTION_MEMORY_DAYS`,
+`LOOM_RETENTION_MEMORY_EMBEDDINGS_DAYS` y `LOOM_RETENTION_DOCUMENTS_DAYS`
+([autoridad de almacenamiento](../../architecture/storage-authority.md)). El
+`retention_days` de un espacio de nombres tampoco afecta a `chunks`, de modo que un documento que permanece conserva los fragmentos con los que la búsqueda lo encuentra; `LOOM_RETENTION_CHUNKS_DAYS` sigue aplicándose.
+
+El worker `retention_reconcile` aplica las dos últimas filas como un `ALTER TABLE … MODIFY TTL` idempotente por tabla, por `(org, namespace)` cuando existen sobrescrituras, y
+elimina el TTL de una tabla cuando ya no queda ningún espacio de nombres ni ventana de despliegue sobre ella. En
+`loom.memory` el TTL se basa en `coalesce(expires_at, created_at)`, de modo que la caducidad del escritor
+prevalece.
+
+- **Un TTL de tabla elimina físicamente** en la siguiente fusión (merge) de la parte. No hay ventana de restauración, y las lápidas caducan junto con las filas que ocultan.
+- **Un Undo se mantiene mientras se mantenga su registro.** El resolutor de conflictos respeta el Undo de una persona
+ sobre una retirada mediante su fila `memory.unsupersede` en `audit_log`. Con un TTL de `audit_log`
+ más corto que la vida de un par, un Undo caducado deja de mantenerse, y el resolutor puede juzgar
+ y retirar ese par de nuevo.
+- **El almacenamiento por niveles necesita un volumen.** `LOOM_TIERING_WARM_VOLUME_NAME` debe nombrar un volumen de la
+ política de almacenamiento, y la antigüedad cálida debe ser menor que la antigüedad de retención.
+
+
+
+## Borrado
+
+`erasure.request` borra un ámbito en todos los lugares donde Loom lo conserva, y responde cuando puede demostrar que no queda nada del ámbito. Para borrar todo lo que un id de usuario tiene en la organización, un administrador de la organización solicita el ámbito `user_id`, que borra las filas del usuario en todos los espacios de nombres de la organización (`purge=true` las elimina en lugar de marcarlas con una lápida; lo que deja se enumera más abajo). `memory.clear` marca con una lápida las memorias de un agente o de un usuario solo en un espacio de nombres ([eliminar no es borrar](#delete-is-not-erase)).
+
+| `scope_type` | `scope_value` | Quién puede solicitarlo |
+| ---------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| `user_id` | El id de usuario, en todos los espacios de nombres de la organización | Un administrador de la organización |
+| `namespace` | Un espacio de nombres | Un administrador de ese espacio de nombres (o de la organización) |
+| `namespace_list` | Un arreglo JSON de 1–500 espacios de nombres, o `{"namespaces": [...], "purge": bool}` | Un administrador de la organización |
+
+La op se puede invocar con un token de escritor, pero el handler exige permisos de administrador sobre el destino (de lo contrario, 403 `AUTH_INSUFFICIENT`).
+
+Los vínculos de categoría (`loom.memory_categories`) no llevan usuario, así que un borrado de `user_id` los deja, junto con las filas de auditoría de `memory.import` que los enumeran. Para un elemento importado, la clave del vínculo es `import:` más un resumen (digest) de su texto, que permite confirmar un texto adivinado; un borrado de `namespace` elimina los vínculos.
+
+Un borrado de `user_id` elimina los chunks literales marcados con el usuario y los chunks sin usuario (`-`) bajo alguno de los pares `(namespace, key)` del usuario, sea de quien sea la memoria a la que pertenezcan: un chunk `-` puede contener texto del usuario, y la ruta de escritura también los retira como del escritor. Los chunks marcados con otro usuario permanecen.
+
+Un borrado de `user_id` también retira los resúmenes consolidados construidos a partir de las memorias del usuario, con la identidad que los haya escrito ([cuáles](../../architecture/memory-architecture.md#background-passes)), junto con lo derivado de ellos: su historial de versiones, sus chunks literales y vectores de entidades, las filas del grafo extraídas de ellos y las copias a nivel de espacio de nombres promovidas a partir de ellos. También elimina las respuestas de `memory.ask` en caché y los precedentes que los citaban.
+
+
+
+### La saga
+
+```mermaid
+flowchart TD
+ R["erasure.request"] --> L["ledger row in loom.erasure_requests (in_progress)"]
+ L --> S["Loom steps: memory, embeddings, versions, chunks, evidence, summaries, graph, conversations, blobs, briefs, runs, tasks, ..."]
+ S --> X["external backends: Langfuse, ClickStack"]
+ X --> V["verify.residue census"]
+ V -->|no live rows| C["completed (residue_count 0, verified_at)"]
+ V -->|rows left| F["failed (residue per table)"]
+ S -->|step error| F
+ X -->|backend cannot confirm| F
+ F --> W["erasure_recovery worker resumes from steps_completed"]
+ W --> S
+ W -->|5 attempts| A["failed + erasure.abandoned audit row"]
+```
+
+- **Pasos con puntos de control e idempotentes.** Cada paso terminado se registra en `steps_completed`. El worker `erasure_recovery` reanuda desde su punto de control una saga que quedó en `in_progress` o `failed`. Un paso espera hasta `LOOM_ERASURE_MUTATION_WAIT_S` a su mutación y, si no termina, falla nombrándola.
+- **Las fuentes de documentos se detienen antes de que se vayan los documentos.** Un borrado de espacio de nombres retira las [fuentes de documentos](https://github.com/ClickHouse/loom/blob/main/docs/features/knowledge.md#document-sources) del espacio de nombres en `knowledge_sources.retire`, su primer paso, y borra sus credenciales; luego espera a que termine el turno de sincronización de cada fuente que siga en ejecución (hasta 30 segundos en total; un turno que sigue en ejecución hace fallar el paso con `OVERLOADED`, y `erasure_recovery` reintenta la saga), de modo que ninguna sincronización vuelva a escribir un documento o una decisión extraída después de que los pasos posteriores los borren.
+- **Los vínculos de código esperan al worker de vínculos.** `code_links.delete` toma el lease de cola del worker de vínculos de código, de modo que ninguna pasada publique un cursor que leyó antes del borrado: entre hosts con Keeper, dentro de un mismo proceso sin él. Espera hasta 15 minutos a que termine una pasada; pasado ese tiempo el paso falla con `LeaseBusy` y `erasure_recovery` lo reintenta.
+- **Lápida o purga.** De forma predeterminada, las tablas de borrado lógico (memoria, embeddings, chunks, resúmenes, vínculos) se marcan con una lápida, y `memory.restore` todavía puede revivirlas dentro de la ventana; `erasure.list` informa esas reanimaciones como `reversals_count`. `purge=true` elimina las filas en su lugar (un `DELETE FROM` ligero en las tablas anchas). Un ámbito que contiene un espacio de nombres que alguna vez tuvo un mirror se purga entero, todos los espacios de nombres que contiene, de modo que ninguno tiene esa ventana ([fuentes de documentos](https://github.com/ClickHouse/loom/blob/main/docs/architecture/document-sources.md#the-mirror)). Un borrado de usuario encuentra lo que las memorias del usuario alimentaron a través de sus claves, así que en una purga sus filas de `loom.memory` y los resúmenes consolidados construidos a partir de ellas se marcan primero con una lápida y se eliminan en `memory.retire`, después de todos los pasos que leen esas claves; hasta entonces `memory.restore` puede revivirlos (las filas propias del usuario cuentan como una reversión, los resúmenes no), y `memory.retire` elimina lo que `memory.restore` revivió.
+- **Originales subidos** de documentos de conocimiento: primero se eliminan las filas del espacio de nombres en `loom.document_blobs` y se registra `blob_erased_at`. Un borrado de usuario elimina los originales que ese usuario subió y que no comparte ningún documento activo de otro escritor, encontrados a través de `loom.blob_uploads` (una fila por subida de cada usuario final, ya que la versión del documento que nombraba un original pudo haber sido reemplazada y fusionada) y a través de sus documentos; después se van sus filas de `loom.blob_uploads`. El censo cuenta ambas tablas. Los originales guardados en un bucket compatible con S3 (`LOOM_DOCUMENT_OBJECT_STORE=s3`) se eliminan antes que sus filas: un borrado de espacio de nombres elimina todos los objetos del ámbito bajo su prefijo y el censo cuenta lo que queda allí (`objects.document_originals`); un borrado de usuario elimina todos los objetos que contienen bytes de los originales propios del usuario, los nombre una fila o no, vuelve a listar sus prefijos y hace fallar el paso si el almacén conservó alguno, luego elimina las filas y después elimina lo que esos prefijos aún contienen y ninguna fila nombra, de modo que la propia subida del usuario de esos bytes, cuya fila se llevó el borrado, también pierde su objeto. Una subida de esos bytes que siga en curso cuando se ejecuta el paso, de cualquier escritor (su objeto almacenado, su fila aún no insertada), pierde su objeto, y su fila, una vez insertada, responde `410 BLOB_GONE`. Cada lote de originales se vuelve a leer justo antes de eliminarse, así que un original que el documento de otro escritor haya nombrado desde entonces permanece; otro escritor que almacene los mismos bytes en el mismo espacio de nombres después de esa lectura puede perderlos, igual que en el almacén de ClickHouse. Una fila que nombra un objeto mientras no hay bucket configurado, o uno fuera del bucket y prefijo configurados, hace fallar el paso en lugar de dejar los bytes. En cualquiera de los dos almacenes, un borrado de usuario elimina las filas en el menor número de mutaciones en que caben sus originales (cada una enlaza tantos como un parámetro de ClickHouse puede llevar). Mover originales de ClickHouse al bucket (`loom knowledge migrate-originals`) está protegido por este ledger: no mueve un original que cubra un borrado sin terminar, y un movimiento que un borrado alcanza termina como ese borrado decida ([dónde se almacenan los originales](https://github.com/ClickHouse/loom/blob/main/docs/features/knowledge.md#where-originals-are-stored)).
+- **Las cancelaciones de ingesta.** Un borrado de usuario elimina las filas de ingesta del usuario, entre ellas las cancelaciones. Una cancelación que el usuario pidió sobre el trabajo de otro escritor que sigue pendiente o en procesamiento se conserva primero como una fila sin identidad (`agent`, `user_id` y `session_id` en `'-'`, `actor` vacío), de modo que ese trabajo siga cancelado.
+- **Cachés de toda la organización.** `loom.idempotency` (respuestas reproducidas) y `loom.embedding_cache` (vectores de consultas, nunca su texto) llevan la organización pero no un espacio de nombres ni un usuario final, así que un borrado en cualquiera de los dos ámbitos elimina todas las filas de la organización en ambas tablas. El costo son fallos de caché. El censo cuenta `loom.idempotency` en toda la organización pero no `loom.embedding_cache`, que cualquier búsqueda de la organización vuelve a llenar; la caché de vectores en el proceso de cada réplica expira dentro de `LOOM_EMBEDDING_CACHE_TTL_S`.
+- **Aprendizajes de reglas del bot.** Las palabras de un usuario en la cola de aprendizajes viven solo en sus filas de `loom.learnings_supporters`, que un borrado de usuario elimina. Un candidato a regla que se queda sin ningún respaldo se elimina entonces si está pendiente, o conserva su decisión con la regla en blanco ([extracción](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/extraction.md#rules-the-assistant-states-about-itself)). El censo cuenta esos candidatos sin respaldo en toda la organización, no solo los del usuario borrado, por lo que una saga puede fallar por un candidato que otro borrado de la organización dejó a medio paso; su paso reabierto lo limpia.
+
+
+
+### La cascada federada
+
+Los datos que Loom envió a otros sistemas se borran en la misma saga. Los pasos externos fallan en modo cerrado: un backend que no puede confirmar el borrado (5xx, timeout, caída de red, una respuesta de salud de Langfuse sin versión) hace fallar el paso, y el worker reintenta. "Nada que borrar" (cero filas coincidentes, o una tabla de ClickStack que el servicio no tiene) cuenta como éxito.
+
+| Backend | Configurado por | Borra |
+| ---------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| Langfuse | `LOOM_LANGFUSE_URL` + `LOOM_LANGFUSE_ADMIN_TOKEN` | Trazas encontradas por `userId` dentro de la etiqueta de la organización, o por el par de etiquetas `org:` + `namespace:`. |
+| ClickStack | `LOOM_CLICKSTACK_DATABASE`, `LOOM_CLICKSTACK_USER_ID_KEYS` | Filas OTel en el mismo servicio de ClickHouse, que coinciden con las claves de atributo del id de usuario o con el espacio de nombres. |
+
+Un borrado de espacio de nombres en ClickStack solo coincide con una fila `loom.namespace` cuando lleva el `loom.org` de la organización que borra, de modo que las métricas propias de Loom de ops y de dominio, que no llevan organización, conservan la etiqueta del espacio de nombres ([borrado en ClickStack](https://github.com/ClickHouse/loom/blob/main/docs/features/integrations/clickstack.md#erasure)).
+
+Un backend sin configurar registra la intención y no borra nada. Solo un borrado de `namespace_list` puede pasar `external=false`; los borrados de `user_id` y `namespace` siempre incluyen los backends. `LOOM_EXTERNAL_ERASURE_TIMEOUT_S` limita cada llamada. Configuración: [Langfuse](https://github.com/ClickHouse/loom/blob/main/docs/features/integrations/langfuse.md) y [ClickStack](https://github.com/ClickHouse/loom/blob/main/docs/features/integrations/clickstack.md).
+
+
+
+### El censo de residuos
+
+El último paso, `verify.residue`, cuenta las filas activas del ámbito en todas las tablas que tocan las rutas de lectura. Cualquier fila restante hace fallar la saga; la fila terminal lleva `residue_count`, `residue` (por tabla), `verified_at` y `census` (todos los conteos, más abajo). Una saga reanudada vuelve a ejecutar el paso que es dueño de cualquier tabla en la que el último censo encontró filas, aunque su punto de control diga que terminó, y siempre vuelve a contar.
+
+
+
+### El comprobante
+
+`erasure.status` (y la respuesta de `erasure.request`) lleva el comprobante del censo de la última ejecución. `census` es null cuando la última fila del ledger no contiene un censo que haya contado todos los almacenes: una ejecución en curso, un censo que no pudo ejecutarse o dejó un almacén sin contar, o una fila escrita por una compilación que no guarda censo. Los campos del comprobante:
+
+- `census`: cada sustrato que el censo contó y su conteo, incluidos los ceros. Las claves son nombres de tabla, `pg:` para la autoridad de Postgres, `objects.document_originals` para el bucket de documentos en un ámbito de espacio de nombres, y `provider_rebuild_copies` sumado sobre las copias de una reconstrucción de proveedor, 0 cuando no existe ninguna (contado en todo el despliegue cuando una copia no tiene columna de organización). Un conteo son las filas que el censo cuenta como residuo en este ámbito: filas activas, o todas las filas cuando la saga purga o la tabla no conserva lápidas ([las reglas del censo](../../architecture/memory-architecture.md#erasure-saga)). `objects.document_originals` cuenta una primera página de listado, así que se lee como "al menos".
+- `purge`: el modo de eliminar o marcar con lápida del ámbito (el de un solo espacio de nombres es lápida, se haya pedido lo que se haya pedido); un ámbito que contiene un mirror ([fuentes de documentos](https://github.com/ClickHouse/loom/blob/main/docs/architecture/document-sources.md#the-mirror)) se elimina digan lo que digan estos valores. Sin purga, una fila con lápida conserva sus bytes en su parte hasta que la tabla se fusiona; con purga las filas se eliminan, y sus bytes permanecen en disco hasta que una fusión o el worker de recuperación de espacio los elimina.
+- El sujeto y el momento son `org`, `scope_type`, `scope_value` y `verified_at` del estado.
+
+El comprobante es el conteo de Loom. Conserve la respuesta: `erasure.status` sirve la fila del ledger durante 89 días después de la solicitud, y la fila de auditoría `erasure.completed`, que también lleva el censo, se escribe después de la fila completada, en la medida de lo posible, y se conserva durante `LOOM_RETENTION_AUDIT_LOG_DAYS`. Cuando quien lo solicitó no recibió respuesta (una saga que terminó el worker de recuperación, una ejecutada en segundo plano, una llamada que agotó el tiempo), lea `erasure.status` dentro de los 89 días.
+
+
+
+#### Verificar usted mismo un borrado
+
+Un operador que tenga la concesión de la superficie SQL de la organización con `--namespaces '*'`, o `--all` ([superficie SQL](https://github.com/ClickHouse/loom/blob/main/docs/reference/sql-surface.md#access)), puede volver a contar tres de las claves del censo, `loom.memory`, `loom.memory_versions` y `loom.conversations`, y revisar el ledger de solicitudes (la cuarta sentencia, más abajo). Enlace el id borrado y el momento del censo como parámetros. ClickHouse igualmente escribe los valores enlazados en `system.query_log`, como hace con las sentencias del propio borrado (más abajo), así que ejecute la verificación desde `clickhouse-client` en lugar de hacerlo a través de `pg_clickhouse`, cuyo texto delegado un registro de sentencias de Postgres conservaría como una copia más:
+
+```bash
+read -r uid # the erased id, typed at the prompt so it stays out of the shell history
+clickhouse-client --param_org='' --param_uid="$uid" --param_at='' \
+ --multiquery --query "
+SELECT count() FROM loom.sql_v1_memories WHERE org = {org:String}
+ AND user_id = {uid:String} AND created_at <= {at:DateTime64(6, 'UTC')};
+SELECT count() FROM loom.sql_v1_memory_history WHERE org = {org:String}
+ AND user_id = {uid:String} AND created_at <= {at:DateTime64(6, 'UTC')};
+SELECT count() FROM loom.sql_v1_conversations WHERE org = {org:String}
+ AND user_id = {uid:String} AND ts <= {at:DateTime64(6, 'UTC')};
+SELECT count() FROM loom.sql_v1_agent_events WHERE org = {org:String}
+ AND user_id = {uid:String} AND ts <= {at:DateTime64(6, 'UTC')};"
+```
+
+El filtro `org` limita al org de la eliminación una concesión que cubre más de un org (`--all`).
+Cada sentencia sigue leyendo todo el alcance de la concesión antes de filtrar ([qué cuesta una lectura](https://github.com/ClickHouse/loom/blob/main/docs/reference/sql-surface.md#what-a-read-costs)), de modo que en un org grande o con una concesión `--all` una sentencia puede detenerse en los límites del usuario SQL (`LOOM_CH_ANALYSIS_MAX_ROWS_TO_READ`, `_MAX_EXECUTION_S`) con un error en lugar de un recuento; súbelos para la comprobación. Para un alcance de espacio de nombres, pasa `--param_ns=''` y filtra las tres primeras por `namespace =
+{ns:String}` en lugar de `user_id`; para un `namespace_list`, ejecútalo una vez por cada nombre en los `namespaces` de su `scope_value`; la sentencia `sql_v1_agent_events` es solo para un alcance de usuario, ya que una eliminación de espacio de nombres conserva las filas del registro de solicitudes del espacio de nombres. Cada recuento es 0 después de una eliminación completada, con estas diferencias respecto al censo: las vistas excluyen los espacios de nombres restringidos, `sql_v1_memories` excluye las filas rechazadas y con tombstone, y `sql_v1_memory_history` excluye las versiones rechazadas (conserva las que tienen tombstone), y un resumen consolidado a partir de las memorias del usuario lleva otro `user_id`, que el censo cuenta y estas consultas no. El recuento del registro de solicitudes es una comprobación aparte, fuera del recibo: una eliminación depura las filas del registro de solicitudes de un usuario a `` en lugar de borrarlas, y la vista del registro de solicitudes contiene solo su ventana ([`sql_v1_agent_events`](https://github.com/ClickHouse/loom/blob/main/docs/reference/sql-surface.md#sql_v1_agent_events)), así que confirma la depuración solo para las filas dentro de ella. Cualquier otra clave del censo es solo el recuento de Loom.
+
+Lo que el recibo no cubre:
+
+- copias de seguridad, recuperación a un punto en el tiempo, WAL y standbys de cualquiera de los dos servicios;
+- copias hechas fuera de Loom, como una tabla creada en el Postgres propio de un org a partir de la [superficie SQL](https://github.com/ClickHouse/loom/blob/main/docs/reference/sql-surface.md);
+- filas que un worker escribe después del censo a partir de una lectura que hizo antes ([autoridad de almacenamiento](../../architecture/storage-authority.md#erasure));
+- un `namespace.restore` desde una instantánea tomada antes de la eliminación, que recupera filas: ejecuta la eliminación de nuevo, y su censo es el nuevo recibo;
+- para un alcance de usuario, los originales de documentos en el bucket, que el censo cuenta solo para un alcance de espacio de nombres.
+
+El id eliminado permanece donde la prueba de eliminación lo necesita: en la fila del registro (hasta que el TTL de la tabla la descarta, 90 días después de la solicitud), en la auditoría, en `loom.erasure_reversals` y en los logs propios del despliegue de las sentencias que lo nombraron (el log de mutaciones de ClickHouse, `system.query_log` y `system.text_log` para una sentencia que lo escribió, y los logs de sentencias de Postgres con `log_statement` o `log_min_duration_statement` activados).
+
+
+
+### Sagas abandonadas
+
+Tras 5 intentos el worker marca la solicitud como `failed` de forma definitiva y escribe una fila de auditoría `erasure.abandoned`, con `failure_reason` y `steps_completed`. Entonces una persona debe escalar el caso. `loom erasure-re-verify` vuelve a comprobar las sagas terminales; `--resume` vuelve a ejecutar las fallidas desde su punto de control (`--skip-external` para una saga `namespace_list` cuyo paso externo sigue fallando). `--completed-since ` vuelve a comprobar las sagas completadas verificadas desde entonces en lugar de las fallidas, para las eliminaciones que ejecutó una versión anterior durante una actualización; con `--resume` borra solo los vínculos de filas huérfanas ([mantenimiento](https://github.com/ClickHouse/loom/blob/main/docs/operations/maintenance.md#erasure)). Consulta la [resolución de problemas](https://github.com/ClickHouse/loom/blob/main/docs/operations/troubleshooting.md).
+
+
+
+### Operaciones
+
+| Op | Rol | Qué hace |
+| ----------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `erasure.request` | writer (admin sobre el destino) | Ejecuta la saga para un alcance. `urgency` `normal` o `urgent`; `purge`; `external`. |
+| `erasure.status` | viewer | El estado de una solicitud, el paso actual, el motivo del fallo y el censo. La eliminación de un usuario solo la responde un admin del org o un admin de plataforma de su org. No figura en los toolsets de MCP. |
+| `erasure.list` | viewer | Solicitudes recientes (filtra por `status`), con `steps_completed_count`, `reversals_count`, `residue_count`. |
+| `erasure.export` | admin | Los datos de un sujeto como JSON: `memory`, `knowledge`, `conversations` (turnos de transcripción y mensajes guardados), `conversation_threads`, `agent_events`, `audit_log`, cada uno limitado por `section_limit` (por defecto 10,000; `truncated` si se supera), y `conversations` también por `LOOM_ERASURE_EXPORT_CONVERSATION_MAX_BYTES` de texto. Incluye por defecto las filas con tombstone. |
+
+`erasure.status` y `erasure.list` leen una fila del registro durante 89 días; el TTL de la tabla la descarta a los 90. Listas de campos: [referencia de operaciones](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md#erasure).
+
+
+
+### Ejemplo
+
+```python
+from loom import Agent
+
+async with Agent(org="acme", namespace="support", agent="privacy-desk") as admin:
+ out = await admin.erasure.request_user_id("u-42", requester="dpo@acme.example")
+ print(out["status"], out["residue_count"], out["verified_at"])
+ if out["status"] != "completed":
+ print(out["failure_reason"], out["residue"])
+```
+
+El `request` del SDK no expone `purge` ni `external`; envíalos por HTTP:
+
+```bash
+curl -sX POST "$LOOM_BASE_URL/v1/erasure.request" \
+ -H "Authorization: Bearer $LOOM_API_KEY" -H "Content-Type: application/json" \
+ -d '{"org":"acme","scope_type":"namespace_list",
+ "scope_value":"[\"bench-a\",\"bench-b\"]",
+ "requester":"ops@acme.example","purge":true,"external":false}'
+```
+
+
+
+### Para colaboradores
+
+Una tabla nueva que pueda contener contenido de memoria necesita un paso de la saga y una entrada del censo (un `Substrate(...)` en `server/erasure/store/census.py` `_CENSUS`), o una línea en `STEP_ONLY_TABLES` con su motivo; si no, falla una prueba unitaria. La saga es `server/erasure/app/saga.py` (`run_saga`), los backends `server/erasure/app/backends.py`, el worker `server/erasure/workers/recovery.py`.
+
+
+
+## Límites
+
+- **No es una garantía de cumplimiento normativo.** La saga, el censo y los hashes de auditoría son primitivas de ingeniería; que cumplan o no una obligación es decisión tuya.
+- **Un borrado es lento.** Cada paso espera a una mutación; calcula varios minutos en un ámbito grande. El SDK espera hasta 120 segundos la primera respuesta; después de eso, consulta periódicamente `erasure.status`.
+- **No existe el ámbito `org`.** Borra los espacios de nombres de una organización con `namespace_list`.
+- **No se puede restaurar desde los TTL de tabla.** Usa la expiración definida por el escritor con `on_expire` cuando el fin de vida deba ser reversible.
+- **Las copias de seguridad quedan fuera de la saga**; consulta
+ [copia de seguridad y recuperación](https://github.com/ClickHouse/loom/blob/main/docs/operations/backup-and-recovery.md).
+- **El bucket de exportación de analítica queda fuera de la saga.** Sus archivos contienen nombres hasheados de organización, espacio de nombres y agente, y recuentos de uso, nunca contenido de la memoria; consulta
+ [nombres hasheados](https://github.com/ClickHouse/loom/blob/main/docs/operations/analytics-export.md#hashed-names).
+
+
+
+## Relacionado
+
+- [Historial y procedencia](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/history-and-provenance.md): `memory.history`, `memory.redact`.
+- [Escritura de memoria](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/writing.md): `ttl_seconds`, `valid_to`, `on_expire` en una escritura.
+- [Ejecuciones](https://github.com/ClickHouse/loom/blob/main/docs/features/runs.md): `retain` en `run.complete`.
diff --git a/i18n/.pending/es/docs/operations/postgres.md b/i18n/.pending/es/docs/operations/postgres.md
new file mode 100644
index 0000000000..52fcb9b963
--- /dev/null
+++ b/i18n/.pending/es/docs/operations/postgres.md
@@ -0,0 +1,246 @@
+
+> Esta página es una traducción automática de la [página en inglés](https://github.com/ClickHouse/loom/blob/main/docs/operations/postgres.md), que prevalece.
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/operations/postgres.md), which is authoritative.
+
+
+
+# Autoridad de memoria en Postgres
+
+Esta guía configura un despliegue de Loom cuyas memorias activas y cabeceras de documentos de conocimiento se almacenan en Postgres, ya sea en ClickHouse Managed Postgres o en un Postgres autoalojado, y explica qué comprobar antes de ponerlo en servicio. El funcionamiento interno se describe en [autoridad de almacenamiento](../architecture/storage-authority.md).
+
+La autoridad se elige una sola vez, en el primer arranque de un despliegue. Un ClickHouse que ya contiene memorias conserva la autoridad de ClickHouse; inicie un despliegue con Postgres sobre un ClickHouse vacío.
+
+
+
+## Requisitos
+
+- Postgres 16 o superior. No se necesita ninguna extensión.
+- Una base de datos y un rol que sea su propietario (Loom crea en ella el esquema `loom`).
+- El rol puede ejecutar `pg_logical_emit_message` (por defecto el público puede; de lo contrario, el arranque se rechaza y nombra el `GRANT`).
+- Para `LOOM_PG_DURABILITY=synchronous` (el valor por defecto): al menos un standby síncrono
+ en otro dominio de fallo, de modo que una escritura confirmada sobreviva a la pérdida del primario.
+- `wal_level = logical` si la base de datos también alimentará una herramienta de replicación; Loom en sí
+ no lo necesita.
+
+
+
+## Configuración
+
+| Ajuste | Valor |
+| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `LOOM_STORAGE_AUTHORITY` | `postgres` |
+| `LOOM_PG_DSN` | `postgres://loom:@:5432/?sslmode=verify-full&sslrootcert=`, el endpoint directo, nunca un pooler de transacciones |
+| `LOOM_PG_POOL_MIN_SIZE`, `LOOM_PG_POOL_MAX_SIZE` | conexiones por proceso de Loom (2 y 20); dimensione `max_connections` para cada proceso de cada réplica |
+| `LOOM_PG_DURABILITY` | `synchronous` (se niega a iniciar sin un standby síncrono) o `local` |
+
+Indique la autoridad de certificación del servidor y exija `sslmode=verify-full`:
+comprueba el certificado y el nombre del host, de modo que nada en la ruta pueda
+hacerse pasar por la autoridad ni leer la memoria o la contraseña. `require` y los
+modos inferiores cifran sin comprobar con quién se habla, y son solo para un servidor
+de desarrollo local.
+
+Loom gestiona su propio pool de conexiones. Apunte `LOOM_PG_DSN` más allá de cualquier
+pooler que entregue al cliente una conexión de servidor distinta por transacción
+(transaction pooling): las migraciones de Loom mantienen un bloqueo advisory de sesión
+y su driver prepara sentencias, y un pooler de ese tipo no conserva ninguna de las dos
+cosas entre transacciones. El `LOOM_PG_DSN` de una [celda](../architecture/cells.md)
+apunta directamente a Postgres, sin ningún pooler de ningún modo: sus procesos marcan
+cada sesión con el parámetro de inicio `loom.tenancy_checked`, que un pooler de sesión
+rechaza o descarta (entonces sus triggers de org rechazan las escrituras del propio
+Loom para una org de la que la celda no tiene ninguna fila, y la protección
+`loom.tenancy` rechaza su fila de tenencia para cada org recién asignada), y
+`loom doctor` señala la sesión que lo perdió. Los scripts y los cargadores masivos
+nunca deben establecer `session_replication_role = replica` en una celda: omite los
+triggers de org y la protección.
+
+Todas las réplicas del despliegue, y su proceso worker, usan los mismos valores. La
+lista completa, con los ajustes de admisión y de entrega, está en la
+[referencia de configuración](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md).
+
+
+
+## Postgres administrado de ClickHouse
+
+1. Crea el servicio con **dos standbys de HA**. Con un solo standby el servicio replica de forma asíncrona, y una escritura confirmada se puede perder junto con el primario.
+2. Crea la base de datos y el rol, concede al rol `pg_read_all_stats` para que Loom pueda ver qué standbys están conectados, y toma la cadena de conexión **directa**, en el puerto 5432, de los detalles de conexión del servicio, no la del pooler: el pooler del servicio funciona en modo de transacción.
+3. Define los [ajustes](#settings) e inicia Loom. Comprueba que `GET /v1/health?include=postgres` informe `postgres.standby` `synchronous`: el arranque rechaza un `synchronous_standby_names` vacío y emite una advertencia cuando hay menos standbys conectados de los que nombra ([qué comprueba el arranque](#what-the-boot-checks)).
+
+La conmutación por error, la ubicación de los standbys y el aislamiento del antiguo primario son responsabilidad del servicio. En Kubernetes, los valores `postgres` del chart definen los [ajustes](#settings) ([ClickHouse Cloud y Postgres administrado](https://github.com/ClickHouse/loom/blob/main/docs/operations/clickhouse-cloud.md)).
+
+
+
+## Postgres autoalojado
+
+Ejecute Postgres bajo un gestor de HA que mantenga un standby síncrono, aísle (fence) al primario anterior en la promoción y promueva solo un standby que contenga todos los commits confirmados.
+Configúrelo en su modo síncrono estricto: se requiere al menos un standby síncrono, y las escrituras se rechazan en lugar de ser confirmadas solo por el primario cuando no hay ninguno conectado. Un gestor que no es estricto vacía `synchronous_standby_names` cuando su standby se desconecta, y entonces el primario confirma los commits por sí solo.
+
+Loom comprueba la configuración del standby al arrancar, y `GET /v1/health?include=postgres` informa `postgres.standby` mientras está en servicio: `synchronous` cuando los standbys que un commit espera (`n` de `FIRST n`, `ANY n` o `n (...)`, y si no, uno) están conectados; `primary_only` cuando no se nombra ninguno, de modo que solo el primario confirma los commits; `waiting` cuando hay menos conectados, de modo que los commits esperan hasta que lo estén; `null` cuando no se pudo leer el estado, porque Postgres no respondió o el rol no puede ver `pg_stat_replication`.
+
+Apunte `LOOM_PG_DSN` al endpoint primario del gestor (el servicio o la dirección que sigue al líder), nunca a un único host, de modo que una promoción mueva a Loom con ella.
+
+Un primario con un standby y sin gestor, como lo inicia `dev/ci_start_postgres.sh` para las pruebas, muestra la configuración:
+
+```text
+synchronous_commit = on
+synchronous_standby_names = 'FIRST 1 (loom_standby)'
+```
+
+
+
+## Qué comprueba el arranque
+
+| Comprobación | Se niega a arrancar cuando |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Conexión | `LOOM_PG_DSN` está vacío o Postgres no responde |
+| Migraciones | se editó un archivo ya aplicado de `schemas/pg_migrations/`, o falta en esta compilación uno anterior al último aplicado |
+| Durabilidad | con `LOOM_PG_DURABILITY=synchronous`, `synchronous_standby_names` está vacío; con cualquier valor, el rol no puede ejecutar `pg_logical_emit_message` |
+| Autoridad | el despliegue registró la autoridad de ClickHouse, este ClickHouse contiene memoria bajo ella, o este Postgres pertenece a otro despliegue |
+| Estado de la celda | falla la primera lectura de las filas de estado de la celda (`loom.cell_first`, `loom.tenancy_mode`, `loom.cell_self`, `loom.tenancy`); con migraciones de Postgres pendientes, el proceso arranca bloqueado y no listo hasta que una lectura se completa ([solución de problemas](https://github.com/ClickHouse/loom/blob/main/docs/operations/troubleshooting.md#a-process-with-loom_cell-unset-is-gated)) |
+
+Una migración espera como máximo 5 s a un bloqueo de tabla y se intenta cinco veces; un
+arranque que registra `Postgres migration waited too long for a lock` cuatro
+veces y después falla con `LockNotAvailableError` encontró una transacción larga que
+retiene la tabla: termínela (`pg_stat_activity` la nombra) y vuelva a arrancar. Un
+arranque que encuentra a otro arranque migrando lo espera, sin límite, y arranca cuando
+sus migraciones terminan.
+
+Cada conexión de Loom establece `synchronous_commit = on` por sí misma, sea cual sea el
+valor por defecto del servidor. El arranque emite una advertencia cuando hay menos
+standbys conectados de los que un commit espera, y cuando su rol no puede ver
+`pg_stat_replication`. Mientras no estén conectados, un commit los espera, hasta
+`LOOM_PG_STATEMENT_TIMEOUT_MS` más un segundo, y luego responde 503
+`POSTGRES_UNAVAILABLE` con `outcome_unknown`: la espera cancelada deja el commit solo en
+el primario. El worker de entrega lo publica en ClickHouse únicamente cuando los standbys
+lo contienen, de modo que una conmutación por error intermedia no deja nada de él en
+ClickHouse
+([autoridad de almacenamiento](../architecture/storage-authority.md#only-durable-revisions-are-published)).
+Un publicador que envía el commit de otra sesión lo vuelve a leer en una transacción que
+confirma un mensaje lógico transaccional con el prefijo `loom.durable`, por lo que un
+consumidor de captura de cambios de la base de datos recibe uno por cada lectura de ese
+tipo; el arranque rechaza un rol que no puede escribir uno.
+
+`GET /v1/health` informa `storage_authority` y, con Postgres, `pg_ok`; con
+`?include=postgres` también un bloque `postgres` con `standby`, `parked_deliveries`,
+`parked_audits`, `parked_knowledge_deliveries` y `backlog` (las entregas pendientes y
+aparcadas de cada fuente, contadas hasta `LOOM_PG_BACKLOG_COUNT_CAP`, `capped` más allá,
+la antigüedad de la más antigua y la de la lectura,
+[SLO del pipeline](https://github.com/ClickHouse/loom/blob/main/docs/operations/monitoring.md#pipeline-slos)), sentencias que la respuesta por defecto omite en una sonda de
+liveness. `pg_ok` es false cuando una consulta en el pool de peticiones no obtuvo
+respuesta en dos segundos, incluida la situación en que todas las conexiones del pool
+están ocupadas. `/v1/health/ready` no espera a Postgres: una réplica que no puede
+alcanzarlo sigue sirviendo los planos que no lo usan. Responde 503
+`POSTGRES_UNAVAILABLE` para las operaciones de memoria, para toda operación de knowledge
+que lee la fila actual de un documento desde su cabeza o la confirma, para la búsqueda y
+las lecturas que comprueban cabezas (`knowledge.search`, `knowledge.outline`,
+`knowledge.synthesize`), y para las operaciones de datasets, que allí leen o confirman el
+catálogo de datasets (`knowledge.dataset_get`, `knowledge.dataset_approve`,
+`knowledge.query`). Las operaciones de knowledge que leen o escriben solo en ClickHouse,
+como `knowledge.list` y `knowledge.dedup_resolve`, siguen sirviendo.
+`knowledge.ingest`, `knowledge.ingest_status` y `knowledge.ingest_cancel` también
+responden 503, ya que cada una lee o confirma su trabajo allí (`loom.knowledge_jobs`); una
+ejecución detenida por una caída cuenta ese intento y se ejecuta de nuevo cuando Postgres
+responde.
+
+`parked_deliveries` cuenta cada entrega de memoria con un arrendamiento sin fin:
+revisiones confirmadas en Postgres que ClickHouse rechazó `LOOM_PG_DELIVERY_MAX_ATTEMPTS`
+veces, las versiones reemplazadas cuyo payload borrado no dejó nada que enviar (abajo), y
+las entregas que `loom reconcile` retiene (`last_error` `held by loom reconcile`) hasta
+que las libera. Una cuyo `targets` no contiene ninguno de 1, 2 y 4 tiene su fila de
+memoria en ClickHouse (también su documento de búsqueda cuando le corresponde), su fila de
+auditoría allí o en `loom.audit_outbox`, y solo debe retiradas: 8, el registro de su
+decisión eliminada, que `decision.chain` sigue sirviendo hasta que se retira; 16, los
+vectores de la versión que reemplazó, que la búsqueda sigue encontrando hasta que se
+retiran (para una fila `high`, su valla oculta mientras tanto los vectores del modelo en
+servicio). Una que agotó sus intentos no se reintenta; su `last_error` en
+`loom.memory_deliveries` contiene el tipo del error y su código de ClickHouse, estado HTTP
+o SQLSTATE de Postgres, nunca su texto, que podría citar la memoria. Esta sentencia
+reintenta una (nunca una retención de reconcile, que `loom reconcile` libera por sí
+mismo):
+
+```sql
+UPDATE loom.memory_deliveries SET attempts = 0, held = false, lease_until = now() WHERE …
+```
+
+Una vez que se ha ejecutado la pasada de [borrado de payloads](../architecture/storage-authority.md#payload-clearing),
+una compilación sin `010_revision_delivered_at.sql` no puede enviar una revisión cuyo
+payload fue borrado: mientras esa compilación sirve, un reintento las excluye, añadiendo
+esto a su `WHERE` (una sonda de clave primaria por entrega):
+
+```sql
+AND NOT EXISTS (SELECT 1 FROM loom.memory_revisions r
+ WHERE r.org = memory_deliveries.org
+ AND r.namespace = memory_deliveries.namespace
+ AND r.seq = memory_deliveries.seq
+ AND r.row IS NULL)
+```
+
+Una publicación que termina el proceso del worker (falta de memoria con un valor enorme)
+cuenta como un intento cuando la siguiente pasada toma su reclamo (`last_error`
+`stopped mid-publish`): al llegar al límite la revisión se aparca o, cuando lo único que
+aún debe es su documento de búsqueda, recibe un stub que el worker de embeddings rellena.
+
+Una publicación que supera el plazo de sentencia de ClickHouse cuenta como fallo propio de
+las filas, ya que ClickHouse aún responde: tras una ralentización que aparcó revisiones
+sanas, la sentencia de reintento anterior con `WHERE attempts >= …` las reintenta todas.
+
+Una aparcada con `last_error` `payload cleared, nothing to send` es una versión cuyo
+payload borró la pasada de [borrado de payloads](../architecture/storage-authority.md#payload-clearing)
+y que una versión posterior de su clave ha reemplazado: ClickHouse sirve la cabeza de la
+clave, y el contenido de esa versión ya no existe (una restauración que omitió el
+[procedimiento operativo](https://github.com/ClickHouse/loom/blob/main/docs/operations/backup-and-recovery.md#the-postgres-journal-and-a-clickhouse-restore)). Su fila de
+auditoría tampoco se envía de nuevo: permanece en el `audit` de la revisión en
+`loom.memory_revisions`. Reintentar la entrega no puede tener éxito; una vez anotada,
+elimine su fila:
+
+```sql
+DELETE FROM loom.memory_deliveries
+WHERE lease_until = 'infinity' AND last_error = 'payload cleared, nothing to send';
+```
+
+El worker de entrega de knowledge publica una entrega a la vez, cada retirada por
+separado: hasta dos inserciones por entrega y `LOOM_PG_DELIVERY_BATCH_ROWS` entregas por
+pasada, dentro de un arrendamiento de `LOOM_PG_DELIVERY_LEASE_SECONDS`, que con un backlog
+suele terminar la pasada antes. Una pasada que el fin del arrendamiento interrumpe libera
+el resto sin contarlo, y la siguiente pasada las toma.
+
+`parked_knowledge_deliveries` cuenta los documentos de knowledge confirmados en Postgres
+cuya fila de `loom.documents` ClickHouse rechazó `LOOM_PG_DELIVERY_MAX_ATTEMPTS` veces: la
+cabeza sirve `knowledge.get` y la búsqueda, que omite los fragmentos de la versión
+anterior que ClickHouse lee como vigentes hasta que se ejecuta la retirada de la entrega
+([búsqueda de knowledge](../architecture/storage-authority.md#knowledge-search)). La
+retirada de un borrado aparcado se ejecuta antes que su fila: `knowledge.get` lo responde
+como borrado, la búsqueda no sirve ninguno de sus fragmentos, y `knowledge.restore`
+responde 503 mientras una publicación de la fuente aún pueda llegar: hasta que la entrega
+aterriza, y durante el límite de inserción después. El barrido de originales conserva el
+original que nombra un documento vigente aparcado, y también lo hace el borrado de un
+usuario distinto de su autor. Su `last_error` en `loom.knowledge_deliveries` contiene el
+tipo y el código del error. Una entrega de un alcance que una compilación anterior borró
+durante una actualización progresiva no se reintenta: ejecute primero ese borrado de nuevo
+([actualizaciones progresivas](../architecture/rolling-upgrades.md)). Esta sentencia
+reintenta una:
+
+```sql
+UPDATE loom.knowledge_deliveries SET attempts = 0, lease_until = now() WHERE …
+```
+
+`parked_audits` cuenta las filas de `loom.audit_outbox` que ClickHouse rechazó el mismo
+número de veces, dejadas allí con su `last_error`: las filas de auditoría de un borrado, y
+las que un reclamo aplazó porque el titular al que reemplazó aún puede insertarlas. Esta
+sentencia reintenta una:
+
+```sql
+UPDATE loom.audit_outbox SET attempts = 0, due_at = now() WHERE …
+```
+
+
+
+## Actualizaciones continuas y rollback
+
+Cada réplica debe ejecutar una compilación que registre la autoridad. Un despliegue de la autoridad de Postgres no puede volver a una compilación que no la incluya: dicha compilación no lee ningún registro y escribe en `loom.memory` directamente ([actualizaciones continuas](../architecture/rolling-upgrades.md)).
+
+
+
+## Copia de seguridad
+
+Haz la copia de seguridad de Postgres con las herramientas del proveedor o del gestor, y la de ClickHouse con las suyas. Una restauración es de un solo almacén, seguida de `loom reconcile`, que vuelve a ejecutar en él lo que el otro almacén registró después del punto de restauración ([restaurar un solo
+almacén](https://github.com/ClickHouse/loom/blob/main/docs/operations/backup-and-recovery.md#restoring-one-store)). Un Postgres de otro despliegue se niega a iniciar.
diff --git a/i18n/.pending/ja/docs/operations/backup-and-recovery.md b/i18n/.pending/ja/docs/operations/backup-and-recovery.md
new file mode 100644
index 0000000000..995881e2d0
--- /dev/null
+++ b/i18n/.pending/ja/docs/operations/backup-and-recovery.md
@@ -0,0 +1,261 @@
+
+> このページは[英語の原文](https://github.com/ClickHouse/loom/blob/main/docs/operations/backup-and-recovery.md)の機械翻訳です。内容は英語の原文が優先されます。
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/operations/backup-and-recovery.md), which is authoritative.
+
+
+
+# バックアップとリカバリ
+
+Loom のバックアップは ClickHouse のバックアップです。カタログのいずれかの行がドキュメントバケット内のオブジェクトを指している間は、そのバケットも対象に含めます。Postgres をオーソリティとして使う場合は、Postgres のバックアップも必要です。
+ClickHouse には、元ドキュメントのカタログ(`loom.document_blobs`。デフォルトのストアではそのバイト列も)、トークンの署名鍵(`loom.signing_keys`)、管理者のランタイムオーバーライド(`loom.runtime_overrides`)が保存されています。次のものは ClickHouse の外にあります。
+
+- `LOOM_JWT_SECRET`:ルートシークレットです。保存された認証情報と署名鍵を暗号化しているため、これなしで復元したバックアップでは、どちらも開けません。env 設定とともに保管してください。
+- `var/code_repos` 配下のコードインデックスの git ミラー:ClickHouse に記録されたリモートのキャッシュです。ミラーのないホストは、再度クローンします。
+- `LOOM_DOCUMENT_S3_BUCKET`:`LOOM_DOCUMENT_OBJECT_STORE=s3` の間に書き込まれた元ドキュメントのバイト列を保持します(設定を戻しても、バイト列はそこに残ります)。各オブジェクトの場所は ClickHouse が保持します。
+
+
+
+## バックアップの選び方
+
+| 方法 | 対象 | 一貫したスナップショット | 用途 |
+| ----------------------------------------------------------------------- | --------------------------------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| ClickHouse Cloud のバックアップ | サービスのすべてのテーブル | あり(サービス単位) | Cloud でのディザスタリカバリ |
+| `BACKUP DATABASE loom TO Disk(...)` / `S3(...)`、または `clickhouse-backup` | すべての `loom.*` テーブル | あり | セルフマネージドの OSS でのディザスタリカバリ |
+| `BACKUP DATABASE loom_telemetry TO ...` | SLI ロールアップ(`loom_telemetry.sli_minute`) | あり | 台帳の再フォールドで復元できる 31 日を超えて SLO 履歴を保持する |
+| `dev/backup_loom.py` ポータブルダンプ | すべての Loom テーブル(下記) | テーブルごと。テーブル間ではなし | デプロイメント、組織、名前空間の移行(元データはバケット内:[下記](#the-portable-dump))、コールドコピー |
+| `namespace.snapshot` | 1 つの名前空間のキュレーション済みメモリ、型、権限付与、監査ログの末尾 | 1 回の呼び出し | API 経由での名前空間のコピーまたは凍結 |
+
+
+
+## ポータブルダンプ
+
+`dev/backup_loom.py` はテーブルごとに 1 つの `JSONEachRow` ファイルを書き出し、続いて `manifest.json` を書き出します。manifest には元のデータベースと、テーブルごとのファイル、行数、バイトサイズ、SHA-256、`CREATE` 文(失敗した場合は停止の原因となったエラー)が記録されます。終了コード 1 はテーブルの失敗(`complete: false`)を、終了コード 2 は不正な引数、ClickHouse の接続先がないこと、または出力先ディレクトリに既にバックアップがあることを表します。
+
+データベースのすべての MergeTree ファミリーのテーブルを `system.tables` から読み取ってダンプします。マイグレーションランナーの `_` で始まるテーブル、`.inner` テーブル、KeeperMap のリース(データではなくライブの協調状態)、および `loom migrate` が作成するビューは対象外です。manifest の `backup_version` は 3 です。`--org` は `org` 列を持つすべてのテーブルを絞り込み、その列を持たないテーブル(`idempotency`、`signing_keys` など)はスキップします。これらのテーブルにはすべての org の行が入っています。
+
+`dev/restore_loom.py` は、すべてのファイルを manifest と照合して検証し(サイズ、行数、SHA-256)、計画を表示し、記録された `CREATE` 文から対象のデータベースと不足しているテーブルを作成します。その後、各ファイルをそのテーブルのステージングコピーに読み込み、ステージされたパーツをテーブルにアタッチします。アタッチではマテリアライズドビューが発火しないため、復元された行は、バックアップが同じく復元するテーブルに再度コピーされません(そうでなければ `memory_versions` はすべてのバージョンを 2 重に保持します)。また、ビューはライブデータベースへの書き込みに対しては動作し続けます。復元先は、`loom migrate` が準備したデータベース(ビューが存在する)か、スクラッチデータベース(テーブルは記録された DDL から作成される)にしてください。コード化されたベクトルテーブル(記録された `CREATE` に `Quantized(` を含む)を持つバックアップは、何かを書き込む前に拒否されます(`--dry-run` も同様)。これは、復元先のコーデック設定を読み取れない場合、または `enable_quantized_codec` を有効にできない場合です。有効にできる場合でも、`allow_suspicious_codecs` を有効にできないときは、テーブルから `Quantized` の後の汎用コーデックが外されます([制限付き設定](https://github.com/ClickHouse/loom/blob/main/docs/architecture/clickhouse.md#gated-clickhouse-settings))。挿入は `optimize_on_insert = 0` で実行されるため、`ReplacingMergeTree` キーの重複を含め、ダンプされたすべての行が書き込まれ、テーブルは自身のマージで重複をまとめます。各テーブルは、アタッチの前に `… attaching ` を、後に `✓` を表示します。実行が途中で打ち切られた場合、最後の行がそのときのテーブルを示します。`--into-nonempty` で再実行する前に、そのテーブルの件数を確認してください。再実行すると同じ行が再び追加されます。
+
+manifest には、挿入で発火する各マテリアライズドビューのソーステーブルとターゲットテーブルが記録されます。アタッチではビューが発火しないため、復元は、ビューの片方の端だけを含む選択を拒否します。`memory` を `memory_versions`(および `memory_code_link_queue`)なしで復元すると、`memory.history`、`memory.redact`、`namespace.rollback` が復元されたバージョンを認識できなくなります。`code_term_freq` を `code_chunks` なしで復元すると、コードの再取り込み時に再び埋められることになります。`documents` と `document_blobs` を結ぶビューはありませんが、復元は片方だけの選択も拒否します。原本のない documents は、ダウンロードのたびに 410 を返します。documents のない原本は、原本スイープが削除する対象です。両ツールは `documents` を他のどのテーブルよりも先に処理するため、`--into-live` でワーカーが動いていても、スイープは、それを参照する document より先に復元された原本の行を見ることがありません(バケットのオブジェクトについては後述)。両方の端を選択するか、復元先に既に行がある場合は `--allow-view-split` を渡してください。`dev/backup_loom.py --exclude t1,t2` は、パスが再構築するテーブルと、ビューがそれらから埋めるすべてのテーブルを除外します(`code_chunks` を除外すると `code_term_freq` と `code_doc_stats` も除外されます)。`restore_loom.py --exclude` はバックアップのテーブルを除外します。
+
+ドキュメントの原本(`document_blobs`)はバイナリです。ダンプはそれを生のバイト列として書き出し、`output_format_json_validate_utf8 = 0` を自身で設定するため、UTF-8 を検証するプロファイルでも置き換えられることはありません。バイナリの原本は、ダンプ内で元のサイズの約 1.6 倍になります。
+
+`LOOM_DOCUMENT_OBJECT_STORE=s3` で書き込まれた行にはオブジェクトの場所だけが入り、バイト列はバケットにあります。バケットは、そのバケット自身のバージョニングまたはレプリケーションでバックアップしてください。復元は、オブジェクトを参照する ClickHouse バックアップの後に、同じ名前のバケット(各行がその名前を保持しています)へ行うか、両方が戻るまで `LOOM_DOCUMENT_BLOB_GC_ENABLED=false` にして行います。復元されたオブジェクトは古い更新時刻を保持することがあり(復元方法に依存します)、その場合、バケットの走査は、`document_blobs` の行がまだ反映されていないオブジェクトをすべて削除してしまいます。
+
+バージョニングされたバケットは、削除されたオブジェクトをすべて非現行バージョンとして保持し、レプリケーションは既定では削除をレプリケートしません。そのため、消去およびスイープされた原本は、ライフサイクルルール(`NoncurrentVersionExpiration`、およびレプリカ側の有効期限)が削除するまで、バケット(またはそのレプリカ)に残ります。このルールの期間が、消去された原本をまだ復元できる期間であり、これは ClickHouse バックアップの保持期間が行に対して持つ意味と同じです。
+
+ダンプにはこのような行の原本のバイト列が含まれないため、移行できません。別のデプロイメントに復元された行は元のバケットを指したままで、その消去はバケットとプレフィックスの外にあるものとして拒否され、元のデプロイメントのスイープは、元の行がなくなるとオブジェクトを削除します。また、元のバケットとプレフィックスを指すターゲットは、そのカタログが参照していない元のオブジェクトをすべてスイープしてしまいます。移すには、ターゲットにドキュメントを再アップロードするか、元を停止してデプロイメント全体を移動してください。
+
+ステージングコピーはテーブルのエンジンを繰り返しますが、`Replicated` ではないデータベース内のレプリケートエンジンは、同じパラメータのローカル形式になります(コピーがテーブルの Keeper パスを再び要求してしまうためです)。その後、アタッチによってパーツがレプリケートされます。復元が作成するレプリケートテーブルは、記録された Keeper パスを、バックアップ元と同じデータベースでのみ、かつそのパスでレプリケートしているものが他になくなった後でのみ保持します(ライブのレプリカが残っている間は拒否されます)。別のデータベースでは独立したパスになります。サーバーの `default_replica_path` の下に新しい UUID を付けたもの、または Replicated データベースではそのデータベース独自のパスです。その既定値に必要なマクロがサーバーにない場合は拒否されます。
+各実行は、ステージングテーブルを `_restore__` と名付け、最初に run id を表示し、自分のものだけを削除します。1 つのデータベースへの復元(たとえば 2 つの org)は 1 度に 1 つずつ実行されます。実行は `default._loom_restore_lock_` を要求し(他の実行の要求を最大 5 分待ちます)、ターゲットをもう一度調べ、前の実行が残したものに以下の拒否を適用します。そのため、同じスコープの 2 回目の復元は、最初の行に折り込まれてしまう行をアタッチせずに、拒否されます。この要求は `default` 内のテーブルなので、セルフマネージドクラスタでは同じサーバー経由の実行の順序づけだけを行います。すべての復元を 1 台に向けてください。クラッシュした実行は、ステージングテーブルと要求を残します。その実行のプロセスが残っていなければ、`restore_loom.py --database --drop-staging ` で削除できます。
+挿入のステップより前には何も書き込まれません。`--dry-run` は計画の後で停止します。次のものは拒否されます。
+
+- `--into-live` なしでのライブデータベース(`loom`、またはサーバー設定が指定するデータベース)
+- `--into-nonempty` なしでの、バックアップのスコープ内で既に行を持つテーブル。挿入は追記なので、通常の MergeTree テーブル(`audit_log`、`agent_events`)はすべての行を 2 重に保持することになります。
+
+両ツールはサーバーと同様に ClickHouse の接続先を解決し(環境変数または `.env` の `LOOM_CH_*`。それぞれ `--host`、`--port`、`--user`、`--database`、`--secure` で上書きできます)、ホストが指定されていない場合は実行を拒否し、パスワードは `LOOM_CH_PASSWORD` からのみ読み取ります。
+
+```bash
+python dev/backup_loom.py --out-dir ./backups/$(date +%F) [--org acme] [--tables memory,namespaces]
+python dev/restore_loom.py --in-dir ./backups/ --database loom_restore --dry-run
+python dev/restore_loom.py --in-dir ./backups/ --database loom_restore --skip-idempotency
+python dev/restore_loom.py --in-dir ./backups/ --into-live \
+ --tables memory,memory_versions,memory_code_link_queue # one end of a view needs the other
+./scripts/ops/backup_drill.sh [--full-restore] # round-trip check into a scratch database
+```
+
+`scripts/ops/backup_drill.sh` はライブデータベースを一時ディレクトリにダンプし、manifest を行数のスナップショットと照合します。`--full-restore` を付けるとスクラッチデータベース `_drill` に復元し、すべてのテーブルの行数を比較し、終了時にスクラッチデータベースを削除します。同じキーの行をまとめるテーブル(`ReplacingMergeTree`、`AggregatingMergeTree` など)は、アタッチの直後にスクラッチデータベース内でマージされることがあります。そこでの行数の減少は、マージが実行された後なら警告、そうでなければ失敗です。このスクリプトはライブデータベースを読み取るだけです。ドリルは定期的に実行してください。
+
+ダンプはテーブルごとのもので、テーブル間のスナップショットではありません。クラスタ間でデータを移すために使い、ディザスタリカバリには使わないでください。
+
+
+
+## リストア後の監査ログの検証
+
+`python dev/verify_audit_chain.py [--org X] [--ts-since YYYY-MM-DD] [--json]` は、すべての `audit_log` 行のコンテンツハッシュを再計算します。不一致があれば終了コード 1 で終了し、検証を実行できなかった場合(不正な引数、対象なし、クエリの失敗)は 2、それ以外は 0 で終了します(行が 0 件の場合も成功として扱います)。不一致のレポートでは、行をパーティション、タイムスタンプ、リクエスト ID で示し、アクター、サブジェクト、名前空間は示しません。`audit_verifier` ワーカーは、同じ行単位のチェックをスケジュールに従って実行します。このチェックは行単位の改ざん検出であり、行にわたるハッシュチェーンではありません。1 時間ごとのチェックポイントは別途チェーンされています([監査](https://github.com/ClickHouse/loom/blob/main/docs/features/observability/audit.md))。
+
+
+
+## 名前空間内の変更の取り消し
+
+これらの操作は、誤った書き込み、誤動作したエージェント、誤ったインポートを、ClickHouse のリストアなしで取り消します。いずれも 1 つの名前空間を対象とします。`namespace.snapshot`、`namespace.restore`、`namespace.rollback` は MCP の `all` 一覧に含まれません。名前を指定するか HTTP 経由で呼び出すか、[ダッシュボード](https://github.com/ClickHouse/loom/blob/main/docs/features/dashboard.md)の Health → Repairs タブを使用してください。このタブでは、名前空間の管理者がスナップショットのダウンロード、リストア、ロールバックを行えます。
+
+| 操作 | ロール | 内容 |
+| -------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `memory.restore` | `WRITER` | トゥームストーン化された 1 つのキーを元に戻します |
+| `namespace.snapshot` | `ADMIN` | 名前空間のメモリ、型、グラント、監査ログの末尾(`include_audit_tail_n`、デフォルトは 1000)を JSON ペイロードとして固定します。`include_embeddings=false`(デフォルト)の場合、ターゲット側は自身のモデルで再埋め込みを行います |
+| `namespace.restore` | 新規ターゲットでは `VIEWER`、既存ターゲットでは `ADMIN` | スナップショットのペイロードを `target_namespace` に書き込みます(任意で `rebind_agent` を指定できます)。`snapshot_id` により冪等です。行は `version`、`content_sha256`、およびアテステーションのカラムを保持するため、`verified_by` は残ります。カラムに格納できない値(UUID ではないメモリ ID など)がペイロードにある場合は 422 で拒否されます。コレクションは拒否されます。そのスナップショットは通常の名前空間にリストアします |
+| `namespace.rollback` | `ADMIN` | すべてのメモリヘッド(または `memory_keys`)を `as_of` 時点のバージョンに戻します。古いバージョンを新しいヘッドとして復元し、それ以降に作成されたキーはトゥームストーン化します。デフォルトはドライランです(適用するには `dry_run=false`)。1 回の呼び出しで処理するのは最大 `max_keys` 件です(再度呼び出すべきかどうかは `truncated` が示します) |
+
+Postgres オーソリティの下では、消去によってターゲットから削除されたメモリは、その[削除エビデンス](../architecture/storage-authority.md)が保持されている間、リストアの対象から除外され、`counts.erased_skipped` に計上されます。エビデンスは、消去によってそのメモリが削除された名前空間のみを対象とします。そのため、消去前のスナップショットを別の場所にリストアすると、消去されたメモリが復活します。そのようなリストアの後は、同じ消去(そのスコープ)を再実行してください。
+
+`namespace.rollback` と `memory.history` は `loom.memory_versions` を読み取ります。これは `loom.memory` へのすべての挿入を記録する追記専用のミラーです(マージでは、置き換えられたバージョンが `loom.memory` 自体から削除されます)。ロールバックの動作は次のとおりです。
+
+- 名前空間の履歴より古い、または未来の `as_of` は拒否します。
+- ハード削除されたキーはスキップします(`skipped_no_head`)。
+- 復元されたヘッドの再埋め込みは、埋め込みワーカーに任せます。
+
+```bash
+AS_OF=$(date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%SZ) # GNU date; the instant before the bad writes
+curl -s -XPOST http://localhost:7777/v1/namespace.rollback -H "Authorization: Bearer $ADMIN_TOKEN" \
+ -H 'Content-Type: application/json' \
+ -d '{"org":"acme","namespace":"support","as_of":"'"$AS_OF"'"}' | jq '{dry_run, reinstate, remove, truncated}'
+```
+
+
+
+## Postgres を権威とする場合
+
+`LOOM_STORAGE_AUTHORITY=postgres` では、ライブメモリ、そのリビジョンジャーナル、ナレッジヘッド、取り込みジョブ、データセットカタログが Postgres にあり([ストレージ権威](../architecture/storage-authority.md))、デプロイメントでバックアップすべきストアは Postgres と ClickHouse の 2 つになります。
+
+| ストア | 単独で保持するもの | RPO | バックアップ手段 |
+| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| Postgres | すべてのメモリヘッドとリビジョン、ナレッジヘッド、取り込みジョブ、データセットカタログ、冪等性の応答 | 同期スタンバイへのフェイルオーバーをまたいでも、確認応答済みの書き込みについては 0。ポイントインタイムリストアでは、そのポイント以降の内容が失われます | HA マネージャーまたはサービスのベースバックアップと WAL アーカイブ |
+| ClickHouse | 検索ドキュメントとベクトル、ナレッジドキュメントおよび長いメモリ値のチャンク、Postgres が保持する範囲を超えた履歴、アナリティクス、トレース、監査行 | ClickHouse のみが保持するものについては、最後のバックアップからの経過時間。Postgres が保持するメモリリビジョンとナレッジドキュメントは再公開されますが、そのチャンクとデータセットの行は再公開されません。`loom reconcile` は再チャンク化すべき各ナレッジソースを示し、20 を超える場合はその名前空間(`loom rechunk`)を示し、あわせて再取り込みすべき各ソースを示します。長いメモリ値は、再設定されるまで抜粋で検索可能です | 上記の方法 |
+
+リストアの復旧時間は、ストア自体のリストア時間に `loom reconcile` の実行時間を加えたものです。この実行は、リストアされたストアが失った、もう一方のストアの記録を再実行します。
+
+
+
+### 片方のストアのリストア
+
+`LOOM_PG_PAYLOAD_CLEAR_ENABLED` を有効にした状態で ClickHouse をリストアする前に、ペイロードのクリアを停止し、[Postgres ジャーナルと ClickHouse のリストア](#the-postgres-journal-and-a-clickhouse-restore)の説明に従ってバックアップを選んでください。クリア処理が一度でも実行された場合は、手順 3 の `loom reconcile` を `010_revision_delivered_at.sql` を含むビルドで実行し、手順 4 でもそのビルドでデプロイメントを起動してください(ローリングアップグレードの[ルール 43](../architecture/rolling-upgrades.md#the-rules))。そのうえで次を行います。
+
+1. デプロイメントのすべてのサーバーとワーカーを停止します。
+2. バックアップからストアをリストアし、バックアップ自体のメタデータからバックアップ時刻を控えます(ClickHouse では `BACKUP` の開始時刻、Postgres ではリカバリターゲット)。
+3. `loom reconcile --restored clickhouse --point `(または `--restored postgres`)を実行します。再実行される内容が出力されます。続いて同じコマンドを `--apply` を付けて実行します。
+4. デプロイメントを起動します。
+5. ClickHouse のリストア後は、reconcile が出力した各 `loom rechunk` を実行し、「to ingest again」の下に挙げられた各ソースをアップロードして再取り込みします。ナレッジドキュメントのチャンクとデータセットの行は ClickHouse にのみ存在します。
+
+[セル](https://github.com/ClickHouse/loom/blob/main/docs/architecture/cells.md)の Postgres には、そのセルがテナンシー行を持たない組織の行を拒否する組織トリガーと、自身を示さないセッションからのテナンシー行を拒否する `loom.tenancy` ガードがあります。セルへの論理リストアはこのようなセッションに当たります。セルのすべてのプロセスを停止した状態で、マーカーを付けた 1 つのコマンド `PGOPTIONS='-c loom.tenancy_checked=on' pg_restore ...` として実行し、その後、他のポッドより先に `LOOM_BOOT_MIGRATE` を有効にしたポッドを 1 つ起動してください。既存スキーマへのデータのみの `pg_restore --disable-triggers` は、最後にすべてのトリガーをオリジントリガーとして有効にするため、`session_replication_role = replica` の下で `loom.cell_first` の 2 つのトリガーが無効のままになります。そのポッドの起動時にそれらが `ALWAYS` に戻され、戻るまでは `loom doctor` がそれらを指摘します。
+
+Helm チャート([Kubernetes](https://github.com/ClickHouse/loom/blob/main/docs/operations/kubernetes.md))で、リリース名を `loom` とした場合:
+
+1. 停止します:`kubectl scale deploy/loom --replicas=0`。`workers.enabled` の場合は `deploy/loom-workers` も停止します。アナリティクスエクスポートが有効なら一時停止します:`kubectl patch cronjob loom-analytics-export -p '{"spec":{"suspend":true}}'`。
+2. マネージドサービスは新しいサービスにリストアされます。`helm upgrade ... --set replicaCount=0 --set workers.replicaCount=0 --set autoscaling.enabled=false`(および新しい `clickhouse.host` または `postgres.host`)でリリースをそのサービスに向け、ポッドが起動しないようにします。ポイントは、サービスがバックアップとして示す開始時刻、または Postgres のリカバリターゲットです。
+3. 下記の Job はリリースのイメージを実行します。クリア処理が一度実行されていて、リリースが `010_revision_delivered_at.sql` を含まないビルドの場合は、まず `helm upgrade ... --set image.tag=`(または `image.digest`。設定されていればこちらが優先されます)を、手順 2 の新しいホストと 3 つの `--set` オーバーライドとともに実行してポッドが起動しないようにし、手順 4 でもそのイメージを維持します。reconcile は、Web ポッド自身の spec から作成した Job で実行します。これによりリリースの環境、Secret、Postgres CA が引き継がれ、固有のコンポーネントラベルを持ち(NetworkPolicy はこれを選択しますが、Service は選択しません)、プローブはありません。
+
+ ```bash
+ kubectl get deploy/loom -o json | jq '{apiVersion: "batch/v1", kind: "Job",
+ metadata: {name: "loom-reconcile"}, spec: {backoffLimit: 0, template: {
+ metadata: {labels: (.spec.selector.matchLabels
+ | .["app.kubernetes.io/component"] = "reconcile")},
+ spec: (.spec.template.spec | .restartPolicy = "Never" | .containers |= [.[0]
+ | del(.livenessProbe, .readinessProbe, .startupProbe)
+ | .command = ["loom", "reconcile", "--restored", "clickhouse", "--point", ""]])}}}' \
+ | kubectl apply -f -
+ kubectl logs -f --pod-running-timeout=10m job/loom-reconcile
+ kubectl wait --for=condition=complete --timeout=10s job/loom-reconcile
+ ```
+
+ Postgres のリストア後は `"postgres"` を使います。Job がまだ実行中(`kubectl get job loom-reconcile -o jsonpath='{.status.active}'` が `1`、ログストリームが切れると `logs -f` が早く終わります)の間に `wait` が失敗した場合は、まだ実行中なので、再びログを追ってください。失敗した Job(`.status.failed` が `1`)は非ゼロで終了しています。出力を読み、Job を削除して、再実行してください。ドライランが問題なければ、`"--apply"` を末尾に加えて実行します。
+
+4. 再び起動します:リリースの values ファイルで `helm upgrade` を実行します。手順 2 の新しいホストと、手順 3 で設定した場合は `image.tag` または `image.digest` を引き継ぎ、手順 2 の 3 つの `--set` オーバーライドは付けません。そしてアナリティクスエクスポートを再開します。reconcile が出力した各 `loom rechunk` を `kubectl exec deploy/loom -- loom rechunk ...` で実行し、「to ingest again」の下に挙げられた各ソースをアップロードして再取り込みします。
+
+`loom reconcile --apply` は次を行います。
+
+- もう一方のストアがポイント以降に完了と記録している各消去を再実行します(台帳は秒単位で保持されるため、ポイントの秒の先頭から)。カウント(census)は行いません(もう一方のストアには、消去後にユーザーが書き込んだ内容が残っているため)。また、リストアされたコピーがポイント以前に実行済みと示すステップは除外します。ClickHouse の場合、除外されるのはポイント以前に書かれた最後の ClickHouse チェックポイントのステップから、census が再オープンしたものを除いたものです(`BACKUP` は開始時からテーブルを順にコピーするため、すべてのコピー済みテーブルに含まれるのはそれらの削除だけです。マージで消えた行がある場合、すべてのステップが実行対象になります)。Postgres の場合は、台帳行が、各ステップがコミットされたトランザクション内で記録したステップです(前のビルドのプロセスが実行したステップは記録されず、再実行されます)。これらを再実行すると、その後にユーザーが書き込んだ内容を削除してしまうためです。リストアされた台帳行は、すべてのステップが実行されると completed になります。それまでは、ClickHouse のリストア後は「replay after a restore pending」とともに `failed` と読まれ、この行はリカバリワーカーも `loom erasure-re-verify --resume` も実行しません。リストアされた行がポイント以前に completed だったもの、または以前の実行が完了させたものは再実行されません。リプレイ応答のステップは、あらゆる消去と同様に、組織のリプレイキャッシュ全体を両方のストアで削除します。終了状態のない消去はリカバリワーカーに任され、そのチェックポイントは、リストアで取り消されたステップを再オープンして書き直されます。ClickHouse のリストア後に、リストアされた行が completed または abandoned を示す消去は、代わりに Postgres の台帳行にその旨が記録されます。再開された saga は通常どおり census を含めて実行され、その範囲でユーザーがその後に書き込んだ内容を数えます。ポイント以降に完了したのに Postgres の台帳行が完了を取りこぼした消去も同様です。この端のケースは、リカバリパスが、要求の 10 分後、または完了後のどちらか遅い方の最初のパスで解消します。abandoned の消去は決して実行されません(`loom erasure-re-verify` が扱います)。
+- ClickHouse のリストア後:まず、ポイント以降にコミットされたすべての Postgres リビジョンとナレッジヘッド(ライターのリースと挿入の上限、つまりポイント以前に採番された書き込みがポイント以降にコミットされうる余裕分を差し引いたもの)と、ClickHouse がより古いバージョンで保持しているすべての Postgres ヘッドを、まだ期限に達していない配信として保留します。次に消去を実行し、その Postgres のステップはスキップします(保持されており、再実行すると消去後にユーザーが書き込んだ内容を削除してしまうため)。保留した配信を公開します。その後、Postgres がポイント以降に記録しているすべてのリダクションを再実行し、ClickHouse がリストアした内容と、それを引用するキャッシュ済みの応答や先例を消去します。
+- Postgres のリストア後:リストアされたコピーに対して、消去の Postgres ステップとリプレイ応答のステップを実行し、ClickHouse がポイント以降に記録しているすべてのリダクションを実行します。リダクション済みのバージョンがコピー上で再びライブヘッドになっている場合(それを置き換えた書き込みが失われたため)は、その場で消去されます。ポイント以降に書き込まれた内容は、ポイントインタイムリストアの通例どおり失われます。ClickHouse にはそのコピーがまだ残っていますが、Postgres に対応するヘッドがなくなるため、検索はそれを返しません。
+
+データセットの行は ClickHouse にのみ存在し、取り込みだけがそれを構築します。そのため ClickHouse のリストア後は、ポイント以降に行が書かれたデータセット(公開、または列の型を変更した承認)は、Postgres にあるカタログ行がそれらの行を指しているにもかかわらず、行が欠けた状態で読み取られます。`loom reconcile` は、ドライランでも、ポイント以降にカタログ行が書かれた各ソースを、アップロードして再取り込みすべきものとして示します。これには、残存していた行の上に承認またはメタデータ編集が書き込んだ行も含まれます。
+
+ナレッジ取り込みジョブには専用のステップは不要です。ジョブの読み取りは Postgres の行と ClickHouse の行のうち新しい方を取り、Postgres が保持するジョブは、キューが提示したときに再び射影されます。ClickHouse のリストアポイント以降に終了したジョブは再提示されないため、ClickHouse を読む `knowledge.inspect` は、その行が期限切れになるまでそれを一覧表示しません。
+
+完了しなかったリプレイは、その ClickHouse 行を「replay after a restore pending」とともに `failed` のままにします。デプロイメントを起動する前、および reconcile より前のビルドへロールバックする前に(そのビルドのリカバリワーカーは census 付きでその行を再開してしまいます)、`loom reconcile` を終了コード 0 になるまで再実行してください。
+
+何かを書き込む前に、ポイントが現在より後の場合、ワーカーが workers-lease の 2 期間(`LOOM_SUPERVISOR_LEASE_TTL_S`、デフォルトでは 1 分)以内にパスを報告している場合、ポイントが `LOOM_ERASURE_LEDGER_DAYS`(ClickHouse の台帳読み取りは 89 日分を保持)より古い場合、および `--restored both` の場合は、実行が拒否されます。両方のリストアポイント以降に行われた消去とリダクションはどちらのストアにも存在せず、監査エクスポートから再発行する必要があります。両方の台帳は消去を要求された時刻で保持するため、消去の最長実行時間の範囲内にあるポイントでは、その端より前に要求されてポイント以降に完了した消去を取りこぼすことがあります。バックアップは、台帳の日数よりその分だけ新しいものを保ってください。書き込みの前にコードリポジトリレジストリを読み取り、その読み取りが失敗した場合は拒否します。実行するすべてのステップは冪等であるため、途中で打ち切られた reconcile や終了コード 1 の reconcile は、デプロイメントを起動する前に最初から再実行してください。保留された配信は、実行が完了するまで `GET /v1/health?include=postgres` で parked として一覧表示されます。
+
+
+
+## 復旧できるものとできないもの
+
+| 状況 | 復旧可否 | 方法 |
+| ---------------------------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `memory.delete` または `memory.clear` で削除マーク(tombstone)が付いたメモリ | 可能 | `memory.restore`、または削除前の時点への `namespace.rollback` |
+| 後のバージョンで上書きされたメモリ | 可能 | `memory.history` でバージョンを確認し、`namespace.rollback` で 1 つを復元する |
+| `purge: true` を指定した消去、またはパージされたベンチマーク名前空間 | 不可 | purge は完全に削除するため、復元期間はありません。それより前に取得したバックアップのみが頼りです |
+| 削除マークを付けた消去(`purge` なし) | 確定として扱う | saga の census により、対象範囲がすべての読み取り経路から消えていることが確認済みです。元に戻すと削除要求を取り消すことになるため、消去そのものが誤りだった場合にのみバックアップから復元します |
+| イメージをロールバックした後の、新しいビルドのスキーマ | 不要 | マイグレーションは追加のみのため、以前のビルドでも新しいスキーマを読み取れます([アップグレード](https://github.com/ClickHouse/loom/blob/main/docs/operations/upgrades.md#rollback)) |
+| 以前のスキーマ | バックアップから | ダウンマイグレーションはありません。アップグレード前に取得したバックアップから復元してください |
+| 単一ノードの ClickHouse OSS サーバーのディスク | バックアップから | レプリケーションもポイントインタイムリカバリもなく、ノードの耐久性は自身のディスクに限られます |
+| コードインデックスのテーブル | 再構築可能 | `loom code backfill` が git ミラーから再生成します([コードインデックスの運用](https://github.com/ClickHouse/loom/blob/main/docs/operations/code-index-operations.md#first-index)) |
+| オプトインの保持 TTL によって削除された行 | 不可 | TTL による削除は確定です。それより前に取得したバックアップのみが頼りです |
+
+自己管理の単一 OSS ノードでは、`BACKUP DATABASE`(または `clickhouse-backup`)をスケジュールして、ホスト外のストレージに保存してください。ClickHouse Cloud はサービス自体をレプリケーションしてバックアップするため、そこでのポータブルダンプはデータの移動用であり、耐久性のためのものではありません。
+
+
+
+## Postgres ジャーナルと ClickHouse のリストア
+
+Postgres をオーソリティとする構成では、`loom.memory_revisions` がすべてのリビジョンを保持します。ClickHouse をリストアすると、バックアップ以降にコミットされたバージョンはジャーナルにはありますが、リストアされた `memory_versions` にはありません。そのコンテンツが残るのは、ペイロード(`row`)がまだジャーナルにある間だけです。`LOOM_PG_PAYLOAD_CLEAR_ENABLED` を有効にすると、`pg_payload_clear` ワーカーが、利用可能なすべてのバックアップが保持しているバージョンのペイロードをクリアします([ペイロードのクリア](../architecture/storage-authority.md#payload-clearing))。ClickHouse をバックアップしていない場合は無効のままにしてください。その場合、ジャーナルはすべてのペイロードを保持し続けます。
+
+**ホライズン。** `LOOM_CH_BACKUP_INTERVAL_MINUTES` には、ClickHouse のバックアップを開始する間隔を設定します。パスは、ClickHouse への配信からホライズンより長く経過したバージョンだけをクリアします。ホライズンは `LOOM_PG_PAYLOAD_RESTORE_HORIZON_MINUTES` で指定します。
+
+- 0(デフォルト)の場合、ホライズンは間隔の 2 倍に 60 を足した値になります。これにより、最新のバックアップが失敗していても、その前のバックアップが予定どおりに開始されていれば、リストアで 1 つ前のバックアップに戻れます。
+- 間隔に 60 を足した値を下回ることはなく、挿入の上限に 60 を足した値も下回りません。これより小さい値を設定した場合は、2 つのうち大きい方に引き上げられます。
+- 間隔に 60 を足した値以上、間隔の 2 倍に 60 を足した値未満の場合は、最新のバックアップが予定どおりに開始されていたときに限り、そのバックアップだけをカバーします。
+
+どちらの設定も LIVE です。変更は、プロセスがオーバーライドを再読み込みした後(`LOOM_RUNTIME_OVERRIDES_REFRESH_SECONDS` ごと)の最初のパスで反映されます。すでに実行中のパスは、開始時のホライズンのまま動作します。
+
+**マージンの理由。** 60 分は、バックアップの開始時刻からはわからない次の要素を吸収します。
+
+- バックアップが読み取るレプリカが、挿入を受け付けたレプリカより遅れていること
+- Postgres とバックアップホストの間のクロックスキュー
+
+クリアされたバージョンはすべて、クリアが停止する時点よりホライズンを超えて前に配信されています。したがって、クリアが停止した時点より前に、ホライズンから 60 分を引いた時間未満の前に開始されたバックアップ(その時点でのバックアップの経過時間が H から 60 分を引いた時間未満であるバックアップ)は、遅延とスキューの合計が 60 分未満である限り、クリアされたすべてのバージョンを保持しています。開始が遅れたバックアップは、その開始時刻に現れます。これを以下のステップ 4 で確認します。最小のホライズンでは、最新のバックアップは予定どおりに開始されていれば条件を満たしますが、遅れていた場合は満たさないことがあります。`BACKUP ... ON CLUSTER` はすべてのシャードを一度に処理します。ノードごとのツールを使う場合は、バックアップの開始時刻を最も早いノードの開始時刻として数えてください。
+
+**リストアの前に、クリアを停止する。** バックアップを選ぶ前に、ClickHouse にまだバックアップにはないバージョンが残っているうちに、次を行います。
+
+1. デプロイメントの env で `LOOM_PG_PAYLOAD_CLEAR_ENABLED=false` を設定します。この設定は LIVE ではなく、`loom.runtime_overrides` をリストアしても再び有効になることはありません。
+2. その env で、すべての Loom プロセスを再起動します。再び起動される可能性のある停止中のインスタンスは削除するか、新しい env で再作成します。
+3. 実行中または起動可能なすべての Loom プロセスで、このスイッチが明示的に `false` になっていることをオーケストレーターで確認します。未設定のままだと、スイッチの値は dotenv ファイル(`LOOM_ENV_FILE`。デフォルトは作業ディレクトリの `.env`)、または環境変数もしくはその dotenv が指す設定ファイル(`LOOM_SETTINGS_FILE`)から決まり、どちらもスイッチを有効にしうります。
+4. バックアップを選ぶのは、その後です。上の手順 3 の確認(クリアが停止した時刻)より、ホライズンから 60 分を引いた時間未満の前に開始されたバックアップを選びます。ホライズンを下げていた場合は、直近のホライズンの期間内に有効だった最小のホライズンを使います。デフォルトのホライズンでは、予定どおりに開始されていれば、最新のバックアップかその 1 つ前のバックアップが該当します。それより古いバックアップには、ペイロードがすでにクリアされたバージョンが含まれていない可能性があり、その場合そのバージョンのコンテンツは失われます。
+5. スイッチを再び有効にするのは、[1 つのストアのリストア](#restoring-one-store)のステップ 4 でデプロイメントが再び起動するときで、それより前ではありません。その時点では、`loom reconcile --apply` が、そのポイント以降にコミットされたすべてのリビジョンについて配信を再び未完了にしており、リビジョンは配信が未完了の間はペイロードを保持します。まず、`LOOM_CH_BACKUP_INTERVAL_MINUTES` と `LOOM_PG_PAYLOAD_RESTORE_HORIZON_MINUTES` をバックアップのスケジュールと照らして確認してください。リストアによって、これらのオーバーライドはバックアップ時点のものに戻っているため、それ以降に変更していた場合は再適用します。リストア後も ClickHouse にないバージョンはペイロードを保持し、そのバージョンに到達した各パスが `missing_in_clickhouse` に数えるため、この値は 0 を超えたままになることがあります。[1 つのストアのリストア](#restoring-one-store)のステップ 4 で、`010_revision_delivered_at.sql` を含むビルドを、それを含まないビルドを提供していたデプロイメントで起動する場合、そのビルドが単独で提供を始めてから 1 回分のクリアホライズンが経過するまで、スイッチは無効のままにします([ルール 43](../architecture/rolling-upgrades.md#the-rules))。
+
+[ゼロダウンタイムペア](https://github.com/ClickHouse/loom/blob/main/docs/operations/deployment.md#zero-downtime-pair)では、次のようにします。
+
+1. `.env` を編集します。
+2. `origin/main` より遅れていないチェックアウトから `./redeploy.sh --force` を実行します。
+3. 再デプロイが成功したか失敗したかにかかわらず、`docker inspect -f '{{.Config.Env}}'` に `LOOM_PG_PAYLOAD_CLEAR_ENABLED=false` が表示されない `loom-*-workers` コンテナーを、実行中か終了済みかを問わずすべて停止し、`docker rm` で削除します。web コンテナーはワーカーを実行しません。前のカラーのワーカーコンテナーがなくなれば、`--rollback` は現在のワーカーを維持します。
+4. これによってワーカーコンテナーが 1 つも残らない場合は、原因を修正して、ステップ 2 をもう一度実行します。
+
+これらの手順を省略してリストアすると、バックアップからリストアまでの間にコミットされたバージョンのコンテンツが失われることがあります。そのメタデータはジャーナルに残ります。
+
+
+
+## ロールバック用のカラー
+
+[ゼロダウンタイムのペア](https://github.com/ClickHouse/loom/blob/main/docs/operations/deployment.md#zero-downtime-pair)では、`redeploy.sh` は以前のカラーのコンテナ(`loom-`、`loom--workers`)を削除せずに停止し、以前のイメージに `loom:prev` のタグを付けます。`./redeploy.sh --rollback` はそれらを起動し、ヘルスチェックを行ってから、プロキシを元に戻します。以前のカラーのコンテナが存在しない場合、ロールバックは拒否されます("the previous build is gone")。その場合は、正常に動作することが確認できているコミットを再デプロイしてください。
+
+> **警告:** ペアを実行しているホストでは、`docker container prune` や `docker system prune` を決して実行しないでください。停止中のロールバック用カラーが削除されます。ディスク容量を空けるには `docker builder prune` と `docker image prune` を使用してください。また、使い捨てのコンテナに `loom-blue` や `loom-green` という名前を付けないでください。名前を指定してそのコンテナを削除すると、カラーが削除されます。
+
+ロールバックの後も、ロールフォワードされていたカラーの web コンテナは、停止するまで動き続けます(ロールバック時に表示されるとおり、`docker stop -t 75 loom-` で停止します)。そのカラーの workers コンテナは切り替えの前にすでに停止されているため、workers のリースはロールバック先のカラーが保持します。ロールバック先のカラーに workers コンテナがない場合に限り、ロールフォワードされていたカラーが workers を動かし続けます。
+
+
+
+## デプロイメントの移行
+
+同じ ClickHouse(`LOOM_STORAGE_AUTHORITY=postgres` の場合は Postgres も)を指す新しい Loom プロセス、または移行・復元した ClickHouse を指す新しい Loom プロセスは、すべての機能を取り戻します。Postgres をオーソリティとする場合は、どちらのストアをコピーする前にもソースを停止してください。別の時点で取得したバックアップから片方のストアだけを復元する場合は、[片方のストアの復元](#restoring-one-store)にあたります。次のものを持ち越します。
+
+- ClickHouse:同じサービス、Keeper の状態を含むコピー、または `loom migrate` で準備した ClickHouse に復元した `dev/backup_loom.py` のダンプ。
+- Postgres(`LOOM_STORAGE_AUTHORITY=postgres` の場合):同じサービス、またはそのコピー。
+- 環境設定(`.env` またはコンテナの環境変数)。
+- `LOOM_JWT_SECRET`。これがないとどのトークンも検証できず、保存済みの認証情報と署名鍵も開けません。
+- カタログの行がバケット内のオブジェクトを指している間は、同じ名前とプレフィックスの `LOOM_DOCUMENT_S3_BUCKET`。新しいホストから到達できる同じバケット、または別のエンドポイント上の同名のバケットを使えます(`LOOM_DOCUMENT_S3_ENDPOINT_URL` は行の場所の一部ではありません)。各行はバケット名を持っており、Loom にはそれを書き換えるツールがありません。別の名前でコピーすると、ダウンロードも削除もすべて古いバケットを指したままになります。
+
+それ以外はすべて ClickHouse から復元されます。ClickHouse に保存されたドキュメントの原本、署名鍵、ランタイムのオーバーライド、スーパーバイザーのリース、失効情報、サインイン試行回数、グラフ走査の無効化マークです。Git ミラーは、次回の取り込みパス、または新しいホストでの最初の履歴読み取りの際に、記録されたリモートから再クローンされます。
+
+限定的な例外:
+
+- イベントストリーム(予算違反)は `SIGTERM` で排出されます。`SIGKILL` や OOM では、このテレメトリが最大で 1 回のフラッシュ間隔分失われますが、監査行やメモリの行が失われることはありません。
+- プロバイダーの再構成は、停止したプロセスについて、同じホスト上のプロセスがそのプロセスの消滅を確認するまで、Kubernetes ではワーカーのリーダーがその Pod の消滅を確認するまで待機します。それ以外の場合、ホストごと失われたもの(新しいホストへの移行)は、`loom participant retire --participant --yes` で手動で退役させます([プロバイダーの再構成](../architecture/provider-reconfiguration.md))。
+- レート制限バケットの充填状態はホストごとです。数秒で補充されるため、新しいホストは満杯のバケットで始まります。
+
+
+
+## 関連ドキュメント
+
+- [アップグレード](https://github.com/ClickHouse/loom/blob/main/docs/operations/upgrades.md):ロールバック手順と追加のみのマイグレーションのルール
+- [メンテナンス](https://github.com/ClickHouse/loom/blob/main/docs/operations/maintenance.md#erasure):消去サーガとその復旧
+- [履歴と来歴](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/history-and-provenance.md):`memory.history` が返す内容
+- [障害と復旧](../architecture/failure-and-recovery.md):コンポーネントに障害が発生したときのシステムの動作
diff --git a/i18n/.pending/ja/docs/operations/monitoring.md b/i18n/.pending/ja/docs/operations/monitoring.md
new file mode 100644
index 0000000000..f997740662
--- /dev/null
+++ b/i18n/.pending/ja/docs/operations/monitoring.md
@@ -0,0 +1,323 @@
+
+> このページは[英語の原文](https://github.com/ClickHouse/loom/blob/main/docs/operations/monitoring.md)の機械翻訳です。内容は英語の原文が優先されます。
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/operations/monitoring.md), which is authoritative.
+
+
+
+# モニタリング
+
+このページでは、何を監視すべきかを説明します。Loom は次の 4 つの手段で自身の状態を報告します。
+
+| 手段 | 対象範囲 |
+| ------------------------------- | ------------------------------------------ |
+| `/v1/health`, `loom doctor` | 単一のプロセス |
+| `ops.health` | ClickHouse に対するより詳細なチェック |
+| OpenTelemetry のメトリクスとスパン | 同じ ClickHouse、または OTLP に書き込まれる |
+| `loom.agent_events` | リクエストの台帳(1 つの操作につき 1 行) |
+
+メトリクス名とラベルの一覧は、[テレメトリ](https://github.com/ClickHouse/loom/blob/main/docs/features/observability/telemetry.md)にまとめています。
+
+
+
+## オペレーターコマンドの実行
+
+オペレーターコマンドは `loom` のサブコマンドです。デプロイメントの環境を持つコンテナ内で実行します。
+
+```bash
+docker exec loom-server loom doctor # web container
+docker exec loom-workers loom code stats # workers container (split deployments)
+```
+
+チェックアウトした環境からは、`pip install -e .` で同じ CLI をインストールできます。この CLI は環境変数と `.env` から `LOOM_*` を読み取ります。`loom --help` で各フラグの説明を確認できます。すべてのコマンドは[CLI リファレンス](https://github.com/ClickHouse/loom/blob/main/docs/reference/cli.md)に一覧があります。
+
+組織全体のビュー(名前空間をまたぐコスト、`ops.health`)には `ORG_ADMIN` または `PLATFORM_ADMIN` が必要です。これらは `LOOM_PLATFORM_ADMINS` でのみ付与されます([デプロイメント](https://github.com/ClickHouse/loom/blob/main/docs/operations/deployment.md#required-environment))。デプロイメント全体の `/v1/admin/*` ルートには `PLATFORM_ADMIN` が必要です。`token.mint`、`namespace.adopt`、`claim_release` は、対象とする組織の `ORG_ADMIN` が必要です。名前空間の `admin` では、これらのいずれにもアクセスできません。
+
+
+
+## ヘルスチェック
+
+```mermaid
+flowchart TD
+ H["/v1/health (any process, no token)"] -->|"HTTP 200/503"| L["liveness: ClickHouse answers SELECT 1"]
+ H -->|"body: status, problems, schema.pending"| R[readiness]
+ D["loom doctor (CLI)"] -->|"same problems list"| R
+ O["ops.health (ORG_ADMIN)"] --> X["ClickHouse parts, workers, stubs, contracts"]
+```
+
+
+
+### /v1/health エンドポイント
+
+```bash
+curl -s http://localhost:7777/v1/health | jq '{status, version, ch_ok, build_commit, schema, problems}'
+curl -s 'http://localhost:7777/v1/health?include=workers' | jq '.workers_leader'
+```
+
+- **HTTP ステータスは ClickHouse のみで決まります。** `SELECT 1` に応答すれば 200、応答しなければ 503 を返します(`ch_error` にはエラーの種類が入り、テキストはサーバーログにあります)。これをライブネスプローブとして使ってください。ステータスコードだけを読むプローブ(イメージのヘルスチェックやロードバランサー)は、本文を解析しない 200 ではなく、障害を検知できます。
+- **`status`** は、ClickHouse が停止している場合、または `problems` のいずれかのエントリの重大度が `error` である場合に `degraded` になります。ただし `code_tier_failing` は例外です。これはデプロイではなくリポジトリのインデックスに関する問題だからです。それ以外は `ok` です。レディネスチェックでは、あわせて `schema.pending` が空であることも条件にしてください(ゼロダウンタイムのペアの切り替えはまさにこれを行います)。
+- **`problems`** は `{code, severity, message, fix, source}` のリストで、深刻なものから順に並びます。同じリストが `loom doctor` で出力され、ダッシュボードのバナーにも表示されます。`loom doctor` は `code_tier_failing` に含まれるエントリを最大 5 件まで名前で示します(残りは `code.repos` に名前が出ます)。プラットフォーム管理者のトークンでは、制限されていない各エントリが名前で示されます([ティアが失敗したとき](https://github.com/ClickHouse/loom/blob/main/docs/operations/code-index-operations.md#when-a-tier-fails))。
+
+| 問題コード | 重大度 | 意味 |
+| ----------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `fake_embedder`, `fake_llm` | warn(`LOOM_REQUIRE_REAL_PROVIDERS=true` の場合は error) | フェイクプロバイダーが設定されています |
+| `embedder_key_missing`, `llm_key_missing` | warn(同上) | 実プロバイダーが設定されているのにキーがありません。プロセスはフェイククライアントで動作します |
+| `embedding_dim_mismatch` | error | エンベッダーが返す次元数が `LOOM_EMBEDDING_DIM` と異なります |
+| `coded_width_mismatch` | error | コード化ベクトル列の幅が、書き込まれるデータの幅と異なります。それらの書き込みは失敗します |
+| `provider_failing:` | error | そのプロバイダーへの直近の呼び出しが失敗しました。次に成功すると解消します |
+| `model_configuration_refused` | error | ダッシュボードで保存したモデル設定がゲートウェイチェックに失敗し、適用されていません。すべてのデータプレーンリクエストが 503 `GATEWAY_REQUIRED` を返し、設定を置き換えるまでサーバーはレディになりません |
+| `jwt_secret_empty` | error | トークンに署名できません |
+| `dev_jwt_secret` | warn | 認証が有効なのに、リポジトリにチェックインされた開発用シークレットを使っています |
+| `config_drift` | error | このプロセスのルートシークレットまたは MUST_MATCH 設定が、デプロイで公開されている設定と異なります。レディではありません([N 個のレプリカの実行](https://github.com/ClickHouse/loom/blob/main/docs/operations/replicas.md)) |
+| `revocation_not_loaded` | error | 認証が有効なのに、このプロセスが `loom.revoked_tokens` を一度も読み込んでいません。すべてのベアラーに 503 が返ります |
+| `revocation_stale` | warn | 失効スナップショットが max(300 秒, 10 × `LOOM_JWT_REVOCATION_CACHE_TTL_SECONDS`) より古くなっています。それ以降に失効したトークンも、ここでは認証に通ります |
+| `revocation_too_stale` | error | スナップショットが `LOOM_JWT_REVOCATION_MAX_STALE_SECONDS`(600 秒)より古くなっています。更新されるまで、すべてのベアラーに 503 が返ります |
+| `pending_migrations` | error | このビルドが想定するマイグレーションがスキーマに適用されていません |
+| `instance_label_missing` | warn | compose ファイル外のプロセスに `LOOM_INSTANCE_LABEL` が設定されていません |
+| `workers_lease_absent` | warn または info | warn: 有効なワーカーリースを保持しているプロセスがありません(`LOOM_BACKGROUND_WORKERS=on` のプロセスはリースを取らないため、そのプロセスと並んで表示されます。引き継ぎ中やコールドスタート中は、一瞬だけ表示されることがあります)。info: このプロセスはワーカーを実行しておらず、最近リースを読み取っていません |
+| `workers_lease_unreachable` | warn | このプロセスが ClickHouse にワーカーリースを問い合わせられませんでした。すべてのプロセスがこれを報告している場合、ワーカーを実行しているものはありません |
+| `workers_lease_given_up` | warn | このプロセスはワーカーリースを解放し、獲得の試行をやめました(ドレイン中か、ワーカーの子プロセスが起動に失敗し続けています)。別のプロセスが引き継ぎます |
+| `otel_erasure_index` | warn | ClickStack のメトリクステーブルに、消去に必要なインデックスがありません([メンテナンス](https://github.com/ClickHouse/loom/blob/main/docs/operations/maintenance.md#clickstack-erasure-index)) |
+| `code_tier_failing` | warn(`LOOM_CODE_TIER_FAILING_ERROR_LAG_COMMITS` 分も遅れている場合は error。フェッチティアは warn のまま) | コードインデックスのティアが、`LOOM_CODE_TIER_FAILING_WARN_PASSES` 回連続、または `LOOM_CODE_TIER_FAILING_WARN_HOURS` の間、失敗しました。fix には、そのエラー種別に必要な対処が示されます([ティアが失敗したとき](https://github.com/ClickHouse/loom/blob/main/docs/operations/code-index-operations.md#when-a-tier-fails))。`status` を degraded にすることはありません。`loom.health.problems` には他の問題と同様に含まれるため、そこで `severity="error"` を対象にしたアラートは `code="code_tier_failing"` を除外する必要があります。 |
+
+その他の本文フィールドは次のとおりです。`providers`(プロバイダーごとの呼び出し状態)、`fake_embedding`、`fake_llm`、`providers_degraded`、`embedding_dim_mismatch`、`adaptive_thresholds`(エンベッダーから導出された類似度のしきい値。`calibration_hash` は同じしきい値を使うすべてのレプリカで等しくなります。`source` は `shared` か、このレプリカ自身の `probe` です)、`ratelimit.backend`(`shared` または `per-process`)、`mode`(`ch`。設定されている場合は `langfuse` と `clickstack` も含まれます)。`?include=` には `workers`、`langfuse`、`otel`、`embedding_cache`、`llm_cache` を指定できます。各サブシステムは個別に報告され、HTTP ステータスを決めるのは ClickHouse だけです。
+
+
+
+### loom doctor コマンド
+
+`loom doctor` は各チェック(`python_version`、`settings_load`、`jwt_secret`、`clickhouse_reachable`、`otel_erasure_index`、`llm_provider`)を実行し、続いて `problems` リストを `problem:` の行として出力します。すべてのチェックを報告してから終了し、いずれかの行が `FAIL` の場合、終了コードは 1 になります。`--json` を指定すると `{ok, checks, problems}` を出力します。`LOOM_CELL` が設定されていて ClickHouse に到達できる場合は、[セル](https://github.com/ClickHouse/loom/blob/main/docs/architecture/cells.md)のチェック(`cell_state`、`cell_marker`、`cell_marker_everywhere`、`cell_triggers`)も実行します。これらの評価は最大でも `WARN` です。`cell_deployment` は、デプロイチェックが拒否した場合(`LOOM_PG_DSN` がない、別の記録済み権限またはデプロイがある、ClickHouse へのアクセスが拒否された)に `FAIL` になります。コードインテリジェンスが有効で ClickHouse に到達できる場合は、失敗しているコードインデックスのティアも読み取り、デプロイのランタイムオーバーライドで評価します。`problem:code_tier_failing` は `status` を degraded にしないため、最大でも `WARN` です。
+
+`--client` を指定すると、このマシンをコーディングエージェントのクライアントとしてもチェックします。対象は、フックが使うサーバー URL とトークン(`--server-url` と `--token` で上書きできます)、トークンが受け入れられ、その名前空間に書き込めるか、Claude Code または Codex の設定、サーバーに届かなかったキャプチャジョブです。`loom report` は、バグ報告の Environment フィールド用に doctor の出力を表示します([issue の報告](https://github.com/ClickHouse/loom/blob/main/CONTRIBUTING.md#filing-an-issue))。
+
+
+
+### ops.health オペレーション
+
+`POST /v1/ops.health`(`ORG_ADMIN`)は、ClickHouse に対してより詳細なチェックを実行します。各チェックは `status`(`ok`、`warn`、`fail`)、`detail`、`repair` を返します。失敗したプローブの `detail` にはエラーの種類(Loom エラーのコードとメッセージ)が入り、各ワーカーの `last_error_kind` にはエラーのクラスが入ります。エラーのテキストはサーバーログと `/v1/admin/workers.status` にあります。プロセス内のスーパーバイザーがワーカーを実行している場合、`/v1/health?include=workers` もワーカーの行を同じように切り詰めます。`last_error` はなく、結果の数値とフラグだけが含まれます。
+
+| チェック | 確認対象 |
+| ------------------------ | --------------------------------------------------------------------- |
+| `clickhouse_parts` | テーブルごとのアクティブなパート数と、直近 15 分間に失敗したマージ |
+| `workers` | 直近のワーカーパスの失敗 |
+| `embedding_stubs` | ベクトル待ちのメモリ埋め込み行 |
+| `schema_contracts` | リスクの高いテーブルとカラムを、スキーマダンプと照合した結果 |
+| `memory_schema_contract` | 永続化された `loom.memory` のカラムを、スキーマダンプと照合した結果 |
+| `op_mix` | `loom.agent_events` における直近の操作の内訳 |
+| `procedure_plane` | `loom.procedure_runs` と、台帳に記録されたプロシージャキー |
+
+
+
+### スモークテスト
+
+デプロイ後に、メモリを1件書き込み、読み出して、一連の動作を確認します。
+
+```bash
+export LOOM_API_KEY=$(docker exec loom-server loom mint-token --subject smoke --org dev --namespaces smoke --roles writer --ttl-days 1)
+curl -s -XPOST http://localhost:7777/v1/memory.set -H "Authorization: Bearer $LOOM_API_KEY" \
+ -H 'Content-Type: application/json' \
+ -d '{"org":"dev","namespace":"smoke","agent":"smoke","memory_key":"k","value":"deploy smoke test"}'
+curl -s -XPOST http://localhost:7777/v1/memory.search -H "Authorization: Bearer $LOOM_API_KEY" \
+ -H 'Content-Type: application/json' \
+ -d '{"org":"dev","namespace":"smoke","agent":"smoke","query":"smoke test"}' | jq '.results[0].content_excerpt'
+```
+
+検索が結果を返さない(abstain する)場合は、`loom.embed.pending` と `/v1/health` の `providers` ブロックを確認してください。ベクトル待ちの行は保存されていますが、まだ検索できません。
+
+
+
+## ワーカーのステータス
+
+バックグラウンド処理は、`server/workers/registry.py`(`_WORKERS`)で宣言された監視付きループとして実行されます。スーパーバイザーは、失敗したパスをバックオフ付きで再試行し、期限(デフォルトは min(4 × interval, 900 s)、下限は 60 s)を超えたパスをキャンセルし、ワーカーが3回連続でパスに失敗すると `: DEGRADED` をログに出力します。各ワーカーは1つの `LOOM_*_ENABLED` フラグで切り替えられます。すべてのワーカー、そのフラグ、デフォルト値、実行間隔は[ワーカーリファレンス](https://github.com/ClickHouse/loom/blob/main/docs/reference/workers.md)に一覧があります。
+
+```bash
+curl -s -H "Authorization: Bearer $ADMIN_TOKEN" http://localhost:7777/v1/admin/workers.status | jq
+```
+
+「何も起きなかった」という報告の多くは、ワーカーが実行されていないことが原因です。たとえば、新しい行の埋め込み、遅延バッチの抽出、コミットのインデックス作成などです。
+
+- `/v1/admin/workers.status` は、無効なものを含め、登録されているすべてのワーカーを、その間隔と最後のパスとともに一覧表示します。このプロセスのレジストリと `loom.worker_status`(30日間保持)をマージするため、Web のみのコンテナでも、workers コンテナが実行したパスを確認できます。ダッシュボードの管理者向け **Health** ビューにも同じ内容が表示されます。
+- `/v1/health?include=workers` → `workers_leader.reason` は、このプロセスがデプロイメントの workers リース(ClickHouse の `workers_supervisor`)を保持しているかどうかを示します。
+- メトリクス:`loom.worker.consecutive_failures{worker}` と `loom.worker.partial_failures{worker}`。
+- `ops.projection_failures.list`(`ORG_ADMIN`)は、失敗して `projection_repair` ワーカーによる処理を待っているセカンダリプロジェクションを一覧表示します。`ops.projection_failures.retry` は1件を再試行します。
+- ワーカーの ClickHouse ステートメントには `log_comment = 'worker.'` が付与されます([クエリの帰属](#logs-traces-and-query-attribution))。
+
+
+
+## アラートの対象
+
+以下のしきい値は出発点です。類似度のベースラインは埋め込みモデルによって変わるため、自分のデプロイメントから設定してください。
+
+| シグナル | アラート条件 | 意味 | 最初の対応 |
+| ------------------------------------------------------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/v1/health` HTTP ステータス | 503 | このプロセスから ClickHouse に到達できない | [トラブルシューティング](https://github.com/ClickHouse/loom/blob/main/docs/operations/troubleshooting.md#every-operation-fails-and-v1health-returns-503) |
+| `/v1/health` `status` | 5 分間 `degraded` | `code_tier_failing` 以外の `error` の問題 | `problems[].fix` を読む |
+| `loom.search.top_similarity` の平均 | 30 分間ベースラインを下回る | 失敗せずに検索品質が低下した(埋め込みモデルの変更、フェイクへのフォールバック) | [トラブルシューティング](https://github.com/ClickHouse/loom/blob/main/docs/operations/troubleshooting.md#search-returns-arbitrary-results-or-extraction-writes-nothing) |
+| `loom.embed.pending` | 15 分間 100 を超える | メモリがまだ検索できない。埋め込みのスループットまたはクォータの問題 | `/v1/health` → `providers` のプロバイダー状態 |
+| 任意の `loom.integrity.*` | 0 を超える | すでに発生した欠陥であり、自然には解消しない([後述](#integrity-invariants)) | 修復の列 |
+| `loom.worker.consecutive_failures` | 3 以上 | ワーカーがループで失敗し続けている | [トラブルシューティング](https://github.com/ClickHouse/loom/blob/main/docs/operations/troubleshooting.md#a-worker-fails-every-pass) |
+| `loom.process.open_fds / loom.process.fd_limit` | 0.5 を超える | ディスクリプタのリーク、または接続が多すぎる | プロセスごとの系列(`loom.pid`) |
+| `loom.host.disk.free_bytes / loom.host.disk.total_bytes` | 0.10 を下回る | `var/` 配下のディスクが埋まりつつある(リポジトリの repack、ログ、blob)。ゼロになるとホスト上のすべての書き込みが失敗する | プロセスごとに 1 系列(`loom.disk.path`) |
+| `loom.langfuse.breaker` | 2 に等しい | Langfuse へのスコア送信が失敗し、スコアが破棄される | `POST /api/public/scores` に対する Langfuse への到達性 |
+| `loom.code.index_lag_commits` | 15 分間、1 パスあたりのコミット予算を超える | コードインデックスがブランチに遅れている | [コードインデックスの運用](https://github.com/ClickHouse/loom/blob/main/docs/operations/code-index-operations.md#failure-model) |
+| `loom.code.tier_lag_seconds` | 10 分間 1800 を超える | コンパイラティアが最近のマージに追いついていない | `deploy/dashboards/code_plane.json` の「code tier lag」アラート。最も遅いティアの通常サイクルより大きく設定する |
+| `loom.code.tier_failing` | 15 分間、いずれかの点がある(ページには `severity="error"`) | `code_tier_failing` の問題が報告するコードインデックスのティアが、`LOOM_CODE_TIER_FAILING_*` のしきい値を超えた | `/v1/health` の `code_tier_failing` の `fix`([ティアが失敗したとき](https://github.com/ClickHouse/loom/blob/main/docs/operations/code-index-operations.md#when-a-tier-fails)) |
+| `ops.health` の `clickhouse_parts`、またはエラー 252 | `fail` | マージが失敗している | [トラブルシューティング](https://github.com/ClickHouse/loom/blob/main/docs/operations/troubleshooting.md#writes-fail-with-too_many_parts-or-merges-are-failing) |
+| `loom.audit.checkpoint_lag_windows` | 増加している | 監査チェックポイントのチェーンが遅れている | `audit_verifier` ワーカーのパス |
+| `loom.trust` ごとの `loom.auth.agents_provisioned{outcome=made}` | コントロールプレーンの通常の割合を超える(10 分間で 50 を目安に開始) | トラストがフリートの成長より速く新しいエージェントを指名している。発行者キーの漏洩、またはコントロールプレーンの暴走 | トラストの `auth.agent_provisioned` 監査行(`audit.list`)を、コントロールプレーンが起動したエージェントと比較する。差異があれば `loom bot disable --name ` を実行し、発行者のキーをローテーションする |
+| `loom.auth.trust_agents_used_ratio` | 0.8 を超える | トラストが `--max-agents` に近づいている(有効なエージェントで数え、解放されたものは枠を戻す) | `outcome=made` もフリートの成長より速く増えている場合は、`outcome=made` の行に従う(トラストを無効化し、キーをローテーションする)。そうでなければ上限を引き上げる:トラストのフラグと大きい `--max-agents` を指定して `loom bot create --replace` を実行する(エージェントのトークンは終了し、それぞれが再度交換する) |
+| `loom.auth.agents_provisioned{outcome=at_cap}` | 10 分間で 0 を超えて増加 | トラストの新しいエージェントが拒否されている | `outcome=made` もフリートの成長より速く増えている場合は、`outcome=made` の行に従う(トラストを無効化し、キーをローテーションする)。そうでなければ上限を引き上げる:トラストのフラグと大きい `--max-agents` を指定して `loom bot create --replace` を実行する(エージェントのトークンは終了し、それぞれが再度交換する) |
+
+HyperDX では空の結果は 0 として扱われるため、最小サンプル数のガードは、行を返さないのではなく、正常範囲内の値を返す必要があります。
+
+何をスケールすべきか(Web レプリカ、プロバイダーのクォータ、ワーカーのコンテナ、または ClickHouse)を示すシグナルは、[障害と復旧](../architecture/failure-and-recovery.md)にあります。
+
+
+
+### パイプラインの SLO
+
+Postgres をオーソリティとする場合、書き込みはコミット時点で応答し、そのメモリ行と検索ドキュメントが ClickHouse に入った時点で検索可能になります([ストレージオーソリティ](../architecture/storage-authority.md#publication))。先行する書き込みがまだ反映されていない検索は、`LOOM_PG_PROJECTION_WAIT_MS`(デフォルト 2000 ms)までそれらを待ち、超過すると 503 `PROJECTION_BEHIND` を返します。
+
+| 目標 | ターゲット | シグナル |
+| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| 読み取りが先行する書き込みを待つ | p99 が `LOOM_PG_PROJECTION_WAIT_MS` の半分未満であり、障害時以外に `deadline` で終わるものがない(op は 503 を返す) | `outcome` ごとの `loom.pg.search_wait_ms` |
+| 書き込みが ClickHouse に入る | p99 が `LOOM_PG_PROJECTION_WAIT_MS` の半分未満。これにより読み取りの待ち時間に残り半分を充てられる | `loom.pg.projection_lag_ms{path="flush"}` |
+| 停止したライターのリースを超えて待つものがない | 最も古い保留が `LOOM_PG_REQUEST_LEASE_SECONDS` の 2 倍と `LOOM_PG_DELIVERY_IDLE_INTERVAL_SECONDS` の合計未満 | `loom.pg.oldest_pending_age_s{source="memory"}` |
+| 障害時以外にラグのエラーがない | 0 | `loom.requests{loom.error_code="PROJECTION_BEHIND" or "PUBLICATION_PENDING"}` |
+| ClickHouse が拒否し続けるものがない | リストア reconcile が保持している間を除き 0 | `loom.pg.backlog{state="parked"}` |
+
+公開前に停止したライターのもとでの検索の最悪の待ち時間は、そのリース(`LOOM_PG_REQUEST_LEASE_SECONDS`)です。待機中の検索は、期限切れの配信を自分で公開します。これはデフォルトの待ち時間より長いため、レイテンシではなく `outcome="deadline"` として現れます。レディネスはこれらのいずれにも依存しません。すべてのレプリカが同じ Postgres を読むため、ラグに基づくレディネスチェックは、すべてのレプリカを一度にローテーションから外してしまいます。
+
+配信ワーカーを実行するすべてのプロセスがデプロイメント全体のバックログをエクスポートし、複数のプロセスが同時に行うことがあるため、バックログのゲージは `sum` ではなく `max` で読んでください。
+
+アラート:
+
+| シグナル | アラート条件 | 意味 | 最初の対応 |
+| ------------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `loom.pg.search_wait_ms{outcome="deadline"}` のレート | 5 分間 0 を超える | 読み取りが期限まで待った。op は 503 `PROJECTION_BEHIND` を返し、レポートはそのまま読み進める | ClickHouse への到達性、次に `loom.pg.backlog` と `pg_delivery` ワーカーのパス |
+| `loom.pg.oldest_pending_age_s{source="memory"}` | 10 分間ターゲットを超える | 配信ワーカーが追いついていない、または ClickHouse が拒否している | `GET /v1/health?include=postgres` → `postgres.backlog`、`pg_delivery` ワーカーのステータス |
+| `loom.pg.backlog{state="parked"}` | 0 を超える | ClickHouse が拒否し続けた配信、またはリストア reconcile が保持している配信(どちらかは `last_error` に示される) | 配信の `last_error`([ストレージオーソリティ](../architecture/storage-authority.md#delivery)) |
+| どのプロセスからも `loom.pg.backlog` の点がない | エクスポート 3 期間にわたって | 読み取りが止まった。バックログの読み取りが失敗している、配信パスが開始されない、または 2 つのパスの開始間隔(パスとその後の間隔)がエクスポート 2 期間を超えている | `pg_delivery` と `knowledge_pg_delivery` ワーカーのログにある `backlog not read` 警告 |
+
+
+
+### 整合性の不変条件
+
+これらのゲージはどれも常に 0 であるべきです。ワーカーのリースを保持するプロセスが 15 分ごとに計算し、キャッシュします。
+
+| メトリクス | 0 以外の値の意味 | 修復 |
+| --------------------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------- |
+| `loom.integrity.divergent_entities` | あるメモリについて、`loom.memory` と `loom.memory_embeddings` でエンティティが異なる | 書き込みパスを調査する |
+| `loom.integrity.orphan_vectors` | メモリ行が存在しない埋め込みベクトル | `orphan_vector_reconcile` worker |
+| `loom.integrity.orphan_entity_vectors` | メモリ行が存在しないエンティティベクトル | `orphan_vector_reconcile` worker |
+| `loom.integrity.orphan_graph_namespaces` | エンティティエッジを持つが、有効なメモリもナレッジもない名前空間 | `loom erasure-re-verify --orphan-graph --erase` |
+| `loom.integrity.live_ns_unregistered`, `live_rows_unregistered` | `loom.namespaces` の行がない名前空間内の有効なメモリ | 名前空間を登録するか、`loom namespaces-adopt` を実行 |
+| `loom.integrity.dim0_with_vector` | ベクトルを持つが `embedding_dim = 0` のため、検索で見えない行 | `loom integrity-repair --apply` |
+| `loom.integrity.tombstone_status_drift` | `tombstoned_at` が設定されているのに、ステータスが別の値になっている行 | `loom integrity-repair` が一覧表示 |
+| `loom.integrity.active_past_valid_to` | 自身の `valid_to` を過ぎても active のままの行 | `loom integrity-repair` が一覧表示 |
+| `loom.integrity.high_with_embedding` | 有効な埋め込み行が残っている高機密度の行 | `loom sensitivity-sweep --apply` |
+
+修復コマンドについては、[メンテナンス](https://github.com/ClickHouse/loom/blob/main/docs/operations/maintenance.md#backfills-and-repairs)を参照してください。
+
+
+
+## メトリクス
+
+Loom は `LOOM_OTEL_METRICS_EXPORT_INTERVAL_S` 秒ごと(デフォルトは 60)に OpenTelemetry メトリクスをエクスポートします。`LOOM_OTEL_EXPORTER=ch`(OTLP エンドポイントが設定されていない場合のデフォルト)では、同じ ClickHouse サービス上の `default.otel_metrics_sum`、`default.otel_metrics_histogram`、`default.otel_metrics_gauge` に直接書き込まれます(`LOOM_CLICKSTACK_DATABASE` が設定されている場合は、ここでも以下でもそのデータベースに書き込まれます)。これらは ClickStack/HyperDX が読み取るテーブルです。代わりにコレクターへ送信するには、`LOOM_OTEL_EXPORTER_OTLP_ENDPOINT` を設定します。カウンターとヒストグラムは、`LOOM_OTEL_METRICS_DELTA_TEMPORALITY=true` でない限り累積値です。エクスポーターの状態は起動ログで確認できます。
+
+```text
+OTel metrics initialized — emitting every 60s (cumulative temporality, gauge heartbeat …s) to default.otel_metrics_{sum,histogram,gauge}
+```
+
+ラベルは限定された集合(オペレーション、名前空間、上限のある enum)から付けられます。キー、ユーザー ID、セッション ID、クエリテキストがラベルになることはありません(`tests/unit/test_domain_metrics.py` がこれを検証しています)。リクエストとコスト、検索品質、メモリ書き込み、バックログ、整合性、コードインデックスに分類した全メトリクスの一覧は、[テレメトリ](https://github.com/ClickHouse/loom/blob/main/docs/features/observability/telemetry.md)を参照してください。
+
+クエリの例:
+
+```sql
+-- mean top similarity per namespace, last hour
+SELECT Attributes['loom.namespace'] AS ns,
+ round(anyLast(Sum) / greatest(anyLast(Count), 1), 3) AS mean_top_similarity
+FROM default.otel_metrics_histogram
+WHERE MetricName = 'loom.search.top_similarity' AND TimeUnix > now() - INTERVAL 1 HOUR
+GROUP BY ns;
+
+-- every gauge's latest value
+SELECT MetricName, anyLast(Value) AS latest
+FROM default.otel_metrics_gauge
+WHERE TimeUnix > now() - INTERVAL 5 MINUTE
+GROUP BY MetricName ORDER BY MetricName;
+```
+
+最初のクエリは累積ヒストグラムを読み取るため、系列ごとの全期間の平均になります。ウィンドウ単位の平均を求めるには、各ポイントを同じ系列の直前のポイントとの差分にします(`deploy/hyperdx_dashboards.md` の「The cumulative-counter correction」にある補正を参照)。
+
+
+
+## ダッシュボード
+
+[`deploy/hyperdx_dashboards.md`](https://github.com/ClickHouse/loom/blob/main/deploy/hyperdx_dashboards.md) は、ClickStack と HyperDX のセットアップガイドであり、SQL パネルのクックブックです。ClickStack との連携そのものについては [ClickStack](https://github.com/ClickHouse/loom/blob/main/docs/features/integrations/clickstack.md) を参照してください。
+
+- **コレクターは不要です。** Loom は OTel の行を自身の ClickHouse の `default.otel_*` に直接書き込みます。そのため、ホスト型の ClickStack では、ソースを既存のテーブルに向けるだけで済みます(`deploy/clickstack_sources.sh` がその設定をスクリプト化しています)。HyperDX のインストールによってテーブルが作成されていない場合は、`schemas/otel/clickstack_otel_tables.sql` を一度だけ手動で適用してください。すべての文は `IF NOT EXISTS` です。
+- **パネルが避けている 2 つの落とし穴。** FastAPI のインストルメンテーションは、親スパンと同じ名前の ASGI 子スパン(`POST /v1/memory.get http send`)を出力するため、スパン名によるフィルタの件数が約 3 倍に膨らみます。`loom.*` 属性を持つのは親スパンだけなので、`mapContains(SpanAttributes, 'loom.operation')` でフィルタしてください。また、累積メトリクスにはシリーズごとの差分が必要です。ウィンドウ内で `sum(Value)` を取ると、累積値の合計になってしまいます。
+- **コードインデックスのボード。** [`deploy/dashboards/code_plane.json`](https://github.com/ClickHouse/loom/blob/main/deploy/dashboards/code_plane.json) は、「Loom — Code Plane」ダッシュボードの信頼できる唯一の情報源です。各タイルのソースと SQL、および `alert` ブロック(しきい値と理由)を持つタイルが記載されています。次回の再構築で同じ内容になるよう、UI でタイルを編集するのではなく、この JSON からプロビジョニングしてください。
+- パネルが空のままの場合は、`docker logs loom-server 2>&1 | grep -i otel` を確認してください。スパンは数秒ごとにフラッシュされ、メトリクスはエクスポート間隔ごとに 1 回フラッシュされます。テーブルが存在しない場合は、`default.otel_traces does not exist … Self-disabling span export` と表示されます。
+
+
+
+## ログ、トレース、クエリの帰属
+
+- **ログ。** `docker logs loom-server` と `docker logs loom-workers` を使います。ログパイプラインには `LOOM_LOG_FORMAT=json` を、出力の詳細度には `LOOM_LOG_LEVEL` を指定します。起動ログには、解決されたプロバイダーと適用された各マイグレーションが記録されます。スーパーバイザーは、失敗した各パスと `DEGRADED` の行をログに出力します。
+- **台帳。** `loom.agent_events` には、操作ごとに 1 行が記録されます。列は `operation`、ID 列、`request_id`、`trace_id`、`latency_ms`、`success`、`error_code`、トークン、`upstream_cost_usd`、`model`、`consumer`、`traffic_class`、`build_commit`、`instance`、`instance_label` です。`loom.audit_log` は、誰が何を変更したかを行ごとのコンテンツハッシュ付きで記録します([監査](https://github.com/ClickHouse/loom/blob/main/docs/features/observability/audit.md))。
+- **トレース。** スパンは `default.otel_traces`(または OTLP エンドポイント)に送られ、`loom.org`、`loom.namespace`、`loom.agent`、`loom.operation`、`loom.request_id`、`enduser.id` のタグが付きます。Langfuse を設定している場合は、スパンツリーも Langfuse に送られます([Langfuse](https://github.com/ClickHouse/loom/blob/main/docs/features/integrations/langfuse.md))。すべての HTTP レスポンスには `X-Request-Id`(クライアントが 1〜64 文字の英数字、`.`、`_`、`-` で送信した場合はその値)と `X-Trace-Id` が付きます。
+- **すべての ClickHouse クエリは** `log_comment` 設定で帰属が示されます。
+
+| `log_comment` | 発行元 |
+| ------------------------------ | ----------------------------------------------------------------- |
+| ` ` | リクエスト(HTTP または MCP) |
+| `worker.` | ワーカーのパス |
+| `cli.[.]` | `loom` コマンド(`loom serve` を除く) |
+| `untagged:.` | それ以外。バックグラウンドループは `set_query_tag(...)` を呼び出してください |
+
+`LOOM_CH_LOG_COMMENT_STATEMENT_DIGEST=true` を指定すると、タグの後ろにステートメントダイジェストが付くため、末尾に `%` を付けて照合します。
+
+```sql
+-- which operations cost ClickHouse the most in the last hour
+SELECT splitByChar(' ', log_comment)[1] AS source,
+ count() AS queries, sum(read_bytes) AS bytes, sum(query_duration_ms) AS ms
+FROM system.query_log
+WHERE type = 'QueryFinish' AND event_time > now() - INTERVAL 1 HOUR AND log_comment != ''
+GROUP BY source ORDER BY ms DESC LIMIT 20;
+
+-- one request end to end
+SELECT * FROM loom.agent_events WHERE request_id = '';
+```
+
+`LOOM_INSTANCE_LABEL`(compose ファイル以外では必須)を設定すると、どちらのクエリでも、ノート PC やテストサーバーの行をデプロイメント自身の行から分離できます。カラースワップの後、`loom deploy-delta` はスワップの前後それぞれの台帳とステートメントの形を比較します。前後それぞれ `--window-min` 分(デフォルトは 60)を読み取るため、そのウィンドウが過ぎてから実行してください。また、自分の読み戻しトラフィックは含めないでください。スワップ直後のリクエストはキャッシュが冷えた状態で実行されるため、スワップ後側のレイテンシが大きく見えます。
+
+
+
+## レート制限とトラフィッククラス
+
+すべてのリクエストは、2 つのトークンバケットから消費されます。1 つは名前空間ごと、もう 1 つは組織ごと(名前空間のサイズの 3 倍)で、いずれも操作クラスをキーとします。上限を超えると、レスポンスは 429 `RATE_LIMITED` となり、`Retry-After` ヘッダーと `X-RateLimit-*` ヘッダーが付きます。
+
+| クラス | 操作 | 名前空間ごとのバースト / 持続レート |
+| ------------------ | ------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
+| `memory` | `memory.*`、`conversation.*`(完全一致キーによる読み取りと `memory.import` を除く) | 100 / 17 毎秒 |
+| `memory.read` | 完全一致キーによる読み取り:`memory.get`、`memory.bulk_get`、`memory.history`、`working_memory.get`、… | 300 / 50 毎秒 |
+| `memory.import` | `memory.import` | 10 / 2 毎秒 |
+| `knowledge.search` | `knowledge.search` | 20 / 3 毎秒 |
+| `knowledge.query` | `knowledge.query` | 20 / 3 毎秒 |
+| `knowledge.read` | `knowledge.inspect` を除く、その他の `read_only` な `knowledge.*` 操作:`knowledge.get`、`knowledge.list`、… | 50 / 10 毎秒 |
+| `knowledge.add` | その他すべての `knowledge.*` 操作(`knowledge.inspect`、`knowledge.synthesize`、`knowledge.dedup_list` を含む) | 10 / 2 毎秒 |
+| `code` | `code.*`(`memory` から消費される `code.outcome` を除く) | 60 / 10 毎秒 |
+| `insights.query` | `insights.query` | 20 / 3 毎秒 |
+| `assistant.ask` | `assistant.ask` とアシスタントのチャットルート | 10 / 1 毎秒 |
+| `default` | それ以外のすべて | 50 / 10 毎秒 |
+
+リクエストは `production`、`interactive`、`bench` のいずれかに分類されます。分類は、`loom mint-token --traffic-class` で発行したトークンのクレームが優先され、なければ名前空間の登録内容、それもなければリクエストのヒントによって決まります。どれが適用されたかは、レスポンスヘッダー `X-Loom-Traffic-Class` で確認できます。bench トラフィックには、より小さな専用バケット(`LOOM_RATELIMIT_CLASS_FRACTIONS`)と、より低い ClickHouse の優先度が割り当てられるため、ベンチマークが production の予算を消費することはありません。制限はレプリカごとに適用されます。`LOOM_REPLICA_COUNT` については[障害と復旧](../architecture/failure-and-recovery.md)を参照してください。`POST /v1/admin/ratelimit.set` に `{namespace|org, op_class, capacity, rate}`(または `clear: true`)を渡すと、バケットを上書きできます。上書きは `loom.runtime_overrides` に保存され、すべてのプロセスが `LOOM_RUNTIME_OVERRIDES_REFRESH_SECONDS`(デフォルトは 10)以内に反映します。再起動後も維持されます。`POST /v1/admin/budget.set` は、レイテンシバジェットの上書きを同じ方法で保存します。バケットの補充そのものは、引き続きホストごとに行われます。
+
+
+
+## 関連ドキュメント
+
+- [トラブルシューティング](https://github.com/ClickHouse/loom/blob/main/docs/operations/troubleshooting.md):これらのシグナルで検知できる事象を、症状から引ける形でまとめたランブック
+- [テレメトリ](https://github.com/ClickHouse/loom/blob/main/docs/features/observability/telemetry.md):メトリクスとスパンの一覧
+- [コストと使用量](https://github.com/ClickHouse/loom/blob/main/docs/features/observability/cost-and-usage.md)と[監査](https://github.com/ClickHouse/loom/blob/main/docs/features/observability/audit.md)
diff --git a/i18n/.pending/ja/docs/reference/cli.md b/i18n/.pending/ja/docs/reference/cli.md
new file mode 100644
index 0000000000..4cd9ff338e
--- /dev/null
+++ b/i18n/.pending/ja/docs/reference/cli.md
@@ -0,0 +1,302 @@
+
+> このページは[英語の原文](https://github.com/ClickHouse/loom/blob/main/docs/reference/cli.md)の機械翻訳です。内容は英語の原文が優先されます。
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/reference/cli.md), which is authoritative.
+
+
+
+# CLI リファレンス
+
+`loom` は、Loom のデプロイメントを実行、保守、接続するための唯一のコマンドラインのエントリポイントです。サーバーパッケージの `loom` コンソールスクリプト(`pyproject.toml`、`[project.scripts]` → `server.cli:main`)であり、パーサーツリーは `server/cli/app.py` と、`server/cli/` 配下のコマンドファミリーごとのモジュールにあります。このページ末尾の表は、そのツリーから生成されています。
+
+
+
+## 実行場所
+
+| 場所 | 方法 | 用途 |
+| -------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
+| サーバーイメージ内 | `docker exec loom-server loom `(web コンテナ) | デプロイ自体の設定に対して実行するオペレーターコマンド:`doctor`、`migrate`、`mint-token`、`reembed`。 |
+| 分割デプロイの workers コンテナ内 | `docker exec loom-workers loom ` | web ティアから切り離したい長時間のメンテナンス:`code backfill`、`code stats`。 |
+| チェックアウト | リポジトリのルートで `pip install -e .` を実行し、`loom ` | `up`、`install`、`demo`、およびローカルスタックに対する開発。 |
+
+コンテナ内では、設定はコンテナの環境変数です。チェックアウトから実行する場合、`loom` はまず作業ディレクトリの `.env`(または `LOOM_ENV_FILE` が指すファイル。空にすると読み込みません)を、compose の `env_file` と同じ方法で環境に読み込みます。シェルがすでにエクスポートしている変数は上書きしません。これはプロバイダーキーで重要です。キーなしでチェックアウトから埋め込みコマンドを実行すると、フェイクの埋め込みにフォールバックし、使えないベクトルを書き込んでしまいます。
+
+コマンドは 2 種類に分かれます。
+
+- **オペレーターコマンド**は `server/settings/` を読み、ClickHouse と直接通信します(`migrate`、`reembed`、`code backfill`、`revoke-token`、各種のバックフィルと修復)。デプロイの認証情報で実行されるため、その認証情報がある場所で実行してください。
+- **クライアントコマンド**は URL とトークンを使い、稼働中のサーバーと HTTP で通信します(`install`、`init`、`demo`、`memory-search`、`ingest-transcript`、`export-okf`、`import-okf`)。`--server-url`(`demo` では `--base-url`)と、`init` を除いて `--token` を受け取ります。解決順はプラグインフックと同じです。URL は `LOOM_BASE_URL`、次に `~/.loom/config.json` の `url`、いずれもなければ `http://localhost:7777` です。トークンは `LOOM_API_KEY`、次に `~/.loom/config.json` の `token`、次に `~/.loom/token`(`LOOM_API_KEY_FILE` で変更可能)です。`LOOM_CONFIG_FILE` は設定ファイルの場所を変更します。エージェント(ワークロードトークンを伴う `LOOM_CLIENT_ID`)の場合は `--token` か `LOOM_API_KEY` だけを使い、保存済みのトークンは使いません。どちらもなければ拒否します(終了コード 2)。`loom install` は `--token` の指定にかかわらず拒否し、`loom init` はサインアップを行う前に拒否します。`loom call` はワークロードトークンの交換を自分で行います。
+
+`loom mint-token` に必要なのは `LOOM_JWT_SECRET` だけです。トークンをローカルで署名します。
+
+**セッションコマンド**(`login`、`logout`、`whoami`、`call`、`token`)は Python SDK 独自のもの(`loom.cli`。SDK だけをインストールした場合は `python -m loom …`)なので、これらを使うには `loom` に `pip install clickhouse-loom` が必要です。`loom login [--server URL] [--profile NAME] [--no-browser] [--org ORG [--wait S]]` はワンタイムコードでサインインします。`--org` を付けると、ルーターの参照が示すその組織の[セル](https://github.com/ClickHouse/loom/blob/main/docs/architecture/cells.md)にサインインします。`loom call [key=text|key:=json …] [--data JSON] [--org] [--namespace]` は、そのセッションで任意のオペレーションやルートにアクセスします。`loom token create|list|revoke` は、CI やエージェント向けの自分のトークンを作成、一覧表示、失効します。詳しくは[ダッシュボードなしで Loom を使う](https://github.com/ClickHouse/loom/blob/main/docs/guides/without-the-dashboard.md)を参照してください。
+
+
+
+## 規約
+
+**書き換えはデフォルトでドライラン。** 保存済みの行を書き換えるコマンドは、`--apply` を指定しない限り、書き込む内容を報告するだけです。`--dry-run` も指定でき、これはデフォルトの動作を明示するものです。この 2 つのフラグは同時に指定できません(`server/cli/_apply.py`、`add_apply_flags`)。ドライランが成功すると、stderr に `dry run: nothing was written; re-run with --apply to write` が出力されて終わります。そのため、コマンドの `--json` 出力だけが stdout に残ります。コマンドによっては同じ考え方を独自のフラグで表します(`loom entity-edges-invalidate-junk` は `--dry-run`(デフォルト)または `--apply` を取ります。`loom reembed --dry-run` は書き込まずに行数を数えます)。各コマンドのフラグは下の表に一覧があります。
+
+**すべての書き込みはプリンシパルを明示します。** コマンドによる書き込みには、アクター `process:cli:` が記録されます(`server/memory/domain/provenance.py`、`cli_actor`)。このため、来歴と監査ログから、どのコマンドがその行を書き込んだかが分かります。
+
+**すべてのクエリには帰属が付きます。** コマンドが発行する ClickHouse のクエリには `log_comment` タグ `cli.[.]` が付きます。コマンドが独自の `--traffic-class` を取らない限り、読み取りは `background` トラフィッククラスで実行されます。`loom serve` は例外です。これはサーバー自体であり、そのリクエストとワーカーの処理は自分でタグを付けます。
+
+**`--json`** を提供するコマンドでは、機械可読な結果を 1 つだけ stdout に出力し、人間向けのレポートは stderr に出力します。
+
+
+
+## よく使うコマンド
+
+
+
+### デプロイの実行と確認
+
+```bash
+loom up # from a checkout: create .env, boot Loom, its extractor and ClickHouse, print how to connect
+docker exec loom-server loom doctor # pre-boot checks + the /v1/health problem list, each with its fix
+docker exec loom-server loom doctor --json # the same, machine-readable
+loom doctor --client # also examine this machine as a coding-agent client
+docker exec loom-server loom migrate --status # applied and pending migrations
+docker exec loom-server loom migrate --dry-run --strict # what a boot would apply; exit 1 on ledger drift
+```
+
+`loom up` は `/v1/health` が応答するまで待機し(上限は `--timeout`、デフォルトは 300 秒)、認証が有効な場合は writer トークンを発行して、ダッシュボードの URL と最初の呼び出し用スニペットを表示します。`--no-build` はキャッシュ済みのイメージを再利用します。すでにヘルスチェックに応答しているスタックは、`--rebuild` を指定しない限りそのまま残されます。`loom doctor` は、いずれかのチェックが失敗すると終了コード 1 で終了します。`loom serve` はローカル用途で uvicorn 上にコントロールプレーンを起動します(イメージでは `scripts/serve.sh` 経由で起動します)。マイグレーションとアップグレードについては[アップグレード](https://github.com/ClickHouse/loom/blob/main/docs/operations/upgrades.md)、ヘルスチェックについては[モニタリング](https://github.com/ClickHouse/loom/blob/main/docs/operations/monitoring.md)を参照してください。
+
+
+
+### トークン
+
+```bash
+# A writer token for one namespace, valid 30 days, printed on stdout
+docker exec loom-server loom mint-token --subject my-bot --org dev \
+ --namespaces local --roles writer --ttl-days 30
+
+# A scoped token: per-namespace roles, in read-priority order
+loom mint-token --subject triage --org acme \
+ --namespace-role priv=admin --namespace-role pub=viewer --json
+
+# Retire one token, or every token of a subject issued before an instant
+docker exec loom-server loom revoke-token --jti --reason "leaked"
+docker exec loom-server loom revoke-token --subject my-bot --issued-before 2030-01-01T00:00:00Z
+```
+
+恒久的な失効には、有効期限を設定することも、それ以前に失効させたトークンを復元するよう範囲を狭めることもできません。既存のカットオフ以降の時刻、または恒久的な失効時刻にトークンのクロックスキュー許容値を加えた時刻のいずれかを、カットオフとして選んでください。
+
+`--save` を指定すると、トークンを表示する代わりに `~/.loom/token`(または指定したパス)に書き込みます。`--ttl-days` を指定しない場合、トークンに有効期限はなく、`loom revoke-token` でのみ失効させられます。`--read-scope own_user` は、読み取りを各リクエストが指定する `user_id` に限定します。`--consumer NAME` は[コンシューマータグ](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#the-consumer-tag)を認証情報に紐づけます。詳しくは[トークンとグラント](https://github.com/ClickHouse/loom/blob/main/docs/guides/tokens-and-grants.md)を参照してください。
+
+
+
+### クライアントの接続
+
+```bash
+loom install --client cursor --token "$LOOM_API_KEY" --server-url https://loom.example.com
+loom install --client claude-code --toolset coding+tracker --dry-run
+loom init --agent triage-bot --server-url https://loom.example.com # self-signup: a namespace + token
+```
+
+`loom install` は、クライアントの設定に MCP サーバーのエントリを書き込みます(または `claude mcp add` / `codex mcp add` を実行します)。`--client` を省略すると、見つかったすべての対応クライアントを設定します。詳しくは [MCP クライアント](https://github.com/ClickHouse/loom/blob/main/docs/features/integrations/mcp-clients.md)を参照してください。`loom init` は、トークンを `~/.loom/token` に、サーバー、組織、名前空間を `~/.loom/config.json` に保存します。このファイルは、クライアントのコマンドとプラグインのフックが読み取ります。
+
+
+
+### エンベッダー変更後の再埋め込み
+
+```bash
+docker exec loom-server loom reembed --dry-run # count rows whose embedding_model is not the configured one
+docker exec loom-server loom reembed --namespace support
+docker exec loom-server loom reembed --delete-old # re-embed, then delete the off-model rows
+```
+
+Loom が自動的に再埋め込みを行うことはありません。`LOOM_EMBEDDING_MODEL` を変更したら、`loom reembed` を実行してください。保存済みのコンテンツからベクトルを再生成し、それ以外のカラムはすべて保持します。`--in-database ` は、`aiEmbed`(ClickHouse 26.7 以降)を使って ClickHouse 内で埋め込みを行い、テーブルごとに 1 つの `INSERT … SELECT` を実行します。顧客ヘッダーまたは ID ヘッダーが設定されている間、および推論ゲートウェイが必須の間は拒否されます。`--resume` は、前回の実行の `resume:` 行が示す行の続きから再開します。詳しくは[メンテナンス](https://github.com/ClickHouse/loom/blob/main/docs/operations/maintenance.md)を参照してください。
+
+
+
+### リポジトリのインデックス作成
+
+```bash
+docker exec loom-workers loom code init --org acme --namespace code-myrepo
+docker exec loom-workers loom code backfill --org acme --namespace code-myrepo --embed
+docker exec loom-workers loom code stats --org acme --namespace code-myrepo
+```
+
+`code backfill` は再開可能です。`--phase index` はパース、チャンク分割、シンボルとエッジの導出を行い、`--phase embed` は未処理のベクトルを埋め、`--embed` は両方を 1 回の実行で行います。フェイクエンベッダーでの埋め込みは、`--allow-fake-embedder`(開発専用)を指定しない限り拒否されます。`--org` と `--namespace` のデフォルトは、それぞれ `LOOM_CODE_ORG` と `LOOM_CODE_NAMESPACE` です。完全な手順、コンパイラティア、PR 履歴のバックフィルについては、[コードインデックスの運用](https://github.com/ClickHouse/loom/blob/main/docs/operations/code-index-operations.md)を参照してください。
+
+
+
+### エクスポートとインポート
+
+```bash
+loom export-okf --namespace support --out ./support-okf # a namespace as a Markdown bundle
+loom okf-lint ./support-okf --strict # offline lint; exit 2 on a critical finding or, with --strict, a warning
+loom import-okf ./support-okf --namespace support-copy
+loom export-actions --format cedar -o loom.cedarschema # the registry as a policy schema
+```
+
+`export-okf` は、`sensitivity=high` の行、および機密度が不明な行を、`--include-high` を指定しない限り出力から除外します。ミラーリポジトリは、名前空間のグラントよりも広い読者に公開されるためです。そのような行にリンクされた raw チャンクとダイジェスト、および high の形式(認証情報、カード番号、SSN、記載された PIN)を含む raw テキストも、その行と同様に除外されます。`--include-high` を指定するとこれらが出力に含まれ、サーバーは出力された各項目を監査します。詳しくは [OKF](https://github.com/ClickHouse/loom/blob/main/docs/features/integrations/okf.md) と[アクションスキーマのエクスポート](https://github.com/ClickHouse/loom/blob/main/docs/reference/mcp.md#exporting-the-action-schema)を参照してください。
+
+
+
+### 診断と修復
+
+`loom report` は、バグ報告フォームの Environment フィールドを `loom doctor` の出力とともに表示します。`--open` を指定すると、バージョン情報を入力済みのフォームを開きます。`loom drops` は、名前空間のメモリ取り込みドロップ台帳を表示します。`loom erasure-re-verify` は、失敗した消去サーガを再検証します。バックフィルと修復のコマンド(`integrity-repair`、`reconcile-status`、`repair-value-bytes`、`entity-edges-invalidate-junk`、`rechunk`、`lexical-stats-rebuild` など)と、それぞれを実行すべきタイミングについては、[メンテナンス](https://github.com/ClickHouse/loom/blob/main/docs/operations/maintenance.md)と[トラブルシューティング](https://github.com/ClickHouse/loom/blob/main/docs/operations/troubleshooting.md)を参照してください。
+
+
+
+## 表の読み方
+
+各行は 1 つのコマンドまたはサブコマンドを表し、完全な呼び出し形式、ヘルプテキストの最初の一文、引数を示します。位置引数は `` の形式で、オプションは長い形式で表示しています。`loom --help` を実行すると、ヘルプの全文、デフォルト値、選択肢を表示できます。ジェネレータ(`scripts/codegen/docs_reference.py`、`render_cli`)は、コミット済みのパーサースナップショット `tests/unit/snapshots/cli_tree.json` を読み込みます。`tests/unit/test_cli_surface_snapshot.py` は、このスナップショットと `tests/unit/snapshots/cli_help.json` を実際のパーサーと一致させ続けます。そのため、新しいフラグを追加すると、両方のスナップショットとこのページを再生成するまで CI が失敗します。
+
+```bash
+LOOM_UPDATE_CLI_SNAPSHOT=1 python -m pytest tests/unit/test_cli_surface_snapshot.py
+python scripts/codegen/docs_reference.py
+```
+
+
+
+## コマンド
+
+
+
+
+
+| コマンド | 概要 | 引数とフラグ |
+| --- | --- | --- |
+| `loom code` | コードインテリジェンスプレーンの操作。 | |
+| `loom code init` | bare クローンとシード状態を作成する。 | `--org`, `--namespace` |
+| `loom code backfill` | ツリー全体のインデックス作成(再開可能)。 | `--org`, `--namespace`, `--phase`, `--embed`, `--include-poisoned`, `--allow-fake-embedder`, `--no-fetch`, `--limit`, `--commit`, `--paths-file`, `--concurrency`, `--edges-second-pass`, `--no-edges-second-pass`, `--dialect-folder-pass`, `--embedding-model-suffix`, `--context-callees`, `--callers-from` |
+| `loom code reconcile` | 内容に基づく陳腐化チェック。チャンクがブランチ先頭での最終変更より古いパスを検出する。--heal を指定すると再取り込みする(ウォーターマークは変更しない)。 | `--org`, `--namespace`, `--heal`, `--limit`, `--max-commits`, `--no-fetch`, `--show` |
+| `loom code compact` | コードベクターテーブルのキーあたりの物理コピー数が --min-ratio に達したときに OPTIMIZE ... FINAL を実行し、マージの完了を待つ。 | `--table`, `--min-ratio`, `--apply`, `--dry-run`, `--timeout-s` |
+| `loom code reembed` | 名前空間の有効なチャンクを、2 つ目の埋め込みモデルのラベルで書き込む。データベース内で完結し、再開可能で、チェックアウトは不要。 | `--org`, `--namespace`, `--embedding-model`, `--source-model`, `--prefix`, `--batch` |
+| `loom code vector-twin` | チャンクベクターの Matryoshka プレフィックス版を ClickHouse 内で名前空間ごとに作成する。再埋め込みは不要で、再開可能。 | `--org`, `--namespace`, `--embedding-model`, `--all-namespaces` |
+| `loom code crossref` | SQL/シェルのテストから実装している C++ への参照パス(code_test_map の method=content_reference を書き込む。冪等)。 | `--org`, `--namespace` |
+| `loom code coverage-import` | 設定されたソースの最新のテスト単位の行カバレッジ実行結果をインポートする(code_test_map の method=coverage と code_coverage_files を書き込む)。 | `--org`, `--namespace`, `--dry-run` |
+| `loom code export-pairs` | 実トラフィック(トレースと結果の結合)から、埋め込みモデルやリランカーのファインチューニング用に(クエリ → 操作対象ユニット、ハードネガティブ)の検索ペアをエクスポートする。 | `--org`, `--namespace`, `--days`, `--out` |
+| `loom code backfill-prs` | GitHub からマージ済み PR の履歴を取り込む。 | `--org`, `--namespace`, `--months`, `--max-prs` |
+| `loom code repack` | 最近マージされた PR のコンテキストパックを、現在のパック形式で再生成する。 | `--org`, `--namespace`, `--days`, `--limit`, `--dry-run` |
+| `loom code describe` | PageRank 上位のチャンクに対し、LLM でコンテキスト付きの一行説明を作成する。 | `--org`, `--namespace`, `--top-pct`, `--limit`, `--suffix`, `--concurrency` |
+| `loom code answers-purge` | キャッシュされた code.ask の回答を墓石化する(合成モデルのアップグレード後、古い低性能モデルの回答は、引用ファイルが変更されたときにしか無効化されないため、そのままでは永久に返され続ける)。 | `--llm-model`, `--all`, `--apply`, `--dry-run`, `--org`, `--namespace` |
+| `loom code scip-full` | コンパイラティアの完全な再インデックスを手動で実行する(code_scip_full ワーカーはデフォルトで毎週実行する。マージごとの差分で TU 上限により劣化した部分やドリフトを修復する)。 | `--checkout`, `--jobs`, `--keep-delta`, `--apply-delta`, `--org`, `--namespace` |
+| `loom code scip-lock-path` | このホスト上のエントリのコンパイラティア用ロックファイルを表示する。 | `--org`, `--namespace` |
+| `loom code entry-lock` | エントリのコンパイラティアロック(このホストのファイルとデプロイメントのリース)を保持してコマンドを実行する。別のパスがロックを保持している場合は終了コード 75、実行中にリースを失った場合は 3(コマンドは停止される)。 | `--org`, `--namespace`, `--tier`, `` |
+| `loom code scip-delta` | コンパイラティアの差分パスを 1 回手動で実行する(code_scip_delta ワーカーと同じコード)。設定済みの各リポジトリで git_head と scip_commit を比較し、変更された TU に対して scip-clang を実行して適用する。 | |
+| `loom code entries` | 設定済みのリポジトリごとに 1 行を表示する:org namespace checkout lock-file(ロックパスは解決済み。手動実行では `loom code entry-lock` 経由でロックを取得する)。 | |
+| `loom code warm` | 質問リスト(1 行 1 質問、または 'question' フィールドを持つ JSONL)から code.ask の回答キャッシュをあらかじめ作成する。 | ``, `--org`, `--namespace` |
+| `loom code scip-retry` | 失敗した SCIP バッチを pending に戻す。 | `--org`, `--namespace`, `` |
+| `loom code backfill-reviews` | code_pr_history にあるマージ済み PR のうち、インラインレビューコメントがまだ保存されていないものを取り込む(新しい順、PR ごとに GitHub へ 1 リクエスト)。 | `--org`, `--namespace`, `--prs` |
+| `loom code backfill-assignees` | すでに保存されているマージ済み PR について code_pr_history.assignees(リポジトリがレビューを割り当てた相手)を埋める。クローズ済みの新しい PR から 1 リクエストあたり 100 件ずつたどる。 | `--org`, `--namespace`, `--pages` |
+| `loom code backfill-items` | 指定日以降に更新された code_gh_items(Issue と PR、状態を問わない)を、更新の古い順に 1 リクエストあたり 100 件ずつ埋める。gh_items_cursor を進める。 | `--org`, `--namespace`, `--since`, `--pages` |
+| `loom code stats` | ウォーターマークと現在の行数。 | `--org`, `--namespace` |
+| `loom code export-matrix` | マージ済み PR の同時変更から保守マトリクスを作成する:「このファイルを変更するとき、通常これらも変更される」を根拠付きで、指示ファイル(AGENTS.md / copilot-instructions.md)向けの Markdown として出力する。 | `--org`, `--namespace`, `--prs`, `--min-together`, `--min-conf`, `--max-partners`, `--max-rows`, `--out`, `--json` |
+| `loom code lint-instructions` | クローンの先頭でパスやシンボルの参照がもう解決できないエージェント向け指示ファイル(CLAUDE.md、AGENTS.md、copilot-instructions、.claude/.md、skills)を検出する。 | `--org`, `--namespace`, `--file`, `--glob`, `--symbols`, `--all`, `--json`, `--fail-on-stale` |
+| `loom decisions` | ドキュメントから抽出した決定記録。 | |
+| `loom decisions extract` | 1 つのナレッジドキュメントから決定記録を抽出する。モデルはドキュメント全体を読む(LOOM_MEMORY_DECISION_EXTRACT_WINDOW_CHARS を超える場合はセクション単位のウィンドウで読む。画像のみの見出しは… | `--org`, `--namespace`, `--source-uri`, `--repo`, `--into`, `--max-per-section`, `--window-chars`, `--apply`, `--dry-run` |
+| `loom knowledge` | ナレッジドキュメントとそのソース。 | |
+| `loom knowledge sync` | リポジトリ名前空間のドキュメントソースに対して同期パスを今すぐ 1 回実行する。各ソースの変更ファイルを一覧し(--full ですべてのファイル)、変更されたものをドキュメントとして書き込み、完全な一覧に存在しなくなったものを廃止する… | `--org`, `--namespace`, `--source`, `--full` |
+| `loom knowledge source` | 実行中のサーバー経由で操作する、名前空間のドキュメントソース。 | |
+| `loom knowledge source list` | 名前空間のソース、アイテム、同期状態を一覧表示する。 | `--namespace`, `--org`, `--server-url`, `--token` |
+| `loom knowledge source add` | リンクまたはアイテムからソースを登録する。何かを保存する前に認証情報でプローブする(knowledge.source.add)。 | `--namespace`, `--org`, `--server-url`, `--token`, `--name`, `--kind`, `--link`, `--item-json`, `--include`, `--credential-file`, `--dry-run` |
+| `loom knowledge source update` | ソースのアイテムを追加・削除したり、ファイル種別を変更したりする。追加したアイテムは保存済みの認証情報でプローブされる(knowledge.source.update)。 | `--namespace`, `--org`, `--server-url`, `--token`, `--name`, `--link`, `--item-json`, `--include`, `--remove-link`, `--remove-item-json` |
+| `loom knowledge migrate-originals` | ドキュメント、アップロード、または取り込みが必要とする、まだ ClickHouse に保持されているドキュメントの原本を LOOM_DOCUMENT_S3_BUCKET に移動する。各原本は個別のオブジェクトにコピーされ、ハッシュ検証のうえ切り替えられ、… で保護される | `--org`, `--namespace`, `--dry-run` |
+| `loom export-okf` | 名前空間を OKF v0.2 バンドル(Markdown + フロントマター)として出力する。Loom メモリを git でレビューできる形にした投影。 | `--server-url`, `--token`, `--org`, `--namespace`, `--out`, `--title`, `--include-tombstoned`, `--limit`, `--dry-run`, `--no-evidence`, `--no-links`, `--include-high` |
+| `loom import-okf` | OKF v0.2 バンドルのコンセプトを memory.set 経由で名前空間に書き込む。 | ``, `--server-url`, `--token`, `--org`, `--namespace`, `--agent`, `--user-id`, `--session-id`, `--keep-sessions`, `--verify`, `--dry-run`, `--no-evidence`, `--no-lint`, `--force-import`, `--no-links`, `--prune` |
+| `loom okf-lint` | OKF バンドルのディレクトリをオフラインで lint する。ミラーリポジトリの CI が実行するコンパイルゲート。 | ``, `--json`, `--strict` |
+| `loom up` | ローカルスタック(Loom、そのドキュメント抽出器、ClickHouse)を起動し、接続方法を表示する。テンプレートから .env と ClickHouse の設定を作成し、docker compose up --build を実行し、待機する… | `--root`, `--file`, `--env-file`, `--no-build`, `--rebuild`, `--port`, `--timeout`, `--subject`, `--org`, `--namespace`, `--open` |
+| `loom down` | データを保持したままローカルスタックを停止する。--delete-data は確認付きのリセットを行う。 | `--root`, `--file`, `--env-file`, `--delete-data`, `-y` |
+| `loom ch-setup` | セルフマネージドの ClickHouse または ClickHouse Cloud サービスを Loom 用に準備する。loom データベースと読み取り専用のリーダーユーザーを作成するか、管理者向けに SQL を表示する。 | `--print-sql`, `--print-analyst-sql` |
+| `loom participant` | プロバイダーの変更が待機する Loom プロセス。 | |
+| `loom participant retire` | シャットダウンせずに終了したプロセスのプロバイダー参加者を退役させる(その ID はそのプロセスの /v1/health の `participant_id`)。 | `--participant`, `--yes` |
+| `loom deployment` | すべてのレプリカが自身を照合する設定。 | |
+| `loom deployment publish` | この env の設定をデプロイメントの設定として公開する。意図的にルートシークレットや LOOM_EMBEDDING_MODEL/DIM を置き換える場合に使う。 | `--yes`, `--check` |
+| `loom settings` | 有効な各設定の値と、ライブ設定の上書き。 | |
+| `loom settings list` | 各設定の値、その出所、ライブかどうかを表示する。 | `--prefix`, `--changed`, `--json` |
+| `loom settings set` | ライブ設定をデプロイメント全体で上書きする。再起動後も維持される。 | ``, ``, `--expect` |
+| `loom settings reset` | 上書きを削除し、env またはデフォルトに戻す。 | ``, `--expect` |
+| `loom settings history` | 記録された変更を新しい順に表示する:誰が、変更前後の値。 | ``, `--limit`, `--json` |
+| `loom secrets` | ClickHouse に封印されて保存された認証情報と署名キー。 | |
+| `loom secrets reseal` | LOOM_JWT_SECRET_PREVIOUS でしか開けないものを、LOOM_JWT_SECRET で封印し直す。 | `--dry-run`, `--check` |
+| `loom signing-key` | LOOM_JWT_SECRET と並んで ClickHouse に保持されるトークン署名キー。 | |
+| `loom signing-key rotate` | キーを追加する。すべてのプロセスが読み込んだ時点で署名に使われる。 | `--algorithm`, `--activate-in` |
+| `loom signing-key retire` | キー(または 'default')によるトークン検証を停止する。 | `` |
+| `loom signing-key record-root` | この LOOM_JWT_SECRET を、意図的に置き換えた後のデプロイメントのルートシークレットとして記録する(旧シークレットで封印されたキーは使用不能のままになる)。 | |
+| `loom signing-key list` | キーを一覧表示する。 | |
+| `loom provider-lock` | プロバイダー設定ロック。 | |
+| `loom provider-lock clear` | プロセスが停止したホルダーのプロバイダー設定ロックを解放する(更新、ハートビート、クエリ実行中の間は拒否される)。 | `--holder` |
+| `loom export-analytics` | UTC の 1 日分の利用状況と名前空間のスナップショットを Parquet として S3 に書き出す。名前は LOOM_ANALYTICS_EXPORT_NAME_KEY でハッシュ化される。 | `--bucket`, `--prefix`, `--day`, `--role-arn`, `--region`, `--expected-bucket-owner` |
+| `loom sql-access` | sql_v1_* ビューを通じてテナントのメモリ、会話、リクエスト台帳を読み取る ClickHouse ユーザーを作成、スコープ変更、削除する。 | |
+| `loom sql-access grant` | ユーザーがこのスコープだけを読み取れるようにする。ユーザーがいなければ作成する(パスワードは一度だけ表示される)。 | `--user`, `--org`, `--namespaces`, `--all`, `--rotate` |
+| `loom sql-access revoke` | ユーザーのスコープを取り消し、その後ユーザーを削除する。 | `--user` |
+| `loom sql-access list` | 付与済みのスコープ行を SQL ユーザーごとにすべて表示する。 | |
+| `loom reembed` | embedding_model が設定済みの埋め込みモデルと異なるベクターを再埋め込みする(LOOM_EMBEDDING_MODEL を変更した後に実行する。Loom は自動で再埋め込みしない)。 | `--org`, `--namespace`, `--batch-size`, `--in-database`, `--dry-run`, `--delete-old`, `--key-only`, `--resume` |
+| `loom reextract` | 名前空間の生のエビデンス(memory.set_from_messages のターン)を、実行中のサーバーの書き込みパス経由で別の名前空間に再生する。保存済みのトランスクリプトに対して現在の抽出器を適用する。ソースは… | `--org`, `--namespace`, `--into`, `--base-url`, `--token`, `--dates`, `--concurrency`, `--limit-sessions`, `--dry-run` |
+| `loom deploy-delta` | カラースワップで何が変わったか:デプロイメントの台帳行(操作ごとの量、エラー、p50/p95、アップストリームの費用)と ClickHouse のステートメント形状(実行回数、バイト数、秒数)を、前後それぞれのウィンドウで比較する… | `--swap-at`, `--window-min`, `--ch-os-user`, `--cluster`, `--top`, `--json` |
+| `loom entity-export` | 名前空間のエンティティグラフ(共起エッジとトリプル)を、外部のグラフツールや RDF ツール向けに GraphML または JSON-LD でエクスポートする。 | `--org`, `--namespace`, `--format`, `--output`, `--all` |
+| `loom audit-namespace` | 名前空間がどのように使われているか(namespace.audit):完全一致キーの読み取りと検索、ハッシュキー、二重エンコードされた値や過大な値、手作りのインデックス行、メモリとして保存されたリース、バージョンの増加。 | `--org`, `--namespace`, `--window-days`, `--samples`, `--json` |
+| `loom mentor` | ストアから 1 つのエージェントへのアドバイス(mentor.brief):呼び出した内容、名前空間が提供するプレーン、根拠付きのヒント、過去のヒントがどれだけ従われたか。 | `--org`, `--namespace`, `--agent`, `--window-days`, `--json` |
+| `loom serve` | コントロールプレーンを起動する(uvicorn)。 | `--host`, `--port`, `--log-level`, `--reload` |
+| `loom migrate` | 設定された CH に対してスキーママイグレーションを適用する。 | `--status`, `--dry-run`, `--strict`, `--target`, `--migrations-dir` |
+| `loom reconcile-status` | status が loom.memory と食い違った memory_embeddings の行(プールが認識しなかった superseded / conflicted / duplicate のマーク)を、識別行(org, namespace, agent… | `--org`, `--namespace`, `--all-namespaces`, `--since-days`, `--exclude`, `--limit`, `--apply`, `--dry-run` |
+| `loom period-digest` | 期間ダイジェストを書き込む。1 つの名前空間内の各識別子について、連続する K 個のセッションダイジェストから導出された 1 つのセマンティックメモリ。 | `--org`, `--namespace`, `--sessions`, `--max-identities`, `--max-periods`, `--apply`, `--dry-run`, `--rewrite` |
+| `loom demote-activity-narration` | ツールの動作を語るだけで持続的な成果を伴わない、名前空間内の抽出済みファクト(「User read lines 1-1000 of X」「Claude ran a command on …」)を見つけ、格下げ(信頼度 x0.25)またはラベル付けする… | `--org`, `--namespace`, `--action`, `--classifier`, `--days`, `--limit`, `--apply`, `--dry-run` |
+| `loom recalibrate` | 埋め込みモデルの再プローブと名前空間ごとのキャリブレーションを今すぐ実行する(通常は再キャリブレーションワーカーが週次で実行する)。 | |
+| `loom import-clickgap` | ClickGap(Detector→Validator→Reviewer)の SQLite エクスポートを Loom にインポートする(lessons、型付きエンティティ、カテゴリ)。 | `--sqlite`, `--org`, `--namespace`, `--agent`, `--dry-run`, `--batch-size`, `--seed-recall-events` |
+| `loom import-recall` | 外部のベクターリコール型エージェントメモリの SQLite エクスポートを Loom にインポートする。 | `--sqlite`, `--org`, `--namespace`, `--agent`, `--base-url`, `--token`, `--dry-run` |
+| `loom import-brain` | Markdown のエージェント「brain」ディレクトリを Loom にインポートする:MEMORY.md(常に注入される HOT レイヤー)→ profile.set のセクション、memory/contexts/*.md(オンデマンドで読む WARM レイヤー)→ knowledge.add のドキュメント。 | `--dir`, `--org`, `--namespace`, `--agent`, `--base-url`, `--token`, `--dry-run` |
+| `loom claim-release` | セルフサインアップのクレームを解放する:付与を取り消し、オーナーをクリアし、無効化する。 | `--org`, `--namespace`, `-y` |
+| `loom mint-token` | JWT をローカルで発行する(LOOM_JWT_SECRET が必要)。 | `--subject`, `--org`, `--namespaces`, `--roles`, `--platform-admin`, `--namespace-role`, `--ttl-days`, `--save`, `--read-scope`, `--read-user-id`, `--traffic-class`, `--consumer`, `--service-account`, `--user-token`, `--json` |
+| `loom revoke-token` | jti または subject でトークンを 1 つ失効させる(失効モジュール経由で loom.revoked_tokens に書き込む。設定済みの ClickHouse が必要)。 | `--jti`, `--subject`, `--list`, `--issued-before`, `--scim`, `--reason`, `--expires-at`, `--json` |
+| `loom sso` | パスワードアカウントをシングルサインオンに移行する。 | |
+| `loom sso adopt` | SSO でのサインインを、メールアドレスが --domain に属するパスワードアカウントに届くようにします。これにより、各ユーザーは ID プロバイダーで自分のアカウント、その名前空間とデータにサインインできます。 | `--domain`, `--org`, `--skip`, `--keep-tokens`, `--apply`, `--dry-run` |
+| `loom sso link` | ある人の SSO でのサインインを、別のアドレス(個人用のアドレスや +tag 付きのアドレス)で登録されたパスワードアカウントに届くようにします。 | `--email`, `--org`, `--namespace`, `--apply`, `--dry-run` |
+| `loom sso unlink` | 1 つのメールアドレスのリンクを元に戻します。そのグラントはアカウントを受け入れなくなります。 | `--email`, `--apply`, `--dry-run` |
+| `loom sso password-link` | シングルサインオンを無効にした後のために、メールアドレスの SSO アカウントのパスワードを設定するための 1 回限りのリンク(LOOM_PASSWORD_LINK_TTL_SECONDS の間有効、デフォルトは 1 日)を出力します。 | `--email`, `--org` |
+| `loom bot` | キーまたは CI の ID でサインインするボットと CI ジョブ。 | |
+| `loom bot create` | ボットを登録します。その名前空間と、キー(--generate-key または --public-key)や CI の信頼設定(--issuer、--audience、--claim)を指定します。 | `--name`, `--org`, `--namespace-role`, `--generate-key`, `--public-key`, `--issuer`, `--audience`, `--claim`, `--jwks-uri`, `--max-token-age`, `--max-access-token-ttl`, `--max-agents`, `--agent-claim`, `--platform-admin`, `--replace` |
+| `loom bot list` | 有効か無効かを問わず、すべてのボット。 | |
+| `loom bot disable` | ボットの証明を拒否し、ボットが保持するトークンを失効させます。 | `--name` |
+| `loom doctor` | 起動前の設定ミス(Python のバージョン、設定、JWT、CH への到達性)を診断し、/v1/health が返す問題一覧を、それぞれの対処法とともに出力します。 | `--json`, `--client`, `--server-url`, `--token` |
+| `loom report` | バグ報告フォームの Environment 欄(バージョンと `loom doctor` のチェック結果)を出力します。 | `--open` |
+| `loom drops` | 名前空間のメモリ取り込みドロップ台帳(loom.memory_drops)を、ステージと理由ごとに出力します。パイプラインが破棄、切り詰め、または断念したものが分かります。 | `--namespace`, `--org`, `--hours` |
+| `loom namespaces-gc` | 使い捨ての名前空間(ベンチのプレフィックス配下にあり、誰も登録しておらず、--idle-hours の間誰も書き込んでいない、完了済みのベンチ実行)を一覧表示(デフォルト)または消去します。消去は、リスト単位の消去 saga ごとに行います… | `--org`, `--prefix`, `--namespace`, `--exclude-prefix`, `--idle-hours`, `--include-registered`, `--erase`, `--no-purge`, `--skip-external`, `--batch`, `--show`, `--requester`, `--worker-pass` |
+| `loom erasure-re-verify` | 失敗した消去 saga を再検証します。それぞれの最後のステップ名付きの理由と、新たな残留データの集計を出力します(デフォルト、読み取り専用)。--resume を指定すると、リカバリワーカーの範囲を超えて、チェックポイントから再実行します… | `--org`, `--id`, `--resume`, `--skip-external`, `--completed-since`, `--orphan-graph`, `--erase`, `--batch`, `--show`, `--requester` |
+| `loom reconcile` | ClickHouse または Postgres のリストア後、もう一方のストアがリストア時点以降に記録した消去と、機密コンテンツを削除またはマスクするプライバシー操作であるリダクションを、リストアされたストアで再度実行します。ClickHouse のリストア後は、すべてを再度公開します… | `--restored`, `--point`, `--allow-live`, `--apply`, `--dry-run` |
+| `loom router` | デプロイメントのセルの前段に置かれるルーター。 | |
+| `loom router serve` | 配置、ルックアップ、オペレーターの API を提供し、その他のリクエストをセルにルーティングします。 | `--host`, `--port`, `--log-level` |
+| `loom router migrate` | ディレクトリの保留中のマイグレーションを適用します。 | |
+| `loom cell` | ルーターのディレクトリを通じて、デプロイメントのセルを操作します。 | |
+| `loom cell credential` | ルーターの認証情報を作成、またはセルの認証情報をローテーションします。 | ``, `--cell`, `--next`, `--finish`, `--revert`, `--operator`, `--router` |
+| `loom cell limit` | セルへの新しい org の受け入れを閉じる、再開する、または上限を設ける。 | `--cell`, `--closed`, `--open`, `--placements-max`, `--router` |
+| `loom cell which` | org に対するルックアップのセルとホストを出力します(配置されていない場合は最初のセル)。 | `--org`, `--router` |
+| `loom cell remove` | 配置のない状態で接続しているセルのディレクトリ行を削除します。 | `--cell`, `--router` |
+| `loom cell prepare` | このセルをルーターのディレクトリに登録し、その行を書き込みます。 | `--cell`, `--host`, `--credential-sha256`, `--probe-url`, `--wait`, `--router` |
+| `loom tracker-probe` | トラッカーソースへの読み取り専用の初回接続。認証情報ごと、アップストリームのテーブルごとの件数と最新のタイムスタンプ、ブレーカーの状態、設定済みのトラッカー名前空間を表示します。 | |
+| `loom tracker-contract-check` | 読み取り専用:各トラッカーソースのスキーマがレコード契約(docs/features/tracker/record-contract.md)を満たしているかを確認します。 | `--source`, `--namespace`, `--json` |
+| `loom tracker-dupcheck-fit` | 1 つのトラッカー名前空間について、tracker.duplicate_check の較正済み信頼度を今すぐ再フィットします。起票時点の重複のゴールドデータを再生し、フィットして、結果を保存します。 | `--namespace`, `--org`, `--negatives`, `--dry-run`, `--out` |
+| `loom tracker-embed-reset` | 1 つのトラッカー名前空間の tracker_embed パスのカーソルをクリアし、次のパスでウィンドウを再走査して、テキストのレシピが変わったすべてのアイテムを再埋め込みします。 | `--namespace`, `--org`, `--kind`, `--apply`, `--dry-run` |
+| `loom namespaces-adopt` | ライブのメモリを持ちレジストリ行のない名前空間に、オーナー行を付与します。ベンチのプレフィックス配下は kind=bench、それ以外は memory とし、retention_days は 0、TTL なしです。 | `--org`, `--owner`, `--prefix`, `--namespace`, `--kind`, `--apply`, `--dry-run`, `--show` |
+| `loom sensitivity-sweep` | 書き込み時に機微性検出器がラベルを付けるはずだったものの、あるパスがスキップした有効な行にラベルを付けます。 | `--org`, `--namespace`, `--since-days`, `--limit`, `--show`, `--only-shape`, `--apply`, `--dry-run` |
+| `loom integrity-repair` | 行レベルの整合性ゲージ(ベクトルを保持する dim-0 行、tombstoned_at/status のずれ、valid_to を過ぎた有効な行)を読み取り、--apply を指定すると、dim-0 行を本来の次元で再出力して検索が… | `--org`, `--namespace`, `--limit`, `--show`, `--apply`, `--dry-run` |
+| `loom rechunk` | 名前空間のナレッジドキュメントを、保存済みのコンテンツから現在のチャンカーで再チャンク化して再埋め込みします。これにより、すべてのドキュメントがセクションのメタデータ、チャンクのコンテキスト、ドキュメント頻度を持つようになります。 | `--org`, `--namespace`, `--source-uri`, `--apply`, `--dry-run` |
+| `loom export-actions` | オペレーションレジストリから導出したアクションスキーマをエクスポートします。Loom の拡張を含む MCP の tools/list マニフェスト(json)、またはポリシーゲートウェイが操作対象の統制に使う Cedar スキーマ(cedar)です。 | `--format`, `--output` |
+| `loom lexical-stats-rebuild` | 名前空間の BM25 の文書頻度を、有効な行から再計算します(語頻度ビューは挿入のみを反映するため、置き換えや tombstone により古い語彙が残ります)。 | `--org`, `--namespace`, `--no-knowledge`, `--no-memory` |
+| `loom version` | インストール済みの Loom のバージョンを出力します。 | |
+| `loom install` | ローカルの AI クライアントの設定に Loom を組み込みます。 | `--client`, `--server-url`, `--token`, `--name`, `--toolset`, `--dry-run`, `--force` |
+| `loom demo` | 最初の 5 分間:このリポジトリの AGENTS.md(または --file)を `make ingest` と同じ方法でナレッジプレーンに取り込み、質問をして、根拠の行とともに回答を出力します。 | `--file`, `--question`, `--tags`, `--base-url`, `--token`, `--org`, `--namespace`, `--root`, `--search-only` |
+| `loom init` | Loom サーバー上に ID を作成します。 | `--agent`, `--server-url`, `--org`, `--purpose`, `--ttl-days`, `--token-path`, `--config-path`, `--no-files`, `--json` |
+| `loom ingest-transcript` | チャット履歴ファイル(markdown / JSON)を、1 つのスレッドとして Loom の conversation テーブルにパイプします。 | `--server-url`, `--token`, `--org`, `--namespace`, `--agent`, `--thread-id`, `--file`, `--dry-run` |
+| `loom memory-search` | シェルから memory.search を実行します。 | `--server-url`, `--token`, `--org`, `--namespace`, `--agent`, `--user-id`, `--query`, `--top-k`, `--search-mode`, `--json-agent` |
+| `loom set-host` | このデプロイメントの Loom ホストを指定します。 | ``, `--env-file`, `--append`, `--dry-run` |
+| `loom login` | ワンタイムコードを使って、任意のブラウザから Loom サーバーにサインインします。 | |
+| `loom logout` | サーバー上の保存済みセッションを終了し、ローカルからも削除します。 | |
+| `loom whoami` | 保存済みのセッションでサインインしている ID を表示します。 | |
+| `loom call` | 保存済みのセッションで、任意のオペレーションまたは API ルートを呼び出します(`loom call --help`)。 | |
+| `loom token` | CI やエージェント向けに、自分のトークンを作成、一覧表示、失効します(`loom token --help`)。 | |
+
+
+
+
+
+
+## 関連ドキュメント
+
+- [オペレーションリファレンス](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md):クライアントコマンドが呼び出す op。
+- [メンテナンス](https://github.com/ClickHouse/loom/blob/main/docs/operations/maintenance.md):再埋め込み、バックフィル、修復。
+- [コードインデックスの運用](https://github.com/ClickHouse/loom/blob/main/docs/operations/code-index-operations.md)。
+- [アップグレード](https://github.com/ClickHouse/loom/blob/main/docs/operations/upgrades.md):アップグレード手順における `loom migrate`。
+- [ローカル開発](https://github.com/ClickHouse/loom/blob/main/docs/development/local-development.md)。
diff --git a/i18n/.pending/ko/docs/reference/cli.md b/i18n/.pending/ko/docs/reference/cli.md
new file mode 100644
index 0000000000..f531eb6cca
--- /dev/null
+++ b/i18n/.pending/ko/docs/reference/cli.md
@@ -0,0 +1,305 @@
+
+> 이 페이지는 [영어 원문](https://github.com/ClickHouse/loom/blob/main/docs/reference/cli.md)을 기계 번역한 것이며, 영어 원문이 기준입니다.
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/reference/cli.md), which is authoritative.
+
+
+
+# CLI 레퍼런스
+
+`loom`은 Loom 배포를 실행하고, 유지 관리하고, 연결하기 위한 단일 명령줄 진입점입니다. 서버 패키지의 `loom` 콘솔 스크립트이며(`pyproject.toml`, `[project.scripts]` → `server.cli:main`), 파서 트리는 `server/cli/app.py`에 있고 명령 계열별 모듈은 `server/cli/` 아래에 하나씩 있습니다. 이 페이지 끝의 표는 해당 트리에서 생성됩니다.
+
+
+
+## 실행 위치
+
+| 위치 | 방법 | 용도 |
+| -------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
+| 서버 이미지 내부 | `docker exec loom-server loom ` (웹 컨테이너) | 배포 환경 자체 설정을 사용하는 운영자 명령: `doctor`, `migrate`, `mint-token`, `reembed`. |
+| 분리 배포의 workers 컨테이너 내부 | `docker exec loom-workers loom ` | 웹 티어에서 분리해 실행하려는 장시간 유지보수 작업: `code backfill`, `code stats`. |
+| 체크아웃 | 저장소 루트에서 `pip install -e .`를 실행한 뒤 `loom ` | `up`, `install`, `demo`, 그리고 로컬 스택을 대상으로 한 개발. |
+
+컨테이너 내부에서 설정은 컨테이너의 환경 변수입니다. 체크아웃에서는 `loom`이 먼저 작업 디렉터리의 `.env`(또는 `LOOM_ENV_FILE`이 지정한 파일, 비워 두면 사용 안 함)를 compose의 `env_file`과 같은 방식으로 환경에 불러오며, 셸에서 이미 export한 변수는 덮어쓰지 않습니다. 이는 공급자 키에서 중요합니다. 키 없이 체크아웃에서 임베딩 명령을 실행하면 가짜 임베더로 대체되어 사용할 수 없는 벡터가 기록됩니다.
+
+명령은 두 종류로 나뉩니다.
+
+- **운영자 명령**은 `server/settings/`를 읽고 ClickHouse와 직접 통신합니다
+ (`migrate`, `reembed`, `code backfill`, `revoke-token`, 백필과 복구 명령). 배포 환경의 자격 증명으로 실행되므로, 해당 자격 증명이 있는 곳에서 실행하세요.
+- **클라이언트 명령**은 URL과 토큰으로 실행 중인 서버와 HTTP로 통신합니다 (`install`, `init`, `demo`, `memory-search`, `ingest-transcript`, `export-okf`, `import-okf`). 이 명령들은 `--server-url`(`demo`에서는 `--base-url`)을 받고, `init`을 제외하면 `--token`도 받으며, 플러그인 훅의 순서대로 값을 결정합니다. URL은 `LOOM_BASE_URL`, 그다음 `~/.loom/config.json`의 `url`, 없으면 `http://localhost:7777`입니다. 토큰은 `LOOM_API_KEY`, 그다음 `~/.loom/config.json`의 `token`, 그다음 `~/.loom/token`(`LOOM_API_KEY_FILE`로 위치 변경)입니다. `LOOM_CONFIG_FILE`은 설정 파일의 위치를 변경합니다.
+ 에이전트(워크로드 토큰이 있는 `LOOM_CLIENT_ID`)의 경우 `--token` 또는 `LOOM_API_KEY`만 사용하고 저장된 토큰은 사용하지 않으며, 둘 다 없으면 거부합니다(종료 코드 2). `loom install`은 `--token`이 무엇이든 거부하고, `loom init`은 아무것도 가입시키기 전에 거부하며, `loom call`은 워크로드 토큰을 직접 교환합니다.
+
+`loom mint-token`에는 `LOOM_JWT_SECRET`만 필요하며, 토큰을 로컬에서 서명합니다.
+
+**세션 명령**(`login`, `logout`, `whoami`, `call`, `token`)은 Python SDK 자체의 명령(`loom.cli`, SDK만 설치된 경우 `python -m loom …`)이므로, 이 명령을 쓰려면 `loom`에 `pip install clickhouse-loom`이 필요합니다. `loom login [--server URL]
+[--profile NAME] [--no-browser] [--org ORG [--wait S]]`는 일회용 코드로 로그인하며, `--org`를 쓰면 라우터의 조회에서 지정된 해당 조직의 [셀](https://github.com/ClickHouse/loom/blob/main/docs/architecture/cells.md)에 로그인합니다. `loom call [key=text|key:=json …] [--data JSON] [--org] [--namespace]`는 그 세션으로 모든 operation 또는 라우트에 접근하고, `loom token create|list|revoke`는 CI와 에이전트용 본인 토큰을 생성, 조회, 폐기합니다. [대시보드 없이 Loom 사용하기](https://github.com/ClickHouse/loom/blob/main/docs/guides/without-the-dashboard.md)를 참고하세요.
+
+
+
+## 규칙
+
+**재작성 명령은 기본적으로 드라이 런입니다.** 저장된 행을 재작성하는 명령은 `--apply`를 지정하지 않으면 쓰게 될 내용을 보고하기만 합니다. `--dry-run`도 사용할 수 있으며 기본 동작을 명시적으로 나타냅니다. 두 플래그는 함께 쓸 수 없습니다(`server/cli/_apply.py`, `add_apply_flags`). 드라이 런이 성공하면 stderr의 마지막 줄에 `dry run: nothing was written; re-run with --apply to write`가 출력되므로, 명령의 `--json` 출력은 stdout에 단독으로 남습니다. 일부 명령은 같은 개념을 자체 플래그로 표현합니다(`loom entity-edges-invalidate-junk`는 `--dry-run`(기본값) 또는 `--apply`를 받고, `loom reembed --dry-run`은 쓰지 않고 행 수만 셉니다). 각 명령의 플래그는 아래 표에 정리되어 있습니다.
+
+**모든 쓰기에는 주체가 명시됩니다.** 명령이 수행하는 쓰기에는 actor `process:cli:`가 기록됩니다(`server/memory/domain/provenance.py`, `cli_actor`). 따라서 출처 정보(provenance)와 감사 로그를 통해 어떤 명령이 행을 썼는지 알 수 있습니다.
+
+**모든 쿼리는 출처가 표시됩니다.** 명령이 실행하는 ClickHouse 쿼리에는 `log_comment` 태그 `cli.[.]`가 붙고, 명령이 자체 `--traffic-class`를 받지 않는 한 읽기는 `background` 트래픽 클래스에서 실행됩니다. `loom serve`는 예외입니다. 이 명령은 서버 자체이므로, 서버의 요청과 워커 패스가 스스로 태그를 붙입니다.
+
+**`--json`** 을 제공하는 명령에서 이 플래그를 쓰면 기계가 읽을 수 있는 결과 하나를 stdout에 출력하고, 사람이 읽는 보고서는 stderr에 남깁니다.
+
+
+
+## 자주 쓰는 명령
+
+
+
+### 배포 실행 및 확인
+
+```bash
+loom up # from a checkout: create .env, boot Loom, its extractor and ClickHouse, print how to connect
+docker exec loom-server loom doctor # pre-boot checks + the /v1/health problem list, each with its fix
+docker exec loom-server loom doctor --json # the same, machine-readable
+loom doctor --client # also examine this machine as a coding-agent client
+docker exec loom-server loom migrate --status # applied and pending migrations
+docker exec loom-server loom migrate --dry-run --strict # what a boot would apply; exit 1 on ledger drift
+```
+
+`loom up`은 `/v1/health`가 응답할 때까지 기다리고(최대 `--timeout`, 기본값 300 s), 인증이 켜져 있으면 writer 토큰을 발급하며, 대시보드 URL과 첫 호출 예제를 출력합니다. `--no-build`는 캐시된 이미지를 재사용하고, 이미 health에 응답하는 스택은 `--rebuild`를 지정하지 않는 한 그대로 둡니다. `loom doctor`는 검사에 하나라도 실패하면 종료 코드 1로 끝납니다. `loom serve`는 로컬 사용을 위해 uvicorn 아래에서 컨트롤 플레인을 실행합니다(이미지는 `scripts/serve.sh`를 통해 이를 시작합니다). 마이그레이션과 업그레이드는 [업그레이드](https://github.com/ClickHouse/loom/blob/main/docs/operations/upgrades.md)에서, 상태 확인은 [모니터링](https://github.com/ClickHouse/loom/blob/main/docs/operations/monitoring.md)에서 다룹니다.
+
+
+
+### 토큰
+
+```bash
+# A writer token for one namespace, valid 30 days, printed on stdout
+docker exec loom-server loom mint-token --subject my-bot --org dev \
+ --namespaces local --roles writer --ttl-days 30
+
+# A scoped token: per-namespace roles, in read-priority order
+loom mint-token --subject triage --org acme \
+ --namespace-role priv=admin --namespace-role pub=viewer --json
+
+# Retire one token, or every token of a subject issued before an instant
+docker exec loom-server loom revoke-token --jti --reason "leaked"
+docker exec loom-server loom revoke-token --subject my-bot --issued-before 2030-01-01T00:00:00Z
+```
+
+영구 폐기에는 만료 시각을 지정할 수 없으며, 그 이전에 폐기된 토큰을 복원하도록 범위를 좁힐 수도 없습니다. 기존 기준 시각과 같거나 그 이후의 기준 시각을 선택하거나, 영구 폐기 시각에 토큰 시계 오차 허용치를 더한 값을 사용하십시오.
+
+`--save`는 토큰을 출력하는 대신 `~/.loom/token`(또는 지정한 경로)에 씁니다. `--ttl-days`가 없으면 토큰은 만료되지 않으며 `loom revoke-token`으로만 폐기할 수 있습니다. `--read-scope own_user`는 각 요청이 지정한 `user_id`로 읽기를 제한하고, `--consumer NAME`은 [컨슈머 태그](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#the-consumer-tag)를 자격 증명에 바인딩합니다. [토큰과 권한 부여](https://github.com/ClickHouse/loom/blob/main/docs/guides/tokens-and-grants.md)를 참고하십시오.
+
+
+
+### 클라이언트 연결
+
+```bash
+loom install --client cursor --token "$LOOM_API_KEY" --server-url https://loom.example.com
+loom install --client claude-code --toolset coding+tracker --dry-run
+loom init --agent triage-bot --server-url https://loom.example.com # self-signup: a namespace + token
+```
+
+`loom install`은 클라이언트 설정에 MCP 서버 항목을 쓰거나 `claude mcp add` / `codex mcp add`를 실행합니다. `--client`를 지정하지 않으면 발견한 모든 지원 클라이언트에 연결합니다. [MCP 클라이언트](https://github.com/ClickHouse/loom/blob/main/docs/features/integrations/mcp-clients.md)를 참고하십시오. `loom init`은 토큰을 `~/.loom/token`에, 서버·조직·네임스페이스를 `~/.loom/config.json`에 저장합니다. 이 파일은 클라이언트 명령과 플러그인 훅이 읽습니다.
+
+
+
+### 임베더 변경 후 재임베딩
+
+```bash
+docker exec loom-server loom reembed --dry-run # count rows whose embedding_model is not the configured one
+docker exec loom-server loom reembed --namespace support
+docker exec loom-server loom reembed --delete-old # re-embed, then delete the off-model rows
+```
+
+Loom은 스스로 재임베딩하지 않습니다. `LOOM_EMBEDDING_MODEL`을 변경한 후에는 `loom reembed`를 실행하십시오. 이 명령은 저장된 콘텐츠에서 벡터를 다시 생성하고 나머지 모든 컬럼은 그대로 유지합니다. `--in-database `은 `aiEmbed`(ClickHouse 26.7 이상)를 사용해 ClickHouse 내부에서 테이블마다 하나의 `INSERT … SELECT`로 임베딩합니다. 고객 또는 ID 헤더가 설정되어 있거나 추론 게이트웨이가 필수인 경우에는 거부됩니다. `--resume`은 이전 실행의 `resume:` 줄이 가리키는 행 다음부터 이어서 실행합니다. [유지보수](https://github.com/ClickHouse/loom/blob/main/docs/operations/maintenance.md)를 참고하십시오.
+
+
+
+### 저장소 인덱싱
+
+```bash
+docker exec loom-workers loom code init --org acme --namespace code-myrepo
+docker exec loom-workers loom code backfill --org acme --namespace code-myrepo --embed
+docker exec loom-workers loom code stats --org acme --namespace code-myrepo
+```
+
+`code backfill`은 이어서 실행할 수 있습니다. `--phase index`는 파싱, 청킹, 심볼과 엣지 도출을 수행하고, `--phase embed`는 대기 중인 벡터를 채우며, `--embed`는 둘을 한 번에 실행합니다. 가짜 임베더로는 임베딩을 거부하며, `--allow-fake-embedder`(개발 전용)를 지정해야 합니다. `--org`와 `--namespace`의 기본값은 각각 `LOOM_CODE_ORG`와 `LOOM_CODE_NAMESPACE`입니다. 전체 절차, 컴파일러 티어, PR 이력 백필은 [코드 인덱스 운영](https://github.com/ClickHouse/loom/blob/main/docs/operations/code-index-operations.md)에서 다룹니다.
+
+
+
+### 내보내기 및 가져오기
+
+```bash
+loom export-okf --namespace support --out ./support-okf # a namespace as a Markdown bundle
+loom okf-lint ./support-okf --strict # offline lint; exit 2 on a critical finding or, with --strict, a warning
+loom import-okf ./support-okf --namespace support-copy
+loom export-actions --format cedar -o loom.cedarschema # the registry as a policy schema
+```
+
+`export-okf`는 `sensitivity=high`이거나 민감도를 알 수 없는 행을 `--include-high`를 지정하지 않는 한 제외합니다. 미러 저장소는 네임스페이스의 권한 부여 범위보다 더 넓은 독자층에 노출되기 때문입니다. 그런 행에 연결된 원시 청크와 다이제스트, 그리고 높은 민감도의 형태(자격 증명, 카드 번호, SSN 또는 명시된 PIN)를 담은 원시 텍스트도 그 행과 함께 내보내지 않습니다. `--include-high`는 이들을 내보내며, 서버는 내보낸 각 항목을 감사합니다. [OKF](https://github.com/ClickHouse/loom/blob/main/docs/features/integrations/okf.md)와 [액션 스키마 내보내기](https://github.com/ClickHouse/loom/blob/main/docs/reference/mcp.md#exporting-the-action-schema)를 참고하십시오.
+
+
+
+### 진단 및 복구
+
+`loom report`는 `loom doctor` 출력과 함께 버그 양식의 Environment 필드를 출력하며, `--open`은 버전이 채워진 양식을 엽니다. `loom drops`는 네임스페이스의 메모리 수집 누락 원장을 출력합니다. `loom erasure-re-verify`는 실패한 삭제 saga를 다시 검사합니다. 백필 및 복구 명령(`integrity-repair`, `reconcile-status`, `repair-value-bytes`, `entity-edges-invalidate-junk`, `rechunk`, `lexical-stats-rebuild` 등)과 각각을 실행해야 하는 시점은 [유지보수](https://github.com/ClickHouse/loom/blob/main/docs/operations/maintenance.md)와 [문제 해결](https://github.com/ClickHouse/loom/blob/main/docs/operations/troubleshooting.md)에 있습니다.
+
+
+
+## 표 읽는 방법
+
+각 행은 하나의 명령 또는 하위 명령입니다. 전체 호출 형식, 도움말 텍스트의 첫 문장, 그리고 인자를 보여 줍니다. 위치 인자는 `` 형태로, 옵션은 긴 형식으로 표시합니다. `loom --help`는 전체 텍스트, 기본값, 선택 가능한 값을 출력합니다. 생성기(`scripts/codegen/docs_reference.py`, `render_cli`)는 커밋된 파서 스냅샷 `tests/unit/snapshots/cli_tree.json`을 읽습니다. `tests/unit/test_cli_surface_snapshot.py`는 이 스냅샷과 `tests/unit/snapshots/cli_help.json`이 실제 파서와 동일하도록 유지하므로, 새 플래그를 추가하면 두 스냅샷과 이 페이지를 다시 생성하기 전까지 CI가 실패합니다.
+
+```bash
+LOOM_UPDATE_CLI_SNAPSHOT=1 python -m pytest tests/unit/test_cli_surface_snapshot.py
+python scripts/codegen/docs_reference.py
+```
+
+
+
+## 명령
+
+
+
+
+
+| 명령 | 요약 | 인자 및 플래그 |
+| --- | --- | --- |
+| `loom code` | 코드 인텔리전스 플레인 작업. | |
+| `loom code init` | bare clone과 초기 상태를 생성합니다. | `--org`, `--namespace` |
+| `loom code backfill` | 전체 트리 인덱싱(재개 가능). | `--org`, `--namespace`, `--phase`, `--embed`, `--include-poisoned`, `--allow-fake-embedder`, `--no-fetch`, `--limit`, `--commit`, `--paths-file`, `--concurrency`, `--edges-second-pass`, `--no-edges-second-pass`, `--dialect-folder-pass`, `--embedding-model-suffix`, `--context-callees`, `--callers-from` |
+| `loom code reconcile` | 내용 기반 최신성 검사: 청크가 브랜치 헤드에서의 마지막 변경보다 오래된 경로를 찾으며, --heal은 해당 경로를 다시 인제스트합니다(워터마크는 변경하지 않음). | `--org`, `--namespace`, `--heal`, `--limit`, `--max-commits`, `--no-fetch`, `--show` |
+| `loom code compact` | 키당 물리적 사본 수가 --min-ratio에 도달하면 코드 벡터 테이블에 OPTIMIZE ... FINAL을 실행하고 병합이 끝날 때까지 기다립니다. | `--table`, `--min-ratio`, `--apply`, `--dry-run`, `--timeout-s` |
+| `loom code reembed` | 네임스페이스의 라이브 청크를 두 번째 임베딩 모델의 레이블로 기록합니다: 데이터베이스 내부 처리, 재개 가능, 체크아웃 불필요. | `--org`, `--namespace`, `--embedding-model`, `--source-model`, `--prefix`, `--batch` |
+| `loom code vector-twin` | ClickHouse 내부에서 네임스페이스의 청크 벡터에 대한 Matryoshka 접두사 트윈을 채웁니다: 재임베딩 없음, 재개 가능. | `--org`, `--namespace`, `--embedding-model`, `--all-namespaces` |
+| `loom code crossref` | SQL/셸 테스트 -> 구현 C++ 참조 패스(code_test_map method=content_reference를 기록하며, 멱등). | `--org`, `--namespace` |
+| `loom code coverage-import` | 구성된 소스의 가장 최근 테스트별 라인 커버리지 실행을 가져옵니다(code_test_map method=coverage와 code_coverage_files를 기록). | `--org`, `--namespace`, `--dry-run` |
+| `loom code export-pairs` | 임베더/리랭커 파인튜닝을 위해 실제 트래픽(trace x outcome 조인)에서 (쿼리 -> 사용된 단위, 하드 네거티브) 검색 쌍을 내보냅니다. | `--org`, `--namespace`, `--days`, `--out` |
+| `loom code backfill-prs` | GitHub의 병합된 PR 이력. | `--org`, `--namespace`, `--months`, `--max-prs` |
+| `loom code repack` | 최근 병합된 PR의 컨텍스트 팩을 현재 팩 형식으로 다시 생성합니다. | `--org`, `--namespace`, `--days`, `--limit`, `--dry-run` |
+| `loom code describe` | PageRank 상위 청크에 대한 LLM 문맥 한 줄 설명. | `--org`, `--namespace`, `--top-pct`, `--limit`, `--suffix`, `--concurrency` |
+| `loom code answers-purge` | 캐시된 code.ask 답변을 툼스톤 처리합니다(합성 모델 업그레이드 후에는 더 약한 모델의 오래된 답변이 계속 제공될 수 있으며, 캐시는 인용된 파일이 변경될 때만 스스로 무효화됩니다). | `--llm-model`, `--all`, `--apply`, `--dry-run`, `--org`, `--namespace` |
+| `loom code scip-full` | 컴파일러 티어 전체 재인덱싱을 수동으로 실행합니다(code_scip_full 워커가 기본적으로 매주 실행하며, 병합별 델타의 TU 한도 저하와 모든 드리프트를 복구합니다). | `--checkout`, `--jobs`, `--keep-delta`, `--apply-delta`, `--org`, `--namespace` |
+| `loom code scip-lock-path` | 이 호스트에서 해당 항목의 컴파일러 티어 잠금 파일 경로를 출력합니다. | `--org`, `--namespace` |
+| `loom code entry-lock` | 항목의 컴파일러 티어 잠금(이 호스트의 파일과 배포의 리스) 아래에서 명령을 실행합니다: 다른 패스가 잠금을 보유하면 75로 종료하고, 실행 중 리스를 잃으면 3으로 종료합니다(명령은 중지됨). | `--org`, `--namespace`, `--tier`, `` |
+| `loom code scip-delta` | 컴파일러 티어 델타 패스를 수동으로 한 번 실행합니다(code_scip_delta 워커와 같은 코드): 구성된 저장소마다 git_head와 scip_commit을 비교하고, 변경된 TU에 scip-clang을 실행한 뒤 적용합니다. | |
+| `loom code entries` | 구성된 저장소마다 한 줄: org namespace checkout lock-file(잠금 경로가 확인됨, 수동 실행은 `loom code entry-lock`을 통해 잠금을 획득). | |
+| `loom code warm` | 질문 목록(한 줄에 질문 하나, 또는 'question' 필드가 있는 JSONL)으로 code.ask 답변 캐시를 미리 채웁니다. | ``, `--org`, `--namespace` |
+| `loom code scip-retry` | 실패한 SCIP 배치를 pending으로 재설정합니다. | `--org`, `--namespace`, `` |
+| `loom code backfill-reviews` | code_pr_history에 이미 있지만 저장된 리뷰 댓글이 없는 병합된 PR의 인라인 리뷰 댓글(최신순, PR당 GitHub 요청 1회). | `--org`, `--namespace`, `--prs` |
+| `loom code backfill-assignees` | 이미 저장된 병합된 PR에 대해 code_pr_history.assignees(저장소가 리뷰어로 지정한 사람)를 채우며, 최신 닫힌 PR부터 요청당 100개씩 탐색합니다. | `--org`, `--namespace`, `--pages` |
+| `loom code backfill-items` | 특정 날짜 이후 업데이트된 code_gh_items(이슈 + PR, 모든 상태)를 요청당 100개씩, 가장 오래된 업데이트부터 채우며 gh_items_cursor를 이동합니다. | `--org`, `--namespace`, `--since`, `--pages` |
+| `loom code stats` | 워터마크와 라이브 행 수. | `--org`, `--namespace` |
+| `loom code export-matrix` | 병합된 PR의 공동 변경에서 도출한 유지보수 매트릭스: '이 파일이 변경되면 보통 이 파일들도 함께 변경된다'를 근거와 함께 지침 파일(AGENTS.md / copilot-instructions.md)용 Markdown으로 출력합니다. | `--org`, `--namespace`, `--prs`, `--min-together`, `--min-conf`, `--max-partners`, `--max-rows`, `--out`, `--json` |
+| `loom code lint-instructions` | 경로나 심볼 참조가 클론의 헤드에서 더 이상 확인되지 않는 에이전트 지침 파일(CLAUDE.md, AGENTS.md, copilot-instructions, .claude/.md, skills). | `--org`, `--namespace`, `--file`, `--glob`, `--symbols`, `--all`, `--json`, `--fail-on-stale` |
+| `loom decisions` | 문서에서 추출한 결정 레코드. | |
+| `loom decisions extract` | 지식 문서 하나를 결정 레코드로 추출합니다: 모델이 문서를 통째로 읽으며(LOOM_MEMORY_DECISION_EXTRACT_WINDOW_CHARS를 넘으면 전체 섹션 단위의 윈도우로 읽음, 이미지만 있는 제목은… | `--org`, `--namespace`, `--source-uri`, `--repo`, `--into`, `--max-per-section`, `--window-chars`, `--apply`, `--dry-run` |
+| `loom knowledge` | 지식 문서와 그 소스. | |
+| `loom knowledge sync` | 저장소 네임스페이스의 문서 소스에 대해 동기화 패스를 지금 한 번 실행합니다: 각 소스의 변경된 파일을 나열하고(--full이면 모든 파일), 변경된 파일은 문서로 기록하며 전체 목록에 더 이상 없는 문서는 폐기합니다… | `--org`, `--namespace`, `--source`, `--full` |
+| `loom knowledge source` | 실행 중인 서버를 통한 네임스페이스의 문서 소스. | |
+| `loom knowledge source list` | 네임스페이스의 소스, 항목, 동기화 상태를 나열합니다. | `--namespace`, `--org`, `--server-url`, `--token` |
+| `loom knowledge source add` | 링크나 항목으로 소스를 등록하며, 저장하기 전에 자격 증명으로 확인합니다(knowledge.source.add). | `--namespace`, `--org`, `--server-url`, `--token`, `--name`, `--kind`, `--link`, `--item-json`, `--include`, `--credential-file`, `--dry-run` |
+| `loom knowledge source update` | 소스의 항목을 추가·제거하거나 파일 종류를 변경하며, 추가된 항목은 저장된 자격 증명으로 확인합니다(knowledge.source.update). | `--namespace`, `--org`, `--server-url`, `--token`, `--name`, `--link`, `--item-json`, `--include`, `--remove-link`, `--remove-item-json` |
+| `loom knowledge migrate-originals` | 문서, 업로드 또는 인제스트에 필요하지만 아직 ClickHouse에 보관된 문서 원본을 LOOM_DOCUMENT_S3_BUCKET으로 옮깁니다: 각각 자체 객체로 복사하고 해시를 검증한 뒤 전환하며, 다음으로 보호됩니다… | `--org`, `--namespace`, `--dry-run` |
+| `loom export-okf` | 네임스페이스를 OKF v0.2 번들(Markdown + frontmatter)로 렌더링합니다. Loom 메모리를 git에서 검토할 수 있게 만든 투영입니다. | `--server-url`, `--token`, `--org`, `--namespace`, `--out`, `--title`, `--include-tombstoned`, `--limit`, `--dry-run`, `--no-evidence`, `--no-links`, `--include-high` |
+| `loom import-okf` | OKF v0.2 번들의 개념을 memory.set을 통해 네임스페이스에 기록합니다. | ``, `--server-url`, `--token`, `--org`, `--namespace`, `--agent`, `--user-id`, `--session-id`, `--keep-sessions`, `--verify`, `--dry-run`, `--no-evidence`, `--no-lint`, `--force-import`, `--no-links`, `--prune` |
+| `loom okf-lint` | OKF 번들 디렉터리를 오프라인으로 린트합니다. 미러 저장소의 CI가 실행하는 컴파일 게이트입니다. | ``, `--json`, `--strict` |
+| `loom up` | 로컬 스택(Loom, 문서 추출기, ClickHouse)을 시작하고 연결 방법을 출력합니다: 템플릿에서 .env와 ClickHouse 설정을 만들고, docker compose up --build를 실행하며, 다음을 기다립니다… | `--root`, `--file`, `--env-file`, `--no-build`, `--rebuild`, `--port`, `--timeout`, `--subject`, `--org`, `--namespace`, `--open` |
+| `loom down` | 데이터를 보존한 채 로컬 스택을 중지합니다. --delete-data는 확인을 거쳐 초기화를 수행합니다. | `--root`, `--file`, `--env-file`, `--delete-data`, `-y` |
+| `loom ch-setup` | Loom용으로 자체 관리 ClickHouse 또는 ClickHouse Cloud 서비스를 준비합니다: loom 데이터베이스와 읽기 전용 reader 사용자를 만들거나, 관리자를 위한 SQL을 출력합니다. | `--print-sql`, `--print-analyst-sql` |
+| `loom participant` | 프로바이더 변경이 기다리는 Loom 프로세스. | |
+| `loom participant retire` | 종료하지 않고 죽은 프로세스의 프로바이더 참여자를 폐기합니다(해당 프로세스의 /v1/health에 있는 `participant_id`). | `--participant`, `--yes` |
+| `loom deployment` | 모든 레플리카가 스스로를 대조하는 구성. | |
+| `loom deployment publish` | 이 환경의 구성을 배포의 구성으로 게시하며, 루트 시크릿이나 LOOM_EMBEDDING_MODEL/DIM을 의도적으로 교체합니다. | `--yes`, `--check` |
+| `loom settings` | 적용 중인 모든 설정값과 라이브 설정의 오버라이드. | |
+| `loom settings list` | 각 설정의 값, 출처, 라이브 여부. | `--prefix`, `--changed`, `--json` |
+| `loom settings set` | 배포 전체에 대해 라이브 설정을 오버라이드합니다. 재시작 후에도 유지됩니다. | ``, ``, `--expect` |
+| `loom settings reset` | 오버라이드를 제거하여 환경 변수 또는 기본값으로 되돌립니다. | ``, `--expect` |
+| `loom settings history` | 기록된 변경을 최신순으로 표시: 변경한 사람, 변경 전후의 값. | ``, `--limit`, `--json` |
+| `loom secrets` | ClickHouse에 암호화되어 저장된 자격 증명과 서명 키. | |
+| `loom secrets reseal` | LOOM_JWT_SECRET_PREVIOUS로만 열리는 항목을 LOOM_JWT_SECRET으로 다시 봉인합니다. | `--dry-run`, `--check` |
+| `loom signing-key` | ClickHouse에 보관되는, LOOM_JWT_SECRET 외의 토큰 서명 키. | |
+| `loom signing-key rotate` | 키를 추가합니다. 모든 프로세스가 로드한 뒤에 서명에 사용됩니다. | `--algorithm`, `--activate-in` |
+| `loom signing-key retire` | 키('default' 포함)가 토큰을 검증하지 못하도록 중단합니다. | `` |
+| `loom signing-key record-root` | 의도적으로 교체한 뒤, 이 LOOM_JWT_SECRET을 배포의 루트 시크릿으로 기록합니다(이전 시크릿으로 봉인된 키는 계속 사용할 수 없음). | |
+| `loom signing-key list` | 키를 나열합니다. | |
+| `loom provider-lock` | 프로바이더 구성 잠금. | |
+| `loom provider-lock clear` | 프로세스가 중지된 보유자의 프로바이더 구성 잠금을 해제합니다(갱신, 하트비트 또는 실행 중인 쿼리가 있으면 거부됨). | `--holder` |
+| `loom export-analytics` | UTC 기준 하루치 사용량과 네임스페이스 스냅샷을 Parquet으로 S3에 기록하며, 이름은 LOOM_ANALYTICS_EXPORT_NAME_KEY로 해시됩니다. | `--bucket`, `--prefix`, `--day`, `--role-arn`, `--region`, `--expected-bucket-owner` |
+| `loom sql-access` | sql_v1_* 뷰를 통해 테넌트의 메모리, 대화, 요청 원장을 읽는 ClickHouse 사용자를 만들거나, 범위를 조정하거나, 삭제합니다. | |
+| `loom sql-access grant` | 사용자가 정확히 이 범위만 읽도록 하며, 없으면 생성하고 비밀번호를 한 번만 출력합니다. | `--user`, `--org`, `--namespaces`, `--all`, `--rotate` |
+| `loom sql-access revoke` | 사용자의 범위를 회수한 뒤 사용자를 삭제합니다. | `--user` |
+| `loom sql-access list` | 부여된 모든 범위 행을 SQL 사용자별로 표시합니다. | |
+| `loom reembed` | embedding_model이 구성된 임베더와 다른 벡터를 다시 임베딩합니다(LOOM_EMBEDDING_MODEL을 변경한 뒤 실행하며, Loom은 자동으로 재임베딩하지 않습니다). | `--org`, `--namespace`, `--batch-size`, `--in-database`, `--dry-run`, `--delete-old`, `--key-only`, `--resume` |
+| `loom reextract` | 네임스페이스의 원본 증거(memory.set_from_messages 턴)를 실행 중인 서버의 쓰기 경로를 통해 다른 네임스페이스로 재생합니다. 저장된 대화록에 현재 추출기를 적용하며, 소스는… | `--org`, `--namespace`, `--into`, `--base-url`, `--token`, `--dates`, `--concurrency`, `--limit-sessions`, `--dry-run` |
+| `loom deploy-delta` | 컬러 스왑이 바꾼 것: 양쪽 구간에서 배포의 원장 행(작업별 볼륨, 오류, p50/p95, 업스트림 비용)과 ClickHouse 구문 형태(실행 횟수, 바이트, 초). | `--swap-at`, `--window-min`, `--ch-os-user`, `--cluster`, `--top`, `--json` |
+| `loom entity-export` | 네임스페이스의 엔티티 그래프(동시 출현 에지 + 트리플)를 외부 그래프 또는 RDF 도구용 GraphML이나 JSON-LD로 내보냅니다. | `--org`, `--namespace`, `--format`, `--output`, `--all` |
+| `loom audit-namespace` | 네임스페이스가 사용되는 방식(namespace.audit): 정확한 키 읽기 대 검색, 해시 키, 이중 인코딩되거나 너무 큰 값, 수작업으로 만든 인덱스 행, 메모리로 저장된 리스, 버전 변동. | `--org`, `--namespace`, `--window-days`, `--samples`, `--json` |
+| `loom mentor` | 한 에이전트에 대한 스토어의 조언(mentor.brief): 에이전트가 호출한 것, 네임스페이스가 제공하는 플레인, 근거가 있는 힌트, 과거 힌트가 얼마나 자주 따라졌는지. | `--org`, `--namespace`, `--agent`, `--window-days`, `--json` |
+| `loom serve` | 컨트롤 플레인을 시작합니다(uvicorn). | `--host`, `--port`, `--log-level`, `--reload` |
+| `loom migrate` | 구성된 CH에 스키마 마이그레이션을 적용합니다. | `--status`, `--dry-run`, `--strict`, `--target`, `--migrations-dir` |
+| `loom reconcile-status` | 상태가 loom.memory와 달라진 memory_embeddings 행(풀이 보지 못한 superseded / conflicted / duplicate 표시)을 다시 내보내며, 식별 행(org, namespace, agent… | `--org`, `--namespace`, `--all-namespaces`, `--since-days`, `--exclude`, `--limit`, `--apply`, `--dry-run` |
+| `loom period-digest` | 기간 요약을 작성합니다. 한 네임스페이스에서 각 식별자의 연속된 K개 세션 요약에 대한 파생 시맨틱 메모리 하나입니다. | `--org`, `--namespace`, `--sessions`, `--max-identities`, `--max-periods`, `--apply`, `--dry-run`, `--rewrite` |
+| `loom demote-activity-narration` | 지속적인 결과 없이 도구 활동을 서술하는('User read lines 1-1000 of X', 'Claude ran a command on …') 네임스페이스의 추출된 사실을 찾아 강등(신뢰도 x0.25)하거나 다음을 통해 레이블을 지정합니다… | `--org`, `--namespace`, `--action`, `--classifier`, `--days`, `--limit`, `--apply`, `--dry-run` |
+| `loom recalibrate` | 임베더를 다시 프로빙하고 네임스페이스별 보정을 즉시 실행합니다(그렇지 않으면 재보정 워커가 매주 실행). | |
+| `loom import-clickgap` | ClickGap(Detector→Validator→Reviewer) SQLite 내보내기를 Loom으로 가져옵니다(레슨 + 타입 엔티티 + 카테고리). | `--sqlite`, `--org`, `--namespace`, `--agent`, `--dry-run`, `--batch-size`, `--seed-recall-events` |
+| `loom import-recall` | 외부 벡터 리콜 에이전트 메모리 SQLite 내보내기를 Loom으로 가져옵니다. | `--sqlite`, `--org`, `--namespace`, `--agent`, `--base-url`, `--token`, `--dry-run` |
+| `loom import-brain` | Markdown 에이전트 'brain' 디렉터리를 Loom으로 가져옵니다: MEMORY.md(항상 주입되는 HOT 레이어) → profile.set 섹션, memory/contexts/*.md(필요 시 읽는 WARM 레이어) → knowledge.add 문서. | `--dir`, `--org`, `--namespace`, `--agent`, `--base-url`, `--token`, `--dry-run` |
+| `loom claim-release` | 셀프 가입 클레임을 해제합니다: 권한을 취소하고, 소유자를 지우고, 비활성화합니다. | `--org`, `--namespace`, `-y` |
+| `loom mint-token` | JWT를 로컬에서 발급합니다(LOOM_JWT_SECRET 필요). | `--subject`, `--org`, `--namespaces`, `--roles`, `--platform-admin`, `--namespace-role`, `--ttl-days`, `--save`, `--read-scope`, `--read-user-id`, `--traffic-class`, `--consumer`, `--service-account`, `--user-token`, `--json` |
+| `loom revoke-token` | jti 또는 subject로 토큰 하나를 취소합니다(취소 모듈을 통해 loom.revoked_tokens에 기록하며, 구성된 ClickHouse가 필요). | `--jti`, `--subject`, `--list`, `--issued-before`, `--scim`, `--reason`, `--expires-at`, `--json` |
+| `loom sso` | 비밀번호 계정을 싱글 사인온으로 이전합니다. | |
+| `loom sso adopt` | SSO 로그인이 --domain의 이메일을 가진 비밀번호 계정에 연결되도록 합니다. 이후 각 사용자는 ID 제공자로 로그인하여 자신의 계정, 네임스페이스, 데이터에 접근합니다. | `--domain`, `--org`, `--skip`, `--keep-tokens`, `--apply`, `--dry-run` |
+| `loom sso link` | 한 사용자의 SSO 로그인이 다른 주소(개인 주소, +tag)로 등록된 비밀번호 계정에 연결되도록 합니다. | `--email`, `--org`, `--namespace`, `--apply`, `--dry-run` |
+| `loom sso unlink` | 한 이메일의 연결을 해제합니다. 해당 권한 부여로는 더 이상 그 계정이 허용되지 않습니다. | `--email`, `--apply`, `--dry-run` |
+| `loom sso password-link` | 싱글 사인온을 끈 뒤 사용할 수 있도록, 한 이메일의 SSO 계정 비밀번호를 설정하는 일회용 링크(LOOM_PASSWORD_LINK_TTL_SECONDS 동안 유효하며 기본값은 하루)를 출력합니다. | `--email`, `--org` |
+| `loom bot` | 키 또는 CI의 ID로 로그인하는 봇과 CI 작업. | |
+| `loom bot create` | 봇을 등록합니다. 봇의 네임스페이스와 키(--generate-key 또는 --public-key), 그리고/또는 CI 신뢰(--issuer, --audience, --claim)를 지정합니다. | `--name`, `--org`, `--namespace-role`, `--generate-key`, `--public-key`, `--issuer`, `--audience`, `--claim`, `--jwks-uri`, `--max-token-age`, `--max-access-token-ttl`, `--max-agents`, `--agent-claim`, `--platform-admin`, `--replace` |
+| `loom bot list` | 활성 상태이거나 비활성화된 모든 봇. | |
+| `loom bot disable` | 봇의 증명을 거부하고 봇이 가진 토큰을 폐기합니다. | `--name` |
+| `loom doctor` | 부팅 전 설정 오류(Python 버전, 설정, JWT, CH 연결 가능 여부)를 진단하고, /v1/health가 전달하는 문제 목록을 각각의 해결 방법과 함께 출력합니다. | `--json`, `--client`, `--server-url`, `--token` |
+| `loom report` | 버그 양식의 Environment 필드를 출력합니다. 버전과 `loom doctor` 검사 결과가 포함됩니다. | `--open` |
+| `loom drops` | 네임스페이스의 메모리 수집 드롭 원장(loom.memory_drops)을 단계/사유별로 출력합니다. 파이프라인이 버리거나, 잘라내거나, 포기한 항목입니다. | `--namespace`, `--org`, `--hours` |
+| `loom namespaces-gc` | 임시 네임스페이스를 나열(기본값)하거나 삭제합니다. 대상은 벤치 접두사 아래에서 완료된 벤치 실행 중 아무도 등록하지 않았고 --idle-hours 동안 아무도 쓰지 않은 것이며, 목록 단위의 삭제 saga 하나로 처리합니다… | `--org`, `--prefix`, `--namespace`, `--exclude-prefix`, `--idle-hours`, `--include-registered`, `--erase`, `--no-purge`, `--skip-external`, `--batch`, `--show`, `--requester`, `--worker-pass` |
+| `loom erasure-re-verify` | 실패한 삭제 saga를 다시 검증합니다. 각 saga의 마지막 단계 이름이 붙은 사유와 새 잔여물 집계를 출력하며(기본값, 읽기 전용), --resume은 복구 워커가 멈춘 체크포인트부터 다시 실행합니다… | `--org`, `--id`, `--resume`, `--skip-external`, `--completed-since`, `--orphan-graph`, `--erase`, `--batch`, `--show`, `--requester` |
+| `loom reconcile` | ClickHouse 또는 Postgres를 복원한 뒤, 복원 시점 이후 나머지 저장소(ClickHouse 또는 Postgres)가 기록한 삭제와 개인정보 보호를 위한 명시적 제거·마스킹(redaction)을 복원된 저장소에서 다시 실행하고, (ClickHouse 복원 후에는) 모든 항목을 다시 게시합니다… | `--restored`, `--point`, `--allow-live`, `--apply`, `--dry-run` |
+| `loom router` | 배포의 셀 앞단에 있는 라우터. | |
+| `loom router serve` | 배치, 조회, 운영자 API를 제공하고 그 외의 요청은 셀로 라우팅합니다. | `--host`, `--port`, `--log-level` |
+| `loom router migrate` | 디렉터리의 대기 중인 마이그레이션을 적용합니다. | |
+| `loom cell` | 라우터의 디렉터리를 통해 배포의 셀을 운영합니다. | |
+| `loom cell credential` | 라우터 자격 증명을 만들거나 셀의 자격 증명을 교체합니다. | ``, `--cell`, `--next`, `--finish`, `--revert`, `--operator`, `--router` |
+| `loom cell limit` | 셀이 새 조직을 받지 않도록 닫거나, 다시 열거나, 제한합니다. | `--cell`, `--closed`, `--open`, `--placements-max`, `--router` |
+| `loom cell which` | 조직에 대한 조회 결과의 셀과 호스트를 출력합니다(배치되지 않았으면 첫 번째 셀). | `--org`, `--router` |
+| `loom cell remove` | 배치 없이 연결된 셀의 디렉터리 행을 제거합니다. | `--cell`, `--router` |
+| `loom cell prepare` | 이 셀을 라우터의 디렉터리에 등록하고 해당 행을 기록합니다. | `--cell`, `--host`, `--credential-sha256`, `--probe-url`, `--wait`, `--router` |
+| `loom tracker-probe` | 트래커 소스와의 읽기 전용 첫 접촉: 자격 증명별 업스트림 테이블마다 개수와 최신 타임스탬프, 차단기 상태, 구성된 트래커 네임스페이스를 보여줍니다. | |
+| `loom tracker-contract-check` | 읽기 전용: 각 트래커 소스의 스키마가 레코드 계약(docs/features/tracker/record-contract.md)을 충족하는지 확인합니다. | `--source`, `--namespace`, `--json` |
+| `loom tracker-dupcheck-fit` | 한 트래커 네임스페이스에 대해 tracker.duplicate_check의 보정된 신뢰도를 지금 다시 적합합니다. 등록 시점의 중복 정답을 재생하고, 적합하여 결과를 저장합니다. | `--namespace`, `--org`, `--negatives`, `--dry-run`, `--out` |
+| `loom tracker-embed-reset` | 한 트래커 네임스페이스의 tracker_embed 패스 커서를 지워, 다음 패스가 구간을 다시 훑고 텍스트 레시피가 바뀐 모든 항목을 다시 임베딩하게 합니다. | `--namespace`, `--org`, `--kind`, `--apply`, `--dry-run` |
+| `loom namespaces-adopt` | 라이브 메모리를 보유하지만 레지스트리 행이 없는 네임스페이스에 소유자 행을 부여합니다. 벤치 접두사 아래에서는 kind=bench, 그 외에는 memory이며, retention_days는 0이고 TTL은 없습니다. | `--org`, `--owner`, `--prefix`, `--namespace`, `--kind`, `--apply`, `--dry-run`, `--show` |
+| `loom sensitivity-sweep` | 민감도 탐지기가 쓰기 시점에 레이블을 붙였어야 하지만 어떤 경로에서 건너뛴 라이브 행에 레이블을 붙입니다. | `--org`, `--namespace`, `--since-days`, `--limit`, `--show`, `--only-shape`, `--apply`, `--dry-run` |
+| `loom integrity-repair` | 행 단위 무결성 게이지(벡터를 가진 dim-0 행, tombstoned_at/status 불일치, valid_to가 지난 활성 행)를 읽고, --apply를 쓰면 dim-0 행을 실제 차원으로 다시 내보내 검색이… | `--org`, `--namespace`, `--limit`, `--show`, `--apply`, `--dry-run` |
+| `loom rechunk` | 저장된 콘텐츠에서 네임스페이스의 지식 문서를 현재 청커로 다시 청킹하고 다시 임베딩하여, 모든 문서가 섹션 메타데이터, 청크 컨텍스트, 문서 빈도를 갖게 합니다. | `--org`, `--namespace`, `--source-uri`, `--apply`, `--dry-run` |
+| `loom export-actions` | 오퍼레이션 레지스트리에서 파생된 액션 스키마를 내보냅니다. loom 확장이 포함된 MCP tools/list 매니페스트(json) 또는 정책 게이트웨이가 표면을 통제하는 데 쓰는 Cedar 스키마(cedar)입니다. | `--format`, `--output` |
+| `loom lexical-stats-rebuild` | 네임스페이스의 라이브 행에서 BM25 문서 빈도를 다시 계산합니다(용어 빈도 뷰는 삽입만 보므로, 대체와 삭제 표시가 오래된 어휘를 남깁니다). | `--org`, `--namespace`, `--no-knowledge`, `--no-memory` |
+| `loom version` | 설치된 Loom 버전을 출력합니다. | |
+| `loom install` | Loom을 로컬 AI 클라이언트의 설정에 연결합니다. | `--client`, `--server-url`, `--token`, `--name`, `--toolset`, `--dry-run`, `--force` |
+| `loom demo` | 처음 5분: 이 저장소의 AGENTS.md(또는 --file)를 `make ingest`와 같은 방식으로 지식 플레인에 수집하고, 질문을 던져 근거 행과 함께 답변을 출력합니다. | `--file`, `--question`, `--tags`, `--base-url`, `--token`, `--org`, `--namespace`, `--root`, `--search-only` |
+| `loom init` | Loom 서버에 ID를 만듭니다. | `--agent`, `--server-url`, `--org`, `--purpose`, `--ttl-days`, `--token-path`, `--config-path`, `--no-files`, `--json` |
+| `loom ingest-transcript` | 대화 기록 파일(markdown / JSON)을 하나의 스레드로 Loom의 대화 테이블에 파이프합니다. | `--server-url`, `--token`, `--org`, `--namespace`, `--agent`, `--thread-id`, `--file`, `--dry-run` |
+| `loom memory-search` | 셸에서 memory.search를 실행합니다. | `--server-url`, `--token`, `--org`, `--namespace`, `--agent`, `--user-id`, `--query`, `--top-k`, `--search-mode`, `--json-agent` |
+| `loom set-host` | 이 배포의 Loom 호스트를 지정합니다. | ``, `--env-file`, `--append`, `--dry-run` |
+| `loom login` | 일회용 코드로 어떤 브라우저에서든 Loom 서버에 로그인합니다. | |
+| `loom logout` | 서버에서 저장된 세션을 종료하고 이곳에서도 삭제합니다. | |
+| `loom whoami` | 저장된 세션이 어떤 사용자로 로그인하는지 보여줍니다. | |
+| `loom call` | 저장된 세션으로 임의의 오퍼레이션이나 API 라우트를 호출합니다(`loom call --help`). | |
+| `loom token` | CI와 에이전트를 위해 본인의 토큰을 만들고, 나열하고, 폐기합니다(`loom token --help`). | |
+
+
+
+
+
+
+## 관련 문서
+
+- [운영 레퍼런스](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md): 클라이언트 명령이 호출하는 op입니다.
+- [유지 관리](https://github.com/ClickHouse/loom/blob/main/docs/operations/maintenance.md): 재임베딩, 백필, 복구를 다룹니다.
+- [코드 인덱스 운영](https://github.com/ClickHouse/loom/blob/main/docs/operations/code-index-operations.md).
+- [업그레이드](https://github.com/ClickHouse/loom/blob/main/docs/operations/upgrades.md): 업그레이드 절차에서 `loom migrate`를 사용하는 방법을 설명합니다.
+- [로컬 개발](https://github.com/ClickHouse/loom/blob/main/docs/development/local-development.md).
diff --git a/i18n/.pending/pt-BR/docs/architecture/system-overview.md b/i18n/.pending/pt-BR/docs/architecture/system-overview.md
new file mode 100644
index 0000000000..53cd1d3b5d
--- /dev/null
+++ b/i18n/.pending/pt-BR/docs/architecture/system-overview.md
@@ -0,0 +1,494 @@
+
+> Esta página é uma tradução automática da [página em inglês](https://github.com/ClickHouse/loom/blob/main/docs/architecture/system-overview.md), que prevalece.
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/architecture/system-overview.md), which is authoritative.
+
+
+
+# Visão geral do sistema
+
+Loom é um servidor Python (uma aplicação FastAPI mais um supervisor de workers em segundo plano)
+e ClickHouse, com Postgres como opção para o estado ativo de memória e conhecimento. Loom mantém
+estado: tudo o que ele sabe (fatos e seus vetores, documentos, conversas, o
+grafo de entidades, o índice de código, tarefas, auditoria, custo e progresso de exclusão) é armazenado no
+ClickHouse, exceto que, com `LOOM_STORAGE_AUTHORITY=postgres`, o Postgres guarda a memória ativa,
+o estado de conhecimento e os registros associados
+([autoridade de armazenamento](storage-authority.md#the-tables)). Os processos do servidor não mantêm
+estado durável próprio, então qualquer número deles pode atender ao mesmo deployment e uma
+requisição pode chegar a qualquer um. As poucas peças de estado mantidas fora desses armazenamentos são
+listadas em [Topologia de deployment](#deployment-topology).
+
+O layout de armazenamento está em [ClickHouse](https://github.com/ClickHouse/loom/blob/main/docs/architecture/clickhouse.md).
+
+
+
+## Objetivos e não objetivos
+
+| Objetivos | Não objetivos |
+| --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| Um único mecanismo para todo tipo de estado (autoridade do ClickHouse): vetores, texto completo, arestas de grafo, séries temporais e ledgers. | Formatos de arquivo no servidor: `knowledge.add` recebe `content: str`; fazer o parsing é tarefa da CLI. |
+| Uma única superfície de comunicação, declarada uma vez e servida da mesma forma via HTTP e MCP. | Transações entre tabelas. As linhas derivadas se atualizam depois da gravação primária. |
+| Os processos do servidor não mantêm estado durável: para aumentar a capacidade web, basta executar mais deles. | Histórico bitemporal. A validade considera apenas o tempo de validade; o histórico de tempo de transação é o espelho de versões. |
+| Toda linha é atribuível a um tenant (tupla de identidade), a um autor da escrita (`actor`) e a uma requisição (`log_comment`). | Garantia de conformidade com a GDPR. O apagamento e o hash de auditoria são primitivas de engenharia. |
+| Uma instalação sem chaves que inicia e responde, com os provedores falsos sendo informados. | |
+
+
+
+## Componentes
+
+```mermaid
+flowchart TB
+ clients["Clients MCP · HTTP · SDKs · dashboard"]
+ subgraph cp["Control-plane process (FastAPI)"]
+ transports["Transports server/transport"]
+ auth["Auth server/auth"]
+ registry["Operation registry server/operations"]
+ app["Domain handlers server/<domain>/app"]
+ domain["Domain logic server/<domain>/domain"]
+ store["Domain stores + client server/<domain>/store · server/core/ch.py"]
+ workers["WorkerSupervisor server/workers · server/<domain>/workers"]
+ obs["Observability server/observability"]
+ end
+ providers["Providers server/embedding · server/llm"]
+ ch[("ClickHouse database loom")]
+ clients --> transports
+ transports --> auth
+ transports --> registry --> app --> store --> ch
+ app --> domain
+ store --> domain
+ workers --> app
+ app --> providers
+ transports --> obs
+ obs --> ch
+```
+
+| Componente | Código | Função |
+| ------------------ | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Transportes | `server/transport/http.py`, `server/transport/mcp.py` | Transformam uma requisição em uma chamada de operação. Ambos são gerados a partir do registro: toda op é `POST /v1/` e a ferramenta MCP `loom_` (os pontos viram sublinhados). A admissão compartilhada fica em `server/transport/gates.py`. |
+| Registro de operações | `server/operations/` | Uma `Operation` por op (`base.py`): nome, modelos de entrada e saída, handler, `required_role`, `idempotent`, `audit`, `maturity` e flags de escopo; seu `budget_p99_ms` vem da tabela de orçamentos em `server/settings/catalog.py`. O `ALL_OPERATIONS` de `registry.py` reúne o `OPERATIONS` de cada grupo. |
+| Pacotes de domínio | `server//` | Um pacote por plano (`memory`, `code`, `tracker`, `knowledge`, `erasure`, `tasks`, `identity`, `insights`), cada um com `api/` (modelos de wire e declarações de `Operation`), `app/` (handlers e orquestração), `domain/` (lógica pura), `store/` (instruções ClickHouse e construtores de linhas) e `workers/`. Veja [organização do servidor](server-layout.md). |
+| Cliente ClickHouse | `server/core/ch.py` | O cliente único: pool de conexões, prazos, novas tentativas, atribuição de consultas. `server/memory/store/rows.py` contém os construtores de linhas de versão. |
+| Workers | `server/workers/` | Loops em segundo plano declarados como linhas em `registry.py` (`_WORKERS`), cada um um módulo em `workers/` do seu domínio, executados por `supervisor.py`. |
+| Auth | `server/auth/` | Verificação de JWT, revogação, autorização por papel e namespace, OIDC, o servidor OAuth e o autocadastro. Veja [segurança](https://github.com/ClickHouse/loom/blob/main/docs/architecture/security.md). |
+| Providers | `server/embedding/`, `server/llm/` | Clientes plugáveis de embedder e de LLM, cada um com um fake determinístico. Veja [arquitetura de LLM](https://github.com/ClickHouse/loom/blob/main/docs/architecture/llm-architecture.md). |
+| Observabilidade | `server/observability/` | O registro por op (`loom.agent_events`), o fluxo de eventos em lote, linhas de auditoria, saúde dos providers, exportação para OpenTelemetry e Langfuse. |
+| Painel | `frontend/` (servido de `frontend/dist/` em `/`) | Interface React sobre as mesmas ops HTTP. Um checkout sem build responde às suas páginas com 503. |
+| CLI | `server/cli/` | O comando `loom`: ações de operador (migrate, tokens, re-embed, doctor) e um cliente das ops. Veja a [referência da CLI](https://github.com/ClickHouse/loom/blob/main/docs/reference/cli.md). |
+
+O registro é toda a superfície de wire. `GET /v1/operations` lista cada op com seu
+orçamento e papel, e a [referência de operações](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md) é gerada
+a partir dele. Para adicionar uma op, defina os modelos, escreva o handler, declare a `Operation` e
+acrescente-a à lista `OPERATIONS` do seu grupo
+([adicionando uma operação](https://github.com/ClickHouse/loom/blob/main/docs/development/adding-an-operation.md)). Ambos os transportes a incorporam.
+
+Algumas rotas HTTP não são ops do registro: `/v1/health`, `/v1/whoami`, `/v1/operations`,
+`/v1/.well-known/jwks.json`, `/v1/.well-known/openid-configuration`, `/v1/knowledge.download`, `/v1/auth/login`, os auxiliares
+`/v1/me/*` e `/v1/admin/*` do painel, e os endpoints OAuth e OIDC. A
+[referência da API HTTP](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md) os lista.
+
+
+
+### Direção das dependências
+
+```text
+transports → operations → /api → /app → /store → server/core/ch.py
+ ↘ /domain ↙
+```
+
+Os workers ficam ao lado dos transportes e chamam o `app` e o `store` do seu domínio. Os handlers
+chamam os providers. Nada abaixo dos transportes importa um módulo de transporte. Qual pacote
+pode importar qual, e as camadas dentro de um domínio, estão em [organização do servidor](server-layout.md);
+`tests/unit/test_package_contracts.py` as faz valer.
+
+`tests/unit/test_transport_layering.py` faz valer a regra dos transportes: ele falha quando
+qualquer coisa fora de `server/transport/`, `server/cli/` e `server/main.py` importa
+`server.transport`. Por isso as peças de que as camadas inferiores precisam ficam abaixo do transporte: os
+conjuntos de ferramentas MCP (`server/operations/toolsets.py`), a verificação de bearer das rotas fora do registro
+(`server/auth/bearer.py`), a variável de contexto de escopo de código (`server/code/domain/scope.py`),
+o construtor de linhas do registro (`server/observability/ledger.py`), os orçamentos de latência
+(`server/observability/budgets.py`) e os padrões do plano (`server/code/app/common.py`).
+
+**Por quê:** só o transporte conhece os protocolos (códigos de status, frames JSON-RPC,
+cabeçalhos). Assim, um handler pode ser chamado por HTTP, MCP, um worker ou um teste com o mesmo
+modelo de entrada.
+
+
+
+## Caminho da requisição
+
+Os dois transportes executam as mesmas decisões de admissão, tomadas uma única vez em `server/transport/gates.py`.
+Eles diferem na forma de ler credenciais e argumentos e de apresentar uma recusa:
+o HTTP responde com um status e um corpo `detail`, o MCP com um resultado que carrega `isError`.
+
+
+
+### HTTP
+
+`build_router()` em `server/transport/http.py` adiciona uma rota `POST /v1/` por op.
+O `BodyLimitMiddleware` recusa primeiro um corpo acima de `LOOM_MAX_REQUEST_BYTES` (32 MiB) com 413;
+0 desativa o limite. Cada requisição passa então por estas fases, em ordem (`_make_endpoint`). Uma
+recusa encerra a requisição.
+
+| Fase | Código | Recusa |
+| -------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Início | `_begin_request` | Nenhuma. Define `X-Request-Id` (o do chamador quando tem de 1 a 64 letras, dígitos, `.`, `_` ou `-`, senão um UUID novo), `X-Schema-Version` e a tag de consulta `" "`. |
+| Verificar token | `_extract_auth` | 401 `AUTH_INVALID` (ausente quando a autenticação está ativa, esquema desconhecido, token que falha); 503 `AUTH_UNAVAILABLE` até que a lista de revogação seja carregada. |
+| Ler corpo | `_read_body` | 400 `VALIDATION_FAILED` em JSON inválido; 422 `UNKNOWN_ARGUMENT` quando uma chave desconhecida de uma op de escrita é parecida com um de seus campos. |
+| Preencher identidade | `gates.with_single_user_identity` | Nenhuma. Em um servidor de usuário único, para uma chamada sem token: a org da instalação em toda op, exceto `code.*` e `tracker.*`, e seu namespace e o agente da op nas ops cotidianas de memória e busca ([quais ops](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#request)); um namespace vazio ou `"-"` em qualquer outra op que exija um, exceto ops de code e tracker, é descartado, de modo que a validação o recusa como ausente. Somente HTTP. |
+| Validar | `_validate_payload` | 422 `VALIDATION_FAILED` indicando os campos. |
+| Autorizar | `_authorize` → `gates.authorize` | 400 `IDENTITY_INCOMPLETE` (sem namespace ou org), 403 `AUTH_INSUFFICIENT`. |
+| Vincular contexto, política | `_bind_context_and_policy` | Define o contexto de autenticação e a execução no ledger (`X-Loom-Run-Id`); 403 `POLICY_FORBIDDEN` quando uma política de histórico nega no modo `enforce`. |
+| Limite de taxa | `_rate_limit` → `gates.rate_limit` | 429 `RATE_LIMITED` com `Retry-After`; cabeçalhos `X-RateLimit-*` em toda chamada limitada. |
+| Idempotência | `_idempotency_gate` | Reenvia uma resposta armazenada (`X-Idempotent-Replay: true`), ou 409 `IDEMPOTENT_CONFLICT` quando a chave é reutilizada com um corpo diferente. |
+| Handler | `_run_handler` | A `HTTPException` do handler, o código e o status de um `LoomServerError`, ou 500 `INTERNAL_ERROR`. |
+| Após o sucesso | `_finish_success`, `post_handler_rows` | Nenhuma. Linha do ledger, métricas, o corpo com `ignored_args`, depois as linhas de violação de orçamento, auditoria e idempotência. |
+
+Por que esta ordem:
+
+- **Token antes do corpo.** Uma requisição anônima que a implantação recusa recebe o 401
+ antes de seu corpo ser lido. Ela não deixa linha no ledger, não descobre erros de campo e não toca
+ o bucket de limite de taxa de nenhum tenant.
+- **Autorizar antes de limitar.** O limitador usa a org do token verificado
+ (`gates._rate_limit_org`), nunca apenas um valor do corpo.
+- **Idempotência após a admissão.** A chave de replay é restrita à org, ao subject e à op do chamador
+ (`server/core/idempotency.py`, `scoped_key`). Um replay nunca chega a um chamador anônimo,
+ a outro tenant ou a outra op.
+
+**Gates que falham abertos.** A classificação de tráfego e o limitador de taxa são controles
+de disponibilidade. Quando qualquer um deles lança uma exceção, a chamada é admitida e a falha é contada e registrada
+no máximo uma vez por minuto (`gates._fail_open`). Autenticação e autorização falham fechadas.
+
+**Argumentos desconhecidos.** Os modelos de entrada ignoram chaves desconhecidas, então `server/transport/arg_check.py`
+as nomeia: a resposta traz `ignored_args` (e `did_you_mean` para um nome de campo
+parecido), e o HTTP define `X-Loom-Ignored-Args`. Ambos listam primeiro qualquer campo que a op leu mas
+decidiu não aplicar, depois as chaves não lidas. Uma op de escrita recusa uma correspondência próxima com 422
+`UNKNOWN_ARGUMENT`. Chaves de identidade e chaves que o próprio transporte lê (`consumer`,
+`traffic_class`, `explain`, a chave de idempotência) nunca são reportadas.
+
+**Após o handler.** A linha do ledger traz a latência e o gasto de embedding e de LLM
+da chamada. A linha de violação de orçamento (acima de `budget_p99_ms` × `LOOM_LATENCY_BUDGET_MULTIPLIER`),
+a linha de auditoria (quando `op.audit`) e a linha de idempotência vão em uma única ida e volta
+(`gather_best_effort`). Cada uma é de melhor esforço. Toda instrução ClickHouse da requisição
+carrega `log_comment = " "` ([atribuição de consultas](https://github.com/ClickHouse/loom/blob/main/docs/architecture/clickhouse.md#query-attribution)).
+
+
+
+### MCP
+
+`POST /mcp` é JSON-RPC 2.0 (`server/transport/mcp.py`, `_handle_request`). Ele atende as
+revisões de protocolo em `MCP_SUPPORTED_PROTOCOL_VERSIONS` (`mcp_config.py`); `initialize`
+devolve a versão do cliente quando suportada e a mais recente caso contrário. Não há
+eventos iniciados pelo servidor.
+
+| Método | O que faz |
+| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `initialize` | Negocia a versão e retorna `instructions`: o primer, com as seções do perfil do chamador. O mesmo primer é o recurso `loom://primer`, o prompt `loom` e a ferramenta `loom_activate`. |
+| `tools/list` | O roster do toolset da conexão (depende da URL, nunca do chamador). |
+| `tools/call` | Uma chamada de op pelos mesmos gates do HTTP. |
+| `prompts/*`, `resources/*`, `ping` | As superfícies do primer e a verificação de disponibilidade. |
+
+`LOOM_MCP_AUTH_MODE` decide quais métodos exigem um bearer: `required` (padrão, todo método
+exceto notificações), `discovery_only` (apenas `tools/call`) ou `open`. Uma recusa carrega um
+desafio `WWW-Authenticate` apontando para os metadados do recurso protegido, para que um
+conector nativo encontre o servidor OAuth (`mcp_auth.py`).
+
+`tools/list` mostra o roster escolhido por `LOOM_MCP_TOOLSET` (padrão `core`) ou `?toolset=`
+(`server/operations/toolsets.py`). Um roster é apenas visibilidade: toda op continua chamável
+pelo nome, exceto as ops em `_MCP_HIDDEN_OPS`, que o MCP não lista nem chama (o HTTP ainda
+as atende). Os toolsets estão na [referência do MCP](https://github.com/ClickHouse/loom/blob/main/docs/reference/mcp.md). Três ferramentas
+têm descritores escritos à mão: `loom_search` (a op `search.query`, apresentada como um resumo
+em texto mais as seções enxutas), `loom_op` (chama qualquer op pelo nome pelo mesmo caminho;
+`op: "help"` as lista, `server/transport/mcp_op.py`) e `loom_activate` (o primer,
+a única ferramenta que não é uma op do registro).
+
+`_call_tool` (`mcp_call.py`; a telemetria, a resposta e a resposta de falha em
+`mcp_outcome.py`) executa estas fases em ordem:
+
+1. **Resolver a ferramenta** (`_resolve_tool`). Uma ferramenta desconhecida ou oculta é um resultado
+ `isError` dizendo o que usar no lugar.
+2. **Vincular o chamador** (`_bind_caller_identity`). Gera o id da requisição, define a tag de consulta
+ e preenche namespace e agente omitidos a partir do token e do padrão salvo do chamador.
+ Argumentos explícitos prevalecem. As ops `code.*` usam por padrão o namespace de code da implantação. As
+ leituras em `_MCP_CROSS_AGENT_READS` usam `*` como padrão para `agent`.
+3. **Execução da sessão.** Uma execução implícita por (org, subject do token, `Mcp-Session-Id`), registrada no
+ namespace padrão do chamador: uma escrita que não nomeia execução recebe o `run_id` da sessão,
+ exceto `run.*`, que nomeia a própria execução, `code.*`, que age como a identidade de code da implantação,
+ e `working_memory.*` e `conversation.update`, em que `run_id` delimita
+ ou vincula a linha.
+4. **Chave de idempotência.** Uma ferramenta idempotente aceita `_idempotency_key` (ou `idempotency_key`)
+ em seus argumentos, removida antes da validação.
+5. **Argumentos** (`_validated_input`). A recusa de argumento com erro de grafia, depois a validação. Uma
+ falha é um resultado `isError` com os erros de campo, o campo provavelmente pretendido para
+ cada chave desconhecida, os argumentos da op e um exemplo de chamada (`arg_feedback.py`).
+6. **Autorizar** (`_authorize_call`), o gate compartilhado.
+7. **Admissão** (`_admission_refusal`): classe de tráfego, política de histórico, limite de taxa. Em um 429
+ com uma dica curta, o transporte espera uma vez e verifica de novo (no máximo
+ `LOOM_MCP_RATELIMIT_RETRY_MAX_WAIT_S`).
+8. **Replay de idempotência**, apenas para um chamador admitido.
+9. **Handler.**
+10. **Resposta.** `structuredContent` descarta detalhes de ranking e contabilidade
+ (`lean_results.py`; `explain=true` os mantém) e carrega `ignored_args`.
+
+**Recusas são resultados, falhas são erros.** Um 4xx diferente de 401 (`LOCKED`,
+`PINNED_CONFLICT`, `BLACKLISTED`, `RESOURCE_NOT_FOUND`, um código de estado de tarefa, `RATE_LIMITED`)
+volta como `isError: true` com o corpo estruturado (`mcp_refusals.py`), para que o cliente
+veja a orientação. Um 401 e um 5xx (`OVERLOADED`, `BACKEND_TIMEOUT`, `SCHEMA_PENDING`) permanecem
+erros JSON-RPC com o corpo e a dica de nova tentativa do HTTP.
+
+Os passo a passo de uma escrita (`memory.set`) e de uma leitura (`memory.search`) estão na
+[arquitetura de memória](memory-architecture.md).
+
+
+
+## Papéis e modos de processo
+
+
+
+### Papéis
+
+`Role` (`server/operations/base.py`) é ordenado como `VIEWER < WRITER < ADMIN < ORG_ADMIN <
+PLATFORM_ADMIN`. Cada op declara seu `required_role`. Os papéis de um token flat se aplicam a todo
+namespace que ele lê, e `loom.namespace_grants` pode elevar esse papel em um namespace, nunca
+reduzi-lo. Os `ns_roles` de um token com escopo são autoritativos para os namespaces que eles nomeiam.
+Grants e `ns_roles` carregam apenas `viewer`, `writer` ou `admin`; `ORG_ADMIN` e
+`PLATFORM_ADMIN` existem apenas nos `roles` de um token flat. Veja
+[segurança](https://github.com/ClickHouse/loom/blob/main/docs/architecture/security.md#authorization) e
+[identidades e namespaces](https://github.com/ClickHouse/loom/blob/main/docs/concepts/identities-and-namespaces.md).
+
+
+
+### Modos de processo
+
+Uma única imagem atende a todos os papéis. As configurações decidem o que um processo faz:
+
+| Modo | Configurações | O que executa |
+| ------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| All-in-one | `LOOM_BACKGROUND_WORKERS=auto` (padrão) | Camada web e os workers no processo que detém o lease do ClickHouse da implantação. |
+| Réplica web | `LOOM_BACKGROUND_WORKERS=off` | HTTP, MCP e o painel. Atualiza seu próprio snapshot de revogação e seu próprio keyring de assinatura. |
+| Workers | `LOOM_BACKGROUND_WORKERS=auto`, `LOOM_DEPLOYMENT=1`, `LOOM_SERVES_TRAFFIC=false` | O supervisor e seus workers; `/v1/health` continua respondendo. |
+| Servidor de branch / A-B | `LOOM_BOOT_MIGRATE=false`, `LOOM_INSTANCE_LABEL=::` | Atende um ClickHouse compartilhado sem aplicar migrations; `auto` não executa workers nele. |
+
+`LOOM_WEB_WORKERS` define os processos uvicorn por contêiner (sem definir, a imagem inicia um por
+CPU que o contêiner pode usar, no máximo um por GiB de memória e no máximo 8). Cada um executa o
+lifespan completo; em `auto`, o lease da implantação escolhe o processo que executa os workers. `on`
+não pega lease: cada processo executa sua própria cópia dos workers e, a menos que um processo `auto`
+detenha o lease, os outros reportam `workers_lease_absent`. Um contêiner de workers executa `auto`.
+
+**Eleição de líder.** `server/workers/leader.py` (`decide_supervisor`, `keep_lease`) elege
+um supervisor por implantação por meio do ClickHouse: a chave `workers_supervisor` na tabela de
+lock do Keeper `loom._migration_lock` (KeeperMap estrito, então, entre dois concorrentes, uma escrita
+vence). A expiração é
+julgada pelo relógio do servidor ClickHouse. O detentor renova a cada
+`LOOM_SUPERVISOR_LEASE_TTL_S / 6` e para seus workers metade do TTL após sua última
+renovação, ou quando uma renovação encontra outro detentor; quando o detentor morre, outro processo `auto`
+assume o lease após `LOOM_SUPERVISOR_LEASE_TTL_S` (padrão 30 s). Os tempos
+estão em [falha e recuperação](failure-and-recovery.md#background-workers). Uma parada graciosa o libera imediatamente, e é
+assim que a nova cor de um par blue/green assume.
+
+**Por que ClickHouse:** os processos que podem executar os workers abrangem contêineres e hosts,
+e o ClickHouse é a única coisa que todos compartilham. Vários hosts podem executar `auto`; um executa os
+workers ([capacidade](failure-and-recovery.md#background-workers)).
+
+
+
+## Inicialização
+
+O `lifespan` em `server/main.py` roda em todo processo, nesta ordem (seus passos ficam em
+`server/boot.py`):
+
+1. **Regra de lançamento.** Um processo é o deployment (`LOOM_DEPLOYMENT=1`, definido pelos
+ arquivos compose) ou carrega um `LOOM_INSTANCE_LABEL` não vazio; caso contrário, ele se recusa a iniciar. Um
+ deployment que exige autenticação com o `LOOM_JWT_SECRET` de desenvolvimento versionado no repositório também se recusa
+ (`require_real_signing_secret`); somente `LOOM_INSTANCE_LABEL=deploy:dev` é isento.
+2. **Conectar** ao ClickHouse.
+3. **Migrar** (`LOOM_BOOT_MIGRATE`, ativado por padrão). Todo processo obtém o lock de migração
+ do deployment antes de aplicar: uma chave KeeperMap em `loom._migration_lock`
+ (`server/core/schema/migrate_lease.py`). Um servidor sem Keeper, ou uma migração com falha,
+ interrompe a inicialização. Com `LOOM_BOOT_MIGRATE=false`, o processo registra em log os arquivos pendentes e
+ os informa em `/v1/health`. Sob a autoridade Postgres, lê o estado de células do deployment
+ antes do primeiro heartbeat e da decisão de lease; uma falha na primeira leitura interrompe
+ a inicialização (com migrações do Postgres pendentes, ele inicia bloqueado e não pronto até que uma leitura
+ seja concluída) ([células](cells.md#the-tenancy-check-and-placement)).
+4. **Iniciar o emissor de `agent_events`.**
+5. **Namespace padrão.** Com a autenticação desativada, cria para o namespace configurado sua
+ linha em `loom.namespaces`, a menos que o gate de célula recuse este processo.
+6. **Eleger o líder dos workers.**
+7. **Tarefas do líder.** Aplica as substituições de TTL de retenção onde diferem e registra os
+ namespaces de tracker configurados.
+8. **Estado de tokens e substituições.** Carrega o snapshot de tokens revogados
+ (`server/auth/revocation.py`) e o chaveiro de assinatura (`server/auth/keyring.py`); todo
+ processo atualiza ambos em seu próprio temporizador. Começa a adotar as substituições de runtime do admin
+ (`loom.runtime_overrides`: limites de taxa, orçamentos de latência e configurações em tempo real) a cada
+ `LOOM_RUNTIME_OVERRIDES_REFRESH_SECONDS`; o processo filho dos workers também as adota. A
+ substituição de uma configuração em tempo real é aplicada sobre os `settings` do próprio processo, então o código a lê como
+ `settings.` ([configurações de runtime](https://github.com/ClickHouse/loom/blob/main/docs/operations/runtime-settings.md)).
+9. **Iniciar os workers** no líder, e o loop de lease em `auto` (e em `on` sob
+ a autoridade Postgres, onde o gate de célula os inicia e os para).
+10. **Relatório de provedor.** Registra em log o provedor de LLM resolvido e sonda a dimensão do embedder.
+11. **Recursos de vetor.** Sonda a configuração de leitura de códigos quantizados, os patch parts e se
+ os inserts podem pular a construção do índice vetorial.
+12. **Calibrar** os limiares de similaridade a partir do embedder (`LOOM_ADAPTIVE_THRESHOLDS`). Uma
+ falha nunca derruba a inicialização; as configurações escalares são aplicadas.
+
+O encerramento inverte essa ordem: para os loops, drena os workers (10 s), libera o lease, drena
+a fila do Langfuse, o emissor de eventos e as escritas adiadas (linhas de exposição,
+projeções pós-escrita, o stream de eventos). O cliente do ClickHouse desconecta por último.
+
+`/v1/health` informa a acessibilidade do ClickHouse e uma lista `problems` (por exemplo, um provedor
+falso). Ele responde 503 somente quando o ClickHouse está fora do ar;
+`?include=workers,langfuse,otel,embedding_cache` adiciona verificações por subsistema.
+
+
+
+## Processamento em segundo plano
+
+`WorkerSupervisor` executa uma task asyncio por worker habilitado, apenas no detentor do lease. Cada worker é uma linha `_Worker` em `server/workers/registry.py` com um flag de habilitação e um intervalo (`LOOM__ENABLED`, `LOOM__INTERVAL_SECONDS` na maioria dos casos). O supervisor escalona as primeiras execuções, cancela uma execução que passa do prazo, tenta novamente com backoff, marca cada consulta com `worker.` na classe de tráfego `background` e registra o estado de cada execução em `loom.worker_status` (`GET /v1/admin/workers.status`). Consulte [falha e recuperação](failure-and-recovery.md#worker-supervision) e a [referência de workers](https://github.com/ClickHouse/loom/blob/main/docs/reference/workers.md) gerada.
+
+
+
+## Topologia de implantação
+
+```mermaid
+flowchart LR
+ lb["nginx proxy :7777 dev/docker-compose.proxy.yml"]
+ subgraph blue["colour blue"]
+ bw["loom-blue web, workers=off"]
+ bk["loom-blue-workers workers=auto"]
+ end
+ subgraph green["colour green (idle)"]
+ gw["loom-green"]
+ gk["loom-green-workers"]
+ end
+ shared[("loom-shared volume rate-limit buckets")]
+ ch[("ClickHouse Cloud or OSS")]
+ lb --> bw
+ bw --> ch
+ bk --> ch
+ gw -.-> ch
+ bk --- shared
+ gk -.- shared
+```
+
+- **Os processos do servidor não mantêm estado durável.** O estado compartilhado entre réplicas (revogações, chaves de assinatura, substituições em tempo de execução, contagens de tentativas de login, marcas de escrita do grafo, o lease do supervisor, checkpoints de remoção, a versão da blacklist, o cache de idempotência sob a autoridade padrão, a autoridade registrada) e os originais dos documentos enviados ficam no ClickHouse; os bytes dos documentos gravados com `LOOM_DOCUMENT_OBJECT_STORE=s3` ficam, em vez disso, em um bucket compatível com S3. Sob a autoridade Postgres, o Postgres guarda as tabelas listadas em [autoridade de armazenamento](storage-authority.md#the-tables), entre elas o cache de idempotência, seu próprio registro de remoção e uma cópia da autoridade registrada. Um novo Loom com o mesmo ClickHouse (e Postgres, sob essa autoridade), a mesma configuração de env e o mesmo `LOOM_JWT_SECRET`, além do bucket enquanto houver linhas que apontem para objetos nele, recupera todos os recursos.
+- **Estado fora do ClickHouse e do Postgres.** Os espelhos git do plano de código em `var/code_repos` (um cache: um host sem eles clona novamente) e os buckets de rate limit no volume `loom-shared`, nenhum dos quais é o sistema de registro; e, enquanto qualquer linha do catálogo apontar para um objeto nele, o `LOOM_DOCUMENT_S3_BUCKET`, que guarda os bytes desses originais.
+- **Dois contêineres, uma imagem.** O `dev/docker-compose.cloud.yml` executa o `loom-server` (`LOOM_BACKGROUND_WORKERS=off`) e o `loom-workers` (`auto`: executa os workers enquanto detém o lease), de modo que uma passagem longa dos workers nunca divide o event loop com as requisições.
+- **Par blue/green.** O `dev/docker-compose.colour.yml` executa duas cores atrás do proxy; o `./redeploy.sh` inicia a cor ociosa, espera pela verificação de saúde, troca o upstream e para a antiga. O rollback não exige nenhuma etapa de schema, porque toda migração é aditiva. Veja [implantação](https://github.com/ClickHouse/loom/blob/main/docs/operations/deployment.md) e [atualizações](https://github.com/ClickHouse/loom/blob/main/docs/operations/upgrades.md).
+- **ClickHouse.** ClickHouse Cloud ou um servidor OSS autogerenciado. Um único nó OSS não tem alta disponibilidade.
+
+
+
+## Formas fundamentais
+
+Quatro formas sustentam a estrutura. Alterar uma delas é uma mudança de design, discutida no pull request
+e nesta página.
+
+
+
+### Um único mecanismo: ClickHouse
+
+Sob a autoridade padrão do ClickHouse, todo plano (fatos e vetores, índices BM25 e de token,
+o grafo de entidades percorrido com uma consulta limitada por salto, o índice de código,
+ledgers e custo) é um conjunto de tabelas do ClickHouse. Com
+`LOOM_STORAGE_AUTHORITY=postgres`, o estado vivo de memória e conhecimento fica no Postgres,
+o que troca um único backup e um único domínio de consistência por escritas transacionais de memória
+([por que dois armazenamentos](storage-authority.md#why-two-stores)); o Porquê e o Custo abaixo valem para
+o padrão.
+
+**Por quê:** um backup, uma fronteira de acesso, uma linguagem de consulta para recuperação e análise,
+e joins entre a memória e sua telemetria sem um job de sincronização. A recuperação híbrida roda como
+SQL junto aos dados. Um armazenamento de vetores separado adicionaria um segundo domínio de consistência,
+escritas duplas e fusão por saltos de rede.
+
+**Custo:** não há atualização transacional de linhas. As tabelas mutáveis são `ReplacingMergeTree` lidas com
+`FINAL`, de modo que todo caminho de escrita carrega todas as colunas adiante
+([a regra de escrita do FINAL](https://github.com/ClickHouse/loom/blob/main/docs/architecture/clickhouse.md#the-final-write-rule)), e as escritas entre tabelas não
+são atômicas ([falha e recuperação](failure-and-recovery.md)).
+
+
+
+### A tupla de identidade
+
+Toda linha de memória carrega `(org, namespace, agent, user_id, session_id)`: os três primeiros
+são obrigatórios, os demais têm `'-'` como padrão. Toda outra tabela de tenant carrega pelo menos
+`(org, namespace)`. Nas escritas de memória, o servidor registra `actor` (`human:` /
+`process:`, `server.memory.app.provenance.writer_actor`) e `source_class`
+(`server.memory.domain.provenance.source_class_for`), que nunca vêm do corpo, exceto um rebaixamento declarado para `derived`,
+`external` ou `imported`.
+
+**Por quê:** tenancy, autoria e proveniência são colunas, então toda leitura filtra pela chave de ordenação
+e toda linha diz de quem é e de onde veio, sem um join. **Custo:** um novo
+caminho de escrita que esqueça `actor` ou `source_class` gera uma linha sem atribuição.
+
+
+
+### Auditoria por hash de conteúdo em cada linha
+
+Toda escrita auditada deixa uma linha em `loom.audit_log` cujo `row_hash` é o SHA-256 do seu
+JSON canônico (`server/observability/audit.py`). Checkpoints a cada hora
+(`loom.audit_checkpoints`) selam a contagem de linhas de cada janela fechada e um digest dos seus hashes,
+cada um encadeado ao checkpoint anterior.
+
+**Por que por linha:** uma cadeia de linha para linha se bifurca sob escritores concorrentes, e o Loom roda
+vários processos de servidor. Hashes por linha detectam adulteração de conteúdo; a cadeia de checkpoints,
+selada por um único worker, detecta linhas excluídas, modificadas e tardias em janelas seladas. **Custo:**
+uma linha removida antes de a sua janela ser selada não deixa rastro. Veja
+[segurança](https://github.com/ClickHouse/loom/blob/main/docs/architecture/security.md#audit-log).
+
+
+
+### Cinco operações de revisão de crenças
+
+O ciclo de vida da memória tem cinco operações: Expandir (`memory.set`), Revisar
+(`memory.update_by_id`), Contrair (`memory.delete`), Reforçar (`memory.pin`) e Recusar
+(`blacklist.add`). É uma lente de design, não um enum de código: tudo no plano de memória que
+não corresponda a uma delas é suspeito. Mesclar, mover e ocultar ou remover conteúdo sensível (redact) são expressos como
+combinações dessas operações. Veja [memória](https://github.com/ClickHouse/loom/blob/main/docs/concepts/memory.md).
+
+
+
+## Invariantes
+
+- Uma op existe em HTTP e MCP se, e somente se, estiver em `ALL_OPERATIONS` (o MCP pode ocultá-la;
+ o HTTP continua atendendo).
+- Nada fora de `server/transport/`, `server/cli/` e `server/main.py` importa
+ `server.transport`.
+- Nenhum gate é executado depois de uma recusa. Uma requisição anônima nunca chega ao parser de corpo, ao
+ ledger, ao limitador nem ao cache de replay quando a autenticação está ativada.
+- O limitador de taxa usa como chave a org do token verificado. Um replay só é servido ao
+ chamador, à org e à op que o produziram.
+- A autenticação e a autorização falham de forma fechada; a classificação de tráfego e o limite de taxa
+ falham de forma aberta, com contagem.
+- Via MCP, uma recusa é um resultado com `isError: true`; apenas 401 e 5xx são erros
+ JSON-RPC.
+- Um processo é o próprio deployment ou carrega um `LOOM_INSTANCE_LABEL`. Uma migration de boot com falha
+ o interrompe antes de qualquer worker iniciar.
+- No máximo um processo do deployment detém o lease de supervisor sob `auto`.
+- O ClickHouse é o sistema de registro de toda linha do plano de memória.
+- O servidor, e não o chamador, define `actor` e `source_class` nas gravações de memória.
+
+
+
+## Pontos de entrada no código-fonte
+
+| O quê | Onde |
+| ------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| App, ciclo de vida, verificação de saúde | `server/main.py`; as etapas de boot e shutdown do ciclo de vida em `server/boot.py`; `GET /v1/health` em `server/health.py` |
+| Declaração de operação | `server/operations/base.py` (`Operation`, `Role`); registro em `server/operations/registry.py` |
+| Rota HTTP e fases | `server/transport/http.py` (`build_router`, `_make_endpoint`); `server/transport/post_rows.py` (`post_handler_rows`) |
+| Admissão compartilhada | `server/transport/gates.py` |
+| Argumentos desconhecidos | `server/transport/arg_check.py`, `server/transport/arg_feedback.py` |
+| Cache de idempotência | `server/core/idempotency.py` |
+| Despacho e recusas do MCP | `server/transport/mcp.py`, `mcp_call.py` (`_call_tool`), `mcp_op.py`, `mcp_refusals.py` |
+| Cliente ClickHouse | `server/core/ch.py` (`get_client`, `set_query_tag`) |
+| Workers e líder | `server/workers/registry.py`, `supervisor.py`, `leader.py` |
+| Lease de migração | `server/core/schema/migrate.py`, `server/core/schema/migrate_lease.py` |
+| Verificação de camadas | `tests/unit/test_transport_layering.py` |
+
+
+
+## Relacionados
+
+- [ClickHouse](https://github.com/ClickHouse/loom/blob/main/docs/architecture/clickhouse.md): tabelas, engines, índices e migrações.
+- [Arquitetura de memória](memory-architecture.md): os caminhos de escrita e de leitura.
+- [Falha e recuperação](failure-and-recovery.md): novas tentativas, reparo e capacidade.
+- [Segurança](https://github.com/ClickHouse/loom/blob/main/docs/architecture/security.md): o que o token e as barreiras de autorização verificam.
+- [Implantação](https://github.com/ClickHouse/loom/blob/main/docs/operations/deployment.md): os procedimentos por trás da topologia.
diff --git a/i18n/.pending/pt-BR/docs/operations/code-index-operations.md b/i18n/.pending/pt-BR/docs/operations/code-index-operations.md
new file mode 100644
index 0000000000..d9500ff2c0
--- /dev/null
+++ b/i18n/.pending/pt-BR/docs/operations/code-index-operations.md
@@ -0,0 +1,817 @@
+
+> Esta página é uma tradução automática da [página em inglês](https://github.com/ClickHouse/loom/blob/main/docs/operations/code-index-operations.md), que prevalece.
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/operations/code-index-operations.md), which is authoritative.
+
+
+
+# Operações do índice de código
+
+Esta página explica como habilitar os workers do índice de código, configurar repositórios e manter o índice atualizado; o índice de código só roda quando um operador habilita seus workers e configura repositórios. Todo worker `code_*`, exceto `code_coverage_notify` e `code_backport_gaps`, vem desativado por padrão. O que as operações `code.*` respondem está na [visão geral do índice de código](../features/code-index/overview.md); como o índice é construído está na [arquitetura do índice de código](../architecture/code-index-architecture.md).
+
+Um namespace de código indexa um branch de um repositório. Há duas formas de adicionar um:
+
+| Forma | Como | Camadas | Página |
+| ------------------ | ------------------------------------------------- | -------------------------------- | ------------------------------------------------------ |
+| Autoatendimento | painel **Repositories → Add repository** | parser (`code_ingest`) | [repositórios](../features/code-index/repositories.md) |
+| Configuração do operador | `LOOM_CODE_REPOS_JSON` | parser + camada do compilador | esta página |
+
+Uma entrada do operador para um namespace que um membro adicionou pela página é ignorada ([adicionando repositórios](../features/code-index/repositories.md)).
+
+Execute `loom code` dentro do contêiner que roda os workers (`loom-workers` em `dev/docker-compose.cloud.yml`, `loom-server` em stacks de contêiner único), para que ele use o `.env`, os git mirrors e o ClickHouse do deployment:
+
+```bash
+docker exec loom-workers loom code stats --namespace code-myrepo
+```
+
+`--org` / `--namespace` assumem por padrão `LOOM_CODE_ORG` / `LOOM_CODE_NAMESPACE`. Informe os dois quando o deployment indexar mais de um repositório.
+
+
+
+## Pré-requisitos
+
+- **A imagem.** Ela inclui as gramáticas do parser (o extra `code`), Go com scip-go,
+ Node com scip-typescript e scip-python, além de npm, pnpm, Yarn e Bun para a
+ preparação automática de dependências de TypeScript. Quem usa Docker não instala
+ nada disso no host. ClickHouse é o único serviço em execução obrigatório.
+- **Toolchains do servidor nativo.** Instale Python 3.12+, Git e Node.js 22+ com npm
+ e, em seguida, execute estes comandos a partir do checkout do Loom antes de iniciar
+ o servidor:
+
+ ```bash
+ pip install -e ".[code]"
+ sh scripts/install-code-toolchains.sh
+ export PATH="$PWD/var/code-toolchains/bin:$PATH"
+ ```
+
+ O script instala indexadores e gerenciadores de pacotes de TypeScript/Python com
+ versões fixas, sem exigir root. Mantenha esse `PATH` no ambiente do servidor Loom,
+ inclusive no do seu gerenciador de serviços. A indexação nativa de Go exige, além
+ disso, Go e scip-go:
+ `go install github.com/scip-code/scip-go/cmd/scip-go@v0.2.7` (coloque o diretório bin
+ do Go no `PATH` do servidor). C/C++ precisa de scip-clang e da configuração de build
+ do projeto.
+
+- **Um embedder.** Os chunks são gerados como embeddings com o `LOOM_EMBEDDING_MODEL`
+ do servidor. `loom code backfill --embed` recusa o embedder fake, a menos que você
+ passe `--allow-fake-embedder` (somente para desenvolvimento).
+- **Mirrors git graváveis.** Os workers rodam como uid 999 e fazem fetch nos clones
+ bare em `var/code_repos` (montado por bind mount nos contêineres). O operador do
+ host compartilha esse diretório com eles por meio de um grupo, aqui o gid 999.
+ Prepare-o uma única vez:
+
+ ```bash
+ sudo chgrp -R 999 var/code_repos && sudo chmod -R g+rwX,o-rwx var/code_repos
+ sudo find var/code_repos -type d -exec chmod g+s {} +
+ ```
+
+ O bit setgid mantém as novas entradas no grupo. Depois, adicione o operador do host
+ ao grupo e defina `LOOM_CODE_REPOS_SHARED_GID=999` no `.env`, que tanto os
+ contêineres quanto os comandos `loom code` do host leem. Um diretório de mirror ou
+ de checkout que o Loom cria nesse grupo tem modo 2770; todos os demais têm modo
+ 0700, abertos apenas ao usuário do servidor, de modo que nada é compartilhado até
+ que a configuração indique o grupo. Com a configuração, o servidor e todo comando
+ `loom code` rodam com umask 007: os diretórios e arquivos de lock que eles criam
+ são graváveis pelo grupo, os arquivos do git dão ao grupo o que dão ao dono (seus
+ objetos continuam somente leitura), e os demais usuários não recebem nada. Execute
+ um harness manualmente em um checkout sob a raiz por meio de
+ `loom code entry-lock`, que o executa com a mesma umask. O Loom altera o modo de um
+ diretório existente apenas para uma entrada restrita: execute os comandos novamente
+ para arquivos criados por uma build mais antiga ou por outra ferramenta.
+
+ O grupo lê todos os mirrors, inclusive os restritos, então deve conter apenas os
+ usuários que executam o Loom: o operador do host e o usuário dos contêineres
+ (`getent group 999`). Quando o gid 999 já é um grupo do sistema com outros membros
+ (`systemd-journal` em muitas distribuições), execute os contêineres com um grupo
+ dedicado (`user: "999:"` no Compose) e use esse gid nos comandos e na
+ configuração. Mantenha todo caminho que o host e os contêineres compartilham
+ (`code_repos_root`, `code_scip_checkout_dir` e o `git_dir` e o `scip_checkout_dir`
+ de cada entrada) dentro do diretório preparado: um diretório ou arquivo de lock que
+ o Loom cria em outro lugar assume o grupo do pai, se o pai tiver setgid, e o grupo
+ do processo que o cria, caso contrário; com a umask, esse grupo poderia gravá-lo.
+
+ A umask cobre todo arquivo que esses processos gravam, inclusive fora da raiz, onde
+ o arquivo assume o grupo primário de quem o grava: o grupo primário do operador do
+ host deve ser só dele (um grupo privado do usuário, o padrão na maioria das
+ distribuições), e não um compartilhado com outros, como `users`.
+
+ Atualize o checkout do host que executa os jobs de `loom code` junto com a imagem e
+ execute os comandos acima novamente depois que a cor anterior de um deployment por
+ cores for interrompida.
+
+- **Um token do GitHub** (`LOOM_CODE_GITHUB_TOKEN`, ou `github_token` por entrada)
+ para o histórico de PRs mesclados e para remotes privados.
+
+
+
+## Configurar a entrada
+
+`LOOM_CODE_REPOS_JSON` é um array JSON com um objeto por branch indexado. Os campos que uma entrada omite recorrem às configurações escalares `LOOM_CODE_*`; uma entrada para um repositório diferente do `LOOM_CODE_REPO` escalar deriva de `repo` o seu `git_remote`
+(`https://github.com//.git`) e o seu `git_dir` (`.git` ao lado do clone escalar, ou em `var/code_repos` quando não há repositório escalar).
+
+```bash
+LOOM_CODE_REPOS_JSON='[
+ {"org": "acme", "namespace": "code-myrepo", "repo": "acme/myrepo",
+ "git_branch": "main", "public": true},
+ {"org": "acme", "namespace": "code-myrepo-release-2", "repo": "acme/myrepo",
+ "git_branch": "release-2", "embed_reuse_from": "code-myrepo"}
+]'
+```
+
+| Campo | Significado |
+| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `namespace`, `org` | onde o índice fica |
+| `repo` | `owner/name` no GitHub |
+| `git_dir`, `git_remote` | o clone bare e seu remoto; branches de um mesmo repositório compartilham um clone |
+| `git_branch` | o branch que este namespace acompanha |
+| `path_prefixes` | prefixos separados por vírgula a indexar; uma entrada sem ele indexa a árvore inteira, menos a lista de exclusão embutida |
+| `exclude` | globs que nunca são indexados (lista ou separados por vírgula) |
+| `exclude_generated` | recusa arquivos cujo conteúdo os marca como gerados (`Code generated … DO NOT EDIT.`, `@generated`) |
+| `include_contrib_paths` | caminhos `contrib/` vendorizados a indexar mesmo assim, para que suas definições se liguem aos pontos de chamada do repositório |
+| `depends_on` | outros namespaces de código que este código chama; uma definição ausente aqui é procurada lá |
+| `embed_reuse_from` | um namespace cujos embeddings são reaproveitados quando o texto do chunk é idêntico (um branch de release do mesmo repositório) |
+| `public` | o repositório é público no seu host: qualquer pessoa da org pode entrar de imediato no índice como leitora |
+| `classification` | `restricted` para um repositório privado: um mantenedor aprova cada leitor, e ele nunca é legível pela org |
+| `scip_producer`, `scip_checkout_dir` | o indexador da camada do compilador (`clang`, `typescript`, `python`, `go`; se não definido, os arquivos de build da árvore decidem) e sua árvore de trabalho |
+| `scip_extra_producers` | outros produtores da camada do compilador sobre a mesma árvore (um repositório Python com frontend TypeScript), cada um em seu próprio checkout |
+| `git_extra_branches` | globs de outros branches remotos que o espelho compartilhado deve carregar |
+| `github_token` | substituição por entrada de `LOOM_CODE_GITHUB_TOKEN` |
+
+Escreva o host de `git_remote` em ASCII, como punycode para um nome internacionalizado: a adição de um repositório pela página recusa qualquer outro, para que os dois escrevam o host da mesma forma.
+
+Uma entrada cujo `git_remote` é um caminho local ou um espelho `file://` é conhecida pelo seu `repo`, com o qual a adição do mesmo repositório pela página deve coincidir: nomeie em `repo` um espelho de um repositório hospedado fora do GitHub como `host/owner/name`.
+
+`public` é lido quando `loom code init` registra o namespace pela primeira vez; editá-lo depois não altera a política de ingresso, que um mantenedor altera com `code.repo.set_access`.
+Uma entrada configurada começa sem mantenedor. `POST /v1/admin/namespace.adopt` recusa um namespace restricted, e nenhuma rota ou comando instala a primeira concessão direta em um namespace restricted configurado, então um repositório privado é configurado nesta ordem:
+
+1. Configure a entrada sem `classification`, com `public` false (o padrão) e sem `org_readable`, e deixe `LOOM_CODE_ORG_READABLE` no padrão, `false`. Até o passo 3 o namespace é standard: uma concessão nele, ou um token cuja claim o cubra (inclusive uma claim `*`, e não só uma que o nomeie), o lê.
+2. Execute `loom code init` para ele, o que grava a linha de diretório do namespace (adopt responde `NAMESPACE_NOT_FOUND` antes disso), e adote-o para o seu mantenedor. Não execute ainda `loom code backfill` (nem qualquer comando `loom code backfill-*`): uma entrada configurada não recebe primeiro índice, histórico de PRs, vereditos de backport nem branches extras (`code.repo.add_branch` responde `REPO_NOT_INDEXED`) até que o backfill grave sua marca d'água `git_head`, então nada do repositório é indexado até você executá-lo. O espelho git da entrada é clonado nesse meio tempo, e as leituras de seu histórico passam pelo mesmo controle, então conclua o passo 3 antes de distribuir tokens `*` da org.
+3. O mantenedor o restringe com `code.repo.set_access` (`classification: "restricted"` e `join_policy: "approval"` ou `"closed"`; ambos são obrigatórios); depois defina também `classification: "restricted"` na entrada, para que qualquer uma das entradas restrinja, e execute `loom code backfill`. Espelhos e checkouts da camada do compilador são criados com o modo 2770 quando pertencem a `code_repos_shared_gid`, abertos apenas ao usuário do servidor e a esse grupo, e 0700 nos demais casos (veja "Espelhos git graváveis"); um criado por uma build mais antiga, ou cujo modo foi alterado manualmente, é ajustado para esse modo imediatamente no host que atende a chamada, e em todo outro host que o mantenha na próxima rodada de espelhamento desse host, assim que o host lê a linha de diretório do namespace como restricted (em até meio minuto). Só o diretório em si muda: o que uma build mais antiga criou dentro dele precisa dos comandos descritos em "Espelhos git graváveis".
+
+A restrição é por branch: o índice de cada branch é seu próprio namespace. Uma pessoa cujo próprio token lê o repositório no seu host ainda pode adicionar outro de seus branches com `code.repo.add`, em um novo namespace standard; essa pessoa já pode ler o repositório. Configure cada branch configurado de um repositório privado na ordem acima.
+
+Uma entrada que não nomeia `scip_producer` mantém `scip_checkout_dir` para C/C++ (veja
+[Camada do compilador](#compiler-tier)), então nomeie o produtor ao preparar essa árvore para outra linguagem.
+
+Os padrões `linguist-generated` / `linguist-vendored` do `.gitattributes` do repositório e um arquivo `.loomignore` no commit indexado são respeitados como exclusões. Uma dependência vendorizada como submódulo git não está no espelho bare; dê a ela sua própria entrada e nomeie-a em `depends_on`. O gauge `loom.code.repos_config_errors` informa as entradas que o servidor não pôde usar (JSON inválido, uma entrada sem nome, um namespace com `.` ou `/`, um namespace duplicado); 0 significa que o valor foi interpretado sem erros. Valide o JSON antes de reiniciar com `docker compose --env-file .env -f dev/docker-compose.cloud.yml config`.
+
+Quem pode ler um índice é definido pela política de ingresso e pelas concessões do namespace
+([tokens e concessões](https://github.com/ClickHouse/loom/blob/main/docs/guides/tokens-and-grants.md)). `LOOM_CODE_ORG_READABLE=true`
+torna todo namespace de código legível por todo principal da org sem concessão; o padrão é desativado.
+
+
+
+## Primeiro índice
+
+```bash
+docker exec loom-workers loom code init --namespace code-myrepo --org acme # optional: bare clone + index state
+docker exec loom-workers loom code backfill --namespace code-myrepo --org acme --embed
+docker exec loom-workers loom code backfill-prs --namespace code-myrepo --org acme --months 12
+```
+
+- `init` é opcional: a passagem de ingestão clona em segundo plano um mirror ausente, inclusive para uma entrada configurada pelo operador, e registra no log o caminho em que clona (a linha `code_mirrors` do `loom doctor` indica um `git_dir` do operador que não existe, de modo que um caminho digitado errado não vira silenciosamente um clone de vários GB). O mirror é um cache dos registros remotos do ClickHouse: cada host de serviço clona os mirrors das entradas indexadas na inicialização (`LOOM_CODE_MIRROR_WARMUP`) e, a cada `LOOM_CODE_MIRROR_FETCH_INTERVAL_S`, busca as refs que a passagem do líder registrou no ClickHouse e que ele não possui (sem `ls-remote` e sem chamada de rede quando já está atualizado). Até que um host tenha o mirror, suas leituras de histórico respondem `no_git_mirror: cloning `; `/v1/health?include=mirrors` conta os mirrors do host em `mirrors`. Disco: cada host guarda uma cópia de cada mirror (N réplicas, N cópias), e um `git_dir` do operador deve ser gravável pelo usuário `loom`. Rede: um host com disco vazio faz um clone completo por repositório indexado; mantenha `LOOM_CODE_REPOS_ROOT` em um volume persistente para que um rollout não reclone todos os mirrors em cada pod.
+- `backfill` faz o parsing, divide em chunks, extrai símbolos e arestas e gera embeddings de cada arquivo. É retomável: execute-o novamente após uma interrupção. `--phase index` seguido de `--phase embed` divide o trabalho, já que as linhas sem embedding formam a fila da fase de embed. `--commit ` fixa a árvore (e implica `--no-fetch`); `--concurrency N` paraleliza os arquivos; `--limit N` indexa uma amostra.
+- O primeiro backfill completo de um namespace também rederiva as arestas de cada arquivo depois que a tabela de nomes está completa, de modo que as referências entre arquivos sejam resolvidas (`--no-edges-second-pass` o pula). `--dialect-folder-pass` permite que arquivos SQL de dialeto indefinido assumam o dialeto com o qual o diretório concorda.
+- `backfill-prs` carrega o histórico de PRs mesclados do GitHub, é retomável por cursor e limitado pelo limite de taxa do GitHub (`LOOM_CODE_PR_BACKFILL_MONTHS`, padrão 12). `backfill-reviews` adiciona comentários de revisão inline, `backfill-assignees` os revisores solicitados e `backfill-items` issues e PRs em qualquer estado.
+- **O worker não inicia um primeiro índice para uma entrada configurada.** Uma entrada sem marca-d'água `git_head` é ignorada com a nota "run `loom code backfill` first". (Ele constrói primeiros índices de autoatendimento, `LOOM_CODE_BOOTSTRAP_FILES_PER_PASS` arquivos por passagem.)
+
+Depois:
+
+- `POST /v1/code.calibrate` (`ADMIN`) deriva os limiares de abstenção do índice de código a partir de `bench/fixtures/code_calibration_probes.jsonl` (incluído na imagem).
+- `loom code describe --top-pct 20` (opcional, com custo de LLM) escreve descrições de uma linha para os chunks mais centrais.
+- `loom code stats` exibe as marcas-d'água (`git_head`, `scip_commit`, …) e as contagens de linhas em tempo real; `POST /v1/code.index_status` responde o mesmo pela API.
+
+`scripts/ops/code_intel_bootstrap.sh` executa essa sequência para `LOOM_CODE_ORG` / `LOOM_CODE_NAMESPACE` configurados no host do Loom (init, as duas fases de backfill, histórico de PRs, calibrate e, em seguida, os gates de `bench/code_intel_qa.py`), recusando um embedder falso ou um servidor cujo `/v1/health` não responda; `--dry-run` executa apenas essa verificação prévia somente leitura e imprime os comandos. Ele lê `LOOM_BASE_URL` e `LOOM_ADMIN_TOKEN`.
+
+
+
+## Estado estável
+
+Habilite os workers no `.env` no container de workers e recrie-o. A configuração de cadência e o valor padrão de cada worker estão na [referência de workers](https://github.com/ClickHouse/loom/blob/main/docs/reference/workers.md).
+
+| Worker | Flag | Função |
+| ---------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `code_ingest` | `LOOM_CODE_INGEST_ENABLED` | a cada `LOOM_CODE_INGEST_INTERVAL_SECONDS`: faz o fetch e, para cada commit de first-parent, refaz o chunking apenas do conteúdo alterado, atualiza símbolos e arestas, marca exclusões com tombstone, monta o pacote de contexto do PR mergeado e avança `git_head`. A cada hora, também encontra arquivos indexados cujos chunks são anteriores ao conteúdo no head e corrige até `LOOM_CODE_RECONCILE_HEAL_PER_PASS` por passagem. Constrói os primeiros índices de autosserviço. |
+| `code_embed_recovery` | `LOOM_CODE_EMBED_RECOVERY_ENABLED` | gera embeddings dos chunks que ficaram sem vetor (queda do provedor, `--phase index`) |
+| `code_pr_history` | `LOOM_CODE_PR_HISTORY_ENABLED` | sincroniza do GitHub os PRs recém-mergeados |
+| `code_graph_stats` | `LOOM_CODE_GRAPH_STATS_ENABLED` | semanalmente: PageRank sobre o grafo de includes, graus por arquivo, o mapa teste ↔ código-fonte |
+| `code_summary` | `LOOM_CODE_SUMMARY_ENABLED` | semanalmente: cards de arquivo e de módulo gerados por LLM para `code.map` (com limite de custo por namespace) |
+| `code_scip_apply` | `LOOM_CODE_SCIP_APPLY_ENABLED` | aplica os deltas da camada do compilador enviados por `code.scip_ingest` |
+| `code_coverage_notify` | `LOOM_CODE_COVERAGE_NOTIFY_ENABLED` (on) | um evento de tarefa quando a cobertura de um commit monitorado está pronta em todas as camadas |
+| `code_backport_gaps` | `LOOM_CODE_BACKPORT_GAPS_ENABLED` (on) | o relatório noturno de backport; só roda junto com `code_pr_history` |
+
+Os workers da camada do compilador por linguagem estão na próxima seção.
+
+**Atualização acionada por push.** Um job de CI pode chamar `POST /v1/code.refresh` (`WRITER`) logo após um merge. Ele executa imediatamente a mesma passagem de ingestão para esse namespace, na réplica que a recebeu, sob o lease do namespace (`code_refresh:/`), de modo que gatilhos que chegam a réplicas diferentes se agrupam em uma única passagem. Responde 404 para um namespace que nenhuma entrada configura, então quem envia o push nunca decide o que é indexado. Funciona com o poller desabilitado.
+
+Pull requests abertos não são indexados; a árvore de trabalho continua sendo do próprio cliente.
+
+
+
+## Camada do compilador
+
+A camada do parser responde a partir do tree-sitter. Onde existe um índice de nível de compilador (SCIP), seus
+símbolos e referências prevalecem. Cada linguagem tem um worker que indexa os commits entre
+sua própria marca d'água e o head do branch no mirror da entrada (obtido por `code_ingest`)
+e aplica o delta no próprio processo, em qualquer processo que detenha o lease dos workers. Uma
+camada do compilador não espera o `git_head` da camada do parser; somente o primeiro
+índice de uma entrada espera.
+
+| Linguagem | `scip_producer` | Flag do worker | O host precisa de |
+| ---------- | --------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| C / C++ | `clang` | `LOOM_CODE_SCIP_DELTA_ENABLED`, `LOOM_CODE_SCIP_FULL_ENABLED` | clang 21, CMake e ninja (na imagem) e scip-clang (na imagem amd64; em outras, `LOOM_CODE_SCIP_CLANG_PATH`) |
+| TypeScript | `typescript` | `LOOM_CODE_SCIP_TS_DELTA_ENABLED` | Node e o indexador/gerenciadores de pacotes fixados (incluídos na imagem); as dependências são preparadas automaticamente |
+| Python | `python` | `LOOM_CODE_SCIP_PY_DELTA_ENABLED` | scip-python (na imagem) |
+| Go | `go` | `LOOM_CODE_SCIP_GO_DELTA_ENABLED` | Go e scip-go (na imagem) |
+
+Uma entrada que não informa `scip_producer` recebe todas as camadas cujo arquivo de build
+sua árvore contém: `go.mod` (em qualquer profundidade) para Go; `tsconfig.json`, `jsconfig.json` ou
+`package.json` na raiz para TypeScript; um `CMakeLists.txt` na raiz para C/C++;
+`pyproject.toml`, `setup.py` ou `requirements.txt` na raiz para Python.
+`code.index_status` as lista como `compiler_candidates`. Informe o producer quando um arquivo
+de build for incidental, como um repositório C++ cujo `pyproject.toml` serve apenas às suas
+ferramentas de teste; `scip_extra_producers` adiciona camadas ao lado de uma informada. Cada camada trabalha na própria
+árvore: o producer informado (C/C++ quando a entrada não informa nenhum) em `scip_checkout_dir`, todos
+os outros em `.`.
+
+Todos os workers vêm habilitados por padrão, e a imagem Docker traz todos os indexadores:
+scip-python, scip-typescript, scip-go e, para C/C++, clang 21, lld, CMake, ninja e
+scip-clang. O upstream compila o scip-clang apenas para Linux x86_64, então a imagem arm64 tem
+o resto da toolchain C/C++, mas não o scip-clang: aponte `LOOM_CODE_SCIP_CLANG_PATH` para
+seu próprio build, ou a camada C/C++ registra `scip-clang missing` como um skip. Cada worker
+cria uma árvore de trabalho ausente como um repositório vazio e busca cada commit nela
+a partir do mirror da entrada, então um novo líder começa do zero. Um worker cujos
+pré-requisitos de projeto estão ausentes registra um skip em `workers.status`; a camada Tree-sitter
+continua disponível. Os projetos TypeScript têm suas dependências instaladas
+automaticamente no checkout.
+
+O harness C/C++ executa o configure do CMake do repositório (apenas banco de dados de compilação, sem
+build) na primeira execução em uma árvore, ou quando seu `CMakeCache.txt` está ausente, foi criado em
+outro diretório, ou nomeia um compilador que o host não tem mais. Ele executa o configure
+novamente sobre o cache existente antes de um índice completo e para um delta cuja janela adiciona um
+arquivo `.cpp`, `.cc` ou `.cxx` ou adiciona, altera ou exclui um arquivo `CMakeLists.txt` ou `.cmake`,
+porque o banco de dados de compilação lista apenas as unidades de tradução da árvore em que
+foi configurado. Um reconfigure que falha faz a execução falhar com as últimas linhas do CMake, e o
+registro `clang` da entrada (`clang_full` para um índice completo) indica falha com o tipo `cmake`
+(`disk` quando o disco está cheio). Um delta com falha não move nenhuma marca d'água, então sua janela, com
+as unidades de tradução que adiciona, é tentada novamente a cada passagem; um índice completo é tentado novamente
+6 horas depois, como qualquer execução completa com falha.
+
+Uma árvore C++ grande é o caso pesado: um checkout do porte do ClickHouse, com seus submódulos
+e árvore de build, ocupa cerca de 30 GB além do mirror, e o scip-clang mantém a AST de uma unidade de
+tradução por job (alguns GB cada), então `LOOM_CODE_SCIP_CLANG_JOBS` deve caber na
+memória que o processo dos workers tem. O índice completo de uma árvore assim leva cerca de uma hora.
+
+- **Limite de delta C/C++.** O worker indexa as unidades de tradução alteradas, incluindo as
+ que incluem um header alterado, até `LOOM_CODE_SCIP_DELTA_MAX_TUS` (200); acima do
+ limite, indexa apenas os arquivos `.cpp` alterados. Um delta que reconfigura o CMake executa o
+ configure dentro do mesmo `LOOM_CODE_SCIP_DELTA_TIMEOUT_SECONDS` (3600) do índice;
+ um delta que estoura o tempo deixa `scip_commit` onde estava, então a próxima passagem tenta uma janela
+ maior.
+- **Limites do delta.** O servidor lê o delta de uma camada do compilador (qualquer camada, execução delta ou
+ completa) somente quando é um arquivo regular, não um link, e o aplica uma rodada de arquivos por
+ vez (`server/code/app/index/delta_file.py`). Primeiro conta os bytes `{`, `[`
+ e `,` do delta, depois faz o parse de cada valor uma vez e verifica cada entrada de arquivo, e só
+ então o reabre e lê os arquivos novamente, uma rodada por vez, para a aplicação. Assim, um
+ delta acima de um limite, ou que não faz parse, faz a passagem da entrada falhar antes que qualquer coisa
+ seja aplicada. Os limites valem como lidos quando o delta é aberto; um valor alterado vale
+ na próxima passagem.
+ - `LOOM_CODE_SCIP_DELTA_FILE_MAX_MB` (180 MiB) limita os bytes do arquivo e
+ `LOOM_CODE_SCIP_DELTA_MAX_NODES` (6,000,000) seus bytes contados, que limitam os valores JSON
+ que os parses constroem. Eles limitam o trabalho de uma passagem. Sua memória é a rodada
+ abaixo mais um registro de cada entrada de arquivo e caminho excluído: cerca de 70 B cada, tantos
+ quanto o limite de nós permitir (uma entrada mínima custa 2 bytes contados, um caminho excluído 1:
+ cerca de 3 milhões de entradas, uns 200 MiB, ou 6 milhões de caminhos excluídos, uns 400 MiB,
+ no padrão), mais o texto dos caminhos (no máximo 4,096 bytes cada), que o limite de bytes
+ restringe. A execução completa de uma árvore C++ grande grava mais de 500 MiB em entradas de dezenas de
+ KB, alguns MiB de controle: aumente ambos para ela.
+ - `LOOM_CODE_SCIP_DELTA_ROUND_MAX_NODES` (3,000,000) limita a memória de uma rodada: os
+ bytes contados que uma rodada de aplicação processa. Uma rodada contém no máximo 100 arquivos e é
+ liberada antes que a próxima seja processada; uma única entrada de arquivo pode preenchê-la, e uma entrada de arquivo
+ acima dela faz a passagem falhar, nomeando a entrada. Qualquer outro valor desse tamanho (um
+ caminho excluído, um valor de header, uma chave ignorada) resulta em `delta invalid`, pois o
+ harness nunca grava um; os caminhos excluídos são lidos um por vez. Um limite fixo de
+ 64 milhões de caracteres, que não é uma configuração, limita da mesma forma o texto de um valor e de uma rodada; uma entrada real tem cerca de 32 caracteres por byte contado, então para ela o limite vale
+ perto de 2,000,000 de bytes contados. A maior entrada de arquivo da execução completa de uma árvore C++ grande
+ tem cerca de 600,000 bytes contados (uns 100,000 edges), cerca de um quinto do
+ orçamento da rodada e um terço do limite de caracteres. A rodada mais densa que o código de um repositório pode
+ gerar (símbolos mínimos) atinge o pico de cerca de 1.8 GiB residentes enquanto é lida no
+ orçamento padrão (medido com `ru_maxrss`; cerca de 330 B por byte contado de objetos Python,
+ o resto do alocador); o texto de um valor próximo ao limite de caracteres (até 4 bytes por
+ caractere) pode ser mantido até três vezes enquanto o buffer de leitura cresce, então a leitura
+ da pior rodada é de cerca de 2.5 GiB, qualquer que seja o tamanho do delta. Sua aplicação mantém as
+ linhas dessa rodada além disso (as linhas ativas lidas para seus caminhos e as novas linhas a inserir),
+ cerca de outro tanto para uma rodada de símbolos novos, então dimensione o worker para cerca do dobro
+ da leitura. Uma entrada de arquivo real de um delta C++ tem um byte contado por cerca de 32 bytes:
+ uma rodada atinge seus 100 arquivos muito antes de chegar ao orçamento. Para medir a leitura
+ da rodada padrão mais densa a partir de um checkout do código-fonte:
+
+ ```bash
+ .venv/bin/python -c "import resource, tempfile, pathlib; from server.settings import settings; from server.code.app.index.delta_file import open_delta; p = pathlib.Path(tempfile.mkdtemp()) / 'delta.json'; n = settings.code_scip_delta_round_max_nodes // 2 - 10; p.write_text('{\"commit\":\"c\",\"files\":[{\"path\":\"a\",\"symbols\":[' + ','.join(['{\"qualified_name\":\"\"}'] * n) + ']}]}'); list(open_delta(p).rounds(100, lambda x: True)); print(resource.getrusage(resource.RUSAGE_SELF).ru_maxrss >> 10, 'MiB peak RSS')"
+ ```
+
+ Um delta inválido faz a passagem falhar com um breve `delta invalid: ` que nomeia seu
+ primeiro problema (para uma entrada, `file entry : …`), não a lista do pydantic com todos os itens
+ inválidos. `--keep-delta` mantém o delta como o harness o gravou, antes de ser processado
+ (o limite de bytes ainda se aplica), como um arquivo que só o usuário que executou o comando pode ler
+ (modo 0600).
+
+- **Índice completo C/C++.** `code_scip_full` reindexa uma entrada por passagem: uma entrada cujo
+ `scip_commit` ainda não foi semeado (o delta a ignora com "watermarks not seeded"), e
+ toda entrada cuja última execução completa aplicada tenha `LOOM_CODE_SCIP_FULL_EVERY_HOURS` (168)
+ horas, o que corrige deltas limitados. Uma execução que falha é tentada novamente 6 horas após a falha,
+ e uma interrompida junto com seu pod (um rollout) 6 horas após seu início. Um
+ delta de base desconhecida limpa `scip_commit`, então a entrada recebe um índice completo em seguida. A passagem
+ roda sob o lock da entrada com `LOOM_CODE_SCIP_FULL_TIMEOUT_SECONDS` (8 horas) para
+ o harness e mais seis para a movimentação do checkout, a aplicação e o repack.
+ `loom code scip-full` executa o mesmo índice manualmente (`--keep-delta` salva o delta para que uma
+ aplicação interrompida possa ser reexecutada com `--apply-delta`), e `loom code scip-delta` uma
+ passagem de delta, que imprime uma linha `RESULT:`.
+- **Submódulos C/C++.** A camada busca os pins dos submódulos com o token de acesso
+ da entrada, então um submódulo privado cuja URL em `.gitmodules` é uma URL https absoluta sob o
+ owner do remote não precisa de outra credencial. O owner é comparado como escrito, com
+ maiúsculas e minúsculas, então um owner escrito em outra caixa é buscado sem o token. Uma
+ URL relativa resolve para um caminho local no checkout, que não tem remote; a camada
+ recusa o transporte `file`, então a atualização desse submódulo falha. Quem pode fazer commit em
+ `.gitmodules` do repositório pode apontar um submódulo para qualquer repositório desse owner
+ que o token leia, então dê a uma entrada um token restrito aos repositórios de que seus submódulos
+ precisam.
+- **Crossref SQL ↔ C++.** `code_crossref` reconstrói as linhas de referência de conteúdo de `code_test_map`
+ (consultas de teste para os arquivos que registram as funções e configurações que usam)
+ para cada entrada C/C++ cujo `git_head` mudou desde sua última execução. Ele lê apenas
+ os chunks da camada do parser.
+- **Manutenção do checkout.** A passagem completa C/C++ (sob o lock da entrada) e as passagens de
+ Python, TypeScript e Go fazem o repack do checkout de sua entrada com
+ `git gc --no-prune` a cada `LOOM_CODE_MIRROR_GC_INTERVAL_H`, sob as mesmas regras dos
+ mirrors (abaixo). Todo comando git que uma camada executa em um checkout tem auto-gc e
+ manutenção em segundo plano desligados, então nenhum fetch inicia um repack.
+- **Locks de entrada.** Uma passagem completa e um delta nunca trabalham na mesma entrada ao mesmo tempo: cada
+ um pega o arquivo de lock da entrada em `LOOM_CODE_SCIP_LOCK_DIR` (`var/cron/locks`),
+ `scip...lock` com ambos os nomes codificados em percent-encoding
+ (`loom code scip-lock-path --org ORG --namespace NS` o imprime). Uma passagem completa espera
+ um delta que já esteja em sua entrada; um delta ignora uma entrada mantida por uma passagem completa e a nomeia
+ em `skipped` ("entry lock held (full pass running)"). Entradas diferentes rodam
+ lado a lado. Toda passagem também pega a chave da entrada no ClickHouse (`scip_entry:/`
+ em `loom._migration_lock`), de modo que
+ passagens em dois hosts também se excluem mutuamente; a chave de um detentor morto expira após 120 s.
+ Uma passagem que não consegue pegar a chave (ClickHouse ou Keeper inacessível) falha em vez de
+ rodar apenas com o arquivo do host. Um detentor considera sua chave perdida após 60 s sem
+ renovação (uma pausa incluída), antes que outro host possa pegá-la, e não grava mais nenhuma linha de
+ índice nem marca d'água: toda gravação desse tipo verifica a chave antes, e a passagem termina com
+ `EntryLockLost`. Uma execução manual do harness vai sob
+ `loom code entry-lock --org ORG --namespace NS -- `, que pega ambos os locks,
+ sai com 75 quando outra passagem detém a entrada e mata o comando (saída 3) se a chave
+ for perdida. Ele entrega ao comando o detentor da chave (`LOOM_ENTRY_LEASE_HOLDER`), que os
+ uploads do harness carregam: `code.scip_ingest` recusa uma parte (409 `ENTRY_LEASE_NOT_HELD`)
+ quando esse detentor não tem mais a chave, então uma passagem que perdeu sua entrada não completa nenhum
+ lote para `scip_apply`. Com `--tier ` ele também registra a saída do comando como
+ a saúde dessa camada do compilador na entrada (`tier_health` em `code.repos`) e repassa a
+ saída do comando, stderr incluído, para stdout.
+- **As dependências do TypeScript são automáticas.** Checkouts novos instalam as dependências
+ antes da indexação do compilador, incluindo dependências de desenvolvimento que contêm definições
+ de tipos. O Loom usa npm, pnpm, Yarn (clássico ou moderno) ou Bun conforme o
+ lockfile, respeita lockfiles existentes e desabilita scripts de ciclo de vida e hooks executáveis
+ do gerenciador de pacotes. Scripts simples sem manifesto de pacote não precisam de instalação.
+ Mudanças no manifesto/lockfile de dependências disparam uma atualização antes do próximo índice; uma instalação com falha
+ ou interrompida é tentada novamente sem avançar a marca d'água do compilador.
+ Os downloads precisam de acesso de rede ao registry de pacotes do repositório. Um registry de pacotes
+ privado, um lockfile incompatível ou tipos gerados que exigem um build ainda podem precisar
+ de configuração específica do projeto. `workers.status` nomeia o instalador que falhou e seu
+ código de saída, e o registro de saúde da camada da entrada (`code.index_status`) guarda o final
+ da saída do instalador. As credenciais do servidor não são passadas ao ambiente do instalador.
+ O servidor lê o `package.json` do checkout (até 1 MiB) e o `yarn.lock` de cada raiz de instalação
+ (até 64 MiB) apenas como arquivos regulares, nunca por meio de um link; um deles que seja symlink
+ faz a passagem do TypeScript falhar mesmo quando o link aponta para dentro do repositório.
+- **Os arquivos do repositório têm o tamanho verificado antes de serem lidos.** A ingestão pergunta ao mirror
+ o tamanho do arquivo primeiro: um arquivo acima de `LOOM_CODE_INGEST_MAX_FILE_BYTES` não é lido, e
+ sua linha em `code_files` registra o motivo (`code.index_errors`); 0 remove o limite. Todo
+ manifesto que o resolvedor de imports lê (os arquivos de projeto e workspace de TypeScript, Python e Go)
+ é lido do mirror até 1 MiB, um `go.mod` até 64 KiB e no máximo 200
+ deles; um maior é ignorado uma vez por commit com um aviso que nomeia o org e o
+ namespace, e os imports que ele teria resolvido permanecem não resolvidos. Fora de uma passagem do worker, o resolvedor lê um arquivo a partir de seus chunks indexados, que contêm apenas arquivos
+ dentro de `LOOM_CODE_INGEST_MAX_FILE_BYTES` (qualquer tamanho com 0). Os re-exports de um barrel são lidos
+ sob o mesmo limite de arquivo. Um arquivo binário ou da denylist acima do limite recebe tombstone como
+ um abaixo dele, por seu caminho e seus primeiros 8 KiB; um arquivo gerado recebe a linha de
+ skipped, sem declarações.
+- **As exclusões do próprio repositório são limitadas e falham de forma aberta.** `.loomignore` e
+ `.gitattributes` são lidos até 1 MiB e dão no máximo 1,000 padrões entre os dois. Um
+ arquivo maior não dá nenhum padrão, e os padrões além do 1,000º são descartados, então os caminhos
+ que eles excluiriam são indexados; o log nomeia o arquivo ou a contagem. Os globs `exclude`
+ da própria entrada nunca são cortados, então um caminho que deve ficar de fora pertence
+ a eles.
+- **Uma aplicação com falha** deixa seu lote como `failed` com o erro;
+ `loom code scip-retry ` o redefine para pending.
+- **Producers manuais e de CI** ficam em `scripts/scip_harness/` (`run_delta.sh`,
+ `run_typescript_delta.sh`, `run_python_delta.sh`, `run_go_monorepo_delta.sh`,
+ `scip_to_delta.py`; veja o README).
+
+
+
+### Sandbox de jobs do repositório
+
+**Camadas baseadas em build executam código do repositório.** A camada de C/C++ executa o próprio
+`cmake` configure do repositório (um `CMakeLists.txt` é um programa), a camada de Go executa `go mod download`
+sobre o grafo de módulos do repositório, e a camada de TypeScript instala os pacotes que o
+lockfile dele nomeia. Trate toda execução de uma camada do compilador como a execução de código
+escrito pelos autores do repositório, no host que a executa.
+
+O Loom executa cada job de repositório (clone, fetch e `ls-remote`, `git submodule update`,
+instalações de dependências e os harnesses da camada do compilador) dentro de um único limite construído sobre
+[bolha de proteção (bubblewrap)](https://github.com/containers/bubblewrap)
+(`server/code/app/index/sandbox.py`) quando o host consegue executá-lo:
+
+- namespaces próprios de user, pid, network, mount, ipc e uts, sem capabilities, sem novos user
+ namespaces, e um filtro seccomp que recusa `ptrace`, `mount`, `unshare`, `setns`,
+ um `clone` com `CLONE_NEWUSER`, `bpf`, `perf_event_open`, keyrings do kernel, carregamento de módulos e
+ kexec, `userfaultfd`, `open_by_handle_at` e `process_vm_readv`/`writev`
+ (`clone3` responde `ENOSYS`, de modo que a biblioteca C recorre a `clone`);
+- apenas os diretórios do sistema, as toolchains e os caminhos do próprio job são montados. Uma
+ toolchain só é montada onde não expõe nenhum dado do Loom: nunca um diretório que
+ seja ou contenha `var/`, os mirrors e checkouts, o arquivo env, a
+ raiz de instalação ou `HOME`, nem um dentro de `var/` ou de `HOME` (o
+ `var/bin/scip-clang` padrão é montado como esse único arquivo). Quando um desses caminhos está
+ dentro de qualquer outro diretório montado (um mirror dentro do prefixo Python do
+ servidor, `var/` sob um caminho do sistema), uma montagem vazia o cobre dentro do sandbox.
+ A raiz de instalação é a exceção, pois o Python do servidor pode executar a partir dela. Um host
+ cujo prefixo Python ou um caminho do sistema é, ou está dentro de, um dos caminhos de dados do Loom
+ não executa nenhum job em sandbox: nenhuma montagem vazia poderia ocultar esses dados, e `/v1/health` e
+ `loom doctor` reportam `repo_sandbox_layout_refused`. O checkout (ou o
+ mirror bare, no caso de um fetch) e o diretório de saída são graváveis, o `.git` do checkout
+ e os scripts do harness são somente leitura, e `/tmp` e `HOME` são um diretório
+ novo removido após o job. Sem ambiente do servidor, credenciais, `HOME` do host, socket do Docker
+ ou outros caminhos do host;
+- rlimits, definidos por `prlimit`: `LOOM_CODE_SANDBOX_CPU_SECONDS` (7200),
+ `LOOM_CODE_SANDBOX_MEMORY_MB` (16384) e `LOOM_CODE_SANDBOX_MAX_FILE_MB` (32768),
+ definidos antes de o bwrap iniciar, limitam **cada processo** de um job (tempo de CPU, memória de dados, tamanho
+ de arquivo), não o total do job. `LOOM_CODE_SANDBOX_MAX_PIDS` (2048) limita os processos
+ e threads de **um job**: ele é definido dentro do user namespace do job, onde o
+ kernel conta apenas as tarefas desse job (Linux 5.14 e posteriores; kernels mais antigos contam as
+ tarefas do uid em todo o host). Fora dele, RLIMIT_NPROC contaria todas as tarefas do uid no
+ host, inclusive as de outros contêineres. O sandbox executa o `prlimit`
+ encontrado no `PATH` do servidor, portanto ele deve estar sob um caminho do sistema montado, como
+ `/usr`. O Loom não define cgroup; dê ao contêiner seus próprios limites de memória e pids para um
+ total rígido. As cores definem `pids_limit: 8192` em cada contêiner como essa salvaguarda.
+ Cada job também tem um timeout de relógio que mata toda a sua árvore; o pid namespace do job
+ garante que nenhum processo iniciado por ele sobreviva a ele;
+- saída limitada no servidor: o stderr de um job, e o stdout de um build, instalação ou
+ clone, mantêm apenas o último 1 MiB; um comando cujo stdout o Loom analisa (`ls-remote`,
+ fetch) pode imprimir até 64 MiB, e acima disso o job inteiro é morto e falha. Um arquivo
+ que o servidor lê de volta de um job ou de um checkout é um arquivo regular, nunca um link: o
+ delta de uma camada do compilador até `LOOM_CODE_SCIP_DELTA_FILE_MAX_MB` e
+ `LOOM_CODE_SCIP_DELTA_MAX_NODES`, o `package.json` do checkout até 1 MiB e o `yarn.lock` de cada
+ raiz de instalação até 64 MiB;
+- sem rede, exceto para clones, fetches, submodules e downloads de dependências, e então
+ apenas por meio de um proxy de egress fora do sandbox. Ele aceita `CONNECT` para as portas 443,
+ 22 e a porta do próprio remote, resolve o nome (apenas a partir de `/etc/resolv.conf`: não
+ `/etc/hosts` ou nsswitch, e sem search domains, de modo que um remote precisa do nome DNS completo),
+ recusa a conexão a menos que **todos** os endereços
+ sejam públicos (loopback, faixas privadas, link-local e o endereço de metadados da nuvem
+ são recusados, inclusive quando alcançados por um redirect ou por uma URL de `.gitmodules`) e
+ conecta ao endereço que verificou. HTTP simples não tem rota. Um job mantém no máximo 32
+ túneis por vez. Um cliente dentro do sandbox alcança o proxy por um relay local
+ (seu proxy HTTPS), que faz ponte de no máximo 32 conexões; mais uma espera até que uma ponte
+ termine. Qualquer outra conexão acima do limite no proxy é recusada após
+ `LOOM_CODE_EGRESS_SLOT_WAIT_S` (5 s por padrão), e o mesmo vale para uma conexão do relay enquanto
+ túneis ssh ocupam alguns dos slots. O proxy registra no log a primeira recusa, e o total
+ quando o job termina, se houve mais de uma.
+
+ Um túnel sem nenhum byte em qualquer direção por `LOOM_CODE_EGRESS_IDLE_TIMEOUT_S` (5 minutos por
+ padrão) é fechado. Depois que seu cliente envia EOF, ele é fechado após
+ `LOOM_CODE_EGRESS_HALF_CLOSE_TIMEOUT_S` (10 s por padrão) sem um byte do
+ servidor; enquanto ainda há bytes aguardando um cliente lento, vale o timeout de inatividade. Um
+ túnel cujo cliente enviou EOF antes de qualquer byte trafegar (uma conexão que ele abandonou) é
+ fechado imediatamente. Depois que o lado do proxy de um túnel terminou (o servidor o fechou ou
+ o reiniciou, ou o proxy o fechou), o relay encerra sua conexão após pelo menos um
+ segundo sem um byte do cliente. Um cliente que nunca lê o que lhe foi enviado
+ mantém sua conexão de relay, e portanto seu slot de relay, por até o timeout de inatividade.
+
+Todo git que um job de repositório executa não lê nenhuma configuração git de sistema ou global e permite apenas
+os transportes `https` e `ssh` (`protocol.allow=never`); `ext::` e `file://` são
+recusados, assim como reescritas de URL. O token de acesso da entrada chega apenas ao seu clone, aos seus
+fetches e ao `git submodule update` da camada de C/C++, nunca a um build ou a `go mod
+download`, e o git o envia apenas a URLs sob o proprietário do remote
+(`https://host/owner/`; o host inteiro para um remote sem caminho de proprietário). Dentro do
+sandbox, um remote `ssh` não tem chave SSH do host: use um remote HTTPS com um token de acesso.
+
+**Quais stacks executam o sandbox.** As cores blue/green que o `redeploy.sh` implanta
+(`dev/docker-compose.colour.yml`) definem as opções de contêiner abaixo. Os outros arquivos Compose
+(`compose.yaml`, `dev/docker-compose.cloud.yml`) não as definem: um
+perfil AppArmor que o host não carregou impede o contêiner de iniciar, então eles mantêm
+os padrões do Docker, a sonda falha e todo job de repositório executa como um processo comum (veja
+_Sem o sandbox_). Para executá-lo nesses stacks, depois que o host tiver o perfil:
+
+- copie o bloco `security_opt` do arquivo das cores e seu `pids_limit` (a salvaguarda
+ do contêiner). O caminho `seccomp=` é relativo ao diretório do projeto (a pasta do arquivo
+ compose, a menos que `--project-directory` diga outra coisa): `./seccomp/…` funciona
+ para os arquivos em `dev/`, e o `compose.yaml` precisa de
+ `./dev/seccomp/loom-repo-sandbox.json`;
+- o bundle standalone da release (`loom-stack.tar.gz`) não inclui nem o arquivo seccomp
+ nem o perfil AppArmor: pegue ambos da árvore de código-fonte da mesma release e aponte
+ `seccomp=` para onde você colocou o JSON;
+- `redeploy.sh` verifica apenas o compose das cores. Execute `dev/apparmor_check.sh `
+ manualmente antes de iniciar outro stack, e também a verificação com contêiner descartável abaixo.
+
+Uma execução a partir do código-fonte (`make server`) tem o sandbox apenas onde o host atende aos mesmos
+requisitos.
+
+**Quais hosts podem carregar o perfil.** O perfil distribuído tem como alvo o AppArmor 4.0 ou posterior
+(`abi `). Apenas o Ubuntu 24.04 é testado, pelo job `sandbox-profile` do CI com
+`kernel.apparmor_restrict_unprivileged_userns=1`; o parser 4.x do Debian 13 aceita a
+ABI, mas o perfil não é testado nele. Hosts sem AppArmor, como o Docker Desktop
+(em qualquer SO) ou distribuições com SELinux, como Fedora e RHEL, não podem usar com segurança as
+opções das cores: o Docker ignora `apparmor=` nesses hosts, então nada substitui as máscaras de `/proc`
+que `systempaths=unconfined` remove (veja _`/proc`_ abaixo). Parsers mais antigos (Ubuntu 22.04,
+Debian 12) rejeitam o perfil; esses hosts só podem executar o sandbox com
+`seccomp=unconfined` e `apparmor=unconfined` (o parágrafo antes de _Sem o
+sandbox_), o que perde a mesma proteção de `/proc`. O stack da release executa em todos
+esses hosts sem o sandbox.
+
+A menos que `LOOM_CODE_SANDBOX_REQUIRED` esteja definido, todo host ainda indexa os repositórios
+listados em `LOOM_CODE_REPOS_JSON`; apenas repositórios adicionados pela página precisam do
+sandbox. _Sem o sandbox_ diz o que isso executa, e o
+[guia de início rápido](../getting-started/quickstart.md#optional-index-a-repository-on-the-released-stack)
+tem os comandos do stack da release.
+
+**Requisitos.** `bwrap` e `prlimit` (util-linux) no `PATH` (a imagem tem ambos) e
+user namespaces sem privilégios. Os padrões do Docker bloqueiam o bwrap de três formas, e o compose das
+cores relaxa cada uma da maneira mais restrita possível:
+
+```yaml
+security_opt:
+ - seccomp=./seccomp/loom-repo-sandbox.json
+ - apparmor=loom-repo-sandbox
+ - systempaths=unconfined
+```
+
+- **seccomp.** O perfil padrão do Docker permite `clone` com flags de namespace, `unshare`,
+ `mount` e `umount2` apenas a um contêiner com `CAP_SYS_ADMIN`, e `pivot_root` a nenhum
+ contêiner. `dev/seccomp/loom-repo-sandbox.json` é o perfil padrão do Docker
+ (moby/profiles `seccomp/v0.2.3`, o que o Docker 29 distribui) mais uma regra que permite essas
+ cinco a todo processo do contêiner; o bwrap precisa de todas elas. Dentro do sandbox,
+ o filtro próprio do Loom recusa ao job `unshare`, `mount`, `umount2`, `pivot_root` e um
+ `clone` com `CLONE_NEWUSER`. Um `clone` que peça qualquer outro novo namespace passa pelo
+ filtro e falha por falta de capability, pois o bwrap executa o job com
+ `--cap-drop ALL`.
+- **AppArmor.** O `docker-default` tem `deny mount`. `apparmor=unconfined` não ajuda
+ em hosts que restringem user namespaces sem privilégios (Ubuntu 23.10 e posteriores,
+ `kernel.apparmor_restrict_unprivileged_userns=1`): ali um processo unconfined que
+ cria um user namespace é movido para o perfil `unprivileged_userns`, que
+ recusa as montagens. Em `deploy/apparmor/loom-repo-sandbox`, todo processo do
+ contêiner executa sob `docker-default`, renomeado, com `deny mount` mantido e, na ABI
+ 4.0, sem regra `userns`, de modo que user namespaces são recusados. Apenas um exec de
+ `/usr/bin/bwrap` passa para o perfil filho `loom-repo-sandbox//bwrap`, que é
+ o mesmo mais `userns, mount, pivot_root`. O bwrap e tudo o que ele inicia permanecem no
+ perfil filho, então um job de repositório tem essas permissões pelo AppArmor e as vê recusadas pelo
+ filtro seccomp do Loom acima. O limite é o exec do bwrap: o servidor e as
+ ferramentas que ele executa fora do sandbox não podem fazer unshare nem mount, mas qualquer processo no
+ contêiner que possa executar `/usr/bin/bwrap` pode criar user namespaces e montar dentro
+ deles, sem o filtro do Loom.
+- **`/proc`.** O Docker mascara caminhos sob `/proc` e `/sys`, e o kernel então recusa
+ a montagem de um procfs novo que o sandbox faz; `systempaths=unconfined` remove as máscaras. Isso
+ também remove as montagens somente leitura sobre `/proc/sys`, `/proc/sysrq-trigger`, `/proc/irq`,
+ `/proc/bus` e `/proc/fs`, e as máscaras sobre `/proc/kcore`, `/proc/keys`,
+ `/sys/firmware` e o restante. Em ambos os perfis, as regras do `docker-default` ainda recusam
+ gravações em `/proc/sys`, `sysrq-trigger` e nos outros arquivos de sistema sob `/proc` e
+ `/sys`, e qualquer acesso a `kcore` e `/sys/firmware`. Em um host sem AppArmor,
+ o Docker ignora a opção `apparmor=` e nada toma o lugar das montagens, de modo que
+ o `redeploy.sh` recusa esse host.
+
+**`--disable-userns`.** O perfil filho mantém as negações de gravação em `/proc/sys` do `docker-default`,
+que recusam a gravação de sysctl que o `--disable-userns` do bwrap faz. Uma regra de permissão
+não pode sobrepor uma negação, e restringir os globs de negação para as duas formas que o caminho pode assumir
+os tornaria difíceis de revisar. Portanto, sob este perfil, inclusive em produção, espera-se que a sonda
+veja o bwrap citar `max_user_namespaces`, registre isso em INFO e execute o bwrap sem
+a flag; o filtro do Loom recusa novos user namespaces por conta própria. Qualquer outra falha da sonda
+é registrada em WARNING e deixa o sandbox desligado.
+
+**Carregando o perfil.** Carregue-o uma vez no host Docker; `/etc/apparmor.d` é carregado
+novamente a cada boot:
+
+```bash
+sudo install -m644 deploy/apparmor/loom-repo-sandbox /etc/apparmor.d/loom-repo-sandbox
+sudo apparmor_parser -r -W /etc/apparmor.d/loom-repo-sandbox
+```
+
+**Verificando.** `apparmor_parser -Q -K` aceita o perfil, mas só se sabe se o bwrap executa
+sob ele depois que um host o carrega. O CI é onde isso acontece primeiro: o
+job `sandbox-profile` em `.github/workflows/docker-smoke.yml` carrega o perfil no
+Ubuntu 24.04 com `kernel.apparmor_restrict_unprivileged_userns=1` mantido ligado e executa a
+sonda e a suíte hostil na imagem de produção com as opções das cores. Em um host de deploy, verifique em um contêiner descartável a partir do build prestes a ser implantado, não
+do que está servindo (`True` significa que o sandbox executa):
+
+```bash
+docker build -q -t loom:sandbox-check .
+docker run --rm --network none --user loom -w /app --entrypoint python \
+ --security-opt seccomp=dev/seccomp/loom-repo-sandbox.json \
+ --security-opt apparmor=loom-repo-sandbox --security-opt systempaths=unconfined \
+ loom:sandbox-check -c 'from server.code.app.index import sandbox as s; print(s.sandbox_available())'
+docker image rm loom:sandbox-check
+```
+
+**O que o `redeploy.sh` verifica.** Antes de construir uma cor, ele para quando o perfil não
+está carregado, e em um host sem AppArmor. Depois que a nova cor inicia, e antes de o
+proxy ser trocado para ela, `dev/sandbox_probe.sh` executa a mesma sonda em cada um dos
+contêineres da cor que executam sob o perfil (`loom-` e
+`loom--workers`). Quando uma falha, ou não pode ser inspecionada, ele imprime o motivo, remove
+os contêineres da nova cor e sai com a cor antiga ainda servindo. Removidos, não
+parados: o build já substituiu o build anterior nessa cor, então ele não é alvo de
+rollback, e seus workers não poderiam obter o lease e executar jobs sem sandbox. Essa é
+a primeira verificação do perfil real em um deploy que pulou a verificação acima.
+
+**Exigindo o sandbox.** A sonda controla a troca, mas os novos workers iniciam antes
+dela e podem obter o lease do supervisor (em um primeiro deploy, ou quando o lease antigo está livre)
+e iniciar jobs de repositório. `LOOM_CODE_SANDBOX_REQUIRED=true`, que as cores definem,
+fecha essa janela: onde o sandbox não pode executar, nenhum job de repositório (clone, fetch,
+instalação de dependências, camada do compilador, harness do `loom code scip-full`) executa como um processo
+comum. A passagem de ingestão e as camadas do compilador ignoram toda entrada, inclusive as do
+operador, e nomeiam o motivo na nota da passagem; `loom code scip-full` sai com 1; qualquer job
+que ainda alcance o runner falha com `SandboxRequiredError`. `/v1/health` reporta
+`repo_jobs_unsandboxed` como erro. O primeiro clone bare do `loom code init` é o
+clone do worker, um job de repositório como os demais: ele também sai com 1 com a recusa.
+
+**Desligando.** Para executar as cores sem o sandbox novamente, remova tanto o bloco
+`security_opt` quanto `LOOM_CODE_SANDBOX_REQUIRED` dos dois serviços em
+`dev/docker-compose.colour.yml`, e então faça o redeploy. Remover apenas `security_opt` deixa
+todo job de repositório recusado e `/v1/health` degradado.
+
+Sem `no-new-privileges`: sob ele o kernel recusa a transição de exec para o perfil filho,
+e o bwrap não iniciaria. Os binários setuid da imagem (`su`, `mount`,
+`passwd` e semelhantes) portanto ainda funcionam no contêiner, como sob os padrões do Docker;
+as regras do perfil, e não as montagens somente leitura, os mantêm longe de `/proc/sys`.
+
+Essas opções ainda enfraquecem o confinamento do próprio contêiner: o seccomp permite que todo processo do contêiner faça as cinco chamadas (fora do bwrap, o AppArmor e a ausência de `CAP_SYS_ADMIN` ainda as recusam); o AppArmor permite que o bwrap e o que ele executa criem namespaces de usuário e montem sistemas de arquivos dentro deles, e qualquer processo que consiga executar o bwrap recebe essa permissão, exceto um job de repositório (o filtro do Loom); e `/proc` e `/sys` passam a depender das regras do perfil em vez das máscaras do Docker. Pese isso contra executar código de repositório sem o sandbox. `seccomp=unconfined` e `apparmor=unconfined` também funcionam onde o host não restringe namespaces de usuário, mas descartam o perfil inteiro.
+
+**Sem o sandbox**, o Loom faz um teste uma vez por processo, registra um aviso no log e informa `repo_jobs_unsandboxed` em `/v1/health` e em `loom doctor`. Com `LOOM_CODE_SANDBOX_REQUIRED=true`, todo job de repositório é recusado (acima). Caso contrário:
+
+- os repositórios do operador (`LOOM_CODE_REPOS_JSON`) mantêm todas as camadas, e seus passos de build rodam como processos comuns no host, como antes;
+- os repositórios autorregistrados cujo remoto é uma URL de rede não são clonados nem buscados e não recebem a camada do compilador: sem o proxy de saída, nada validaria os hosts e as portas aos quais um job se conecta. A nota da passagem de ingestão e `workers.status` informam o que foi ignorado; a entrada é retomada quando o sandbox estiver disponível;
+- os repositórios autorregistrados em um caminho local mantêm a camada do parser e as camadas estáticas do compilador, mas não recebem nenhuma camada baseada em build (C/C++);
+- adicionar um repositório ou um branch pelo painel é recusado com `SANDBOX_UNAVAILABLE`.
+
+Cada entrada Go tem seu próprio cache de módulos em `LOOM_CODE_SCIP_GO_MODCACHE` (`//`): o `go` não verifica de novo as somas dos módulos que já estão no cache, então um cache gravado pelo job de um repositório nunca é usado pelo job de outro.
+
+
+
+### Manutenção dos espelhos
+
+Cada processo servidor executa `git gc --no-prune` nos espelhos do seu host a cada `LOOM_CODE_MIRROR_GC_INTERVAL_H` (com baixa prioridade de CPU e de IO, e somente se houver espaço para uma segunda cópia mais `LOOM_CODE_MIRROR_GC_MARGIN_GB`, 5 GB por padrão; sem esse espaço, o gc espera outro intervalo e registra um aviso no log). Também varre `LOOM_CODE_REPOS_ROOT`, removendo os espelhos, as árvores `checkout-*` e os arquivos de lock de espelho que nenhuma entrada ativa nomeia, de modo que um repositório removido sai de todos os hosts, e não apenas daquele que `code.repo.remove` alcançou. Os gauges `loom.host.disk.free_bytes` / `loom.host.disk.total_bytes` são a entrada do alarme de disco.
+
+
+
+## Cobertura medida
+
+Um repositório cujo CI executa um build instrumentado com cobertura de linhas por teste pode alimentar o mapa de testes com o que cada teste executou, e não apenas com o que ele nomeia. A importação lê a execução completa mais recente do servidor ClickHouse que contém as tabelas `checks_coverage_lines` e `checks` do CI, em `LOOM_CODE_COVERAGE_SHARDS` fatias por hash de arquivo. Uma fatia precisa caber na memória por consulta desse servidor. Um servidor com cota por hora para cada formato de instrução também precisa comportar uma importação inteira (duas instruções por fatia) mais uma nova tentativa. Um playground público permite 100 instruções por formato por hora; as 16 fatias padrão usam 16 de cada, então uma execução de teste (dry run) e uma execução real cabem na mesma hora.
+
+Ela grava:
+
+- uma linha de `code_test_map` por (arquivo-fonte, teste), com `method = coverage`, quando o teste executou uma linha alcançada por no máximo `LOOM_CODE_COVERAGE_SPECIFIC_MAX_TESTS` testes (uma linha que toda consulta executa não nomeia nenhum teste); `confidence` diminui conforme o número de testes que compartilham a linha mais específica do par, e `evidence` guarda o commit da execução e os intervalos de linhas específicas;
+- uma linha de `code_coverage_files` por arquivo-fonte, com todos os intervalos executados por qualquer teste, de modo que `code.coverage_claim` consiga distinguir "executado por muitos testes" de "executado por nenhum".
+
+As linhas que a execução mais recente não tem mais recebem marca de exclusão (tombstone), e isso só ocorre depois que todas as fatias foram lidas. `code.coverage_claim` classifica uma linha medida como `executed`, acima de todas as outras camadas, quando seus intervalos encontram o trecho do assunto; um assunto cujo arquivo a execução cobriu, mas cujas linhas nenhum teste executou, é `uncovered`, com a medição em `measured`.
+
+```bash
+LOOM_CODE_COVERAGE_SOURCE_URL=https://
+LOOM_CODE_COVERAGE_SOURCE_USER=
+LOOM_CODE_COVERAGE_NAMESPACES=[,]
+loom code coverage-import --namespace --dry-run # counts only, writes nothing
+loom code coverage-import --namespace
+LOOM_CODE_COVERAGE_IMPORT_ENABLED=true # then daily, in the workers
+```
+
+
+
+## Outra branch
+
+Um namespace acompanha uma branch, e uma branch só é indexada quando uma entrada a nomeia. Adicione uma entrada com o mesmo `repo` e um `namespace` e `git_branch` diferentes; ela compartilha o clone bare. Defina `embed_reuse_from` com o namespace da branch principal para que chunks idênticos reutilizem os embeddings. Em seguida, execute `loom code init` e `loom code backfill` para o novo namespace, como no primeiro índice.
+
+
+
+## Reparos
+
+`loom code reconcile --namespace NS` lista os caminhos indexados cujos chunks são anteriores à última
+alteração no head do branch; `--heal` os reingere sem mover a marca d'água.
+
+**Após uma mudança no extrator.** O código dos módulos em `EXTRACTOR_MODULES`
+(`server/code/domain/extract/extractor_stamp.py`) e as versões das gramáticas formam o
+carimbo de versão do índice. O carimbo faz hash apenas dos tokens de código; edições em comentários e docstrings
+não o alteram. Quando um deploy move o carimbo, `code_ingest` rederiva os arquivos ativos de
+cada namespace nas famílias de linguagens que a mudança afeta,
+`LOOM_CODE_EXTRACTOR_RECHUNK_PER_PASS` arquivos por passagem, e executa apenas as etapas (chunk,
+symbol, edge, guard) cujo carimbo mudou. `code.index_status` mostra o progresso nas
+chaves de estado `extractor_stamp*`. Em um índice grande, isso leva horas.
+
+**Após uma mudança fora do carimbo** (uma faixa de linguagem, uma faceta, um novo tipo de arquivo),
+as linhas existentes não são corrigidas automaticamente. Reingira os caminhos afetados na
+marca d'água do próprio namespace:
+
+```bash
+HEAD=$(docker exec loom-workers loom code stats --namespace "$NS" | awk '$1 == "git_head" {print $2}')
+git --git-dir var/code_repos/.git ls-tree -r --name-only "$HEAD" | grep -E '\.(sql|sh)$' > /tmp/$NS-paths.txt
+docker cp /tmp/$NS-paths.txt loom-workers:/tmp/
+docker exec loom-workers loom code backfill --namespace "$NS" --commit "$HEAD" --no-fetch --embed \
+ --paths-file /tmp/$NS-paths.txt
+```
+
+`--paths-file` é o modo de reparo: reingere apenas os caminhos listados e deixa a
+marca d'água intacta. Arquivos cujo conteúdo não mudou mantêm seus chunks e embeddings;
+símbolos, facetas e arestas são rederivados. Adicione `--edges-second-pass` quando muitos arquivos ganharem
+símbolos de uma só vez.
+
+As faixas opcionais são ativadas por configurações; depois de ativar uma, execute o reparo nos
+caminhos correspondentes:
+
+| Configuração | Padrão | Faixa |
+| --------------------------------- | ------- | ----------------------------------------------------------------------------------- |
+| `LOOM_CODE_SQL_STATEMENT_RECORDS` | off | arquivos `.sql` como um símbolo `statement` por instrução, com facetas de dialeto e tabela |
+| `LOOM_CODE_SHELL_ISLANDS` | off | SQL emitido por scripts de shell como registros de instrução |
+| `LOOM_CODE_PY_SQL_ISLANDS` | off | strings SQL em chamadas Python como registros de instrução |
+| `LOOM_CODE_HOST_ISLANDS` | off | workflows de CI, Dockerfiles e Makefiles: jobs, estágios e alvos como símbolos |
+
+`scripts/ops/code_edge_audit.py` é um censo somente leitura dos dois buracos silenciosos do grafo de chamadas
+da camada do parser (pontos de chamada recusados cujo callee agora tem uma definição, e arestas
+de baixa qualidade cujo destino não existe mais); execute-o com `LOOM_BACKGROUND_WORKERS=off` em uma cópia
+de staging.
+
+
+
+## Comandos de manutenção
+
+| Comando | O que faz |
+| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `loom code compact [--table T] [--apply]` | mede e, com `--apply`, executa `OPTIMIZE … FINAL` em uma tabela de vetores de código quando suas cópias físicas por chave atingem `LOOM_CODE_COMPACT_MIN_RATIO` (1.5), e aguarda o merge; as passagens em lote fazem isso sozinhas depois de `LOOM_CODE_COMPACT_AFTER_BULK_ROWS` linhas ([manutenção](maintenance.md#compaction-and-optimize)) |
+| `loom code warm ` | faz cada pergunta uma vez para que as respostas de `code.ask` fiquem em cache para todos (linhas de texto ou JSONL com `question`); os acertos são gratuitos, então executar novamente é seguro |
+| `loom code answers-purge` | aposenta as respostas de `code.ask` em cache após uma mudança no modelo de síntese (caso contrário, o cache só é invalidado quando um arquivo citado muda); simulação até usar `--apply` |
+| `loom code repack` | reconstrói os pacotes de contexto dos PRs mesclados recentemente no formato atual |
+| `loom code crossref` | a passagem de referência entre teste SQL/shell e o C++ que o implementa (idempotente) |
+| `loom code coverage-import [--dry-run]` | importa a execução mais recente de cobertura de linhas por teste da fonte configurada para o mapa de testes ([cobertura medida](#measured-coverage)) |
+| `loom code reembed`, `loom code vector-twin` | gravam os chunks de um namespace sob o rótulo de um segundo modelo de embedding, ou preenchem um gêmeo de prefixo Matryoshka dos vetores, dentro do ClickHouse; retomável |
+| `loom code lint-instructions` | lista caminhos e referências `Qualified::symbol` em `CLAUDE.md`, `AGENTS.md`, `.claude/**` e skills que não resolvem mais no head; `--fail-on-stale` para CI |
+| `loom code export-matrix` | grava, para um arquivo de instruções, uma tabela "quando este arquivo muda, estes geralmente mudam também", a partir da mudança conjunta em PRs mesclados |
+| `loom code export-pairs` | exporta pares de recuperação (consulta → unidade utilizada, negativos difíceis) a partir de tráfego real, para ajuste de embedder ou reranker |
+
+`make bench-code-intel LOOM_BASE_URL=…` executa o portão de qualidade do índice de código
+(`bench/code_intel_qa.py`) contra um servidor com provedores reais, para um repositório que
+tenha um conjunto de perguntas de referência; ele nunca é executado no CI, cujo embedder é falso
+([testes de desempenho](https://github.com/ClickHouse/loom/blob/main/docs/benchmarks/running.md)).
+
+
+
+## Implantação e desligamento
+
+- `LOOM_MCP_CODE_TOOLS` (desativado por padrão) lista as ferramentas `code.*` no conjunto de ferramentas MCP padrão. O conjunto de ferramentas `coding` as lista independentemente dessa variável, e o HTTP e os SDKs sempre podem chamá-las, de modo que você pode avaliar um índice antes de expô-lo a clientes de chat.
+- `LOOM_CODE_INTEL_ENABLED=false` faz com que toda operação `code.*`, exceto `code.repo.remove`, retorne um erro de pré-condição. Também interrompe os workers de importação de cobertura e de notificação e o loop do host de mirror; cada um dos outros workers de código tem seu próprio interruptor ([workers de segundo plano](https://github.com/ClickHouse/loom/blob/main/docs/reference/workers.md)).
+- **Desativar um repositório.** Um mantenedor usa **Retire…** na aba Access do repositório (`code.repo.remove` com `confirm` definido como o namespace). A entrada fica inativa, uma saga de eliminação apaga todas as tabelas `loom.code_*` do namespace, e o mirror bare é excluído quando nenhuma outra branch o usa. A telemetria de busca é mantida. Uma entrada configurada pelo operador é recusada com `REPO_FROM_CONFIG`: remova-a de `LOOM_CODE_REPOS_JSON`. Com `LOOM_CODE_INTEL_ENABLED=false`, a página não consegue listar repositórios, mas `code.repo.remove` via HTTP, MCP ou SDK continua sendo atendido; nesse caso, as outras réplicas só limpam a própria cópia do mirror quando a inteligência de código for ativada novamente.
+- **Apagar um índice.** `erasure.request` com `scope_type = namespace` em um namespace de código também apaga as tabelas `loom.code_*`. Uma entrada que ainda está configurada é reindexada do zero na próxima passagem, portanto desative-a primeiro.
+
+
+
+## Quando uma camada falha
+
+Cada camada que mantém uma entrada atualizada (o fetch do mirror, o ingest do parser e toda camada do compilador) registra seu último resultado na entrada: quando falha, o erro com as credenciais ocultadas, um tipo de erro, a única correção para esse tipo, `failing_since` e o número de execuções consecutivas que falharam. A próxima execução que for bem-sucedida limpa o registro. Uma camada executada a partir do cron registra da mesma forma quando roda sob `loom code entry-lock --tier `; `loom code scip-delta` e `scip-full` registram por conta própria.
+
+Um módulo Go cujas dependências este host não consegue buscar (o Go informa um repositório privado, muitas vezes os próprios módulos do repositório por meio de um caminho de importação vanity) não é uma falha: a camada Go indexa o restante e registra a camada como `unavailable`, tipo `dependency_unavailable`, com a correção (defina `LOOM_CODE_SCIP_GO_PRIVATE` e forneça ao usuário da camada uma credencial git para esse host; o Go diz o mesmo sobre um caminho ou uma versão que está errada ou não existe mais). A nota é escrita uma única vez, não conta execuções, nunca é um problema `code_tier_failing` e não aparece em `as_of.failing_tiers`, de modo que a resposta de código de um agente não sinaliza esses módulos. Ela reflete a última execução que compilou módulos: uma execução que não compila nada a mantém, e a próxima execução que compilar sem essa falha a limpa, de modo que ela volta quando um módulo que ainda não consegue buscar sua dependência muda novamente. Sob `entry-lock --tier go`, que enxerga apenas o código de saída e a saída do seu comando, uma saída limpa sem essa falha a limpa. Um módulo que falha por qualquer outro motivo ainda faz a camada falhar, e o registro dela nomeia também os inacessíveis.
+
+O registro é lido onde cada leitor já olha:
+
+- as respostas de código de um agente o trazem em `as_of.failing_tiers`
+ ([atualização dos dados](../features/code-index/freshness.md#the-as_of-block));
+- `code.index_status` e `code.repos` o retornam em `tier_health`, e o cartão do repositório no painel mostra a camada com falha, desde quando, quão atrasada está e a correção, além de qualquer camada `unavailable` com sua correção;
+- quando uma camada falha por `LOOM_CODE_TIER_FAILING_WARN_PASSES` execuções consecutivas ou por `LOOM_CODE_TIER_FAILING_WARN_HOURS`, ela se torna o problema `code_tier_failing` em `/v1/health`, no banner do painel e em `loom doctor` ([monitoramento](monitoring.md#v1health)): uma linha por entrada e camada com falha, até cinco, com o motivo, e cada correção distinta uma vez. `loom doctor`, que lê com as credenciais do próprio deployment, também nomeia cada entrada que lista, até cinco, como repositório@branch (org/namespace) com a linha de erro que explica o motivo; `code.repos` nomeia as demais. O token de um administrador da plataforma lê o mesmo para toda entrada que não seja [restrita](https://github.com/ClickHouse/loom/blob/main/docs/architecture/security.md#restricted-namespaces); uma restrita aparece como "a restricted entry", assim como uma cuja classificação não pode ser lida. Qualquer outro chamador não lê nenhuma entrada, já que `/v1/health` responde sem token;
+- para alertas por push, os gauges `loom.code.tier_failing` e `loom.code.tier_lag_commits` trazem cada camada que o problema `code_tier_failing` reporta ([telemetria](../features/observability/telemetry.md)), com um alerta em `deploy/dashboards/code_plane.json` e, para o Prometheus, a regra do chart ([regras de alerta](kubernetes.md#alert-rules)).
+
+Os tipos (`_KINDS`) e suas correções (`fix_for`) estão em
+[`server/code/domain/index/tier_health.py`](https://github.com/ClickHouse/loom/blob/main/server/code/domain/index/tier_health.py).
+Uma falha que não corresponde a nenhum tipo aparece como "unclassified error" e traz o final da saída para leitura.
+
+
+
+## Modelo de falhas
+
+| Falha | Comportamento | Recuperação |
+| ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `git fetch` falha | a marca d'água não se move; a camada `fetch` da entrada registra o erro, seu tipo e a correção (`tier_health`) | a próxima passagem (backoff do supervisor) |
+| falha no meio de um commit | o commit é executado de novo | upserts idempotentes |
+| um arquivo falha ao ser analisado | chunks sem símbolos, com `code_files.index_error` definido (inclusive uma análise além de `code_parse_timeout_s` ou `code_parse_memory_mb`, e uma que não pôde ser executada em seu processo) | `code.index_errors` lista esses arquivos; corrigido pela próxima alteração ou por um reparo (aumentar qualquer um dos limites não releitura nenhum) |
+| todo arquivo falha ao ser analisado com `LookupError` "... is loaded from outside the interpreter's site-packages" | chunks sem símbolos para todos os arquivos: o tree-sitter ou uma gramática está instalado onde o processo de análise não o enxerga | instale os pacotes do tree-sitter no ambiente do próprio interpretador do servidor, não por meio de `PYTHONPATH` nem do site do usuário |
+| provedor de embeddings fora do ar | chunks armazenados sem vetores; a busca lexical continua funcionando | `code_embed_recovery` |
+| falha ao aplicar a camada do compilador | lote `failed` com o erro | `loom code scip-retry ` |
+| uma passagem da camada do compilador falha ou trava | o timeout do harness encerra uma trava, e o prazo da passagem (esse timeout mais folga para as etapas do git e para a aplicação) cancela qualquer outro caso; o lock da entrada é liberado; uma falha que a passagem reporta (inclusive o próprio timeout do harness) é registrada com seu tipo e correção em `tier_health` | a próxima passagem; `workers.status` informa o timeout |
+| base da janela da camada do compilador desconhecida (histórico reescrito, espelho podado) | toda camada de `scripts/scip_harness/` sai com 3, nunca com um delta vazio; os workers de Python, TypeScript e Go limpam a marca d'água da camada | a próxima execução é uma indexação completa dessa camada (`code_scip_full` para C/C++) |
+| um delta da camada do compilador é um link, não um arquivo regular, ou é grande demais, ou o harness do Go grava mais deltas do que módulos | o delta é recusado (`FileRefused`, ou `Go harness wrote more deltas than its N module(s)`) e a passagem da entrada falha; a marca d'água permanece | grande demais: aumente `LOOM_CODE_SCIP_DELTA_FILE_MAX_MB` e `LOOM_CODE_SCIP_DELTA_MAX_NODES` (eles limitam o trabalho e o texto de caminho mantido); para uma entrada de arquivo acima do orçamento da rodada, aumente `LOOM_CODE_SCIP_DELTA_ROUND_MAX_NODES`, dentro da memória do worker; uma entrada de arquivo acima do limite fixo de caracteres é nomeada, e nenhuma configuração altera esse limite: o que se deve dividir é o arquivo que ela indexa; um link, um arquivo não regular ou deltas extras se repetem a cada passagem até o repositório mudar ou a entrada ser removida |
+| limite de taxa do GitHub | a passagem termina, cursor não se move | a próxima passagem |
+| branch com force-push (a marca d'água não é mais um ancestral) | marca d'água redefinida para o novo head, com registro em log | `loom code backfill` para derivar de novo |
+| falha nas estatísticas semanais do grafo | os rankings da semana anterior continuam sendo servidos | a próxima passagem semanal |
+
+Os indicadores do índice de código (`loom.code.index_lag_commits`, `loom.code.stale_files`,
+`loom.code.tier_lag_seconds`, `loom.code.embed_backlog`, `loom.code.files_errored`) estão
+catalogados em [telemetria](../features/observability/telemetry.md); o que merece alerta está em
+[monitoramento](monitoring.md#what-to-alert-on), e o painel "Loom — Code Plane" está
+definido em `deploy/dashboards/code_plane.json`.
+
+
+
+## Relacionados
+
+- [Repositórios](../features/code-index/repositories.md): repositórios de autoatendimento,
+ mantenedores e leitores
+- [Atualização](../features/code-index/freshness.md): como um cliente lê o atraso do índice
+- [Arquitetura do índice de código](../architecture/code-index-architecture.md)
diff --git a/i18n/.pending/zh-CN/docs/concepts/memory.md b/i18n/.pending/zh-CN/docs/concepts/memory.md
new file mode 100644
index 0000000000..c39940f0e9
--- /dev/null
+++ b/i18n/.pending/zh-CN/docs/concepts/memory.md
@@ -0,0 +1,425 @@
+
+> 本页由机器从[英文原文](https://github.com/ClickHouse/loom/blob/main/docs/concepts/memory.md)翻译,内容以英文原文为准。
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/concepts/memory.md), which is authoritative.
+
+
+
+# 记忆
+
+一条记忆就是 agent 之后应当能再次找到的一个论断,例如“部署在周二进行”“支付团队负责账单服务”。Loom 把每个论断存为 `loom.memory` 中的一行,使用可读的键,并记录写入者、论断成立的时间、来源,以及是否有人为其背书。本页介绍这一行的结构、写入时如何与已存储的内容比对判定,以及行如何随时间变化。[检索与排序](https://github.com/ClickHouse/loom/blob/main/docs/concepts/retrieval-and-ranking.md)介绍如何找到这些行。
+
+
+
+## ClickHouse 中的行
+
+记忆、文档分块、对话轮次、实体边、代码符号、运行记录、审计条目和擦除请求,都是 ClickHouse 中的行,由服务器在启动时应用的编号迁移创建。在 [Postgres 记忆权威](../architecture/storage-authority.md#why-two-stores)模式下,Postgres 保存实时的记忆和知识状态,ClickHouse 则保存向量、搜索和历史记录。上传的文档原件也是 ClickHouse 中的行(`loom.document_blobs`),除非部署把它们的字节保存在兼容 S3 的存储桶中。除了 ClickHouse、Postgres 和该存储桶之外,Loom 还在共享卷上保存代码索引的 git 镜像(即 ClickHouse 所记录远程仓库的缓存)以及限流桶。
+
+- **身份元组位于排序键的最前面。** `loom.memory` 按 `(org, namespace, agent, user_id, session_id, memory_key)` 排序,因此把读取限定在某个命名空间内就是一次主键范围查询;只有在指定了 agent 的情况下,user 才能完全缩小范围;只有在指定了 agent 和 user 的情况下,session 才能完全缩小范围。[身份与命名空间](https://github.com/ClickHouse/loom/blob/main/docs/concepts/identities-and-namespaces.md)介绍了这个元组。
+- **单一引擎。** 在默认的 ClickHouse 权威模式下,向量搜索、词法搜索、图遍历、过滤、审计和擦除都是针对同一批行的 SQL,无需再维护另一个需要保持同步的存储。代价是每次读取都是一次查询,而不是键值命中。在 Postgres 权威模式下,点读取(按键或 id 读取,且不在 `as_of` 回放中)由 Postgres 响应。
+- **写入即新版本。** 记忆表使用 `ReplacingMergeTree(version)`,并通过 `FINAL` 读取。修订、墓碑标记、固定或恢复操作都会插入一条新的版本行。
+
+
+
+## 写入、派生、读取循环
+
+```mermaid
+flowchart LR
+ W["Writer: memory.set, set_from_messages, knowledge.add"] --> G["Write checks: lock, pin, blacklist, precondition, conflict"]
+ G --> T[("ClickHouse rows: memory, embeddings, chunks, audit_log")]
+ T --> D["Workers derive: entities, deferred extraction, consolidation, calibration, usage folds"]
+ D --> T
+ R["Reader: memory.search, memory.ask, context.pack"] --> L["Retrieval legs: vector, lexical, graph, chunks, digests"]
+ T --> L
+ L --> K["Fuse and rank, gate or abstain"]
+ K --> A["Answer with provenance"]
+ A --> F["run.complete, memory.outcome"]
+ F --> T
+```
+
+1. **写入。** `memory.set` 会先执行各项检查(见[下文](#how-a-write-is-judged)),然后内联生成嵌入向量,并插入记忆行、对应的嵌入行、长值的原文分块(verbatim chunks)以及一条仅含哈希的审计行。如果内联嵌入失败,调用即失败,不会写入任何内容。`memory.set_from_messages` 由 LLM 从对话记录中挑选出需要长期保留的事实,并通过同样的批量路径写入。
+2. **派生。** Workers 负责处理对写入路径来说太慢的工作:实体标签(`entity_extractor`)、延迟提取(`extraction_queue`)、整合后的事实、门限重新校准,以及折算为排序信号的使用情况(`usage_fold`)。派生行带有 `source_class=derived`。
+3. **读取。** `memory.search` 会运行多条检索路径(向量、词法、实体图、原文分块、会话摘要),将结果融合并排序,然后返回命中结果或放弃回答。`memory.ask` 生成有依据的回答;`context.pack` 构建受预算限制的提示词块。
+4. **反馈。** 如果一次运行指明了它所依赖的记忆(`run.complete` 的 `memories_used`,或 `memory.outcome`),这些记忆会获得加分;结果不佳则记录损害。这会形成一个有界且随时间衰减的排序项。它不会删除任何行,也不会把某一行排到其相关性应有的位置之下。
+
+该循环是最终一致的。写入后立即读取,可以通过内联嵌入找到该事实;实体和提取出的事实会在 worker 下一轮处理之后出现。
+
+
+
+## `loom.memory` 行
+
+一行是一条记忆的一个版本。
+
+| 分组 | 列 | 决定 |
+| ---------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| 身份 | `org`, `namespace`, `agent`, `user_id`, `session_id`, `run_id` | 谁可以读取它,以及谁写入了它 |
+| 地址 | `memory_key`, `memory_id` | 调用方如何称呼它(key),以及 Loom 如何称呼一行(id) |
+| 内容 | `value`, `memory_type`, `tags`, `entities`, `files`, `confidence` | 它说了什么,以及如何分类 |
+| 生命周期 | `status`, `pinned`, `conflict_with`, `duplicate_of`, `superseded_by`, `version` | 它是否被提供,以及被什么取代 |
+| 时间 | `created_at`, `updated_at`, `valid_at`, `valid_to`, `invalid_at`, `expires_at` | 它何时写入,何时有效,何时停止服务 |
+| 来源 | `actor`, `source_class`, `content_sha256`, `verified_by`, `verified_sha256` | 谁写入了它,Loom 如何得知它,是否有人证实过它 |
+| 防护 | `lock_mode`, `lock_until`, `sensitivity`, `on_expire` | 它拒绝哪些写入,以及如何读取它 |
+
+完整的列列表见[schema 参考](https://github.com/ClickHouse/loom/blob/main/docs/reference/schema.md)。可搜索的记忆在 `loom.memory_embeddings` 中也有一行:包含 value 和 key 的向量,用于词法匹配的摘录的小写、词干提取和词形还原副本,以及排序器读取的 `source_class` 和 `verified` 标志。
+
+
+
+## 键
+
+一个键以可读路径 `//` 命名某个主体的某一项属性:
+
+```
+sre/case/1234/evidence/dns-sidecar
+project/loom/deploy-window
+user/preferences/editor
+```
+
+- **一个键只存一条事实。** 冲突检查、取代和历史都按键进行。如果一个键里存放了多条互不相关的事实,就无法只修订其中一部分。
+- **修订时重写同一个键。** Loom 会保留每个版本,因此带编号的副本(`…-v2`)或由值的哈希生成的键只会掩盖修订。由哈希生成的键会在 `namespace.audit` 中作为 `hash_keys` 发现项列出。
+- **分面信息放在 `tags` 和 `entities` 中,** 不要放进键里。
+
+存储标识为 `(org, namespace, agent, user_id, session_id, memory_key)`:同一个键由两个 agent 写入,或在两个会话中写入,就是两行记录。在命名空间策略 `newest_wins` 下,某个键的最新写入会使该命名空间中所有带该键的较旧有效行失效,无论是谁写入的。提取时,键由主体和属性生成,而不是由值生成,因此之后的会话如果陈述同一属性,就会落在同一个键上。在 `auto_reinforce` 和 `manual_review` 下,冲突解析器会判定同一用户的两个会话(不包括匿名用户 `-` 或发送为空的 user_id,它们的会话属于相互独立的任务)通过单点写入或批量写入而写下的同一个键的各行,判定方式与判定任何相近的记录对相同:对于它有把握判定为更新的情况,它会使较旧的行失效(`manual_review` 下除外),将矛盾标记为待审核,并让复用同一个键的两条不同事实保持有效。在 `append_only` 下不做任何判定。
+
+
+
+## 记忆类型
+
+`memory_type` 是自由字符串,默认值为 `semantic`。少数取值会改变该行的存储和检索方式(`server/memory/domain/memory_types.py`):
+
+| 类型 | 是否嵌入 | 是否出现在未过滤的搜索中 | 用途 |
+| ---------------------- | -------- | ------------------------ | -------------------------------------------------------- |
+| `semantic`(默认) | 是 | 是 | 持久的事实。 |
+| `preference` | 是 | 是 | 应在召回中排名靠前的偏好。 |
+| `procedural` | 是 | 是 | 流程(`procedure.*`)。 |
+| `reflection` | 是 | 否 | 从运行中得到的经验教训;使用 `memory_type="reflection"` 读取。 |
+| `episodic` | 否 | 否 | 按时间先后重放的会话事件。 |
+| `profile` | 否 | 否 | 按标签获取、始终加载的上下文(`profile.*`)。 |
+| 其他任意值(`decision`) | 是 | 是 | 领域类型默认可被搜索。 |
+
+- **反思不会出现在**未过滤的搜索和 `memory.ask` 中:关于某个流程的经验教训,并不是对世界的陈述。
+- **`procedural` 写入**的值如果不是流程主体(非空的 `situation` 和至少两个 `steps`),则会以 `semantic` 存储,并标记 `retyped_from:procedural`,响应会在 `retyped_from` 中说明这一点。
+- **敏感度。** `sensitivity="high"` 的行不会被嵌入,因此任何搜索分支都找不到它。它只能通过 key 读取,且该读取会被审计。未设置 `sensitivity` 时,服务器会检测凭据格式、银行卡号、美国社会安全号码和明示的 PIN(`high`),以及电子邮件、电话和 IBAN 格式(`medium`)(`LOOM_MEMORY_SENSITIVITY_AUTODETECT`)。
+
+
+
+## 状态
+
+| 状态 | 含义 | 默认是否返回 |
+| ------------ | -------------------------------------------------------------------------- | ------------------------- |
+| `active` | 当前有效的记忆。 | 是 |
+| `conflicted` | 与另一条记忆相近但内容不同,通过 `conflict_with` 关联。 | 是 |
+| `duplicate` | 与某条规范记录(`duplicate_of`)几乎完全相同,由该规范记录代为应答。 | 否(`include_duplicates`) |
+| `superseded` | 已被后来的记录取代(`superseded_by`,在 `invalid_at` 失效)。 | 否(`include_superseded`) |
+| `proposed` | 处于试用期的事实,通过 `memory.proposal_decide` 决定去留。 | 否(`include_proposed`) |
+| `rejected` | 被标记为错误(`memory.reject`,或被拒绝的提议)。 | 否 |
+| `tombstoned` | 已被其写入者删除(`memory.delete`)。 | 否 |
+
+默认返回的状态集合只在 `server/memory/domain/temporal_sql.py`(`SERVED_STATUSES`)中定义一次。conflicted 记录仍会被返回:如果隐藏矛盾的某一方,存储就会用一条自己有理由怀疑的事实自信地作答。
+
+
+
+## 写入如何被判定
+
+五个操作覆盖记忆的整个生命周期:
+
+| 视角 | 操作 | 效果 |
+| --------- | --------------------- | -------------------------------------------------------------------------- |
+| 扩展 | `memory.set` | 在某个 key 下记录一条事实。 |
+| 修订 | `memory.update_by_id` | 按 id 修正一行(`memory.update` 按 key 做同样的事)。 |
+| 收缩 | `memory.delete` | 为某个 key 打上墓碑标记。`memory.restore` 可在删除后 14 天内恢复。 |
+| 强化 | `memory.pin` | 存储并固定:之后任何本身不固定的写入都不能替换它。 |
+| 拒绝 | `blacklist.add` | 拒绝此后所有匹配某个子串或正则表达式的写入。 |
+
+可搜索的 `memory.set` 按顺序执行以下检查:
+
+1. **锁与固定保护**,作用于该 key 下的现有行。`memory.lock`(`read_only` 或 `no_delete`)返回 423 `LOCKED`。对已固定的 key 写入不同的值,返回 409 `PINNED_CONFLICT`。逐字节相同的重复陈述可通过所有保护。
+2. **黑名单。** 值匹配已登记的模式时返回 422 `BLACKLISTED`;在批量写入中,该条目会被跳过。各副本缓存这些模式,并轮询一张只有一行的版本表(`loom.blacklist_version`),因此新模式会在数秒内到达每个副本。
+3. **前置条件。** `if_match_sha256` 使写入只在当前有效行的哈希仍然匹配时才生效;否则返回 409 `PRECONDITION_FAILED`。当前哈希(`content_sha256`)会包含在每个 `memory.get`、`memory.get_by_id` 和 `memory.set` 的响应中。
+4. **重复陈述。** 与当前有效行逐字节相同的值,会写入一个新版本,并带上当前有效行的 `reinforcement_count + 1`。批量路径(`memory.bulk_set`,由 `set_from_messages` 使用)把 `(org, namespace, agent, user_id)` 内任何哈希相同的有效行视为同一条事实(`LOOM_MEMORY_BULK_DEDUP_SCOPE=identity`)。
+5. **近邻搜索与判定。** 同一 `memory_type` 中、嵌入向量与新值接近的活跃行是**近邻**,按距离由近到远比较;指明了 `user_id` 的写入只从该用户的行中取近邻([写入如何被判定](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/conflicts-and-refusal.md#how-a-write-is-judged)):
+ - 规范形式相同(转为小写、去除标点、合并空白)→ `merge`:不写入任何内容,近邻被强化,`merged_into_key` 指明它;
+ - 存在接近的已固定近邻 → `rejected`,409 `PINNED_CONFLICT`(在覆盖整个命名空间的令牌下,如果写入指明了用户,并重复陈述了其他用户的或共享的已固定值,则会被写入);
+ - 在 `newest_wins` 下,如果某个近邻陈述了相同的主语和谓语但宾语不同 → `refines`:该近邻被停用,除非它的 `valid_at` 晚于新行的,此时返回 `conflict`;
+ - 余弦相似度达到或超过重复阈值,且实词相同、没有不同的取值(数字、时间、金额或单位;如 "27:10" / "26:30")→ `duplicate`;
+ - 余弦相似度达到或超过冲突阈值但内容不同 → `conflict`,两行均标为 `conflicted`;
+ - 没有接近的近邻 → `clear`。
+6. **插入**到 `loom.memory` 和 `loom.memory_embeddings`,并执行取代、实体投影,以及在 `loom.audit_log` 中写入一行仅含哈希的记录。
+
+不可搜索的类型或 `high` 敏感度的行会跳过近邻搜索:它们没有可供比较的嵌入向量。`dry_run=true` 会运行所有检查但不写入任何内容,可在你确定 key 之前回答“这是新事实、重复陈述还是矛盾?”。响应包含 `conflict_verdict`、最多五个 `peers` 以及一个 `next` 提示。
+
+- **阈值。** 开启 `LOOM_ADAPTIVE_THRESHOLDS` 并使用真实的嵌入器时,冲突阈值和重复阈值在启动时由该嵌入器自身的相似度分布得出(`server/memory/app/embedder_calibration.py`)。标量 `LOOM_CONFLICT_THRESHOLD`(0.85)和 `LOOM_DUPLICATE_THRESHOLD`(0.97)作为回退值。命名空间或记忆类型可以固定自己的阈值;`calibration.get` 会报告当前生效的是哪一个。
+- **冲突解析器。** 余弦相似度只说明两条陈述讲的是同一件事,不说明它们是否一致。一个仅在 leader 上运行的 worker 会在写入落地后,对每条带有接近近邻的写入做判断,每行一次 LLM 调用:在默认的 `auto_reinforce` 和 `newest_wins` 下,对于它确信是更新的情况,会停用较旧的行(旧值仍可通过 `include_superseded` 和 `as_of` 读取),标记矛盾,并清除错误的标记([冲突](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/conflicts-and-refusal.md#the-conflict-resolver))。对写入本身的判定不会调用 LLM。
+- **运行范围。** 在某个 `run_id` 下的写入,如果其规范匹配项属于另一次运行,则按 `duplicate` 存储而不合并,因此限定运行范围的读取仍能找到它。
+- **命名空间策略。** `default_conflict_policy` 决定矛盾如何处理(`auto_reinforce`、`manual_review`、`newest_wins`、`append_only`)。
+
+`memory.update`、`memory.update_by_id` 和 `memory.bulk_set` 运行相同的检查。判定细节、各项策略、Review 队列和 `conflicts.resolve` 见[冲突与拒绝](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/conflicts-and-refusal.md)。
+
+**固定保护用户说过的内容。** 已固定的行不会被本身不固定的写入替换,无论是按 key 写入,还是在另一个 key 下写入接近的值。要修改它,请使用 `memory.update`(保留固定状态)或 `memory.pin`(重新固定)。`memory.for_file` 会把已固定的行排在最前;其他读取都不按固定状态排序。
+
+**整合会保留谱系。** `memory.consolidate`(以及命名空间选择启用时的整合 worker)把关于同一主题的片段合并为 `source_class='derived'` 的规范行,并为每个来源写入一行 `loom.memory_belief_sources`(`support_type='derived_from'`)。删除某个来源时,如果整合行的所有来源都不再存在,则该行被停用;如果仍有部分来源存在,则降级为 `conflicted`(`memory.delete` 响应中的 `dependents_tombstoned`、`dependents_downgraded`)。
+
+
+
+### 记忆的生命周期
+
+```mermaid
+stateDiagram-v2
+ [*] --> active: memory.set (clear, refines)
+ [*] --> conflicted: memory.set (conflict)
+ [*] --> duplicate: memory.set (duplicate)
+ [*] --> proposed: memory.set(proposed=true)
+ active --> conflicted: a later close write
+ conflicted --> active: conflicts.resolve (revise, allow)
+ conflicted --> tombstoned: conflicts.resolve (contract, or peer revised)
+ proposed --> active: memory.proposal_decide (accept)
+ proposed --> conflicted: memory.proposal_decide (accept, contradicted on trial)
+ proposed --> rejected: memory.proposal_decide (reject)
+ active --> rejected: memory.reject
+ active --> superseded: newer write (newest_wins, refines, conflict resolver)
+ superseded --> active: memory.restore
+ active --> tombstoned: memory.delete, blacklist sweep, expiry
+ tombstoned --> active: memory.restore (within 14 days)
+```
+
+每个箭头都是一个新版本;旧版本保留在 `loom.memory_versions` 中。
+
+
+
+## 标签、实体与文件
+
+- `tags` 是自由标签(`case:1234`、`kind:evidence`)。搜索可以按标签过滤(`tags`)、用标签加权(`tags_soft`),或让带有这些标签的结果下沉(`demote_tags`)。命名空间的 `tag_registry` 可以为标签附加保留、去重和冲突策略。标签保持写入时的大小写:`memory.list` 和 `knowledge.list` 匹配标签时不区分大小写,其他所有标签过滤(包括 `memory.search` 和 `memory.apply`)都按原样精确匹配。
+- `entities` 是值中提到的命名事物,以搜索读取时使用的规范形式存储(小写;去掉冠词、所有格和标点;中心名词用单数),因此 `Billing Services` 和 `billing service` 是同一个实体。写入方可以传入实体;否则由 `entity_extractor` worker 填充。实体用于实体加权和[实体图](https://github.com/ClickHouse/loom/blob/main/docs/features/entity-graph.md)。
+- `files` 是该记忆所涉及的仓库路径;`memory.for_file` 会在编辑这些文件之前提供相关记忆。
+
+`memory.for_file` 每条记忆渲染一行。决策(decision)或约束(constraint)会完整输出,上限见下文,并且不计入请求的 `token_budget`(默认 300 个 token);其他行受该预算限制,并被截断为 220 个字符的一行。放不下的行会被整行省略,而其后的行仍有机会输出;末尾的 `- … more` 行同样计入预算,说明有多少行被省略以及如何列出它们。标题和移除页脚始终会输出,只要有行被省略,`… more` 行也会输出,因此小于这些内容的预算可能被超出。
+
+决策和约束共用一个上限 `memory_for_file_whole_tokens`(1,500 个 token,约 6,000 个字符),因此受数十条决策和约束管辖的文件不会撑爆提示。它们按块中的顺序输出;会超过上限的一条被省略,其后仍能放下的则照常输出。末尾一行统计被省略的数量,并列出前五个键,每个键可用 `memory.get` 读取(团队行则在其所指的命名空间中读取),或用 `loom_search` 找到。若某行连同取代它的较新行一起被省略,则计入 `… more` 行,绝不会作为需要读取的行被点名。默认值使整个块保持在 coding-agent 宿主从钩子传给模型的 10,000 个字符以内,无需任何改动。
+
+每一行:
+
+- 来自额外命名空间(仓库的代码命名空间)的记忆,标题为 `Team rule (by , )`;若是决策(`memory_type` 为 `decision` 或带有标签 `decision`),则为 `Decision (by , )`。
+- 一行把它的 `constraint`、`gotcha` 和 `decision` 类别列在同一对方括号中(`[constraint, decision]`;标题为 `Decision` 的行会省略 `decision`)。
+- `(pinned)` 标记已固定的行。固定是该行自身的标志:代码命名空间的成员可以对自己在那里写入的行设置它,因此团队行上的 `(pinned)` 只表示有人冻结了它,并不表示是维护者所为。
+- 没有人固定的决策,例如由 `loom decisions extract` 写入的决策,不带固定标记:按原样提供。
+- `(outcome: failed)` 标记任何已记录结果为失败的决策,无论是否固定。
+- 带有 `source-changed` 标签的决策(其来源文档不再这样表述;见[提取决策](https://github.com/ClickHouse/loom/blob/main/docs/features/tasks-and-decisions.md#extract-decisions-from-a-document))显示为 `(source changed)`,无论是否固定。
+- 备注会说明其关联的代码何时发生了变更或已被移除。
+- 字符串值按文本输出,而不是按其存储的 JSON 形式输出;决策或约束之外的行,如果被读取或该行截断,则以 `…` 结尾;被截断的对象或列表按存储形式输出。
+- 带来源的决策会在其值之后完整附上 ` — source: `,因此 `knowledge:` 引用会保留其 `#section`,并可通过 `knowledge.get` 解析。
+- 冲突检查将较新的行与其同类型的较旧行关联后,较新行会置于较旧行之上,团队行会说明它取代了哪一行(较旧行带有标签 `decision` 时为 `supersedes decision`)。冲突检查关联的两条带类型的决策各自保持其在块中的位置,不加此类说明,因为每个决策键本身就是独立的决策。当预算或上限使任何命名空间中取代其他行的某一行被省略时,它所取代的每一行也会一并省略,因此较旧的行绝不会被当作当前有效的行。
+
+
+
+## 与代码关联的记忆
+
+这能为编码 agent 带来什么,以及从哪里开始:
+[与代码关联的记忆](../use-cases/memory-linked-to-code.md)。
+
+关于代码的记忆会与它所提到的定义和文件建立关联,并且这些关联会随代码一起变化。`memory_code_links` worker 会把每条带有 `repo:` 标签的记忆(编码插件会给各自的会话打上该标签),或写在某个仓库代码命名空间中的记忆,与该仓库的 trunk 建立关联:
+
+- 每个带反引号的名称、`A::b` 和 `a.b()` 调用,只要恰好解析到一个定义;记忆的 `files` 用于在同名定义之间做选择,而被定义多次的名称不会被关联;
+- 正文中单独出现的 camelCase 或 snake_case 单词,只关联到记忆的 `files` 中的定义;
+- 记忆提到的、且不包含上述任何定义的每个文件。
+
+trunk 中尚未定义的限定名称会等待 `memory_code_links_pending_days`(14),因此关于未合并代码的记忆会在代码合并后建立关联。
+
+关联会记录定义的指纹:它的所有重载以及选择这些重载的条件,均按 token 计算,因此空白、注释(Go 的 `//go:` 指令和 Python 的 `# type:` 注释除外)以及格式化工具所做的大部分改动(行尾逗号和其他可选分隔符、JavaScript 的 `;`、引号风格及其所需的转义、数字字面量的大小写、Python 文档字符串的缩进、Python、JavaScript 和 TypeScript 中的括号)都不会改变指纹。合并相邻的字符串字面量以及任何其他编辑则会改变指纹。
+文件中定义了什么,是从仓库裸 git 镜像中已索引的 head 处读取该文件得到的。对每个已索引的提交,worker 都会跟踪该提交中的重命名和编辑:
+
+| 关联状态 | 条件 |
+| ------------ | ------------------------------------------------------------------------------------------------------------------ |
+| `fresh` | 定义仍在原处,文本与撰写记忆时一致。 |
+| `moved` | 它所在的文件被移动,或仅被重命名而无其他改动,或被移到了另一个文件。 |
+| `changed` | 它的文本在记忆撰写之后发生了变化(`changed_since` 给出对应的提交),无论是否重命名。 |
+| `unresolved` | 它的名称已不存在,原处可能有一个新定义就是它,但无法确定。会照常提供,并附带复查信号。 |
+| `missing` | 代码已消失:没有新的内容取而代之。关联会保留其位置,因此回滚后可以再次找到它。 |
+
+
+
+控制台中的记忆详情会列出这些关联及其状态
+([视频片段](https://github.com/ClickHouse/loom/blob/main/docs/assets/screenshots/clip-memory-linked-code.webm))。
+
+关联会跟随其定义经历文件移动、重命名(伴随编辑时,只要新名称与旧名称相关),以及其所在类在文件内的重命名。位于另一个类或命名空间中的同名定义绝不会继承关联,而 `missing` 关联只有在其自身的名称重新出现时才会恢复。若某个名称已从其文件中消失,会在自上次检查以来变化的文件中查找它,这些文件取自镜像中保存的状态,与索引并列;因此,如果某次提交没有被索引完整接收(超过 `code_ingest_max_files_per_commit`),被该提交移动的定义会在重新检查关联时被跟踪到。当提到它的这类文件达到 `memory_code_links_mirror_naming_files` 个或更多,或在条目前缀下变化的文件超过 `memory_code_links_mirror_changed_files` 个,或无法读取 diff,或路径数量超过 git 一条命令所能接受或在其时限内所能搜索的范围时,镜像不会补充任何内容,由索引来决定。当 git 无法运行搜索,或找到的定义无法计算指纹时,索引中的同名定义无法确定的有效关联会变为 `unresolved`。ingest 不会索引的文件(位于条目的 `path_prefixes` 之外、被其拒绝列表拒绝、超过字节上限、二进制文件)不会增加定义;而生成的文件(ingest 会将其声明为生成文件,但不会搜索其文本)则会增加。解析失败的文件会保持其关联不变,直到它能够被解析。当指纹规则变化时,每个关联都会基于其哈希当初所取自的提交重新计算哈希。当其旧文本已不在 git 中时,与旧文本匹配的关联会采用下次检查发现的文本,而已变化的关联仍为 `changed`;旧文本已无法解析的关联会保留其最后的状态,worker 会对此作出报告。
+
+Loom 从不改写记忆。命名空间的 `code_change_policy`(`namespace.register`)决定读取时如何处理变更:
+
+| 策略 | 被移除的代码 | 被修改的代码 |
+| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `retire_removed`(默认) | 当一条记忆的所有关联都是 `missing` 时(待定或 `unresolved` 的关联不计入),搜索(以及 `memory.ask`、`context.pack`)会在挑选结果之前将其排除;`memory.get` 仍会显示它。代码恢复后它也随之恢复。 | 标记。 |
+| `flag` | 标记。 | 标记。 |
+| `revise` | 与 `retire_removed` 相同。 | 由 LLM 对照新旧代码重新检查该论断:仍成立的会被重新锚定,被推翻的会得到一个修正后的论断,作为该关联的 `suggestion`。 |
+
+在每种策略下,当一条仍被搜索提供的记忆,其最差的关联为 `changed`、`unresolved` 或 `missing` 时,它的排名会降低:它会移到按分数排名的后续 `memory_search_code_changed_places`(3)行之下(同样在下移或已经下移的行不计入),但绝不会被移出结果,也不会排到仅作为填充提供的行之后(低于相似度下限,或因低于弃答阈值而被标记),这发生在置信度与弃答检查按相关性顺序读取这些行之后;`score_components.code_changed_places` 说明它在其所属搜索的各行中下移了多远(`loom_search` 会按相似度,在其搜索未降级的行中安排其合并后的仓库决策)。以下情形绝不会被下移:
+
+- 由人持有的记忆;
+- 仅有的此类关联指向调用方无权读取的代码,或指向没有任何机制使其保持最新的关联(`memory_code_links_enabled` 关闭)的记忆;
+- 由标识符匹配或 `anchor_first`、`recent_first` 层级安排位置的行,下移也不会把它们算作一个位置;
+- 搜索针对答案为日期顺序的查询所提供的每一行(`loom_search` 按相似度安排的合并后仓库决策仍会下移);
+- 后续页(`page=`)的行,按其暂存的顺序提供;
+- 分块、记录或摘要命中,它们不带 `code_state`。
+
+当提问中带有时间词(`when`、`after`、`since`、`latest` 等)时,阅读器块(`render="reader"`,即 `loom_search` 的块)会按日期列出其行,因此下移在其中不会体现;`results` 则保留下移。
+
+当 `memory_ask_recency_weight` 大于 0(默认 0.2)时,`memory.ask` 会按相似度和时效性对搜索的行重新排序,其标识符查找会安排各自的行;没有查询的 `context.pack` 启动读取不进行搜索。下移在以上这些情形中都不会体现。
+
+`revise` 对每次编辑只判断一次已变化的关联,并受每轮预算(`memory_code_links_revise_per_pass`)的限制。敏感度标为 `high` 的记忆绝不会发送给模型。由人固定、锁定(直到锁到期)或验证过的记忆,以及提到的代码多于关联上限的记忆,只会被标记。为记忆的较早取值(其文本、文件、仓库或用户)所建立的关联,在重新关联之前会被所有读取忽略。
+
+关联是针对 trunk 保存的。在其他分支上,lesson 会将该分支自身的定义(取关联最近 16 个名称中的任意一个)与撰写记忆时的文本进行比较:仍保留旧文本的发布分支,在 trunk 已修改之后仍读作 `fresh`,而拥有 trunk 已移除的代码的分支仍会得到它的 lesson。在无法读取分支文件的情况下(设置了 `LOOM_GIT_HISTORY=none` 的主机没有 git 镜像),lesson 沿用 trunk 的最后状态。
+
+关联会在代码所在之处被读取:
+
+- `code.symbol` 将关联的记忆作为 `lessons` 附上,每条都带有其 `code_state`。它们来自仓库的团队命名空间以及调用中指定的 `lesson_namespaces`(通过 MCP 调用且未指定时,取调用方的记忆主目录),绝不会来自调用方可读的所有命名空间。
+- `code.search`、`code.callers`、`code.callees`、`code.impact`、`code.outline` 以及任务的 `code.context_pack` 会为答案中靠前的文件(`code_result_lessons_paths`)附上 `lessons`:来自相同的命名空间,去除任何其他仓库的代码命名空间,包含与每个文件中的代码关联的记忆,或以其路径或路径尾部(裸文件名,`search/handler.py`;绝对路径会被认为指向以它结尾的根目录之下的某个文件)提到该文件的记忆,每条都带有其 `code_state`,总量在 `code_result_lessons_tokens` 之内。每一行带有 `path`、`memory_key`、`namespace`、`excerpt`、`code_state`、`changed_since`(使其代码进入已变化、unresolved 或 missing 状态的提交,已知时提供),以及在其取代较旧行时的 `supersedes_key`;被答案所读取的另一行所取代的行不会提供。`lessons_left_out` 统计被上限、截断或该规则排除的行数。决策或约束要么完整提供,要么被排除。该读取在答案之后运行,从不进入搜索 memo,并且在 `include_lessons: false`、`code_result_lessons` 关闭,或令牌被限定在其自身用户或会话时跳过。
+- `memory.for_file` 会提供与该文件中的代码关联的记忆,以及其 `files` 提到该文件的记忆。代码发生变化、再也找不到或已消失的行会如此说明,并给出它首次被读作该状态的已索引提交;`context.pack` 的决策行带有同样的备注,其记忆行则带有 `code_state=@` 标签。
+- `memory.get` 以 `code` 的形式返回关联(包含任何 `suggestion`);`memory.search` 中读取自记忆自身行的命中,会以 `code_state` 带上其最差的关联(分块、记录或摘要命中不带此项,也绝不会被排除);`memory.ask` 会注明其代码已移动、变化或消失的记忆。
+- `namespace.validate` 会列出调用方有权读取的仓库中,代码已变化、再也找不到或已消失的记忆。
+
+
+
+## 时间
+
+| 列 | 时间轴 | 含义 |
+| ----------------- | ------ | --------------------------------------------------------------------------------------- |
+| `valid_at` | 现实 | 事实成立的时间,由写入方给出。`NULL` 表示未知。 |
+| `valid_to` | 现实 | 事实不再成立的时间。读取时会丢弃已超过其 `valid_to` 的行。 |
+| `temporal_anchor` | 现实 | 事实所涉及的日期(事件日期),由提取过程设置。 |
+| `created_at` | 记录 | Loom 写入该行的时间。 |
+| `invalid_at` | 记录 | Loom 淘汰该行的时间(被取代)。 |
+| `tombstoned_at` | 记录 | 写入方删除该行的时间。 |
+| `expires_at` | 记录 | 该行退出服务集合的时间,前提是其写入方或命名空间所有者设置了过期时间。 |
+
+`as_of` 读取会回放其中一条时间轴。`as_of_basis="valid_time"`(默认值)查询的是在时间 T 什么为真:即最佳现实日期(`valid_at`,否则 `temporal_anchor`,再否则 `created_at`)不晚于 T 的行。`as_of_basis="knowledge_time"` 查询的是到时间 T 为止 Loom 已经获知了什么:即在 T 之前写入,且到 T 时尚未被淘汰、删除或失效的行。
+
+在 `newest_wins` 下,模板化替换只有在对端行的 `valid_at` 不晚于新行的对应时间时才会淘汰对端行,因此回填旧事实不会淘汰当前事实。这是有效时间加淘汰标记,而不是双时态模型:决定两行中哪一行为当前行的是取代关系,而不是按日期排除。完整的区间模型需要每个写入方说明各个事实何时结束,而 agent 通常并不知道这一点。
+
+
+
+## 版本与历史
+
+每一次变更(值编辑、墓碑标记、恢复、锁定、状态切换)都会写入一行新记录,其纳秒级 `version` 更高,其余各列沿用原值。合并会丢弃旧版本,因此 `loom.memory` 保存的是当前状态,而不是历史。
+
+历史记录保存在 `loom.memory_versions` 中,这是一个只追加的镜像表,由物化视图在每次插入时填充。`memory.history` 读取某个键的所有版本;`namespace.rollback` 将命名空间中的每个最新版本恢复到某个时间点的版本;`memory.redact` 清除某个历史值,同时保留其审计条目。每个版本上的 `content_sha256` 就是 `if_match_sha256` 所比较的值,也是证明(attestation)所绑定的对象。
+
+
+
+## 来源追溯
+
+服务器会在每次写入时为两个列盖章,且从不从请求体中读取它们:
+
+- `actor`:`human:` 或 `process:`(服务账号),取自令牌。
+- `source_class`:Loom 如何获得这些内容,由操作和令牌决定。
+
+| `source_class` | 含义 |
+| -------------- | ------------------------------------------------------- |
+| `asserted` | 调用方直接给出(`memory.set`)。 |
+| `extracted` | 提取流水线从对话记录中推断得出。 |
+| `observed` | Loom 根据所见的活动记录得到。 |
+| `derived` | 由其他记忆计算得出(整合输出、会话摘要)。 |
+| `imported` | 由导入器从其他系统加载。 |
+| `external` | 写入方声明其为外部内容:工具结果、网页、文档。 |
+
+请求只能声明降级(`derived`、`external` 或 `imported`);其他任何值都会返回 422。agent 从其环境中复制的文本正是攻击者可以控制的内容,因此 `memory.ask` 会将未经证明的 `external` 行排除在综合结果之外(`LOOM_MEMORY_ASK_EXCLUDE_UNVERIFIED_EXTERNAL`,默认开启),而 `LOOM_MEMORY_SEARCH_TRUST_WEIGHT` 可以在排序中提升 asserted 行和已证明行的权重。
+
+- **谱系。** 整合会写入 `loom.memory_belief_sources` 行;会话摘要会在 `session_summaries.derived_from` 中列出它所概括的键。`memory.provenance` 说明一行数据的来源,`memory.evidence` 返回提取出的事实所取自的对话轮次,`memory.lineage` 则追溯共享记忆是如何被提升的。
+- **证明。** `memory.verify` 记录是谁为内容担保,并与其哈希绑定。读取时会报告 `verification`:内容未变时为 `human` 或 `process`,内容变更后为 `stale`,从未证明过则为 `none`。编辑会保留证明并读作 `stale`,它绝不会把信任转移到新内容上。
+
+
+
+## 内容该放在哪里
+
+| 内容 | 层面 | 为什么不放进记忆 |
+| -------------------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------- |
+| 下周仍然成立、且其他会话需要的事实 | **持久记忆**,`memory.set` | 它本身就是记忆。 |
+| 用户希望被记住的一段对话记录 | `memory.set_from_messages`(提取) | 一整行大内容只能作为整体被检索到;提取会为每个键写入一条简短的事实。 |
+| 当前计划、租约、游标、“我做到哪了” | **工作记忆**,`working_memory.*` | 协调状态每一步都会变化;对其排序会污染召回结果。 |
+| 可能需要重新读取的大型工具结果 | `context.offload` / `context.fetch` | 它是按键获取的数据块,而不是需要排序的论断。 |
+| 某一条工作线的可恢复状态 | **会话简报**,`session.brief_*` | 简报由用户选择恢复,绝不会被排入其他任务的答案中。 |
+| 文档、规范或运维手册;任何超过几 KB 的内容 | **知识库**,`knowledge.add` / `knowledge.upsert` | 文档按标题分块;记忆则是根据最多 1,200 个字符的摘录生成嵌入。 |
+| 聊天轮次日志 | **对话**,`conversation.*` | 轮次是证据,而非信念;`memory.recall` 会读取某次提取所用到的轮次。 |
+| 具有身份标识和精确字段的数据(PR、工单) | **记录**,`memory.record.*` | 记录按字段逐一合并,并支持精确过滤。 |
+| 始终加载的人设或偏好 | **配置档案**,`profile.*` | 每次都按标签获取;将其与问题一起排序会白白浪费名额。 |
+
+对于文档:把文档存入知识库,再以一个可读的键写入一条简短的记忆,说明它是什么并指向该文档。`context.pack` 会把工作记忆加载在持久部分之前,因此 agent 会先看到自己的状态。
+
+
+
+## 保留策略
+
+Loom 只删除写入方要求删除的内容。任何记忆表都没有默认 TTL,也没有按时间清理行的扫描任务。一行记忆会在以下情况下不再出现在服务集合中:写入方删除或取代它,写入方为它设置了过期时间(`ttl_seconds`、`valid_to`),或者命名空间所有者或运维人员配置了保留窗口。`memory.restore` 可以在 14 天内恢复一条墓碑记录。[保留与擦除](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/retention-and-erasure.md)介绍了相关设置和擦除 saga。
+
+
+
+## 一个事实随时间的变化
+
+3 月,用户说“我住在 Delhi”;6 月,又说“我搬到了 Berlin”。
+
+- **6 月的写入。** 提取过程根据主体和属性生成键,因此两条陈述落在同一个键上。6 月的行不会覆盖 3 月的行:Delhi 版本仍保留在 `loom.memory_versions` 中,可通过 `memory.history` 读取。
+- **归错键的事实。** 如果 Berlin 落在另一个键下,近邻搜索会发现 Delhi 这一行相近但内容不同,并把两者都标记为 `conflicted`,通过 `conflict_with` 相互关联。之后如何处理由命名空间策略决定(参见[一次写入如何被判定](#how-a-write-is-judged))。
+- **“4 月时他们住在哪里?”** 使用 `as_of` 读取即可回答,可以按事实成立的时间查询,也可以按 Loom 在该日期所知的内容查询([时间](#time))。
+- **“这是谁说的?”** `actor` 和 `source_class` 记录写入者以及该事实的来源方式;`memory.evidence` 返回提取出该事实的对话轮次。
+- **错误的导入。** `namespace.rollback` 会把命名空间中的每个头版本恢复到某个时间点的版本,除非另行指定,否则以试运行方式执行。
+
+
+
+## 示例
+
+写入一条事实,在写入变更之前先探测,然后针对你读取到的哈希值进行更新:
+
+```python
+import asyncio
+import os
+from datetime import datetime, timezone
+
+from loom import Datapack
+
+
+async def main() -> None:
+ dp = Datapack(
+ org="acme",
+ namespace="eng-tooling",
+ base_url=os.environ["LOOM_BASE_URL"],
+ api_key=os.environ["LOOM_API_KEY"],
+ )
+ agent = dp.agent("release-bot")
+ key = "project/billing/deploy-window"
+
+ out = await agent.memory.set(
+ memory_key=key,
+ value="Billing deploys only on Tuesdays and Thursdays, never on Fridays.",
+ tags=["kind:constraint", "service:billing"],
+ entities=["billing"],
+ valid_at=datetime.now(timezone.utc),
+ )
+ print(out["conflict_verdict"], out["content_sha256"])
+
+ probe = await agent.memory.set(
+ memory_key="project/billing/deploy-days",
+ value="Billing deploys only on Thursdays.",
+ dry_run=True,
+ )
+ if probe["conflict_verdict"] == "conflict":
+ peer = probe["peers"][0] # closest peer, with its key
+ current = await agent.memory.get(memory_key=peer["memory_key"])
+ await agent.memory.update(
+ memory_key=peer["memory_key"],
+ value="Billing deploys only on Thursdays.",
+ if_match_sha256=current["content_sha256"],
+ )
+
+
+asyncio.run(main())
+```
+
+如果更新返回 409 `PRECONDITION_FAILED`,说明在你读取之后有另一个写入方修改了该行:请重新读取,并重新做出判断。通过 HTTP 写入使用 `POST /v1/memory.set`;通过 MCP 则使用 `loom_memory_set` 工具。
+
+
+
+## 相关内容
+
+- [身份与命名空间](https://github.com/ClickHouse/loom/blob/main/docs/concepts/identities-and-namespaces.md),[检索与排序](https://github.com/ClickHouse/loom/blob/main/docs/concepts/retrieval-and-ranking.md)
+- [写入记忆](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/writing.md),
+ [冲突与拒绝](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/conflicts-and-refusal.md),
+ [历史与来源](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/history-and-provenance.md),
+ [工作记忆与配置档案](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/working-memory-and-profiles.md),
+ [知识](https://github.com/ClickHouse/loom/blob/main/docs/features/knowledge.md)
+- [记忆架构](https://github.com/ClickHouse/loom/blob/main/docs/architecture/memory-architecture.md):代码中的写入路径
+- [操作](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md#memory),[设置](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#memory)
diff --git a/i18n/.pending/zh-CN/docs/features/namespaces-and-sharing.md b/i18n/.pending/zh-CN/docs/features/namespaces-and-sharing.md
new file mode 100644
index 0000000000..d931eb7519
--- /dev/null
+++ b/i18n/.pending/zh-CN/docs/features/namespaces-and-sharing.md
@@ -0,0 +1,271 @@
+
+> 本页由机器从[英文原文](https://github.com/ClickHouse/loom/blob/main/docs/features/namespaces-and-sharing.md)翻译,内容以英文原文为准。
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/features/namespaces-and-sharing.md), which is authoritative.
+
+
+
+# 命名空间与共享
+
+命名空间是组织内部隔离和共享的基本单位。每次读取都限定在 `(org, namespace)` 范围内,每个授权都指向一个命名空间,每项针对命名空间的设置(冲突策略、保留策略、检索默认值、重排序器)都保存在 `loom.namespaces` 中对应的行上。身份模型见[身份与命名空间](../concepts/identities-and-namespaces.md)。
+
+
+
+## 注册命名空间
+
+`namespace.register` 会创建注册表中的行,并使调用方成为该命名空间的管理员。任何主体都可以调用它(viewer);重新注册已有的命名空间需要管理员权限。如果某个名称没有对应的行,但已经存有数据或存在有效授权,则会被拒绝,除非调用方已经是它的管理员([新名称可以占用什么](https://github.com/ClickHouse/loom/blob/main/docs/architecture/security.md#what-a-new-name-may-claim))。当 `LOOM_NAMESPACE_AUTOREGISTER_ENABLED` 开启(默认)时,首次向没有对应行的命名空间写入会自动注册它,以令牌的 subject 作为所有者(如果该名称已被占用,则没有所有者),并设置 `retention_days = 0`。只要没有其他人在该名称上持有有效授权,该所有者就可以完成注册。
+
+重新注册是部分更新:省略的字段保留其已存储的值。`tags` 会被整体替换。对于 `conflict_threshold`、`capture_generation_io` 和 `coverage_sweep`,省略表示保留已存储的选择,显式的 `null` 则恢复为服务器默认值。
+
+| 字段 | 作用 |
+| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `kind` | `memory`、`code`(一个已索引的仓库和分支;只读参考数据)或 `bench`(一个一次性的测试框架命名空间,空闲后由 GC 清除)。在新行上省略时由名称决定:匹配 `LOOM_NAMESPACE_BENCH_PREFIXES` 前缀的为 `bench`,其他均为 `memory`,与首次写入时相同。 |
+| `visibility`、`join_policy`、`requires_approval` | 谁可以发现并加入它:`private`(仅成员)或 `public`(由 `namespace.browse` 列出);`join_policy` 可为 `open`、`approval`、`closed` 或 `inherit`。 |
+| `default_conflict_policy` | `auto_reinforce`(默认)、`manual_review`、`newest_wins` 或 `append_only`,即一次写入如何与已有的同类记忆比较判定。参见[冲突与拒绝](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/conflicts-and-refusal.md)。 |
+| `conflict_threshold` | 相近的写入被视为冲突的余弦值;显式的 `null` 继承 `LOOM_CONFLICT_THRESHOLD`。 |
+| `proposal_policy` | 如何裁定处于试用中的事实;只有所有者设置的 `auto` 才允许 Loom 在评分运行中自行裁定。参见[写入记忆](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/writing.md)。 |
+| `retrieval_defaults` | 未固定参数的 `memory.search` 所使用的设置(`search_mode`、`top_k`、`min_similarity`、`floor_mode`、`recency_pool_weight` 等);`{}` 表示清除。参见[搜索与提问](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/search-and-ask.md)。 |
+| `rerank_endpoint`、`classify_endpoint` | 可选的重排序器(内置名称或 `LOOM_RERANK_ENDPOINTS_JSON` 中的名称,不能是 URL)和分类器 URL(公网地址上的 https,或 `LOOM_MEMORY_CLASSIFY_PRIVATE_HOSTS` 列出的主机;当要求使用网关时,必须是 `LOOM_INFERENCE_GATEWAY_HOSTS` 中的主机;在列出的网关主机上,即使不要求网关,也须是默认端口的 https),以及它们的提示词模板。两者都是失败时放行,但网关拒绝该调用的身份时,写入会失败。 |
+| `retention_days`、`warm_days`、`tag_registry` | 命名空间的保留与分层,以及按类型设置的保留和去重阈值。`0` 表示永久保留。参见[保留与擦除](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/retention-and-erasure.md)。 |
+| `conversation_logging_enabled`、`capture_generation_io` | 是否同意存储对话记录,以及是否同意将提示词和补全文本发送到 Langfuse。两者都需主动开启。 |
+| `consolidation_enabled`、`daily_cost_cap_usd`、`coverage_sweep` | 后台整合、该命名空间的上游支出上限,以及提取覆盖率扫描。 |
+
+```python
+from loom import Agent
+
+async with Agent(org="acme", namespace="eng-tooling", agent="setup") as agent:
+ await agent.namespaces.register(
+ owner_email="platform@acme.example",
+ description="Shared memory for the build tooling agents",
+ visibility="public",
+ default_conflict_policy="newest_wins",
+ retrieval_defaults={"search_mode": "hybrid", "top_k": 8},
+ )
+ # Fields the SDK method does not take go through Agent.call:
+ await agent.call(
+ "namespace.register",
+ owner_email="platform@acme.example",
+ join_policy="approval",
+ daily_cost_cap_usd=5.0,
+ )
+```
+
+`namespace.delete`(管理员)会将该行标记为未激活,并停止接受写入;它不会触及数据。要删除数据,请先执行擦除(`erasure.request(scope_type="namespace")`,参见[保留与擦除](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/retention-and-erasure.md))。使用 `active=true` 调用 `namespace.register` 可重新激活它。
+
+
+
+## 成员与授权
+
+授权(grant)赋予一个主体(个人的登录名、SSO 或已关联账号的已验证邮箱,或服务账号 `sa:`)在某个命名空间上的角色:`viewer` 可读,`writer` 可写,`admin` 可管理授权和设置。令牌携带组织以及可访问的命名空间,具体角色由授权表决定。
+
+| 操作 | 角色 | 作用 |
+| -------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `grants.create` | admin | 授予角色。若创建的角色低于该主体当前的角色,则返回 409 `GRANT_WOULD_DOWNGRADE` 并拒绝,除非设置 `replace=true`。 |
+| `grants.list` | viewer | 列出谁拥有访问权限、角色是什么,以及 `pending_role`。 |
+| `grants.revoke` | admin | 移除授权。 |
+| `grants.approve` | admin | 批准或拒绝待处理的请求,可以选择授予不同的角色。 |
+| `grants.pending_for_me` | viewer | 调用者担任管理员的各命名空间中的所有待处理请求,范围为整个组织。 |
+| `namespace.browse` | viewer | 组织中的公开命名空间,不包括 collection(`closed` 的命名空间仅在使用 `include_closed` 时返回)。 |
+| `namespace.join` | viewer | 自行加入公开命名空间。`viewer` 会立即授予;`writer` 或 `admin` 的请求始终处于待处理状态,在管理员批准之前没有任何访问权限。 |
+| `namespace.leave`, `namespace.cancel_request`, `namespace.mark_seen` | viewer | 放弃自己的授权、撤回待处理的请求、确认已收到邀请。 |
+| `namespace.list_mine` | viewer | 调用者所属的命名空间,每个都带有其 `kind`(collection 对应 `collection`)和 `title`。 |
+| `namespace.list` | 组织管理员 | 组织中的所有命名空间。 |
+
+签发令牌、服务账号、读取范围和受限命名空间的内容,请参阅[令牌与授权指南](https://github.com/ClickHouse/loom/blob/main/docs/guides/tokens-and-grants.md)。
+
+
+
+## 在 agent 和命名空间之间共享事实
+
+在一个命名空间内,默认情况下每个写入方的行对所有读取方都可见(`agent="*"`)。跨越边界始终是带有溯源信息的复制,而不是共享同一行:
+
+| 操作 | 角色 | 作用 |
+| ---------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `memory.promote` | admin | 将一条私有记忆复制到命名空间的共享层(`loom.shared`),可通过 `memory.search(scope="shared")` 读取。在 `reversible_for_days`(默认 7)天内可撤销。 |
+| `memory.demote` | admin | 将共享副本及其 embedding 标记为已删除(tombstone);`was_reversible` 表示该操作是否发生在可撤销期限内。 |
+| `memory.copy_to` | 目标上的 writer | 自助复制:按 key 将你可读取的记忆复制到你可写入的命名空间。非破坏性;目标由其自身的 embedder 重新生成 embedding。 |
+| `memory.cross_promote` | 两端的 admin | 面向运维人员的形式,按记忆 id 指定,并在目标上带有 `cross_promoted_from_*` 溯源信息。 |
+
+`memory.copy_to` 按 key 读取源行,并将调用方记录为该副本的操作者,因此需要已登录的调用方:即设置 `LOOM_AUTH_REQUIRED=true`,并使用既能读取源又能写入目标的令牌。默认的单用户部署会拒绝该操作。Python SDK 通过 `agent.client` 调用它:
+
+```python
+from loom import Agent
+from loom.errors import NotFound
+
+async with Agent(org="acme", namespace="support", agent="triage-bot") as agent:
+ try:
+ result = await agent.client.memory.copy_to(
+ from_org="acme",
+ from_namespace="support",
+ memory_key="customer/4812/plan",
+ to_namespace="billing",
+ rationale="Billing checks invoices against this plan.",
+ )
+ except NotFound:
+ ... # no live row under that key in the source namespace
+ else:
+ print(result["copied"], result["target_key"]) # True customer/4812/plan
+```
+
+除非 `target_key` 指定了其他 key,否则副本沿用源 key;除非你指定了 agent,否则它在目标中归命名空间所有(`target_agent="-"`)。`from_agent="*"`(默认值)会复制该 key 下最近写入的一行。rationale 不会作为文本存储:审计行只保留它的 SHA-256 和长度。
+
+跨命名空间的复制不是原子的:复制中途失败时,源保持不变,而目标中没有该行。learnings 队列(`learnings.*`)会提出值得提升的行,详见[过程与 learnings](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/procedures-and-learnings.md)。
+
+
+
+## 读取命名空间的健康状况
+
+| 操作 | 回答的问题 |
+| --- | --- |
+| [`namespace.inventory`](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/namespace.md#namespaceinventory) | 命名空间中有什么、出现了哪些主体:记忆、记录、文档、运行和集成的实时数量与最新写入;成员数;在记忆行上观察到的 agent、作者和主体;响应请求的进程是否由真实的模型和 embedder 提供服务。 |
+| `namespace.summary` | 按记忆类型统计的数量、热门实体、最近的写入和召回、不同的 agent、最近活动。 |
+| `namespace.validate` | 完整性报告:卡住的冲突、低置信度的行、仍在等待 embedding 的行。在一批写入之后,或召回结果看起来不对时运行它。 |
+| `namespace.audit` | 命名空间被用作记忆还是对象存储:按精确键读取与搜索的对比、哈希形态的键、双重编码或过大的值、被存为记忆的租约、版本频繁变动。它还会指出部署自身的状态(类型 `system_state`:缺少遥测、索引积压);当账本没有记录窗口内写入背后的任何调用时,它会跳过账本检查,而不是将其报告为正常。每个发现都附带修复建议。 |
+| `memory.inspect` | 单个用户、agent 或会话:它自己的行(与命名空间中的其余部分分开)、窗口内的调用,以及生成其记忆的指南、类别和提取策略([见下文](#inspecting-one-user-agent-or-session))。 |
+| `namespace.tune` | 对生成命名空间记忆的提取规则、类别和指南,以及对其文档的分块和提取器设置的修改草案,每条都附有证据和用于应用它的写入操作;不会自动应用任何内容([见下文](#drafting-changes-to-how-memories-are-made))。 |
+| `namespace.taxonomy` | 实时词汇表:热门标签、实体、记忆类型和社区。 |
+| `agents.connected` | 窗口内(默认 24 小时)活跃的 agent:最后和首次出现时间、操作数、涉及的命名空间以及每个 agent 的成本。回答“我的客户端是否真的在与 Loom 通信?” |
+
+`namespace.inventory` 将各类对象分开统计。`members` 统计授权持有者:即持有有效授权的人,不包括待处理的请求、组、agent 或服务账号(在命名空间上以及在集合的每个上级上调用 `grants.list`,会列出他们的授权)。声明中直接指明该命名空间的令牌无需授权即可读取,且不计入其中;集合也会统计其上级的授权持有者,因为父级的授权会覆盖每个子级。在这条层级链上的任何位置,只要存在授予 `everyone`、组或 agent(在其下登录的每个终端用户)的授权,或存在整个组织都可读取的代码命名空间,计数就会是 `complete: false`,因为这些成员没有被列出。`agents`、`authors`(写入某行的 `actor`)和 `subjects`(某行所属的 `user_id`,不含未设置的 `-`)是在实时记忆行上观察到的身份,而不是一份目录。个人集合的所有者不持有授权,因此不计入成员(`total` 为 null)。如果某个部分失败,或调用方无权读取,会以 `complete: false` 并附带原因说明:集成数量仅对命名空间管理员可见;在绑定到单个用户的读取范围下(`read_scope=own_user` 或 `own_session`,或固定到某个用户的令牌),记忆数、运行数以及观察到的 agent、作者和主体都只属于该用户,文档和成员按整个命名空间统计,与 `knowledge.*` 和 `grants.list` 的读取结果一致,而记录(每个键一条,无论最后由谁写入)和集成则不统计。
+
+每个 `namespace.audit` 和 `namespace.validate` 的发现都带有相同的证据字段,因此 CLI、控制台和 MCP 客户端读取的是同一种结构:
+
+| 字段 | 含义 |
+| --- | --- |
+| `kind` | 当存储的值违反已声明的不变量或证明时为 `contract_violation`;当某种模式通常会损害召回或存储,但合理的设计也可能命中它时为 `usage_heuristic`。启发式命中只是警告,不是误用的证明。当发现涉及的是部署而不是写入方时为 `system_state`:索引积压(`index_backlog`)或账本未记录的写入(`telemetry_unavailable`,此时会跳过账本检查,而不是将其报告为正常)。这些是 `namespace.audit` 的发现;`namespace.validate` 的 `unembedded` 检查属于 `contract_violation`,会统计所有超过宽限期仍没有向量的行,包括被暂扣的模型调用。 |
+| `rule_version`、`source_op` | 规则的版本(当其谓词或内置阈值改变时提高,因此两份报告只有在同一版本下才可比较;规则读取的设置或请求输入,例如 `confidence_floor` 或值大小建议,不计入版本)以及计算它的操作。 |
+| `window_seconds` | 使用类规则统计所覆盖的账本窗口;对读取当前状态的规则为 null。 |
+| `population`、`count` | `share` 的分母(发现所对照的行或调用,其中可能包含规则按设计排除的行),以及匹配的数量。`namespace.validate` 的检查只报告没有分母的计数,并将 `population` 留空;摘要读取被跳过的审计发现也是如此。 |
+| `sample_limit`、`samples_complete` | 样本上限,以及样本是否列出了所有匹配项:当上限截断了样本,或样本无法指明每一个匹配项时为 false。 |
+| `evidence` | 样本所指明的每一行的实时修订版本(见下文)。绝不包含值。 |
+| `exceptions`、`uncertainty` | 规则按设计排除的内容,以及命中为何仍可能是正确的。 |
+
+每个 `evidence` 条目都是样本所指明的某一行的实时修订版本,在检查运行完毕后读取:`memory_key`、`memory_id`、`version`、`content_sha256`(`memory.get` 提供的哈希;对于高敏感度的行、长度超过 `LOOM_NAMESPACE_REPORT_HASH_MAX_BYTES`(64 KiB;[配置](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md))的值,或在报告读取期间发生变化的行,该值为空)、身份列、`memory_type`、`source_class` 和 `updated_at`。样本通过 `memory_id` 指明其行,来自 embedding 表时则通过其身份列指明;在多个身份下持有的同一个键,只会引用匹配的那一个。在检查运行之后被修订的行,会按其较新的修订版本引用;此时它的 `updated_at` 不早于报告的 `computed_at` 或 `checked_at`(精确到整秒)。仅改变行状态的写入可能保持其 `updated_at` 不变,因此这种比较只是提示,而不是证明。不指明单个行的样本(`exact_key_store` 热点键、`version_churn` 键)、不再有效的行(孤立向量)没有条目;在 Postgres authority 下,授权方在所读取版本上不再提供的行也没有条目([存储 authority](../architecture/storage-authority.md))。
+
+报告的 `coverage` 列出已运行的规则(`rules_run`)和无法运行的规则(`rules_skipped`,同时附带原因列在 `skipped` 中)。两者都会指明所读取的证据(`evidence`),对于 `namespace.audit`,还包括其摘要读取(大多数发现都以此为衡量基准),以及在 Postgres authority 下的 `projection`,即等待 ClickHouse 发布该命名空间已提交的内容([存储 authority](../architecture/storage-authority.md))。只要其中任何一项被跳过,`complete` 就为 false。
+
+`loom audit-namespace` 从 shell 运行 `namespace.audit`;[优化命名空间指南](https://github.com/ClickHouse/loom/blob/main/docs/guides/optimize-namespace.md)会把它的发现转化为经过审阅的改造计划。词汇通过 `namespace.register_category`、`namespace.list_categories`、`namespace.search_categories`(类别)以及 `namespace.register_ontology`、`namespace.list_ontology`(用于[实体图](https://github.com/ClickHouse/loom/blob/main/docs/features/entity-graph.md)的实体类型和关系动词)进行注册。
+
+快照和时间点回滚(`namespace.snapshot`、`namespace.restore`、`namespace.rollback`)在[历史与溯源](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/history-and-provenance.md)中介绍。
+
+
+
+## 检查某个用户、agent 或会话
+
+`memory.inspect`(viewer)接受 `subject`(`user`、`agent` 或 `session`)和 `id`,即要查看的 `user_id`、agent 名称或 `session_id`;未设置的 `-` 和 `*` 不指代任何对象,会被拒绝。它不会修改所读取的任何内容,也不计入召回。与 `memory.list` 一样,它会为所列出的行写入一条暴露账本行。
+
+- **`own`**:其身份指向该 subject 的有效行。对于 agent,是以其名称写入的行;该名称说明某一行来自哪个 agent,并不是读取边界。对于用户,是归在该 `user_id` 下的行,无论由谁写入:这也是绑定到该用户的令牌(`read_scope: own_user`)所能读取的内容。对于会话,是任何用户在该 `session_id` 中写入的行;绑定到某一用户和该会话的令牌(`read_scope: own_session`)读取的是该用户的那部分。
+- **`others`**:该命名空间中所有其他的有效行。成员同样可以读取这些行,因此仅凭 `own` 并不能代表某个用户、agent 或会话能读取的全部内容。两个视图都不统计已提升的行(`memory.promote`),搜索也会把这些行提供给每个 agent。
+- 每个视图的 `definition` 用通俗的语言说明它包含哪些行;其 `refs` 列出它所指的确切列,以及定义中提到的读取范围和操作。
+- 每个视图按类型、状态和来源类别统计其行数,列出热门标签以及其行所归入的已注册类别,并列出最新的行(`sample_limit`,默认 10),包含 `memory_id`、`version`、`memory.get` 提供的 `content_sha256`、`actor`、`sensitivity`、历史中保留的版本数(包括实体标注器重新发出的版本,`memory.history` 不包含这些版本)以及 200 个字符的摘录。高敏感度的行既没有摘录也没有哈希;值大于 `namespace_report_hash_max_bytes`(0 表示不引用任何哈希)的行,以及在列出与引用读取之间被修订的行,没有哈希。当列出的行数少于视图中的行数、无法读取视图的统计数据,或者在 Postgres 作为权威存储时无法确认 ClickHouse 已包含命名空间所提交的内容(等待超时或 Postgres 未响应,`skipped` 会指明 `projection`)时,`complete` 为 false。
+- **`activity`**:账本在 `window_seconds`(默认 7 天)内按操作归入该 subject 的调用,包括尝试次数和成功次数,不含 worker 行,也不含控制台和助手发起的调用。账本根据调用参数中指明的 `agent`、`user_id` 和 `session_id`,或受限令牌所绑定的用户和会话来归类调用,因此任何人发出的、指明了该 subject 的调用都会被计入,而不指明任何 subject 的 `memory.inspect` 调用则不会。调用只说明某个工具运行过,不说明其结果已到达模型。当账本保留的天数少于该时间窗口时,`gap` 会说明这一点(取命名空间自己的 `retention_days`,否则取部署的设置)。
+- **`settings`**:指南的修订版本和摘要、已注册类别的数量,以及仅对组织管理员显示的操作员提取策略(缺失时由 `extraction_policy_unavailable` 说明原因)。提取指令随每个请求发送;没有任何用户、agent 或会话设置会存储它们,`extraction_instructions_refs` 指明承载这些指令的操作和参数。
+- 无法读取的部分会列在 `skipped` 中;被跳过的部分并不等于空。权限被收窄到命名空间以下的令牌(`read_scope`)不能调用它。
+
+
+
+## 起草对记忆生成方式的修改
+
+`namespace.tune`(viewer)会读取命名空间的审计、其标签和键布局、已注册的类别、其指南,对于组织管理员还会读取当前生效的运营方提取策略,并起草对创建其记忆的设置的修改。它读取整个命名空间,而不是单个用户、agent 或会话(`memory.inspect` 可查看单个),不应用任何修改,也不调用模型。每条提议都包含:
+
+- **`target`**:它所修改的设置。可以是 `extraction_instructions.request`(`memory.set_from_messages` 请求所发送的指令;没有任何用户、agent 或会话设置存储这些指令)、`namespace.category`、`namespace.guide`,对于文档则是 `settings.knowledge_chunking` 和 `settings.document_extractors_json`(见[下文](#document-drafts))。提取规则绝不会被起草为运营方提取策略:生效的策略会覆盖所有其他指令,并关闭提取的恢复流程,因此在那里写入风格规则会使命名空间损失目前保留的事实。如果当前生效的策略已包含某条规则的完全相同的文本,则不会再次起草该规则。
+- **`current`** 和 **`proposed`**:设置当前的值和将要设置的值;对于指南,还有 `current_revision`。
+- **`evidence`**:它所回应的审计发现(`finding_codes`),有多少行支持它(前 `sample_limit` 行以 `memory_id`、`version` 和 `memory.get` 返回的 `content_sha256` 引用,依次从每个发现中各取一行),以及它必须保持可用的行数(`counter_count`:至少是检查所读取的、且没有被任何检查标记的最小总体的行数,或另一个类别已持有的带标签行数;当该数量无法读取时为 null,对于不改变任何已存储行的指南也为 null)。
+- **`affected_agents`**:该修改所影响的写入方,最多 20 个,并附带 `affected_agents_total`:对于提取指令,是其行由提取写入的 agent;对于类别或指南,是写入过活跃行的每个 agent;当命名空间的写入方无法读取时,`affected_agents_total` 为 null。
+- **`effect`**(`future`)和 **`historical`**:设置只影响其修改之后写入的记忆;对已存储行的重新处理(`memory.move`、`memory.assign_category`)是单独的操作,需要各自的批准。
+- **`apply`**:普通的写入操作、其参数(当参数只是要合并进每个请求的一部分时为 `args_complete: false`)、所需的角色及其保护条件。`namespace.guide_set` 会拒绝已超出 `expected_revision` 的指南;`namespace.register_category` 没有修订检查,因此在应用之前会重新读取类别。
+- **`refs`**:草稿文本中以普通文字提到的每个确切名称,供据此执行操作的调用方使用。设置按其被修改的方式命名:可实时修改时为 `settings.set `,仅由环境设置时为其 `LOOM_` 变量。关于某个设置、丢失的能力、某个发现或错误码的 `skipped` 原因,或指示读者执行操作的原因,会在括号中给出确切名称;`projection:` 行和 `audit.` 行原样保留其来源的文本。
+
+草稿来自固定规则:针对每个写入方一侧的审计发现各有一条提取规则(双重编码的值、JSON 前缀摘录、过大的值、情景性 blob、协调状态、手工构造的索引行)。只有当 `memory.set_from_messages` 的提取向该命名空间写入(行带有其来源 trace),且该发现所引用的行中至少有一行来自它时才会起草,因为这些指令不会影响其他任何内容;如果某个发现所引用的行都不是提取写入的,或审计没有引用该发现的任何活跃行,或提取没有向该命名空间写入任何内容,则不起草任何内容,并在 `skipped` 中说明。其受影响的 agent 是其行由提取写入的 agent,它引用由提取写入的被标记行,而被标记的数量涵盖所有写入方。键的布局属于写入方(提取出的键会被清理),因此不会为它起草规则。其次,对于在至少 `min_rows` 个活跃行上带有、但没有同名类别的每个标签,起草一个类别;对于在至少 `min_rows` 行上列出键前缀和标签(或现有指南遗漏的前缀)的情况,起草一份指南;个人集合(`col-me-…`)不起草,因为它不接受指南。不是普通名称的标签或前缀绝不会被起草,因此存储在行中的文本无法左右目标或参数;`:` 形式的标签(`source:`、`speaker:`、`agent:`)也不会被起草,因为它们表示一行来自哪里,而不是关于什么。审计无法运行的检查会在 `skipped` 中列为 `audit.`。范围被缩小到命名空间以下的令牌(`read_scope`)无法调用它。
+
+
+
+### 文档草稿
+
+切分和提取文档的设置属于整个部署,且只存在于那里:文档草稿的 `scope` 是部署的每个命名空间,其证据来自当前命名空间,其 `apply` 通过 `via` 指明该设置如何修改。
+
+- **分块大小和步长**(`settings.knowledge_chunking`):最多 `namespace_tune_document_sample` 个活跃文档(默认 50,按其 `source_uri` 的哈希挑选)会在进程内按当前的 `knowledge_chunk_size` 和 `knowledge_chunk_stride` 重新切分,每个文档使用其写入路径所用的分块器:文本文档用其文本,已摄取的文档用其存储的产物,直到加载了 8 MiB 的文本和产物为止;超出该上限的文档、超过 2,000,000 个字符的文本或超过 8 MiB 的产物计为 `unread`,`load_cap` 给出总量。不写入任何内容,不调用模型,也不返回文本。`chunking` 报告切分结果:块数、每块的字符数、按大小切分后产生的块多于其结构所需块数的小节(`sections_cut`)、最大的嵌入输入(以 token 计),以及超出嵌入器限制的输入数量(当其提供方没有声明 Loom 会检查的限制时为 null)。当有输入超出限制时会起草一个大小(能容纳的最大的更小值,最低到 200),或者当超过四分之一的抽样小节被切分、涉及至少五个文档且限制已知时也会起草(最小的更大值,最高为当前值的四倍,使四分之三的小节在限制内保持完整);每个候选大小只尝试一次,由近及远,步长与大小保持比例。`preview` 保存在这两个值下对样本的切分。`apply` 是 `settings.set`(`POST /v1/admin/settings.set`,需要平台管理员)并带有 `expected`,`apply_also` 用于设置步长。两条规则都不触发的样本不起草任何内容,并作为证据保留。`knowledge_chunk_size` 为 0 或更小(此时不切分窗口:文本文档是一个块,已摄取的文档每个块对应一个 block)以及 `knowledge_chunk_stride` 为 0 或更小(此时不会对长于该大小的小节或 block 做窗口切分)的情况也一样:两者都不起草大小。
+- **提取器路由**(`settings.document_extractors_json`):如果某个格式的来源的当前任务以 `format_unavailable` 失败,或其已发布的提取不完整,则该格式会被路由到在其能力中声明了它的已配置提取器。来源当前所用的服务按摄取读取的方式,根据其格式和媒体类型确定;草稿会为该格式本身添加一条路由,它优先于媒体类型路由,因此会接管该格式的每个来源。在声明了该格式的服务中(对于不完整的提取,则是那些没有造成不完整提取的服务),路由会指向其来源已经在使用的服务(完整提取的来源,或失败来源的服务现在已声明该格式),否则指向其媒体类型路由所到达的服务,否则指向任意服务;在每一类中,没有造成不完整提取的服务排在前面。路由仍可能移动在另一服务上完整提取的来源,其理由中会点名它们;无法解决不完整提取的路由会在 `skipped` 中说明。草稿通过保存其 URL 的设置来指明服务,而绝不写出 URL(URL 可能带有凭据),因此 `args_complete` 为 false;`via` 为 `environment`,在每个服务器和 worker 重启后生效。没有已配置的提取器声明的格式不起草任何内容,并在 `skipped` 中列出(`extractor.`);失败来源的服务现在已声明该格式的情况也一样,这类来源应重新摄取。
+
+决策提取(`loom decisions extract` 以及来源同步的挖掘)根据固定文本构建其提示,不接受来自请求、命名空间或组织的指令,因此不为它起草任何指令;当命名空间有文档时,`skipped` 会说明这一点。已存储的文档保留其块和提取结果:重新切分或重新提取它们是单独的操作(`historical`)。
+
+
+
+## 命名空间的指南
+
+命名空间的指南是为该命名空间编写的一份 Markdown README:说明命名空间存放什么、键的布局、每个标签的含义,以及应调用哪些 op。agent 在首次写入之前阅读它,并在改变其中某项约定时更新它;人也阅读同一份文本。它只记录关于数据的约定,不记录事实本身,事实仍保存在记忆中,由搜索和擦除覆盖。
+
+| 操作 | 角色 | 作用 |
+| ------------------------- | ------ | ------------------------------------------------------------------------------------------------------ |
+| `namespace.guide_get` | viewer | 返回当前指南(或某个历史 `revision`):正文、一行摘要、修订号、写入者和备注。 |
+| `namespace.guide_set` | writer | 当 `expected_revision` 是当前修订号时写入下一个修订;否则拒绝,并返回当前指南以便合并。 |
+| `namespace.guide_history` | viewer | 返回最新的若干修订,包含摘要、备注、写入者和长度。 |
+
+每次保存都要指明所基于的修订号。若两个 agent 基于同一修订编辑,先保存的生效,后保存的会收到 `conflict: true` 以及当前最新的指南;该 agent 将自己的改动合并到这份文本中,再用返回的修订号重新保存。服务器自己从不合并文本。重试一次已经生效的保存时,会发现自己的文本已是当前版本,不会写入任何内容。保存时省略 `summary` 会保留当前摘要,`content` 为空则清空指南。终端用户的个人集合(`col-me-…`)没有指南。每个修订都会保留,因此带 `revision` 调用 `namespace.guide_get` 即可读取其中任何一个。
+
+指南无需请求就会送达 agent:
+
+- **会话开始时**,`context.pack` 会渲染一个 `namespace_guide` 部分:先是指南的修订号、写入者和摘要,然后是按该部分预算(200 个 token)截断的正文。正文属于召回的数据,与其他写入者的文本一样,经转义后缩进在同一条目之下。
+- **在目录中**,公开命名空间的每个 `namespace.browse` 行都带有 `guide_revision` 和 `guide_summary`,`query` 也会匹配指南的摘要,因此 agent 在众多公开命名空间中查找时,能找到指南描述了所需内容的那一个。对非成员而言,私有行不显示指南,受限行则完全不显示。
+- **`namespace.get`** 会返回 `guide_revision` 和 `guide_summary`。
+
+读取指南需要对其命名空间有读取权限,因为公开行的可见性不会扩大任何读取权限:`namespace.browse` 向组织展示每个公开命名空间的摘要,而完整的指南只供其成员阅读(`namespace.join`)。在控制台中,记忆页面标题处,**Add memory** 旁边有一个 **Guide** 按钮,按钮上会显示指南的修订号和摘要;对于没有指南的命名空间,writer 点击后会直接进入编辑器。首份指南无论从这里还是从组织内的命名空间页面开始,都以一份提纲起步,其中列出新人会问的问题(命名空间存放什么、键、标签、如何使用),且在未修改的情况下无法保存。组织内的命名空间页面会在描述下方显示公开命名空间的指南摘要;对于你所属的命名空间,点击摘要即可打开指南,没有显示摘要时则使用 **Guide** 菜单项。writer 可以在这两处任一位置编辑,并像 agent 一样基于所打开的修订保存。擦除命名空间会删除其指南的所有修订。
+
+
+
+## 导师
+
+`mentor.brief` 返回针对某个 agent 的建议及其依据:该 agent 在一个时间窗口内(默认 7 天)的调用、命名空间提供的各个 plane,以及每条提示和触发它的计数。`context.pack` 在会话开始时最多渲染三条提示,成功的响应最多携带一条(MCP 上为 `hint`,HTTP 上为 `X-Loom-Hint`),上限由 `LOOM_MENTOR_MAX_HINTS_PER_SESSION` 控制。`loom mentor --org … --namespace … --agent …` 会打印完整的 brief。参见 [导师操作](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/mentor.md)。
+
+brief 的 `usage_evidence` 列出该 agent 使用 Loom 的情况,每个层级一项,并注明记录者(`server`:Loom 亲眼所见;`client`:由调用方上报,未经验证)。这些层级在每次生成 brief 时读取,而不是来自缓存的画像,时间窗口为 brief 所报告的窗口。从调用账本读取的层级(`attempt`、`success`、`committed_write`、`returned_hit` 以及 `memory.outcome` 标签)统计的是账本中记录在该 agent 名下的行,即调用请求体中指明的 agent(对于按密钥发起的调用,则是该行的写入者,无论调用者是谁):请求体未指明 agent 的调用(按 id 读取、MCP 的 `memory.update`、Python SDK 默认的 `memory.update`),或者跨 agent 读取并记录在 `*` 下的调用(SDK 中的 `memory.search` 和 `memory.ask`、MCP 的跨 agent 读取、未指明 agent 的 `memory.outcome`),都不会被计入。该层级体系不使用画像中的任何计数,因此即使导师处于关闭状态也能给出结果;不针对特定 agent 的 brief 没有层级体系。
+
+| 层级 | 来源 | 统计内容 |
+| --------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `attempt` | `server` | 发起的调用,无论是否得到应答;不包括控制台或助手发起的调用、brief,以及延迟的 `memory.ask` 留下的裁决 |
+| `success` | `server` | 未返回错误的调用;读取不到内容的读取也计入 |
+| `committed_write` | `server` | 实际存储了一行的 `memory.set` 调用:不包括空操作、试运行或重放 |
+| `indexed_write` | `server` | 在窗口内首次创建的记忆(每个用户、会话和键一条),由任意写入 op 产生,带有当前 embedder 生成的向量,处于可服务状态且未过期 |
+| `returned_hit` | `server` | 未弃答的 `memory.search` 或 `memory.ask`,命中记忆、文档或对话的 `search.query`,以及找到其键的 get |
+| `client_acknowledged` | `client` | agent 上报其依赖过的不同记忆键:`run.complete` 的 `memories_used`,以及按 id 提交、标记为 `used` 或 `positive` 且落在某一行上的 `memory.outcome`;不包括按键提交的标签(记录在该行写入者的 agent 名下)、Python SDK 的 `outcome` 调用(没有 agent)或 `memory.outcome_run` |
+| `task_outcome` | `client` | 被评为 `pass` 或 `fail` 的该 agent 的运行(`run.grade`),以评分者上报为准 |
+
+返回命中并不能说明答案已送达模型,或改变了它的工作。`ledger_from` 是该 agent 在窗口内最早的账本行,`ledger_retention_days` 表示已配置的保留策略会将该命名空间的账本行保留多久(0:直到被删除);窗口长于此值时,从账本读取的层级所覆盖的范围会小于窗口所声明的范围。
+
+[`mentor.guide`](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/mentor.md#mentorguide) 返回如何使用 Loom 的说明,面向模型编写:即 `skills/loom/` 中的 `loom` skill,`part` 可取 `skill`(循环与规则)、`reference`(每个 plane 及其 op)或 `all`。它对所有调用者都相同,因此任何 viewer 令牌都可以读取,包括限定到某个用户的令牌,以及通过 HTTP 访问的终端用户的令牌。
+
+
+
+## 临时命名空间
+
+基准测试和测试工具会写入以 `LOOM_NAMESPACE_BENCH_PREFIXES` 中的前缀命名的命名空间;自动注册会将它们标记为 `kind = bench`。`namespace_gc` 工作进程会清除仍有记忆、但在 `LOOM_NAMESPACE_GC_IDLE_HOURS`(默认 24)小时内没有写入的 bench 命名空间,每批通过一次按列表限定范围的擦除 saga 完成。`loom namespaces-gc --org ` 会列出候选命名空间,`--erase` 则手动清除它们;`loom namespaces-adopt` 会为那些持有记忆但没有注册表行的命名空间添加一条所有者行。
+
+
+
+## 设置
+
+| 设置 | 作用 |
+| -------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| `LOOM_NAMESPACE_AUTOREGISTER_ENABLED` | 首次写入时注册该命名空间。 |
+| `LOOM_NAMESPACE_BENCH_PREFIXES`, `LOOM_NAMESPACE_GC_*` | 哪些命名空间是一次性的,以及 GC 何时清除它们。 |
+| `LOOM_MENTOR_TTL_SECONDS`, `LOOM_MENTOR_MAX_HINTS_PER_SESSION` | mentor 缓存,以及每个会话中每次调用提示的数量上限;TTL 为 0 时禁用 mentor。 |
+| `LOOM_CONFLICT_THRESHOLD` | 命名空间继承的部署级冲突阈值。 |
+
+参见[配置:命名空间注册与 GC](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#namespace-registration-and-gc)和[配置:上下文](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#context)。
+
+
+
+## 限制
+
+- 命名空间名称长度为 1–128 个字符,建议使用 kebab-case。
+- `namespace.delete` 是软删除。它不会删除记忆,只有擦除操作才会删除。
+- 修改 `default_conflict_policy` 或 `retrieval_defaults` 会改变之后的写入和搜索行为,已存储的行不会被重新判定。
+- `memory.promote` 只在一个命名空间内共享。其他命名空间只能通过副本(`memory.copy_to`、`memory.cross_promote`)看到某条事实,副本不会跟随源记忆之后的修改。
+
+
+
+## 相关内容
+
+- [身份与命名空间](../concepts/identities-and-namespaces.md):模型说明。
+- [令牌与授权](https://github.com/ClickHouse/loom/blob/main/docs/guides/tokens-and-grants.md):创建令牌并限定访问范围。
+- [控制台](dashboard.md):组织中的命名空间、设置和管理抽屉。
+- [安全架构](https://github.com/ClickHouse/loom/blob/main/docs/architecture/security.md):请求如何获得授权。
+- [操作参考:命名空间](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md#namespace)、[授权](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md#grants)、[导师](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md#mentor)、[agent](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md#agents)。
diff --git a/i18n/.pending/zh-CN/docs/features/observability/telemetry.md b/i18n/.pending/zh-CN/docs/features/observability/telemetry.md
new file mode 100644
index 0000000000..67f883eb8d
--- /dev/null
+++ b/i18n/.pending/zh-CN/docs/features/observability/telemetry.md
@@ -0,0 +1,326 @@
+
+> 本页由机器从[英文原文](https://github.com/ClickHouse/loom/blob/main/docs/features/observability/telemetry.md)翻译,内容以英文原文为准。
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/features/observability/telemetry.md), which is authoritative.
+
+
+
+# 遥测
+
+Loom 通过三个层面报告自身的运行情况:
+
+| 层面 | 存放位置 | 回答的问题 |
+| ---------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------- |
+| 账本 | `loom.agent_events`,每次操作或 worker 执行对应一行 | 谁调用了什么、耗时多久、成本多少 |
+| OpenTelemetry | `default.otel_traces`、`otel_logs`、`otel_metrics_*`(或 OTLP collector) | 一次请求内部的时间花在哪里;趋势与告警 |
+| ClickHouse 查询归因 | `system.query_log.log_comment` | 哪个操作或 worker 让 ClickHouse 执行了这些工作 |
+
+三者共用同一个请求 id。[审计日志](https://github.com/ClickHouse/loom/blob/main/docs/features/observability/audit.md)是另一份记录,用于记录谁修改了什么,并具备防篡改能力。
+
+
+
+## 账本
+
+`loom.agent_events` 每个操作一行:`operation`、身份列(`org`、`namespace`、`agent`、`user_id`、`session_id`、`run_id`)、`request_id`、`trace_id`、`latency_ms`、`success`、`error_code`、token 计数、`upstream_cost_usd`、`model`、`llm_calls`、`consumer`、`traffic_class`、`subject`、`build_commit`、`instance`、`instance_label`,以及一个 `args` 映射,其中保存经过限长和脱敏的请求与输出字段。worker 的各个处理阶段写入 `kind='worker'` 的行。[成本与用量](https://github.com/ClickHouse/loom/blob/main/docs/features/observability/cost-and-usage.md)基于此表构建。
+
+每条请求行还带有服务级别列:
+
+- `transport`:`http` 或 `mcp`。
+- `slo_class`:`code`、`search`、`admin`;其他非只读的 op 为 `write`,否则为 `read`。
+- `status_class`:`ok`;4xx 拒绝,或被重试的幂等键仍在运行时为 `client`;其余情况为 `server`。
+- `budget_ms`:该请求所适用的延迟预算。预算为 0(用于强制产生违规的覆盖值)会使每个成功的请求都算作慢请求。
+
+未指定 org 或命名空间的调用,会记录在闸门放行它时所针对的 org 和命名空间之下(代码 op 的默认值是部署的代码命名空间),因此这一行归该租户所有:它的 SLI、成本汇总、`subject_last_seen` 以及历史策略的计数都会在那里看到它。未指定 org 且在闸门之前被拒绝的调用,记录在令牌所属的 org 之下(org 级令牌或关闭认证时为 `-`),因此 `cost.summary`、已连接 agent 视图和 `subject_last_seen` 也会把它计入该 org。
+
+计入服务端错误的情况:
+
+- 因无法评估历史策略而被拒绝的写入。
+- 因检查所需的某次读取失败而做出的拒绝(授权、subject 的别名、服务账号或委托令牌的创建者、命名空间分类)。如果请求自身的答案因此被拒绝或隐藏(按 id 查找返回 `found=False`、处理器自身检查返回的 403 或 404、整个 org 级汇总被清空),即使在传输层上成功,也算 `server`,此时 `error_code` 为空。
+- 不计入的情况:答案本身完整,只是少了某个命名空间。例如 Loom 自行添加的命名空间(代码链接、grounding、仓库文档、trunk、为调用方未指明条目的代码答案补充信息的 tracker)、调用方未限定范围的列表或默认选择所省略的条目,或发布者本已被放行的任务上的所有者检查。这些情况下请求仍为 `ok`。
+
+调用被放行之前的拒绝:
+
+- MCP 会为分发前被拒绝的调用写一行(令牌不能使用的 org 或命名空间、不对 MCP 开放的 op、只读连接上的写入),与 HTTP 对其拒绝的处理一致。此时调用方尚未绑定,所以该行带有令牌的 org(或调用指明的 org,若令牌可在其中操作)、subject 和 consumer,其余为 `-`,且没有参数。
+- 在两种传输上,指明了令牌无权操作的 org 的拒绝,都记录在令牌所属的 org 中,而不是所指明的 org。
+- 在调用被分类之前记录的拒绝,带有令牌的 `traffic_class` 声明,没有声明则为 ''。
+- 在同一个 MCP 批次内,调用方在处理器运行前的拒绝,按操作、代码、org 和状态类别各记录一次;服务端故障最多记录十次。未写入的行计入 `loom.ledger.batch_repeats`(调用方的拒绝)或 `loom.ledger.dropped{reason="batch_repeat"}`(服务端故障的,即丢失的服务端错误)。幂等拒绝(在限流器之后)和处理器的失败总是有各自的行。
+
+一个可刷新的物化视图每分钟把账本汇总进 `loom_telemetry.sli_minute`(请求数、服务端和客户端错误、被限流的请求(属于客户端错误)、超出预算的成功请求、延迟分位数,保留 400 天;延迟是处理器的耗时,也就是预算所针对的那段,不含其前面的各道闸门),供 SLO 控制台和告警规则读取,无需扫描账本。它从 ClickHouse 接收每一行的时间(`ingested_at`)继续,而不是该行的 `ts`,因此刷写被延迟的行仍然只会被计数一次,并计入其 `ts` 所在的那一分钟;一行在 ClickHouse 接收后至少 70 秒(最多约 130 秒)才会被汇总,这为它的插入留出了提交的时间。一次刷新写入一个 part,因此刷新失败时,重试既不会重复汇总,也不会遗漏。若某个账本 part 的提交时间晚于 ClickHouse 给其行打时间戳后的 70 秒,它就永远不会被汇总;`loom.sli.rollup_missed_rows` 统计最近一天内这类行的数量,重新汇总该rollup([ClickHouse](../../architecture/clickhouse.md))即可恢复它们。没有 SLO 类别的行(`/v1/me/*` 路由,以及未指明任何已注册 op 的 MCP 调用,如 `initialize`)不在汇总之内。同一分钟在合并之前可能以多行形式出现,因此读取方应按其键分组,计数用 `sum()`,延迟用 `quantilesTDigestMerge(0.5, 0.95, 0.99)(latency)`。每次刷新还会写入一行,所有键为空、所有计数为 0,下一次刷新从这里继续:读取方应过滤 `slo_class != ''`。若要排除测试流量,过滤 `traffic_class NOT IN
+('bench', 'background')`:在调用被分类之前记录的拒绝,其类别为空。
+
+发送器是批量的,从不使请求失败;崩溃可能丢失尚未刷出的队列。
+
+每个写入行的进程都要标明其启动者。compose 文件设置 `LOOM_DEPLOYMENT=1`,并给服务打上 `deploy:web`、`deploy:workers` 或 `deploy:dev` 标签。任何其他进程(`make server`、测试服务器)必须设置 `LOOM_INSTANCE_LABEL=::`,否则拒绝启动;`loom serve` 默认为 `cli:serve:`。这样可以让该部署的行与同一 ClickHouse 上的其他内容区分开。
+
+
+
+## 追踪与日志
+
+- **追踪。** span 写入 `default.otel_traces`(或 OTLP 端点),并带有 `loom.org`、`loom.namespace`、`loom.agent`、`loom.operation`、`loom.request_id` 和 `enduser.id` 标签。健康检查轮询不会产生 span(`LOOM_OTEL_EXCLUDED_URLS`,默认 `/v1/health`)。每个 HTTP 响应都带有 `X-Request-Id`(若客户端发送了由 1 到 64 个字母、数字、`.`、`_` 或 `-` 组成的值,则沿用客户端的值)和 `X-Trace-Id`。span 不会携带查询文本。
+- **模型调用。** 每次 LLM 和 embedding 调用都是独立的 span,名为 `llm.` 或 `embed.provider`,并带有 OpenTelemetry GenAI 属性:`gen_ai.provider.name`、`gen_ai.operation.name`(`chat` 或 `embeddings`)、`gen_ai.request.model`、`gen_ai.usage.input_tokens` 和 `output_tokens`,provider 提示缓存的份额记在 `gen_ai.usage.cache_read.input_tokens` 和 `cache_creation.input_tokens` 中(两者都包含在 `input_tokens` 内),以及根据 Loom 价格表计算的 `gen_ai.usage.cost`。发起调用的环节记为 `loom.llm.stage`。由 Loom 自身 embedding 缓存提供的 token 记为 `loom.embed.cached_tokens`,与计费的输入分开。HyperDX 的 LLM 视图和 Langfuse 会按原样读取这些键。
+- **日志。** 使用 `docker logs loom-server` 和 `docker logs loom-workers`,以及导出到 `default.otel_logs` 的 OTel 日志。日志管道可使用 `LOOM_LOG_FORMAT=json`,用 `LOOM_LOG_LEVEL` 控制详细程度。启动日志会列出解析出的 provider 和每个已应用的迁移;supervisor 会记录每次失败的轮次以及 `DEGRADED` 行。
+- **Langfuse。** 设置 `LOOM_LANGFUSE_URL` 和 `LOOM_LANGFUSE_ADMIN_TOKEN` 后,span 树还会作为第二个 span 处理器转发到 Langfuse,经过采样和过滤。参见 [Langfuse](../integrations/langfuse.md)。
+
+`init_otel` 在 pytest 下不会启动,因此测试不会写入部署的可观测性表。`LOOM_OTEL_ENABLED=false` 会关闭数据输出。
+
+
+
+### 导出器
+
+| 设置 | 默认值 | 作用 |
+| ------------------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `LOOM_OTEL_EXPORTER` | `""` | `ch` 直接写入 Loom 自带 ClickHouse 服务上的 `default.otel_*` 表;`otlp` 发送到收集器;为空时,若设置了端点则为 `otlp`,否则为 `ch` |
+| `LOOM_OTEL_EXPORTER_OTLP_ENDPOINT` | `""` | OTLP/HTTP 收集器的基础 URL(会追加 `/v1/traces` 和 `/v1/metrics`) |
+| `LOOM_OTEL_EXPORTER_OTLP_HEADERS` | `""` | 以逗号分隔的 `K=V` 请求头,例如 `Authorization=Bearer ` |
+| `LOOM_OTEL_SERVICE_NAME`, `LOOM_OTEL_ENVIRONMENT` | `loom`, `dev` | 每个 span、日志和指标上的 `service.name` 和 `deployment.environment.name` |
+| `LOOM_OTEL_METRICS_EXPORT_INTERVAL_S` | `60` | 指标导出间隔;span 保持自己的 3 秒批处理延迟 |
+| `LOOM_OTEL_METRICS_DELTA_TEMPORALITY` | `false` | 计数器和直方图使用增量而非累积值;默认的控制台读取累积行,因此两者应同时切换 |
+| `LOOM_OTEL_GAUGE_HEARTBEAT_S` | `0` | 仅限 `ch` 导出器:仅在值变化时或经过这么多秒后才写入一个 gauge 点;0 = 每次导出都写(gauge 图块会用 0 填补空缺)。OTLP 会导出每个点 |
+| `LOOM_OTEL_CENSUS_SCOPE` | `leader` | 由谁执行全表普查:仅持有 supervisor 租约的进程,或每个进程(开销大) |
+
+`ch` 导出器写入 ClickStack/HyperDX 读取的表,因此默认的技术栈无需收集器即可使用控制台。参见 [ClickStack](../integrations/clickstack.md) 和 `deploy/hyperdx_dashboards.md`。
+
+
+
+## 指标
+
+指标每隔 `LOOM_OTEL_METRICS_EXPORT_INTERVAL_S` 导出一次。使用 `ch` exporter 时,指标写入 `default.otel_metrics_sum`、`default.otel_metrics_histogram` 和 `default.otel_metrics_gauge`;使用 `otlp` 时,指标发送到 collector 的 `/v1/metrics`。控制台定义位于 `deploy/dashboards/` 和 `deploy/hyperdx_dashboards.md`。
+
+标签来自封闭集合(操作、命名空间、有界枚举)。键、用户 id、会话 id 和查询文本从不作为标签;`tests/unit/test_domain_metrics.py` 会强制检查这一点。模型标签(`loom.llm.fallback`、`loom.llm.response_cache`)的取值是价格表中列出的模型,或部署的 `LOOM_LLM_MODEL` / `LOOM_LLM_FALLBACK_MODEL`,其他任何模型都记为 `unlisted`,因为请求可以指定模型。
+
+需要扫描表的 gauge 由持有 workers 租约的实例计算并缓存:完整性不变量和 embed 积压每隔 `LOOM_OTEL_INVARIANTS_PROBE_S`(3600 秒)计算一次,保留期普查每隔 `LOOM_OTEL_RETENTION_CENSUS_S`(3600 秒)一次,代码平面计数每隔 `LOOM_OTEL_CODE_COUNTS_CACHE_S`(3600 秒)一次。
+
+
+
+### 请求与成本
+
+| 指标 | 类型 | 含义 |
+| ------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `loom.requests` | counter | 已处理的操作数,按操作、命名空间、是否成功以及 `loom.error_code`(失败时的错误码,成功时为空)区分 |
+| `loom.request.duration` | histogram | 操作的墙钟耗时,单位 ms |
+| `loom.cost.usd` | counter | 归属于某个操作的上游提供方花费 |
+| `loom.tokens` | counter | 按 `kind`(`embed`、`llm_input`、`llm_output`)统计的 token |
+| `loom.ops.paid_errors` | counter | 已经产生上游花费的失败请求 |
+| `loom.llm.fallback` | counter | 由 `LOOM_LLM_FALLBACK_MODEL` 应答的 LLM 调用 |
+| `loom.llm.response_cache` | counter | 按结果统计的精确提示词 LLM 缓存查找 |
+| `loom.memory.build.tokens` | counter | 构建记忆所花费的 LLM token,按阶段和方向区分 |
+| `loom.memory.extraction_yield` | histogram | 每写入一条记忆所用的提示词 token,按 `messages` 范围区分 |
+| `loom.extract.cost_per_row_usd` | histogram | 一次提取每写入一行记忆的 USD 成本 |
+| `loom.auth.refusals` | counter | 因其 bearer 令牌而被拒绝的请求(没有令牌、验证失败的令牌,或暂时无法检查的令牌;也包括由 ClickHouse 判定已吊销的令牌发起的签发),按 `reason`(`missing`、`malformed`、`expired`、`revoked`、`invalid`、`unavailable`)和 `loom.transport`(`http`、`mcp`,或用于提供方令牌缺失、格式错误或错误的 SCIM 请求的 `scim`)区分;这些都不会进入 SLI 汇总 |
+
+
+
+### Agent 信任
+
+使用 `--agent-claim` 注册的工作负载信任,会在每个 agent 首次交换时为其创建一个命名空间,数量上限为 `--max-agents`([机器人与 CI](https://github.com/ClickHouse/loom/blob/main/docs/operations/sso.md#bots-and-ci))。`loom.trust` 是该信任的名称,只有运维人员可以注册。
+
+| 指标 | 类型 | 含义 |
+| ----------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `loom.auth.agents_provisioned` | counter | 某个信任下 agent 的首次交换,按 `loom.org`、`loom.trust` 和 `outcome` 区分:`made`(已创建其命名空间)或 `at_cap`(被拒绝:该信任已创建 `--max-agents` 个) |
+| `loom.auth.trust_agents` | gauge | 活跃信任下仍存活的 agent(已释放的不计入),与上限的计数方式一致;由持有 workers 租约的实例每五分钟计算一次 |
+| `loom.auth.trust_agents_used_ratio` | gauge | `loom.auth.trust_agents` 与该信任的 `--max-agents` 之比;达到 1 时,每个新 agent 都会被拒绝 |
+
+
+
+### 检索质量
+
+这些指标用于发现“速度很快但结果错误”的搜索,这是 HTTP 指标看不到的。
+
+| 指标 | 类型 | 含义 |
+| --------------------------------------- | --------- | ----------------------------------------------------------------------------------------- |
+| `loom.search.results` | histogram | 每次搜索的结果数;向 0 漂移意味着悄无声息的故障 |
+| `loom.search.top_similarity` | histogram | 最佳命中的余弦相似度;最具诊断价值的检索信号(更换 embedder 后需重新建立基线) |
+| `loom.search.confidence` | histogram | 响应中的 `retrieval_confidence` |
+| `loom.search.abstain` | counter | 选择放弃作答的搜索,按 `reason` 区分 |
+| `loom.search.plane_hits` | counter | 每个检索平面的命中数 |
+| `loom.search.assist` | counter | 启用的可选辅助(HyDE、rerank、迭代式评判),按 `kind` 区分 |
+| `loom.search.judged_relevance` | histogram | 独立 LLM 评判者对抽样搜索的评分(`LOOM_RETRIEVAL_JUDGE_SAMPLE_RATE`,默认 0) |
+| `loom.search.judge_verdict` | counter | 评判者的裁决,按类别统计 |
+| `loom.search.bm25_stats_failures` | counter | 失败后放行的 BM25 语料统计读取(词法部分未加权运行),按平面和错误区分 |
+| `loom.memory.search.enumeration_shaped` | counter | 措辞上要求枚举某一类已存储记录的搜索;这是一个信号,而不是拒绝 |
+
+
+
+### 记忆写入
+
+| 指标 | 类型 | 含义 |
+| ---------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------- |
+| `loom.memory.writes` | counter | 写入结果:created、updated、merged、duplicate、conflicted、rejected、blacklisted、too_large 等 |
+| `loom.memory.drops` | counter | 摄取管线丢弃或截断的条目,按 `stage` 和 `reason` 区分(行记录在 `loom.memory_drops` 中) |
+| `loom.memory.attribute_tagged` | counter | 写入时被标记为 `attribute:` 的行 |
+| `loom.policy.decisions` | counter | 历史策略闸门的决策 |
+| `loom.procedure.runs`, `loom.procedure.evolve` | counter | 按结果统计的 procedure 运行;`procedure.evolve` 的结果 |
+| `loom.memory.agent_labels_24h` | gauge | 过去 24 小时内 agent 写入的使用标签,按命名空间统计(前 `LOOM_OTEL_AGENT_LABELS_MAX_NAMESPACES` 个,其余记为 `other`) |
+| `loom.memory.agent_labels_namespaces_at_pace` | gauge | 每个组织中 agent 标签达到每月 1,000 条的日均速度的命名空间数 |
+
+`loom drops --namespace NS [--hours 24]` 会按阶段和原因输出丢弃计数。彻底失败的提取不算丢弃:`set_from_messages` 返回 502 `EXTRACTION_FAILED`,部分失败则出现在响应的 `pipeline_errors` 中。
+
+
+
+### 积压与进程状态
+
+水位非零并且能够逐步消化,属于正常情况。
+
+| 指标 | 类型 | 含义 |
+| ---------------------------------------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `loom.embed.pending` | gauge | 等待生成向量的行(`embedding_dim = 0`);尚不可搜索的记忆 |
+| `loom.vectors.total` | gauge | 已存在的已嵌入向量 |
+| `loom.vector_index.searches_total`, `adds_total`, `reads_indexed_ratio` | gauge | 被探测副本上的向量索引使用情况:已处理的搜索与已付出的构建成本之比,以及近期向量读取中打开了索引的比例 |
+| `loom.process.open_fds`, `loom.process.fd_limit` | gauge | 每个进程(`loom.pid`)的已打开描述符数和软限制;曲线持续上升说明存在泄漏 |
+| `loom.host.disk.free_bytes`, `loom.host.disk.total_bytes` | gauge | 存放 `var/` 的磁盘的可用字节数和总字节数 |
+| `loom.ch.mutations_pending` | gauge | 尚未完成的 ClickHouse mutation 数 |
+| `loom.ch.table.active_parts`, `wide_parts`, `patch_parts`, `bytes_on_disk`, `rows_per_mark` | gauge | 按表(`loom.table`)统计,针对参与维护的表 |
+| `loom.memory_embeddings.patch_parts` | gauge | `loom.memory_embeddings` 上的 patch part 数;非零时会关闭量化编码读取 |
+| `loom.ch.view_refresh.scheduled`, `loom.ch.view_refresh.age_s` | gauge | 按可刷新视图(`loom.view`,位于 `loom` 中的只写视图名,否则带数据库名:`loom_telemetry.sli_minute_refresh`)统计:已调度且无错误时为 1;以及距上次成功的秒数 |
+| `loom.sli.rollup_lag_s` | gauge | 最近一次存储探测(每五分钟一次,由 workers-lease 持有者执行)时,`loom_telemetry.sli_minute` 的标记落后于当前时间的秒数:正常时约为 70 到 130;更大说明汇总正在追赶,其最新的几分钟读取为空 |
+| `loom.sli.rollup_missed_rows` | gauge | 最近一天内的账本请求行中,其插入在汇总标记越过它们之后才提交的行数,因此 `sli_minute` 永远不会统计它们(存储探测,每五分钟一次,由 workers-lease 持有者执行);大于 0 时应告警并重新折叠汇总 |
+| `loom.audit.checkpoint_lag_windows` | gauge | 尚未封入检查点链的每小时审计窗口数([审计日志](https://github.com/ClickHouse/loom/blob/main/docs/features/observability/audit.md#checkpoint-lag)) |
+| `loom.langfuse.breaker` | gauge | Langfuse 评分熔断器:0 为闭合,1 为半开,2 为打开(评分被丢弃;span 导出不受影响) |
+| `loom.health.problems` | gauge | 此进程上每个未解决的 `/v1/health` 问题计为 1,按 `code` 和 `severity` 区分(`provider_failing` 另有 `provider`),但 `/v1/health` 通过 ClickHouse 读取发现的问题(`otel_erasure_index`)除外;已解决的问题会停止上报,因此告警应读取至少为 `LOOM_OTEL_GAUGE_HEARTBEAT_S` 加一个 `LOOM_OTEL_METRICS_EXPORT_INTERVAL_S` 的窗口(即两个没有心跳的间隔):使用 `ch` 导出器并有心跳时,未变化的值会在每次心跳之后的第一次导出时写入 |
+| `loom.ledger.dropped` | counter | 此进程自启动以来丢失的账本行数,按 `reason` 区分(`queue_full`、`flush_failed` 和 `batch_repeat`:MCP 批处理在其十行之外没有写入的服务器故障);SLI 会相应少计同样的数量 |
+| `loom.ledger.batch_repeats` | counter | MCP 批处理没有再次写入的调用方拒绝行(每个批次只记账一次);这是调用方所致,不属于丢失 |
+| `loom.worker.passes` | counter | 按 `worker` 和 `outcome` 统计的轮次数 |
+| `loom.worker.pass_duration_ms` | histogram | 单轮的实际耗时 |
+| `loom.worker.consecutive_failures` | gauge | 每个 worker 当前的连续失败次数;达到 3 时告警 |
+| `loom.worker.partial_failures` | gauge | 上一轮容忍下来的失败数 |
+| `loom.retention.active_rows`, `never_recalled_ratio`, `low_information_rows`, `sensitive_without_expiry`, `stale_candidates` | gauge | 按组织统计的记忆整洁度计数;Loom 不会按时间删除任何内容 |
+
+
+
+### Postgres 发布管道
+
+在 `LOOM_STORAGE_AUTHORITY=postgres` 下:一次写入需要多久才能被搜索到,以及 ClickHouse 还欠下哪些数据(无论哪种 authority,`loom.ch.inserts` 都会计数)([管道 SLO](https://github.com/ClickHouse/loom/blob/main/docs/operations/monitoring.md#pipeline-slos))。
+
+| 指标 | 类型 | 含义 |
+| ---------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `loom.pg.search_wait_ms` | histogram | 读取在屏障处等待 ClickHouse 持有该命名空间写入的时间,按 `loom.operation`(请求调用的 op)、`outcome`(`passed`,或在到达截止时间时为 `deadline`,截止时间即 `LOOM_PG_PROJECTION_WAIT_MS` 或可重入的一轮所剩的时间:该 op 返回 503 `PROJECTION_BEHIND`,这是一份可以跳过投影读取继续的报告)和 `loom.traffic_class` 区分;仅统计发现其落后的读取 |
+| `loom.pg.projection_lag_ms` | histogram | 按 Postgres 的时钟,从某个修订的提交事务开始,到其投递清除了最后一个搜索目标为止,按 `path`(flush、redelivered)区分:文档已落地,或重新投递发现该修订已不再提供服务(已被编辑删除,或其键已更新)并在未发送的情况下将其结清 |
+| `loom.pg.backlog` | gauge | 按 `source`(memory、audit_outbox、knowledge)和 `state`(pending、parked)统计的待投递数,每项最多计到 `LOOM_PG_BACKLOG_COUNT_CAP`;memory 的 pending 项是搜索所等待的那些 |
+| `loom.pg.oldest_pending_age_s` | gauge | 按 `source` 统计的最旧待投递项的年龄:memory 的从其提交事务开始算起,knowledge 的从其来源的最近一次提交算起,均在按租约排序的前 `LOOM_PG_BACKLOG_COUNT_CAP` 项中取;audit outbox 的为逾期秒数,覆盖所有已逾期的行 |
+| `loom.pg.backlog_reading_age_s` | gauge | 自各来源的积压被读取以来的秒数,仅在读数新鲜时上报;两个导出周期内没有新读数时,积压相关的 gauge 会停止上报 |
+| `loom.ch.inserts`, `loom.ch.insert_rows` | counter | 记忆写入路径对记忆行和搜索文档的插入,以及审计写入器的插入,及其行数,按 `table` 区分;`memory` 和 `memory_embeddings` 的插入是已提交的,每次一个 part,而 `audit_log` 的插入默认是批量的(`LOOM_CH_BATCHED_INSERTS`) |
+
+积压由投递 worker 在每一轮的开头读取,并由运行它们的进程导出(默认是 workers 子进程,否则是 workers-lease 持有者)。多个进程可能同时导出(`LOOM_BACKGROUND_WORKERS=on`、租约交接),每个进程导出的都是整个部署的全部积压:聚合这些 gauge 时应使用 `max`,不要用 `sum`。
+
+
+
+### 完整性不变量
+
+每一项都应始终为 0。非零值表示已经发生的缺陷,且不会自行消退。
+
+| 指标 | 非零值表示 | 修复 |
+| --------------------------------------------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------- |
+| `loom.integrity.divergent_entities` | 某条记忆在 `loom.memory` 与 `loom.memory_embeddings` 中的实体不一致 | 排查写入路径 |
+| `loom.integrity.orphan_vectors` | 已嵌入的向量,其记忆行已不存在 | `orphan_vector_reconcile` worker |
+| `loom.integrity.orphan_entity_vectors` | 实体向量,其记忆行已不存在 | `orphan_vector_reconcile` worker |
+| `loom.integrity.orphan_graph_namespaces` | 有实体边但没有有效记忆或知识的命名空间 | `loom erasure-re-verify --orphan-graph --erase` |
+| `loom.integrity.live_ns_unregistered`, `live_rows_unregistered` | 位于没有 `loom.namespaces` 行的命名空间中的有效记忆 | 注册该命名空间 |
+| `loom.integrity.dim0_with_vector` | 有向量但 `embedding_dim = 0` 的行,搜索不可见 | `loom integrity-repair --apply` |
+| `loom.integrity.tombstone_status_drift` | 设置了 `tombstoned_at` 但状态为其他值的行 | 由 `loom integrity-repair` 列出 |
+| `loom.integrity.active_past_valid_to` | 已超过自身 `valid_to` 的活动行 | 由 `loom integrity-repair` 列出 |
+| `loom.integrity.high_with_embedding` | 仍有有效嵌入行的高敏感度行 | `loom sensitivity-sweep --apply` |
+
+
+
+### 代码平面
+
+按命名空间统计。
+
+| 指标 | 类型 | 含义 |
+| ----------------------------------------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `loom.code.index_lag_commits` | gauge | 索引水位线与分支末端之间相差的提交数;表示索引过期的信号 |
+| `loom.code.index_age_seconds` | gauge | 水位线上次推进至今的秒数 |
+| `loom.code.stale_files` | gauge | 已索引路径中,其分块早于文件在 head 处内容的路径数 |
+| `loom.code.scip_lag_commits`, `scip_age_seconds`, `scip_py_age_seconds` | gauge | 各编译器层级(`tier` 属性)落后于快速层级的程度 |
+| `loom.code.tier_lag_seconds` | gauge | 某个层级(`fast`、`clang`、`python` 等)尚未处理到的最旧提交的年龄 |
+| `loom.code.tier_failing` | gauge | `code_tier_failing` 健康问题所报告的各层级连续失败的次数,按 `tier`、错误 `kind` 以及该问题评定的层级 `severity` 区分 |
+| `loom.code.tier_lag_commits` | gauge | 上述各层级落后于已拉取末端的提交数(下限值:按该条目最后发布的状态统计),按 `tier` 区分;仅在落后量已知时上报 |
+| `loom.code.pr_cursor_age_seconds` | gauge | PR 历史同步落后于 GitHub 的程度 |
+| `loom.code.files_errored`, `loom.code.embed_backlog` | gauge | 索引出错的文件数;等待生成向量的分块数 |
+| `loom.code.symbols` | gauge | 按 `tier`(`treesitter`、`scip`)统计的有效符号数;数量下降说明应用出错 |
+| `loom.code.edges_unqualified`, `loom.code.edges_low_confidence` | gauge | 仅按名称绑定的解析器层级调用边;可与 `loom.code.symbols` 对比 |
+| `loom.code.grep.wrong_abstain_24h` | gauge | `code.grep` 对语料中存在的字面量放弃返回结果的次数;前 8 个调用方加 `other`(每 `LOOM_OTEL_CODE_GREP_REPLAY_CACHE_S` 重新统计一次;0 = 关闭) |
+| `loom.code.repos_config_errors` | gauge | `LOOM_CODE_REPOS_JSON` 中无法使用的条目数(0 = 解析无误) |
+| `loom.code.outcome`, `loom.code.shunt`, `loom.code.shunt_tokens_saved` | counter | 客户端上报的结果;coding agent 的分流决策,以及被挡在上下文之外的 token |
+| `loom.code.ask_cache`, `ask_cache_saved_ms`, `ask_cache_saved_usd` | counter | `code.ask` 答案缓存的结果以及命中所节省的量 |
+| `loom.tracker.sections`, `loom.tracker.section_ms` | 计数器、直方图 | 按模板和状态统计的 `tracker.answer` 分节;读取耗时 |
+
+关于滞后指标对调用方意味着什么,参见[代码索引新鲜度](../code-index/freshness.md)。
+
+
+
+### 建议的告警
+
+| 条件 | 原因 |
+| ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `loom.search.top_similarity` 均值低于基线持续 30 分钟 | 检索质量下降(嵌入模型或索引发生变更) |
+| `loom.embed.pending` 高于 100 持续 15 分钟 | 新记忆无法被搜索到 |
+| 任何 `loom.integrity.*` 高于 0 | 出现了数据缺陷 |
+| `loom.worker.consecutive_failures` ≥ 3 | worker 陷入失败循环 |
+| `loom.process.open_fds / loom.process.fd_limit` 高于 0.5 | 描述符泄漏 |
+| `loom.host.disk.free_bytes / loom.host.disk.total_bytes` 低于 0.10 | 数据磁盘即将写满 |
+| `loom.langfuse.breaker` = 2 | 发往 Langfuse 的评分正在被丢弃 |
+| `loom.audit.checkpoint_lag_windows` 持续上升数小时 | 审计封存器已停滞 |
+| `loom.code.index_lag_commits` 高于每轮提交预算持续 15 分钟 | 代码摄取正在落后 |
+| `loom.code.tier_lag_seconds` 高于 1800 持续 10 分钟 | 某个编译器层级卡住(即 `deploy/dashboards/code_plane.json` 中的“code tier lag”告警;阈值应设置得高于最慢层级的正常周期) |
+| 每个 trust 的 `loom.auth.agents_provisioned{outcome=made}` 高于其控制平面的正常速率(可从 10 分钟内 50 起步) | 某个 trust 命名新 agent 的速度超过其集群的增长速度:可能是签发密钥泄漏,或控制平面失控 |
+| `loom.auth.trust_agents_used_ratio` 高于 0.8 | 该 trust 接近 `--max-agents` |
+| `loom.auth.agents_provisioned{outcome=at_cap}` 在 10 分钟内增量高于 0 | 该 trust 的新 agent 被拒绝 |
+
+在 HyperDX 中,空结果会被当作 0,因此最小样本数保护必须返回一个处于健康范围内的值,而不是不返回任何行。
+
+起步查询:
+
+```sql
+-- mean top similarity per namespace, last hour
+SELECT Attributes['loom.namespace'] AS ns,
+ round(anyLast(Sum) / greatest(anyLast(Count), 1), 3) AS mean_top_similarity
+FROM default.otel_metrics_histogram
+WHERE MetricName = 'loom.search.top_similarity' AND TimeUnix > now() - INTERVAL 1 HOUR
+GROUP BY ns;
+
+-- every gauge's latest value
+SELECT MetricName, anyLast(Value) AS latest
+FROM default.otel_metrics_gauge
+WHERE TimeUnix > now() - INTERVAL 5 MINUTE
+GROUP BY MetricName ORDER BY MetricName;
+```
+
+
+
+## ClickHouse 中的查询归因
+
+每条 ClickHouse 查询都带有一个 `log_comment` 设置,用来标明发起者:请求使用 `
+`,worker 的一次处理使用 `worker.`,CLI 命令使用 `cli.`,其余情况使用 `untagged:.`。标签表、`query_id` 关联以及语句摘要见 [ClickHouse:查询归因](../../architecture/clickhouse.md#query-attribution)。
+
+```sql
+-- one request end to end
+SELECT * FROM loom.agent_events WHERE request_id = '';
+SELECT query_duration_ms, read_bytes, log_comment
+FROM system.query_log
+WHERE type = 'QueryFinish' AND log_comment LIKE '% %';
+```
+
+
+
+## 不是遥测:`observe.*` 操作
+
+`observe.record` 和 `observe.crystallize` 属于记忆平面。它们用于捕获 agent 的工具调用:
+
+- `observe.record` 将一次工具调用(工具名称、输入、输出、文件路径、错误)存为一条情节性的、不可搜索的记忆行,键为 `obs::`,不调用 LLM,也不做同步嵌入。如果工具调用来自 Loom 自身或 harness 的元工具,则不存储内容(`skipped_reason: "self_referential"`),内容匹配黑名单模式的调用也一样(`skipped_reason: "blacklisted"`)。
+- `observe.crystallize` 是会话结束时的刷新操作:它把该会话中待处理的观察标记为可供提取。它只负责入队,不运行 LLM。
+
+提炼观察需要 `observe_extract` worker(默认关闭,由 `LOOM_OBSERVE_EXTRACT_ENABLED` 控制)。关闭时,观察会被存储,但不会被提取。
+
+编码 agent 插件如何使用这些操作,参见[对话与会话](../conversations-and-sessions.md)。
+
+`ui.vitals` 为控制台提供服务:它把某个页面的 web vitals 记录在自己的账本行上。
+
+
+
+## 相关内容
+
+- [监控](https://github.com/ClickHouse/loom/blob/main/docs/operations/monitoring.md):健康检查、控制台以及运维人员的日常视图。
+- [故障排查](https://github.com/ClickHouse/loom/blob/main/docs/operations/troubleshooting.md)。
+- [成本与用量](https://github.com/ClickHouse/loom/blob/main/docs/features/observability/cost-and-usage.md)和[审计日志](https://github.com/ClickHouse/loom/blob/main/docs/features/observability/audit.md)。
+- [ClickStack](../integrations/clickstack.md)和 [Langfuse](../integrations/langfuse.md)。
+- [Workers 参考](https://github.com/ClickHouse/loom/blob/main/docs/reference/workers.md)和[配置参考](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#observability)。
diff --git a/i18n/.pending/zh-CN/docs/features/tasks-and-decisions.md b/i18n/.pending/zh-CN/docs/features/tasks-and-decisions.md
new file mode 100644
index 0000000000..4b6d25177d
--- /dev/null
+++ b/i18n/.pending/zh-CN/docs/features/tasks-and-decisions.md
@@ -0,0 +1,415 @@
+
+> 本页由机器从[英文原文](https://github.com/ClickHouse/loom/blob/main/docs/features/tasks-and-decisions.md)翻译,内容以英文原文为准。
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/features/tasks-and-decisions.md), which is authoritative.
+
+
+
+# 任务、决策与策略
+
+除记忆之外,还有三个平面用于 agent 之间的协调。每个 op 都可以在任意 MCP 列表中按名称调用;`all` 列表显示哪些 op,详见 [MCP 工具集](https://github.com/ClickHouse/loom/blob/main/docs/reference/mcp.md#toolsets)。
+
+| 平面 | 回答的问题 | Ops |
+| --------- | ------------------------------------ | ------------------- |
+| 任务收件箱 | “这项工作属于另一个 agent,该如何移交?” | `inbox.*`, `task.*` |
+| 决策 | “遇到类似情况我们当时是如何决定的,原因是什么,结果有效吗?” | `decision.*` |
+| 历史策略 | “鉴于该 agent 刚刚的操作,现在允许它这样做吗?” | `policy.*` |
+
+**由所有者决定。** Loom 存储所有者设置的模式并加以应用。它不会把发布者提升为受信任,不会自动接受已分流的任务,也不会把策略规则从 shadow 模式切换到 enforce 模式。Loom 提供的证据(发布者的历史记录、规则的 shadow 台账)由人或所有者 agent 阅读,并由其更改模式。如果信任被自动更改,写入方就可能通过操纵自己被监测的信号来越过关卡。
+
+
+
+## 任务收件箱
+
+每个 agent 都有一个持久化队列。发布者可以向自己无法读取的收件箱写入任务。收件箱所有者决定对每个发布者的信任程度。一个已认领的任务同一时间只有一个所有者。agent 主动拉取自己的工作;可选的带签名 webhook 只是通知"现在去拉取"。
+
+```mermaid
+sequenceDiagram
+ participant S as Sender (public-bot)
+ participant L as Loom inbox private-bot
+ participant R as Receiver (private-bot)
+ S->>L: task.create (kind, brief, disclosure)
+ Note over L: policy: deny / review / auto
+ R->>L: task.pull (long poll)
+ L-->>R: claimed task + fence
+ R->>L: task.heartbeat (fence)
+ R->>L: task.complete (fence, outcome)
+ S->>L: task.updates (since_seq)
+ L-->>S: events: accepted, claimed, done
+```
+
+
+
+### 状态
+
+```mermaid
+stateDiagram-v2
+ [*] --> triage: untrusted poster (review)
+ [*] --> todo: trusted poster (auto)
+ triage --> todo: task.accept
+ triage --> wont_do: task.wont_do
+ todo --> in_progress: task.pull / task.claim
+ in_progress --> done: task.complete
+ in_progress --> failed: task.fail
+ in_progress --> deferred: task.defer
+ in_progress --> blocked: task.block
+ in_progress --> todo: lease expired
+ deferred --> todo: resume_at / task.resume
+ blocked --> todo: task.unblock
+ failed --> todo: task.reopen
+ wont_do --> todo: task.reopen
+ cancelled --> todo: task.reopen
+ done --> [*]
+```
+
+- `task.wont_do`(所有者)和 `task.cancel`(所有者,或在无人拥有该任务时的发布者)适用于任何未结束的状态。已结束的任务(`done`、`wont_do`、`failed`、`cancelled`)会返回 409 `TASK_TERMINAL`。
+- `task.reopen`(所有者)将 `failed`、`wont_do` 或 `cancelled` 的任务移回 `todo`。
+- 每一次偏离 `triage → todo → in_progress → done` 主路径的状态变更都需要带上 `reason`。
+
+
+
+### 注册收件箱
+
+所有者命名空间的管理员注册收件箱,并按 `(poster, kind)` 设置信任:
+
+```python
+from loom import Agent
+
+async with Agent(org="acme", namespace="private", agent="admin", api_key=ADMIN_TOKEN) as a:
+ await a.tasks.register_inbox(
+ "private-bot",
+ owner_agent="private-bot",
+ posters=["sa:public-bot"], # may post without holding the namespace
+ accept_disclosure=["confidential", "internal"],
+ default_lease_seconds=1800,
+ max_attempts=3,
+ )
+ await a.tasks.set_policy(
+ "private-bot",
+ poster="sa:public-bot",
+ kind="security_finding",
+ mode="review",
+ require_evidence=["inputs.finding_id", "inputs.test"],
+ )
+ await a.tasks.set_policy("private-bot", poster="sa:public-bot", kind="*", mode="deny")
+```
+
+| 模式 | 来自该发布者和该 kind 的任务…… |
+| -------- | ------------------------------------------------------------- |
+| `deny` | 被拒绝,返回 403 `TASK_POSTER_DENIED`。 |
+| `review` | 进入 `triage`,直到所有者 agent 或某个人接受或拒绝它。 |
+| `auto` | 进入 `todo`,可直接拉取。 |
+
+- 没有对应记录时,收件箱所有者和所有者命名空间的写入者发布的任务为 `auto`;其他人发布的为 `review`。
+- 以 agent 标签为键的记录,只会向所有者命名空间的写入者授予 `auto`,因为标签由调用方自行选择。对外部发布者,请以其服务账号标识(`sa:`)作为键。
+- `require_evidence` 指定创建任务时 brief 必须包含的字段;缺少时 422 会列出缺失的字段。
+- 披露级别有 `confidential`、`internal` 和 `public_ok`。任务的级别若不被收件箱接受,会返回 422,并列出可接受的值。
+
+`inbox.register` 的参数:
+
+| 参数 | 默认值 | 含义 |
+| ------------------------------- | ----------- | ------------------------------------------------------ |
+| `default_lease_seconds` | 1800 | 认领获得的租约时长,除非拉取时指定了其他值。 |
+| `max_attempts` | 3 | 租约过期多少次后,任务被阻塞并等待人工处理。 |
+| `max_defers` | 5 | 推迟多少次后,任务被阻塞并等待人工处理。 |
+| `triage_escalate_after_seconds` | 14400 (4 h) | 未回复的 triage 项达到该时长后升级,仅升级一次。 |
+| `webhook_url` | 空 | 收件箱有新事件时,接收带签名的唤醒通知。 |
+| `webhook_secret_ref` | 空 | 保存 webhook 签名密钥的环境变量。 |
+
+`webhook_url` 是 `http` 或 `https` URL,其主机只能解析到公网地址:每次投递都会解析它,拒绝回环、私有、链路本地(云元数据)和多播地址,连接到已检查过的地址(域名仍作为 `Host` 头和 TLS SNI),并且不跟随任何重定向。`webhook_secret_ref` 必须是收件箱所属组织自己的变量之一,即 `LOOM_WEBHOOK_SECRET___`:ORG 是组织 id,其中小写字母转为大写,数字保持不变,其余每个字节(包括大写字母)写成 `_` 加两位十六进制数(组织 `acme-corp` → `LOOM_WEBHOOK_SECRET_ACME_2DCORP__ALERTS`,`acme_corp` → `ACME_5FCORP`),NAME 由字母和数字组成。`inbox.register` 会拒绝其他任何名称(422),而指向其他名称的记录永远不会被读取,因此任何租户都无法让 Loom 使用其他租户的密钥签名。不同的组织 id 不会得到相同的 ORG 部分。
+
+
+
+### 发布任务
+
+```python
+async with Agent(org="acme", namespace="public", agent="public-bot", api_key=PUBLIC_TOKEN) as a:
+ out = await a.tasks.create(
+ "private-bot", # the target inbox
+ kind="security_finding",
+ title="Out-of-bounds read in the JSON reader",
+ brief={
+ "objective": "confirm and file in the private repository",
+ "inputs": {"finding_id": "f-77", "test": "json_oob.sql"},
+ },
+ disclosure="confidential",
+ idempotency_key="f-77", # a retried create lands once
+ )
+ out["task"]["status"] # "triage", or "todo" when the poster is trusted
+```
+
+同一个发布者使用同一个 `idempotency_key` 的两次创建只会存储一个任务,即使它们并发竞争:它们在该键的租约下依次执行,各自都返回该任务,只有真正存储它的那一次会返回 `created=true`。键属于其发布者自己:另一个发布者使用相同键的创建会存储它自己的任务。如果某次创建在存储任务后被中断,重试时会补写它漏掉的 `created` 事件;它缺失的租约行由租约清扫来补写,因此该任务在清扫的 60 s 宽限期加上再一轮之后即可被认领。若第一次创建自己的事件最终仍然写入(它在插入中途被取消),两者共用同一个去重令牌,读取方(`task.history`、`task.updates`、`/v1/task/watch`、webhook)只保留第一个,因此任务在其历史记录和每个游标的投递中只创建一次。若一次创建等待持有同一个键的另一次创建超过 10 s,会返回 409 `PRECONDITION_FAILED`;租约存储(Keeper)无响应时返回 503;两种情况都可以重试。
+
+`namespace` 是发布者自己的;第一个参数指定收件箱。`create` 还接受 `priority`(默认 3)、`deadline`、`not_before`、`origin` 和 `parent_task_id`。带有 `not_before` 的任务状态是 `todo`,但在该时间之前对 `pull` 不可见,bot 可以借此维护自己的"稍后重试"待办列表。
+
+| 拒绝原因 | 响应 |
+| --------------------------------------- | ------------------------------------------------ |
+| 无权发布但可读取收件箱 | 403 `AUTH_INSUFFICIENT` |
+| 既无权发布也无权读取 | 404 `RESOURCE_NOT_FOUND`,与未注册的收件箱相同 |
+| 策略拒绝该发布者或 kind | 403 `TASK_POSTER_DENIED` |
+| 披露级别不被接受 | 422,附带可接受的值 |
+| brief 缺少 `require_evidence` 字段 | 422,附带缺失的字段名 |
+
+
+
+### 拉取、处理、完成
+
+```python
+async with Agent(org="acme", namespace="private", agent="private-bot", api_key=PRIVATE_TOKEN) as a:
+ async for task in a.tasks.stream("private-bot", kinds=["security_finding"]):
+ fence = task["fence"]
+ try:
+ result = await work(
+ task["brief"], heartbeat=lambda: a.tasks.heartbeat(task["task_id"], fence=fence)
+ )
+ await a.tasks.complete(task["task_id"], fence=fence, outcome={"issue_url": result.url})
+ except Exception as e:
+ await a.tasks.fail(task["task_id"], fence=fence, reason=str(e)[:500])
+```
+
+- **长轮询。** `task.pull` 和 `task.updates` 最多等待 30 s(`wait_seconds`)。同一服务进程上的创建会立即唤醒正在等待的拉取;另一个副本上的创建则在约 2 s 内被发现。
+- **租约与 fence。** 认领会获得一个租约和一个 `fence` 令牌,所有者的每次写入都要出示它。`task.heartbeat` 延长租约。当 worker 死亡时,`task_lease_sweep` worker 会把任务放回 `todo`,在 `max_attempts` 次过期后将其阻塞并等待人工处理。过期的 fence 会得到 409 `TASK_FENCE_STALE`。只有当认领赢得租约之后重新读取的任务仍处于该 fence 下的 `todo` 时,认领才算成立;否则认领会把租约原样归还。每次清扫还会纠正与任务不同步的租约行:没有行的 `todo` 或 triage 任务会补上一行,空闲或已过期的行采用其任务的 fence(认领赢得租约后被中断,会留下一个领先一个 fence 的行),已结束任务的行会被删除。清扫会跳过最近 60 s 内写入的行,它们可能属于仍在进行中的创建或重新打开;对于协调过程为一个正在被取消的任务回写的行,会在其 60 s 宽限期之后的第一轮中被清除。若取消发生在认领的租约与其状态写入之间,会被认领覆盖,任务因此保持 `in_progress`;这个竞态在协调机制出现之前就已存在,协调机制并未消除它。
+- **其他操作。** `task.defer`(带 `resume_at`)、`task.block`(`blocked_on`:`sender`、`human`、`external`)、`task.wont_do`,以及 `task.progress`(添加备注,不改变状态)。
+- **Triage。** `task.pull(status="triage")` 返回未被认领的待审项;用 `task.accept` 或 `task.wont_do` 做出决定。发布者不能接受自己的任务(403 `TASK_SELF_ACCEPT`)。没有任何机制会让 triage 中的任务过期或自动接受。
+
+
+
+### 跟踪结果
+
+发送方用游标读取自己所发任务的事件:
+
+```python
+upd = await a.tasks.updates(since_seq=cursor, wait_seconds=30)
+for ev in upd["events"]: # accepted, claimed, done, wont_do, blocked, ...
+ reconcile(ev)
+if upd["events"]:
+ cursor = upd["next_seq"] # save only after reconcile succeeds
+```
+
+在读取与保存之间崩溃会导致事件被重放,因此 `reconcile` 必须能容忍重复。游标始终落后最新事件约 3 s,这样仍在另一个副本上写入的行不会被跳过。
+
+
+
+### 操作
+
+| 分组 | 操作 |
+| ------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| 收件箱设置(管理员) | `inbox.register`、`inbox.policy_set`、`inbox.principals`;`inbox.list`、`inbox.policy_list`(查看者) |
+| 发布(发送方) | `task.create`、`task.updates`、`task.cancel` |
+| 处理(所有者) | `task.pull`、`task.claim`、`task.heartbeat`、`task.progress`、`task.complete`、`task.fail`、`task.defer`、`task.block` |
+| Triage 与修复(所有者) | `task.accept`、`task.wont_do`、`task.unblock`、`task.resume`、`task.reopen`、`task.update`、`task.reassign` |
+| 读取 | `task.get`、`task.list`、`task.counts`、`task.history` |
+
+Python SDK 通过 `agent.tasks` 提供这些操作。通过 MCP 时,`?toolset=tasks` 会列出工作中的 agent 所用的操作:`task.pull`、`task.create`、`task.complete`、`task.fail`、`task.wont_do`、`task.defer`、`task.heartbeat`、`task.updates`、`task.list`、`task.get`、`inbox.list`。
+
+控制台的 **Tasks** 页面列出该命名空间的所有收件箱,包含需要人工处理事项的统计卡片、按下一步操作分组的行、行内的 Accept / Won't do,以及每个任务的面板(`task.update` 配合 `if_match_version`)。写入者可以执行状态机中的每一种转换:通过面板按钮(Start 是在由 `loom-ui` 持有的一天期租约下执行 `task.claim`;Mark done 和 Fail 分别是 `task.complete` / `task.fail`,使用当前租约的 fence),或者把行或卡片拖到另一个分组,这会在那里执行一步移动(拖入 To do 会执行接受、解除阻塞、恢复或重新打开;拖入 In progress 会开始;拖入 Waiting 会阻塞;拖入 Closed 会标记为完成或 won't do)。拖动任务时,一步无法到达的分组会变暗。收件箱设置从 Loom 在该组织中已知的身份里选择发布者(`inbox.principals`,管理员)。
+
+
+
+### 设置
+
+| 设置 | 默认值 | 作用 |
+| ----------------------------------- | ------ | ------------------------------------------------------------------------------------------ |
+| `LOOM_TASK_LEASE_SWEEP_ENABLED` | true | 运行清扫器:处理过期租约、到达 `resume_at` 的推迟任务、陈旧的 triage、与任务不同步的租约行。 |
+| `LOOM_TASK_WEBHOOK_DELIVER_ENABLED` | true | 每个新事件批次向收件箱的 `webhook_url` 发送一条带签名的通知。 |
+
+参见 [配置:任务收件箱](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#task-inbox)。
+
+
+
+## 决策
+
+决策记录保存日后仍然重要的选择:供应商、架构、策略例外。`decision.record` 接受 `category`、`scenario`、`reasoning`、`outcome`、`alternatives`、`confidence`,以及它的 `caused_by` 或 `influenced_by` 的键。它会写入:
+
+- 一条内置 `decision` schema 的类型化记录;
+- 一行同键、类型为 `decision` 的可搜索记忆;
+- 从每个 `caused_by` / `influenced_by` 键指向该决策的一条边。
+
+记录在仓库主干代码命名空间中的决策,也能从该仓库的检出目录通过 MCP `loom_search` 搜到,前提是调用方有权读取该命名空间([统一搜索](https://github.com/ClickHouse/loom/blob/main/docs/features/unified-search.md#reading-the-memory-section))。
+
+记忆行的值是一条陈述:`. Decided because . Rejected: ; …`,在 `decision.outcome` 记录了结果之后,再追加 `Realized: …`。category 不在其中:它保留在记录上,以及该行的 `decision:category:` 标签里,按 category 过滤时读取的就是这个标签。如果 reasoning 与 outcome 逐字相同(不计大小写、空白和结尾标点),则表示这是一条没有给出理由的禁令或不变量:陈述写作 `Decided .`,`context.pack` 不给出 `because`。每个部分都按记录保存的原样完整存储,受记录上限约束(scenario 2,000 个字符,outcome 1,000,reasoning 4,000,realized outcome 2,000,alternatives 最多十项,每项 300)。过长的备选项会在空格处或两个 CJK 字符之间截断,并以 `…` 结尾,这样不会出现读起来像文件名的半截名称。一条陈述最长可达约 12,000 个字符。`memory.for_file` 会完整显示它,若超出该块的上限,则只给出它的名称;搜索嵌入的是它的摘录,即存储的前 1,200 个字符(去掉 ` (#)` 后缀),因此摘录以 scenario 开头;更长的陈述还会存为分块,搜索也会读取这些分块。
+
+`stage` 为 `decided`(默认)或 `proposed`:后者表示已提出但尚未选定或实施的方案,例如提案、计划或行动项。提议决策的陈述写作 `Proposed because .`,其行带有 `decision:proposed` 标签,因此编辑前的块和搜索都会把它当作提案呈现。被提议的禁令保留其 `constraint` 标签:编辑前的块仍会把它排在最前,措辞为提案,没有给出理由时写作 `Proposed .`。
+
+stage 保存在行上,而不是记录上:`context.pack` 把提议的决策列为 `→ proposed: `,`decision.precedents` 和 `decision.chain` 返回它的 `stage`,该值读自持有该记录的行上的标签(已记录结果的决策读作 decided)。
+
+`decision.outcome` 会去掉 stage,因为记录结果意味着该决策已被执行:此时陈述写作 `Decided … Realized: …`。用 `stage: "decided"` 再次记录该决策,同样会去掉它。`decision.record` 会忽略调用方自带的 `decision:proposed` 标签;`memory.update` 会替换行的标签,对这个标签的编辑与其他标签无异,读取方也会跟随它。
+
+`loom decisions extract` 运行时,会保留文档仍然陈述的那些行的 stage([从文档中提取决策](#extract-decisions-from-a-document),**Stage**),因此后来被标记为已接受的提案,其行仍保持 proposed。要把这样的决策标记为 decided,可以:给它发送 `--dry-run` 报告的正文(它带有提取器的身份,因此会替换该行)并设 `stage: "decided"`;用 `decision.outcome` 记录它的结果;或者删除该文档中未固定、未认证的已提取行,再重新提取,这样会重新读取每一行的 stage。
+
+- **检查**:黑名单读取每个存储字段的完整内容;敏感度标签和属性标签读取存储的 category、scenario、outcome、reasoning、alternatives 和 realized outcome(不包括 `decision_maker` 或 `run_id`,行中并不保存这两项)。
+- **文件**:`files` 的设置方式与 `memory.set` 相同;未设置时,文件从存储的字段中检测,绝不从 realized outcome 中检测。在编辑它所指名的文件之前,`memory.for_file` 会原样提供该决策,已固定时标注 `(pinned)`,被打上 `source-changed` 标签后标注 `(source changed)`([该块如何呈现](../concepts/memory.md#tags-entities-and-files))。
+- **来源**:`source_resource_id` 和 `source_class` 设置对应的列,方式与 `memory.set` 相同;`source_resource_id` 引用该决策所出自的文档。
+- **结果**:`decision.outcome` 保留该行的文件、来源、声明的类别和调用方的标签。它会去掉 `decision:proposed` 标签,重新设置 `decision` 标签,并重新计算服务器的 `sensitivity:` 和 `attribute:` 标签。
+
+决策由它的键标识,而不是由它的文本标识。写入时的冲突检查绝不会把一条决策合并进另一条决策的行,不会把它归为某条决策的重复项,不会让某条决策替换它,也不会让已固定的决策拒绝它,无论两者读起来多么相似;不同键下的相近决策会被标记为冲突。为某个用户记录的决策,只与该用户的决策比对,任何指明了用户的写入都是如此([写入如何被裁定](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/conflicts-and-refusal.md#how-a-write-is-judged))。冲突解析器之后可能会撤下一对相近记录中它判定为另一条的更新版本的那一条;这会被记录为 `memory.auto_supersede`,`memory.restore` 可以撤销它。
+
+`category` 加 `scenario` 标识一条决策。对同一 scenario 再次作出决策,会取代先前的记录(`superseded_prior=true`);历史会保留它。键的推导方式与记录的标识键相同(见[类型化记录](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/writing.md#typed-records)):任何文字的 scenario 都可以记录,而没有字母或数字(仅有标点、符号或标记)的 category 或 scenario 会被拒绝,返回 400 `MISSING_IDENTITY_FIELD`。逐字重复记录的决策会写入相同的陈述,`memory.set` 将其视为重述:它会强化该行,已固定的决策也接受它。重述比较的是陈述的字节,因此以另一种陈述形式存储的行,会被相同的字段修订而不是重述,无论这些字段来自 `decision.record`,还是同样会重建陈述的 `decision.outcome`。值被锁定的行会以 423 `LOCKED` 拒绝这两种写入,直到锁结束或被释放;已认证的行接受写入,其认证会显示为过期,直到 `memory.verify` 再次绑定;已固定的行会拒绝 `decision.record`,直到取消固定,而固定只能通过 `memory.pin` 重新设置,`decision.outcome` 则保留固定状态。当已固定决策的写入者作出不同的决定时,调用会被拒绝,返回 409 `PINNED_CONFLICT`,且不写入任何内容;管理员需先用 `memory.unpin` 取消固定。固定只保护其写入者的行:另一个身份对同一 scenario 的决策仍会取代该记录。新记录只保存新决策所陈述的内容:它省略的字段,以及先前的 `realized_outcome` 或 `success`,都不会沿用,无论是由 `decision.record` 还是 `memory.record.write` 写入。不带 `success` 的 `decision.outcome` 会保留记录原有的结论。
+
+记录保存的是其最后一位写入者的文本,即记录它的 agent、用户和会话,因此删除该写入者的决策行会使该记录失效;已过期的行仍算作有效。同一键下另一个身份的行,在记录层已被取代,不会让该记录继续存在。
+
+- **使记录失效**:对写入者的决策行执行 `memory.delete` 或 `memory.delete_version`,包括通过 `memory.delete` 删除的 `memory.move`(`keep_redirect=false`)和 `memory.apply`(`action="delete"`);`conflicts.resolve` 和 `memory.dedup_resolve` 中被它们标记为墓碑的一方;带 `sweep=true` 的 `blacklist.add` 和 `blacklist.sweep`。`decision.chain`、`decision.precedents` 和 `decision.outcome` 不再提供它,`memory.record.history` 会显示最后一个版本,其 `status="tombstoned"`。两个并发的失效操作可能各自写入一个墓碑版本,因此历史中可能列出两次墓碑。
+- **失效之后**:`memory.restore`,或越过该删除的 `namespace.rollback`,会恢复该行但不会恢复记录;请再次调用 `decision.record`。以 `keep_redirect=false` 移动的行不再是决策:它的新键下没有记录,用相同的 category 和 scenario 调用 `decision.record` 会在其推导出的键下重新记录它。
+- **保持记录有效**:删除另一个身份的行;以其他方式把行标记为墓碑的 `memory.clear` 和 `namespace.rollback`;`memory.move` 且 `keep_redirect=true`,其重定向行在旧键下仍算作写入者的有效行;以写入者身份进行、用另一个 `memory_type` 改写该键的 `memory.set`;过期清扫对已过期写入者行的墓碑标记。
+- **没有决策行的记录**:对 `decision` schema 的 `memory.record.write` 只写入记录本身。`decision.chain` 会提供它,`decision.outcome` 对它返回 not-found;请用 `decision.record` 记录决策。
+- **`decision.outcome`**:以记录的写入者身份写入,保留已固定行的固定状态,当写入者的行不是有效行时返回 not-found。它对行的写入以它所读取的那一行为条件:调用期间决策发生变化,或另一个条件写入占用了该键时,返回 409 `PRECONDITION_FAILED`;该键的租约存储不可达时返回 503;请重新调用。保持决策文本不变的重新记录不会改变行的值,因此 outcome 还会在写行之前以及写记录之前,再次检查写入者的记录,若它已变动则返回同样的 409;若在第二次检查时才发现,行会保留该 outcome 的陈述和 outcome 标签,直到再次发起调用,而那次调用会被视为对该行的重述。条件针对的是行的值,而不是它的固定状态:在 outcome 读取与写入之间发生的 `memory.unpin` 会被撤销,因为 outcome 会把该行重新写为已固定。
+
+| 操作 | 角色 | 作用 |
+| --------------------- | ------ | -------------------------------------------------------------------------------------------------- |
+| `decision.record` | writer | 记录一条决策及其因果边。 |
+| `decision.precedents` | viewer | 对过往决策做语义搜索(最多 25 条),可按 `category` 或 `with_outcome_only` 筛选。 |
+| `decision.chain` | viewer | 沿因果边按 `upstream`、`downstream` 或 `both` 遍历,最多 4 跳。 |
+| `decision.outcome` | writer | 记录 `realized_outcome` 和 `success`;为作出决策的运行所依赖的记忆加分或扣分。 |
+
+请传入作出该决策时所用的 `run_id`:`decision.outcome` 通过该运行的 `memories_used` 找到要加分的记忆([运行](https://github.com/ClickHouse/loom/blob/main/docs/features/runs.md))。
+
+```python
+rec = await agent.decision.record(
+ category="storage",
+ scenario="retention for raw transcripts in the support namespace",
+ reasoning="Replay needs 30 days; legal hold is handled by export, not by retention.",
+ outcome="keep transcripts 30 days",
+ alternatives=["keep forever", "7 days"],
+ confidence=0.8,
+ influenced_by=["policy/legal/hold"],
+)
+prior = await agent.decision.precedents("how long do we keep transcripts?", category="storage")
+await agent.decision.outcome(rec["memory_key"], "no replay gaps in the quarter", success=True)
+```
+
+
+
+### 从文档中提取决策
+
+`loom decisions extract` 读取一份[知识](https://github.com/ClickHouse/loom/blob/main/docs/features/knowledge.md)文档,并记录其中陈述的决策。它在进程内运行,不需要令牌,因此是运维人员使用的命令;它会针对文档各节的每个窗口调用已配置的 LLM:一次读取(重新读取的窗口为两次,见下文)和一次支持性检查,当某条已存储的决策看起来已经消失时,每个窗口再多做一次检查,试运行(dry run)中也是如此。它的模型调用不受命名空间成本上限的限制。如果某次模型调用被组织拦下(其模型调用被关闭,或被推理网关拒绝或延后),无论是用于模型读取,还是写入所需的嵌入,运行都会停止:不再写入任何内容,不撤下任何内容,并以 1 退出。文档源同步会对它写入的每份文档运行同样的提取,并限制在命名空间成本上限的一个份额之内([挖掘决策](https://github.com/ClickHouse/loom/blob/main/docs/features/knowledge.md#mining-decisions))。
+
+```bash
+loom decisions extract --org O --namespace NS --source-uri URI # dry run: prints what it would write
+loom decisions extract --org O --namespace NS --source-uri URI --apply # writes
+loom decisions extract --org O --namespace NS --source-uri URI --repo OWNER/NAME --into source --apply
+```
+
+- **仓库**:默认情况下,文档的命名空间就是查找其代码名称、写入其决策的位置,这适用于添加到某个仓库代码命名空间中的文档。位于个人或团队命名空间中的文档用 `--repo OWNER/NAME`(或远程 URL)指定仓库,按 owner/name 匹配,与 `code.repos` 匹配检出副本的远程的方式相同(不会沿 fork 的远程追溯到上游:请指定上游);文档中的名称随后在该仓库的主干代码命名空间中查找,由 `--into` 选择行写入的位置:
+ - `--into source`(文档位于代码命名空间之外时的默认值):写入文档的命名空间,每一行带有 `repo:` 标签,这是编码插件发送给 `memory.for_file` 的标签,因此当会话自身的命名空间(插件的 `namespace`)就是该文档的命名空间时,会话在编辑文档中提到的文件之前就能拿到这一行。编辑前的钩子只读取该命名空间和仓库的主干,所以,若团队共享文档的读者在各自的命名空间中工作,应使用 `--into repo` 写入。位于主干本身的文档得到的行不带标签,由每个编辑者在主干中读取。
+ - `--into repo`(文档位于代码命名空间时的默认值):写入仓库的主干代码命名空间,该仓库的每个读者在编辑之前都能拿到这一行。`source_resource_id` 仍然引用文档所在的命名空间中的文档;不存在按文档的访问控制,因此无权读取文档命名空间的仓库读者能看到这一行的决策,但无法打开它所引用的文档。这些行属于主干:清除文档的命名空间不会删除它们,需要在主干中用 `memory.delete` 删除。
+ - **标签**:对于主干之外的文档,在 `--into source` 下,提取器的行若被本次运行原样保留(已固定、已证明或已记录结果,仍被文档陈述或未被判定,或者因仍被陈述或未被判定而被淘汰步骤保留),以及被它标记为 `source-changed` 的行,会通过仅修改标签的写入获得 `repo:` 标签;其他写入者的行不会获得。
+ - **访问**:运行会读取文档的命名空间和仓库的命名空间,并写入行所去的位置。绑定了认证上下文时,它会逐项检查(viewer、viewer 以及 writer,试运行则只需 viewer),并在任何模型调用之前拒绝;CLI 不带认证上下文运行,以操作员身份执行。
+ - **早先运行留下的行**:协调和淘汰步骤读取的每一条记忆行都在行所写入的命名空间中,因此,当本文档的行位于运行可能写入的另一个命名空间(文档的命名空间、所指定仓库的主干,或者对于分支代码命名空间中的文档,其仓库的主干),或带有另一个仓库的 `repo:` 标签(对于不带 `--repo` 的运行,或所指仓库没有远程的运行,则任何此类标签都算)时,运行会在任何模型调用之前拒绝:继续下去会让文档的决策分散在两处,或关联到错误的仓库。当调用者可以读取所关联的仓库时,拒绝信息会以 `owner/name` 指出它;无权读取该另一命名空间的调用者会被拒绝。运行看不到两种情况:一是 `--into repo` 的运行把行写入了并非文档所在代码命名空间所属的仓库(对于代码命名空间之外的文档,则是任何仓库),之后的运行去掉了 `--repo` 或指定了另一个仓库,所以请再次使用相同的 `--repo`;二是同一文档上同时有两次使用不同 `--into` 的运行,它们都可能发现另一个命名空间为空。
+ - **退出码 1**:除上述拒绝之外,以下情况会在任何模型调用之前退出:
+ - 仓库未在组织中配置,或调用者无权读取(两种情况同一个回答);
+ - 仓库没有可用于给行打标签的远程,且处于 `--into source` 下、文档位于主干之外;
+ - 有 `--into` 而没有 `--repo`;
+ - 文档位于另一个仓库的代码命名空间中,却使用 `--into source`(其行会关联到所指定仓库的代码,却在另一个仓库中被读取);
+ - 无法读取从控制台添加的仓库。
+
+- **窗口**:文档中当前嵌入模型下的有效分块,按章节分组,每次调用最多 `--window-chars`(默认为 `LOOM_MEMORY_DECISION_EXTRACT_WINDOW_CHARS`,24,000)个字符:能放下的文档会被整体读取,因此文档在与结论不同的章节中给出的理由(问题陈述、测量结果、缺失情形列表)会一并被读到。默认值使一份内容密集的设计文档的回复(token 数与窗口大致相当)保持在读取的输出上限(`LOOM_LLM_MAX_TOKENS_OVERRIDES` 中的 `decision_extract`)之内;在上限处被截断的回复会丢失其窗口,被丢弃的那一行会提示降低 `--window-chars`(同步读取该设置)或提高上限。按另一个嵌入模型分块的文档没有分块:命令会提示先运行 `loom rechunk`,并且不写入任何内容。`--source-uri` 没有对应的有效文档时退出码为 1,且不写入任何内容。提示词会列出提取器已为该文档保存的最多 `LOOM_MEMORY_DECISION_EXTRACT_KNOWN_MAX`(默认 30)条决策的类别和场景,并要求模型在文本仍记录某个决策时复用它们,使重新运行读到相同的键;旧的结果不会展示,因此变化后的结果按文本现在的内容读取。
+- **读取**:对于每个决策,模型用自己简洁的措辞写出其结果、文档给出的理由以及文档否决的选项(附所给理由,或没有理由),并且这些论断各自引用文档中一到三条简短引文(`server/memory/domain/decision_extract.py`,`SYSTEM`)。文档陈述了决策却没有给出理由时,就写成没有理由。新设计所取代的当前或以前的方案,算作新设计被否决的选项;测量、回顾、议程或基准测试结果不算决策。当回复中没有任何决策,且窗口的文本不止是一个图注(去掉图片和链接标记后超过 80 个字符)时,会用同一提示词再读一次该窗口,报告为 `read again`。文档有标题时,窗口的文本以一行 `[document: ]` 开头(取标题的前 200 个字符)。
+- **依据核对**:每条引文必须出现在模型读取的文本中:连续空白视为一个空格,忽略字母大小写,并且在两个词之间最多可跨过三行标签行读取,就像模型复制被幻灯片或图表导出拆开的句子那样(`find_span`)。找到的引文会保留为文档自己的原话,合并为一行,其中的标签行被省略,短于 12 个字符的引文没有依据。一条理由或被否决的选项,若其所有引文都找不到,就会被省略(`reason '...' left out: none of its quotes is in the document text`);一个决策,若其结果的所有引文都找不到,就会被丢弃(`none of the outcome's quotes is in the document text`)。结果引文所在章节的标题路径中,任何一级标题含有 `recap`、`summary` 或 `background` 这样的词时,该引文不能用来定位决策;若决策没有其他结果引文,就会被丢弃(`the quote is in a recap, summary or background section`),而理由可以依据这类章节的文本。
+- **支持核对**:对同一窗口进行第二次调用,连同引文一起读取每条保留下来的论断,只有当引文在文档上下文中陈述或直接蕴含该论断时才予以支持;概括和合并引文是可以的,增加理由、原因、数字、名称或被否决的选项则不行。未获支持的论断会被省略(`... left out: the support check found it not stated`),结果未获支持的决策会被丢弃。它不判断决策是已经决定还是仅仅被提议:那是读取阶段的事。同一次调用还会对照文本读取提取器为该文档保存的每个决策(至多到已知决策上限):是否仍被陈述,以及哪个候选重述了它。只要有任一窗口的核对认为某个已保存的决策仍被陈述,它就算被陈述;只有每个窗口都认为它已不再被陈述,才判定为不再被陈述,随后会在没有候选的情况下再读一次,且仅当每个窗口的第二次核对都同意时,才算不再被陈述。其他任何情况(核对失败或返回无法读取的结果,或回复遗漏了该决策)都不产生结论,丢失的核对也会使其窗口的候选一并丢失。
+- **仅含图片的章节**:章节自身的文本没有文字(只有标题,或标题下只有图片),或者含有一张图片以及不超过 80 个字符的其他文本(图注),则不会发送给模型,并得到一行 `image-only, rationale not extracted`;仅有标题而其下是子章节的不算。第一个标题之前的文本,或没有任何标题的文档,在含有图片且至多只有图注时同样被跳过,报告为 `(untitled)`。图片包括 Markdown 图片(行内的,或通过引用的,如 `![diagram][fig1]`;形如 `![spill flow]` 的简写引用不会被读取,因为它看起来像 `vec![0; n]` 这样的宏)、HTML 图片,以及 `[image]`、`[Image 3]` 或 `[image: ...]` 这样的占位符。图注的字符数不计入 HTML 标签、链接目标、引用标签、包裹图片的链接留下的空方括号以及裸 URL,因此包在链接中的徽章不会增加字数;标签是单行内的小写名称,所以 `x < 10k` 和 `Option` 仍算文本。代码中的图片标记(代码片段或代码块中的 `` 或 ` `)算作文本。没有文字的分块同样不会发送。
+- **每个章节的重复与上限**:键相同,或结果(忽略空白和字母大小写)与本次运行中较早的候选相同的候选会被丢弃,不符合 `decision.record` 的候选,以及超出 `--max-per-section`(默认 3)的候选(按其第一条结果引文所在的章节计)也会被丢弃。
+- **阶段**:模型把每个候选标记为 `decided` 或 `proposed`;除明确的 `decided` 之外的任何情况(提议、RFC、计划、未来工作、后续事项,或没有回答)都以 `stage: "proposed"` 记录,因为把提议当作已做出的选择提供给 agent,比把已做出的选择当作提议提供更具误导性。文本仍然陈述的已保存决策保持其阶段,当文档读出的阶段与之不同时,运行的说明会指出文档读出的阶段,但已记录结果的行除外,无论文档怎么写,它都按已决定读取。已固定或已证明的行不会被运行重新记录,因此其阶段只能手动更改。
+- **写入**:通过 `decision.record`,以 agent `loom-decisions`(用户和会话为 `-`)的身份写入,理由以 `; ` 连接作为推理(没有理由的决策则以结果本身作为推理,陈述中读作没有给出理由),每个被否决的选项写成 ` — rejected: `,或只写选项本身,置信度为 0.5,`source_class="derived"`,`source_resource_id` 为 `knowledge:/#`,标签为 `source-kind:design_doc`,禁令或不变式加上 `constraint`,对于位于仓库主干之外的文档,在 `--into source` 下再加上 `repo:`。行的 `actor` 是 `process:cli:decisions`。每次 `decision.record`,以及每次删除一行的 `memory.delete_version`,都会留下传输层为该操作写入的审计行,其 actor 为 `process:cli:decisions`;写标签的 `memory.update_by_id` 不声明审计,与通过 HTTP 调用时相同。
+- **文件**:文档文本中每个用反引号括起的或限定的名称,以及每个裸类名,都用 `code.symbol` 在文档的命名空间中查找,使用 `--repo` 时则在仓库的主干中查找;恰好有一个定义文件时(类优先于其构造函数)会放入 `files`,有多个或没有则不添加。只有测试或 Markdown 页面定义的名称不建立关联:决策约束的是代码,编辑测试或页面时不应显示它。试运行会输出 `only a test or a page defines it`,并把该名称列为未解析(`only tests or pages`),交由人工添加代码文件;若它是 snake_case 且有页面记录了它,则列为设置项;只有测试定义的 snake_case 名称是辅助函数,不会被列出。哪些路径算测试由 `server/memory/domain/decision_extract.py` 中的 `governs` 决定:常见的测试、mock 和端到端布局;它漏掉的路径会保留其关联。被引用的引文中写出的仓库路径(`src/Storages/MergeTreeData.cpp`)也会被加入,就像 `memory.set` 检测到的那样。当某个名称无法读取代码索引时,已记录的决策保留其行已有的文件,新决策则以已解析出的文件写入。拉取请求编号和设置名称在试运行中作为未解析项输出,交由人工添加;用反引号括起的 snake_case 名称会先被查找,若索引中没有定义它,则报告为设置项。在多个文件中定义的名称会作为未解析项输出,交由人工选择文件。
+- **协调**:只有当支持核对发现该键已保存的决策不再被陈述时,才算文档另有说法;仅凭模型的措辞不算变化。仍被陈述的决策只为更新其行字段而重新记录,使用其已保存的措辞。行在其当前形式下已固定或已证明(`memory.verify`)时,不会被重新提取。即使修订为文档中的决策增加了理由或被否决的选项,仍被陈述的决策也保留其已保存的措辞:核对问的是文本是否仍然说着该行所说的内容,而不是它是否说得更多。按该键的活动记录所属的行处理:
+ - **提取器自己的、未固定也未证明、来自本文档的行**:仍被陈述,且 `files`、`source_resource_id`、`constraint` 标签和 `repo:` 标签都相同:不写入。不再被陈述:按文本现在的内容重新记录(原记录被取代,历史保留它);仍被陈述但其他行字段不同(代码被索引后得以解析的文件、重命名的标题、首次使用 `--repo` 的运行):以其已保存的措辞重新记录。
+ - **没有结论**(超出已知决策上限的已保存行、回复遗漏的行或回复中既非真也非假的行,或其核对丢失的行):已固定、已证明或已被采用的行保持原样;其他行在运行给出其键时重新记录,措辞不同时按文本现在的内容,仅文件、来源或标签变化时则以其已保存的措辞和阶段。
+ - **提取器自己的、已固定或已证明、引用本文档的行**:不再被陈述:不写入;会输出完整的 `decision.record` 正文及该行的 agent、用户和会话,并且除非该行已带有 `source-changed` 标签,否则给它加上该标签。要接受该正文,维护者需用 `memory.unpin` 取消固定已固定的行(对已固定的写入者行执行 `decision.record` 会返回 409 `PINNED_CONFLICT`),然后发送它;已证明的行可直接接受该正文,其证明随后显示为过期,直到 `memory.verify` 再次绑定它。
+ - **其他写入者的行,或来自其他文档的行**:既不修订也不打标签;会输出其正文。支持核对只读取提取器自己的行。
+ - **已记录结果的行**(`decision.outcome`):永不重新记录,因为 `decision.record` 会在没有结果的情况下重建它;不再被陈述的此类行会被打上 `source-changed` 标签,与已固定或已证明的行一样。
+ - **重述**:当候选的键是新的,或是某个未被发现已被陈述的已保存决策的键时,被支持核对指为重述某个并未发现已消失的已保存决策的候选不会被写入(`restates , not found gone`):已保存的行及其阶段保持不变,候选的键下的行在发现已消失时被淘汰,没有结论时则保留其已保存的措辞。这一步先于对不再被陈述的行和没有结论的行的重新记录。
+ - **该键下没有记录**:在与候选最接近的 `LOOM_MEMORY_DECISION_EXTRACT_RESTATEMENT_TOP_K`(默认 20)个决策键(仅按余弦相似度)中,若有另一个键下已固定或已证明的决策,其读起来与候选相同,且相似度达到或超过该命名空间的冲突阈值,则跳过该候选:`already recorded by under `。查询内容是候选的陈述,其中不含类别,因此归在另一类别下的已固定或已证明决策也会计入。否则记录该决策。获取上限为 500 行,所以较大的值或 `LOOM_MEMORY_SEARCH_PER_KEY_CAP=0` 可能使读取的键更少。
+- **标签写入**:通过行的 `memory_id` 调用 `memory.update_by_id`,只写标签,并以所读取的值为条件:若该值此后已被 `decision.outcome` 或重新记录改变,则不予改动,并作为竞态报告。它是由提取器写出的新版本:该行的固定(pin)、值和证明(attestation)保持不变(值的哈希不变,因此证明仍然绑定该值),其操作者和时间则改为本次写入,所以编辑前的那一行显示为 `by cli:decisions, just now`。它是一次完整的修订,与任何 `memory.update_by_id` 一样:该行会被重新嵌入并接受冲突检查,因此存在相近同类的决策会被标记为 `conflicted`(除非 `include_conflicted=false`,否则 `memory.for_file` 仍会列出它),而过期的冲突标记会被清除。
+- **竞态**:`decision.record` 不带前置条件,因此在本次运行读取与重新记录之间写入的 `decision.outcome` 会连同记录的其余部分一起被替换;标签写入的前置条件只覆盖值,不覆盖这段间隔内仅修改标签的变更。
+- **撤销**:一条未固定、未证明、引用该文档且不再被陈述(见上文)的 `loom-decisions` 行,会用 `memory.delete_version` 删除,同时撤销其记录;已固定或已证明的行,或其结果由 `decision.outcome` 记录过的行,则改为标记 `source-changed`。若本次运行已在另一个键下记录了取代它的决策,则报告为被该键取代。仍被陈述的行保持不变,无论本次运行是否再次输出它;没有判定结果的行也保持不变(超出已知决策上限的行,或被某次检查遗漏或丢失的行)。判定依据的是提取器自己的记录:其有效记录由其他身份写入的键不会被改动。一条决策的陈述若跨越长文档的两个窗口,可能在每个窗口中都被判为不再被陈述。
+- **引用文档**:当一行的 `source_resource_id` 以 `knowledge:/#` 开头时,即视为引用该文档,其中的命名空间是文档所在的命名空间(而非该行所在的命名空间),因此含有 `#` 的标题(`C# bindings`)不会造成妨碍;但若该命名空间中曾摄取过以 `#` 为 URI 且该行同样以其开头的文档,则不然:一旦该文档存在,`doc#v2#Intro` 即引用 `doc#v2`。
+- **清除 `source-changed`**:当本次运行在带标签的行的键下输出候选,且支持检查发现该行再次被陈述时,只要该行引用本文档,无论是否已固定,运行都会去掉该标签。撤销步骤绝不会去掉它。手动时,维护者可对该行的 `memory_id` 调用 `memory.update_by_id`,将 `tags` 去掉 `source-changed`;或重新记录该决策(在 `memory.unpin` 之后),或将其删除。
+- **拒绝与竞态**:服务器拒绝的写入(被列入黑名单的决策、运行期间被固定的行、忙碌的键、存储超时)会连同其代码一起报告;被嵌入提供方的错误中止的写入(`memory.set` 和 `memory.search` 在进程内嵌入)会连同该错误的名称一起报告;若写入发现其行自本次运行读取后已被删除或改写,或某个键的行在本次运行的两次读取之间被删除,则如实报告,这类竞态由下一次运行解决。无论哪种情况,运行都会继续处理下一个候选和撤销步骤。
+- **限制**:`--max-per-section` 至少为 1,`--window-chars` 至少为 500;更小的值会被拒绝。在模型 token 上限处被截断的回复,会连同其触及的上限(`decision_extract` 为 12000,`decision_support` 为 8000,除非 `LOOM_LLM_MAX_TOKENS_OVERRIDES` 另行设置)一起报告,并建议调低其中一个标志或调高该条目;某个窗口的读取、空回复后的第二次读取,或其支持检查若失败(提供方错误、超时),只会丢失该窗口。
+- **模型与退出码**:当运行需要用 fake 模型读取文档时,会在任何模型调用之前拒绝运行,因为该模型的决策按构造即可通过依据检查:这包括已配置需要密钥的提供方(`LOOM_LLM_PROVIDER=openai` 或 `anthropic`)但未设置 API 密钥,或完全未配置提供方。显式设置 `LOOM_LLM_PROVIDER=fake` 则会有意在其上运行。否则,由 fake 模型应答的窗口(备用模型 `LOOM_LLM_FALLBACK_MODEL` 且无密钥)会被当作未读取而丢弃。若每个窗口的模型调用都失败或返回无法读取的内容,或没有应答且再次读取时失败,则运行什么也不读取,也不撤销任何内容。当命令无法在该文档上运行时(没有文档、没有分块、没有可用的模型、触发上文 **Repository** 下的某项拒绝、在任何模型调用之前提取器自己的行无法读取、没有读取任何窗口),退出码为 1;当某次写入或所需的读取被拒绝或失败时(试运行的读取也计入;在其他窗口已被读取的情况下,模型无法给出可读应答的窗口或支持检查也计入),退出码为 2;其余情况为 0;竞态不改变退出码。
+
+引文用于佐证结论,不会被存储:记录以模型自己的措辞保存决策,并引用文档的相应章节。提取出的行按原样提供,无需任何人审核。固定是可选的:若要使某行不被重新提取改动,可用 `memory.get` 读取其身份并在其下调用 `memory.pin`,或用 `memory.verify` 证明其当前值;此后若文档不再陈述它,运行会将该行标记为 `source-changed`,而不是修订或删除它。编辑之前,`memory.for_file` 会将已固定的提取行标为 `(pinned)`,将标记为 `source-changed` 的行标为 `(source changed)`,对每一条决策行都是如此([决策](#decisions))。提取到仓库主干代码命名空间中的行,也会像在那里记录的每条决策一样,从该仓库的检出处通过 `loom_search` 到达([统一搜索](https://github.com/ClickHouse/loom/blob/main/docs/features/unified-search.md#reading-the-memory-section));该界面不标示固定状态,也不标示其来源是否已变更,因此提取出的行在那里与任何决策一样显示。
+
+
+
+## 历史策略
+
+角色规定谁可以调用什么。历史策略则在此基础上,针对调用者自身在 agent 事件轨迹(`loom.agent_events`)中的近期历史增加规则:例如“只有在读取之后”“每小时写入不超过 200 次”。策略只能收回权限;未通过角色检查的调用不会到达策略关卡。
+
+一条规则由 `effect` + `actions` + `condition` 组成:
+
+- `effect`:`forbid` 在条件成立时拒绝;`require` 在条件不成立时拒绝。
+- `actions`:操作名或通配符(`memory.delete`、`memory.*`)。
+- `condition`:由只涉及过去的叶子节点组成的树,用 `all`、`any` 和 `not` 组合。
+
+| 叶子节点 | 成立条件 |
+| ---------------- | ---------------------------------------------------------------------------------------- |
+| `formerly` | 窗口内发生过匹配的事件。 |
+| `count_within` | 匹配事件的数量与 `value` 的比较(`gt`、`gte`、`lt`、`lte`、`eq`)成立。 |
+| `not_since` | 窗口内发生过 `anchor` 事件,并且自最近一次 anchor 以来,指定的事件没有再发生。 |
+| `breadth_within` | 主体看到过的不同键的数量,与 `value` 或命名空间中有效行数的某个 `fraction` 的比较成立。 |
+
+每个叶子节点都接受 `within`(`30s`、`15m`、`1h`、`7d`;上限由 `LOOM_POLICY_MAX_WINDOW_SECONDS` 决定)、`operation` 和 `key`:`agent`(默认)、`session` 或 `user`(`breadth_within` 默认为 `actor`,即经过验证的令牌主体)。编译器会固定调用者,因此规则永远不会读取其他主体的事件。`args_equal` 将事件参数与字面量或当前调用的 `$args.` 进行比较。
+
+```python
+await agent.policy.set(
+ "read-before-delete",
+ effect="require",
+ actions=["memory.delete"],
+ condition={
+ "op": "formerly",
+ "within": "1h",
+ "operation": "memory.get",
+ "args_equal": {"memory_key": "$args.memory_key"},
+ },
+ description="An agent deletes only what it has just looked at.",
+)
+verdict = await agent.policy.check(
+ operation="memory.delete", agent="cleanup-bot", args={"memory_key": "notes/old"}
+)
+# verdict: {decision, would_enforce, mode, write_shaped, determining_rules, errors, rules, latency_ms}
+```
+
+
+
+### 模式
+
+`LOOM_POLICY_MODE` 设置部署的模式:
+
+| 模式 | 效果 |
+| --------------- | --------------------------------------------------------------------------------- |
+| `off`(默认) | 关卡不读取也不写入任何内容。 |
+| `shadow` | 规则会运行,每个决策都追加到 `loom.policy_decisions`;不会阻止任何调用。 |
+| `enforce` | 命中拒绝规则时返回 403 `POLICY_FORBIDDEN`,并附上作出该决定的规则及各叶子节点的值。 |
+
+规则自身的 `mode`(`inherit`、`shadow`、`enforce`)会覆盖部署的模式,但部署为 `off` 时除外。将规则切换到 enforce 是所有者的操作,应在查看 `policy.decisions` 之后进行。
+
+在 `enforce` 模式下,无法求值的规则会拒绝写入类调用(writer 角色及以上),而放行读取调用,并报告错误。该关卡从不作用于 `policy.*` 或 `ops.*`,因此运维人员始终可以修复规则。扩大 agent 权限范围的变更还会写入一条 `policy.widened` 审计记录。
+
+| 操作 | 角色 | 作用 |
+| ------------------ | ------ | ------------------------------------------------------------ |
+| `policy.set` | admin | 创建或替换规则;返回 `leaf_count` 以及是否放宽了权限。 |
+| `policy.delete` | admin | 删除规则。 |
+| `policy.list` | viewer | 命名空间的规则以及部署的模式。 |
+| `policy.check` | viewer | 针对已存储的规则或你传入的 `rules` 对一次调用进行试运行。 |
+| `policy.decisions` | viewer | 读取决策账本,可按 `allow` / `deny` 过滤。 |
+
+控制台的 **Policies** 页面(管理员抽屉)用于管理规则、试运行调用和读取账本。相关设置:`LOOM_POLICY_MODE`、`LOOM_POLICY_MAX_WINDOW_SECONDS`(默认 86,400)和 `LOOM_POLICY_CACHE_TTL_SECONDS`(默认 30;其他副本会在该时间内看到规则变更),详见[配置:认证](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#auth)。
+
+
+
+## 限制
+
+- 认领是排他的,但与具体工作并不构成事务。完成任务和写入结果是两次调用,请确保结果写入是幂等的。
+- `decision.chain` 最多追溯 4 跳;`decision.precedents` 最多返回 25 条。
+- 策略评估只看过去:当前调用尚未进入跟踪记录,因此见证事件总是更早发生的事件。
+
+
+
+## 相关内容
+
+- [运行](https://github.com/ClickHouse/loom/blob/main/docs/features/runs.md):决策计入的运行账本。
+- [命名空间与共享](https://github.com/ClickHouse/loom/blob/main/docs/features/namespaces-and-sharing.md):所有者命名空间与授权。
+- [令牌与授权](https://github.com/ClickHouse/loom/blob/main/docs/guides/tokens-and-grants.md):用于 `posters` 的服务账号主体。
+- [无头机器人](https://github.com/ClickHouse/loom/blob/main/docs/guides/headless-bots.md)。
+- [控制台](dashboard.md):任务看板与策略页面。
+- [安全架构](https://github.com/ClickHouse/loom/blob/main/docs/architecture/security.md):策略关卡所在的位置。
diff --git a/i18n/.pending/zh-CN/docs/operations/monitoring.md b/i18n/.pending/zh-CN/docs/operations/monitoring.md
new file mode 100644
index 0000000000..bc96474db9
--- /dev/null
+++ b/i18n/.pending/zh-CN/docs/operations/monitoring.md
@@ -0,0 +1,323 @@
+
+> 本页由机器从[英文原文](https://github.com/ClickHouse/loom/blob/main/docs/operations/monitoring.md)翻译,内容以英文原文为准。
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/operations/monitoring.md), which is authoritative.
+
+
+
+# 监控
+
+本页说明需要关注哪些内容。Loom 通过四个渠道报告自身状态:
+
+| 渠道 | 范围 |
+| ------------------------------- | ------------------------------------------ |
+| `/v1/health`、`loom doctor` | 单个进程 |
+| `ops.health` | 针对 ClickHouse 的更深入检查 |
+| OpenTelemetry 指标和 span | 写入同一个 ClickHouse,或发送到 OTLP |
+| `loom.agent_events` | 请求账本,每次操作一行 |
+
+指标名称和标签的完整列表见[遥测](https://github.com/ClickHouse/loom/blob/main/docs/features/observability/telemetry.md)。
+
+
+
+## 运行运维命令
+
+运维命令是 `loom` 子命令。请在容器内运行它们,容器中带有该部署的环境变量:
+
+```bash
+docker exec loom-server loom doctor # web container
+docker exec loom-workers loom code stats # workers container (split deployments)
+```
+
+在代码检出目录中,`pip install -e .` 会安装同一个 CLI;它从环境变量和 `.env` 中读取 `LOOM_*`。`loom --help` 会列出每个标志的说明,[CLI 参考](https://github.com/ClickHouse/loom/blob/main/docs/reference/cli.md)列出了全部命令。
+
+组织范围的视图(跨命名空间的成本、`ops.health`)需要 `ORG_ADMIN` 或 `PLATFORM_ADMIN`,而这只能通过 `LOOM_PLATFORM_ADMINS` 授予([部署](https://github.com/ClickHouse/loom/blob/main/docs/operations/deployment.md#required-environment))。整个部署范围的 `/v1/admin/*` 路由需要 `PLATFORM_ADMIN`;`token.mint`、`namespace.adopt` 和 `claim_release` 需要在其所作用的组织中拥有 `ORG_ADMIN`。命名空间的 `admin` 无法访问其中任何一项。
+
+
+
+## 健康检查
+
+```mermaid
+flowchart TD
+ H["/v1/health (any process, no token)"] -->|"HTTP 200/503"| L["liveness: ClickHouse answers SELECT 1"]
+ H -->|"body: status, problems, schema.pending"| R[readiness]
+ D["loom doctor (CLI)"] -->|"same problems list"| R
+ O["ops.health (ORG_ADMIN)"] --> X["ClickHouse parts, workers, stubs, contracts"]
+```
+
+
+
+### /v1/health 端点
+
+```bash
+curl -s http://localhost:7777/v1/health | jq '{status, version, ch_ok, build_commit, schema, problems}'
+curl -s 'http://localhost:7777/v1/health?include=workers' | jq '.workers_leader'
+```
+
+- **HTTP 状态码只取决于 ClickHouse:** `SELECT 1` 有响应时为 200,没有响应时为 503(`ch_error` 给出错误的类别,错误文本在服务器日志中)。可将其用作存活探针。这样,只读取状态码的探针(镜像的 healthcheck、负载均衡器)看到的是故障,而不是一个其响应体从未被解析的 200。
+- **`status`** 在 ClickHouse 不可用,或 `problems` 中存在严重级别为 `error` 的条目(`code_tier_failing` 除外,它涉及的是某个仓库的索引,而不是部署本身)时为 `degraded`;否则为 `ok`。就绪检查还应要求 `schema.pending` 为空(零停机双实例切换正是这样做的)。
+- **`problems`** 是 `{code, severity, message, fix, source}` 的列表,按严重程度由高到低排列。`loom doctor` 会打印同一份列表,控制台也会将其显示为横幅。`loom doctor` 会逐一列出 `code_tier_failing` 中的条目,最多五个(其余的由 `code.repos` 列出);平台管理员的令牌会列出每个未受限制的条目([层级失败时](https://github.com/ClickHouse/loom/blob/main/docs/operations/code-index-operations.md#when-a-tier-fails))。
+
+| 问题代码 | 严重级别 | 含义 |
+| ----------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `fake_embedder`, `fake_llm` | warn(设置 `LOOM_REQUIRE_REAL_PROVIDERS=true` 时为 error) | 配置了模拟的 provider |
+| `embedder_key_missing`, `llm_key_missing` | warn(同上) | 配置了真实的 provider 但缺少其密钥;进程使用模拟客户端运行 |
+| `embedding_dim_mismatch` | error | embedder 返回的维度与 `LOOM_EMBEDDING_DIM` 不一致 |
+| `coded_width_mismatch` | error | 编码向量列的宽度与写入所带的宽度不一致;这些写入会失败 |
+| `provider_failing:` | error | 对该 provider 的最近一次调用失败;下一次成功后清除 |
+| `model_configuration_refused` | error | 控制台保存的模型配置未通过网关检查,未被应用;所有数据平面请求都返回 503 `GATEWAY_REQUIRED`,在该配置被替换之前服务器不会就绪 |
+| `jwt_secret_empty` | error | 无法签发令牌 |
+| `dev_jwt_secret` | warn | 在启用认证的情况下使用了随代码提交的开发密钥 |
+| `config_drift` | error | 此进程的根密钥或 MUST_MATCH 设置与部署已发布的配置不一致:它不会就绪([运行 N 个副本](https://github.com/ClickHouse/loom/blob/main/docs/operations/replicas.md)) |
+| `revocation_not_loaded` | error | 启用了认证,但此进程从未读取过 `loom.revoked_tokens`:每个 bearer 都得到 503 |
+| `revocation_stale` | warn | 吊销快照早于 max(300 s, 10 × `LOOM_JWT_REVOCATION_CACHE_TTL_SECONDS`):此后被吊销的令牌在此处仍可通过认证 |
+| `revocation_too_stale` | error | 快照早于 `LOOM_JWT_REVOCATION_MAX_STALE_SECONDS`(600 s):在刷新完成之前,每个 bearer 都得到 503 |
+| `pending_migrations` | error | 数据库 schema 缺少此版本所需的迁移 |
+| `instance_label_missing` | warn | compose 文件之外的进程没有设置 `LOOM_INSTANCE_LABEL` |
+| `workers_lease_absent` | warn 或 info | warn:没有进程持有有效的 workers 租约(设置了 `LOOM_BACKGROUND_WORKERS=on` 的进程不获取租约,因此这种情况下会与其同时出现;在交接或冷启动期间,它可能短暂出现一次);info:此进程不运行 workers,且最近没有读取过租约 |
+| `workers_lease_unreachable` | warn | 此进程无法向 ClickHouse 查询 workers 租约;如果所有进程都这样报告,则没有任何进程在运行 workers |
+| `workers_lease_given_up` | warn | 此进程已释放 workers 租约并停止竞争(它正在排空,或其 workers 子进程持续启动失败);由另一个进程接管 |
+| `otel_erasure_index` | warn | ClickStack 指标表缺少擦除所需的索引([维护](https://github.com/ClickHouse/loom/blob/main/docs/operations/maintenance.md#clickstack-erasure-index)) |
+| `code_tier_failing` | warn(同时落后 `LOOM_CODE_TIER_FAILING_ERROR_LAG_COMMITS` 时为 error;fetch 层级保持 warn) | 某个代码索引层级连续 `LOOM_CODE_TIER_FAILING_WARN_PASSES` 轮失败,或持续失败达 `LOOM_CODE_TIER_FAILING_WARN_HOURS`;其 fix 会说明该错误类别需要什么([层级失败时](https://github.com/ClickHouse/loom/blob/main/docs/operations/code-index-operations.md#when-a-tier-fails))。它从不使 `status` 降级;`loom.health.problems` 像对待其他问题一样包含它,因此针对其中 `severity="error"` 的告警必须排除 `code="code_tier_failing"`。 |
+
+响应体中的其他字段:`providers`(各 provider 的调用状态)、`fake_embedding`、`fake_llm`、`providers_degraded`、`embedding_dim_mismatch`、`adaptive_thresholds`(由 embedder 推导出的相似度阈值,带有 `calibration_hash`,使用相同阈值的每个副本上该值相同;以及 `source`:`shared` 或此副本自身的 `probe`)、`ratelimit.backend`(`shared` 或 `per-process`),以及 `mode`(`ch`,配置后还包括 `langfuse` 和 `clickstack`)。`?include=` 接受 `workers`、`langfuse`、`otel`、`embedding_cache` 和 `llm_cache`;每个子系统各自单独报告,只有 ClickHouse 决定 HTTP 状态码。
+
+
+
+### loom doctor 命令
+
+`loom doctor` 运行其检查项(`python_version`、`settings_load`、`jwt_secret`、`clickhouse_reachable`、`otel_erasure_index`、`llm_provider`),然后将 `problems` 列表打印为 `problem:` 行。每项检查都会在退出前报告;只要有任何一行为 `FAIL`,退出码即为 1。`--json` 输出 `{ok, checks, problems}`。设置了 `LOOM_CELL` 且 ClickHouse 可达时,它还会运行[单元](https://github.com/ClickHouse/loom/blob/main/docs/architecture/cells.md)检查(`cell_state`、`cell_marker`、`cell_marker_everywhere`、`cell_triggers`),等级最高为 `WARN`;以及 `cell_deployment`,当部署检查被拒绝时为 `FAIL`(没有 `LOOM_PG_DSN`、存在另一个已记录的授权方或部署,或 ClickHouse 访问被拒绝)。启用代码智能且 ClickHouse 可达时,它还会读取失败的代码索引层级,并按该部署的运行时覆盖值评级;`problem:code_tier_failing` 最高为 `WARN`,因为它从不使 `status` 降级。
+
+`--client` 还会把本机作为编码 agent 客户端进行检查:hooks 将使用的服务器 URL 和令牌(可用 `--server-url`、`--token` 覆盖)、令牌是否被接受并能写入其命名空间、Claude Code 或 Codex 的接入配置,以及从未到达服务器的捕获任务。`loom report` 会打印 doctor 的输出,用于填写错误报告的 Environment 字段([提交 issue](https://github.com/ClickHouse/loom/blob/main/CONTRIBUTING.md#filing-an-issue))。
+
+
+
+### ops.health 操作
+
+`POST /v1/ops.health`(`ORG_ADMIN`)对 ClickHouse 运行更深入的检查。每项检查返回 `status`(`ok`、`warn` 或 `fail`)、`detail` 和 `repair`。探测失败时,`detail` 给出错误的类别(Loom 错误的 code 和 message),每个 worker 的 `last_error_kind` 给出错误的类;错误的文本在服务器日志和 `/v1/admin/workers.status` 中。当进程内的 supervisor 运行 workers 时,`/v1/health?include=workers` 以同样的方式裁剪其 worker 行:没有 `last_error`,只有结果数字和标志。
+
+| 检查项 | 检查对象 |
+| ------------------------ | --------------------------------------------------------------------- |
+| `clickhouse_parts` | 每个表的活动 part,以及最近 15 分钟内失败的合并 |
+| `workers` | 最近 worker 执行失败的情况 |
+| `embedding_stubs` | 仍在等待向量的记忆 embedding 行 |
+| `schema_contracts` | 高风险的表和列,与 schema dump 对照 |
+| `memory_schema_contract` | 已持久化的 `loom.memory` 列,与 schema dump 对照 |
+| `op_mix` | `loom.agent_events` 中最近的操作构成 |
+| `procedure_plane` | `loom.procedure_runs` 以及账本中记录的 procedure key |
+
+
+
+### 冒烟测试
+
+部署之后,端到端地写入并读取一条记忆:
+
+```bash
+export LOOM_API_KEY=$(docker exec loom-server loom mint-token --subject smoke --org dev --namespaces smoke --roles writer --ttl-days 1)
+curl -s -XPOST http://localhost:7777/v1/memory.set -H "Authorization: Bearer $LOOM_API_KEY" \
+ -H 'Content-Type: application/json' \
+ -d '{"org":"dev","namespace":"smoke","agent":"smoke","memory_key":"k","value":"deploy smoke test"}'
+curl -s -XPOST http://localhost:7777/v1/memory.search -H "Authorization: Bearer $LOOM_API_KEY" \
+ -H 'Content-Type: application/json' \
+ -d '{"org":"dev","namespace":"smoke","agent":"smoke","query":"smoke test"}' | jq '.results[0].content_excerpt'
+```
+
+如果搜索放弃作答,请检查 `loom.embed.pending` 以及 `/v1/health` 的 `providers` 块:一行仍在等待向量,说明它已存储,但还不能被搜索到。
+
+
+
+## Worker 状态
+
+后台任务运行在受监督的循环中,这些循环声明于 `server/workers/registry.py`(`_WORKERS`)。supervisor 会在失败后以退避方式重试;如果某一轮超过截止时间(默认为 min(4 × interval, 900 s),下限为 60 s),则将其取消;某个 worker 连续三轮失败后,会记录 `: DEGRADED`。每个 worker 由一个 `LOOM_*_ENABLED` 标志开关控制;[worker 参考文档](https://github.com/ClickHouse/loom/blob/main/docs/reference/workers.md)列出了所有 worker、对应的标志、默认值和运行频率。
+
+```bash
+curl -s -H "Authorization: Bearer $ADMIN_TOKEN" http://localhost:7777/v1/admin/workers.status | jq
+```
+
+许多"事情没有发生"的报告,其原因都是某个 worker 没有运行:为新行生成嵌入、提取延迟批次、为提交建立索引。
+
+- `/v1/admin/workers.status` 列出所有已注册的 worker(包括已禁用的),并给出其运行间隔和最近一轮的情况。它会合并当前进程的注册表与 `loom.worker_status`(保留 30 天),因此仅运行 web 的容器也能看到 workers 容器所执行的各轮结果。控制台的管理员 **Health** 视图显示相同内容。
+- `/v1/health?include=workers` → `workers_leader.reason` 说明当前进程是否持有该部署的 workers 租约(ClickHouse 中的 `workers_supervisor`)。
+- 指标:`loom.worker.consecutive_failures{worker}` 和 `loom.worker.partial_failures{worker}`。
+- `ops.projection_failures.list`(`ORG_ADMIN`)列出失败并等待 `projection_repair` worker 处理的次级投影;`ops.projection_failures.retry` 重试其中一项。
+- worker 的 ClickHouse 语句带有 `log_comment = 'worker.'`([查询归因](#logs-traces-and-query-attribution))。
+
+
+
+## 告警项
+
+下面的阈值只是起点;相似度基线请根据你自己的部署来设定,因为它取决于 embedder。
+
+| 信号 | 告警条件 | 含义 | 第一步 |
+| ------------------------------------------------------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/v1/health` HTTP 状态 | 503 | 此进程无法连接 ClickHouse | [故障排查](https://github.com/ClickHouse/loom/blob/main/docs/operations/troubleshooting.md#every-operation-fails-and-v1health-returns-503) |
+| `/v1/health` `status` | `degraded` 持续 5 分钟 | 出现 `code_tier_failing` 之外的 `error` 问题 | 阅读 `problems[].fix` |
+| `loom.search.top_similarity` 均值 | 低于你的基线持续 30 分钟 | 检索质量下降但没有报错(embedder 变更、回退到 fake) | [故障排查](https://github.com/ClickHouse/loom/blob/main/docs/operations/troubleshooting.md#search-returns-arbitrary-results-or-extraction-writes-nothing) |
+| `loom.embed.pending` | 高于 100 持续 15 分钟 | 记忆尚不可搜索;embedder 吞吐量或配额不足 | `/v1/health` → `providers` 中的提供方状态 |
+| 任意 `loom.integrity.*` | 大于 0 | 缺陷已经发生且不会自行消除([见下文](#integrity-invariants)) | 修复列 |
+| `loom.worker.consecutive_failures` | ≥ 3 | 某个 worker 在循环中反复失败 | [故障排查](https://github.com/ClickHouse/loom/blob/main/docs/operations/troubleshooting.md#a-worker-fails-every-pass) |
+| `loom.process.open_fds / loom.process.fd_limit` | 高于 0.5 | 描述符泄漏或连接过多 | 按进程区分的序列(`loom.pid`) |
+| `loom.host.disk.free_bytes / loom.host.disk.total_bytes` | 低于 0.10 | `var/` 所在磁盘将满(仓库 repack、日志、blob);降为零时主机上的所有写入都会失败 | 每个进程一个序列(`loom.disk.path`) |
+| `loom.langfuse.breaker` | = 2 | 向 Langfuse 提交评分失败;评分被丢弃 | 检查 `POST /api/public/scores` 的 Langfuse 可达性 |
+| `loom.code.index_lag_commits` | 高于每轮提交预算持续 15 分钟 | 代码索引落后于分支 | [代码索引运维](https://github.com/ClickHouse/loom/blob/main/docs/operations/code-index-operations.md#failure-model) |
+| `loom.code.tier_lag_seconds` | 高于 1800 持续 10 分钟 | 某个编译器层级尚未处理最近的合并 | `deploy/dashboards/code_plane.json` 中的 "code tier lag" 告警;阈值应设得高于最慢层级的正常周期 |
+| `loom.code.tier_failing` | 任意数据点持续 15 分钟(`severity="error"` 时发出页面告警) | `code_tier_failing` 问题所报告的代码索引层级,已超过其 `LOOM_CODE_TIER_FAILING_*` 阈值 | `/v1/health` 中 `code_tier_failing` 的 `fix`([层级失败时](https://github.com/ClickHouse/loom/blob/main/docs/operations/code-index-operations.md#when-a-tier-fails)) |
+| `ops.health` 中的 `clickhouse_parts`,或错误 252 | `fail` | 合并失败 | [故障排查](https://github.com/ClickHouse/loom/blob/main/docs/operations/troubleshooting.md#writes-fail-with-too_many_parts-or-merges-are-failing) |
+| `loom.audit.checkpoint_lag_windows` | 持续增长 | 审计检查点链落后 | `audit_verifier` worker 的各轮执行 |
+| 每个 `loom.trust` 的 `loom.auth.agents_provisioned{outcome=made}` | 高于控制平面的正常速率(起点为 10 分钟内 50 个) | 某个 trust 创建新 agent 的速度快于其集群增长:签发者密钥泄漏或控制平面失控 | 将该 trust 的 `auth.agent_provisioned` 审计行(`audit.list`)与其控制平面启动的 agent 对比;若不一致,执行 `loom bot disable --name ` 并轮换签发者密钥 |
+| `loom.auth.trust_agents_used_ratio` | 高于 0.8 | 该 trust 接近 `--max-agents`,按其存活的 agent 计数(已释放的 agent 会归还名额) | 若 `outcome=made` 的增长也快于集群增长,请按 `outcome=made` 行处理(禁用该 trust,轮换密钥);否则调高上限:使用该 trust 的参数和更大的 `--max-agents` 执行 `loom bot create --replace`(这会使这些 agent 的令牌失效;每个 agent 需重新交换) |
+| `loom.auth.agents_provisioned{outcome=at_cap}` | 10 分钟内增量大于 0 | 该 trust 的新 agent 被拒绝 | 若 `outcome=made` 的增长也快于集群增长,请按 `outcome=made` 行处理(禁用该 trust,轮换密钥);否则调高上限:使用该 trust 的参数和更大的 `--max-agents` 执行 `loom bot create --replace`(这会使这些 agent 的令牌失效;每个 agent 需重新交换) |
+
+在 HyperDX 中,空结果会被当作 0,因此最小样本保护必须返回健康范围内的值,而不是返回无行。
+
+关于该扩容什么(web 副本、提供方配额、workers 容器或 ClickHouse)的信号,见[故障与恢复](../architecture/failure-and-recovery.md)。
+
+
+
+### 管道 SLO
+
+在 Postgres 权威模式下,写入在提交时即返回,待其记忆行和搜索文档进入 ClickHouse 后才可被搜索([存储权威](../architecture/storage-authority.md#publication))。如果搜索发现较早的写入尚未到达,它会等待这些写入,最长等待 `LOOM_PG_PROJECTION_WAIT_MS`(默认 2000 ms),超时则返回 503 `PROJECTION_BEHIND`。
+
+| 目标 | 指标 | 信号 |
+| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| 读取等待较早的写入 | p99 低于 `LOOM_PG_PROJECTION_WAIT_MS` 的一半,且在非故障期间没有以 `deadline` 结束的情况(该 op 返回 503) | 按 `outcome` 区分的 `loom.pg.search_wait_ms` |
+| 写入已进入 ClickHouse | p99 低于 `LOOM_PG_PROJECTION_WAIT_MS` 的一半,使读取的等待有另一半时间 | `loom.pg.projection_lag_ms{path="flush"}` |
+| 没有任何内容等待超过已停止写入方的租约 | 最早的待处理项低于 `LOOM_PG_REQUEST_LEASE_SECONDS` 的两倍加上 `LOOM_PG_DELIVERY_IDLE_INTERVAL_SECONDS` | `loom.pg.oldest_pending_age_s{source="memory"}` |
+| 非故障期间没有滞后错误 | 0 | `loom.requests{loom.error_code="PROJECTION_BEHIND" or "PUBLICATION_PENDING"}` |
+| 没有 ClickHouse 持续拒绝的内容 | 除恢复 reconcile 持有期间外为 0 | `loom.pg.backlog{state="parked"}` |
+
+如果写入方在发布前停止,搜索的最坏等待时间就是其租约(`LOOM_PG_REQUEST_LEASE_SECONDS`):等待中的搜索会自行发布已过期的投递。这个时间超过默认等待时间,因此表现为 `outcome="deadline"`,而不是延迟。就绪状态不依赖上述任何一项:每个副本读取的是同一个 Postgres,因此由滞后驱动的就绪检查会让所有副本同时退出轮转。
+
+每个运行投递 workers 的进程都会导出整个部署的积压量,并且可能有多个进程同时导出,因此读取积压量 gauge 时应使用 `max`,而不是 `sum`。
+
+告警:
+
+| 信号 | 告警条件 | 含义 | 第一步 |
+| ------------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `loom.pg.search_wait_ms{outcome="deadline"}` 速率 | 高于 0 持续 5 分钟 | 读取等待到超时:该 op 返回 503 `PROJECTION_BEHIND`,报告则继续读取 | 先检查 ClickHouse 可达性,再检查 `loom.pg.backlog` 和 `pg_delivery` worker 的各轮执行 |
+| `loom.pg.oldest_pending_age_s{source="memory"}` | 高于目标值持续 10 分钟 | 投递 worker 跟不上,或 ClickHouse 拒绝写入 | `GET /v1/health?include=postgres` → `postgres.backlog`,以及 `pg_delivery` worker 的状态 |
+| `loom.pg.backlog{state="parked"}` | 大于 0 | ClickHouse 持续拒绝的投递,或恢复 reconcile 持有的投递(其 `last_error` 会说明是哪种) | 该投递的 `last_error`([存储权威](../architecture/storage-authority.md#delivery)) |
+| 任何进程都没有 `loom.pg.backlog` 数据点 | 持续 3 个导出周期 | 读取已停止:积压读取失败、没有投递轮次启动,或两轮起点之间的时间(一轮加其后的间隔)超过两个导出周期 | `pg_delivery` 和 `knowledge_pg_delivery` worker 日志中的 `backlog not read` 警告 |
+
+
+
+### 完整性不变量
+
+下列每个 gauge 应始终为 0。它们由持有 workers 租约的进程每 15 分钟计算一次并缓存。
+
+| 指标 | 非零值的含义 | 修复 |
+| --------------------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------- |
+| `loom.integrity.divergent_entities` | 某条记忆在 `loom.memory` 与 `loom.memory_embeddings` 之间的 entities 不一致 | 排查写入路径 |
+| `loom.integrity.orphan_vectors` | 记忆行已不存在的已嵌入向量 | `orphan_vector_reconcile` worker |
+| `loom.integrity.orphan_entity_vectors` | 记忆行已不存在的实体向量 | `orphan_vector_reconcile` worker |
+| `loom.integrity.orphan_graph_namespaces` | 存在实体边,但没有有效记忆或知识的命名空间 | `loom erasure-re-verify --orphan-graph --erase` |
+| `loom.integrity.live_ns_unregistered`, `live_rows_unregistered` | 位于没有 `loom.namespaces` 行的命名空间中的有效记忆 | 注册该命名空间,或运行 `loom namespaces-adopt` |
+| `loom.integrity.dim0_with_vector` | 有向量但 `embedding_dim = 0` 的行,搜索不可见 | `loom integrity-repair --apply` |
+| `loom.integrity.tombstone_status_drift` | 设置了 `tombstoned_at` 但状态为其他值的行 | 由 `loom integrity-repair` 列出 |
+| `loom.integrity.active_past_valid_to` | 已超过自身 `valid_to` 的活动行 | 由 `loom integrity-repair` 列出 |
+| `loom.integrity.high_with_embedding` | 仍有有效嵌入行的高敏感度行 | `loom sensitivity-sweep --apply` |
+
+修复命令的说明见[维护](https://github.com/ClickHouse/loom/blob/main/docs/operations/maintenance.md#backfills-and-repairs)。
+
+
+
+## 指标
+
+Loom 每隔 `LOOM_OTEL_METRICS_EXPORT_INTERVAL_S` 秒(默认 60)导出一次 OpenTelemetry 指标。当 `LOOM_OTEL_EXPORTER=ch`(未设置 OTLP 端点时的默认值)时,指标会直接写入同一 ClickHouse 服务上的 `default.otel_metrics_sum`、`default.otel_metrics_histogram` 和 `default.otel_metrics_gauge`(如果设置了 `LOOM_CLICKSTACK_DATABASE`,则写入该数据库,此处及下文同理),这些表也是 ClickStack/HyperDX 读取的表;若要改为发送到 collector,请设置 `LOOM_OTEL_EXPORTER_OTLP_ENDPOINT`。除非设置 `LOOM_OTEL_METRICS_DELTA_TEMPORALITY=true`,否则计数器和直方图均为累积值。启动日志会确认导出器:
+
+```text
+OTel metrics initialized — emitting every 60s (cumulative temporality, gauge heartbeat …s) to default.otel_metrics_{sum,histogram,gauge}
+```
+
+标签来自一个封闭的集合(操作、命名空间、有界枚举);键、用户 id、会话 id 和查询文本绝不会作为标签(`tests/unit/test_domain_metrics.py` 会强制检查这一点)。完整的指标目录按请求与成本、检索质量、记忆写入、积压、完整性和代码索引分组,见 [遥测](https://github.com/ClickHouse/loom/blob/main/docs/features/observability/telemetry.md)。
+
+起步查询:
+
+```sql
+-- mean top similarity per namespace, last hour
+SELECT Attributes['loom.namespace'] AS ns,
+ round(anyLast(Sum) / greatest(anyLast(Count), 1), 3) AS mean_top_similarity
+FROM default.otel_metrics_histogram
+WHERE MetricName = 'loom.search.top_similarity' AND TimeUnix > now() - INTERVAL 1 HOUR
+GROUP BY ns;
+
+-- every gauge's latest value
+SELECT MetricName, anyLast(Value) AS latest
+FROM default.otel_metrics_gauge
+WHERE TimeUnix > now() - INTERVAL 5 MINUTE
+GROUP BY MetricName ORDER BY MetricName;
+```
+
+第一个查询读取的是累积直方图,因此得到的是每个序列的整个生命周期均值;若要得到窗口均值,需要将每个点与其所在序列的前一个点做差(见 `deploy/hyperdx_dashboards.md` 中的“The cumulative-counter correction”)。
+
+
+
+## 控制台
+
+[`deploy/hyperdx_dashboards.md`](https://github.com/ClickHouse/loom/blob/main/deploy/hyperdx_dashboards.md) 是 ClickStack 和 HyperDX 的设置指南及 SQL 面板手册;ClickStack 集成本身的说明见 [ClickStack](../features/integrations/clickstack.md)。
+
+- **无需 collector。** Loom 直接把 OTel 行写入自己 ClickHouse 上的 `default.otel_*`,因此托管的 ClickStack 只需把数据源指向现有的表即可(`deploy/clickstack_sources.sh` 可以脚本化完成这一步)。如果没有 HyperDX 安装创建这些表,请手动执行一次 `schemas/otel/clickstack_otel_tables.sql`;其中每条语句都带有 `IF NOT EXISTS`。
+- **面板避开的两个陷阱。** FastAPI 的插桩会生成与父 span 同名的 ASGI 子 span(`POST /v1/memory.get http send`),这会使按 span 名称的过滤结果膨胀约三倍;只有父 span 带有 `loom.*` 属性,因此应使用 `mapContains(SpanAttributes, 'loom.operation')` 过滤。另外,累计型指标需要按序列计算增量:对一个时间窗口内的 `sum(Value)` 求和,得到的是累计值的总和。
+- **代码索引看板。** [`deploy/dashboards/code_plane.json`](https://github.com/ClickHouse/loom/blob/main/deploy/dashboards/code_plane.json) 是“Loom — Code Plane”控制台的唯一权威来源:包含每个图块及其数据源和 SQL,以及带有 `alert` 块(含阈值和原因)的图块。请根据该 JSON 进行配置,而不要在 UI 中编辑图块,这样下次重建时才能保持一致。
+- 如果面板一直为空,请检查 `docker logs loom-server 2>&1 | grep -i otel`。span 每隔几秒刷新一次;指标则在每个导出间隔刷新一次。缺少表时会显示为 `default.otel_traces does not exist … Self-disabling span export`。
+
+
+
+## 日志、追踪与查询归因
+
+- **日志。** 使用 `docker logs loom-server` 和 `docker logs loom-workers`。接入日志管道时设置 `LOOM_LOG_FORMAT=json`,用 `LOOM_LOG_LEVEL` 控制详细程度。启动日志会列出解析出的 provider 以及每个已应用的迁移;supervisor 会记录每一次失败的执行和 `DEGRADED` 行。
+- **账本。** `loom.agent_events` 每个操作对应一行,包含 `operation`、身份列、`request_id`、`trace_id`、`latency_ms`、`success`、`error_code`、token、`upstream_cost_usd`、`model`、`consumer`、`traffic_class`、`build_commit`、`instance` 和 `instance_label`。`loom.audit_log` 记录谁修改了什么,并为每一行附带内容哈希([审计](https://github.com/ClickHouse/loom/blob/main/docs/features/observability/audit.md))。
+- **追踪。** span 会写入 `default.otel_traces`(或 OTLP 端点),并带有 `loom.org`、`loom.namespace`、`loom.agent`、`loom.operation`、`loom.request_id` 和 `enduser.id` 标签。配置 Langfuse 后,span 树也会发送到 Langfuse([Langfuse](../features/integrations/langfuse.md))。每个 HTTP 响应都带有 `X-Request-Id`(如果客户端发送了由 1 到 64 个字母、数字、`.`、`_` 或 `-` 组成的值,则沿用客户端的值)和 `X-Trace-Id`。
+- **每个 ClickHouse 查询都会归因**,记录在其 `log_comment` 设置中:
+
+| `log_comment` | 发起方 |
+| ------------------------------ | ----------------------------------------------------------------- |
+| ` ` | 一次请求(HTTP 或 MCP) |
+| `worker.` | 一次 worker 执行 |
+| `cli.[.]` | 一条 `loom` 命令(不含 `loom serve`) |
+| `untagged:.` | 其他情况;后台循环应调用 `set_query_tag(...)` |
+
+设置 `LOOM_CH_LOG_COMMENT_STATEMENT_DIGEST=true` 后,标签后面会附加语句摘要,因此匹配时请在末尾加上 `%`。
+
+```sql
+-- which operations cost ClickHouse the most in the last hour
+SELECT splitByChar(' ', log_comment)[1] AS source,
+ count() AS queries, sum(read_bytes) AS bytes, sum(query_duration_ms) AS ms
+FROM system.query_log
+WHERE type = 'QueryFinish' AND event_time > now() - INTERVAL 1 HOUR AND log_comment != ''
+GROUP BY source ORDER BY ms DESC LIMIT 20;
+
+-- one request end to end
+SELECT * FROM loom.agent_events WHERE request_id = '';
+```
+
+`LOOM_INSTANCE_LABEL`(在 compose 文件之外必须设置)可使笔记本电脑或测试服务器的行与部署本身的行在上述两个查询中保持可区分。蓝绿切换后,`loom deploy-delta` 会比较切换前后两侧的账本和语句形态。它在两侧各读取 `--window-min` 分钟(默认 60),因此请在该窗口过去之后再运行,并避免自己的回读流量混入其中:切换后立即发出的请求运行在冷缓存上,会拉高切换后一侧的延迟。
+
+
+
+## 速率限制与流量类别
+
+每个请求都会从两个令牌桶中扣减,一个按命名空间,一个按组织(容量为命名空间的三倍),并按操作类别划分。超出限制时,响应为 429 `RATE_LIMITED`,并带有 `Retry-After` 和 `X-RateLimit-*` 头。
+
+| 类别 | 操作 | 每个命名空间的突发 / 持续速率 |
+| ------------------ | ------------------------------------------------------------------------------------------------------------- | ----------------------------- |
+| `memory` | `memory.*`、`conversation.*`(精确键读取和 `memory.import` 除外) | 每秒 100 / 17 |
+| `memory.read` | 精确键读取:`memory.get`、`memory.bulk_get`、`memory.history`、`working_memory.get` 等 | 每秒 300 / 50 |
+| `memory.import` | `memory.import` | 每秒 10 / 2 |
+| `knowledge.search` | `knowledge.search` | 每秒 20 / 3 |
+| `knowledge.query` | `knowledge.query` | 每秒 20 / 3 |
+| `knowledge.read` | 其余 `read_only` 的 `knowledge.*` 操作(`knowledge.inspect` 除外):`knowledge.get`、`knowledge.list` 等 | 每秒 50 / 10 |
+| `knowledge.add` | 其他所有 `knowledge.*` 操作,包括 `knowledge.inspect`、`knowledge.synthesize` 和 `knowledge.dedup_list` | 每秒 10 / 2 |
+| `code` | `code.*`(`code.outcome` 除外,它从 `memory` 扣减) | 每秒 60 / 10 |
+| `insights.query` | `insights.query` | 每秒 20 / 3 |
+| `assistant.ask` | `assistant.ask` 及 assistant 的聊天路由 | 每秒 10 / 1 |
+| `default` | 其他所有操作 | 每秒 50 / 10 |
+
+请求被归为 `production`、`interactive` 或 `bench`(优先取 `loom mint-token --traffic-class` 设置的令牌声明,其次是命名空间的注册信息,最后是请求的提示);响应头 `X-Loom-Traffic-Class` 会说明实际使用的类别。Bench 流量使用独立的、更小的桶(`LOOM_RATELIMIT_CLASS_FRACTIONS`),并使用更低的 ClickHouse 优先级,因此基准测试不会耗用生产环境的额度。限制按副本分别执行,参见[故障与恢复](../architecture/failure-and-recovery.md)中的 `LOOM_REPLICA_COUNT`。`POST /v1/admin/ratelimit.set` 携带 `{namespace|org, op_class, capacity, rate}`(或 `clear: true`)可覆盖某个桶。覆盖值存储在 `loom.runtime_overrides` 中,每个进程会在 `LOOM_RUNTIME_OVERRIDES_REFRESH_SECONDS`(默认 10)内采用它,且重启后依然有效。`POST /v1/admin/budget.set` 以同样方式存储延迟预算的覆盖值。桶的填充本身仍然按主机进行。
+
+
+
+## 相关内容
+
+- [故障排查](https://github.com/ClickHouse/loom/blob/main/docs/operations/troubleshooting.md):按症状组织的运行手册,针对这些信号所能捕获的问题
+- [遥测](https://github.com/ClickHouse/loom/blob/main/docs/features/observability/telemetry.md):指标和 span 目录
+- [成本与用量](https://github.com/ClickHouse/loom/blob/main/docs/features/observability/cost-and-usage.md)和[审计](https://github.com/ClickHouse/loom/blob/main/docs/features/observability/audit.md)
diff --git a/i18n/es/docs/getting-started/whats-included.md b/i18n/es/docs/getting-started/whats-included.md
new file mode 100644
index 0000000000..10071c326d
--- /dev/null
+++ b/i18n/es/docs/getting-started/whats-included.md
@@ -0,0 +1,80 @@
+
+> Esta página es una traducción automática de la [página en inglés](https://github.com/ClickHouse/loom/blob/main/docs/getting-started/whats-included.md), que prevalece.
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/getting-started/whats-included.md), which is authoritative.
+
+
+
+# Qué incluye
+
+Esta página enumera las principales capacidades de Loom, autoalojadas desde el repositorio con licencia Apache-2.0: una sección por área, con cada fila enlazada a la página que la describe. El [índice de la documentación](https://github.com/ClickHouse/loom/blob/main/docs/index.md) muestra el resto de la documentación. Varias capacidades deben activarse; la página enlazada explica cómo, y los interruptores booleanos que se cargan como false se enumeran en [estado](https://github.com/ClickHouse/loom/blob/main/docs/reference/status.md). El embedder lo eliges tú: el modelo local incluido, un proveedor alojado o un endpoint compatible con OpenAI que ejecutes tú mismo. La extracción, los resúmenes y las respuestas con citas necesitan un LLM real ([modelos y claves de API](https://github.com/ClickHouse/loom/blob/main/docs/getting-started/models-and-keys.md)).
+
+
+
+## Memoria
+
+| Capacidad | Qué hace | Página |
+| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| Memoria compartida a largo plazo | Una afirmación por clave en un espacio de nombres, evaluada contra los hechos que ya existen antes de guardarse | [Escritura de memoria](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/writing.md) |
+| Registros tipados | Filas con campos exactos para datos que tienen identidad, y que responden preguntas de predicado sin analizar texto | [Registros tipados](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/writing.md#typed-records) |
+| Búsqueda y consulta | Resultados clasificados, o una respuesta que cita claves de memoria; ambas se abstienen cuando la memoria no respalda una respuesta | [Búsqueda y consulta](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/search-and-ask.md) |
+| Conflictos y rechazo | Un valor cercano pero distinto se marca y el propietario del espacio de nombres decide qué hecho prevalece; un patrón registrado rechaza las escrituras que coinciden | [Conflictos y rechazo](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/conflicts-and-refusal.md) |
+| Historial y procedencia | Cada escritura es una versión nueva, con quién la escribió y cómo entró en la memoria | [Historial y procedencia](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/history-and-provenance.md) |
+| Extracción de transcripciones | El servidor decide qué parte de una transcripción es duradera | [Extracción](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/extraction.md) |
+| Importación | Hechos que otro sistema de memoria ya destiló, escritos con las mismas comprobaciones que cualquier escritura | [Importación](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/writing.md#importing-from-another-memory-system) |
+| Webhooks de cambios | Un evento firmado cuando una memoria se escribe, se revisa, se elimina, se restaura, se redacta (se ocultan datos sensibles) o se borra, enviado a una URL que registra un administrador del espacio de nombres | [Webhooks de cambios](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/writing.md#change-webhooks) |
+| Memoria de trabajo y perfiles | Pequeños bloques con nombre y texto de perfil que se entregan a un agente cada vez | [Memoria de trabajo y perfiles](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/working-memory-and-profiles.md) |
+| Procedimientos y aprendizajes | Pasos aprendidos a partir de ejecuciones reportadas, reflexiones y una cola de revisión de hechos candidatos | [Procedimientos y aprendizajes](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/procedures-and-learnings.md) |
+| Memorias vinculadas al código | Una memoria sobre código sigue a las definiciones que nombra cuando se mueven o cambian | [Memorias vinculadas al código](https://github.com/ClickHouse/loom/blob/main/docs/concepts/memory.md#memories-linked-to-code) |
+| Grafo de entidades | Entidades y sus relaciones junto a las filas de memoria | [Grafo de entidades](https://github.com/ClickHouse/loom/blob/main/docs/features/entity-graph.md) |
+
+
+
+## Documentos, código y registros de trabajo
+
+| Capacidad | Qué hace | Página |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Búsqueda de documentos | Documentos divididos en secciones, con embeddings, que se buscan y se citan por pasaje; las búsquedas que no encontraron nada se agrupan en lagunas de conocimiento | [Documentos de conocimiento](https://github.com/ClickHouse/loom/blob/main/docs/features/knowledge.md) · [Lagunas de conocimiento](https://github.com/ClickHouse/loom/blob/main/docs/features/knowledge.md#knowledge-gaps) |
+| Archivos y fuentes de documentos | PDF, DOCX, PPTX, XLSX, CSV y más, analizados por un servicio extractor; fuentes registradas sincronizadas en un espacio de nombres | [Ingesta de archivos](https://github.com/ClickHouse/loom/blob/main/docs/features/knowledge.md#ingesting-files) · [Fuentes de documentos](https://github.com/ClickHouse/loom/blob/main/docs/features/knowledge.md#document-sources) |
+| Búsqueda unificada | Memoria, perfil, documentos y conversaciones pasadas en una sola llamada, y un paquete de contexto para una tarea | [Búsqueda unificada](https://github.com/ClickHouse/loom/blob/main/docs/features/unified-search.md) |
+| Preguntar a la IA | Un asistente en el panel de control que responde sobre lo que contiene un espacio de nombres, con una cita para cada afirmación; sus respuestas del modelo se ejecutan en un servidor de chat que despliegas junto a Loom | [Panel de control](https://github.com/ClickHouse/loom/blob/main/docs/features/dashboard.md#ask-ai) · [Configuración del servidor de chat](https://github.com/ClickHouse/loom/blob/main/docs/features/integrations/librechat.md#the-deployed-assistant) |
+| Índice de código | Definiciones, llamadores, impacto y búsqueda por significado sobre tus repositorios git | [Índice de código](https://github.com/ClickHouse/loom/blob/main/docs/features/code-index/overview.md) |
+| Historial de PR y versiones | Pull requests fusionados cruzados con los símbolos, llamadores y pruebas actuales | [Historial, PR y versiones](https://github.com/ClickHouse/loom/blob/main/docs/features/code-index/history-and-prs.md) |
+| Tracker | Issues, pull requests, incidentes y ejecuciones de CI leídos en vivo desde tu propio ClickHouse | [Plano del tracker](https://github.com/ClickHouse/loom/blob/main/docs/features/tracker/overview.md) |
+| Conversaciones y sesiones | Transcripciones literales con búsqueda, registradas una vez que un administrador activa el registro para el espacio de nombres, y resúmenes de sesión desde los que un agente retoma el trabajo | [Conversaciones y sesiones](https://github.com/ClickHouse/loom/blob/main/docs/features/conversations-and-sessions.md) · [Registro](https://github.com/ClickHouse/loom/blob/main/docs/features/conversations-and-sessions.md#recording-is-the-owners-choice) |
+| Ejecuciones | Un registro por cada ejecución de tarea, con las memorias en las que se apoyó | [Ejecuciones](https://github.com/ClickHouse/loom/blob/main/docs/features/runs.md) |
+| Tareas, decisiones y políticas | Bandejas de tareas, un registro de decisiones y políticas para la coordinación entre agentes | [Tareas, decisiones y políticas](https://github.com/ClickHouse/loom/blob/main/docs/features/tasks-and-decisions.md) |
+
+
+
+## Acceso, gobernanza y operaciones
+
+| Capacidad | Qué hace | Página |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Espacios de nombres y uso compartido | La unidad de aislamiento y de uso compartido dentro de una organización; toda lectura se limita a uno | [Espacios de nombres y uso compartido](https://github.com/ClickHouse/loom/blob/main/docs/features/namespaces-and-sharing.md) |
+| Tokens y roles | Tokens, permisos y roles por espacio de nombres | [Tokens y permisos](https://github.com/ClickHouse/loom/blob/main/docs/guides/tokens-and-grants.md) |
+| Inicio de sesión único y SCIM | Inicio de sesión OIDC para el panel, la CLI y los clientes MCP, y desaprovisionamiento mediante SCIM | [Inicio de sesión único](https://github.com/ClickHouse/loom/blob/main/docs/operations/sso.md) |
+| Registro de auditoría | Una fila por operación auditada o evento del servidor, con sus valores de texto libre almacenados como hashes, sellada en una cadena verificada de puntos de control | [Registro de auditoría](https://github.com/ClickHouse/loom/blob/main/docs/features/observability/audit.md) |
+| Retención y borrado | Caducidad, retención configurada y borrado de un ámbito en todos los lugares donde Loom lo guarda | [Retención y borrado](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/retention-and-erasure.md) |
+| Valores sensibles | Una memoria de sensibilidad `high` nunca se incrusta y solo se puede leer por clave, con una lectura auditada; la detección es configurable | [Tipos de memoria](https://github.com/ClickHouse/loom/blob/main/docs/concepts/memory.md#memory-types) |
+| Controles de llamadas a modelos | Un administrador de la organización puede desactivar todas las llamadas a modelos para los datos de la organización, y un despliegue puede enrutarlas a través de un gateway de inferencia | [Desactivar las llamadas a modelos](https://github.com/ClickHouse/loom/blob/main/docs/getting-started/models-and-keys.md#switching-an-orgs-model-calls-off) · [Gateway de inferencia](https://github.com/ClickHouse/loom/blob/main/docs/getting-started/models-and-keys.md#through-an-inference-gateway) |
+| Costo y uso | Cada dólar gastado en embeddings y LLM se registra frente a la operación que lo gastó | [Costo y uso](https://github.com/ClickHouse/loom/blob/main/docs/features/observability/cost-and-usage.md) |
+| Telemetría | Un registro por operación, trazas, logs y métricas de OpenTelemetry, y atribución de consultas | [Telemetría](https://github.com/ClickHouse/loom/blob/main/docs/features/observability/telemetry.md) |
+| Panel | La aplicación web donde las personas deciden sobre conflictos, propuestas, tareas, solicitudes de permisos y políticas | [Panel](https://github.com/ClickHouse/loom/blob/main/docs/features/dashboard.md) |
+| Acceso SQL | Vistas de ClickHouse de solo lectura sobre las memorias, el historial, las conversaciones y el registro de solicitudes de un tenant, también legibles desde Postgres | [Superficie SQL](https://github.com/ClickHouse/loom/blob/main/docs/reference/sql-surface.md) · [Consultar desde Postgres](https://github.com/ClickHouse/loom/blob/main/docs/guides/query-from-postgres.md) |
+| Réplicas y Kubernetes | Réplicas idénticas detrás de una única URL, y un chart de Helm | [Ejecutar N réplicas](https://github.com/ClickHouse/loom/blob/main/docs/operations/replicas.md) · [Kubernetes](https://github.com/ClickHouse/loom/blob/main/docs/operations/kubernetes.md) |
+| Postgres como autoridad de memoria | Opcional: memoria activa y cabeceras de documentos en Postgres, elegido en el primer arranque | [Postgres](https://github.com/ClickHouse/loom/blob/main/docs/operations/postgres.md) |
+| Copia de seguridad y recuperación | Copias de seguridad de ClickHouse, más el bucket de documentos y Postgres cuando se usan | [Copia de seguridad y recuperación](https://github.com/ClickHouse/loom/blob/main/docs/operations/backup-and-recovery.md) |
+| Actualizaciones | Se reemplaza la imagen y sus migraciones se aplican al arrancar; una instalación nueva sigue el mismo camino | [Actualizaciones](https://github.com/ClickHouse/loom/blob/main/docs/operations/upgrades.md) |
+| Copia de espacios de nombres y bundles OKF | Un espacio de nombres copiado a otro Loom de forma programada, o exportado e importado como un bundle OKF | [Copiar un espacio de nombres](https://github.com/ClickHouse/loom/blob/main/docs/operations/okf-sync.md) · [Bundles OKF](https://github.com/ClickHouse/loom/blob/main/docs/features/integrations/okf.md) |
+| Exportación de uso | Un día UTC de uso y una instantánea de los espacios de nombres, escritos en S3 como Parquet para un data warehouse | [Exportación de analítica](https://github.com/ClickHouse/loom/blob/main/docs/operations/analytics-export.md) |
+
+
+
+## Formas de conectarse
+
+MCP para cualquier cliente MCP, plugins para Claude Code y Codex, adaptadores de frameworks, una API HTTP, SDKs de Python y TypeScript, y la CLI `loom`:
+[Integraciones](https://github.com/ClickHouse/loom/blob/main/docs/features/integrations/index.md) ·
+[Clientes MCP](https://github.com/ClickHouse/loom/blob/main/docs/features/integrations/mcp-clients.md) ·
+[Marcos de trabajo](https://github.com/ClickHouse/loom/blob/main/docs/features/integrations/frameworks.md) ·
+[API HTTP](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md) · [SDK de Python](https://github.com/ClickHouse/loom/blob/main/docs/reference/python-sdk.md) ·
+[SDK de TypeScript](https://github.com/ClickHouse/loom/blob/main/docs/reference/typescript-sdk.md) · [CLI](https://github.com/ClickHouse/loom/blob/main/docs/reference/cli.md).
diff --git a/i18n/ja/docs/features/observability/telemetry.md b/i18n/ja/docs/features/observability/telemetry.md
new file mode 100644
index 0000000000..c0e8cd8330
--- /dev/null
+++ b/i18n/ja/docs/features/observability/telemetry.md
@@ -0,0 +1,326 @@
+
+> このページは[英語の原文](https://github.com/ClickHouse/loom/blob/main/docs/features/observability/telemetry.md)の機械翻訳です。内容は英語の原文が優先されます。
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/features/observability/telemetry.md), which is authoritative.
+
+
+
+# テレメトリ
+
+Loom は自身の状態を次の 3 つのレイヤーで報告します。
+
+| レイヤー | 記録先 | 分かること |
+| ---------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------- |
+| 台帳 | `loom.agent_events`、操作またはワーカーの 1 回の処理につき 1 行 | 誰が何を呼び出したか、所要時間、コスト |
+| OpenTelemetry | `default.otel_traces`、`otel_logs`、`otel_metrics_*`(または OTLP コレクター) | リクエスト内で時間がどこに費やされたか、傾向とアラート |
+| ClickHouse クエリの帰属 | `system.query_log.log_comment` | どの操作またはワーカーが ClickHouse に処理をさせたか |
+
+3 つのレイヤーはすべてリクエスト ID を共有します。[監査ログ](https://github.com/ClickHouse/loom/blob/main/docs/features/observability/audit.md)は、誰が何を変更したかを改ざん検知付きで記録する、別個の記録です。
+
+
+
+## 台帳
+
+`loom.agent_events` には、操作ごとに1行が記録されます。列は `operation`、ID 列(`org`、`namespace`、`agent`、`user_id`、`session_id`、`run_id`)、`request_id`、`trace_id`、`latency_ms`、`success`、`error_code`、トークン数、`upstream_cost_usd`、`model`、`llm_calls`、`consumer`、`traffic_class`、`subject`、`build_commit`、`instance`、`instance_label`、そして上限付きでマスク済みのリクエストフィールドと出力フィールドを持つ `args` マップです。ワーカーのパスは `kind='worker'` の行を書き込みます。[コストと使用量](https://github.com/ClickHouse/loom/blob/main/docs/features/observability/cost-and-usage.md)はこのテーブルを基に構築されています。
+
+各リクエスト行には、サービスレベルの列も含まれます。
+
+- `transport`:`http` または `mcp`。
+- `slo_class`:`code`、`search`、`admin` のいずれか。読み取り専用でないその他の op は `write`、それ以外は `read`。
+- `status_class`:`ok`。4xx の拒否、または再試行された冪等性キーがまだ実行中の場合は `client`。それ以外は `server`。
+- `budget_ms`:そのリクエストに課されたレイテンシ予算。予算が 0 の場合(違反を強制するオーバーライド)、成功したリクエストはすべて遅いとみなされます。
+
+org や名前空間を指定しない呼び出しは、ゲートがその呼び出しを受け入れた org と名前空間のもとで記録されます(code op のデフォルトは、デプロイのコード用名前空間です)。そのため、その行はそのテナントのものとなり、テナントの SLI、コストの集計、`subject_last_seen`、履歴ポリシーの件数のすべてにそこで反映されます。org を指定せず、ゲートの前で拒否された呼び出しは、トークンの org のもとで記録されます(org 全体のトークンの場合や認証がオフの場合は `-`)。そのため `cost.summary`、接続中エージェントのビュー、`subject_last_seen` も、その org の呼び出しとして数えます。
+
+サーバー側の問題として数えられるもの:
+
+- 履歴ポリシーを評価できなかったために拒否された書き込み。
+- チェックに必要な読み取りが失敗したために行われた拒否(権限付与、サブジェクトのエイリアス、サービスアカウントまたは委任トークンの作成者、名前空間の分類)。そのような形で応答自体が拒否または非表示にされたリクエスト(id 検索の `found=False`、ハンドラー自身のチェックによる 403 や 404、org 全体の集計が丸ごと空になった場合)は、ワイヤ上では成功していても `server` となり、その場合 `error_code` は空になります。
+- 次のものは数えません。それなしでも応答が完全である場合に、応答から外された名前空間です。Loom が自ら追加したもの(コードリンク、グラウンディング、リポジトリのドキュメント、トランク、呼び出し元が指定していないアイテムのコード回答を補強するトラッカー)、呼び出し元がスコープを指定していない一覧やデフォルトの選択で除外されたエントリ、投稿者がいずれにせよ受け入れられるタスクでの所有者チェックがこれにあたります。これらはリクエストを `ok` のままにします。
+
+呼び出しが受け入れられる前の拒否:
+
+- MCP は、ディスパッチ前に拒否した呼び出しについても行を書き込みます(トークンが使用できない org や名前空間、MCP から除外された op、読み取り専用接続での書き込み)。HTTP が拒否を記録するのと同様です。この時点では呼び出し元がまだバインドされていないため、その行にはトークンの org(トークンがその org で動作できる場合は呼び出しが指定した org)、サブジェクト、consumer が入り、残りは `-`、引数はなしになります。
+- どちらのトランスポートでも、トークンが動作できない org を指定した拒否は、指定された org ではなく、トークンの org で記録されます。
+- 呼び出しが分類される前に記録された拒否には、トークンの `traffic_class` クレームが入り、クレームがなければ '' になります。
+- 1つの MCP バッチ内では、ハンドラーが実行される前の呼び出し元の拒否は、操作、コード、org、ステータスクラスごとに1回記録され、サーバー障害は最大10回までです。書き込まれなかった行は、`loom.ledger.batch_repeats`(呼び出し元の拒否)または `loom.ledger.dropped{reason="batch_repeat"}`(サーバー障害、つまり失われたサーバーエラー)に計上されます。冪等性の拒否(レートリミッターの後)とハンドラーの失敗は、必ず独自の行を持ちます。
+
+リフレッシュ可能なマテリアライズドビューが、台帳を1分に1回 `loom_telemetry.sli_minute` に集約します(リクエスト数、サーバーエラーとクライアントエラー、クライアントエラーに含まれるレート制限されたリクエスト、予算超過の成功、レイテンシの分位数を 400 日間保持します。レイテンシはハンドラーの処理時間で、予算の基準となるものであり、その前段のゲートの時間は含みません)。これにより、SLO ダッシュボードやアラートルールは台帳をスキャンせずに読み取れます。集約は、行の `ts` ではなく ClickHouse が各行を受け取った時刻(`ingested_at`)から再開するため、フラッシュが遅れた行も、その `ts` の分に1回だけ数えられます。行は ClickHouse が受け取ってから少なくとも 70 秒後(最大で約 130 秒後)に集約され、その間に挿入がコミットされます。リフレッシュは1つのパートを書き込むため、リフレッシュが失敗しても、再試行で二重に集約されたり飛ばされたりするものは残りません。ClickHouse が行にスタンプを付けてから 70 秒を超えてコミットされた台帳のパートは集約されません。`loom.sli.rollup_missed_rows` は過去1日のそのような行を数え、ロールアップを再集約する([ClickHouse](https://github.com/ClickHouse/loom/blob/main/docs/architecture/clickhouse.md))ことで復旧できます。SLO クラスを持たない行(`/v1/me/*` ルート、および `initialize` のように登録済み op を指定しない MCP 呼び出し)は除外されます。同じ分が、マージされるまで複数の行として現れることがあるため、読み取り側はキーでグループ化し、件数には `sum()`、レイテンシには `quantilesTDigestMerge(0.5, 0.95, 0.99)(latency)` を使います。各リフレッシュは、すべてのキーが空で件数がすべて 0 の行も書き込み、次のリフレッシュはそこから再開します。読み取り側は `slo_class != ''` でフィルターしてください。テストトラフィックを除くには、`traffic_class NOT IN
+('bench', 'background')` でフィルターします。呼び出しが分類される前に記録された拒否は、クラスが空です。
+
+エミッターはバッチ処理され、リクエストを失敗させることはありません。クラッシュすると、フラッシュされていないキューが失われることがあります。
+
+行を書き込むすべてのプロセスは、起動元の名前を持つ必要があります。compose ファイルは `LOOM_DEPLOYMENT=1` を設定し、サービスに `deploy:web`、`deploy:workers`、`deploy:dev` のラベルを付けます。それ以外のプロセス(`make server`、テストサーバー)は `LOOM_INSTANCE_LABEL=::` を設定する必要があり、設定しないと起動を拒否します。`loom serve` のデフォルトは `cli:serve:` です。これにより、同じ ClickHouse 上にある他のものとデプロイの行が区別されます。
+
+
+
+## トレースとログ
+
+- **トレース。** スパンは `default.otel_traces`(または OTLP エンドポイント)に書き込まれ、`loom.org`、`loom.namespace`、`loom.agent`、`loom.operation`、`loom.request_id`、`enduser.id` のタグが付きます。ヘルスチェックのポーリングではスパンを開始しません(`LOOM_OTEL_EXCLUDED_URLS`、デフォルトは `/v1/health`)。すべての HTTP レスポンスに `X-Request-Id`(クライアントが 1〜64 文字の英字、数字、`.`、`_`、`-` を送った場合はその値)と `X-Trace-Id` が付きます。スパンにクエリ文字列は含まれません。
+- **モデル呼び出し。** LLM と埋め込みの各呼び出しは、それぞれ独立したスパン `llm.` または `embed.provider` になり、OpenTelemetry GenAI 属性が付きます。属性は `gen_ai.provider.name`、`gen_ai.operation.name`(`chat` または `embeddings`)、`gen_ai.request.model`、`gen_ai.usage.input_tokens` と `output_tokens`、プロバイダーのプロンプトキャッシュ分を示す `gen_ai.usage.cache_read.input_tokens` と `cache_creation.input_tokens`(どちらも `input_tokens` に含まれます)、および Loom の価格表に基づく `gen_ai.usage.cost` です。呼び出しを行った処理段階は `loom.llm.stage` に入ります。Loom 自身の埋め込みキャッシュから返されたトークンは、課金対象の入力とは別に `loom.embed.cached_tokens` に記録されます。HyperDX の LLM ビューと Langfuse は、これらのキーをそのまま読み取ります。
+- **ログ。** `docker logs loom-server` と `docker logs loom-workers`、および `default.otel_logs` への OTel ログエクスポートがあります。ログパイプライン向けには `LOOM_LOG_FORMAT=json`、詳細度の調整には `LOOM_LOG_LEVEL` を使います。起動ログには解決されたプロバイダーと適用された各マイグレーションが記録され、スーパーバイザーは失敗した各パスと `DEGRADED` 行を記録します。
+- **Langfuse。** `LOOM_LANGFUSE_URL` と `LOOM_LANGFUSE_ADMIN_TOKEN` を設定すると、スパンツリーは 2 つ目のスパンプロセッサーとして Langfuse にも転送されます。転送ではサンプリングとフィルタリングが行われます。詳細は [Langfuse](https://github.com/ClickHouse/loom/blob/main/docs/features/integrations/langfuse.md) を参照してください。
+
+`init_otel` は pytest の下では起動しないため、テストがデプロイ環境のオブザーバビリティテーブルに書き込むことはありません。`LOOM_OTEL_ENABLED=false` で出力を無効にできます。
+
+
+
+### エクスポーター
+
+| 設定 | デフォルト | 効果 |
+| ------------------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `LOOM_OTEL_EXPORTER` | `""` | `ch` は Loom 自身の ClickHouse サービス上の `default.otel_*` テーブルに直接書き込みます。`otlp` はコレクターに送信します。空の場合、エンドポイントが設定されていれば `otlp`、そうでなければ `ch` になります |
+| `LOOM_OTEL_EXPORTER_OTLP_ENDPOINT` | `""` | OTLP/HTTP コレクターのベース URL(`/v1/traces` と `/v1/metrics` が付加されます) |
+| `LOOM_OTEL_EXPORTER_OTLP_HEADERS` | `""` | カンマ区切りの `K=V` ヘッダー。例:`Authorization=Bearer ` |
+| `LOOM_OTEL_SERVICE_NAME`, `LOOM_OTEL_ENVIRONMENT` | `loom`, `dev` | すべてのスパン、ログ、メトリクスに付く `service.name` と `deployment.environment.name` |
+| `LOOM_OTEL_METRICS_EXPORT_INTERVAL_S` | `60` | メトリクスのエクスポート間隔。スパンは独自の 3 秒のバッチ遅延を保ちます |
+| `LOOM_OTEL_METRICS_DELTA_TEMPORALITY` | `false` | カウンターとヒストグラムを累積ではなくデルタにします。標準のダッシュボードは累積行を読むため、両方を同時に切り替えてください |
+| `LOOM_OTEL_GAUGE_HEARTBEAT_S` | `0` | `ch` エクスポーターのみ:ゲージの点は、値が変化したとき、またはこの秒数が経過したときだけ書き込みます。0 の場合は毎回のエクスポートで書き込みます(ゲージのタイルは欠損を 0 で埋めます)。OTLP はすべての点をエクスポートします |
+| `LOOM_OTEL_CENSUS_SCOPE` | `leader` | テーブル全体の集計を行う主体:スーパーバイザーのリースを持つプロセスのみ、またはすべてのプロセス(高コスト) |
+
+`ch` エクスポーターは ClickStack/HyperDX が読み取るテーブルに書き込むため、標準のスタックならコレクターなしでダッシュボードを利用できます。[ClickStack](https://github.com/ClickHouse/loom/blob/main/docs/features/integrations/clickstack.md) と `deploy/hyperdx_dashboards.md` を参照してください。
+
+
+
+## メトリクス
+
+メトリクスは `LOOM_OTEL_METRICS_EXPORT_INTERVAL_S` ごとにエクスポートされます。`ch` エクスポーターでは `default.otel_metrics_sum`、`default.otel_metrics_histogram`、`default.otel_metrics_gauge` に書き込まれ、`otlp` ではコレクターの `/v1/metrics` に送られます。ダッシュボードの定義は `deploy/dashboards/` と `deploy/hyperdx_dashboards.md` にあります。
+
+ラベルは閉じた集合(操作、名前空間、上限のある列挙値)から取ります。キー、ユーザー ID、セッション ID、クエリテキストはラベルになりません。これは `tests/unit/test_domain_metrics.py` が検証します。モデルラベル(`loom.llm.fallback`、`loom.llm.response_cache`)には、料金表に載っているモデル、またはデプロイの `LOOM_LLM_MODEL` / `LOOM_LLM_FALLBACK_MODEL` のモデル名が入ります。リクエストがモデルを指定できるため、それ以外は `unlisted` になります。
+
+テーブルスキャンが必要なゲージは、workers-lease の保持者が計算してキャッシュします。整合性の不変条件と埋め込みバックログは `LOOM_OTEL_INVARIANTS_PROBE_S`(3600 秒)ごと、保持期間の集計は `LOOM_OTEL_RETENTION_CENSUS_S`(3600 秒)ごと、コードプレーンの件数は `LOOM_OTEL_CODE_COUNTS_CACHE_S`(3600 秒)ごとです。
+
+
+
+### リクエストとコスト
+
+| メトリクス | 型 | 意味 |
+| ------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `loom.requests` | counter | 処理した操作の数。操作、名前空間、成否、`loom.error_code`(失敗時のコード。成功時は空)ごと |
+| `loom.request.duration` | histogram | 操作の実時間(ms) |
+| `loom.cost.usd` | counter | 操作に帰属する上流プロバイダーの支出 |
+| `loom.tokens` | counter | `kind`(`embed`、`llm_input`、`llm_output`)別のトークン数 |
+| `loom.ops.paid_errors` | counter | すでに上流で支出が発生していた失敗リクエスト |
+| `loom.llm.fallback` | counter | `LOOM_LLM_FALLBACK_MODEL` が応答した LLM 呼び出し |
+| `loom.llm.response_cache` | counter | プロンプト完全一致の LLM キャッシュ検索の結果別件数 |
+| `loom.memory.build.tokens` | counter | メモリの構築に使った LLM トークン。ステージと方向別 |
+| `loom.memory.extraction_yield` | histogram | 書き込まれたメモリ 1 件あたりのプロンプトトークン数。`messages` の範囲別 |
+| `loom.extract.cost_per_row_usd` | histogram | 1 回の抽出で書き込まれたメモリ行 1 行あたりの USD |
+| `loom.auth.refusals` | counter | ベアラートークンを理由に拒否されたリクエスト(トークンなし、検証に失敗したもの、まだ確認できないもの。ClickHouse が失効済みと判断したトークンによる発行も含む)。`reason`(`missing`、`malformed`、`expired`、`revoked`、`invalid`、`unavailable`)と `loom.transport`(`http`、`mcp`、またはプロバイダートークンが欠落・不正・誤りの SCIM リクエストでは `scim`)別。SLI ロールアップには含まれません |
+
+
+
+### エージェントトラスト
+
+`--agent-claim` 付きで登録したワークロードトラストは、最初の交換時にエージェントごとの名前空間を作成します。上限は `--max-agents` です([ボットと CI](https://github.com/ClickHouse/loom/blob/main/docs/operations/sso.md#bots-and-ci))。`loom.trust` はトラストの名前で、登録できるのはオペレーターだけです。
+
+| メトリクス | 型 | 意味 |
+| ----------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `loom.auth.agents_provisioned` | counter | トラストのエージェントの最初の交換。`loom.org`、`loom.trust`、`outcome` 別。`made`(名前空間を作成した)または `at_cap`(拒否:トラストがすでに `--max-agents` 件作成済み) |
+| `loom.auth.trust_agents` | gauge | 有効なトラストの稼働中エージェント数(解放済みは数えない)。上限の数え方と同じ。workers-lease の保持者が 5 分ごとに計算 |
+| `loom.auth.trust_agents_used_ratio` | gauge | `loom.auth.trust_agents` をトラストの `--max-agents` で割った値。1 になると新しいエージェントはすべて拒否されます |
+
+
+
+### 検索品質
+
+高速だが誤った検索は、HTTP メトリクスでは見えません。以下のメトリクスでそれを検出します。
+
+| メトリクス | 型 | 意味 |
+| --------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------ |
+| `loom.search.results` | histogram | 検索ごとの結果数。0 に近づく傾向は、気づきにくい破損を示します |
+| `loom.search.top_similarity` | histogram | 最上位ヒットのコサイン類似度。検索で最も診断に役立つシグナル(埋め込みモデルを変更したら基準を取り直す) |
+| `loom.search.confidence` | histogram | レスポンスの `retrieval_confidence` |
+| `loom.search.abstain` | counter | 回答を控えた検索。`reason` 別 |
+| `loom.search.plane_hits` | counter | 検索プレーンごとのヒット数 |
+| `loom.search.assist` | counter | 作動したオプションの補助(HyDE、rerank、反復ジャッジ)。`kind` 別 |
+| `loom.search.judged_relevance` | histogram | サンプリングした検索に対する独立した LLM ジャッジの評価(`LOOM_RETRIEVAL_JUDGE_SAMPLE_RATE`、デフォルト 0) |
+| `loom.search.judge_verdict` | counter | ジャッジの判定のカテゴリ別件数 |
+| `loom.search.bm25_stats_failures` | counter | フェイルオープンした BM25 コーパス統計の読み取り失敗(語彙側が重みなしで実行された)。プレーンとエラー別 |
+| `loom.memory.search.enumeration_shaped` | counter | 保存済みレコードをクラスとして列挙する言い回しの検索。拒否ではなくシグナル |
+
+
+
+### メモリの書き込み
+
+| メトリクス | 型 | 意味 |
+| ---------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `loom.memory.writes` | counter | 書き込み結果:created、updated、merged、duplicate、conflicted、rejected、blacklisted、too_large など |
+| `loom.memory.drops` | counter | 取り込みパイプラインが破棄または切り詰めた項目。`stage` と `reason` 別(`loom.memory_drops` の行) |
+| `loom.memory.attribute_tagged` | counter | 書き込み時に `attribute:` というラベルが付いた行 |
+| `loom.policy.decisions` | counter | 履歴ポリシーゲートの判定 |
+| `loom.procedure.runs`, `loom.procedure.evolve` | counter | 結果別の手順の実行数。`procedure.evolve` の結果 |
+| `loom.memory.agent_labels_24h` | gauge | 過去 24 時間にエージェントが書いた使用ラベル数。名前空間ごと(上位 `LOOM_OTEL_AGENT_LABELS_MAX_NAMESPACES` 件、残りは `other`) |
+| `loom.memory.agent_labels_namespaces_at_pace` | gauge | エージェントラベルが 1 日あたりのペース(月 1,000 件)に達している名前空間の数。組織ごと |
+
+`loom drops --namespace NS [--hours 24]` は、ステージと理由ごとの破棄件数を表示します。完全に失敗した抽出は破棄には含まれません。`set_from_messages` は 502 `EXTRACTION_FAILED` を返し、部分的な失敗はレスポンスの `pipeline_errors` に入ります。
+
+
+
+### バックログとプロセスの状態
+
+レベルは 0 でないことが通常で、時間とともに減っていくものです。
+
+| メトリクス | 型 | 意味 |
+| ---------------------------------------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `loom.embed.pending` | gauge | ベクトル待ちの行(`embedding_dim = 0`)。まだ検索できないメモリ |
+| `loom.vectors.total` | gauge | 存在する埋め込み済みベクトルの数 |
+| `loom.vector_index.searches_total`, `adds_total`, `reads_indexed_ratio` | gauge | プローブしたレプリカでのベクトルインデックスの利用状況:支払った構築コストに対して処理した検索数と、最近のベクトル読み取りのうちインデックスを開いたものの割合 |
+| `loom.process.open_fds`, `loom.process.fd_limit` | ゲージ | プロセスごとの開いているディスクリプタ数とソフトリミット(`loom.pid`)。右肩上がりの線はリークを示す |
+| `loom.host.disk.free_bytes`, `loom.host.disk.total_bytes` | ゲージ | `var/` を保持するディスクの空きバイト数と総バイト数 |
+| `loom.ch.mutations_pending` | ゲージ | 未完了の ClickHouse ミューテーション |
+| `loom.ch.table.active_parts`, `wide_parts`, `patch_parts`, `bytes_on_disk`, `rows_per_mark` | ゲージ | ハウスキーピング対象のテーブルごと(`loom.table`) |
+| `loom.memory_embeddings.patch_parts` | ゲージ | `loom.memory_embeddings` のパッチパート数。0 以外になると量子化コードの読み取りが無効になる |
+| `loom.ch.view_refresh.scheduled`, `loom.ch.view_refresh.age_s` | ゲージ | リフレッシュ可能ビューごと(`loom.view`。`loom` 内のものはビュー名のみ、それ以外はデータベース付き:`loom_telemetry.sli_minute_refresh`)。エラーなしでスケジュールされている間は 1。最後に成功してからの秒数 |
+| `loom.sli.rollup_lag_s` | ゲージ | 直近のストレージプローブ(5 分ごと、workers-lease 保持者が実行)の時点で、`loom_telemetry.sli_minute` のマークが現在時刻から遅れていた秒数。最新であれば約 70 から 130。それより大きい場合はロールアップが追いつき中で、最新の数分は空に見える |
+| `loom.sli.rollup_missed_rows` | ゲージ | 直近 1 日の台帳のリクエスト行のうち、ロールアップのマークが通過した後に insert がコミットされたため、`sli_minute` が集計しないもの(ストレージプローブ、5 分ごと、workers-lease 保持者が実行)。0 を超えたらアラートを出し、ロールアップを再集計する |
+| `loom.audit.checkpoint_lag_windows` | ゲージ | チェックポイントチェーンにまだ封印されていない 1 時間単位の監査ウィンドウ数([監査ログ](https://github.com/ClickHouse/loom/blob/main/docs/features/observability/audit.md#checkpoint-lag)) |
+| `loom.langfuse.breaker` | ゲージ | Langfuse スコアのブレーカー。0 は閉、1 は半開、2 は開(スコアは破棄される。スパンのエクスポートには影響しない) |
+| `loom.health.problems` | ゲージ | このプロセスで開いている `/v1/health` の問題 1 件につき 1。`code` と `severity`(`provider_failing` では `provider`)別。ただし `/v1/health` が ClickHouse の読み取りで検出するもの(`otel_erasure_index`)は除く。解決した問題は報告されなくなるため、アラートは少なくとも `LOOM_OTEL_GAUGE_HEARTBEAT_S` に `LOOM_OTEL_METRICS_EXPORT_INTERVAL_S` を 1 つ加えた期間(ハートビートなしの 2 インターバル)のウィンドウで読む。`ch` エクスポーターとハートビートを使う場合、値が変わらなくても各ハートビート後の最初のエクスポートで書き込まれる |
+| `loom.ledger.dropped` | カウンター | このプロセスが起動以降に失った台帳行。`reason` 別(`queue_full`、`flush_failed`、`batch_repeat`:MCP バッチが 10 行を超えて書き込まなかったサーバー障害)。SLI はその分だけ過少に計上される |
+| `loom.ledger.batch_repeats` | カウンター | MCP バッチが再度書き込まなかった、呼び出し元の拒否行(バッチごとに 1 回台帳に記録される)。呼び出し元に起因するもので、損失ではない |
+| `loom.worker.passes` | カウンター | `worker` と `outcome` 別のパス数 |
+| `loom.worker.pass_duration_ms` | ヒストグラム | パスの実時間 |
+| `loom.worker.consecutive_failures` | ゲージ | ワーカーごとの現在の連続失敗数。3 でアラート |
+| `loom.worker.partial_failures` | ゲージ | 直近のパスが耐えた失敗数 |
+| `loom.retention.active_rows`, `never_recalled_ratio`, `low_information_rows`, `sensitive_without_expiry`, `stale_candidates` | ゲージ | 組織ごとのメモリ衛生カウント。Loom は経過時間では何も削除しない |
+
+
+
+### Postgres パブリケーションパイプライン
+
+`LOOM_STORAGE_AUTHORITY=postgres` の場合:書き込みが検索可能になるまでの時間と、ClickHouse にまだ届いていないもの(`loom.ch.inserts` はどちらの authority でも計上される)([パイプライン SLO](https://github.com/ClickHouse/loom/blob/main/docs/operations/monitoring.md#pipeline-slos))。
+
+| メトリクス | 種類 | 意味 |
+| --- | --- | --- |
+| `loom.pg.search_wait_ms` | ヒストグラム | 読み取りがバリアで、ClickHouse が名前空間の書き込みを保持するのを待った時間。`loom.operation`(リクエストが呼び出した op)、`outcome`(`passed`、またはデッドライン `LOOM_PG_PROJECTION_WAIT_MS`、もしくは再入パスの残り時間に達した場合の `deadline`。その op は 503 `PROJECTION_BEHIND` を返し、レポートは projection の読み取りを省略してよい)、`loom.traffic_class` 別。遅れを検出した読み取りのみ |
+| `loom.pg.projection_lag_ms` | ヒストグラム | リビジョンのコミットトランザクションの開始から、その配信が最後の検索ターゲットを解消するまで。Postgres の時計で計測し、`path`(flush、redelivered)別。ドキュメントが反映されたか、再配信でリビジョンがもう提供されていない(削除済み、またはキーが移った)ことが分かり、未送信のまま決着した場合 |
+| `loom.pg.backlog` | ゲージ | 未配信の配信数。`source`(memory、audit_outbox、knowledge)と `state`(pending、parked)別。それぞれ `LOOM_PG_BACKLOG_COUNT_CAP` までカウントする。memory の pending は検索が待つ対象 |
+| `loom.pg.oldest_pending_age_s` | ゲージ | `source` 別の最も古い pending 配信の経過時間。memory はコミットトランザクションの開始から、knowledge はそのソースの最新コミットから計測し、いずれもリース順の先頭 `LOOM_PG_BACKLOG_COUNT_CAP` 件が対象。監査アウトボックスは、期限を過ぎた全行を対象に、期限超過の秒数で表す |
+| `loom.pg.backlog_reading_age_s` | ゲージ | 各ソースのバックログを読んでからの秒数(読み取りが新しい間)。2 エクスポート期間にわたって読み取りがないと、バックログのゲージは停止する |
+| `loom.ch.inserts`, `loom.ch.insert_rows` | カウンター | メモリ書き込みパスによるメモリ行と検索ドキュメントの insert、および監査ライターの insert と、その行数。`table` 別。`memory` と `memory_embeddings` の insert はコミットされ、1 回ごとに 1 パートとなる。`audit_log` の insert はデフォルトでバッチ処理される(`LOOM_CH_BATCHED_INSERTS`) |
+
+バックログは配信ワーカーが各パスの最初に読み取り、それらを実行するプロセス(デフォルトではワーカーの子プロセス、そうでなければ workers-lease 保持者)がエクスポートする。複数のプロセスが同時にエクスポートすることがあり(`LOOM_BACKGROUND_WORKERS=on`、リースの引き継ぎ)、それぞれがデプロイメント全体のバックログを報告する。これらのゲージは `sum` ではなく `max` で集計すること。
+
+
+
+### 整合性の不変条件
+
+いずれも常に 0 であるべきです。0 以外の値は、すでに発生した欠陥であり、自然には解消しません。
+
+| メトリクス | 0 以外の値の意味 | 対処 |
+| --------------------------------------------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------- |
+| `loom.integrity.divergent_entities` | あるメモリについて、`loom.memory` と `loom.memory_embeddings` でエンティティが異なっている | 書き込みパスを調査する |
+| `loom.integrity.orphan_vectors` | 対応するメモリ行が失われた埋め込みベクトル | `orphan_vector_reconcile` ワーカー |
+| `loom.integrity.orphan_entity_vectors` | 対応するメモリ行が失われたエンティティベクトル | `orphan_vector_reconcile` ワーカー |
+| `loom.integrity.orphan_graph_namespaces` | エンティティエッジはあるが、有効なメモリもナレッジもない名前空間 | `loom erasure-re-verify --orphan-graph --erase` |
+| `loom.integrity.live_ns_unregistered`, `live_rows_unregistered` | `loom.namespaces` に行がない名前空間にある有効なメモリ | 名前空間を登録する |
+| `loom.integrity.dim0_with_vector` | ベクトルはあるが `embedding_dim = 0` のため、検索で見えない行 | `loom integrity-repair --apply` |
+| `loom.integrity.tombstone_status_drift` | `tombstoned_at` が設定されているのに、別のステータスになっている行 | `loom integrity-repair` が一覧表示する |
+| `loom.integrity.active_past_valid_to` | 自身の `valid_to` を過ぎても active のままの行 | `loom integrity-repair` が一覧表示する |
+| `loom.integrity.high_with_embedding` | 機密度が high で、有効な埋め込み行がまだ残っている行 | `loom sensitivity-sweep --apply` |
+
+
+
+### コードプレーン
+
+名前空間ごとのメトリクスです。
+
+| メトリクス | 種類 | 意味 |
+| ----------------------------------------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `loom.code.index_lag_commits` | gauge | インデックスのウォーターマークとブランチ先端の間にあるコミット数。古さを示すシグナル |
+| `loom.code.index_age_seconds` | gauge | ウォーターマークが最後に進んでからの秒数 |
+| `loom.code.stale_files` | gauge | チャンクが head 時点のファイル内容より古い、インデックス済みパスの数 |
+| `loom.code.scip_lag_commits`, `scip_age_seconds`, `scip_py_age_seconds` | gauge | 各コンパイラティア(`tier` 属性)が高速ティアにどれだけ遅れているか |
+| `loom.code.tier_lag_seconds` | gauge | ティア(`fast`、`clang`、`python` など)がまだ到達していない最も古いコミットの経過時間 |
+| `loom.code.tier_failing` | gauge | `code_tier_failing` ヘルス問題が報告する各ティアの連続失敗パス数。`tier`、エラー `kind`、および問題が評価するティアの `severity` ごと |
+| `loom.code.tier_lag_commits` | gauge | それらの各ティアが取得済みの先端に遅れているコミット数(下限値:エントリが最後に公開したステータスで数えたもの)。`tier` ごと。遅れが判明している間に報告される |
+| `loom.code.pr_cursor_age_seconds` | gauge | PR 履歴の同期が GitHub にどれだけ遅れているか |
+| `loom.code.files_errored`, `loom.code.embed_backlog` | gauge | インデックスエラーのあるファイル数、ベクトル待ちのチャンク数 |
+| `loom.code.symbols` | gauge | `tier`(`treesitter`、`scip`)ごとの有効なシンボル数。減少した場合は不正な適用を示す |
+| `loom.code.edges_unqualified`, `loom.code.edges_low_confidence` | gauge | 名前のみで束縛されたパーサティアの呼び出しエッジ。`loom.code.symbols` と比較する |
+| `loom.code.grep.wrong_abstain_24h` | gauge | コーパスに存在するリテラルに対して `code.grep` が回答を控えた件数。上位 8 件のコンシューマーと `other`(`LOOM_OTEL_CODE_GREP_REPLAY_CACHE_S` ごとに再集計。0 = オフ) |
+| `loom.code.repos_config_errors` | gauge | `LOOM_CODE_REPOS_JSON` 内の使用できないエントリ数(0 = 問題なく解析された) |
+| `loom.code.outcome`, `loom.code.shunt`, `loom.code.shunt_tokens_saved` | counter | クライアントが報告した結果。コーディングエージェントの shunt の判断と、コンテキストに入れずに済んだトークン数 |
+| `loom.code.ask_cache`, `ask_cache_saved_ms`, `ask_cache_saved_usd` | counter | `code.ask` の回答キャッシュの結果と、ヒットによる節約量 |
+| `loom.tracker.sections`, `loom.tracker.section_ms` | カウンター、ヒストグラム | テンプレートとステータスごとの `tracker.answer` セクション数、および読み取り時間 |
+
+遅延ゲージが呼び出し側にとって何を意味するかは、[コードインデックスの鮮度](https://github.com/ClickHouse/loom/blob/main/docs/features/code-index/freshness.md)を参照してください。
+
+
+
+### 推奨アラート
+
+| 条件 | 理由 |
+| ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `loom.search.top_similarity` の平均が、ベースラインを 30 分間下回る | 検索品質が低下した(エンベッダーまたはインデックスの変更) |
+| `loom.embed.pending` が 15 分間 100 を超える | 新しいメモリが検索可能になっていない |
+| いずれかの `loom.integrity.*` が 0 を超える | データ不整合が発生した |
+| `loom.worker.consecutive_failures` ≥ 3 | ワーカーが失敗を繰り返している |
+| `loom.process.open_fds / loom.process.fd_limit` が 0.5 を超える | ディスクリプタのリーク |
+| `loom.host.disk.free_bytes / loom.host.disk.total_bytes` が 0.10 を下回る | データディスクが逼迫している |
+| `loom.langfuse.breaker` = 2 | Langfuse へのスコアが破棄されている |
+| `loom.audit.checkpoint_lag_windows` が数時間にわたって増加している | 監査シーラーが停止している |
+| `loom.code.index_lag_commits` が 15 分間、1 パスあたりのコミット予算を超える | コードの取り込みが遅れている |
+| `loom.code.tier_lag_seconds` が 10 分間 1800 を超える | コンパイラティアが停止している(`deploy/dashboards/code_plane.json` の「code tier lag」アラート。しきい値は最も遅いティアの通常サイクルより大きく設定する) |
+| trust ごとの `loom.auth.agents_provisioned{outcome=made}` が、そのコントロールプレーンの通常の頻度を超える(10 分間に 50 から始める) | trust が、フリートの増加より速く新しいエージェントを命名している:発行者キーの漏えい、またはコントロールプレーンの暴走 |
+| `loom.auth.trust_agents_used_ratio` が 0.8 を超える | trust が `--max-agents` に近づいている |
+| `loom.auth.agents_provisioned{outcome=at_cap}` が 10 分間で 0 を超えて増加する | その trust の新しいエージェントが拒否されている |
+
+HyperDX では、空の結果は 0 として読み取られます。そのため、最小サンプル数のガードは、行を返さないのではなく、正常範囲内の値を返す必要があります。
+
+開始用のクエリ:
+
+```sql
+-- mean top similarity per namespace, last hour
+SELECT Attributes['loom.namespace'] AS ns,
+ round(anyLast(Sum) / greatest(anyLast(Count), 1), 3) AS mean_top_similarity
+FROM default.otel_metrics_histogram
+WHERE MetricName = 'loom.search.top_similarity' AND TimeUnix > now() - INTERVAL 1 HOUR
+GROUP BY ns;
+
+-- every gauge's latest value
+SELECT MetricName, anyLast(Value) AS latest
+FROM default.otel_metrics_gauge
+WHERE TimeUnix > now() - INTERVAL 5 MINUTE
+GROUP BY MetricName ORDER BY MetricName;
+```
+
+
+
+## ClickHouse でのクエリ帰属
+
+すべての ClickHouse クエリには、発行元を示す `log_comment` 設定が付きます。リクエストの場合は `
+`、ワーカーのパスの場合は `worker.`、CLI コマンドの場合は `cli.`、それ以外の場合は `untagged:.