diff --git a/.claude/rules/docs.md b/.claude/rules/docs.md
index 0cca94b10b..27ee15f982 100644
--- a/.claude/rules/docs.md
+++ b/.claude/rules/docs.md
@@ -13,4 +13,4 @@ paths:
- Generated pages and regions under `docs/reference/` come from their generators (`settings_reference.py`, `docs_reference.py`); never hand-edit them.
- Relative links and `#anchors` must resolve (`test_doc_links.py`).
- Follow the [documentation style guide](../../docs/development/documentation-style.md).
-- `i18n//` holds machine translations of the README, the quickstart and the use-case pages, generated by `scripts/i18n/translate.py` after an English edit lands on main (`.github/workflows/i18n.yml`); never edit them by hand, and edit the English page instead. A new page in that set goes into `SOURCES`, and the PR that adds it commits a translation for each entry in `LANGUAGES`, made with `python -m scripts.i18n.translate update` and AWS credentials that can invoke the model on Bedrock ([translations](../../CONTRIBUTING.md#translations); `test_i18n.py` requires every page); after a change to the prompt, a banner or the model, run the workflow with `all` (a new model needs the runner role's policy changed first).
+- `i18n//` contains machine translations of tracked `README.md` and `docs/**/*.md`, including generated references. Edit English or its generator, never translations by hand. `.github/workflows/i18n.yml` queues bounded batches after English merges to main; ordinary PRs may have pending coverage. `python -m scripts.i18n.translate check` reports missing, stale and obsolete output; `check --skip-stale` still validates present files and links. Verified replacements wait in `i18n/.pending//` until their link dependencies permit publication. The updater reuses validated generated data from `i18n/update`, never branch code, and deletes only stamped obsolete output after inbound links are repaired. Paid calls require an explicit cumulative allowance and durable reservations ([translations](../../CONTRIBUTING.md#translations)). After a prompt change, request `update --all`; another model also needs the runner role's policy changed.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index dd6e154d42..8480bd9696 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -6,6 +6,12 @@ on:
branches: [main, "release/**"]
pull_request:
branches: [main, "release/**"]
+ workflow_dispatch:
+ inputs:
+ expected_sha:
+ description: Exact generated translation commit to validate
+ required: true
+ type: string
# A new push to a pull request cancels its superseded run. Every push (to main
# or a release/X.Y line) runs to completion in its own group, so a failure on
@@ -25,7 +31,26 @@ env:
UV_VERSION: "0.12.19"
jobs:
+ validate-ref:
+ name: validate requested commit
+ runs-on: ubuntu-latest
+ timeout-minutes: 2
+ steps:
+ - name: Bind a dispatched run to its generated commit
+ env:
+ EVENT: ${{ github.event_name }}
+ REF: ${{ github.ref }}
+ SHA: ${{ github.sha }}
+ EXPECTED_SHA: ${{ inputs.expected_sha }}
+ run: |
+ if [ "$EVENT" = "workflow_dispatch" ]; then
+ test "$REF" = "refs/heads/i18n/update"
+ [[ "$EXPECTED_SHA" =~ ^[0-9a-f]{40}$ ]]
+ test "$SHA" = "$EXPECTED_SHA"
+ fi
+
clickhouse:
+ needs: validate-ref
name: the ClickHouse release this run tests
runs-on: ubuntu-latest
timeout-minutes: 10
@@ -43,6 +68,7 @@ jobs:
echo "image=$image" >> "$GITHUB_OUTPUT"
lint:
+ needs: validate-ref
name: ruff + mypy-gate
runs-on: ubuntu-latest
timeout-minutes: 15
@@ -112,7 +138,7 @@ jobs:
# coverage data and applies the floors.
unit:
name: pytest unit part ${{ matrix.part }}
- needs: clickhouse
+ needs: [validate-ref, clickhouse]
runs-on: ubuntu-latest
timeout-minutes: 30
strategy:
@@ -186,7 +212,7 @@ jobs:
unit-coverage:
name: pytest unit coverage, floors and bench
- needs: unit
+ needs: [validate-ref, unit]
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
@@ -244,6 +270,7 @@ jobs:
path: coverage.xml
sandbox:
+ needs: validate-ref
name: repository-job sandbox (real bubblewrap)
runs-on: ubuntu-24.04
timeout-minutes: 15
@@ -279,7 +306,7 @@ jobs:
schema-check:
name: schema.sql in sync with migrations
- needs: clickhouse
+ needs: [validate-ref, clickhouse]
runs-on: ubuntu-latest
timeout-minutes: 15
env:
@@ -318,6 +345,7 @@ jobs:
run: make schema-check
ts-typecheck:
+ needs: validate-ref
name: tsc (frontend)
runs-on: ubuntu-latest
timeout-minutes: 15
@@ -340,6 +368,7 @@ jobs:
run: npm run budget
format:
+ needs: validate-ref
name: format (biome, prettier, taplo, shfmt)
runs-on: ubuntu-latest
timeout-minutes: 15
@@ -366,6 +395,7 @@ jobs:
run: git ls-files '*.sh' ':!tests/fixtures' | xargs shfmt -d
helm:
+ needs: validate-ref
name: helm chart (lint, kubeconform)
runs-on: ubuntu-latest
timeout-minutes: 10
@@ -390,7 +420,7 @@ jobs:
assistant=(--set assistant.enabled=true --set assistant.existingSecret=ci)
# TLS on Loom's port, which the assistant (in "all") cannot reach: its own render.
tls=(--set tls.secretName=ci --set 'ingress.annotations.alb\.ingress\.kubernetes\.io/backend-protocol=HTTPS' --set workers.enabled=true --set networkPolicy.enabled=true "${on[@]}" "${extractor[@]}")
- all=(--set workers.enabled=true --set workers.replicaCount=2 --set autoscaling.enabled=true --set networkPolicy.enabled=true --set alerts.prometheusRule.enabled=true --set mustMatchChange.publish=ci --set settingsFile.memory_ask_recency_weight=0.3 "${on[@]}" "${extractor[@]}" "${assistant[@]}")
+ all=(--set workers.enabled=true --set workers.replicaCount=2 --set autoscaling.enabled=true --set networkPolicy.enabled=true --set alerts.prometheusRule.enabled=true --set mustMatchChange.publish=ci --set cellProbe.port=8777 --set settingsFile.memory_ask_recency_weight=0.3 "${on[@]}" "${extractor[@]}" "${assistant[@]}")
# The PrometheusRule's schema: the CRD catalog at a pinned commit.
crd='https://raw.githubusercontent.com/datreeio/CRDs-catalog/c86448cbf1a840ca62d119259864863897c8748a/{{.Group}}/{{.ResourceKind}}_{{.ResourceAPIVersion}}.json'
@@ -465,8 +495,11 @@ jobs:
# TLS on Loom's port: the Secret's mount, the settings, HTTPS probes, and the refusals.
- name: tls
run: python3 -m scripts.gates.helm_tls
+ - name: private cell probe
+ run: python3 -m scripts.gates.helm_cell_probe
agent-plugins:
+ needs: validate-ref
name: coding-agent plugins (node --test)
runs-on: ubuntu-latest
timeout-minutes: 15
@@ -498,6 +531,7 @@ jobs:
# The dashboard's vitest and Playwright suites share nothing but `npm ci`, so
# each runs as its own job, split into parts on separate runners.
frontend-vitest:
+ needs: validate-ref
name: frontend vitest part ${{ matrix.part }}
runs-on: ubuntu-latest
timeout-minutes: 20
@@ -524,6 +558,7 @@ jobs:
# With fullyParallel: false, --shard splits by spec file per project, not by test.
frontend-e2e:
+ needs: validate-ref
name: frontend playwright part ${{ matrix.part }}
runs-on: ubuntu-latest
timeout-minutes: 20
@@ -566,7 +601,7 @@ jobs:
# analyzer corpus.
integration:
name: pytest integration ${{ matrix.part == 'isolation' && 'isolation gates' || format('part {0} of 4', matrix.part) }}
- needs: clickhouse
+ needs: [validate-ref, clickhouse]
runs-on: ubuntu-latest
timeout-minutes: 45
strategy:
@@ -721,13 +756,16 @@ jobs:
done
curl -sf http://127.0.0.1:5000/ >/dev/null
echo "LOOM_TEST_S3_ENDPOINT=http://127.0.0.1:5000" >> "$GITHUB_ENV"
- # The whole directory on every pull request, split over the parts; no test
- # is slow enough to justify a separate merge-only tier.
+ # Split ordinary integration cases over the parts. Signed mirror HTTP cases
+ # run in the authenticated isolation step below on every pull request.
- name: pytest (this part of tests/integration)
if: matrix.part != 'isolation'
env:
LOOM_TEST_SHARD: ${{ matrix.part }}/4
- run: pytest tests/integration -q --durations=20
+ run: >-
+ pytest tests/integration -q --durations=20
+ --ignore=tests/integration/test_mirror_checked_search_http.py
+ --ignore=tests/integration/test_mirror_checked_list_http.py
- name: Native Google ADK live tests (Python and TypeScript)
if: matrix.part == '1'
run: python -m tests.integration._google_adk_ci "$RUNNER_TEMP/loom-adk-client"
@@ -777,6 +815,8 @@ jobs:
tests/integration/test_run_begin_claims.py
tests/integration/test_mcp_session_run_scope.py
tests/integration/test_projection_failures_restricted.py
+ tests/integration/test_mirror_checked_search_http.py
+ tests/integration/test_mirror_checked_list_http.py
# The statement corpus: every builder's shapes through
# EXPLAIN QUERY TREE on the migrated service, and shapes.txt in step
# with the builders. ~10 s; a rejection here is a statement that would
@@ -796,7 +836,7 @@ jobs:
integration-postgres:
name: pytest integration (Postgres ${{ matrix.postgres }} memory authority)
- needs: clickhouse
+ needs: [validate-ref, clickhouse]
runs-on: ubuntu-latest
timeout-minutes: 60
# The oldest supported major and the newest.
@@ -929,6 +969,23 @@ jobs:
tests/integration/test_cell_unset_gate_pg.py
tests/integration/test_cell_prepare.py
tests/integration/test_cell_org_triggers_pg.py
+ tests/integration/test_source_access_store.py
+ tests/integration/test_source_document_store.py
+ tests/integration/test_mirror_reader_evidence.py
+ tests/integration/test_mirror_session_latch_native.py
+ tests/integration/test_mirror_search_chunk_keys.py
+ tests/integration/test_mirror_title_projection.py
+ tests/integration/test_mirror_ask_http.py
+ tests/integration/test_marked_admin_events_native.py
+ tests/integration/test_marked_analytics_export_native.py
+ tests/integration/test_marked_assistant_ledger_native.py
+ tests/integration/test_marked_cost_summary_native.py
+ tests/integration/test_marked_derived_activity_native.py
+ tests/integration/test_marked_event_readers_native.py
+ tests/integration/test_marked_mentor_agents_native.py
+ tests/integration/test_marked_rollup_migration_native.py
+ tests/integration/test_marked_durable_folds_native.py
+ tests/integration/test_marked_sql_surface_native.py
# The tenant-isolation gates again, against a second server that enforces auth:
# the Postgres read paths (heads by key and by id, narrowed scopes) see real tokens.
# They run whether or not the memory suites passed (`!cancelled()`).
@@ -938,6 +995,7 @@ jobs:
env:
LOOM_AUTH_REQUIRED: "true"
LOOM_INSTANCE_LABEL: "ci:integration-postgres-auth"
+ LOOM_CH_ANALYSIS_PROBE_INTERVAL_S: "10"
run: |
LOOM_WEB_WORKERS=3 PORT=7778 nohup sh scripts/serve.sh > server-auth.log 2>&1 &
for _ in $(seq 1 60); do
@@ -957,6 +1015,7 @@ jobs:
env:
LOOM_AUTH_REQUIRED: "true"
LOOM_BASE_URL: http://localhost:7778
+ LOOM_CH_ANALYSIS_PROBE_INTERVAL_S: "10"
run: >-
pytest -q
tests/integration/test_cross_principal_leakage.py
@@ -967,6 +1026,9 @@ jobs:
tests/integration/test_mcp_session_run_scope.py
tests/integration/test_onboard_tenant.py
tests/integration/test_blacklist.py
+ tests/integration/test_mirror_checked_search_http.py
+ tests/integration/test_mirror_checked_list_http.py
+ tests/integration/test_analysis_isolation.py
tests/integration/test_sensitivity_high_canary.py
tests/integration/test_pg_authority.py
-k "not test_a_duplicate_never_resolves_to_a_canonical_outside_the_scope
@@ -986,9 +1048,12 @@ jobs:
server-auth.log
mixed-version:
+ needs: [validate-ref, clickhouse]
name: builds N-1 and N on one ClickHouse
runs-on: ubuntu-latest
timeout-minutes: 30
+ env:
+ LOOM_CLICKHOUSE_IMAGE: ${{ needs.clickhouse.outputs.image }}
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
@@ -1018,8 +1083,11 @@ jobs:
# target branch's tip can carry a newer migration by the time the run starts.
- name: Mixed-version gate
run: python scripts/gates/mixed_version.py --require --base HEAD~1
+ - name: Published build ordinary-event compatibility
+ run: python scripts/gates/mixed_version.py --require --base 1cbaf0411114512957b96ec5ea7bbb8058828543
sdk-typescript:
+ needs: validate-ref
name: typescript sdk (generated types in sync, lint, tsc, vitest, dist)
runs-on: ubuntu-latest
timeout-minutes: 15
@@ -1064,6 +1132,7 @@ jobs:
run: npm run check:dist
sdk-python-adapters:
+ needs: validate-ref
name: python sdk adapters (py ${{ matrix.python }}${{ matrix.lowest && ', lowest deps' || '' }})
runs-on: ubuntu-latest
timeout-minutes: 15
@@ -1091,6 +1160,7 @@ jobs:
run: make test-sdk-adapters SDK_ADAPTERS_PYTHON="$(which python)" SDK_ADAPTERS_RESOLUTION="${{ matrix.lowest && 'lowest-direct' || 'highest' }}"
sdk-python-package:
+ needs: validate-ref
name: python sdk wheel (py ${{ matrix.python }}${{ matrix.lowest && ', lowest deps' || '' }})
runs-on: ubuntu-latest
timeout-minutes: 15
diff --git a/.github/workflows/docs-site.yml b/.github/workflows/docs-site.yml
index eb81d4e88e..ff35d3117f 100644
--- a/.github/workflows/docs-site.yml
+++ b/.github/workflows/docs-site.yml
@@ -12,6 +12,7 @@ on:
branches: [main]
paths:
- "docs/**"
+ - "i18n/**"
- "mkdocs.yml"
- "llms.txt"
- "llms-install.md"
diff --git a/.github/workflows/i18n.yml b/.github/workflows/i18n.yml
index 4b1954769c..9e61a83ada 100644
--- a/.github/workflows/i18n.yml
+++ b/.github/workflows/i18n.yml
@@ -1,25 +1,24 @@
name: translations
-# Keeps i18n// in step with the English pages it translates. On a push to main that
-# changes the README or a page under docs/, and on a manual run, it translates the stale
-# pages with scripts/i18n/translate.py and opens or updates one pull request from the
-# branch i18n/update. After a change to the prompt, a banner or the model, run it by hand
-# with "all" to translate every page again. A pull request opened with the workflow token
-# starts no other workflow: close and reopen it to run CI. Needs "Allow GitHub Actions to
-# create and approve pull requests" (Settings → Actions → General).
-#
-# Claude is called on Amazon Bedrock with no credential stored in GitHub: the job runs on a
-# self-hosted runner in AWS whose instance role may invoke one model, and the SDK signs with
-# that role. The repository variable LOOM_I18N_RUNNER holds the runner's labels as JSON;
-# while it is empty the job is skipped. Only a push to main or a manual run reaches the
-# runner, never a pull request. The runner group and the role are described in
-# CONTRIBUTING.md#translations.
+# Main supplies every executable byte. The pending branch contributes generated data
+# only. Hosted CI is dispatched explicitly because GITHUB_TOKEN PRs suppress events.
on:
push:
branches: [main]
paths:
- "README.md"
- "docs/**"
+ - "scripts/i18n/**"
+ - "scripts/docs_site/messages.py"
+ - "scripts/docs_site/indexnow.py"
+ - "scripts/docs_site/paths.py"
+ - ".github/workflows/i18n.yml"
+ workflow_run:
+ workflows: [ci]
+ types: [completed]
+ branches: [i18n/update]
+ schedule:
+ - cron: "37 */6 * * *"
workflow_dispatch:
inputs:
all:
@@ -27,7 +26,7 @@ on:
type: boolean
default: false
languages:
- description: Language codes to translate, separated by spaces (empty for all)
+ description: Language codes separated by spaces (empty for all five or configured subset)
type: string
default: ""
@@ -41,87 +40,78 @@ concurrency:
jobs:
update:
name: update
- if: github.ref == 'refs/heads/main' && vars.LOOM_I18N_RUNNER != ''
+ if: github.ref == 'refs/heads/main' && contains(fromJSON('["push","schedule","workflow_dispatch"]'), github.event_name) && vars.LOOM_I18N_RUNNER != ''
runs-on: ${{ fromJSON(vars.LOOM_I18N_RUNNER) }}
timeout-minutes: 45
- # Limited to main (Settings → Environments); it records each run. What keeps other
- # workflows off the runner is the runner group's selected-workflow rule.
+ # Environment and runner-group restrictions admit this main-only workflow.
environment: i18n
permissions:
+ actions: write
contents: write
pull-requests: write
+ env:
+ LOOM_I18N_LANGUAGES: ${{ vars.LOOM_I18N_LANGUAGES }}
+ LOOM_I18N_BATCH_LANGUAGES: ${{ inputs.languages }}
defaults:
run:
- # Explicit bash runs with -o pipefail, so a failed translation fails its step.
shell: bash
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+ with:
+ ref: ${{ github.sha }}
+ fetch-depth: 0
- uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
with:
python-version: "3.12"
- - name: Find stale translations
- id: check
- env:
- ALL: ${{ inputs.all }}
- run: |
- if [ "$ALL" != "true" ] && python -m scripts.i18n.translate check; then
- echo "stale=false" >> "$GITHUB_OUTPUT"
- else
- echo "stale=true" >> "$GITHUB_OUTPUT"
- fi
- - name: Install the Bedrock client
- if: steps.check.outputs.stale == 'true'
+ - name: Install translation runtime
# A virtualenv in the job's temp directory: a self-hosted runner keeps its Python.
run: |
python -m venv "$RUNNER_TEMP/i18n"
"$RUNNER_TEMP/i18n/bin/python" -m pip install --quiet --require-hashes --no-deps \
--only-binary=:all: -r scripts/i18n/requirements.txt
echo "$RUNNER_TEMP/i18n/bin" >> "$GITHUB_PATH"
- - name: Translate
+ - name: Preserve verified pending pages
+ id: prepare
+ run: python -m scripts.i18n.automation prepare
+ - name: Translate a bounded batch
id: translate
- if: steps.check.outputs.stale == 'true'
env:
- LOOM_I18N_MAX_USD: "5"
- ALL: ${{ inputs.all && '--all' || '' }}
- LANGUAGES: ${{ inputs.languages }}
+ LOOM_I18N_TOTAL_USD: ${{ vars.LOOM_I18N_TOTAL_USD || '0' }}
+ ALL: ${{ inputs.all }}
run: |
- # The runner's region, or us-east-1 when it sets none; the role's policy names it.
export AWS_REGION="${AWS_REGION:-${AWS_DEFAULT_REGION:-us-east-1}}"
- args=($ALL)
- for code in $LANGUAGES; do args+=(--lang "$code"); done
- if python -m scripts.i18n.translate update "${args[@]}" 2>&1 | tee -a "$GITHUB_STEP_SUMMARY"; then
- echo "ok=true" >> "$GITHUB_OUTPUT"
- else
- echo "ok=false" >> "$GITHUB_OUTPUT"
- fi
- # The pages written passed the verifier; links, anchors and labels across i18n/
- # must hold before anything is pushed.
- python -m scripts.i18n.translate check --skip-stale
- - name: Open or update the pull request
- if: steps.check.outputs.stale == 'true'
+ args=()
+ if [ "$ALL" = "true" ]; then args+=(--all); fi
+ python -m scripts.i18n.automation update "${args[@]}" 2>&1 | tee -a "$GITHUB_STEP_SUMMARY"
+ - name: Validate and publish for hosted CI
+ if: ${{ !cancelled() && steps.prepare.outcome == 'success' && steps.translate.outcome != 'skipped' }}
env:
GH_TOKEN: ${{ github.token }}
- SOURCE_SHA: ${{ github.sha }}
- run: |
- git config user.name "github-actions[bot]"
- git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
- git switch -C i18n/update
- git add README.md i18n
- if git diff --cached --quiet; then
- echo "no page was translated"
- exit 0
- fi
- git commit -s -q -m "Translations follow ${SOURCE_SHA::9}"
- git push --force origin i18n/update
- title="Translations follow ${SOURCE_SHA::9}"
- body="Machine translations of the pages changed up to ${SOURCE_SHA}, generated by \`scripts/i18n/translate.py\`. Close and reopen this pull request to run CI."
- if [ -z "$(gh pr list --head i18n/update --state open --json number --jq '.[].number')" ]; then
- gh pr create --head i18n/update --base main --title "$title" --body "$body"
- else
- gh pr edit i18n/update --title "$title" --body "$body"
- fi
- - name: Fail when a page was not translated
- if: steps.translate.outputs.ok == 'false'
+ LOOM_I18N_PENDING_SHA: ${{ steps.prepare.outputs.pending_sha }}
+ run: python -m scripts.i18n.automation publish
+
+ finalize:
+ name: merge validated translations
+ if: github.ref == 'refs/heads/main' && (github.event_name == 'schedule' || (github.event_name == 'workflow_run' && github.event.workflow_run.event == 'workflow_dispatch'))
+ runs-on: ubuntu-latest
+ timeout-minutes: 10
+ permissions:
+ actions: write
+ contents: write
+ pull-requests: write
+ steps:
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+ with:
+ ref: main
+ fetch-depth: 0
+ - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+ with:
+ python-version: "3.12"
+ - name: Install the site builder
run: |
- echo "some pages failed; the pull request carries the ones that passed"
- exit 1
+ python -m pip install --require-hashes --no-deps --only-binary=:all: -r scripts/docs_site/requirements.txt
+ - name: Merge the successful exact head and publish the site
+ env:
+ GH_TOKEN: ${{ github.token }}
+ LOOM_I18N_LANGUAGES: ${{ vars.LOOM_I18N_LANGUAGES }}
+ run: python -m scripts.i18n.automation finalize
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 7350efe7e6..a7fba601c2 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -144,12 +144,19 @@ An operation or field may be renamed or removed. Say so in the PR description an
## Translations
-`i18n//` holds machine translations of the README, the quickstart and the use-case pages. `scripts/i18n/translate.py` writes them and `.github/workflows/i18n.yml` runs it on main after an English page changes; never edit a translation by hand.
+The translation inventory includes every tracked `README.md` and `docs/**/*.md`, including generated references. `i18n//` holds the available machine translations. Edit English or its generator; never edit translations by hand. Inventory discovery includes nested additions and renames and excludes untracked or deleted files.
-The script calls Claude Sonnet 5.5 on Amazon Bedrock through the `anthropic` package's `AnthropicBedrock` client, which signs each request with the default AWS credential chain. To run it yourself, sign in to an AWS account where Bedrock serves the model and install the pinned client:
+English is canonical and the default. Simplified Chinese (`zh-CN`), Japanese (`ja`), Korean (`ko`), Brazilian Portuguese (`pt-BR`) and Spanish (`es`) are the five active translation locales for default generation and localized website rollout. An additional language requires evidence that its relevant developer audience expects local-language technical documentation. Keep English for an audience that expects English technical documentation. Country, native language and developer population do not establish a translation need. This evidence requirement governs future additions.
+
+With an allowance and the restricted runner configured, translation follows an English merge to main. It is asynchronous: the English PR can merge while coverage is pending. The workflow queues a bounded batch after relevant main pushes and every six hours. Changed existing translations precede missing pages. Relative links use an available translated target and anchor, otherwise the English page. A verified replacement that would break surviving links waits in `i18n/.pending//`; later batches reuse it. Obsolete pages are removed only after surviving inbound links are repaired, and only with a matching generator stamp, language and source path. Unknown files are refused. A source deletion that breaks a published English fallback must include the generated link repair: run `LOOM_I18N_MAX_USD=0 python -m scripts.i18n.translate update` to repair links without provider calls. Repair uses a published translation only when its requested anchor exists; otherwise validation blocks the deletion until the incoming page is repaired.
+
+`python -m scripts.i18n.translate check` reports every missing, stale and obsolete page across all five translation locales. `check --skip-stale` permits pending coverage but still checks present stamps, banners, links, anchors and translated labels, plus the content invariants of current output. Ordinary PR tests follow this asynchronous contract. A changed prompt requires an explicit `update --all`; a generated refresh receipt tracks that request across bounded scheduled batches and pending-branch reuse. Completed source/output proofs prevent repeated calls; the receipt stays until main contains those results. A concurrent main translation is preserved when it differs from the refresh's recorded base output. Model and banner changes invalidate stamps automatically.
+
+The updater imports only validated generated blobs from `i18n/update`, preserving fresh main output. Owned output outside a selected batch can remain as hidden checkpoint data after its English source changes or disappears. Such archives never become publication routes; activation still requires current source, model and content validation. A conflicting existing checkpoint refuses replacement so both versions remain recoverable. It executes no code from that branch. It dispatches hosted CI for the exact bot commit because PR events created with `GITHUB_TOKEN` do not start CI. A hosted finalizer checks the successful commit, generated diff, current main parent, current language approval and repository review requirements before merging. Required human reviews remain required. After merge it explicitly dispatches the docs-site workflow; publication also requires the site's deployment configuration. A newer main commit defers merging until the producer composes another batch.
+
+The script calls Claude Sonnet 5.5 on Amazon Bedrock through `AnthropicBedrock`. Local runs also spend money and require separate authorization. For an authorized run:
```bash
-# A separate virtualenv: the lock pins versions that differ from Loom's own.
python -m venv .venv-i18n && . .venv-i18n/bin/activate
python -m pip install --require-hashes --no-deps --only-binary=:all: -r scripts/i18n/requirements.txt
aws sso login
@@ -157,14 +164,16 @@ export AWS_REGION=
python -m scripts.i18n.translate update
```
-The workflow stores no credential in GitHub. Its job runs on a self-hosted runner in AWS, and the SDK signs with that runner's EC2 instance role, which may invoke the one model and nothing else. Every step of the job can use the role, so the job only runs on a push to main or a manual run on main, never on a pull request. The runner group's selected-workflow rule keeps every other workflow off the runner; the job's environment `i18n`, limited to main, records each run. While the repository variable `LOOM_I18N_RUNNER` is empty, the job is skipped.
+One batch shares an approximate USD 5 usage cap across every language. Before any workflow provider call, the updater books a conservative allowance covering every selected request, verifier retry, API retry and maximum output in the append-only `i18n/budget` branch. These reservations can greatly exceed the expected bill and are never refunded automatically, including after failures. `LOOM_I18N_TOTAL_USD` is the cumulative reservation ceiling, defaults to zero, and does not reset between runs or languages. An exhausted allowance defers work. A missing or invalid ledger refuses paid work. `LOOM_I18N_LANGUAGES` optionally restricts a batch to a space-separated subset of the five active translation locales. Unset or empty selects all five, as does the local update command by default. Other locale codes are refused. Manual language requests must stay within the configured subset and govern pending import, generation and publication together. Published output and checkpoints outside a selected batch stay intact. Automated maintenance changes only selected locales; present-link validation still covers retained files. A first translated README waits if publishing it would require changing an excluded locale or repairing a stale or conflicted README. Other selected pages continue. When a pending batch changes the English README’s generated language bar, importing it requires all affected locales. A partial run stops before generation or publication and retains the pending batch. An English deletion that breaks an unselected file requires a coordinated repair before it can pass validation. Raising the ceiling authorizes additional spending; a schedule cannot raise it.
-To turn translations on:
+The workflow stores no AWS credential in GitHub. Only main push, schedule and manual events may reach the role-bearing runner. Hosted CI and completion events cannot reach it. To activate authorized translation:
-1. Create the environment `i18n` with deployment branches set to `main` only (Settings → Environments).
-2. Get a runner group for this repository with "Allow public repositories" ticked (a group serves only private repositories otherwise, and the job would wait in the queue) and access limited to the selected workflow `ClickHouse/loom/.github/workflows/i18n.yml@refs/heads/main` (runner group settings → Workflow access → Selected workflows), so no other workflow and no fork's pull request can schedule a job on it. The runner image needs an OS that `actions/setup-python` supports, `git`, `bash` and the `gh` CLI.
-3. Give the runners' instance role the policy below. In the account, accept Bedrock's model access for Claude Sonnet 5.5 once: the first call can otherwise fail with an access-denied error about `aws-marketplace:Subscribe`, and the role is not granted those Marketplace actions.
-4. Set the repository variable `LOOM_I18N_RUNNER` to the runner group's labels as a JSON list, for example `["self-hosted","
+ );
+}
+
function LearningsPanel({
initialPending,
onSeedUsed,
@@ -877,6 +892,8 @@ function LearningsPanel({
{isAgentRule(r) && (r.proposed_value === null || r.proposed_value === "") ? (
// A user erasure took the rule's last supporter: only the decision is kept.
Rule removed by a user erasure; the decision stands.
{/* Click UI's ProgressBar sets no role or value, so the meter's ARIA is passed in.
Past the cap the bar stays full and the value text says by how much. */}
-
+ {pct !== null && budget.spent_24h_usd !== null && (
+
+ )}
Rolling 24h sum of upstream model and embedding cost on this namespace. {COST_CAP_EFFECT}
diff --git a/i18n/.pending/es/docs/concepts/retrieval-and-ranking.md b/i18n/.pending/es/docs/concepts/retrieval-and-ranking.md
new file mode 100644
index 0000000000..7d04e3a1b7
--- /dev/null
+++ b/i18n/.pending/es/docs/concepts/retrieval-and-ranking.md
@@ -0,0 +1,236 @@
+
+> Esta página es una traducción automática de la [página en inglés](https://github.com/ClickHouse/loom/blob/main/docs/concepts/retrieval-and-ranking.md), que prevalece.
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/concepts/retrieval-and-ranking.md), which is authoritative.
+
+
+
+# Recuperación y ranking
+
+Esta página explica cómo `memory.search` encuentra filas. Ejecuta varias rutas de recuperación sobre el espacio de nombres a la vez, fusiona sus candidatos en un único conjunto, ordena ese conjunto por relevancia más términos de corrección acotados y, a continuación, decide si el mejor resultado es lo bastante bueno para responder a partir de él. Un resultado débil se reporta como **abstain** ("Loom no lo sabe"), no como el ruido más cercano. Los campos de la solicitud y la respuesta están en [búsqueda y ask](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/search-and-ask.md).
+
+
+
+```mermaid
+flowchart LR
+ Q["query"] --> P["plan: mode, budget, HyDE"]
+ P --> F["fact leg: value + key vectors"]
+ P --> L["lexical leg: tokens, stems, BM25"]
+ P --> C["verbatim chunks"]
+ P --> R["records"]
+ P --> S["side legs: summaries, entity boost"]
+ P --> G["graph: entity edges, triples"]
+ F --> U["fused pool"]
+ L --> U
+ C --> U
+ R --> U
+ S --> U
+ G --> U
+ U --> K["rank: relevance + bounded terms"]
+ K --> X["optional reranker"]
+ X --> V{"top hit above abstain threshold?"}
+ V -- yes --> A["hits"]
+ V -- no --> B["abstain + abstain_code"]
+```
+
+
+
+## Las etapas de recuperación
+
+Cada etapa responde a un fallo de las demás. Una etapa que no tiene nada que aportar
+no devuelve nada; una etapa que falla con error continúa sin bloquear la consulta y la respuesta la nombra en `degraded`.
+
+| Etapa | Lee | Encuentra lo que las demás pasan por alto |
+| --------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| **Hecho, vector** | Vector de valor de `loom.memory_embeddings` (sin índice vectorial) | Paráfrasis: la pregunta y la afirmación almacenada comparten significado, no palabras. |
+| **Hecho, eje de clave** | El vector `memory_key` de la misma tabla | Una pregunta que nombra el atributo que codifica una clave. Puntúa `least(value distance, key distance)`. |
+| **Léxica** | Extractos y clave en minúsculas, con stemming y lematización | Identificadores exactos, números y palabras raras que se incrustan mal. El stemming se ejecuta en ClickHouse (`stem`). |
+| **BM25** | IDF por token y agregados de longitud del corpus | Ponderación de términos raros para `bm25_hybrid`, con una cola en vivo para que las filas nuevas cuenten de inmediato. |
+| **Fragmentos literales** | `loom.memory_chunks` | Un pasaje de un valor largo de `memory.set` se pliega sobre la fila cuyo valor lo contiene; el de una transcripción es un resultado directo. |
+| **Resúmenes de sesión** | `loom.session_summaries` | «Qué ocurrió en esa sesión»; con el descenso por resúmenes, los mejores resúmenes traen los mejores hechos de sus sesiones. |
+| **Entidad** | `loom.entity_vectors`, `loom.entity_summaries` | Filas sobre una entidad que nombra la consulta, incluso cuando la redacción difiere. |
+| **Grafo** | `loom.entity_edges`, `loom.entity_triples` | Filas a un salto de las entidades de la consulta, y filas con una tripleta (sujeto, relación, objeto) coincidente. |
+| **Registros** | `loom.memory_records` | Registros tipados cuyos campos coinciden. |
+| **Coincidencia de clave** | Partes de clave con stemming | Una fila cuya clave nombra exactamente el atributo solicitado, como criterio de desempate (`LOOM_MEMORY_SEARCH_KEY_MATCH_MODE`). |
+| **Evidencia calculada** | `loom.derived_facts`, fechas de eventos | Agregados («cuántos»), diferencias de fechas y el último valor de un atributo, calculados en ClickHouse. |
+
+**Por qué tantas etapas.** Una sola etapa vectorial pasa por alto identificadores y números (se
+incrustan mal), pasajes situados en lo profundo de un valor largo (solo se incrusta la primera parte) y filas que
+nombran una entidad con otras palabras. Cada etapa es una consulta sobre una tabla que Loom ya escribe, así que
+añadir una cuesta una sentencia, no un segundo sistema.
+
+**Las etapas vectoriales recorren los datos, sin índice vectorial.** El recorrido es exacto o, donde se aplican
+las [lecturas con códigos primero](../architecture/clickhouse.md#vector-storage), una pasada sobre
+códigos cuantizados mantiene un conjunto de candidatos y lo vuelve a puntuar con precisión completa.
+
+**El eje de clave** se activa por espacio de nombres cuando se reutilizan sus claves (`LOOM_MEMORY_SEARCH_KEY_AXIS=auto`,
+umbral `LOOM_MEMORY_SEARCH_KEY_AXIS_AUTO_REUSE_SHARE`): leer dos columnas vectoriales
+cuesta aproximadamente el doble de bytes, y solo ayuda donde las claves tienen significado.
+
+**Planificación y presupuestos.** `retrieval_budget` (`fast`, `standard`, `deep`) decide qué
+etapas costosas se ejecutan. Con `standard`, primero se ejecuta la recuperación barata y las etapas con LLM
+(HyDE, descomposición de la consulta, el reintento iterativo) solo gastan cuando la primera pasada es
+débil, acotadas por `LOOM_MEMORY_SEARCH_FALLBACK_MAX_ROUNDS` y
+`LOOM_MEMORY_SEARCH_FALLBACK_MAX_WALL_MS`. Con `fast` (o la receta `fast`) una lectura
+no hace ninguna llamada a un LLM; cuesta embeddings y lecturas de ClickHouse. HyDE incrusta una respuesta
+hipotética escrita por un LLM en lugar de la pregunta, lo que cierra la brecha entre cómo se formulan las preguntas
+y las afirmaciones almacenadas; `hyde=false` fuerza la consulta original.
+
+
+
+## Fusión
+
+`search_mode` elige cómo se ordena el conjunto de hechos.
+
+- Una solicitud que no define ni `search_mode` ni `recipe` recibe el modo `retrieval_defaults` del espacio de nombres; si no existe, `LOOM_MEMORY_SEARCH_DEFAULT_MODE` (`semantic`). El esquema de la API muestra `rrf`; el servidor completa el valor predeterminado real.
+- Las reglas de forma del planificador se aplican por encima: un identificador en la consulta aplica la fusión léxica.
+- `recipe` aplica un preset con nombre (`fast`, `balanced`, `quality`, `verbatim`, `code`, `temporal`, `graph`) y prevalece sobre ambos valores predeterminados.
+
+| Modo | Ordenación |
+| ------------- | ----------------------------------------------------------------------------------------------------- |
+| `semantic` | Similitud del coseno más los términos de rango que se describen abajo. |
+| `rrf` | Fusión por rango recíproco de los órdenes léxico y semántico, `1/(k + rank)` con k = 60. |
+| `hybrid` | `alpha × lexical + (1 − alpha) × cosine`, más los términos de rango. |
+| `bm25_hybrid` | BM25 ponderado por IDF fusionado con el coseno. |
+| `lexical` | Coincidencia de tokens en el contenido y la clave; sin orden vectorial. |
+| `graph` | Coseno más la señal del grafo de entidades: coincidencia a un salto y tripletas coincidentes. |
+| `temporal` | Filas fechadas dentro de una ventana alrededor de la fecha resuelta de la pregunta, coseno dentro de la ventana. |
+| `related` | Coincidencia de etiquetas y entidades con `tags` / `entity_filter` de la solicitud. |
+
+**Por qué existe la fusión por rango recíproco como modo.** Las puntuaciones de coincidencia léxica se distribuyen entre 0 y 1, mientras que los cosenos de un embedder real están en una banda estrecha; una suma ponderada de ambos da menos peso a uno de ellos a menos que alpha se ajuste para cada corpus. RRF combina rangos, no puntuaciones, por lo que no requiere ajuste. Loom también reduce el peso léxico en las consultas con forma de código o de ruta, cuyos tokens de ruta compartidos son casi ruido (`server/memory/app/retrieval/fusion.py`, `_rrf_lexical_weight`). Los empates en un orden se resuelven con el otro, luego por clave y por el espacio de nombres, el escritor y la sesión de la fila, de modo que dos búsquedas idénticas devuelven la misma ventana.
+
+
+
+## La expresión de ranking
+
+Para los modos ordenados por coseno, la puntuación de una fila de hechos es la relevancia más términos que pueden reordenar empates cercanos, pero que están acotados para que no superen a la relevancia
+(`server/memory/app/retrieval/fact_rank.py`):
+
+| Término | Qué aporta | Controlado por |
+| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| Similitud | `1 − cosine distance` del mejor vector. | el embedder |
+| Refuerzo por entidad | Hasta 0.5 × la proporción de entidades de `entity_filter` que contiene la fila; coincidencias de vectores de entidad con la consulta. | `entity_filter` |
+| Recencia, cronología, fecha | Un impulso en una consulta con intención de recencia ("latest", "current") o de ordenación, y para las filas ancladas cerca de la fecha solicitada. | las propias señales de la consulta; la variante a nivel de pool `LOOM_MEMORY_SEARCH_RECENCY_POOL_WEIGHT` tiene por defecto 0 (desactivada) |
+| Grupo de priors | `confidence` almacenado × `confidence_weight`, refuerzos suaves por etiqueta y categoría, el refuerzo por preferencia; limitados en conjunto. | `confidence_weight`, `tags_soft`, `prior_cap` (`LOOM_MEMORY_PRIOR_CAP`) |
+| Refuerzo por uso | Recuperaciones y resultados positivos, que decaen con una vida media; un evento `harm` retira el refuerzo ganado. | `LOOM_MEMORY_SEARCH_REINFORCEMENT_WEIGHT` (0.15), `…_HALF_LIFE_DAYS` (90) |
+| Confianza | `+0.5` afirmado u observado, `−0.25` importado, `−1` externo, `+1` cuando está atestiguado; multiplicado por el peso. | `LOOM_MEMORY_SEARCH_TRUST_WEIGHT` (por defecto 0 = desactivado) |
+| Penalizaciones | `demote_tags` hunde una fila al final sin descartarla; las filas etiquetadas `sensitivity:medium` o `:high` se rebajan, excepto cuando la consulta pide un dato de contacto o una cuenta bancaria (un IBAN). | `demote_tags`, `LOOM_MEMORY_SEARCH_SENSITIVITY_DEMOTE` (0.1) |
+
+**Fijar no es un término de ranking.** Un pin protege una fila de ser sobrescrita
+([cómo se juzga una escritura](https://github.com/ClickHouse/loom/blob/main/docs/concepts/memory.md#how-a-write-is-judged)); no hace que puntúe
+más alto. Un hecho se devuelve porque responde a la pregunta.
+
+`personalization="none"` elimina todos los términos derivados del usuario (preferencia, el grupo de priors,
+refuerzo por uso) y conserva la relevancia, de modo que los dos rankings se puedan comparar en un mismo servidor.
+`LOOM_MEMORY_SEARCH_SOURCE_CLASS_BOOST_ELIGIBLE` limita qué clases de procedencia pueden
+ganar esos términos: excluir `extracted` evita que una inferencia supere a una
+afirmación por sus priors.
+
+**Reranker.** `rerank` en la solicitud, o el `rerank_endpoint` del espacio de nombres, envía el
+pool a un reranker (`builtin:openai[:model]`, `builtin:cohere[:model]`, o el nombre de un
+endpoint que el operador configuró en `LOOM_RERANK_ENDPOINTS_JSON`; una URL se rechaza). Primero se amplía el pool (`LOOM_MEMORY_SEARCH_POOL_MULTIPLIER_RERANK`),
+porque un reranker solo reordena lo que la primera etapa ha sacado a la superficie. Falla en abierto y nunca
+descarta un candidato.
+
+Pasa `rerank` cuando el orden del pool importa más que una llamada adicional por búsqueda. Para
+medirlo con tus propias consultas, ejecuta cada consulta con `rerank` y con `rerank="none"`
+(que también desactiva el `rerank_endpoint` de un espacio de nombres), ambas con `explain=true` y con
+el presupuesto que usas en producción (una lectura `fast` o sin LLM no hace ninguna llamada a `builtin:openai`), y
+compara las dos ventanas, leyendo el `score_components` de cada resultado como explica [Por qué se clasificó
+aquí](#why-did-this-rank-here). Ninguna ejecución registrada compara las mismas búsquedas con
+y sin reranker ([resultados](https://github.com/ClickHouse/loom/blob/main/docs/benchmarks/results.md#longmemeval-s)).
+
+Tras el ranking, se da forma a la ventana servida: las filas `duplicate` y `superseded` se ocultan
+salvo que se pidan, se conservan como máximo `LOOM_MEMORY_SEARCH_PER_KEY_CAP` filas por clave,
+y `exclude_keys` elimina las filas que el llamante ya tiene.
+
+
+
+## Abstención
+
+Toda búsqueda termina con un veredicto sobre su propio resultado. La respuesta incluye `abstain`,
+`abstain_code` (`no_match`, `below_threshold`, `entity_absent`,
+`low_calibrated_confidence`, `page_expired`), un `abstain_reason` en prosa, un
+`retrieval_confidence` y un `retrieval_risk` con valor `low`, `medium`, `high` o `abstain`.
+Los códigos se definen en [búsqueda y ask](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/search-and-ask.md).
+
+Las filas de la ventana cuya propia similitud queda por debajo del umbral llevan
+`below_threshold: true`, de modo que un llamador que quiera que "abstenerse signifique abstenerse" fila por fila
+puede filtrar por ese campo.
+
+**De dónde salen los umbrales.** Un piso de similitud fijo se calibra para un solo
+modelo de embeddings; si se cambia el modelo, la distribución de los cosenos cambia, y el mismo
+número empieza a filtrar buenos resultados o deja de filtrar ruido. Con
+`LOOM_ADAPTIVE_THRESHOLDS` activado (el valor por defecto), una sonda al arrancar genera embeddings de tres corpus pequeños
+y deriva cada puerta a partir de la distribución del propio embedder
+(`server/memory/app/embedder_calibration.py`):
+
+| Corpus de la sonda | Puertas derivadas |
+| --------------------- | ----------------------------------------------------------------------------------------------- |
+| Pares de distractores | El piso de ruido (percentil 90 + 0.02) y el umbral de abstención (piso + 0.05). |
+| Pares pregunta → hecho | Las puertas de activación: reescritura de la consulta, respaldo HyDE y omisión del rerank (percentiles 10, 25 y 75). |
+| Pares de paráfrasis | Los umbrales de conflicto y duplicado al escribir (mediana, percentil 75). |
+
+Una calibración por espacio de nombres, cuando existe una almacenada, tiene prioridad sobre la del clúster, y
+el worker `recalibration` repite la sonda (`LOOM_RECALIBRATION_INTERVAL_SECONDS`) para que
+las puertas sigan a un embedder revisado de forma silenciosa. `calibration.get` muestra qué nivel
+está en vigor. Los ajustes escalares (`LOOM_MEMORY_SEARCH_MIN_SIMILARITY` 0.22,
+`LOOM_MEMORY_SEARCH_ABSTAIN_THRESHOLD` 0.30, `LOOM_MEMORY_SEARCH_HYDE_FALLBACK_THRESHOLD`
+0.45, `LOOM_MEMORY_SEARCH_QUERY_REWRITE_THRESHOLD` 0.38) se aplican a embedders falsos, a
+una sonda fallida o a cuando la adaptación está desactivada; en ese caso te corresponde volver a hacer el benchmark
+tras un cambio de embedder.
+
+**El equilibrio.** Un piso intercambia recall por precisión. Un agente al que se le dan las cinco filas más cercanas
+a una pregunta fuera de tema las usará; una abstención le indica que pregunte o diga que no
+lo sabe. Un piso demasiado alto oculta respuestas formuladas de forma distinta a la pregunta. La
+postura de Loom es que una abstención explícita sobre la que un agente puede actuar vale más que una
+ventana llena, y deja la elección al llamador en cada lectura:
+
+- `min_similarity` fija el piso de esta lectura;
+- `floor_mode` decide qué ocurre con las filas por debajo de él: `readmit` (por defecto: se añaden después
+ de las filas confiables, marcadas como por debajo del piso, de modo que se llena `top_k`), `ids_only` (se añaden
+ con el cuerpo vacío: la clave indica que existe una coincidencia débil sin poner su texto en
+ el contexto) o `drop`.
+
+Un resultado vacío de un ámbito con extracción diferida en curso informa
+`pending_extraction`: hay un guardado en camino, por lo que la respuesta vacía no es prueba
+de ausencia.
+
+
+
+## Por qué se clasificó aquí
+
+`explain=true` en `memory.search` adjunta `score_components` a cada resultado servido: las señales de ranking, la puntuación RRF y su peso cuando ese modo se ejecutó, y, tras un reranker, el movimiento de cada fila (`rerank_from`, `rerank_pos`, `rerank_delta`) y, cuando el reranker cambió el orden, su propia puntuación fusionada (`rank_score_pre_rerank`). Una memoria cuyo código vinculado cambió y que bajó de posición indica cuántos lugares bajó (`code_changed_places`; cuándo se mueve se explica en [memorias vinculadas a código](https://github.com/ClickHouse/loom/blob/main/docs/concepts/memory.md#memories-linked-to-code)). `memory.search_trace` acepta la misma solicitud y puntúa solo la rama vectorial (sin fusión, ensamblado ni reranker): cada candidato con su `similarity`, `entity_boost`, `rank_score`, `rank` y el plano del que procede (`source`: `fact` o `chunk`). Con `LOOM_SEARCH_TRACE_LOG_ENABLED=true`, cada búsqueda también añade una fila a `loom.search_trace_log` (claves devueltas, puntuaciones, abstain, riesgo, latencia), que se puede leer con `memory.search_trace_log`; el texto de la consulta se almacena solo cuando el espacio de nombres consiente la captura de texto. El Recall Lab del dashboard (`/recall`) muestra las filas que la lista de Memorias muestra para una consulta: coincidencias de palabras clave y, después, los resultados de `memory.search` con sus `score_components`.
+
+`memory.ask` recupera de la misma manera y luego escribe una respuesta a partir de un conjunto más reducido; consulta [búsqueda y ask](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/search-and-ask.md). La herramienta MCP `loom_search` (la operación `search.query`) y `context.pack` buscan en varios planos a la vez; consulta [búsqueda unificada](https://github.com/ClickHouse/loom/blob/main/docs/features/unified-search.md).
+
+
+
+## Límites
+
+- La búsqueda solo lee vectores del modelo de embeddings activo. Las filas generadas con otro modelo
+ permanecen invisibles hasta que `loom reembed` las regenera.
+- Solo se genera el embedding de la primera parte de un valor largo; la rama de chunks es la que encuentra un
+ pasaje situado más adelante. Un valor que en realidad es un documento pertenece a knowledge.
+- El umbral de abstención lee la fila de rango 1. Con `rrf`, una coincidencia solo léxica puede ocupar el rango 1
+ mientras un coseno mejor queda en el rango 2; `LOOM_MEMORY_SEARCH_ABSTAIN_TOP_SIM_SCOPE=window`
+ lee en su lugar el mejor coseno de la ventana.
+- La calibración deriva los umbrales a partir de pequeños corpus de prueba integrados. Un corpus distinto a ellos
+ (código, un único dominio acotado) puede requerir una calibración por espacio de nombres.
+
+
+
+## Relacionado
+
+- [Buscar y preguntar](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/search-and-ask.md): todos los campos de la solicitud y de la
+ respuesta.
+- [Búsqueda unificada](https://github.com/ClickHouse/loom/blob/main/docs/features/unified-search.md): `loom_search` y `context.pack` en
+ detalle.
+- [Grafo de entidades](https://github.com/ClickHouse/loom/blob/main/docs/features/entity-graph.md): de dónde provienen las ramas de entidades y de grafo.
+- [Memoria](https://github.com/ClickHouse/loom/blob/main/docs/concepts/memory.md): los campos que lee el ranking (`source_class`, `status`, tiempo).
+- [Ajuste del rendimiento](https://github.com/ClickHouse/loom/blob/main/docs/guides/performance-tuning.md).
+- Operaciones: [memoria](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md#memory),
+ [calibración](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md#calibration),
+ [contexto](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md#context). Configuraciones:
+ [Búsqueda de memoria](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#memorysearch),
+ [Consulta de memoria](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#memoryask),
+ [Mcp](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#mcp).
diff --git a/i18n/.pending/es/docs/development/adding-a-table.md b/i18n/.pending/es/docs/development/adding-a-table.md
new file mode 100644
index 0000000000..926a52be8d
--- /dev/null
+++ b/i18n/.pending/es/docs/development/adding-a-table.md
@@ -0,0 +1,114 @@
+
+> 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/adding-a-table.md), que prevalece.
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/development/adding-a-table.md), which is authoritative.
+
+
+
+# Agregar una tabla o columna de ClickHouse
+
+El estado de ClickHouse en Loom son tablas en las bases de datos `loom` y `loom_telemetry`; bajo la autoridad de memoria en Postgres, la memoria activa, el estado del conocimiento y los registros asociados están en Postgres. La página de [autoridad de almacenamiento](../architecture/storage-authority.md#the-tables) enumera las tablas de Postgres. El esquema de ClickHouse cambia únicamente mediante migraciones numeradas y aditivas, porque dos compilaciones sirven el mismo esquema durante un despliegue. Cada una de las reglas siguientes está respaldada por una prueba. [ClickHouse](../architecture/clickhouse.md) explica las familias de tablas.
+
+```mermaid
+flowchart TD
+ A["schemas/migrations/NNN_name.sql"] --> B["make migrate (local ClickHouse)"]
+ B --> C["make schema-dump schemas/schema.sql"]
+ C --> D{"table holds memory content?"}
+ D -->|yes| E["erasure saga step + _CENSUS row"]
+ D -->|derived, no read path| F["STEP_ONLY_TABLES"]
+ D -->|no| G["NO_MEMORY_CONTENT + reason"]
+ C --> H{"column on loom.memory / shared / memory_embeddings?"}
+ H -->|yes| I["row builders + memory_versions mirror"]
+```
+
+
+
+## 1. Escribe la migración y regenera el esquema
+
+[Migraciones](https://github.com/ClickHouse/loom/blob/main/docs/development/migrations.md) define las reglas: numeración, qué se considera aditivo, directivas del runner, reconstrucciones de la clave de ordenación, y `make schema-dump` / `make schema-check` contra el ClickHouse fijado. En resumen:
+
+- Añade `schemas/migrations/_.sql` con el siguiente número libre. El comentario de cabecera indica para qué sirve el cambio y qué ven las filas antiguas y las compilaciones antiguas.
+- Referencia las tablas como `loom.
` y escribe `IF NOT EXISTS` / `IF EXISTS`. La telemetría derivada de las tablas propias de Loom va en `loom_telemetry` ([por qué](../architecture/clickhouse.md)); preflight ya comprueba sus permisos, y el censo de borrado nombra la tabla con su base de datos.
+- Nunca edites ni elimines una migración ya fusionada. Corrige un error con un archivo nuevo.
+- Ejecuta `make migrate`, `make schema-dump` y después `python scripts/codegen/docs_reference.py` para que la [referencia del esquema](https://github.com/ClickHouse/loom/blob/main/docs/reference/schema.md) incluya la tabla.
+
+Hasta que un despliegue aplique la migración, la protección de esquema del cliente rechaza cualquier lectura o escritura que nombre una tabla que una migración pendiente crearía, con `SCHEMA_PENDING`.
+
+
+
+## 2. Replica todas las columnas en las rutas de escritura de ReplacingMergeTree
+
+`loom.memory`, `loom.shared` y `loom.memory_embeddings` son tablas `ReplacingMergeTree(version)` que se leen con `FINAL`. Todo handler que escribe una nueva fila de versión (set, tombstone, restore, touch, `update_by_id`, `bulk_set`, promote, demote) arrastra **todas** las columnas persistidas. Una columna omitida en una versión posterior se lee como cero bajo `FINAL`.
+
+Cuando añadas una columna a una de estas tablas:
+
+1. Añádela a la lista canónica de columnas en `server/memory/store/rows.py`
+ (`MEMORY_PERSISTED_COLS` o `EMBEDDING_PERSISTED_COLS`).
+2. Inclúyela en los builders de ese archivo (`build_memory_version_row`, `build_revision_row`,
+ `build_first_version_row`, `build_embedding_row`) y en toda proyección que los alimente
+ (el `SELECT` que carga la fila existente).
+3. Nunca construyas una fila de versión a mano en un handler; llama a los builders.
+
+`tests/unit/test_memory_write_path_mirror.py` y `tests/unit/test_embedding_mirror_carry.py` comprueban las rutas de escritura secundarias.
+
+**El espejo del historial.** `loom.memory_versions` es una réplica de solo anexado de `loom.memory`, rellenada por la vista materializada `memory_versions_mv`. `memory.history`, `memory.redact` y `namespace.rollback` la leen, porque las fusiones eliminan de `ReplacingMergeTree` las filas reemplazadas. Añade cada nueva columna de `loom.memory` a `loom.memory_versions` y al `SELECT` de la vista **en la misma migración**. `tests/unit/test_memory_versions_schema.py` compara ambas listas de columnas en `schema.sql` con `MEMORY_PERSISTED_COLS`.
+
+Toda nueva ruta de escritura establece los valores `actor` y `source_class` asignados por el servidor (`server.memory.domain.provenance`), nunca valores tomados del cuerpo de la solicitud.
+
+
+
+## 3. Clasificar la tabla para el borrado
+
+El borrado es una saga (`server/erasure/app/saga.py`). Su último paso es un censo de residuos sobre todas las tablas que tocan las rutas de lectura; cualquier fila viva dentro del alcance hace fallar la saga en modo cerrado. `tests/unit/test_every_table_is_classified.py` falla ante cualquier `CREATE TABLE` de `schema.sql` que no esté en exactamente una de las tres listas de `server/erasure/store/census.py`:
+
+| Lista | Pon la tabla aquí cuando | También añades |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `_CENSUS` | Puede contener contenido de memoria que sirve una ruta de lectura. | Un paso de la saga que elimine las filas dentro del alcance, y un `Substrate(table, live, user_pred, ns_step, user_step)` que nombre ese paso para cada alcance. |
+| `STEP_ONLY_TABLES` | Un paso de la saga la modifica pero el censo no la cuenta (libros derivados, mapas de alias), con el motivo en el comentario sobre el dict. | El paso, indexado por su nombre. |
+| `NO_MEMORY_CONTENT` | No contiene contenido de memoria dentro del alcance (contadores, cursores, cachés de datos públicos). | Un motivo de una línea. |
+
+Para una tabla de `_CENSUS`:
+
+- `live` es el predicado que cumple una fila viva (`tombstoned_at IS NULL`, o `"1"` cuando cuentan todas las filas); `user_pred` es `user_id = {uid:String}` cuando la tabla tiene un eje de usuario, y `None` para una tabla solo de espacio de nombres (en ese caso solo se cuenta en los borrados con alcance de espacio de nombres).
+- El paso es una función en `server/erasure/store/steps_*.py`, listada con su nombre de paso en cada tabla de la saga que corresponda (`NAMESPACE_STEPS`, `USER_STEPS` en `server/erasure/app/saga_steps.py`), y `final=False` en el `Substrate` para un `MergeTree` simple (FINAL no es válido ahí).
+- Una saga reanudada vuelve a ejecutar el paso propietario de cualquier tabla en la que el último censo encontró filas (`steps_to_reopen`), por lo que el paso debe ser idempotente.
+- Una tabla del plano de código con clave `(org, namespace)` normalmente pertenece a `CODE_INDEX_STEP_ONLY_TABLES` (la elimina el paso `code_index.purge` de la saga); una prueba unitaria comprueba que esa tupla coincida con el esquema.
+
+Prueba la forma de la sentencia del paso con un cliente stub, como hacen `tests/unit/test_erasure_repo.py` y `tests/unit/test_erasure_late_steps.py`.
+
+
+
+## 4. Clasificar cualquier mutación
+
+Un `ALTER TABLE loom. UPDATE|DELETE` es una mutación de ClickHouse: reescribe las partes de forma asíncrona y no es transaccional. `tests/unit/test_clickhouse_mutation_inventory.py` cuenta todas las mutaciones visibles bajo `server/` y las compara con `_EXPECTED_MUTATIONS`. Una mutación nueva hace fallar la prueba hasta que la añades allí con un comentario que explique el motivo.
+
+Es preferible usar una nueva fila de versión en una `ReplacingMergeTree`, una columna de tombstone o un `DELETE FROM` ligero. Nunca uses una mutación como un claim o un bloqueo del que dependa una solicitud; la bandeja de tareas hace sus claims mediante una tabla de lease `KeeperMap`.
+
+
+
+## Lista de verificación
+
+- [ ] Un nuevo `schemas/migrations/_.sql`, aditivo e idempotente; ningún archivo ya fusionado se edita.
+- [ ] `make schema-dump` contra un ClickHouse fijado y limpio; `make schema-check` sin errores.
+- [ ] `python scripts/codegen/docs_reference.py` para la referencia del esquema.
+- [ ] Columnas RMT: la lista de columnas de `rows.py`, los constructores y las proyecciones; `memory_versions` y
+ `memory_versions_mv` en la misma migración.
+- [ ] Clasificación de borrado: `_CENSUS` + paso de saga, `STEP_ONLY_TABLES`, o
+ `NO_MEMORY_CONTENT` con un motivo.
+- [ ] Toda nueva mutación se incluye en el test de inventario.
+- [ ] Una fila en el [diseño del almacenamiento](https://github.com/ClickHouse/loom/blob/main/docs/architecture/storage-layout.md), en la tabla de su familia
+ para una tabla de ClickHouse (la sección de las tablas `_` para un nombre que empieza por `_`),
+ con todas las columnas rellenas. `tests/unit/test_storage_layout_rows.py` comprueba que la
+ fila existe (y, para una tabla de ClickHouse, que desaparece cuando la tabla se elimina; la fila de una tabla
+ de Postgres eliminada se borra a mano), y, para una fila de ClickHouse, que su
+ celda Today coincide con el esquema, su celda Erasure con el censo, y que sus citas nombran
+ la tabla; mientras el volcado del esquema está pendiente, falla hasta que el volcado se incorpora.
+- [ ] `make test-unit` (los tests de aditividad, numeración, espejo, clasificación e inventario).
+
+
+
+## Relacionado
+
+- [Migraciones](https://github.com/ClickHouse/loom/blob/main/docs/development/migrations.md)
+- [ClickHouse](../architecture/clickhouse.md)
+- [Retención y borrado](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/retention-and-erasure.md)
+- [Actualizaciones](https://github.com/ClickHouse/loom/blob/main/docs/operations/upgrades.md)
diff --git a/i18n/.pending/es/docs/features/entity-graph.md b/i18n/.pending/es/docs/features/entity-graph.md
new file mode 100644
index 0000000000..3826719d94
--- /dev/null
+++ b/i18n/.pending/es/docs/features/entity-graph.md
@@ -0,0 +1,238 @@
+
+> 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/entity-graph.md), que prevalece.
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/features/entity-graph.md), which is authoritative.
+
+
+
+# Grafo de entidades
+
+Loom mantiene un grafo de entidades junto a las filas de memoria, en la misma base de datos de ClickHouse. Las entidades son nodos. Dos entidades mencionadas en la misma memoria comparten una arista de coocurrencia; la extracción agrega tripletas tipadas `(subject, relation, object)` como un segundo conjunto de aristas. El grafo es una proyección de la memoria: cada arista se puede rastrear hasta las filas que la produjeron. Úsalo para preguntas que la búsqueda vectorial no puede responder, como "qué está conectado con el servicio de facturación".
+
+Las comunidades de entidades están desactivadas por defecto (`LOOM_ENTITY_COMMUNITIES_ENABLED`).
+
+
+
+## Qué contiene el grafo
+
+| Tabla | Contiene |
+| ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `loom.entity_edges` (+ `entity_edge_memories`, `entity_edge_rows`) | Una fila por observación de coocurrencia (`co_occur = 1`); los lectores suman por par. Clave de origen por par, y la fila y el valor que lo nombraron. |
+| `loom.entity_triples` (+ `entity_triple_memories`, `entity_triple_rows`) | Tripletas tipadas con `confidence` y el modelo extractor como `adapter_name`. Clave de origen por tripleta, y la fila y el valor que la enunciaron. |
+| `loom.entity_degree` | El grado total de coocurrencia de cada entidad (`SummingMergeTree`); las reglas de hubs lo leen. |
+| `loom.entity_canonical_map` | Texto de la mención → entidad canónica. |
+| `loom.entity_communities` | Id de comunidad por entidad, por nivel. |
+| `loom.entity_vectors`, `loom.entity_summaries` | Embeddings que leen las ramas de entidades de la búsqueda. |
+| `loom.derived_facts` | Hechos numéricos con unidad y fecha, para respuestas calculadas en la búsqueda. |
+| Aristas `memory.link` | Aristas que afirma un agente o una persona (`supports`, `depends_on`, `caused`, …); las lee la búsqueda en modo grafo. |
+
+Las aristas y las tripletas llevan `valid_from` / `valid_to` (tomados de `valid_at` / `valid_to` de la memoria de
+origen) y una marca `invalid_at` que las retira. Una lectura con `as_of` suma solo las observaciones válidas en ese
+instante.
+
+El grafo vive en ClickHouse para que las aristas se escriban en la misma solicitud que su fila, se borren con la misma
+saga y se unan con la memoria sin un salto de red. El costo: un recorrido es una serie de consultas agregadas
+acotadas, por lo que todo recorrido tiene un límite.
+
+
+
+## Cómo se construye el grafo
+
+Primero se escribe la fila de memoria; las filas del grafo son proyecciones de ella. Una proyección fallida se registra en
+`loom.memory_projection_failures` y se reintenta, solo mientras la fila conserve el valor que no se pudo proyectar.
+Nunca hace fallar la escritura. Una entrada masiva de sensibilidad `high` no proyecta nada; un `memory.set` de
+sensibilidad `high` proyecta únicamente las aristas de las entidades que declaró su escritor, nunca su texto.
+
+1. **Entidades.** El escritor pasa `entities` en `memory.set`, o `memory.set_from_messages` las extrae. El worker
+ `entity_extractor` (`LOOM_ENTITY_EXTRACT_ENABLED`, activado) etiqueta las filas escritas sin ellas, fuera de la ruta de
+ escritura; necesita un proveedor de LLM real. El texto de las entidades se canonicaliza de la misma forma al escribir y
+ al leer (se eliminan artículos y posesivos, el sustantivo principal se pasa a singular y la primera persona se asigna a
+ `user`), de modo que "The Billing Service's" y "billing service" son un mismo nodo. Un nombre `commit:` o
+ `error:` es un identificador: se canonicaliza igual, pero nunca se pasa a singular: `error:Timeouts`, o el mismo
+ nombre entre comillas invertidas o comillas, es el nodo `error:timeouts`. Un espacio en blanco o marcado justo después
+ de los dos puntos (`Error: the build failed`, ``error:`Timeouts` ``) lo convierte en prosa. Se descartan los
+ pronombres, las interjecciones, los verbos ligeros y los tokens de dos caracteres, y también el texto de más de 256
+ caracteres, tal como está escrito o una vez normalizado (NFKC convierte `fi` en `fi`), tanto al escribir como en un
+ `entity_filter`; una escritura puntual rechaza un sujeto u objeto de hecho de ese tipo en lugar de descartarlo.
+2. **Aristas.** Cada par de entidades de una memoria se convierte en una fila de observación, con un máximo de 100 pares
+ por memoria.
+3. **Tripletas.** Las relaciones de un hecho extraído se convierten en tripletas, con un máximo de 8 por memoria. Los
+ verbos se normalizan a `lower_snake`. `namespace.register_ontology` (admin) registra tipos de entidad, verbos y
+ atributos preferidos con una cardinalidad. Los nombres fuera del conjunto generan `ontology_warnings`; no se rechaza
+ nada.
+4. **La sustitución cierra tripletas.** Cuando una fila sustituye a otra, las tripletas abiertas de la fila antigua que la
+ nueva no confirma reciben `invalid_at`. En una relación `one` (empleador, ubicación), el valor más reciente sigue
+ vigente y el anterior se cierra cuando empieza el más reciente. Una escritura que vuelve a declarar el valor anterior
+ mientras se ejecuta ese cierre lo mantiene abierto.
+ - Los valores se ordenan por el día en que empiezan (un valor sin fecha empieza cuando llega) y luego por su llegada
+ al microsegundo, de modo que los escritores concurrentes coinciden en un único valor vigente. Dentro de una misma
+ escritura, el valor declarado después es el más reciente.
+ - Dentro de una misma escritura, un valor sin fecha en tiempo pasado (`lived_in`, `worked_at`) es más antiguo que uno
+ con fecha, en cualquier orden: "user lived_in london" junto a Paris desde el 1 de octubre deja a Paris como vigente.
+ - Un valor se juzga por su fila más reciente: "London desde el 15 de octubre, Paris desde el 14 de octubre, London desde
+ el 13 de octubre" deja a London como vigente.
+ - Un valor declarado con su propio final ("London hasta diciembre") nunca se cierra antes de tiempo. Sigue vigente junto
+ al valor más reciente hasta ese final.
+ - Un Undo (`memory.restore`) hace vigente el valor restaurado desde la restauración, o desde el inicio posterior del
+ propio hecho ("mudándose a Berlín el 1 de diciembre"). El otro valor se cierra y su fila sigue activa. Un valor
+ fechado en un día posterior sigue prevaleciendo, y también un valor declarado después del Undo. Deshacer y rehacer
+ repetidamente no añade peso.
+ - Un cierre fallido se reproduce tal como estaba en la escritura o el Undo que lo originó, de modo que un valor
+ declarado desde entonces sigue vigente.
+
+ En la [arquitectura de la memoria](../architecture/memory-architecture.md#undo) se explica cómo un Undo vuelve a
+ declarar sus hechos y aristas, los pondera y se reproduce.
+
+Una escritura puntual (`memory.set`, `memory.update`, `memory.update_by_id`) escribe las tripletas que el llamador pasa en
+`relations`, con un máximo de 8, por HTTP y en las operaciones tipadas de los SDK (no en el listado de MCP); no extrae
+ninguna. La extracción automática se ejecuta en la ruta masiva: `memory.set_from_messages`, o un escritor masivo que
+proporcione relaciones. Con los proveedores simulados de serie, solo las entidades que pasas forman aristas.
+
+
+
+## Operaciones
+
+| Operación | Rol | Responde |
+| ------------------------------ | ------ | ------------------------------------------------------------------------------------------------------------- |
+| `facts.list` | viewer | Tripletas filtradas por `subject`, `object`, `relation` (AND) o `entity` (cualquiera de los dos extremos). |
+| `facts.related` | viewer | Entidades que coinciden con una entidad, de mayor a menor fuerza, e indica de qué lado está la semilla. |
+| `facts.traverse` | viewer | El vecindario a N saltos de una semilla. |
+| `facts.path` | viewer | La cadena más corta de aristas entre dos entidades dentro de `max_hops`. |
+| `facts.expire_by_adapter` | admin | Marca como eliminadas (tombstone) las tripletas que escribió un extractor. Las memorias permanecen. |
+| `memory.search` (modo grafo) | viewer | `search_mode="graph"`: resultados a un salto de las entidades de la consulta ([búsqueda y ask](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/search-and-ask.md)). |
+| `memory.related` | viewer | Memorias que comparten entidades con una memoria dada. |
+| `memory.timeline` | viewer | Las memorias de una entidad en orden cronológico (`entity=…`). |
+| `memory.backlinks` | viewer | Memorias que comparten las entidades de una fila. |
+| `namespace.taxonomy` | viewer | Las entidades principales de un espacio de nombres y, cuando se calculan, sus comunidades. |
+
+Listas de campos: [hechos](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/facts.md), [memoria](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/memory.md). Fuera del modo
+grafo, `entity_filter` da más peso a las filas sobre las entidades indicadas, y los tramos de entidades de la búsqueda encuentran filas sobre una entidad que la
+consulta nombra con otras palabras ([recuperación y ranking](https://github.com/ClickHouse/loom/blob/main/docs/concepts/retrieval-and-ranking.md)).
+
+
+
+### `facts.list`
+
+Sin filtros, devuelve las tripletas principales por `co_occur`; `sort_by="recency"` ordena por `last_seen`.
+
+| Campo | Efecto |
+| ----------------------- | ---------------------------------------------------------------------------------------------------- |
+| `include_sources` | Agrega hasta unas diez claves de memorias de origen por tripleta. |
+| `include_source_status` | Lee cada fila de origen; marca una tripleta como `stale` cuando está abierta pero todas las filas que la respaldan han sido reemplazadas. |
+| `provenance` | `extracted` (ambos extremos en el texto de origen), `inferred` o `facet` (una arista de navegación creada por Loom). |
+| `as_of` | Conserva las tripletas válidas en ese instante. |
+
+
+
+### `facts.traverse`
+
+El recorrido poda antes de expandir. Cada salto envía la frontera como una sola consulta, suma las observaciones por par dentro de la
+ventana de validez, descarta las entidades ya visitadas y conserva los `top_k_per_hop` pares más fuertes de cada padre. Una frontera de salto h
+tiene como máximo K^h entidades. Cada entidad se informa una sola vez, en el primer salto que la alcanza, a través de su padre
+más fuerte, por lo que el resultado se dibuja como un árbol.
+
+Una consulta recursiva que expande todo y poda después materializaría todo el vecindario; en un espacio de nombres grande, un recorrido de tres saltos
+puede superar el límite de memoria de ClickHouse. Podar en cada salto acota el costo al tamaño de la respuesta.
+
+| Campo | Valor por defecto | Efecto |
+| ----------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `max_hops` | 2 (1–4) | Profundidad del recorrido. |
+| `top_k_per_hop` | 20 (hasta 100) | Hijos conservados por padre en cada salto. |
+| `min_co_occur` | 1 | Mínimo de observaciones por par. |
+| `max_nodes` | 400 (hasta 5,000) | Límite estricto; `truncated=true` cuando se alcanza. |
+| `as_of` | sin definir | Conserva las observaciones válidas en ese instante. |
+| `labeled` / `relations` | false / sin definir | Recorre tripletas tipadas (todas, o solo estos verbos); los nodos incluyen `via_relation`, `via_direction`, `via_provenance`. |
+| `hub_degree` | 0 (desactivado) | Un nodo con grado total igual o mayor que este valor es un hub. |
+| `hub_share` | `LOOM_FACTS_TRAVERSE_HUB_SHARE` (0.01) | Un nodo es un hub cuando la arista que llegó a él representa como máximo esta proporción de su grado. |
+| `rank_by` | `LOOM_FACTS_TRAVERSE_RANK_BY` (`cosine`) | Poda por salto: `co_occur`, `specificity` (`via_co_occur / degree`) o `cosine` (`via_co_occur / sqrt(degree)`). |
+
+Cada nodo informa `hop`, `cumulative_weight`, `via_co_occur`, `path` (la cadena desde la semilla), `valid_from` /
+`valid_to`, `degree` y `community_id` cuando existen comunidades. Los nodos se ordenan por salto y luego por peso.
+
+**Hubs.** Las entidades genéricas ("user", "pr") coinciden con todo. Un hub se informa (`hub: true`, listado en `hubs`)
+pero no se expande. La semilla siempre se expande, así que parte de un hub para ver su vecindario. `hub_share` es la regla
+por defecto porque no depende de la escala de grados del espacio de nombres. `hub_degree` es específico de cada espacio de nombres; revisa la cola
+de la distribución de grados antes de definirlo.
+
+
+
+### `facts.path`
+
+Una búsqueda en anchura bidireccional acotada sobre las mismas aristas, que se encuentra en el medio. `max_hops` (1–4, por defecto 3)
+acota la longitud total. La respuesta es `found`, `path` y `edges`, con el `co_occur` y la validez de cada par.
+`truncated=true` significa que la respuesta puede estar incompleta. `found=false` con `truncated=false` significa que no hay conexión dentro de
+`max_hops`.
+
+
+
+## Ejemplo
+
+```python
+from loom import Agent
+
+async with Agent("dev", "local", "sre-bot", base_url="http://localhost:7777") as agent:
+ await agent.memory.set(
+ "billing/depends_on",
+ "The billing service reads invoices from the ledger database.",
+ entities=["billing service", "ledger database"],
+ )
+ walk = await agent.facts.traverse("billing service", max_hops=2, top_k_per_hop=10)
+ for node in walk["nodes"]:
+ print(node["hop"], " > ".join(node["path"]), node["via_co_occur"])
+
+ route = await agent.facts.path("billing service", "ledger outage")
+ print(route["found"], route["path"], route["truncated"])
+```
+
+Sobre HTTP, un recorrido del grafo tal como estaba en un instante pasado:
+
+```bash
+curl -s localhost:7777/v1/facts.traverse -H "Authorization: Bearer $LOOM_API_KEY" \
+ -H 'content-type: application/json' \
+ -d '{"org":"dev","namespace":"local","seed_entity":"billing service","max_hops":2,"as_of":"'"$AS_OF"'"}'
+```
+
+Sobre MCP, llama a `loom_op` con `op="facts.traverse"`.
+
+
+
+## Mantenimiento del grafo
+
+| Tarea | Cómo |
+| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| Revertir las tripletas de un extractor defectuoso | `facts.expire_by_adapter(adapter_name=…, max_confidence=…)`. Las memorias se conservan. |
+| Exportar el grafo | `loom entity-export --org O --namespace N --format graphml` (o `jsonld`; `--all` incluye las aristas invalidadas). |
+| Agrupar entidades en comunidades | Define `LOOM_ENTITY_COMMUNITIES_ENABLED=true` (más abajo). |
+| Verlo | La vista Graph del dashboard ([panel](https://github.com/ClickHouse/loom/blob/main/docs/features/dashboard.md)). |
+
+El worker `entity_communities` ejecuta propagación de etiquetas por espacio de nombres sobre `loom.entity_communities`, que leen `namespace.taxonomy`, la expansión en modo grafo y `community_id`. Cubre los espacios de nombres con la consolidación activada, además de los recorridos en los últimos `LOOM_ENTITY_COMMUNITIES_WALKED_DAYS` (14) días. Descarta primero las entidades de mayor grado (`LOOM_ENTITY_COMMUNITIES_HUB_DROP_FRACTION`) y duplica esa fracción mientras una comunidad contenga más de `LOOM_ENTITY_COMMUNITIES_GIANT_SHARE` de las entidades, de modo que los tokens genéricos no puedan fusionar el grafo en una sola comunidad.
+
+
+
+## Configuración
+
+| Configuración | Sección |
+| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `LOOM_FACTS_TRAVERSE_HUB_SHARE`, `…_RANK_BY` | [Salud del espacio de nombres, grafo de conocimiento, comunidades](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#namespace-health-knowledge-graph-communities) |
+| `LOOM_ENTITY_COMMUNITIES_*` | La misma sección. |
+| `LOOM_ENTITY_EXTRACT_*` | [Consolidación](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#consolidation) |
+| `LOOM_MEMORY_SEARCH_GRAPH_SEED` | [Búsqueda de memoria](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#memorysearch) |
+
+
+
+## Límites
+
+- **La co-ocurrencia no es una relación.** Dos entidades en una misma memoria quedan vinculadas sin importar lo que diga la oración. Usa triples tipados (`labeled`, `relations`) o `memory.link` cuando la relación importe.
+- **El grafo solo es tan bueno como sus entidades.** Las filas sin entidades no añaden aristas hasta que el worker `entity_extractor` las procesa.
+- **Los recorridos están acotados.** Lee `truncated` antes de concluir que dos entidades no están conectadas.
+- **Las aristas pueden quedar rezagadas respecto de una fila reemplazada.** `facts.list(include_source_status=true)` muestra los triples que siguen abiertos.
+- **La validez es tiempo de validez.** `as_of` lee cuándo se cumplía un hecho, no cuándo Loom lo supo.
+
+
+
+## Relacionado
+
+- [Búsqueda y consulta](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/search-and-ask.md): modo grafo.
+- [Escritura de memorias](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/writing.md): cómo pasar `entities`.
+- [Extracción](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/extraction.md): de dónde provienen las entidades y los tripletes extraídos.
+- [Arquitectura de memoria](../architecture/memory-architecture.md): los escritores de proyecciones.
+- [Referencia de workers](https://github.com/ClickHouse/loom/blob/main/docs/reference/workers.md).
diff --git a/i18n/.pending/es/docs/features/memory/history-and-provenance.md b/i18n/.pending/es/docs/features/memory/history-and-provenance.md
new file mode 100644
index 0000000000..fc5596ff61
--- /dev/null
+++ b/i18n/.pending/es/docs/features/memory/history-and-provenance.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/features/memory/history-and-provenance.md), que prevalece.
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/history-and-provenance.md), which is authoritative.
+
+
+
+# Historial y procedencia
+
+Cada escritura en la memoria crea una nueva versión; nada se edita en el mismo lugar. Las versiones se conservan en un espejo de solo anexado, de modo que el historial de un hecho sobrevive a las fusiones en segundo plano. Cada fila registra quién la escribió y cómo entró en la memoria, las filas derivadas registran sus fuentes, y una persona puede certificar que una fila es verdadera. El funcionamiento del espejo de versiones se explica en [arquitectura de la memoria](../../architecture/memory-architecture.md).
+
+
+
+
+
+## Operaciones
+
+| Operación | Rol | Responde |
+| -------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------- |
+| `memory.history` | viewer | Todas las versiones de una clave, de la más reciente a la más antigua, incluidas las versiones eliminadas (tombstone) y las redactadas. |
+| `memory.provenance` | viewer | De dónde proviene la fila activa: traza de origen, escritor, clase de origen y la conversación de la que se extrajo. |
+| `memory.evidence` | viewer | Los turnos de origen de los que se extrajo un hecho, con el fragmento que lo respalda y cómo se creó cada vínculo. |
+| `memory.backlinks` | viewer | Qué apunta a una fila: versiones, resúmenes, vínculos tipados de entrada y salida, cantidad de evidencias y entidades vecinas. |
+| `memory.lineage` | viewer | El historial de promoción de una memoria compartida: quién la promovió, desde qué filas y mediante qué revisión. |
+| `memory.verify` | writer | Certifica que una fila es verdadera como la persona o la cuenta de servicio que inició sesión, o revoca la certificación. |
+| `memory.redact` | admin | Borra el valor de una versión histórica, conservando la fila y su entrada de auditoría. |
+| `namespace.rollback` | admin | Devuelve todas las cabeceras de memoria de un espacio de nombres a su versión en un momento dado. |
+| `namespace.snapshot` | admin | Exporta el estado curado de un espacio de nombres como una carga útil JSON. |
+| `namespace.restore` | viewer | Importa un snapshot en un espacio de nombres nuevo, o en uno existente que el solicitante administra; nunca en una colección. |
+
+`namespace.snapshot` y `namespace.restore` no son herramientas MCP. Las listas de campos están en la
+referencia de operaciones, en [memoria](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md#memory) y
+[espacio de nombres](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md#namespace).
+
+
+
+## Versiones: `memory.history`
+
+`loom.memory` contiene el estado actual y se lee con `FINAL`, de modo que una fusión conserva solo la
+versión más reciente de cada fila. `loom.memory_versions` es un espejo de solo anexado que llena una
+vista materializada en cada inserción; es el historial que leen `memory.history`,
+`memory.redact` y `namespace.rollback`.
+
+Una fila de historial incluye `version` (la época en nanosegundos de la escritura), `written_at`, `value`,
+`confidence`, `pinned`, `expires_at`, `tombstoned_at`, `redacted_at`,
+`redaction_reason`, `content_sha256`, `agent`, `actor` y `source_class`. `created_at`
+es la primera escritura de la fila y se repite en cada versión. `agent="*"` abarca a todos los escritores
+de la clave.
+
+```python
+from loom import Agent
+
+async with Agent(org="acme", namespace="support", agent="auditor") as agent:
+ for v in await agent.memory.history("customer/4812/plan", agent_id="*"):
+ print(v["written_at"], v["actor"], v["source_class"], v["value"])
+```
+
+Una lápida (tombstone) también es una versión, por lo que un borrado aparece en el historial y `memory.restore` puede
+revivir la clave dentro de 14 días. Para lecturas del estado actual en un momento dado, usa `as_of` en
+`memory.get`, `memory.search` y `memory.ask`
+([tiempo de validez](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/writing.md#validity-time-valid_at-and-valid_to)).
+
+
+
+## Quién lo escribió: actor y clase de fuente
+
+El servidor registra `actor` (`human:` o `process:`) y `source_class`
+en cada fila a partir del token y de la operación. Los valores de `source_class` están en
+[conceptos de memoria](https://github.com/ClickHouse/loom/blob/main/docs/concepts/memory.md). Una solicitud solo puede rebajar su clase a
+`external`, `imported` o `derived`.
+
+`memory.provenance` devuelve ambos, además de:
+
+- `source_trace` y un `source_kind` derivado de él (`conversation`, `extracted`,
+ `observed`, `consolidated`, `app`, `manual`, `other`);
+- el `source_resource_id` citado por quien escribió;
+- el `thread_id` de la conversación y `thread_exists` (false cuando el espacio de nombres no
+ registra transcripciones, o la transcripción ya no existe);
+- los vínculos creados manualmente (`memory.link`) que tocan la fila.
+
+Los resultados de búsqueda incluyen `source_class` y `verified`, que lee el término de confianza
+opcional (`LOOM_MEMORY_SEARCH_TRUST_WEIGHT`).
+
+
+
+## Evidencia: de qué turnos proviene un hecho
+
+La extracción vincula cada hecho con sus turnos en `loom.memory_belief_sources`.
+`memory.evidence(memory_key)` devuelve esos vínculos con el texto del turno (hasta 600
+caracteres), el rol, la hora, el `span` de respaldo y la forma en que se creó el vínculo:
+
+| `scope` | `support_type` | Significado |
+| --------- | ----------------- | ------------------------------------------------------------ |
+| `cited` | `extracted_from` | El extractor indicó el turno de respaldo. |
+| `lexical` | `lexical_support` | El servidor asoció el hecho con su mejor turno. |
+| `window` | `window` | Nada coincidió; se vincula toda la ventana de extracción. |
+| `derived` | `derived_from` | Linaje de consolidación: el elemento es el texto de la memoria de origen. |
+
+La respuesta cuenta los vínculos por scope, de modo que una comprobación puede distinguir un hecho citado de
+uno asociado de forma laxa. Para obtener la redacción exacta de una conversación, `memory.recall` busca en los turnos almacenados
+([extracción](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/extraction.md)).
+
+
+
+## Linaje
+
+- `memory.consolidate` y los resúmenes por período escriben un enlace `derived_from` por cada fuente en
+ `loom.memory_belief_sources`; `memory.evidence` los devuelve como elementos `derived`.
+- Un resumen de sesión lista las claves que comprimió (`derived_from` en un resultado de tipo `summary`).
+- `memory.lineage` (`scope="shared"`) recorre la promoción de una memoria compartida: el evento, quién
+ la promovió, las filas de apoyo, el candidato de aprendizajes del que proviene cuando hay una
+ coincidencia (`match_confidence` `exact` o `inferred`) y los eventos de auditoría. `mechanism` es
+ `review`, `import`, `auto` o `unknown`.
+- `memory.backlinks` es la operación inversa: qué apunta a una fila.
+
+`memory.delete` retira un resumen consolidado cuyas fuentes han desaparecido todas y degrada a
+`conflicted` uno cuyas fuentes siguen existiendo.
+
+
+
+## Atestación: `memory.verify`
+
+`pinned` y `confidence` no indican quién comprobó un hecho. `memory.verify` lo registra: el
+actor del token del llamante y el hash del contenido que atestiguó. Se direcciona la fila por
+`memory_id`, o por `namespace` y `memory_key` con la identidad del escritor. Requiere permiso de
+escritor sobre el espacio de nombres de la fila.
+
+`memory.get` y `memory.get_by_id` devuelven `verification`, derivado del hash almacenado
+y del hash actual de la fila:
+
+| `verification` | Significado |
+| -------------- | -------------------------------------------------------------------------- |
+| `human` | Una persona atestiguó y el contenido no ha cambiado desde entonces. |
+| `process` | Una cuenta de servicio atestiguó y el contenido no ha cambiado desde entonces. |
+| `stale` | Alguien atestiguó, y el contenido ha cambiado desde entonces. |
+| `none` | Nunca se atestiguó, o se revocó. |
+
+- Una edición no borra una atestación; la deja como `stale` hasta que alguien vuelva a verificar.
+- `revoke=true` la borra. Volver a verificar una fila sin cambios por el mismo actor no hace nada
+ (`changed=false`).
+- El prefijo `human:` proviene del token, por lo que un agente no puede marcar su propia escritura como humana.
+ El `actor` del cuerpo solo se lee en modo dev sin autenticación.
+- Los snapshots y las restauraciones conservan las columnas de atestación; una restauración nunca elimina
+ `verified_by`.
+
+
+
+## Borrado de historial: `memory.redact`
+
+`memory.redact(memory_id, version)` borra el texto de una versión histórica en todos los lugares donde se copió, y también cada versión de perfil que un modelo construyó a partir de la memoria. Registra `redacted_at` y `redaction_reason`, y conserva las filas y sus entradas de auditoría. Úsalo para un secreto o un dato personal que se filtró en una versión anterior.
+
+| Dónde | Qué ocurre |
+| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `loom.memory`, `loom.memory_versions` | `value` pasa a ser `"[REDACTED]"`; `value_json`, `evidence`, `entities` y `concepts` se vacían. |
+| `loom.memory_embeddings`, `loom.memory_chunks` | Se eliminan las filas cuyo extracto o hash de fragmento no coincide con el de la versión activa; las filas de la versión activa se conservan. |
+| Las versiones de perfil del usuario construidas a partir de la memoria | Se borra del mismo modo cada versión cuya traza nombra la memoria, incluida la versión activa, junto con las filas derivadas de su clave. |
+| `loom.shared`, una copia promovida desde la clave | Cada versión cuyo `value` es el texto redactado pasa a ser `"[REDACTED]"`, y se eliminan sus filas de búsqueda. Una copia activa sigue promovida hasta que un administrador la degrade. |
+
+Fuera de alcance: las etiquetas, los archivos, `content_sha256`, `loom.memory_evidence` (gestionada por el borrado definitivo), las tablas de linaje (solo ids y hashes) y el grafo de entidades. Una copia compartida se deja tal cual mientras la versión activa también contenga el texto redactado (una edición revertida byte por byte).
+
+- Rechaza la versión activa de la memoria (`refused_head=true`): primero elimina o reescribe la clave. Un perfil activo ya borrado queda fuera de los renders, los packs y la búsqueda de perfiles hasta que el worker lo reconstruya.
+- Ambos modos de bloqueo la rechazan, tanto en la clave propia de la memoria como en cualquier clave de perfil a la que alcance.
+- Elimina las respuestas en caché de `memory.ask` y `code.ask` y los precedentes que citaron la clave o la clave de una copia compartida (`cache_rows_deleted`, `precedent_rows_deleted`). Para una clave de perfil a la que alcanza, la eliminación es a nivel de toda la organización: el perfil de cada usuario tiene la misma clave, así que borra todas las respuestas en caché y todos los precedentes de la organización cuya ventana contenía esa clave, en todos los espacios de nombres.
+- El espacio de nombres se comprueba después de obtener el dato; un rechazo responde `redacted=false`, no 403.
+- Una versión que no existe responde `redacted=false` y no borra nada, tampoco ninguna versión de perfil.
+- Ejecuta un `ALTER TABLE … UPDATE` síncrono sobre las dos tablas de memoria (y sobre `loom.shared` cuando una copia aún contiene el texto) y un `DELETE` ligero sobre las filas derivadas: es una llamada administrativa.
+
+Escrituras que compiten con la redacción de una copia compartida:
+
+- una fila de búsqueda que el worker de embeddings escribe después de la purga, a partir de un stub que leyó antes, permanece hasta la siguiente redacción de la clave;
+- una promoción de la clave pierde su fila de búsqueda hasta que se vuelva a promover;
+- una degradación que leyó la copia antes del borrado escribe su marca de eliminación con el texto, que permanece hasta que esa versión se redacte de nuevo.
+
+Una copia que una promoción posterior de su clave reemplazó, y que `loom.shared` ha fusionado y descartado desde entonces, ya no se encuentra: su fila de búsqueda, que `FINAL` ya no sirve, permanece hasta una purga posterior de la clave, y las respuestas en caché bajo una clave distinta de la redactada permanecen hasta que caducan.
+
+Una copia cuyo valor es `"[REDACTED]"` cuenta como una que una redacción anterior ya borró, así que una memoria que contiene ese texto por sí misma y fue promovida pierde sus filas de búsqueda en la siguiente redacción de su clave.
+
+El alcance sobre los perfiles y sus límites están en [seguridad](https://github.com/ClickHouse/loom/blob/main/docs/architecture/security.md#sensitivity).
+Para eliminar los datos de una persona en todas partes, usa el [borrado definitivo](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/retention-and-erasure.md#erasure).
+
+
+
+## Revertir un espacio de nombres: `namespace.rollback`
+
+`namespace.rollback(as_of)` reinserta, para cada clave, la versión más alta anterior o igual a
+`as_of` como la nueva versión principal, y marca con tombstone las claves creadas después. La reversión genera a su vez nuevas
+versiones, por lo que puede deshacerse de la misma manera.
+
+- Es una simulación por defecto (dry run) y reporta `reinstate`, `remove` y `sample`; `dry_run=false`
+ la aplica.
+- `memory_keys` (hasta 500) la restringe; `max_keys` (por defecto 5,000) limita una llamada y
+ `truncated` indica que hay que volver a llamar.
+- El `embedding_worker` vuelve a generar los embeddings de las versiones principales reinstauradas.
+- Se rechaza un `as_of` anterior al historial del espacio de nombres o situado en el futuro.
+
+```bash
+curl -sX POST http://localhost:7777/v1/namespace.rollback \
+ -H "Authorization: Bearer $LOOM_API_KEY" -H 'Content-Type: application/json' \
+ -d '{"org":"dev","namespace":"local","as_of":"T09:00:00Z"}' \
+ | jq '{reinstate, remove, truncated, sample}'
+```
+
+
+
+## Snapshots: `namespace.snapshot` y `namespace.restore`
+
+`namespace.snapshot` exporta el estado curado de un espacio de nombres como JSON: cada fila de memoria con
+`version`, `content_sha256`, `actor`, `source_class`, las columnas de validez y de atestación,
+la configuración por tipo, los grants y hasta `include_audit_tail_n` filas de auditoría
+recientes (1,000 por defecto). `include_embeddings` es false por defecto, de modo que el destino vuelve a generar los embeddings
+con su propio modelo.
+
+`namespace.restore(target_namespace, payload)` escribe el payload de vuelta como filas de versión.
+Es idempotente respecto a `snapshot_id` (una nueva ejecución responde `restored=false`). Restaura en un
+espacio de nombres nuevo (quien llama pasa a ser admin; se rechaza si el nombre no tiene ninguna fila pero ya
+contiene datos o grants, salvo que quien llama ya lo administre) o en uno que quien llama administra;
+`rebind_agent` reasigna el escritor de cada fila. Las filas restauradas quedan como `imported`.
+
+Un snapshot no es una copia de seguridad del despliegue; consulta
+[copia de seguridad y recuperación](https://github.com/ClickHouse/loom/blob/main/docs/operations/backup-and-recovery.md).
+
+
+
+## El registro de auditoría
+
+Cada escritura que crea o modifica la memoria deja una fila con solo el hash en `loom.audit_log`
+(clave, id, hash del contenido, actor, clase de origen, veredicto; nunca el valor). Los puntos de control
+horarios encadenan el registro. Consulta [auditoría](https://github.com/ClickHouse/loom/blob/main/docs/features/observability/audit.md).
+
+
+
+## Límites
+
+- **La redacción de una versión fusionada es de mejor esfuerzo** en `loom.memory`; el mirror se depura en cualquier caso.
+- **El historial solo es tan completo como el mirror.** Una columna añadida a `loom.memory` debe añadirse a `loom.memory_versions` y a su vista en la misma migración.
+- **La validez es únicamente de tiempo de validez (valid-time).** `knowledge_time` reproduce `created_at` frente a las marcas de retiro (`invalid_at`) y de eliminación (`tombstoned_at`); no existe una tabla separada de tiempo de transacción.
+- **`thread_exists=false` no es un error.**
+- **Una reversión (rollback) no restaura las claves eliminadas de forma definitiva** (`skipped_no_head`).
+
+
+
+## Relacionado
+
+- [Escritura de memoria](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/writing.md)
+- [Conflictos y rechazo](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/conflicts-and-refusal.md)
+- [Retención y borrado](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/retention-and-erasure.md)
+- [Auditoría](https://github.com/ClickHouse/loom/blob/main/docs/features/observability/audit.md)
diff --git a/i18n/.pending/es/docs/features/runs.md b/i18n/.pending/es/docs/features/runs.md
new file mode 100644
index 0000000000..80baf47233
--- /dev/null
+++ b/i18n/.pending/es/docs/features/runs.md
@@ -0,0 +1,262 @@
+
+> 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/runs.md), que prevalece.
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/features/runs.md), which is authoritative.
+
+
+
+# Ejecuciones
+
+Una ejecución (run) es una ejecución de una tarea, como "triage issue 1234". `run.begin` la abre y devuelve un `run_id`; el
+agente pasa ese id en sus escrituras (`memory.set`, `memory.update`, `observe.record`); `run.complete` la cierra con
+un estado, las memorias en las que se apoyó el agente y, opcionalmente, una reflexión. Un `run_id` en el cuerpo de una lectura (`memory.search`,
+`memory.ask`) filtra por las filas propias de la ejecución, por lo que las lecturas se etiquetan de otra forma: mediante la cabecera `X-Loom-Run-Id` en HTTP
+(`run_scope` en el SDK de Python) y mediante la propia ejecución de la sesión en MCP. Una memoria en la que se apoyó una ejecución exitosa
+se posiciona más alto la próxima vez; una en la que se apoyó una ejecución fallida pierde el impulso que había ganado.
+
+
+
+## Qué registra una ejecución
+
+Una fila de ejecución vive en `loom.agent_runs`. La mayor parte de lo que muestra `run.get` se deriva en el momento de la lectura a partir de los otros planos:
+
+| Campo | Almacenado o derivado | Fuente |
+| ---------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `goal`, `user_request`, `model`, … | almacenado | `run.begin` |
+| `status`, `final_response` | almacenado | `run.complete` (`active` hasta entonces) |
+| `memories_used` | almacenado | `run.complete`: la propia declaración del agente sobre en qué se apoyó |
+| `grade`, `grade_source`, … | almacenado | `run.grade`, después de que la ejecución se cerró |
+| `memories_written` | derivado | filas de `loom.memory` que llevan el `run_id` de la ejecución |
+| `recalled`, `recalled_keys` | derivado | el registro de trazas de búsqueda bajo el `run_id`, unido con `run.complete(recalled_keys)` |
+| `observations` | derivado | filas episódicas de `observe.record` etiquetadas con el `run_id` |
+| `turns`, `cost_usd` | derivado | los turnos de la sesión en `loom.agent_turn_usage` realizados mientras la ejecución estaba abierta (escritos por el plugin de Claude Code, o por un agente con `cost.record_turns`) |
+| `budget_usd`, `budget_seconds` | almacenado | `run.begin` (0 = sin presupuesto) |
+| `elapsed_seconds`, `over_budget` | derivado | desde el inicio de la ejecución hasta su cierre (o hasta ahora), según el reloj del servidor, y `cost_usd`, frente al presupuesto |
+
+`recalled` es `-1` cuando `LOOM_SEARCH_TRACE_LOG_ENABLED` está desactivado y no se enviaron `recalled_keys`.
+
+
+
+## Presupuestos
+
+`run.begin` acepta un `budget_usd` opcional (gasto en modelos) y un `budget_seconds` opcional (cuánto tiempo puede tardar la ejecución). `run.get` los compara con `cost_usd` y `elapsed_seconds` y enumera en `over_budget` los que la ejecución ha superado (`cost`, `time` o ambos). Loom no ejecuta el agente, así que un presupuesto es una señal para quien lo ejecuta, nunca una detención.
+
+El gasto de una ejecución son los turnos de su sesión realizados mientras la ejecución estaba abierta, según la hora propia de cada turno (`turn_at`, tomada de la transcripción), por lo que `budget_usd` requiere un `session_id` (de lo contrario, un 422). Se guarda con 6 decimales, igual que el costo, así que el valor mínimo es $0.000001. El tiempo transcurre desde el inicio de la ejecución hasta su cierre según el reloj del servidor, sea cual sea el `duration_ms` que haya informado el cliente. Define el presupuesto en el primer `run.begin` de la ejecución.
+
+El primer `run.get` de una sesión que encuentra una ejecución activa por encima del presupuesto incluye además la sugerencia del mentor `run_over_budget`, que los plugins entregan al modelo como consejo. Una ejecución cerrada sigue informando `over_budget`, pero no recibe la sugerencia. Como toda sugerencia del mentor, se dice una sola vez por sesión, y un llamador que no envía sesión (el SDK, HTTP plano) comparte una por espacio de nombres y proceso web, así que decide según `over_budget`, no según la sugerencia.
+
+Límites:
+
+- **Solo entre prompts.** El plugin de Claude Code envía los turnos de un prompt cuando este termina (un agente puede enviar los suyos con `cost.record_turns`), por lo que un presupuesto de costo se comprueba entre prompts, y un único prompt headless (`claude -p`) muestra su gasto solo después de terminar. Esos turnos se cuentan igualmente aunque lleguen después del `run.complete` del propio agente. El costo de una llamada solo se conoce después de que esta devuelve, así que una ejecución puede superar `budget_usd` por el costo de su último turno antes de que nada lo detecte.
+- **El reloj del cliente.** La ventana compara las horas de los turnos del cliente con las horas de ejecución del servidor; un reloj desfasado unos minutos coloca mal los turnos en los bordes de una ejecución. Un turno conserva la hora con la que se envió, así que un turno reenviado permanece en la ejecución en la que cayó la primera vez. Uno enviado sin hora (o con una que no se pueda interpretar) toma la hora con la que se registra su `message_id`, o la actual si es nuevo; un reenvío a una fracción de segundo del primero aún puede quedar fechado con la hora actual. `cost.record_turns` responde con `turns_dated_ahead`, los turnos que recibió con fecha más de 5 s posterior al reloj del servidor, de modo que un llamador que envía turnos por su cuenta pueda detectar un reloj adelantado; el plugin de Claude Code los envía sin leer la respuesta.
+- **Una sesión, varias ejecuciones.** Las ejecuciones abiertas a la vez en una misma sesión ven los mismos turnos: una ejecución anidada cuenta para ambas, y los workers concurrentes que quieran cada uno un presupuesto de costo necesitan sus propias sesiones.
+- **Modelos sin precio.** Un turno cuyo modelo no figura en la tabla de precios cuesta 0; `run.get` los cuenta en `unpriced_turns` y no cuentan para `budget_usd`.
+- **MCP.** Las herramientas MCP ofrecen solo `budget_seconds`, ya que el modelo no conoce el id de sesión con el que se registran sus turnos.
+- **Reintentos.** Un `run.begin` reenviado reemplaza la fila de la ejecución como cualquier reintento: conserva la sesión y el presupuesto que no se vuelven a indicar, un nuevo presupuesto distinto de cero reemplaza al anterior, y 0 lo mantiene.
+ Un nuevo `budget_usd` debe enviarse con su `session_id` (de lo contrario, un 422); un nuevo `budget_seconds` no necesita nada más.
+ Un begin reenviado que mueve la ejecución a otra sesión elimina su presupuesto de costo, que se definió para los turnos de la sesión anterior, conserva su presupuesto de tiempo y lo indica en su `next`. Esa es la única forma de quitar un presupuesto.
+ Cuando `run.begin` respondió con un `run_id` distinto del enviado, reenvía ese `run_id`, o el mismo `session_id`; de lo contrario, el reintento abre una nueva ejecución.
+
+
+
+## Recuperado no es lo mismo que utilizado
+
+Dos listas viajan en `run.complete`:
+
+- **`memories_used`** — las claves en las que el agente se apoyó realmente. Cada una recibe un evento de uso `used`, más un evento `evidence` si el resultado es positivo o un evento `harm` si es negativo. `outcome` toma su valor por defecto de `status`: `completed` es positivo, `failed` es negativo y `cancelled` es ninguno.
+- **`recalled_keys`** — las claves que las herramientas de Loom devolvieron durante la ejecución (los plugins de Claude Code y Codex las guardan a partir de los resultados de `loom_search` y `memory.get` y las envían al final de la sesión). Se registran para `run.get` y nunca se acreditan.
+
+Una fila que se devolvió pero se ignoró no recibe nada; acreditar cada resultado de búsqueda premiaría lo que quede primero en el ranking.
+El worker `usage_fold` integra los eventos en el término de refuerzo por el que ordena la [búsqueda de memoria](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/search-and-ask.md). Un evento `harm` retira el impulso ganado, con un mínimo igual a la base de la fila en el momento de escritura, de modo que una mala ejecución nunca empuja una fila por debajo de su relevancia y nunca la elimina.
+
+Una clave de procedimiento mencionada en `memories_used` también obtiene una fila en el registro de procedimientos (ruta vacía, `ok` según el resultado); un agente que llama a `procedure.record_run` por su cuenta debe dejar esa clave fuera de `memories_used` para que la ejecución no se cuente dos veces. Consulta
+[procedimientos y aprendizajes](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/procedures-and-learnings.md).
+
+
+
+## Reflexiones
+
+`run.complete(reflection=...)` registra `what_worked`, `what_failed`, `assumptions`, `lessons`, `improvements` (hasta
+20 elementos cada uno), un `confidence` y las claves de `evidence` en las que se apoya la lección. Se almacena como una memoria de tipo
+`reflection` bajo `reflection:`:
+
+- se genera su embedding, de modo que una ejecución posterior puede encontrarla con `memory.search(memory_type="reflection")`,
+ pero queda fuera de la búsqueda sin filtros y de `memory.ask`;
+- `what_failed` y `lessons` necesitan al menos una clave de `evidence` (de lo contrario, se devuelve un 422);
+- caduca tras `expires_in_days` (90 por defecto, `0` = nunca) a menos que `memory.verify`
+ o un resultado positivo la renueve;
+- una ejecución abierta con `role` (planner, executor, critic, o una palabra propia) etiqueta su
+ reflexión con `role:`, de modo que el `memory.search(role=...)` de un agente con el mismo rol la prioriza.
+
+
+
+## Qué ocurre con las filas que escribió una ejecución
+
+`retain` en `run.complete` decide el destino de las memorias escritas durante la ejecución:
+
+| `retain` | Efecto |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `keep` (default) | No cambia nada. |
+| `demote` | Su confianza se reduce de inmediato. |
+| `expire` | Se establece una expiración a `LOOM_MEMORY_RUN_COMPLETE_EXPIRE_DAYS` días (por defecto 7) con `on_expire=demote`; el worker `memory_expiry_sweep` la aplica. |
+
+Las filas fijadas, verificadas, promovidas, bloqueadas, episódicas y de reflexión se conservan sea cual sea el
+modo, y ningún modo marca nada como eliminado. El valor por defecto proviene de
+`LOOM_MEMORY_RUN_COMPLETE_RETAIN`; la ejecución implícita de una sesión MCP siempre conserva, ya que
+el transporte que la cierra no puede juzgar el trabajo.
+
+
+
+## Ejecuciones calificadas
+
+`status` indica que la ejecución terminó; una calificación indica si su resultado se sostuvo. A menudo la calificación llega días después, cuando CI
+pasa o un revisor rechaza el pull request. `run.grade` recibe `grade` (`pass` o `fail`), un `source` (`maintainer`,
+`ci`, `reviewer`, … texto libre), un `reason` y un `ref` (una URL, una clave de hallazgo, el id de una ejecución de
+verificación), dirigidos a un `run_id` o a todas las ejecuciones cerradas de un `session_id` (por ejemplo
+`pr_1234`). Una recalificación reemplaza el veredicto; el mismo veredicto de la misma fuente no
+cambia nada. Las ejecuciones activas se omiten.
+
+Cada memoria en `memories_used` de una ejecución calificada se cuenta frente a la calificación. Esos
+recuentos son lo que `memory.proposals` muestra junto a cada dato a prueba (una
+fila de `memory.set(proposed=true)`). Loom decide una propuesta a partir de ellos solo cuando el
+propietario del espacio de nombres configuró `proposal_policy.mode` como `auto`; cualquier escritor decide con
+`memory.proposal_decide` en cualquiera de los dos modos. Consulta [escritura de memoria](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/writing.md).
+
+`run.list(grade="ungraded")` lista las ejecuciones cerradas a las que aún se les debe un veredicto.
+
+Una sesión MCP obtiene una ejecución implícita sin pedirla: su primera llamada a una herramienta
+con alcance de ejecución inicia una, y `DELETE /mcp` o el worker `mcp_session_run_sweep` la cierra
+(consulta [MCP](https://github.com/ClickHouse/loom/blob/main/docs/reference/mcp.md)). El barrido cierra una ejecución activa con
+`environment='mcp'` y `metadata.implicit` en true cuyo id es `mcp-` más 40 caracteres
+hexadecimales (la forma que solo produce el transporte). La cierra cuando ninguna llamada de
+su token (de cualquiera, si la ejecución no registra token) la alcanzó dentro de
+`LOOM_MCP_SESSION_RUN_IDLE_SECONDS`. La ejecución reside en el espacio de nombres predeterminado del llamador, de modo que lo que ven sus lectores se queda allí: su objetivo es la etiqueta
+`mcp session ()`, nunca el texto de una llamada (la consulta de una lectura puede alcanzar cualquier
+espacio de nombres que lea el llamador), y `memories_written` lista únicamente las escrituras en ese
+espacio de nombres (las demás siguen llevando su `run_id`). Cerrarla no juzga nada:
+su resultado es `none` y sus memorias se conservan sea cual sea el modo de retención predeterminado del servidor, de modo que dos cierres que compiten por ella (el barrido en dos hosts, un `DELETE`)
+a lo sumo escriben dos veces la misma finalización.
+
+Cómo la ejecución abarca varios procesos web. Su id es un hash de la organización del llamador, del
+sujeto del token y del `Mcp-Session-Id`, de modo que todos los procesos del servidor nombran
+la misma ejecución para la sesión y ningún otro token puede nombrarla enviando el mismo
+id de sesión. Un proceso registra la ejecución en la primera llamada admitida con alcance de ejecución de la sesión y escribe la fila de inicio en segundo plano (un insert con espera
+retendría esa llamada durante segundos en ClickHouse Cloud); una llamada que las compuertas rechazan
+no escribe ninguna fila de ejecución. Dos procesos que no encuentran ninguna fila escriben cada uno un primer inicio,
+y gana el inicio más temprano y su propietario (la versión de fila de un primer inicio cuenta hacia atrás
+desde su inicio; toda escritura posterior la reemplaza). Cada proceso comprueba una ejecución en caché contra el registro como máximo una vez
+por minuto y la reabre cuando un `DELETE` o el barrido la cerró entretanto.
+Un `DELETE` cierra la ejecución en cualquier proceso al que llegue, por su id; el cierre
+cuenta todas las escrituras bajo ese id, sin importar quién la cierre. Un `DELETE` que llega a
+otro proceso antes de que la fila de inicio haya aterrizado no encuentra nada que cerrar,
+y el inicio aterriza entonces como una ejecución abierta que el barrido cierra cuando queda inactiva: un reintento corto no cubriría un inicio que tarda segundos, y retrasaría el `DELETE`
+de toda sesión que nunca tomó una ejecución. Una ejecución reabierta conserva su `started_at` original, de modo que una ejecución cerrada por el barrido y reabierta más tarde informa un
+`duration_ms` contado desde la primera llamada de la sesión, huecos incluidos. Una comprobación que
+no encuentra ninguna fila, porque un borrado por erasure la eliminó, inicia una nueva ejecución con inicio en ese momento,
+de modo que no vuelve ninguna ejecución con fecha anterior al borrado.
+
+
+
+## Operaciones
+
+| Operación | Rol | Qué hace |
+| -------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `run.begin` | writer | Abre una ejecución: `goal` (obligatorio), `user_request`, `expected_outcome`, `run_id` (vacío o `-`: se genera uno), `session_id`, `role`, `model`, `metadata`. Reenviar el mismo `run_id` reemplaza la fila; un id con la forma del transporte MCP (`mcp-` y 40 dígitos hexadecimales) recibe un id propio. |
+| `run.complete` | writer | La cierra una sola vez: `status`, `memories_used`, `recalled_keys`, `outcome`, `reflection`, `retain`. No es idempotente: completarla dos veces añade los eventos de uso dos veces. |
+| `run.get` | viewer | Una ejecución con sus derivaciones vigentes. |
+| `run.list` | viewer | Una página de ejecuciones, filtradas por `agent`, `session_id`, `status`, `grade`, `q` y `memory_activity` (`with` conserva las ejecuciones que se apoyaron en una memoria o escribieron una, `without` las vacías; los filtros se aplican antes de `limit`). |
+| `run.grade` | writer | Califica una ejecución cerrada, o las ejecuciones de una sesión, como `pass` / `fail`. |
+
+`run.list` pagina con `order_by` (hora de inicio, duración o memorias usadas, cada una
+ascendente o descendente; por defecto `started_desc`, las más recientes primero) y `offset` (como máximo
+100,000). `q` conserva las ejecuciones cuyo objetivo, id de ejecución o agente contiene el texto, sin distinguir mayúsculas de minúsculas. `total`
+cuenta todas las ejecuciones que coinciden con los filtros, y es null en una página completa posterior a la primera, donde
+la página por sí sola no puede determinarlo.
+
+Las listas completas de campos están en la [referencia de operaciones](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md#run).
+`memory.outcome_run` registra un resultado helped / hurt para cada memoria recuperada durante una
+ejecución, para los llamadores que califican en bloque en lugar de nombrar claves.
+
+
+
+## Ejemplo
+
+El `run.scope` del SDK de Python abre la ejecución al entrar y la cierra al salir. Las claves que una respuesta de
+`memory.ask` citó dentro del bloque, más las que se pasen a `used()`, pasan a ser
+`memories_used`; una excepción cierra la ejecución como `failed` (resultado negativo) y luego
+se propaga. Las escrituras dentro del bloque llevan el id de la ejecución.
+
+```python
+from loom import Agent
+
+async with Agent(org="acme", namespace="support", agent="triage-bot") as agent:
+ async with agent.run.scope(goal="Answer ticket 4411: refund policy for annual plans") as run:
+ answer = await agent.memory.ask("what is the refund policy for annual plans?")
+ run.used("policy/refunds/annual") # relied on beyond what the answer cited
+ run.final_response = answer["answer"]
+
+ replay = await agent.run.get(run.run_id)
+ print(replay["run"]["status"], replay["memories_written"], replay["recalled"])
+
+ # Later, once the customer confirmed the answer was right:
+ await agent.run.grade("pass", run_id=run.run_id, source="support-lead")
+```
+
+Por HTTP, el ciclo de vida son dos llamadas:
+
+```bash
+curl -sX POST "$LOOM_BASE_URL/v1/run.begin" -H "Authorization: Bearer $LOOM_API_KEY" \
+ -H 'Content-Type: application/json' \
+ -d '{"org":"acme","namespace":"support","agent":"triage-bot","goal":"Answer ticket 4411"}'
+# → {"run_id":"…","status":"active","started_at":"…","next":"…"}
+
+curl -sX POST "$LOOM_BASE_URL/v1/run.complete" -H "Authorization: Bearer $LOOM_API_KEY" \
+ -H 'Content-Type: application/json' \
+ -d '{"org":"acme","namespace":"support","run_id":"…","status":"completed",
+ "memories_used":["policy/refunds/annual"]}'
+```
+
+`Agent(auto_run=True)` (o `LOOM_AUTO_RUN=on` en el entorno del cliente) abre una ejecución
+de forma diferida en la primera llamada al plano de memoria, hace pasar por ella todas las llamadas posteriores y
+la completa cuando el `Agent` se cierra, con resultado `none`, de modo que nunca acredita ni penaliza nada. Está desactivado por
+defecto porque una escritura bajo una ejecución queda limitada a ella: la reformulación de una fila de otra ejecución se almacena como `duplicate`
+en lugar de fusionarse.
+
+
+
+## Configuración
+
+| Configuración | Efecto |
+| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `LOOM_MEMORY_RUN_COMPLETE_RETAIN` | El modo `retain` cuando una llamada no indica ninguno (`keep`). |
+| `LOOM_MEMORY_RUN_COMPLETE_EXPIRE_DAYS` | Cuánto tiempo después `retain=expire` fija la caducidad (7 días). |
+| `LOOM_SEARCH_TRACE_LOG_ENABLED` | Registra cada búsqueda bajo su `run_id`, del cual se deriva `recalled`. Desactivado por defecto porque registra el texto de las consultas. |
+| `LOOM_USAGE_FOLD_ENABLED` | El proceso en segundo plano `usage_fold`, que convierte los eventos de uso, evidencia y daño en ranking. |
+| `LOOM_MEMORY_SEARCH_REINFORCEMENT_WEIGHT`, `…_HALF_LIFE_DAYS` | Cuánto, y durante cuánto tiempo, la confianza en una fila la eleva en la búsqueda. |
+
+Consulta [configuración: deduplicación y caducidad](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#dedup-and-expiry),
+[procesos en segundo plano](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#workers) y
+[búsqueda de memoria](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#memorysearch).
+
+
+
+## Límites
+
+- `memories_used` y `recalled_keys` aceptan como máximo 500 claves cada uno; `goal` acepta como máximo 2,000
+ caracteres.
+- Una clave de `memories_used` que no se resuelve a una fila activa no suma nada;
+ `used_applied` en la respuesta cuenta las que sí se resolvieron.
+- `run.complete` no es idempotente. Si se reintenta una finalización, los eventos de uso se contabilizan dos veces;
+ complétala una sola vez.
+- El `run.scope` del SDK escribe el registro con el mejor esfuerzo: un `run.complete` fallido nunca
+ oculta la excepción del propio bloque, por lo que una ejecución cuya finalización falló sigue en estado `active`.
+- `turns` y `cost_usd` valen 0 cuando la ejecución no tiene `session_id` o el cliente no
+ informa el uso de turnos. Solo cuentan los turnos realizados mientras la ejecución estaba abierta.
+
+
+
+## Relacionado
+
+- [Trazar y reanudar ejecuciones largas](https://github.com/ClickHouse/loom/blob/main/docs/guides/trace-and-resume.md) — checkpoints en la memoria de trabajo indexados por `run_id`, y cómo trazar lo que hizo una ejecución.
+- [Buscar y preguntar](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/search-and-ask.md) — cómo entra el refuerzo en el ranking.
+- [Tareas y decisiones](https://github.com/ClickHouse/loom/blob/main/docs/features/tasks-and-decisions.md) — `decision.outcome` acredita las memorias en las que se apoyó una ejecución que tomó una decisión.
+- [Arquitectura de la memoria](../architecture/memory-architecture.md) — el plegado de eventos de uso y las tablas que lo sustentan.
diff --git a/i18n/.pending/es/docs/glossary.md b/i18n/.pending/es/docs/glossary.md
new file mode 100644
index 0000000000..182506efc1
--- /dev/null
+++ b/i18n/.pending/es/docs/glossary.md
@@ -0,0 +1,158 @@
+
+> Esta página es una traducción automática de la [página en inglés](https://github.com/ClickHouse/loom/blob/main/docs/glossary.md), que prevalece.
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/glossary.md), which is authoritative.
+
+
+
+# Glosario
+
+Los términos de Loom, en orden alfabético, cada uno definido una sola vez. Los identificadores de código van entre acentos graves.
+
+**Abstain** — `memory.search` devuelve `abstain=true` con un código de motivo en lugar de la coincidencia débil más cercana, cuando el mejor resultado queda por debajo del umbral de abstención calibrado para el embedder.
+Distingue entre "no se almacenó nada" y "algo no relacionado obtuvo 0.3".
+Consulta [recuperación y ranking](https://github.com/ClickHouse/loom/blob/main/docs/concepts/retrieval-and-ranking.md).
+
+**Actor** — la columna estampada por el servidor que indica quién escribió una fila: `human:` o `process:`, con el tipo tomado del token. Nunca se lee del cuerpo de la solicitud.
+Consulta [identidades y espacios de nombres](https://github.com/ClickHouse/loom/blob/main/docs/concepts/identities-and-namespaces.md).
+
+**Agente** — el tercer elemento de la tupla de identidad: el nombre del programa que escribe y lee (`claude-code`, `support-bot`). Registra la autoría; no es un límite de lectura: todos los miembros de un espacio de nombres leen las filas de todos los agentes.
+
+**Attestation** — las columnas `verified_*` que registran que una fila fue verificada. Una edición las deja en su lugar y las marca como obsoletas; el lector decide la confianza comparando el hash de contenido atestiguado. Consulta [historial y procedencia](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/history-and-provenance.md).
+
+**Registro de auditoría** — `loom.audit_log`: una fila con hash de contenido por cada operación auditada, agrupadas en puntos de control horarios encadenados por hash. Las filas contienen hashes, no contenido.
+Consulta [auditoría](https://github.com/ClickHouse/loom/blob/main/docs/features/observability/audit.md).
+
+**Revisión de creencias** — la perspectiva de diseño del ciclo de vida de la memoria: Expand (`memory.set`), Revise (`memory.update_by_id`), Contract (`memory.delete`), Reinforce (`memory.pin`), Refuse (`blacklist.add`). Consulta [cómo se juzga una escritura](https://github.com/ClickHouse/loom/blob/main/docs/concepts/memory.md#how-a-write-is-judged).
+
+**Blacklist** — subcadenas o expresiones regulares registradas que rechazan las escrituras coincidentes (`422 BLACKLISTED`); `sweep=true` también marca con tombstone las coincidencias existentes.
+
+**Fragmento (chunk)** — una porción de un documento de conocimiento o de un archivo fuente, almacenada y con embedding por separado para que la recuperación pueda devolver el pasaje en lugar del documento completo.
+
+**Enlace de código** — el vínculo de una memoria con una definición o un archivo que nombra, seguido a través de renombrados y ediciones. Su estado es `fresh`, `moved`, `changed`, `unresolved` o `missing`.
+Un nombre de código que aún no está en trunk espera hasta `memory_code_links_pending_days` (14 días).
+Consulta [memorias enlazadas a código](https://github.com/ClickHouse/loom/blob/main/docs/concepts/memory.md#memories-linked-to-code).
+
+**Espacio de nombres de código** — un espacio de nombres de tipo `code` que contiene un repositorio git indexado: sus fragmentos, símbolos, aristas, commits e historial de PR.
+Consulta [índice de código](https://github.com/ClickHouse/loom/blob/main/docs/features/code-index/overview.md).
+
+**Cobertura de commit** — si todos los niveles del índice han procesado un commit dado; `code.index_status(commit=...)` lo responde, y `code.coverage.watch` notifica cuando pasa a ser verdadero. Consulta [frescura](https://github.com/ClickHouse/loom/blob/main/docs/features/code-index/freshness.md).
+
+**Nivel del compilador** — hechos del índice de código derivados de un indexador de calidad de compilador (SCIP) en lugar del nivel del parser; aristas de llamada y referencias resueltas mediante información de tipos.
+
+**Conflicto** — una escritura semánticamente cercana a una memoria existente (coseno ≥ `LOOM_CONFLICT_THRESHOLD`). Ambas filas se marcan como `conflicted` y quedan enlazadas entre sí; una persona o un agente las resuelve. Consulta [conflictos y rechazo](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/conflicts-and-refusal.md).
+
+**Consolidación** — el proceso en segundo plano que fusiona memorias fragmentadas sobre el mismo sujeto y registra el linaje (`memory_belief_sources`, `support_type='derived_from'`).
+
+**Hash de contenido** — `content_sha256` del valor de una memoria. Deduplica repeticiones exactas, respalda la precondición `if_match_sha256` y ancla las filas de auditoría.
+
+**Paquete de contexto** — `context.pack`: un conjunto acotado de memoria de trabajo, perfil, memorias relevantes, procedimientos y decisiones, cargado una vez al inicio de una sesión.
+Consulta [búsqueda unificada](https://github.com/ClickHouse/loom/blob/main/docs/features/unified-search.md#contextpack).
+
+**Panel** — la aplicación web en la raíz del servidor, para personas: memoria, actividad, fuentes, cola de revisión, tareas, repositorios y configuración. Consulta [panel](https://github.com/ClickHouse/loom/blob/main/docs/features/dashboard.md).
+
+**Decisión** — un registro de primera clase de una elección (`decision.record`) con su razonamiento, alternativas descartadas y, más adelante, su resultado (`decision.outcome`).
+Consulta [tareas y decisiones](https://github.com/ClickHouse/loom/blob/main/docs/features/tasks-and-decisions.md).
+
+**Arista de entidad** — un vínculo ponderado de coocurrencia entre dos entidades en `loom.entity_edges`, con un intervalo de validez; el grafo que recorre `facts.traverse`.
+Consulta [grafo de entidades](https://github.com/ClickHouse/loom/blob/main/docs/features/entity-graph.md).
+
+**Saga de borrado** — la secuencia reanudable y con cierre ante fallos de pasos que ejecuta `erasure.request` para eliminar los datos de un sujeto de todas las tablas (y de los backends externos configurados), y que termina con un censo de residuos. Consulta [retención y borrado](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/retention-and-erasure.md).
+
+**Extracción** — convertir mensajes de conversación en memorias candidatas (`memory.set_from_messages`), con un LLM y filtros de calidad.
+Consulta [extracción](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/extraction.md).
+
+**Extractor stamp** — un hash de los tokens de código de los módulos extractores del índice de código. Un cambio en él vuelve a fragmentar todos los repositorios indexados; los comentarios y docstrings no cuentan.
+Consulta [arquitectura del índice de código](architecture/code-index-architecture.md).
+
+**FINAL** — el modificador de ClickHouse que reduce una tabla `ReplacingMergeTree` a la última versión por clave en el momento de la lectura. Loom lee `loom.memory` con él.
+Consulta [ClickHouse](architecture/clickhouse.md).
+
+**Fence** — el token que `task.claim` devuelve junto con un arrendamiento; las llamadas posteriores a `task.progress`, `task.heartbeat`, `task.complete` y `task.fail` deben presentarlo, de modo que quien haya perdido el arrendamiento no pueda escribir.
+
+**Grant** — una fila que otorga a un sujeto un rol sobre un espacio de nombres (`grants.*`).
+Consulta [tokens y grants](https://github.com/ClickHouse/loom/blob/main/docs/guides/tokens-and-grants.md).
+
+**Tupla de identidad** — `(org, namespace, agent, user_id, session_id)` en cada fila. Los tres primeros son obligatorios; los dos últimos toman por defecto `'-'`.
+Consulta [identidades y espacios de nombres](https://github.com/ClickHouse/loom/blob/main/docs/concepts/identities-and-namespaces.md).
+
+**`ignored_args`** — el campo de respuesta que nombra los campos de la solicitud que el servidor no usó (desconocidos o retirados), de modo que el cliente detecta la deriva sin que haya un fallo.
+
+**Inbox** — una cola con nombre de tareas que pertenece a un espacio de nombres (`task.*`, `inbox.*`).
+Consulta [tareas y decisiones](https://github.com/ClickHouse/loom/blob/main/docs/features/tasks-and-decisions.md).
+
+**Documento de conocimiento** — un documento añadido con `knowledge.add`, dividido en fragmentos y con embeddings para su recuperación. Distinto de una memoria: es material de referencia, no una creencia.
+Consulta [documentos de conocimiento](https://github.com/ClickHouse/loom/blob/main/docs/features/knowledge.md).
+
+**Learning** — un candidato que espera en `loom.learnings_queue` la decisión de una persona (`learnings.list`, `learnings.review`): un hecho respaldado por varios escritores, promovido a la capa compartida; un hecho originado en una conversación, promovido a una fila de memoria del espacio de nombres; o una regla que un bot enunció sobre sí mismo, promovida al conocimiento del espacio de nombres.
+
+**`log_comment`** — el ajuste de consulta de ClickHouse que Loom rellena con la op, el worker o el comando de CLI que realiza la llamada, de modo que `system.query_log` atribuye cada sentencia.
+
+**`maturity`** — el campo declarado de una op, `stable`/`experimental`. Una op experimental que ni el conjunto core ni el atomic incluyen queda fuera del listado `all`; sigue pudiéndose llamar por su nombre. Consulta [toolsets de MCP](https://github.com/ClickHouse/loom/blob/main/docs/reference/mcp.md#toolsets).
+
+**Herramienta MCP** — la proyección de una op en el Model Context Protocol, llamada `loom_` con los puntos sustituidos por guiones bajos (`loom_memory_set`), más algunas herramientas sintéticas como `loom_search` y `loom_op`. Consulta [MCP](https://github.com/ClickHouse/loom/blob/main/docs/reference/mcp.md).
+
+**Memoria** — una fila en `loom.memory`: una clave, un valor, su tupla de identidad, tipo, etiquetas, validez y procedencia. Consulta [memoria](https://github.com/ClickHouse/loom/blob/main/docs/concepts/memory.md).
+
+**Clave de memoria** — el identificador legible de una memoria dentro de su espacio de nombres y agente, por convención `//`. Una escritura sobre una clave existente la reemplaza.
+
+**Tipo de memoria** — la clase de una memoria: `semantic`, `episodic`, `procedural`, `preference`, `profile` y otras; el tipo decide si se le calcula un embedding y cómo se busca.
+
+**Mentor hint** — una breve sugerencia de uso que Loom adjunta a los resultados o sirve mediante `mentor.brief`, y que orienta a un agente hacia un plano o una op que no está aprovechando bien.
+
+**Espacio de nombres** — la unidad de almacenamiento, compartición y acceso: un espacio de trabajo con nombre dentro de una org. Los tipos son `memory`, `code` y `bench`.
+Consulta [espacios de nombres y compartición](https://github.com/ClickHouse/loom/blob/main/docs/features/namespaces-and-sharing.md).
+
+**Operación (op)** — una entrada declarada en el registro (`server.operations.registry.ALL_OPERATIONS`), servida en `POST /v1/`, como herramienta MCP y mediante los SDK.
+Consulta [referencia de operaciones](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md).
+
+**Org** — el tenant de nivel superior; el primer elemento de la tupla de identidad.
+
+**Pinned** — una memoria marcada con `memory.pin`. Una escritura en conflicto con una memoria fijada se rechaza con `409 PINNED_CONFLICT`.
+
+**Plano** — un área de producto con sus propias ops y tablas: memoria, conocimiento, conversación, grafo, código, tracker, ejecuciones y tareas, auditoría.
+
+**Procedimiento** — un how-to reutilizable (`procedure.add` / `match`), almacenado como una memoria de tipo `procedural`. Consulta [procedimientos y learnings](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/procedures-and-learnings.md).
+
+**Perfil** — el contexto permanente de un agente o usuario (`profile.*`), cargado en primer lugar por `context.pack`.
+
+**Proyección** — una fila derivada de una escritura (un embedding, una arista de grafo, un resumen). Una proyección que falla se registra y se reintenta (`ops.projection_failures.*`).
+
+**Alcance de lectura** — `read_scope`, que acota una lectura dentro de un espacio de nombres: `namespace` (todas las filas, el valor por defecto), `own_user` u `own_session`. La reclamación de un token es un techo que una solicitud puede estrechar pero no ampliar.
+Consulta [identidades y espacios de nombres](https://github.com/ClickHouse/loom/blob/main/docs/concepts/identities-and-namespaces.md#read-scope-inside-a-namespace).
+
+**Registro (record)** — una memoria estructurada validada contra un esquema de registro (`memory_schema.*`). No debe confundirse con un registro del tracker.
+
+**ReplacingMergeTree (RMT)** — el motor de ClickHouse detrás de la mayoría de las tablas de Loom: una fila de nueva versión reemplaza a la anterior al fusionar o al leer con `FINAL`, por lo que toda ruta de escritura debe arrastrar todas las columnas. Consulta [ClickHouse](architecture/clickhouse.md).
+
+**Censo de residuos** — el último paso de una saga de borrado: un recuento de filas vivas dentro del alcance en todas las tablas que tocan las rutas de lectura. Cualquier residuo hace fallar la saga.
+
+**Rol** — `viewer`, `writer`, `admin`, `org_admin`, `platform_admin`, en orden creciente de privilegio. Cada op declara el mínimo que necesita.
+
+**Ejecución (run)** — una ejecución de un agente, delimitada por `run.begin` y `run.complete`, que registra lo que recuperó y escribió. Consulta [ejecuciones](https://github.com/ClickHouse/loom/blob/main/docs/features/runs.md).
+
+**Sesión** — una conversación o período de trabajo, el quinto elemento de la tupla de identidad; un **resumen de sesión** (`session.brief_*`) es su resumen guardado para retomarla más tarde.
+
+**Capa compartida** — una fila canónica por `(org, namespace, memory_key)`, promovida a partir de las filas que escriben los agentes (`memory.promote` / `memory.demote`, tabla `loom.shared`).
+"Privada" para la otra capa significa no promovida, no oculta.
+
+**Clase de fuente** — la procedencia de una fila estampada por el servidor: `asserted`, `extracted`, `observed`, `derived`, `imported` o `external`. Una solicitud solo puede degradarla.
+
+**Nivel (tier)** — qué extractor produjo un hecho del índice de código (parser o compilador); las respuestas indican qué nivel las respalda.
+
+**Tombstone** — una fila de versión superior que marca una memoria como eliminada. `memory.restore` puede deshacerlo dentro del período de gracia; `memory.delete` no elimina nada físicamente.
+
+**Toolset** — el listado de MCP que solicita un cliente (`core`, `coding`, `atomic`, `tasks`, `tracker`, `readonly`, `all`); cambia lo que se lista, no lo que el token puede llamar.
+
+**Tracker** — el plano que lee los registros de un issue tracker (issues, PRs, ejecuciones de CI) desde una fuente configurada para comprobar duplicados, bisect e historial de tests.
+Consulta [rastreador](https://github.com/ClickHouse/loom/blob/main/docs/features/tracker/overview.md).
+
+**Modo de confianza** — la política de aceptación que el propietario de un inbox establece para quien publica; Loom la almacena y nunca la cambia por sí mismo.
+
+**Tiempo de validez** — `valid_at` / `valid_to` en las memorias (`valid_from` / `valid_to` en las aristas de entidad): cuándo un hecho fue verdadero en el mundo. Loom registra solo el tiempo de validez; no es bitemporal.
+
+**Versión** — la columna monótonamente creciente de la que un `ReplacingMergeTree` conserva el valor más alto; cada escritura de una memoria (incluido un borrado) es una nueva versión.
+
+**Worker** — un bucle supervisado en segundo plano registrado como una fila en `server/workers/registry.py` (`_WORKERS`). Consulta [procesos de trabajo](https://github.com/ClickHouse/loom/blob/main/docs/reference/workers.md).
+
+**Memoria de trabajo** — bloques de notas (`working_memory.*`) para la tarea en curso: sin embedding, sin ranking, cargados por `context.pack` antes que la memoria duradera.
+Consulta [memoria de trabajo y perfiles](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/working-memory-and-profiles.md).
diff --git a/i18n/.pending/es/docs/guides/performance-tuning.md b/i18n/.pending/es/docs/guides/performance-tuning.md
new file mode 100644
index 0000000000..bb7c99d19c
--- /dev/null
+++ b/i18n/.pending/es/docs/guides/performance-tuning.md
@@ -0,0 +1,177 @@
+
+> Esta página es una traducción automática de la [página en inglés](https://github.com/ClickHouse/loom/blob/main/docs/guides/performance-tuning.md), que prevalece.
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/guides/performance-tuning.md), which is authoritative.
+
+
+
+# Ajustar el rendimiento de Loom
+
+Cada palanca de esta página es un ajuste de configuración o un campo de solicitud. La
+[referencia de configuración](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md) indica el valor predeterminado y el
+significado de cada ajuste. Cuando un equilibrio se ha medido, la página nombra el comando que lo mide.
+
+
+
+## Mide primero
+
+| Pregunta | Comando | Requiere |
+| -------------------------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------- |
+| p50 / p95 / p99 y RPS de una op con concurrencia N | `make bench OP=memory.search C=5 D=60` (`scripts/ops/benchmark.py`) | un servidor en ejecución; las escrituras van a un espacio de nombres `bench-…` |
+| ¿Un cambio de ranking o de embedder perjudicó el recall? | `make bench-quick` (un fragmento de un benchmark público de memoria a largo plazo con un juez de respuestas) | proveedores reales, `OPENAI_API_KEY` |
+| Recall frente a la línea base registrada | `make bench-quality-gate MIN_RECALL=…` | proveedores reales |
+| modo de búsqueda × rerank × ancho del pool | `make bench-matrix` (escribe `bench/MATRIX_RESULTS.md`) | un servidor en ejecución |
+| Regresiones de extracción y de extracción de grafos | `make bench-algorithm-gate` | un servidor en ejecución |
+| Símbolo, callers, recall y costo de tokens del plano de código | `make bench-code-intel`, `make bench-code-legs` | un embedder real |
+| Qué cambió después de un despliegue | `loom deploy-delta` (formas de las sentencias del ledger y de ClickHouse a cada lado del swap) | `var/deployed.json` |
+
+> **Advertencia:** un valor de recall medido con el embedder falso no dice nada sobre la
+> recuperación real. Por eso los quality gates se mantienen fuera de CI. Ejecútalos contra
+> un servidor con los proveedores que vas a desplegar, y vuelve a fijar la línea base tras
+> cualquier cambio de embedder.
+
+Para una sola petición lenta, lee su cabecera `Server-Timing` (`app` frente a `ch`) y sus
+filas de `system.query_log` antes de tocar cualquier ajuste ([depuración](https://github.com/ClickHouse/loom/blob/main/docs/guides/debugging.md)). El costo por
+operación en todo el despliegue es una consulta sobre `log_comment`:
+
+```sql
+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;
+```
+
+El tráfico de benchmark justo después de un swap lee cachés frías; espera antes de
+comparar la latencia de un despliegue con la de la compilación anterior.
+
+
+
+## Ranking y umbrales
+
+`memory.search` ordena un conjunto de candidatos de primera etapa y después aplica términos de ranking y umbrales ([recuperación y ranking](https://github.com/ClickHouse/loom/blob/main/docs/concepts/retrieval-and-ranking.md)). La mayoría de los términos se pueden configurar por despliegue y sobrescribir por solicitud, de modo que un cambio se puede probar con A/B primero en un solo cliente.
+
+| Palanca | Configuración (campo de la solicitud) | Compromiso |
+| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| Umbrales de similitud | `LOOM_ADAPTIVE_THRESHOLDS` (activado por defecto) | Activado: los umbrales se derivan al arrancar de la propia distribución de coseno del embedder. Desactivado: usted gestiona los umbrales escalares de abajo. |
+| Umbrales escalares (respaldo) | `LOOM_MEMORY_SEARCH_MIN_SIMILARITY`, `LOOM_MEMORY_SEARCH_ABSTAIN_THRESHOLD`, `LOOM_MEMORY_SEARCH_HYDE_FALLBACK_THRESHOLD`, `LOOM_MEMORY_SEARCH_QUERY_REWRITE_THRESHOLD` | Ajustados para `text-embedding-3-small`; se usan con embedders falsos, una sonda fallida o la adaptación desactivada. |
+| Resultados bajo el umbral mínimo | `LOOM_MEMORY_SEARCH_FLOOR_MODE` (`floor_mode`) | `readmit` completa `top_k` y marca `below_floor`; `ids_only` completa con cuerpos vacíos; `drop` devuelve menos. |
+| Conjunto de candidatos | `LOOM_MEMORY_SEARCH_POOL_MULTIPLIER_STANDARD`, `_RERANK`, `_DEEP`, limitado por `LOOM_MEMORY_SEARCH_MAX_POOL_TOP_K` | Un conjunto más amplio aumenta la cobertura y la entrada del rerank; cuesta filas vectoriales leídas y tokens de rerank. |
+| Omitir rerank | `LOOM_LLM_RERANK_SKIP_ABOVE` (respaldo cuando el umbral adaptativo no tiene sonda) | Omite la llamada de rerank cuando el mejor resultado vectorial ya es sólido. |
+| Cascada de respaldo | `LOOM_MEMORY_SEARCH_FALLBACK_MAX_ROUNDS`, `_MAX_WALL_MS`, `_MAX_LLM_CALLS`, `_MAX_VECTOR_QUERIES` | Limita los reintentos que puede gastar una primera pasada débil (reescritura de la consulta, HyDE). |
+| Refuerzo | `LOOM_MEMORY_SEARCH_REINFORCEMENT_WEIGHT` (`reinforcement_weight`), `_HALF_LIFE_DAYS` | Cuánto elevan una fila las recuperaciones y los resultados positivos; 0 lo desactiva. Limitado por debajo de la relevancia. |
+| Procedencia | `LOOM_MEMORY_SEARCH_TRUST_WEIGHT` (por defecto 0) | Un término acotado que favorece las fuentes verificadas. |
+| Recencia | `LOOM_MEMORY_SEARCH_RECENCY_POOL_WEIGHT` (`recency_pool_weight`) | Reordena el conjunto hacia filas recientes en una consulta con intención de recencia; 0 = desactivado. |
+| Rama léxica en consultas con forma de código | `rrf_adaptive_lexical` (solicitud), `LOOM_MEMORY_RRF_CODE_SHAPE_LO` / `_HI` | Reduce el peso de la rama léxica para consultas con forma de ruta o de código bajo RRF. |
+| Modo por defecto | `LOOM_MEMORY_SEARCH_DEFAULT_MODE` (`search_mode`) | Se usa cuando el cliente no indica ni un modo ni una receta. |
+| Duplicados por clave | `LOOM_MEMORY_SEARCH_PER_KEY_CAP` | Filas que una clave puede aportar a una página. |
+
+> **Advertencia:** un umbral ajustado para un embedder es incorrecto para el siguiente. Con
+> `LOOM_ADAPTIVE_THRESHOLDS=false`, o con un embedder falso, vuelva a ejecutar el benchmark (`make bench-quick`,
+> `make bench-quality-gate`) después de cada cambio de embedder. `calibration.get` muestra qué
+> nivel produjo los umbrales vigentes para un espacio de nombres.
+
+
+
+## Lecturas vectoriales
+
+Las columnas vectoriales son `Array(BFloat16)`; donde `enable_quantized_codec` puede estar activado, el migrador las crea codificadas ([ClickHouse](../architecture/clickhouse.md#gated-clickhouse-settings)).
+
+| Palanca | Ajuste | Compromiso |
+| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Escaneo de códigos primero | `LOOM_VECTOR_SEARCH_QUANTIZED_CODES` (activado por defecto), `LOOM_MEMORY_SEARCH_FACT_CODES_FIRST` (`auto`) | Lee los códigos cuantizados y luego vuelve a puntuar con precisión completa. `auto` lo desactiva mientras `memory_embeddings` tenga partes de parche, donde se omitiría la nueva puntuación. |
+| Sobrecarga de lectura de códigos | `LOOM_VECTOR_SEARCH_QUANTIZED_FETCH_MULTIPLIER`, `LOOM_MEMORY_SEARCH_FACT_CODES_FETCH_MULTIPLIER` | Filas que se conservan por distancia de código antes de la nueva puntuación. Un valor menor es más barato y cambia con más frecuencia los primeros resultados. |
+| Hilos por sentencia de hechos | `LOOM_MEMORY_SEARCH_FACT_LEG_MAX_THREADS` (0 = sin fijar) | Fijar los hilos limita la CPU y la memoria máxima por sentencia a costa de algo de latencia. |
+| Lecturas de pares en escrituras masivas | `LOOM_MEMORY_BULK_PEER_READ` (por defecto `batched`; `per_fact`) | `per_fact` lee los pares de conflicto y de actualización de valor de cada hecho masivo con códigos primero, como hace `memory.set`: para espacios de nombres grandes, donde la sentencia de pares por lotes falla con `MEMORY_LIMIT_EXCEEDED` (`batched conflict candidates failed` en el log del servidor) y una entrada se escribe sin verificar cuando también falla su alternativa por hecho. Un par puede diferir cuando las distancias empatan. |
+
+Para mover una tabla existente a un códec o a una disposición, usa `scripts/ops/vector_codec_rebuild.py` (tabla gemela, controles de consistencia y de recall, `EXCHANGE`; [pasos](https://github.com/ClickHouse/loom/blob/main/docs/operations/deployment.md#recommended-clickhouse-settings)), nunca un `ALTER` en una migración.
+
+
+
+## Conexiones y plazos de ClickHouse
+
+| Palanca | Configuración | Compromiso |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Tamaño del pool | `LOOM_CH_POOL_MAXSIZE` (por defecto 64 por proceso) | Dimensiónalo según la concurrencia de solicitudes esperada más los workers, más las conexiones que las inserciones por lotes retienen durante su espera; el valor por defecto del propio driver se agota con escrituras masivas. |
+| Inserciones por lotes | `LOOM_CH_BATCHED_INSERTS` (por defecto activado), `LOOM_CH_BATCHED_INSERT_WAIT_MIN_MS` (10), `LOOM_CH_BATCHED_INSERT_WAIT_MAX_MS` (50), `LOOM_CH_BATCHED_INSERT_BACKGROUND_WAIT_MAX_MS` (200) | Las inserciones concurrentes comparten una parte, con una latencia de hasta la de la ventana cada una; una inserción aislada espera el mínimo; cada inserción en espera retiene una conexión del pool, por lo que el pool crece con la tasa de escritura ([inserciones por lotes](../architecture/clickhouse.md#batched-inserts)). |
+| Espera del pool | `LOOM_CH_POOL_WAIT_MS` (por defecto 500) | Pasado ese tiempo, una solicitud falla rápido con 503 `OVERLOADED` en lugar de quedar en cola; 0 = sin límite. |
+| Keep-alive | `LOOM_CH_KEEPALIVE_TIMEOUT` (por defecto 5 s) | Debe mantenerse por debajo del corte por inactividad del balanceador de carga, de modo que Loom cierre primero una conexión del pool. |
+| Plazos de sentencias | `LOOM_CH_TIMEOUT_READ_S`, `LOOM_CH_TIMEOUT_WRITE_S`, `LOOM_CH_TIMEOUT_DDL_S` | Se aplican como `max_execution_time` y como un límite del cliente que libera el espacio del pool; 0 = sin límite para esa clase. |
+| Prioridad por clase de tráfico | `LOOM_CH_SETTINGS_BY_TRAFFIC_CLASS` (JSON) | `priority` y `max_threads` por clase (`production`, `interactive`, `bench`, `background`), de modo que los benchmarks y los workers cedan ante las lecturas de producción. |
+| Lectura de las propias escrituras | `LOOM_CH_READ_YOUR_WRITES`, `LOOM_CH_READ_YOUR_WRITES_WINDOW_S` | Lecturas secuencialmente consistentes después de una escritura; tiene un costo en servicios replicados y no hace nada en un solo nodo. |
+| Presupuestos de operación | `LOOM_LATENCY_BUDGET_MULTIPLIER` | Escala el `budget_p99_ms` de cada op; un salto WAN hacia ClickHouse necesita cerca de 20. Los presupuestos solo generan eventos `budget.violated`; no cortan solicitudes. |
+
+La capacidad web es `LOOM_WEB_WORKERS` por contenedor multiplicado por el número de contenedores; el limitador de tasa divide
+sus límites entre las réplicas activas que cuenta en `loom.instances`, nunca menos que
+`LOOM_REPLICA_COUNT` ([réplicas](https://github.com/ClickHouse/loom/blob/main/docs/operations/replicas.md#rate-limits)).
+
+
+
+## Proveedores
+
+| Palanca | Configuración | Compromiso |
+| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Límite del embedding de consulta | `LOOM_MEMORY_SEARCH_EMBED_BOUND_S`, `LOOM_MEMORY_SEARCH_EMBED_BOUND_RETRIES` | Límite por intento sobre el embedding de la consulta; tras los reintentos la búsqueda responde 503 `EMBED_TIMEOUT`. |
+| Ortografía de la consulta | `LOOM_MEMORY_SEARCH_QUERY_SPELLING_MAX_WORDS` | Una consulta de como máximo este número de palabras lee el espacio de nombres una vez, junto al embedding, para generar el embedding de sus palabras en minúsculas con la ortografía del corpus: 100–300 ms para un espacio de nombres de 40k filas, reutilizado durante un minuto; `0` = desactivado. |
+| Cachés del embedding de consulta | `LOOM_EMBEDDING_CACHE_SIZE`, `LOOM_EMBEDDING_CACHE_TTL_S`, `LOOM_EMBEDDING_CACHE_SHARED`, `LOOM_EMBEDDING_CACHE_SHARED_MAX_CHARS` | Una LRU por proceso delante de un `loom.embedding_cache` compartido; las consultas repetidas se saltan la llamada al proveedor. |
+| Caché de respuestas del LLM por clase | `LOOM_LLM_POLICY_BY_TRAFFIC_CLASS` (JSON) | Almacena en caché las respuestas del LLM (activado por defecto para `bench`) y puede impedir que una clase use el nivel fuerte o el intermedio. |
+| Modelo de respaldo | `LOOM_LLM_FALLBACK_MODEL` | Responde cuando el principal sigue sin estar disponible tras los reintentos, en lugar de hacer fallar la op. |
+| Tope de gasto | `LOOM_DEFAULT_DAILY_COST_CAP_USD` (por espacio de nombres `daily_cost_cap_usd`) | Al superar el tope, los workers basados en LLM omiten el espacio de nombres y `memory.ask` se abstiene con `budget_capped`; las lecturas y escrituras simples continúan. |
+
+
+
+### Elección del embedder
+
+| Embedder (`LOOM_EMBEDDING_MODEL`) | Compromiso |
+| ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
+| `text-embedding-3-large`, `gemini-embedding-001` | El valor por defecto de Loom, de 3072 dimensiones; aun así hay que medir la calidad y el costo con tus datos. |
+| `text-embedding-3-small` | Opción de vectores más estrechos, de 1536; cambiar la anchura requiere volver a generar los embeddings. |
+| `local`, `local:bge-small`, `local:bge-base`, `local:minilm` | Embedding en CPU dentro del proceso, sin llamada a un proveedor ni clave; sacrifica calidad por latencia y costo. |
+| `fake-ngram-3072` | N-gramas de caracteres con la anchura estándar, solo para pruebas y cableado; las cifras de recall no significan nada. |
+
+Cambiar el embedder cambia el espacio vectorial: ajusta `LOOM_EMBEDDING_DIM` para que coincida, ejecuta
+`loom reembed` y, con los umbrales adaptativos activados, deja que la sonda de arranque recalibre. Ejecuta
+`make bench-quick` antes y después; lo mismo vale para `LOOM_LLM_MODEL`, con el que están calibrados
+los prompts de extracción.
+
+
+
+## Workers y lotes
+
+Cada worker tiene un interruptor `*_ENABLED` y una cadencia `*_INTERVAL_SECONDS`, y muchos tienen
+una pausa `*_IDLE_INTERVAL_SECONDS` después de una pasada que no encontró nada
+([referencia de workers](https://github.com/ClickHouse/loom/blob/main/docs/reference/workers.md)). Los intervalos más cortos reducen el retraso
+del trabajo en segundo plano a costa de más escaneos; el intervalo de inactividad mantiene barata una cola vacía.
+
+| Worker | Parámetros |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `embedding_worker` | `LOOM_EMBEDDING_WORKER_INTERVAL_SECONDS`, `_IDLE_INTERVAL_SECONDS`; `LOOM_EMBEDDING_WORKER_ORPHAN_FULL_SCAN_SECONDS` / `_ORPHAN_RECENT_SECONDS` acotan el anti-join de huérfanos. |
+| `extraction_queue` | `LOOM_EXTRACTION_QUEUE_INTERVAL_SECONDS`, `_MAX_BATCHES_PER_PASS`, `_NAMESPACE_CONCURRENCY`, `_LEASE_SECONDS`; `LOOM_EXTRACTION_DEFER_AGENTS` difiere `set_from_messages` para los agentes indicados, de modo que la solicitud regrese antes de la extracción. |
+| `memory_expiry_sweep` | `LOOM_MEMORY_EXPIRY_SWEEP_BATCH_SIZE`. |
+| `task_lease_sweep` | `LOOM_TASK_LEASE_SWEEP_INTERVAL_SECONDS`, `_IDLE_INTERVAL_SECONDS`. |
+
+Los workers se ejecutan en la clase de tráfico `background`, por lo que `LOOM_CH_SETTINGS_BY_TRAFFIC_CLASS` también
+limita su prioridad y sus hilos en ClickHouse. Ejecuta exactamente un proceso de workers: una segunda
+copia de un worker respaldado por un LLM duplica sus escaneos y su gasto. Los workers de ingesta del plano de código y del
+nivel del compilador tienen sus propios parámetros ([operaciones del índice de código](https://github.com/ClickHouse/loom/blob/main/docs/operations/code-index-operations.md)).
+
+
+
+## Optimizaciones desde el cliente
+
+Algunas de las mayores mejoras están en la propia solicitud:
+
+- Pedir menos cuerpos: `bodies` y `body_budget_tokens` en `memory.search`, `token_budget`
+ en `context.pack` y `code.search`.
+- Cargar el contexto una sola vez por tarea (`context.pack`) en lugar de hacer una búsqueda por paso.
+- Usar `retrieval_budget` para elegir un perfil de búsqueda más económico o más profundo en cada llamada.
+- Reintentar las operaciones idempotentes con un encabezado `Idempotency-Key` (los SDKs generan uno): una
+ repetición devuelve la respuesta almacenada en lugar de ejecutar la operación de nuevo.
+
+
+
+## Relacionado
+
+- [Fallos y recuperación](../architecture/failure-and-recovery.md): capacidad y qué escalar
+- [Monitorización](https://github.com/ClickHouse/loom/blob/main/docs/operations/monitoring.md)
+- [Ejecución de benchmarks](https://github.com/ClickHouse/loom/blob/main/docs/benchmarks/running.md)
+- [Depuración](https://github.com/ClickHouse/loom/blob/main/docs/guides/debugging.md)
diff --git a/i18n/.pending/es/docs/operations/supported-versions.md b/i18n/.pending/es/docs/operations/supported-versions.md
new file mode 100644
index 0000000000..9f8ed985ff
--- /dev/null
+++ b/i18n/.pending/es/docs/operations/supported-versions.md
@@ -0,0 +1,83 @@
+
+> 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/supported-versions.md), que prevalece.
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/operations/supported-versions.md), which is authoritative.
+
+
+
+# Versiones compatibles
+
+Las versiones N y N−1 reciben correcciones, y un SDK en `X.Y` funciona con un servidor en `X.Y` o `X.(Y−1)`. Loom
+publica una sola versión para el servidor, las dos imágenes, la aplicación web, ambos SDK, las skills raíz y el `appVersion` del
+chart de Helm ([proceso de publicación](https://github.com/ClickHouse/loom/blob/main/docs/development/release-process.md)). Esta página también cubre
+los plugins de agentes de programación y cómo se anuncia un cambio que elimina algo.
+
+
+
+## Líneas de versiones
+
+| Línea | Qué recibe |
+| ---- | ------------------------------------------------------------------------------------------------- |
+| N | la versión menor más reciente (`X.Y`): todas las correcciones, como versión de parche (`X.Y.(Z+1)`) cuando no pueden esperar |
+| N−1 | la versión menor anterior: correcciones de seguridad y correcciones de pérdida de datos o de respuestas erróneas, como parches |
+| N−2 | ninguna: actualice a N o N−1 |
+
+Una versión menor sale de `main` aproximadamente cada dos semanas; un parche sale de la rama
+`release/X.Y` de la línea, con la corrección fusionada antes en `main`. Una actualización sigue
+[las actualizaciones](https://github.com/ClickHouse/loom/blob/main/docs/operations/upgrades.md); dos versiones adyacentes funcionan en paralelo mientras una reemplaza a la otra
+([actualizaciones progresivas](../architecture/rolling-upgrades.md)).
+
+
+
+## SDK y servidores
+
+Los SDK (`clickhouse-loom` en PyPI, `@clickhouse/loom` en npm) se publican con cada versión, con
+la versión del servidor; el `latest` de npm apunta a la versión final más alta, y un parche de una línea anterior usa su
+dist-tag `release-X.Y`. Frente al servidor más antiguo:
+
+- un campo que el SDK envía y que el servidor más antiguo no conoce se atiende y se nombra en
+ `ignored_args` de la respuesta, excepto en una op que cambia el estado, donde una clave que el servidor interpreta como un error ortográfico
+ de uno de sus campos (un nombre cercano, un sinónimo, una palabra del nombre de un campo) se rechaza con
+ `422 UNKNOWN_ARGUMENT` y no se escribe nada
+ ([campos desconocidos y eliminados](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#unknown-and-removed-fields));
+- una operación que el servidor más antiguo no atiende responde `404`, que los SDK lanzan como `NotFound`
+ (Python `loom.errors.NotFound`, TypeScript `NotFound`): una llamada nunca tiene éxito en silencio frente a un
+ servidor que no puede realizarla. El mismo error significa que falta una fila, así que un cliente que deba distinguir ambos casos
+ lee `ops.capabilities` al arrancar
+ ([descubrir qué atiende un despliegue](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#discovering-what-a-deployment-serves)).
+
+Una versión mayor (`X.0`) puede romper la regla frente al último servidor `(X−1).Y`; sus notas de la versión
+indican qué necesita un SDK en `X.0`.
+
+Un SDK más antiguo sigue funcionando con un servidor más reciente mientras el servidor atienda lo que llama;
+una eliminación sigue la regla de abajo.
+
+
+
+## Plugins de agentes de programación
+
+Los plugins de Claude Code y Codex tienen su propia versión e indican el servidor más antiguo que sus
+hooks admiten (`MIN_SERVER_VERSION` en `lib/server-version.mjs`). Una sesión contra un servidor más
+antiguo empieza con una línea `loom:` que lo indica, y el plugin sigue funcionando donde puede
+([Claude Code](https://github.com/ClickHouse/loom/blob/main/docs/features/integrations/claude-code.md)). El plugin de Claude Code requiere Claude Code
+2.1.139 o posterior, la primera versión que ejecuta los `args` de un hook sin shell.
+
+
+
+## Eliminar algo
+
+Una eliminación se anuncia, a mano en el pull request de la versión, en las notas de la versión menor
+anterior a la que la elimina, bajo "What changed for clients". Hasta la eliminación, el
+servidor atiende el campo o la op antigua; después, un campo de solicitud eliminado se sigue aceptando y se nombra
+en `ignored_args`, de modo que un cliente que lo envía se entera del cambio sin fallar, y una op eliminada
+responde `404` (`NotFound`), lo que `ops.capabilities` distingue de una fila ausente.
+
+
+
+## Artefactos de la versión
+
+Cada imagen de la versión se construye en la arquitectura en la que se ejecuta, se analiza en busca de vulnerabilidades críticas
+con corrección disponible, y se publica con su procedencia y un SBOM. El índice multiarquitectura de cada imagen lleva una
+firma sin clave del flujo de trabajo de publicación; [imágenes de contenedor](https://github.com/ClickHouse/loom/blob/main/docs/operations/deployment.md#container-images)
+da el comando `cosign verify`. Cada archivo de la GitHub Release se firma del mismo modo, en un
+`.sigstore.json` junto a él; [archivos de la versión](https://github.com/ClickHouse/loom/blob/main/docs/operations/deployment.md#release-files) da el
+comando `cosign verify-blob`.
diff --git a/i18n/.pending/es/docs/operations/upgrades.md b/i18n/.pending/es/docs/operations/upgrades.md
new file mode 100644
index 0000000000..855c17ab76
--- /dev/null
+++ b/i18n/.pending/es/docs/operations/upgrades.md
@@ -0,0 +1,444 @@
+
+> 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/upgrades.md), que prevalece.
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/operations/upgrades.md), which is authoritative.
+
+
+
+# Actualizaciones
+
+Una actualización reemplaza la imagen (y la del extractor de documentos, que no guarda estado) y
+aplica las migraciones que incluye la nueva compilación. No se mueve ningún otro estado: todo lo duradero
+está en ClickHouse (y en el bucket de documentos, para los originales escritos con
+`LOOM_DOCUMENT_OBJECT_STORE=s3`), y los mirrors de código se montan sin cambios. Esta página
+describe el lado del operador. Cómo ve un cliente los campos desconocidos y eliminados se explica en la [referencia de la API HTTP](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#unknown-and-removed-fields). Qué versiones reciben correcciones y qué
+SDK funciona con qué servidor: [versiones compatibles](https://github.com/ClickHouse/loom/blob/main/docs/operations/supported-versions.md).
+
+
+
+## Cómo se ejecutan las migraciones
+
+El journal, la numeración, las directivas del runner y las reglas para escribir una migración están en
+[migraciones](https://github.com/ClickHouse/loom/blob/main/docs/development/migrations.md). Lo que necesita un operador:
+
+- **Al arrancar.** El servidor aplica los archivos pendientes antes de informar que está listo o de iniciar
+ los workers (`LOOM_BOOT_MIGRATE=true`, el valor por defecto). Cada proceso, en cualquier contenedor, toma
+ el bloqueo `KeeperMap` en `loom._migration_lock`, de modo que cada archivo se aplica una sola vez. Un servidor
+ sin Keeper es rechazado.
+- **Reconstrucciones del proveedor.** Un arranque con archivos pendientes primero se inscribe como participante del
+ proveedor y luego comprueba, bajo el bloqueo de configuración del proveedor (una clave de Keeper, retenida solo durante
+ esa comprobación), que no haya una reconstrucción del proveedor sin terminar, y se niega a migrar si la hay:
+ `Finish the provider rebuild before applying schema migrations`. Después los archivos
+ se aplican solo bajo el bloqueo de migración. Una reconfiguración iniciada mientras tanto espera hasta que el proceso en arranque
+ la reconozca, de modo que una reconstrucción nunca se ejecuta junto a una migración.
+- **Un contenedor terminado mientras migra o reconfigura** bloquea a los demás solo durante
+ un tiempo. El bloqueo de migración se toma por la fuerza una vez que su titular deja de renovarlo (`ttl_s`).
+ El bloqueo del proveedor (TTL de 60 s, renovado cada 20 s) se toma por la fuerza una vez que ha expirado y la fila de participante de
+ su titular también ha expirado: sin heartbeat durante 60 s (uno cada 10 s) y sin
+ ninguna consulta etiquetada con su id en `system.processes` en ningún nodo. Los contenedores que arrancan juntos
+ esperan hasta 120 s por el bloqueo del proveedor en lugar de fallar. Un bloqueo cuyo titular no
+ tiene fila de participante se libera con `loom provider-lock clear --holder ` una vez
+ confirmado que ese proceso está detenido; el comando se niega mientras el titular renueve,
+ envíe heartbeats o tenga una consulta en ejecución.
+- **Mutaciones.** Un archivo se registra solo cuando sus mutaciones han terminado. Una mutación fallida,
+ o una que supere `LOOM_MIGRATE_MUTATION_WAIT_S` (600 por defecto), hace fallar el archivo y
+ detiene el arranque con el archivo indicado en el log.
+- **Cambios de clave.** Una migración que cambia una clave de ordenación o de partición reconstruye por sí misma una tabla vacía
+ y hace fallar el arranque si la tabla tiene filas. Ejecute `scripts/ops/table_rebuild.py`
+ para esa tabla antes del despliegue; el dry run estricto lo detecta.
+- **Instalación nueva.** Una instalación nueva y una actualización siguen el mismo camino: el servidor reproduce
+ lo que le falte al ledger. En una base de datos vacía eso es todo el journal y tarda
+ unos minutos.
+- **Ledger varado.** Una base de datos cuyo ledger se detuvo a mitad de los archivos que reemplaza un
+ baseline es rechazada (`stranded`): primero migre esa base con una compilación anterior a ese
+ baseline.
+- **Archivos renumerados.** Una fila del ledger cuyo archivo ya no existe en el repositorio es
+ `ledger-only`, y `--strict` termina con código 1 ante ella, salvo cuando su SHA-256 registrado es el de un
+ archivo actual: es el mismo archivo con un número nuevo. El runner lo informa como renombrado,
+ registra el nombre nuevo sin volver a ejecutarlo si está pendiente, y
+ `--strict` pasa. Un archivo editado después de ejecutarse con su nombre anterior tiene otro SHA-256,
+ así que sigue como ledger-only: su nombre nuevo se ejecuta como archivo pendiente, y la fila antigua se
+ elimina a mano ([solución de problemas](https://github.com/ClickHouse/loom/blob/main/docs/operations/troubleshooting.md#migrations-pending-or-checksum-drift)).
+ `/v1/health` lista la fila antigua en `schema.ledger_only` hasta entonces.
+
+La CLI ejecuta el mismo runner a mano:
+
+```bash
+loom migrate --status # applied and pending; changes nothing
+loom migrate --dry-run --strict # pending files; exit 1 on ledger-only rows (not renames) or checksum drift
+loom migrate # apply pending migrations
+loom migrate --target N # apply through file number N only
+```
+
+`make migrate`, `make migrate-status` y `make migrate-dry` ejecutan el mismo módulo desde un
+checkout.
+
+
+
+## Procedimiento de actualización
+
+1. Lee las notas de la versión en [publicación de GitHub](https://github.com/ClickHouse/loom/releases)
+ para conocer los pasos del operador (nuevos ajustes, backfills que un despliegue debe ejecutar) y los
+ cambios de protocolo visibles para el cliente.
+2. Desde el checkout de la nueva build, contra el ClickHouse de producción, ejecuta
+ `loom migrate --dry-run --strict`. Muestra lo que aplicará el arranque y se detiene ante problemas
+ del registro ([solución de problemas](https://github.com/ClickHouse/loom/blob/main/docs/operations/troubleshooting.md#migrations-pending-or-checksum-drift)).
+ Si la versión declara una reconstrucción de tabla, ejecuta ahora `scripts/ops/table_rebuild.py` para esa
+ tabla. Un despliegue de la autoridad Postgres que pasa a una build que mantiene los
+ encabezados de documentos de conocimiento en Postgres desactiva ahora `LOOM_RETENTION_DOCUMENTS_DAYS`, a
+ mano: la build más nueva se niega a arrancar con ese ajuste definido, y bajo esa autoridad ningún
+ TTL de retención llega a `loom.documents`, y el `retention_days` de un espacio de nombres tampoco
+ llega a `loom.chunks`
+ ([actualizaciones continuas](../architecture/rolling-upgrades.md), regla 38). Una
+ [celda](../architecture/cells.md) que pasa a una build que marca sus sesiones y
+ lleva los triggers de org (regla 47) primero apunta su `LOOM_PG_DSN` directamente a
+ Postgres, sin pasar por ningún pooler ([Postgres](https://github.com/ClickHouse/loom/blob/main/docs/operations/postgres.md)), y una celda posterior preparada y
+ luego revertida desactivando `LOOM_CELL` se limpia primero
+ ([solución de problemas](https://github.com/ClickHouse/loom/blob/main/docs/operations/troubleshooting.md#a-process-with-loom_cell-unset-is-gated)):
+ la build más nueva condiciona sus procesos a su estado. En una celda posterior ya preparada,
+ el primer arranque con migración de la build más nueva crea los triggers de org, de modo que un pod
+ antiguo que siga ejecutándose allí tiene rechazada cada inserción de una fila de org de un tenant
+ (un error sin asignar para sus llamadores) hasta que se reemplace: despliega la celda en un solo paso.
+3. Despliega la nueva imagen. El primer contenedor en arrancar aplica las migraciones; los demás
+ esperan y luego no encuentran nada pendiente.
+4. Espera a que `/v1/health` informe `status: ok` y un `schema.pending` vacío antes de
+ enrutar tráfico hacia ella. El [par sin tiempo de inactividad](https://github.com/ClickHouse/loom/blob/main/docs/operations/deployment.md#zero-downtime-pair)
+ hace los pasos 2 a 4 por ti, salvo desactivar el ajuste que nombra el paso 2: `redeploy.sh`
+ ejecuta el dry run estricto en su verificación previa y cambia solo después de que el nuevo color esté
+ listo.
+5. Ejecuta los backfills de la versión, si los hay ([mantenimiento](https://github.com/ClickHouse/loom/blob/main/docs/operations/maintenance.md#backfills-and-repairs)).
+6. Actualiza los plugins de cliente cuando la versión mencione un cambio de plugin: los hooks se ejecutan
+ en la máquina del cliente y solo cambian mediante el gestor de plugins del cliente
+ (`claude plugin update loom@loom` para Claude Code), nunca mediante un despliegue del servidor.
+7. Una vez detenida la última réplica antigua, vuelve a verificar los borrados completados durante el
+ despliegue: `loom erasure-re-verify --completed-since --resume`. La saga de una
+ réplica antigua no conoce las tablas que añadió la nueva build
+ ([actualizaciones continuas](../architecture/rolling-upgrades.md), regla 14). El comando
+ elimina solo los vínculos de fila huérfanos: filas de `entity_triple_rows` y `entity_edge_rows`
+ en el alcance de cada borrado cuya memoria no tiene fila viva ni fila escrita desde el censo
+ del borrado. Sin `--resume` las cuenta y sale con 1 si queda alguna.
+ Los datos escritos después del borrado permanecen.
+8. Activa una función que la build anterior no puede respetar solo cuando todas las réplicas ejecuten
+ la nueva build: `memory_extract_agent_learnings`, ya que la build anterior no
+ borra `loom.learnings_supporters`
+ ([actualizaciones continuas](../architecture/rolling-upgrades.md), regla 23);
+ `LOOM_DOCUMENT_OBJECT_STORE=s3`, ya que la build anterior lee el `data` vacío de una fila de bucket
+ y responde a su descarga con `410 BLOB_GONE` (regla 9); y
+ `LOOM_PG_PAYLOAD_CLEAR_ENABLED`, no antes de un horizonte de limpieza después de que la nueva
+ build sirva sola, ya que la build anterior no marca una entrega tardía (regla 43).
+9. Un despliegue con `LOOM_CODE_ASK_MEMORY_NAMESPACE` definido, ahora o en cualquier momento anterior,
+ que pasa de una build cuyas respuestas `code.ask` en caché no nombran la memoria que citaron
+ (una anterior a `086_code_answer_memory_scope.sql`) a una que sí lo hace, incluido un avance
+ tras un rollback: una vez que la build más nueva sirva sola, sin ninguna reconstrucción del proveedor en curso, vacía la caché de respuestas con
+ `TRUNCATE TABLE .code_answers` (`loom.code_answers` por defecto). Las
+ respuestas y tombstones de la build antigua no nombran ninguna memoria, y un borrado o redact que ejecutó
+ durante el despliegue no conocía la tabla
+ ([actualizaciones continuas](../architecture/rolling-upgrades.md), regla 36), de modo que ninguna saga puede encontrar
+ lo que contienen. Una reconstrucción publica su copia de la tabla sobre ella, así que una que se ejecute
+ durante el truncate devuelve las filas. Un truncate elimina las partes al instante, en cada
+ réplica de una tabla replicada, sin mutación que esperar, y el usuario loom tiene
+ el permiso. Cada pregunta limpiada cuesta una síntesis en su siguiente consulta.
+10. Al pasar a una build cuyo borrado de usuario alcanza lo que alimentó un resumen consolidado de las
+ memorias del usuario, incluido un avance tras un rollback: una vez que la build más nueva
+ sirva sola, solicita de nuevo cada borrado de usuario sin `purge` solicitado antes (las
+ filas `user_id` de `loom.erasure_requests`, conservadas 90 días), incluido uno que la build más nueva
+ terminó: la saga de una build antigua dejó el historial del resumen, los chunks, los vectores,
+ las filas del grafo y las copias compartidas
+ ([actualizaciones continuas](../architecture/rolling-upgrades.md),
+ regla 37).
+ La nueva saga también borra lo que el usuario escribió desde entonces: solicítala para un usuario sin
+ fila de memoria viva, o solo donde se desee. Un purge de usuario que completó una build antigua dejó
+ las mismas filas, y ningún borrado de usuario posterior las encuentra: las claves del usuario ya no existen.
+ Uno que se ejecutó pasado `shared.tombstone` también dejó las filas de búsqueda de copias compartidas
+ de las memorias del propio usuario, sea cual sea la build que lo terminó. Una copia compartida que una build antigua
+ promovió con `agent="*"` nombra `*` como su agente de origen, y ningún borrado del
+ usuario que copió puede encontrarla. Lístalas y revisa cada una, con `memory.demote` para una
+ que contenga texto de un usuario borrado:
+
+ ```sql
+ SELECT org, namespace, memory_key FROM loom.shared FINAL
+ WHERE tombstoned_at IS NULL AND arrayExists(x -> splitByChar('/', x)[3] = '*', promoted_from)
+ ```
+
+11. Un despliegue de la autoridad Postgres que pasa a una build que mantiene los encabezados de documentos
+ de conocimiento en Postgres (`002_knowledge_documents.sql`), incluido un avance tras un
+ rollback: una vez que la build más nueva sirva sola, ejecuta de nuevo cada borrado
+ completado mientras una réplica de una build antigua servía desde que la build más nueva sirvió por primera vez. El borrado de una build antigua
+ no elimina ningún encabezado ni entrega: el texto de un documento borrado
+ permanece en `loom.knowledge_heads` hasta que el borrado se ejecute de nuevo, y una entrega que dejó
+ es publicada de nuevo por el worker de entregas
+ ([actualizaciones continuas](../architecture/rolling-upgrades.md), regla 38). Hazlo antes de
+ reintentar una entrega aparcada.
+12. Un despliegue de la autoridad Postgres que pasa a una build que mantiene los trabajos de ingesta de
+ conocimiento (`005_knowledge_jobs.sql`) o el catálogo de datasets
+ (`007_knowledge_datasets.sql`) en Postgres, incluido un avance tras un rollback: una vez que la build más nueva sirva sola, ejecuta de nuevo cada borrado completado
+ mientras una réplica de una build antigua servía desde que la build más nueva sirvió por primera vez. El
+ borrado de una build antigua no elimina ningún trabajo de `loom.knowledge_jobs` ni fila de catálogo
+ de `loom.knowledge_datasets`: el worker de la build más nueva proyecta ese trabajo de nuevo
+ en `loom.knowledge_ingestions` y lo ejecuta, y las filas del catálogo permanecen hasta que el
+ borrado se ejecute de nuevo ([actualizaciones continuas](../architecture/rolling-upgrades.md), reglas
+ 40 y 42). Las ejecuciones del paso 11 cubren por igual los encabezados, los trabajos y las filas del catálogo; basta una
+ ejecución por borrado. Pide de nuevo también cada `knowledge.delete` y
+ `knowledge.bulk_delete` que una build antigua respondió en esa ventana: eliminó los datasets de las
+ fuentes solo de `loom.datasets`.
+13. Al pasar a una build que mantiene fuentes de documentos en cualquier espacio de nombres, incluido un avance
+ tras un rollback: una vez que la build más nueva sirva sola, retira las fuentes que un
+ `namespace.delete`, `collection.delete` o borrado de espacio de nombres de una build antigua dejó
+ activas ([actualizaciones continuas](../architecture/rolling-upgrades.md), regla 44). Las
+ fuentes en un espacio de nombres eliminado:
+
+ ```sql
+ SELECT s.org, s.namespace, s.name
+ FROM (SELECT org, namespace, name FROM loom.knowledge_sources FINAL WHERE active) AS s
+ INNER JOIN (SELECT org, namespace FROM loom.namespaces FINAL WHERE NOT active) AS n
+ ON s.org = n.org AND s.namespace = n.namespace
+ ```
+
+ y las fuentes registradas antes de que se completara un borrado de espacio de nombres que este no
+ retiró (una que ejecutó una build antigua, o una que una build antigua añadió mientras se ejecutaba el borrado de una build más nueva):
+
+ ```sql
+ SELECT s.org, s.namespace, s.name, e.id
+ FROM (
+ SELECT org, namespace, name, active, created_at, updated_at
+ FROM loom.knowledge_sources FINAL
+ ) AS s
+ INNER JOIN (
+ SELECT id, org, completed_at,
+ arrayJoin(if(scope_type = 'namespace', [scope_value],
+ if(JSONType(scope_value) = 'Array',
+ JSONExtract(scope_value, 'Array(String)'),
+ JSONExtract(scope_value, 'namespaces', 'Array(String)')))) AS namespace
+ FROM loom.erasure_requests FINAL
+ WHERE scope_type IN ('namespace', 'namespace_list') AND status = 'completed'
+ ) AS e ON s.org = e.org AND s.namespace = e.namespace
+ WHERE s.created_at <= e.completed_at AND (s.active OR s.updated_at > e.completed_at)
+ ```
+
+ Para la primera consulta, elimina cada fuente listada (`knowledge.source.remove`), o
+ borra de nuevo su espacio de nombres con la build más nueva, que la retira. Para la segunda,
+ elimina cada fuente listada con `knowledge.source.remove` y
+ `delete_documents=true`, que retira los documentos que escribió (acepta una
+ fuente ya retirada, por un borrado posterior de su espacio de nombres en un caso), y borra con
+ `memory.delete` las filas de decisiones extraídas de ellos. Un borrado de espacio de nombres con la
+ build más nueva hace ambas cosas, pero también borra todo lo escrito en el espacio de nombres desde
+ el primer borrado; solicítalo de nuevo solo para un espacio de nombres en el que nadie haya escrito
+ desde entonces. Una fuente registrada después del borrado no aparece en la lista: el borrado nunca
+ la cubrió. La segunda lista es una lista de trabajo que se ejecuta una sola vez: una fuente eliminada como se indicó
+ sigue apareciendo, ya que su fila de eliminación es más nueva que el borrado.
+
+ Un borrado de espacio de nombres que inició una build antigua y terminó la build más nueva no necesita
+ nada aquí: su censo final encuentra los documentos y decisiones que su fuente
+ escribió y reabre sus pasos, de modo que la saga se completa solo cuando ya no existen.
+
+14. Al pasar a una build cuyo borrado de espacio de nombres alcanza `loom.shared`, incluido un avance tras un
+ rollback: una vez que la build más nueva sirva sola, limpia las filas promovidas que el borrado de espacio de nombres de una build
+ antigua dejó ([actualizaciones continuas](../architecture/rolling-upgrades.md),
+ regla 45). La consulta siguiente lista cada espacio de nombres que un borrado `namespace` o `namespace_list`
+ del registro (conservado 90 días) alcanzó y que contiene una fila promovida, con la
+ hora en que ejecutó su censo el último sin purge (`erased_at`) y con purge (`purged_at`).
+ Las sentencias siguientes toman las filas promovidas antes de ese segundo, de modo que una fila promovida
+ después del censo permanece, y también puede permanecer una promovida antes dentro del propio segundo del censo,
+ que los segundos enteros de `promoted_at` no pueden distinguir; el paso de la build más nueva ya tomó esa fila en un borrado que ejecutó.
+ Solo un `namespace_list` hace purge, y la fila `namespace` de una build antigua puede contener el indicador
+ que se le pidió.
+
+ ```sql
+ SELECT org, namespace,
+ maxIf(counted_at, NOT purged) AS erased_at,
+ maxIf(counted_at, purged) AS purged_at
+ FROM (
+ -- The census's time: a row promoted after it was never in the erasure's reach.
+ SELECT org, ifNull(verified_at, completed_at) AS counted_at,
+ scope_type = 'namespace_list' AND purge AS purged,
+ arrayJoin(if(scope_type = 'namespace', [scope_value],
+ if(JSONType(scope_value) = 'Array',
+ JSONExtract(scope_value, 'Array(String)'),
+ JSONExtract(scope_value, 'namespaces', 'Array(String)')))) AS namespace
+ FROM loom.erasure_requests FINAL
+ WHERE scope_type IN ('namespace', 'namespace_list') AND status = 'completed'
+ )
+ -- Only a namespace that holds a promoted row has anything to clear.
+ WHERE (org, namespace) IN (SELECT org, namespace FROM loom.shared)
+ GROUP BY org, namespace
+ ```
+
+ Para cada uno, ejecuta lo que ejecuta el paso de la build más nueva, sobre cada versión promovida antes del
+ censo del borrado, incluida una versión que una promoción posterior de la misma clave oculta a `FINAL`.
+ Donde `purged_at` esté definido, elimínalas:
+
+ ```sql
+ ALTER TABLE loom.shared DELETE
+ WHERE org = '' AND namespace = '' AND promoted_at < ''
+ SETTINGS mutations_sync = 2
+ ```
+
+ y donde `erased_at` esté definido, marca con tombstone las vivas que queden:
+
+ ```sql
+ ALTER TABLE loom.shared UPDATE tombstoned_at = toDateTime('')
+ WHERE org = '' AND namespace = '' AND tombstoned_at IS NULL
+ AND promoted_at < ''
+ SETTINGS mutations_sync = 2
+ ```
+
+ El ajuste espera cada sentencia en todas las réplicas. La hora se escribe como
+ literal, como la enlaza el paso, porque una tabla replicada rechaza una mutación que llama
+ a una función no determinista como `now()`. Un borrado de espacio de nombres solicitado
+ antes de los 90 días del registro no aparece en la lista, y las filas promovidas que dejó no se pueden distinguir
+ de las de un espacio de nombres vivo; permanecen como las dejó la build antigua.
+
+15. Al pasar a una build donde cada comando de la CLI que declara una org (un comando del índice de código, una
+ importación) comprueba su despliegue: bajo cualquiera de las autoridades su usuario de ClickHouse necesita
+ `SELECT` sobre `loom.storage_authority`, y el comando se niega contra un despliegue que registra
+ otra autoridad. Bajo la autoridad Postgres también necesita `LOOM_PG_DSN`
+ y lee el estado de la celda (con `LOOM_CELL` sin definir, en una sesión propia). Con
+ `LOOM_CELL` definido, un comando que no escribe para ninguna org pero cambia los almacenes de la celda
+ (`loom settings set`, `loom secrets reseal`, `loom code compact` y el resto) o
+ revoca el acceso comprueba su despliegue del mismo modo y lee la fila `first` de la celda en una
+ sesión propia. Concede al rol de Postgres con el que se conecta:
+ - con `LOOM_CELL` sin definir, `USAGE` sobre el esquema `loom`, `SELECT` sobre `loom.cell_first`,
+ `loom.tenancy_mode` y `loom.authority`, `SELECT (updated_at)` sobre `loom.cell_self`
+ y `SELECT (since)` sobre `loom.tenancy` (los permisos por columna mantienen las huellas y
+ las orgs fuera de su alcance), y un `CONNECTION LIMIT` de al menos `LOOM_PG_POOL_MAX_SIZE`
+ veces el número de comandos de ese tipo que se ejecutan a la vez, ya que cada uno abre su propio pool para
+ sus escrituras (la lectura de estado reintenta brevemente con el límite lleno, luego se niega);
+ - con `LOOM_CELL` definido, lo mismo con `SELECT` sobre `loom.cell_self` y `loom.tenancy`
+ completos y, para registrar una nueva org mientras la primera celda está en `recording`, `INSERT` sobre
+ `loom.tenancy` y `UPDATE (since)` sobre `loom.tenancy_mode`; revoca ambos con
+ `LOOM_CELL_ROUTER_TOKEN` cuando la celda se adjunte. Los ajustes de su bucket de documentos
+ (`LOOM_DOCUMENT_S3_BUCKET`, `LOOM_DOCUMENT_S3_PREFIX`) son iguales a los de los servidores.
+
+ Una escritura que un rol con solo los permisos por columna hace en una celda que ya pasó de `recording` es
+ rechazada como un error de permisos (SQLSTATE 42501) en lugar de `LT001`.
+
+16. Antes del attach de una primera celda, cada imagen de CLI y de CI ejecuta una compilación que lee ese estado, y cada CLI que escribe para una organización tiene `LOOM_CELL` definido. Ningún CLI envía un heartbeat, así que el attach tampoco puede comprobar ninguna de las dos cosas, y un CLI de una compilación anterior no es rechazado en una celda `enforced` ([celdas](../architecture/cells.md#failure-modes)).
+
+17. Paso a una compilación cuyos procesos de la primera celda leen el estado de su celda desde el router de forma periódica: todas las réplicas del router (`loom router serve`) ejecutan esta compilación antes que los procesos de cualquier celda. Cada proceso de una primera celda preparada consulta la ruta de estado del router desde su primera lectura del estado de la celda hasta que lee `serving`, y un router de una compilación anterior lee el directorio en cada una de esas llamadas: aproximadamente una lectura por proceso de servidor cada `min(LOOM_INSTANCE_HEARTBEAT_SECONDS, LOOM_TENANCY_MODE_CACHE_S)`, es decir, 1,600 lecturas por segundo para mil pods de ocho workers con los valores por defecto; un router de esta compilación las responde con una lectura por réplica cada `LOOM_ROUTER_DIRECTORY_CACHE_S` ([celdas](../architecture/cells.md#the-heartbeats-keys)).
+
+Mientras se aplica una migración, la compilación anterior sigue sirviendo: toda migración es aditiva. Las reglas que permiten que las dos compilaciones sirvan en paralelo están en [actualizaciones progresivas](../architecture/rolling-upgrades.md).
+
+
+
+## Reversión
+
+Vuelva a desplegar la imagen anterior; con el par, `./redeploy.sh --rollback`. Antes de hacer rollback
+a una build sin aprendizajes de turnos del asistente, desactive `memory_extract_agent_learnings`
+y elimine las filas de `loom.learnings_supporters` y las filas `assistant_turn` de
+`loom.learnings_queue`
+([extracción](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/extraction.md#rules-the-assistant-states-about-itself)).
+La build anterior entrega una regla de bot promovida a todos los agentes del espacio de nombres, no solo a
+su bot. Para evitarlo, elimine con `knowledge.delete` los documentos etiquetados `source-kind:assistant_turn`
+antes del rollback; de lo contrario, acepte la entrega más amplia.
+Un borrado de espacio de nombres que ejecute la build anterior una vez que existan guías de espacio de nombres deja la guía de ese
+espacio de nombres; ejecute el borrado de nuevo cuando la build más reciente vuelva a servir
+([actualizaciones progresivas](../architecture/rolling-upgrades.md), regla 24). Un borrado de espacio de nombres
+que ejecute la build anterior deja activas las filas promovidas del espacio de nombres; el paso 14 del procedimiento
+de actualización las enumera cuando la build más reciente vuelve a servir (regla 45).
+Tras un rollback a una build sin máximos de token para bots, los tokens de cada bot duran una hora,
+y un bot que guarde esa build conserva 3600 como máximo; vuelva a aplicar uno más corto o más largo
+cuando la build más reciente vuelva a servir
+([actualizaciones progresivas](../architecture/rolling-upgrades.md), regla 26).
+Un borrado de usuario que ejecute la build anterior deja lo que alimentó un resumen de las memorias del usuario;
+solicite de nuevo cada uno de los que se ejecutaron sin `purge` cuando la build más reciente vuelva a servir, como en el paso
+10; una purga que se completó no se vuelve a encontrar (regla 37).
+No haga rollback más allá de la build que añade el bucket de documentos mientras alguna fila del catálogo
+nombre un objeto en él: una build anterior responde esas descargas con `410 BLOB_GONE`, su
+borrado elimina las filas y no puede alcanzar sus objetos, y su barrido nunca recorre el
+bucket ([dónde se almacenan los originales](https://github.com/ClickHouse/loom/blob/main/docs/features/knowledge.md#where-originals-are-stored)).
+Tras un rollback a una build anterior a `086_code_answer_memory_scope.sql` con un espacio de nombres de memoria
+vinculado a `code.ask`, limpie la caché de respuestas como en el paso 9 dos veces: una cuando la build más antigua
+sirva sola, y otra cuando la build más reciente vuelva a servir. La migración ya está
+en el registro, así que el roll forward no aplica nada que provoque la segunda.
+Desactive `LOOM_PG_PAYLOAD_CLEAR_ENABLED` antes del rollback, y vuelva a activarlo no antes de
+un horizonte de limpieza después de que la build más reciente sirva sola de nuevo; una vez que una pasada de limpieza
+se haya ejecutado, ejecute `loom reconcile` solo con una build que incluya
+`010_revision_delivered_at.sql`, inicie el despliegue con esa build después, y haga
+rollback solo cuando la build más reciente no deba ninguna entrega reclamable de una revisión limpiada, lo cual
+esta consulta devuelve como 0 (regla 43):
+
+```sql
+SELECT count(*) FROM loom.memory_deliveries d
+JOIN loom.memory_revisions r USING (org, namespace, seq)
+WHERE r.row IS NULL AND NOT d.settled AND d.lease_until <> 'infinity';
+```
+
+Hasta entonces, deje que la build más reciente las entregue. La build anterior nunca reclama una
+entrega aparcada, así que una aparcada puede quedarse. Mientras la build anterior sirve, un reintento
+omite las revisiones limpiadas
+([operaciones de Postgres](https://github.com/ClickHouse/loom/blob/main/docs/operations/postgres.md#what-the-boot-checks)), y no se ejecuta `loom reconcile`:
+liberaría las retenciones de reconcile a la build anterior.
+Antes de hacer rollback de una celda preparada (una con una fila `loom.cell_first`) a una build
+sin los triggers de org de [celda](../architecture/cells.md), detenga todos los pods de la build más reciente,
+y luego ejecute solo la eliminación de triggers de
+[Un proceso con LOOM_CELL sin definir queda bloqueado](https://github.com/ClickHouse/loom/blob/main/docs/operations/troubleshooting.md#a-process-with-loom_cell-unset-is-gated),
+no su transacción de estado (la celda sigue preparada), y vuelva a ejecutarla si un pod más reciente
+arranca con migraciones activadas antes de que termine el rollback: las sesiones de la build más antigua no envían
+marcador de tenencia, así que una vez que la build más reciente haya creado los triggers y la guarda `loom.tenancy`,
+se rechaza cada una de sus escrituras para una org de la que la celda no tiene fila de tenencia (en una celda posterior antes de attach, toda org de tenant), igual que su fila de tenencia
+para cada org colocada de nuevo, y sus demás escrituras pagan la lectura de estado de los triggers.
+No hay ninguna migración que deshacer: la build anterior lee y escribe el esquema más reciente.
+Sus escrituras de versión en `loom.memory` y en las demás tablas de memoria `ReplacingMergeTree`
+conservan las columnas que no conoce
+([actualizaciones progresivas](../architecture/rolling-upgrades.md)).
+
+No hay migraciones inversas. Para volver a un esquema anterior, restaure una copia de seguridad hecha
+antes de la actualización ([copia de seguridad y recuperación](https://github.com/ClickHouse/loom/blob/main/docs/operations/backup-and-recovery.md)).
+
+
+
+### Volver a una versión anterior de una instalación con el instalador
+
+Cada bundle del instalador indica la versión de ClickHouse con la que se construyó, así que instalar
+una versión anterior de Loom también ejecuta un ClickHouse anterior sobre un volumen que escribió el más reciente,
+y puede que no pueda leerlo. Para hacer rollback solo de Loom, conserve el ClickHouse más reciente: antes de ejecutar
+el instalador anterior (inicia la pila de inmediato), fije la imagen que ClickHouse ejecuta ahora
+en el `.env` del directorio de instalación. Esto imprime la línea que debe poner allí, reemplazando cualquier
+línea `LOOM_CLICKHOUSE_IMAGE` anterior:
+
+```bash
+dir=${LOOM_INSTALL_DIR:-$HOME/.loom}
+echo "LOOM_CLICKHOUSE_IMAGE=$(docker inspect -f '{{.Config.Image}}' \
+ "$(docker compose --project-directory "$dir" ps -q clickhouse)")"
+```
+
+Luego ejecute el instalador de la versión anterior indicando su versión, ya que un instalador más antiguo sobre una
+instalación más reciente se niega en caso contrario:
+
+```bash
+curl -fsSL https://github.com/ClickHouse/loom/releases/download/vX.Y.Z/install.sh -o loom-install.sh && LOOM_VERSION=X.Y.Z sh loom-install.sh && rm loom-install.sh
+```
+
+Ejecútelo desde su directorio personal, o desde otro
+[directorio en el que solo usted pueda escribir](../getting-started/quickstart.md#fast-path-released-image-no-clone).
+
+El instalador conserva `.env`, así que la fijación mantiene ClickHouse también en actualizaciones posteriores:
+elimine la línea `LOOM_CLICKHOUSE_IMAGE` antes de instalar una versión más reciente de Loom, y no
+deje `LOOM_CLICKHOUSE_IMAGE` exportada en el shell, ya que el instalador vuelve a escribir en `.env` un valor que
+se le da. Para volver
+en ambos, restaure una copia de seguridad hecha antes de la actualización.
+
+
+
+## Qué se mantiene igual en una actualización
+
+| En una actualización | Qué se garantiza | Lo garantiza |
+| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
+| La compilación anterior con el nuevo esquema | sigue leyendo y escribiendo todas las tablas que conocía, por lo que un rollback no requiere ningún paso de esquema | `tests/unit/test_migrations_additive.py` |
+| Un archivo de migración ya aplicado | nunca se edita ni se elimina; una corrección es un archivo nuevo | el checksum del registro; `--dry-run --strict` |
+| Un cliente que envía un campo que el servidor eliminó | se atiende; el campo aparece en `ignored_args` | `server/transport/arg_check.py` |
+| La compilación anterior y la nueva sirviendo a la vez | cada una lee lo que escribió la otra, incluidas las columnas nuevas, salvo una funcionalidad que se activa solo después del despliegue (paso 8) | `make test-mixed-version` |
+
+Una actualización puede cambiar o eliminar operaciones y campos. Consulta qué sirve un despliegue
+con el catálogo de capacidades
+([API HTTP](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#discovering-what-a-deployment-serves)) y lista lo que
+cambió entre dos compilaciones con `scripts/codegen/wire_changelog.py `
+([generación de código](https://github.com/ClickHouse/loom/blob/main/docs/development/code-generation.md#wire-changelog)).
+
+
+
+## Documentación relacionada
+
+- [Despliegue](https://github.com/ClickHouse/loom/blob/main/docs/operations/deployment.md#zero-downtime-pair): el par que convierte una actualización en un intercambio
+- [Migraciones](https://github.com/ClickHouse/loom/blob/main/docs/development/migrations.md): las reglas que sigue una nueva migración
+- [Actualizaciones progresivas](../architecture/rolling-upgrades.md): las reglas para las compilaciones N-1 y N
+- [Solución de problemas](https://github.com/ClickHouse/loom/blob/main/docs/operations/troubleshooting.md#migrations-pending-or-checksum-drift)
diff --git a/i18n/.pending/es/docs/reference/mcp.md b/i18n/.pending/es/docs/reference/mcp.md
new file mode 100644
index 0000000000..230b53c0b6
--- /dev/null
+++ b/i18n/.pending/es/docs/reference/mcp.md
@@ -0,0 +1,453 @@
+
+> Esta página es una traducción automática de la [página en inglés](https://github.com/ClickHouse/loom/blob/main/docs/reference/mcp.md), que prevalece.
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/reference/mcp.md), which is authoritative.
+
+
+
+# Referencia de MCP
+
+Loom expone sus operaciones como herramientas MCP en `/mcp`. Cualquier cliente MCP que
+hable HTTP en streaming se conecta con una URL y un token bearer. La lista de herramientas
+se genera a partir del mismo registro de operaciones que la [API HTTP](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md),
+y una llamada a una herramienta sigue la misma ruta de autorización, límite de tasa, auditoría e idempotencia
+que `POST /v1/`. El transporte está en `server/transport/mcp.py`, con la llamada a una
+herramienta en `mcp_call.py` y `mcp_outcome.py`, las comprobaciones del bearer en `mcp_auth.py`, su
+listado en `mcp_tools.py`, el modelado de esquemas en `mcp_schemas.py`, las constantes de protocolo y
+sesión en `mcp_config.py` y las descripciones curadas en
+`mcp_descriptions.py`.
+
+La configuración de un cliente concreto (Claude Code, Codex, Cursor, VS Code, Claude Desktop
+y otros) con `loom install` o a mano está en
+[Clientes MCP](https://github.com/ClickHouse/loom/blob/main/docs/features/integrations/mcp-clients.md).
+
+
+
+## Punto de conexión
+
+| Solicitud | Qué hace |
+| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `POST /mcp` | Una solicitud JSON-RPC o un lote de 1 a 64. La respuesta es un cuerpo JSON, no un flujo de eventos. Una notificación responde `202` sin cuerpo. |
+| `DELETE /mcp` + `Mcp-Session-Id` | Termina la sesión y cierra su ejecución implícita. Tiene límite de frecuencia como `run.complete`, por llamador dentro del presupuesto de la organización: al superar el tope responde `429` con `Retry-After`. |
+
+Los parámetros de consulta en la URL seleccionan lo que `tools/list` muestra para esa conexión:
+
+- `?toolset=` elige la lista que se muestra ([Conjuntos de herramientas](#toolsets)). Valor por defecto:
+ `LOOM_MCP_TOOLSET` (`core`).
+- `?schema_profile=` elige la forma del listado: `standard` (la descripción
+ curada y el esquema de entrada; el valor por defecto, `LOOM_MCP_SCHEMA_PROFILE`),
+ `full` (añade `outputSchema`) o `compact` (el primer párrafo y el
+ árbol de argumentos).
+
+Un valor desconocido en cualquiera de los dos vuelve al valor por defecto del despliegue, de modo que un error tipográfico nunca amplía ni reduce un listado en silencio. El valor de `?toolset=` también da forma al
+primer de sesión (las instrucciones de `initialize`, `server/discover`, el prompt `loom`, `loom://primer` y `loom_activate`): el primer nombra la herramienta propia de una op cuando el toolset la incluye; si no, nombra la op marcada con "(via loom_op)", y omite una op que `loom_op` no enruta allí.
+
+Métodos atendidos: `initialize`, `notifications/initialized`,
+`notifications/cancelled`, `ping`, `tools/list`, `tools/call`, `prompts/list`,
+`prompts/get` (el prompt `loom`: el primer de sesión), `resources/list`,
+`resources/read` (`loom://primer`) y `server/discover`. Los resultados de listas incluyen las pistas `ttlMs` y `cacheScope` para que un cliente pueda almacenarlos en caché.
+
+**Versiones del protocolo.** `2025-11-25`, `2025-06-18`, `2025-03-26` y
+`2024-11-05` (`MCP_SUPPORTED_PROTOCOL_VERSIONS`). `initialize` responde con la
+versión del cliente cuando es una de estas; si no, con `2025-11-25`. Un
+encabezado `MCP-Protocol-Version` que nombre otra revisión produce un HTTP 400 con el error JSON-RPC
+`-32022`, cuyo `data.supported` enumera las versiones atendidas. `server/discover`
+responde con la misma lista, las capacidades, la identidad del servidor y las
+instrucciones.
+
+
+
+## Autenticación
+
+`LOOM_MCP_AUTH_MODE` decide qué métodos necesitan un bearer:
+
+| Modo | Bearer requerido en |
+| ------------------------- | --------------------------------------------------------------- |
+| `required` (predeterminado) | todos los métodos excepto las notificaciones |
+| `discovery_only` | solo `tools/call`; todos los demás métodos están abiertos |
+| `open` | ninguno; un bearer inválido se ignora (solo redes de confianza) |
+
+Un servidor en un `LOOM_BIND_HOST` que no es loopback se niega a iniciar con `open` a menos que
+`LOOM_ALLOW_INSECURE=1`. Un despliegue con la autenticación desactivada (`LOOM_AUTH_REQUIRED=false`)
+se comporta como `open`. Un bearer ausente o inválido en un método protegido produce HTTP `401` con
+`WWW-Authenticate: Bearer realm="loom"` (más `error="invalid_token"` cuando se
+envió un token). Un token que todavía no se puede comprobar, porque la lista de
+revocación no se ha cargado, produce en cambio HTTP `503` con `Retry-After`, de modo que el cliente
+conserva el token y reintenta. **Por qué un 401 y no un error JSON-RPC:** los clientes basan su flujo de
+"necesita autenticación", y su descubrimiento OAuth, en el estado HTTP; un cuerpo de
+error JSON-RPC se mostraría en cambio como un error de análisis o de herramienta. El token
+es un JWT ordinario de Loom; consulta [Tokens y permisos](https://github.com/ClickHouse/loom/blob/main/docs/guides/tokens-and-grants.md).
+
+El bearer se lee únicamente del encabezado `Authorization`. Un token pasado como `?token=` en
+la URL de `/mcp` se ignora y la solicitud queda sin autenticar: las líneas de solicitud terminan en los registros
+de proxy y de acceso, donde un token en la URL quedaría escrito en texto plano.
+
+
+
+### Autorización con OAuth
+
+Se sirve solo con `LOOM_OAUTH_ENABLED=true`. Loom es un servidor de autorización OAuth 2.1 para clientes que
+se conectan mediante inicio de sesión en el navegador en lugar de un token pegado (`server/auth/oauth.py`):
+
+- Descubrimiento en `/.well-known/oauth-authorization-server` y
+ `/.well-known/oauth-protected-resource`.
+- Registro dinámico de clientes en `/oauth/register`: clientes públicos, PKCE
+ `S256` obligatorio.
+- `/oauth/authorize` y `/oauth/token` emiten un token de acceso más un token de
+ actualización rotativo. Una actualización tiene éxito solo cuando la solicitud indica el
+ `client_id` al que se emitió el token.
+- El token de acceso es un JWT de Loom para el usuario que inició sesión, de modo que los espacios de nombres a los que el usuario
+ se una más adelante son accesibles en la misma conexión.
+- El inicio de sesión usa el login con contraseña de Loom, a menos que `LOOM_OAUTH_LOGIN_PROVIDER=oidc`
+ lo delegue a un proveedor de identidad externo (`LOOM_OIDC_ISSUER`,
+ `LOOM_OIDC_CLIENT_ID`, `LOOM_OIDC_CLIENT_SECRET`). Delegar el inicio de sesión también
+ cierra el autorregistro con contraseña.
+- Un despliegue remoto debe servir HTTPS y establecer `LOOM_OAUTH_ISSUER` con su
+ URL base pública `https://`.
+- Un URI de redirección registrado debe ser absoluto y sin fragmento: `https`, `http`
+ hacia un host loopback, o un esquema de aplicación (`cursor://…`). La página de inicio de sesión indica
+ el host al que va la autorización.
+- Cada actualización vuelve a comprobar que la cuenta sigue activa y vuelve a derivar sus
+ roles, de modo que una cuenta liberada, o un sujeto eliminado de
+ `LOOM_PLATFORM_ADMINS`, no conserva su acceso al actualizar.
+
+[Seguridad](https://github.com/ClickHouse/loom/blob/main/docs/architecture/security.md) cubre el modelo de tokens que hay detrás de esto.
+
+
+
+## Sesiones e identidad
+
+- **Id de sesión.** `initialize` asigna un `Mcp-Session-Id` y cada respuesta
+ lo repite. El `clientInfo.name` del cliente se guarda en caché asociado a ese id y pasa a ser
+ el `agent` de las llamadas posteriores, convertido a slug (`Cursor` → `cursor`; si falta →
+ `claude-desktop`). La caché está en el proceso y tiene un límite de tamaño.
+- **Valores de identidad por defecto.** Las llamadas a herramientas suelen llevar solo los argumentos de la acción. El
+ servidor completa `org` a partir del token, y `namespace` y `agent` a partir del
+ workspace predeterminado del llamador; los argumentos explícitos tienen prioridad. Las llamadas `code.*` se resuelven en el plano de código
+ en su lugar, y en el toolset `assistant` una lectura que no indica `namespace` o no indica `agent`
+ sigue las reglas de ese toolset (consulta [El toolset assistant](#the-assistant-toolset)). Un argumento `org`
+ en el que el token no puede actuar se rechaza (`ORG_MISMATCH`): un token actúa en su
+ propia org, un token de toda la org (`*`) o un administrador de la plataforma en cualquier org, la misma regla que
+ sobre HTTP (`authz.may_act_in_org`). Un espacio de nombres restringido sigue rechazando a cualquier otra
+ org, incluidos los administradores de la plataforma. `loom_search` no acepta el argumento `namespace`: busca
+ en el espacio de nombres principal del llamador y en sus otros espacios de nombres de tipo memoria, hasta
+ el límite de dispersión.
+- **Ámbito de código.** Un cliente puede enviar `X-Loom-Code-Scope: /` (el
+ plugin de Claude Code envía el repositorio al que se resolvió su checkout). Se aplica
+ a toda llamada `code.*` que no indique un espacio de nombres, y la autorización se ejecuta entonces sobre ese
+ espacio de nombres como si se hubiera indicado. Con esa cabecera, `loom_search` también lee
+ los documentos del repositorio y las memorias `decision` de su espacio de nombres de código principal (trunk),
+ cuando el llamador puede leerlo, y ejecuta la comprobación de duplicados del tracker para una
+ consulta con forma de defecto.
+- **Ejecución implícita.** Una ejecución por (org, sujeto del token, sesión), iniciada en el
+ registro de ejecuciones por la primera llamada a una herramienta con ámbito de ejecución de la sesión y archivada en el
+ espacio de nombres predeterminado del llamador; las escrituras llevan su `run_id` (excepto `run.*`, que
+ indica su propia ejecución, `code.*`, que actúa como la identidad de código del despliegue, y
+ `working_memory.*` y `conversation.update`, donde `run_id` delimita o vincula
+ la fila), y las lecturas se etiquetan con él pero no se filtran. La ejecución se cierra con
+ `DELETE /mcp`, o cuando el worker `mcp_session_run_sweep` no encuentra ninguna llamada del
+ token bajo ella durante `LOOM_MCP_SESSION_RUN_IDLE_SECONDS` (1800 por defecto); un
+ despliegue que no ejecuta workers en segundo plano en ningún lugar mantiene abiertas las ejecuciones inactivas. La
+ ejecución no almacena un recuento de llamadas: sus llamadas son las filas de `agent_events` con su
+ `run_id`. Consulta [Ejecuciones](https://github.com/ClickHouse/loom/blob/main/docs/features/runs.md).
+
+
+
+## Lista de herramientas
+
+Toda operación del registro que no esté en `_MCP_HIDDEN_OPS` es una herramienta:
+
+- **Nombre.** `loom_` más el nombre de la operación con los puntos convertidos en guiones bajos (`memory.set` →
+ `loom_memory_set`).
+- **Descripción.** El texto curado en `TOOL_DESCRIPTIONS`
+ (`server/transport/mcp_descriptions.py`) cuando existe; si no, un texto de una línea de respaldo con el presupuesto de latencia de la operación, su idempotencia y el rol mínimo. Los
+ textos curados indican cuándo usar una herramienta y cuándo no; la elección se deja al
+ modelo. Un texto nombra otras operaciones por su nombre de operación, y cada listado lo representa para el cliente que lo lee (`name_ops_for_listing` en
+ `server/transport/mcp_op.py`): una operación que el listado incluye se nombra por su
+ herramienta (`loom_memory_update`), y una operación que no incluye conserva su nombre de operación,
+ el que acepta `loom_op`, con "(via loom_op)" después de su primera mención cuando
+ `loom_op` la enruta en esa conexión; no enruta una operación oculta, una
+ escritura en `readonly` ni nada en `assistant`. Las descripciones de los campos de entrada, y
+ el esquema de salida que conserva el perfil `full`, se representan de la misma manera, y también
+ el texto `instead` de una operación oculta; el texto propio de `loom_op`, que trata de los nombres de operación, se construye en cambio para cada listado. El texto del mentor se representa para el
+ listado del llamador también por MCP (el `hint` del resultado de una herramienta, la sección `mentor` de
+ `context.pack`, y los hints y el `when` del plano de `mentor.brief`); por HTTP
+ se lee tal como está almacenado.
+- **Esquema de entrada.** El modelo de entrada Pydantic de la operación sin los campos que el
+ servidor completa por sí mismo (`org`, `agent`, `user_id`, `session_id`, `consumer`),
+ los campos solo del dashboard (`_HIDDEN_OP_PROPS` en
+ `server/transport/mcp_schemas.py`) y todo campo marcado como `MCP_HIDDEN`;
+ `namespace` se mantiene como propiedad opcional. Los campos ocultos se siguen aceptando
+ por nombre.
+- **Anotaciones.** `readOnlyHint`, `destructiveHint` e `idempotentHint` se
+ derivan del registro (rol, idempotencia, auditoría, verbos destructivos en el
+ nombre). `readOnlyHint` es verdadero solo para una operación idempotente de viewer que no está
+ auditada ni marcada como `writes`, de modo que un cliente que aprueba automáticamente las herramientas de solo lectura
+ nunca ejecuta un cambio de estado sin confirmación. Son indicaciones; la comprobación de rol en el momento de la llamada es el límite real.
+
+Se listan tres herramientas sintéticas en todos los toolsets excepto `assistant`:
+
+| Herramienta | Qué hace |
+| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `loom_search` | Una sola llamada busca en memoria, perfil, conocimiento y conversaciones en paralelo y devuelve las cuatro secciones. `explain: true` añade por qué cada resultado de memoria quedó en su posición. |
+| `loom_activate` | Devuelve el primer de la sesión (perfil, preferencias, workspace predeterminado), el mismo texto que el prompt `loom`. |
+| `loom_op` | `{op, arguments}` ejecuta cualquier operación que la lista no incluya, por la misma ruta que una herramienta listada; `{op: "help", query}` lista hasta 15 operaciones coincidentes (`_CATALOG_LIMIT`), cada una con sus argumentos obligatorios y opcionales. |
+
+`loom_search` es la operación `search.query` del registro (`POST /v1/search.query`
+por HTTP, las mismas secciones sin el resumen de texto). Por MCP sigue la misma
+ruta que toda herramienta del registro (valores predeterminados del llamador, ejecución de sesión, autorización, auditoría de
+acceso restringido, clase de tráfico, política de historial, límite de tasa, idempotencia) y conserva su
+propio esquema listado, sus opciones tolerantes (un `top_k` fuera de rango o un `recipe` / `bodies` desconocido se ajusta, no se rechaza) y un resumen de texto junto al
+resultado reducido. `Operation.mcp_tool` la nombra, así que no se lista ni se puede invocar una segunda herramienta `loom_search_query`. Consulta la
+[búsqueda unificada](https://github.com/ClickHouse/loom/blob/main/docs/features/unified-search.md#searchquery-over-http-and-the-sdks).
+
+**Las operaciones ocultas** (`_MCP_HIDDEN_OPS` en `server/operations/toolsets.py`) no están
+listadas ni se pueden invocar por MCP: las búsquedas por almacén que `loom_search` reemplaza
+(`memory.search`, `knowledge.search`, `conversation.search`), las colas de revisión,
+snapshot y restore, la administración de políticas, los dashboards de auditoría y costos, y la ingesta del índice de código. Una llamada a una de ellas responde `isError` con el código `OP_NOT_ON_MCP` y qué usar
+en su lugar. Siguen disponibles por HTTP y los SDK. En el toolset `assistant`,
+`memory.search` y `knowledge.search` están listadas y se pueden invocar, y una llamada a cualquier
+otra operación oculta responde `UNKNOWN_OP`. La regla para ocultar una operación: ¿la usaría en el chat un usuario final típico, no un operador? Una vista de todo el espacio de nombres puede ocultarse
+mientras una variante limitada al llamador sigue en MCP: `namespace.list` está oculta y
+`namespace.list_mine` se puede invocar (listada en `all` y `readonly`, mediante `loom_op` en
+todos los demás toolsets excepto `assistant`); `memory.extraction_status` (cada lote en cola
+en el espacio de nombres) está oculta y `memory.extraction_status_mine` (los lotes que puso en cola el llamador,
+por `queue_id`, como máximo 20 por llamada) se puede invocar por nombre o mediante `loom_op`
+en todos los toolsets excepto `assistant` (`readonly` incluido). Su gemela de escritura,
+`memory.extraction_retry_mine`, vuelve a ejecutar una vez más los lotes fallidos del llamador;
+`loom_op` la enruta en todos los toolsets excepto `readonly` y `assistant`.
+
+
+
+### Conjuntos de herramientas
+
+Un toolset decide qué se **lista**; toda operación no oculta sigue pudiéndose invocar por nombre de
+herramienta, o mediante `loom_op`, sea cual sea el toolset. Dos excepciones: en
+`assistant` solo se pueden invocar sus propias lecturas, y en `readonly`, indicado por
+`?toolset=` o por `LOOM_MCP_TOOLSET` cuando la solicitud no indica ninguno, `loom_op`
+enruta solo operaciones de lectura.
+
+| Toolset | Lista | Para |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------- |
+| `core` | El ciclo de memoria: `memory.set/update/delete/pin/get/history/apply/lock`, `blacklist.add`, `context.pack`. Todas las demás operaciones se ejecutan mediante `loom_op`; ninguna herramienta listada en `core` registra turnos de conversación. Las herramientas de código se suman con `LOOM_MCP_CODE_TOOLS=true`. | clientes de chat (el valor predeterminado) |
+| `coding` | `memory.set/update/get/delete`, `working_memory.set`, `context.pack`, las herramientas de código (`code.search`, `grep`, `enclosing`, `ask`, `symbol`, `outline`, `callers`, `context_pack`), `tracker.duplicate_check`, `code.bisect_candidates`, `code.pr_check`, `code.impact`. | agentes de programación |
+| `tracker` | `tracker.answer`, `binding`, `component`, `duplicate_check`, `flaky`, `item`, `links`, `release`, `similar`, `test_signal`, además de `code.bisect_candidates`, `code.pr_check`, `code.impact`. | sesiones que trabajan en una prueba fallida, un fallo o un PR |
+| `tasks` | `task.pull/create/complete/fail/wont_do/defer/heartbeat/updates/list/get`, `inbox.list`. | una sesión que actúa como agente con una bandeja de tareas |
+| `atomic` | `memory.set/get/delete/ask`, `working_memory.set/append`, `run.begin/complete`. | agentes mínimos, configurados por política |
+| `readonly` | El listado `all` sin ninguna herramienta cuyo `readOnlyHint` sea falso; `loom_op` enruta solo operaciones de lectura. | registros de solo lectura |
+| `assistant` | Un conjunto fijo de lecturas para investigar Loom en nombre de una persona: `namespace.get/summary/inventory/tune/taxonomy/audit/validate/guide_get/guide_history/list_categories`, `mentor.brief/guide`, `help.search/get`, `grants.list`, `memory.inspect/search/ask/get/list/history/provenance/aggregate`, `facts.traverse/path`, `knowledge.search/get/list/inspect`, `code.search/symbol`, `insights.catalog/query`. Sin herramientas sintéticas. | un cliente de chat que actúa por una persona con sesión iniciada |
+| `all` | Toda operación no oculta cuya `maturity` sea `stable`, más las operaciones `experimental` que lista el roster core o atomic. Una operación experimental que ninguno de los dos rosters lista queda fuera; sigue pudiéndose invocar por nombre o mediante `loom_op`. Las herramientas de código solo con `LOOM_MCP_CODE_TOOLS=true`. | operadores |
+
+Los rosters curados se combinan: `?toolset=coding+tracker`, `coding,tracker`, o un
+`+` sin escapar que llega como espacio. Solo se pueden unir rosters curados (`all`,
+`readonly` y `assistant` son superficies completas), y una parte desconocida hace que todo el valor
+sea desconocido, así que el listado vuelve al valor predeterminado del despliegue. Los rosters son
+los frozensets de `server/operations/toolsets.py`; `ops.capabilities` informa los
+`toolsets` de cada operación. Un segundo registro MCP con otro toolset
+(`?toolset=tracker`, `?toolset=tasks`) añade un roster sin cambiar el primero.
+
+**Por qué el listado es pequeño.** El nombre, la descripción y el esquema de cada herramienta listada
+se pagan en tokens en cada turno de cada sesión, y la precisión en la selección de herramientas
+baja a medida que crece la lista. `tests/unit/test_mcp_listing_budget.py`
+mantiene cada roster por debajo de un tope de tokens. Es preferible dejar una operación invocable por nombre
+antes que listarla; [Cómo añadir una operación](https://github.com/ClickHouse/loom/blob/main/docs/development/adding-an-operation.md) explica
+cuándo y cómo listar una.
+
+
+
+## Resultados
+
+`structuredContent` (y el JSON en `content[0].text`) es la salida de la op, recortada
+a la respuesta (`server/transport/lean_results.py`): los resultados con su clave,
+contenido, espacio de nombres, fechas, similitud, fuente y estado, además de los
+conteos, la paginación y los campos de abstención. Se descartan los componentes de
+puntuación, las explicaciones, los planes y costos de recuperación, los hashes y los
+campos vacíos. **Por qué:** algunos clientes entregan `structuredContent` al modelo
+además del bloque de texto, y la forma completa de diagnóstico cuesta varios miles de
+tokens para una respuesta corta. `explain: true` en la llamada devuelve la forma
+completa. HTTP, los SDK y el toolset `assistant` siempre reciben el resultado completo
+(en `assistant`, un `memory.search` sin el desglose de puntuación por resultado).
+
+
+
+### El toolset assistant
+
+`?toolset=assistant` es la conexión que usa un cliente de chat para investigar Loom en
+nombre de la persona que ha iniciado sesión: qué contiene un espacio de nombres, cómo
+se usa, y respuestas con citas sobre memoria, documentos y código. El valor nombra
+solo `assistant` (en cualquier combinación de mayúsculas): un error ortográfico o una
+unión como `assistant+core` no se resuelve y la conexión recibe el listado
+predeterminado del despliegue, sin error. La garantía la dan la URL que configura el
+operador y un token `viewer`, no el cliente. Una réplica una versión más antigua
+tampoco conoce el valor y sirve su listado predeterminado, así que durante una
+actualización progresiva solo el token limita la conexión: apunte un cliente a
+`?toolset=assistant` solo cuando todas las réplicas ejecuten una compilación que lo
+sirva, y dele de todos modos un token `viewer`. En ella:
+
+- **Solo se pueden invocar sus lecturas.** Un `tools/call` a cualquier otra
+ herramienta, incluidas `loom_op` y `loom_search`, responde `isError` antes de que
+ se ejecute el manejador, sea lo que sea que el token permita: con el código
+ `UNKNOWN_OP`, o con el rechazo de acceso cuando la llamada nombra una organización o
+ un espacio de nombres que el token no puede leer, que se comprueba primero. El token
+ se sigue comprobando en cada llamada, de modo que una lectura que la persona no
+ puede hacer se rechaza como en cualquier otra conexión. Emita el token del cliente
+ con el rol `viewer` para que el mismo límite valga en todas las demás superficies.
+- **Sus llamadas se registran en el libro como consumidor `loom-assistant`**, sea lo
+ que sea que envíe la llamada, incluida una llamada rechazada a una herramienta del
+ registro (un nombre de herramienta desconocido no escribe ninguna fila).
+ `namespace.audit`, `namespace.summary`, `mentor.brief` y `knowledge.reads` excluyen
+ de sus conteos de uso las lecturas de ese consumidor y las del dashboard
+ (`loom-ui`), de modo que mirar un espacio de nombres no cambia su calificación (un
+ cambio en una memoria desde el dashboard es una persona usando el espacio de nombres
+ y sí cuenta en `namespace.audit` y `namespace.summary`); `namespace.audit` informa
+ cuántas excluyó en `summary.inspector_calls`. Un token cuyo claim `consumer` nombra
+ a otro consumidor conserva su claim, y sus llamadas se cuentan.
+- **Una lectura que no nombra espacio de nombres lee el del token.** El valor
+ predeterminado es el primer espacio de nombres que el claim del token nombra y que
+ puede leer, no el primero en el que puede escribir: el token de una respuesta del
+ assistant se emite para un espacio de nombres, mientras que el espacio de nombres
+ personal de su sujeto es el que puede escribir. Un token cuyo claim no nombra
+ ninguno conserva el workspace predeterminado del llamador.
+- **Una lectura nombra las filas que lee.** El assistant no escribe nada, así que el
+ propio agente de su cliente no tiene filas, y una lectura que no nombra ningún
+ `agent` no se restringe a él: `memory.ask` lee entre agentes y `mentor.brief` informa
+ sobre el principal escritor del espacio de nombres, igual que `memory.search`,
+ `memory.list` y `memory.history` ya leen entre agentes. `insights.query` responde
+ preguntas analíticas abiertas en SQL sobre las tablas que lista `insights.catalog`,
+ limitadas por ClickHouse a la organización y el espacio de nombres del token
+ ([diseño del assistant](../architecture/assistant.md#the-analysis-op)). Una lectura
+ de las filas de un solo escritor, `memory.aggregate` o `memory.provenance`, se
+ rechaza por falta de `agent` hasta que la llamada nombre al escritor: el `agent`,
+ `user_id` y `session_id` de un resultado de búsqueda. El listado ofrece esos
+ argumentos en cada lectura de memoria, y `agent` en `mentor.brief`. `memory.get`
+ recurre a la fila bajo cualquier agente.
+- **Las lecturas no registran uso.** `memory.search` se ejecuta con
+ `auto_touch: false` y `memory.ask` con `reinforce: false`, sea lo que sea que envíe
+ la llamada, de modo que una investigación no aumenta los conteos de recuperación que
+ ordenan los resultados; `memory.ask` también se ejecuta con `precedents: false`, así
+ que no se guarda ninguna respuesta para reutilizarla. Lo que queda es telemetría y
+ cachés: la fila del libro de solicitudes; la fila de exposición que deja toda
+ lectura de una memoria (`loom.memory_exposures`, el registro de a quién se le sirvió
+ cada fila); la traza de búsqueda de código que escribe un `code.search` o
+ `code.symbol` (`loom.code_search_trace`, bajo `LOOM_CODE_TRACE_LOG_ENABLED`); las
+ filas de traza de búsqueda y de nodos de consulta que escribe un `memory.search`
+ cuando `LOOM_SEARCH_TRACE_LOG_ENABLED` o `LOOM_MEMORY_QUERY_NODES_ENABLED` está
+ activado; una fila de consistencia de `memory.ask` bajo consistencia diferida; y la
+ caché de respuestas del modelo. Una llamada del assistant no abre ninguna ejecución
+ de sesión MCP, y su `initialize` y el prompt `loom` no escriben ninguna fila de
+ lectura de perfil: su primer no incluye ningún perfil.
+- **Los resultados son la salida completa**, tal como los devuelve HTTP, ya que una
+ cita necesita las identidades, versiones y atestaciones que la forma recortada
+ descarta; un `memory.search` se ejecuta con `explain: false`, así que sus resultados
+ no traen desglose de puntuación por resultado. `memory.search` y `knowledge.search`,
+ que los otros listados dejan a `loom_search`, se listan aquí para que una respuesta
+ pueda venir de un plano a la vez. Un resultado de `knowledge.search` nombra su
+ `source_uri`, la ruta de encabezados (`section`) y la `revision` con la que se
+ escribió su pasaje (0 cuando no se registró ninguna), y el de un archivo ingerido su
+ `locator`. El resultado es el pasaje más cercano, no una respuesta: la op no tiene
+ señal de abstención, así que el modelo dice que un hecho no está en los documentos
+ cuando ningún resultado lo afirma.
+- **Las instrucciones de `initialize`** indican al modelo que cite cada afirmación por
+ clave y versión o hash de contenido, o por `source_uri` del documento, sección y la
+ revisión que lleva un resultado (ninguna cuando es 0), que mantenga separadas las
+ afirmaciones de la fuente, los resultados calculados y su propia lectura, que
+ informe la evidencia faltante como no observada, y que trate el texto almacenado
+ como datos que no pueden conceder una herramienta ni aprobar un cambio.
+
+
+
+## Errores
+
+Una llamada que no puede ejecutarse tal como se envió vuelve como un **resultado de herramienta** con
+`isError: true`, un bloque de texto que lee el modelo y un cuerpo `structuredContent`.
+Los clientes se lo muestran al modelo para que pueda corregir la llamada; muchos clientes pierden
+el estado ante un frame de error JSON-RPC, que Loom reserva para los fallos de transporte.
+
+- **Argumentos incorrectos.** Un fallo de validación responde `": invalid
+arguments."` seguido de cada error de campo, cada clave desconocida con el campo
+ que probablemente se quiso escribir (incluidos los campos anidados), los argumentos
+ obligatorios y opcionales y un ejemplo de llamada corregida:
+
+ ```text
+ memory.get: invalid arguments.
+ memory_key: Field required [missing]
+ unknown 'key' — did you mean 'memory_key'?
+ required: memory_key
+ optional: if_version, include_recall_breakdown, as_of, fields, follow
+ example: {"memory_key": "deploy_window"}
+ ```
+
+ `structuredContent` lleva las mismas partes: `errors`, `op`, `required`,
+ `optional`, `unknown` (clave → sugerencia) y `example`. Una op que cambia
+ el estado (cualquier op que no sea de solo lectura) y recibe una clave casi correcta se rechaza antes de la
+ validación (`UNKNOWN_ARGUMENT`, no se escribe nada) con `did_you_mean` y los
+ argumentos de la op.
+
+- **Rechazos.** Un 4xx de un handler distinto de 401 (`LOCKED`, `PINNED_CONFLICT`,
+ `BLACKLISTED`, `RESOURCE_NOT_FOUND`, `RATE_LIMITED`, …) es un resultado de herramienta cuyo
+ cuerpo es el `detail` HTTP más `status` y, cuando hubo un `Retry-After`,
+ `retry_after_s`.
+- **Acceso.** Un fallo de rol responde `AUTH_INSUFFICIENT` con `required_role`; un
+ espacio de nombres que el token ni nombra ni tiene concedido responde
+ `NAMESPACE_NOT_ACCESSIBLE`. En un espacio de nombres de código o de tracker, o en una colección compartida
+ (no la personal de otra persona), el rechazo indica cómo obtener acceso.
+- **Errores de transporte** siguen siendo errores JSON-RPC: error de análisis `-32700`, solicitud
+ no válida `-32600` (un rechazo de autenticación lleva su estado HTTP; una solicitud mal formada o un
+ lote fuera del rango de 1 a 64 responde 200), método no encontrado `-32601`, versión
+ de protocolo no compatible `-32022` y un fallo del servidor `-32000 "tool execution
+failed"`. Un fallo que Loom nombra (`OVERLOADED`, `BACKEND_TIMEOUT`,
+ `SCHEMA_PENDING`, `EMBED_TIMEOUT`) indica su código y mensaje en ese error, y
+ `error.data` es el `detail` HTTP más `status`, `tool` y `request_id` (con
+ `retry_after_s` cuando el error indica una espera); cualquier otro fallo dice solo `internal error` y el
+ id de la solicitud.
+
+Todo cuerpo de rechazo con un `code` y todo `error.data` de un fallo llevan además `category`
+y `retryable`, igual que el envelope HTTP. El texto de rechazo de una herramienta termina con la misma clase
+en palabras (`(auth: do not retry unchanged)`), para un host que solo muestra el texto al modelo;
+los rechazos propios de `loom_op` llevan los campos en su texto JSON. Un rechazo `NAMESPACE_NOT_ACCESSIBLE`
+de un espacio de nombres que no es una colección, desde una herramienta que no es de código ni de tracker,
+en un toolset que llega a `loom_op`, lleva también un paso `next`
+([referencia de errores](https://github.com/ClickHouse/loom/blob/main/docs/reference/errors.md#the-error-envelope-over-http)). Cada código, con su
+causa y su solución, está en la [referencia de errores](https://github.com/ClickHouse/loom/blob/main/docs/reference/errors.md).
+
+
+
+## Seguridad
+
+`tools/call` ejecuta las puertas del transporte HTTP (`server/transport/gates.py`):
+
+- **Autorización** por llamada: el `required_role` de la op y las reglas de acceso del espacio de nombres.
+- **Límite de tasa**: los mismos buckets que en HTTP. Como los clientes MCP no reintentan, una llamada limitada cuya indicación de espera sea como máximo `LOOM_MCP_RATELIMIT_RETRY_MAX_WAIT_S` (por defecto 2 s) espera ese tiempo una sola vez y vuelve a comprobar los mismos buckets; una indicación más larga o una segunda negativa responde `RATE_LIMITED` con `retry_after_s` (`LOOM_MCP_RATELIMIT_RETRY_MAX_WAIT_S=0` nunca espera).
+- **Auditoría**: las ops declaradas con `audit=True` escriben las mismas filas de `loom.audit_log`.
+- **Idempotencia**: MCP no tiene cabecera de idempotencia, por lo que una op idempotente recibe `_idempotency_key` (o `idempotency_key`) en sus argumentos. Se elimina antes de la validación y se reproduce exactamente como lo hace el `Idempotency-Key` de HTTP: solo después de la autorización, y solo para el principal que lo almacenó.
+
+
+
+## Exportar el esquema de acciones
+
+Un gateway de políticas puede gobernar las herramientas de Loom a partir de un esquema generado desde el
+registro (`server/transport/action_schema.py`):
+
+```bash
+loom export-actions --format json -o loom-tools.json # tools/list manifest + a `loom` block per tool
+loom export-actions --format cedar -o loom.cedarschema # Cedar: one action per operation
+```
+
+El manifiesto JSON tiene la forma de `tools/list` de MCP (`name`, `description`,
+`inputSchema`, `outputSchema`) para cada op, además de un bloque `loom` con lo que un motor de
+políticas necesita y para lo que MCP no tiene ningún campo: el nombre de la op, la ruta HTTP, el
+rol requerido, la clase de efecto (`read`, `write` o `destructive`, según el mismo
+clasificador que usan las anotaciones), la idempotencia, el indicador de auditoría, la visibilidad en MCP y
+los nombres de los modelos de entrada y salida. El esquema Cedar declara, en el espacio de nombres
+`Loom`, un principal `Agent` y un recurso `Namespace`, un tipo de registro por cada
+modelo de entrada y salida, los grupos de acciones `Read`, `Write` y `Destructive`
+(`Destructive` dentro de `Write`), y una acción por operación en su grupo. `-o -`
+escribe en la salida estándar.
+
+
+
+## Relacionado
+
+- [Clientes MCP](https://github.com/ClickHouse/loom/blob/main/docs/features/integrations/mcp-clients.md): cómo conectar Claude Code, Codex, Cursor y otros clientes.
+- [Claude Code](https://github.com/ClickHouse/loom/blob/main/docs/features/integrations/claude-code.md) y [Codex](https://github.com/ClickHouse/loom/blob/main/docs/features/integrations/codex.md): los plugins que montan el servidor por sí mismos.
+- [Referencia de operaciones](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md): cada op con su rol, su tipo y si `all` la incluye en la lista.
+- [Referencia de errores](https://github.com/ClickHouse/loom/blob/main/docs/reference/errors.md).
diff --git a/i18n/.pending/ja/docs/architecture/system-overview.md b/i18n/.pending/ja/docs/architecture/system-overview.md
new file mode 100644
index 0000000000..fe998ea9ee
--- /dev/null
+++ b/i18n/.pending/ja/docs/architecture/system-overview.md
@@ -0,0 +1,330 @@
+
+> このページは[英語の原文](https://github.com/ClickHouse/loom/blob/main/docs/architecture/system-overview.md)の機械翻訳です。内容は英語の原文が優先されます。
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/architecture/system-overview.md), which is authoritative.
+
+
+
+# システム概要
+
+Loom は、Python サーバー(FastAPI アプリケーションとバックグラウンドワーカーのスーパーバイザー)と ClickHouse で構成され、ライブのメモリとナレッジ状態用のオプションとして Postgres を使用できます。Loom はステートフルです。Loom が保持するすべての情報(ファクトとそのベクトル、ドキュメント、会話、エンティティグラフ、コードインデックス、タスク、監査、コスト、消去の進捗)は ClickHouse に保存されます。ただし `LOOM_STORAGE_AUTHORITY=postgres` の場合は、ライブのメモリ、ナレッジ状態、およびそれに付随するレコードを Postgres が保持します([ストレージオーソリティ](storage-authority.md#the-tables))。サーバープロセス自体は永続的な状態を持たないため、任意の数のサーバープロセスが同じデプロイメントを処理でき、リクエストはどのプロセスにも到達できます。これらのストア以外に保持される少数の状態は、[デプロイメントトポロジー](#deployment-topology)に記載しています。
+
+ストレージのレイアウトについては、[ClickHouse](https://github.com/ClickHouse/loom/blob/main/docs/architecture/clickhouse.md) を参照してください。
+
+
+
+## 目標と非目標
+
+| 目標 | 非目標 |
+| -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| あらゆる種類の状態を 1 つのエンジンで扱う(ClickHouse が正本):ベクトル、全文検索、グラフのエッジ、時系列、台帳。 | サーバー内でのファイル形式の扱い:`knowledge.add` は `content: str` を受け取り、パースは CLI の役割です。 |
+| 1 つのワイヤーインターフェースを一度だけ宣言し、HTTP と MCP で同じように提供する。 | テーブルをまたぐトランザクション。派生行は主書き込みの後に追いつきます。 |
+| サーバープロセスは永続的な状態を持たない:プロセスを増やすだけでウェブ処理能力を追加できる。 | 双時間履歴。有効性は有効時間のみで、トランザクション時間の履歴はバージョンミラーが担います。 |
+| すべての行を、テナント(識別タプル)、書き込み主体(`actor`)、リクエスト(`log_comment`)に帰属させられる。 | GDPR 準拠の保証。消去と監査ハッシュはエンジニアリング上のプリミティブです。 |
+| キーなしでインストールしても起動して応答し、フェイクプロバイダーであることが報告される。 | |
+
+
+
+## コンポーネント
+
+```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
+```
+
+| コンポーネント | コード | 役割 |
+| ------------------ | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| トランスポート | `server/transport/http.py`, `server/transport/mcp.py` | リクエストをオペレーション呼び出しに変換します。どちらもレジストリから生成されます。すべての op は `POST /v1/` および MCP ツール `loom_`(ドットはアンダースコアになります)として公開されます。共通の受け付け処理は `server/transport/gates.py` にあります。 |
+| オペレーションレジストリ | `server/operations/` | op ごとに 1 つの `Operation`(`base.py`)を持ちます。名前、入力モデルと出力モデル、ハンドラ、`required_role`、`idempotent`、`audit`、`maturity`、スコープに関するフラグを含みます。`budget_p99_ms` は `server/settings/catalog.py` の予算テーブルから取得されます。`registry.py` の `ALL_OPERATIONS` は、各グループの `OPERATIONS` を結合したものです。 |
+| ドメインパッケージ | `server//` | プレーンごとに 1 つのパッケージ(`memory`、`code`、`tracker`、`knowledge`、`erasure`、`tasks`、`identity`、`insights`)があり、それぞれ `api/`(ワイヤモデルと `Operation` 宣言)、`app/`(ハンドラとオーケストレーション)、`domain/`(純粋なロジック)、`store/`(ClickHouse のステートメントと行ビルダー)、`workers/` を持ちます。[サーバーレイアウト](server-layout.md)を参照してください。 |
+| ClickHouse クライアント | `server/core/ch.py` | 唯一のクライアントです。プーリング、デッドライン、リトライ、クエリの帰属を扱います。`server/memory/store/rows.py` にはバージョン行ビルダーがあります。 |
+| ワーカー | `server/workers/` | `registry.py`(`_WORKERS`)に行として宣言されるバックグラウンドループです。それぞれが所属ドメインの `workers/` 内のモジュールであり、`supervisor.py` によって実行されます。 |
+| 認証 | `server/auth/` | JWT の検証、失効、ロールと名前空間の認可、OIDC、OAuth サーバー、セルフサインアップを扱います。[セキュリティ](https://github.com/ClickHouse/loom/blob/main/docs/architecture/security.md)を参照してください。 |
+| プロバイダー | `server/embedding/`, `server/llm/` | 差し替え可能なエンベッダーと LLM のクライアントで、それぞれ決定的なフェイクを備えます。[LLM アーキテクチャ](https://github.com/ClickHouse/loom/blob/main/docs/architecture/llm-architecture.md)を参照してください。 |
+| オブザーバビリティ | `server/observability/` | op ごとの台帳(`loom.agent_events`)、バッチ処理されるイベントストリーム、監査行、プロバイダーのヘルス、OpenTelemetry と Langfuse へのエクスポートを扱います。 |
+| ダッシュボード | `frontend/`(`frontend/dist/` から `/` で配信) | 同じ HTTP op を利用する React の UI です。ビルドされていないチェックアウトでは、そのページに 503 を返します。 |
+| CLI | `server/cli/` | `loom` コマンドです。運用操作(migrate、tokens、re-embed、doctor)と、op 用のクライアントを提供します。[CLI リファレンス](https://github.com/ClickHouse/loom/blob/main/docs/reference/cli.md)を参照してください。 |
+
+レジストリがワイヤ上のインターフェース全体です。`GET /v1/operations` はすべての op を予算とロールとともに一覧表示し、[オペレーションリファレンス](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md)はそこから生成されます。op を追加するには、モデルを定義し、ハンドラを書き、`Operation` を宣言して、所属グループの `OPERATIONS` リストに追加します([オペレーションの追加](https://github.com/ClickHouse/loom/blob/main/docs/development/adding-an-operation.md))。両方のトランスポートが自動的にそれを取り込みます。
+
+一部の HTTP ルートはレジストリの op ではありません。`/v1/health`、`/v1/whoami`、`/v1/operations`、`/v1/.well-known/jwks.json`、`/v1/.well-known/openid-configuration`、`/v1/knowledge.download`、`/v1/auth/login`、ダッシュボードの `/v1/me/*` と `/v1/admin/*` ヘルパー、そして OAuth と OIDC のエンドポイントです。これらは [HTTP API リファレンス](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md)に一覧があります。
+
+
+
+### 依存の方向
+
+```text
+transports → operations → /api → /app → /store → server/core/ch.py
+ ↘ /domain ↙
+```
+
+ワーカーはトランスポートと並ぶ位置にあり、所属ドメインの `app` と `store` を呼び出します。ハンドラはプロバイダーを呼び出します。トランスポートより下のどのモジュールも、トランスポートのモジュールをインポートしません。どのパッケージがどのパッケージをインポートできるか、およびドメイン内部のレイヤーについては[サーバーレイアウト](server-layout.md)に記載されており、`tests/unit/test_package_contracts.py` がそれを検証します。
+
+`tests/unit/test_transport_layering.py` はトランスポートのルールを検証します。`server/transport/`、`server/cli/`、`server/main.py` 以外が `server.transport` をインポートすると失敗します。そのため、下位レイヤーが必要とする要素はトランスポートより下に置かれています。MCP ツールセットのロースター(`server/operations/toolsets.py`)、レジストリ以外のルートのベアラーチェック(`server/auth/bearer.py`)、コードスコープのコンテキスト変数(`server/code/domain/scope.py`)、台帳の行ビルダー(`server/observability/ledger.py`)、レイテンシ予算(`server/observability/budgets.py`)、プレーンのデフォルト値(`server/code/app/common.py`)です。
+
+**理由:** プロトコル(ステータスコード、JSON-RPC フレーム、ヘッダー)を知っているのはトランスポートだけです。これにより、ハンドラは同じ入力モデルで HTTP、MCP、ワーカー、テストのいずれからでも呼び出せます。
+
+
+
+## リクエストパス
+
+どちらのトランスポートも、`server/transport/gates.py` で一度だけ行われる同じ受け入れ判定を実行する。
+違いは、認証情報と引数の読み取り方、および拒否の返し方である。HTTP はステータスと `detail` ボディで応答し、MCP は `isError` を持つ結果で応答する。
+
+
+
+### HTTP
+
+`server/transport/http.py` の `build_router()` は、op ごとに `POST /v1/` ルートを 1 つ追加する。
+まず `BodyLimitMiddleware` が、`LOOM_MAX_REQUEST_BYTES`(32 MiB)を超えるボディを 413 で拒否する。0 を指定すると上限は無効になる。その後、各リクエストは次のフェーズを順に通過する(`_make_endpoint`)。拒否された時点でリクエストは終了する。
+
+| フェーズ | コード | 拒否 |
+| -------------------- | -------------------------------------- | ---------- |
+| 開始 | `_begin_request` | なし。`X-Request-Id`(呼び出し元の値が 1〜64 文字の英数字、`.`、`_`、`-` であればそれを、そうでなければ新しい UUID)、`X-Schema-Version`、およびクエリタグ `""` を設定する。 |
+| トークン検証 | `_extract_auth` | 401 `AUTH_INVALID`(認証が有効なのにトークンがない、未対応のスキーム、トークンの検証失敗)。失効リストが読み込まれるまでは 503 `AUTH_UNAVAILABLE`。 |
+| ボディ読み取り | `_read_body` | JSON が不正な場合は 400 `VALIDATION_FAILED`。書き込み op の未知のキーがそのフィールドのいずれかに近い場合は 422 `UNKNOWN_ARGUMENT`。 |
+| ID の補完 | `gates.with_single_user_identity` | なし。シングルユーザーサーバーで、トークンなしの呼び出しに対して行う。`code.*` と `tracker.*` を除くすべての op ではインストールの org を、日常的なメモリ op と検索 op ではさらにその名前空間と op のエージェントを補う([対象の op](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#request))。名前空間を必要とするその他の op(code と tracker の op を除く)で名前空間が空または `"-"` の場合は取り除かれ、検証で不足として拒否される。HTTP のみ。 |
+| 検証 | `_validate_payload` | 422 `VALIDATION_FAILED`。対象フィールドを示す。 |
+| 認可 | `_authorize` → `gates.authorize` | 400 `IDENTITY_INCOMPLETE`(名前空間または org がない)、403 `AUTH_INSUFFICIENT`。 |
+| コンテキストとポリシーの紐付け | `_bind_context_and_policy` | 認証コンテキストと台帳の run(`X-Loom-Run-Id`)を設定する。履歴ポリシーが `enforce` モードで拒否した場合は 403 `POLICY_FORBIDDEN`。 |
+| レート制限 | `_rate_limit` → `gates.rate_limit` | `Retry-After` を伴う 429 `RATE_LIMITED`。制限対象のすべての呼び出しに `X-RateLimit-*` ヘッダーが付く。 |
+| 冪等性 | `_idempotency_gate` | 保存済みの応答を再生する(`X-Idempotent-Replay: true`)。同じキーが異なるボディで再利用された場合は 409 `IDEMPOTENT_CONFLICT`。 |
+| ハンドラー | `_run_handler` | ハンドラーの `HTTPException`、`LoomServerError` のコードとステータス、または 500 `INTERNAL_ERROR`。 |
+| 成功後 | `_finish_success`、`post_handler_rows` | なし。台帳の行、メトリクス、`ignored_args` を含むボディ、続いて予算超過、監査、冪等性の各行。 |
+
+この順序にしている理由:
+
+- **ボディより先にトークン。** デプロイが拒否する匿名リクエストには、ボディを読む前に 401 を返す。台帳の行は残らず、フィールドエラーも漏れず、どのテナントのレート制限バケットにも触れない。
+- **制限より先に認可。** リミッターは、検証済みトークンの org(`gates._rate_limit_org`)から取り、ボディの値だけから取ることはない。
+- **受け入れの後に冪等性。** 再生キーは、呼び出し元の org、サブジェクト、op にスコープされる(`server/core/idempotency.py`、`scoped_key`)。再生が匿名の呼び出し元、別のテナント、別の op に届くことはない。
+
+**フェイルオープンのゲート。** トラフィック分類とレートリミッターは可用性のための制御である。どちらかが例外を送出した場合、呼び出しは受け入れられ、その失敗は計数され、1 分に最大 1 回ログに記録される(`gates._fail_open`)。認証と認可はフェイルクローズである。
+
+**未知の引数。** 入力モデルは未知のキーを無視するため、`server/transport/arg_check.py` がそれらを名指しする。応答には `ignored_args`(フィールド名に近いものがあれば `did_you_mean`)が含まれ、HTTP は `X-Loom-Ignored-Args` を設定する。どちらも、op が読み取ったが適用しなかったフィールドを先に、続いて読まれなかったキーを列挙する。書き込み op は、近い一致があれば 422 `UNKNOWN_ARGUMENT` で拒否する。ID のキーと、トランスポート自身が読むキー(`consumer`、`traffic_class`、`explain`、冪等性キー)は報告されない。
+
+**ハンドラーの後。** 台帳の行には、呼び出しのレイテンシと、埋め込みおよび LLM の支出が記録される。予算超過の行(`budget_p99_ms` × `LOOM_LATENCY_BUDGET_MULTIPLIER` を超えた場合)、監査の行(`op.audit` の場合)、冪等性の行は、1 回のラウンドトリップで書き込まれる(`gather_best_effort`)。いずれもベストエフォートである。リクエストのすべての ClickHouse ステートメントには `log_comment = ""` が付く([クエリの帰属](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`)。`MCP_SUPPORTED_PROTOCOL_VERSIONS`(`mcp_config.py`)にあるプロトコルリビジョンに対応する。`initialize` は、クライアントのバージョンが対応していればそれをそのまま返し、そうでなければ最新のバージョンを返す。サーバー起点のイベントはない。
+
+| メソッド | 動作 |
+| ---------------------------------- | ---------- |
+| `initialize` | バージョンを交渉し、`instructions` を返す。これは呼び出し元のプロファイルセクションを含むプライマーである。同じプライマーが、`loom://primer` リソース、`loom` プロンプト、`loom_activate` ツールとしても提供される。 |
+| `tools/list` | 接続のツールセットに対応するロースター(URL で決まり、呼び出し元には依存しない)。 |
+| `tools/call` | HTTP と同じゲートを通る 1 回の op 呼び出し。 |
+| `prompts/*`、`resources/*`、`ping` | プライマー関連のサーフェスと死活確認。 |
+
+`LOOM_MCP_AUTH_MODE` は、どのメソッドにベアラーが必要かを決める。`required`(デフォルト。通知を除くすべてのメソッド)、`discovery_only`(`tools/call` のみ)、`open` のいずれか。拒否には、保護リソースメタデータを指す `WWW-Authenticate` チャレンジが付くため、ネイティブコネクターは OAuth サーバーを見つけられる(`mcp_auth.py`)。
+
+`tools/list` は、`LOOM_MCP_TOOLSET`(デフォルトは `core`)または `?toolset=` で選ばれたロースターを表示する(`server/operations/toolsets.py`)。ロースターは可視性だけを決める。すべての op は名前で呼び出せるが、`_MCP_HIDDEN_OPS` にある op は例外で、MCP では一覧にも呼び出しにも現れない(HTTP では引き続き提供される)。ツールセットは [MCP リファレンス](https://github.com/ClickHouse/loom/blob/main/docs/reference/mcp.md)にある。3 つのツールは手書きのディスクリプターを持つ。`loom_search`(`search.query` op を、テキストの要約と簡素なセクションとして返す)、`loom_op`(同じ経路で任意の op を名前で呼び出す。`op: "help"` で一覧を表示する。`server/transport/mcp_op.py`)、`loom_activate`(プライマー。レジストリの op ではない唯一のツール)である。
+
+`_call_tool`(`mcp_call.py`。テレメトリ、レスポンス、失敗時の応答は `mcp_outcome.py`)は、次のフェーズを順に実行する:
+
+1. **ツールの解決**(`_resolve_tool`)。未知または非表示のツールは、代わりに使うべきものを示す `isError` の結果になる。
+2. **呼び出し元の紐付け**(`_bind_caller_identity`)。リクエスト ID を発行し、クエリタグを設定し、省略された名前空間とエージェントをトークンと呼び出し元の保存済みデフォルトから補う。明示された引数が優先される。`code.*` op のデフォルトは、デプロイの code 名前空間である。`_MCP_CROSS_AGENT_READS` の読み取りでは、`agent` のデフォルトは `*` になる。
+3. **セッション run。** (org、トークンのサブジェクト、`Mcp-Session-Id`) ごとに暗黙の run が 1 つあり、呼び出し元のデフォルト名前空間に登録される。run を指定しない書き込みには、セッションの `run_id` が付く。ただし、独自の run を指定する `run.*`、デプロイの code ID として動作する `code.*`、`run_id` が行のスコープまたは紐付けを決める `working_memory.*` と `conversation.update` は除く。
+4. **冪等性キー。** 冪等なツールは、引数に `_idempotency_key`(または `idempotency_key`)を取り、検証の前に取り出される。
+5. **引数**(`_validated_input`)。まずスペルミスの引数の拒否、次に検証。失敗は `isError` の結果となり、フィールドエラー、未知のキーごとに意図されたと思われるフィールド、op の引数、呼び出し例が含まれる(`arg_feedback.py`)。
+6. **認可**(`_authorize_call`)。共有のゲート。
+7. **受け入れ**(`_admission_refusal`):トラフィッククラス、履歴ポリシー、レート制限。短いヒントを伴う 429 の場合、トランスポートは 1 回だけ待って再確認する(最大 `LOOM_MCP_RATELIMIT_RETRY_MAX_WAIT_S`)。
+8. **冪等性の再生。** 受け入れられた呼び出し元に対してのみ行う。
+9. **ハンドラー。**
+10. **レスポンス。** `structuredContent` はランキングと集計の詳細を省き(`lean_results.py`。`explain=true` で保持される)、`ignored_args` を含む。
+
+**拒否は結果、失敗はエラー。** 401 以外の 4xx(`LOCKED`、`PINNED_CONFLICT`、`BLACKLISTED`、`RESOURCE_NOT_FOUND`、タスク状態コード、`RATE_LIMITED`)は、構造化ボディを持つ `isError: true` として返されるため(`mcp_refusals.py`)、クライアントはガイダンスを確認できる。401 と 5xx(`OVERLOADED`、`BACKEND_TIMEOUT`、`SCHEMA_PENDING`)は、HTTP のボディとリトライのヒントを持つ JSON-RPC エラーのままである。
+
+書き込み 1 件(`memory.set`)と読み取り 1 件(`memory.search`)のウォークスルーは、[メモリアーキテクチャ](memory-architecture.md)にある。
+
+
+
+## ロールとプロセスモード
+
+
+
+### ロール
+
+`Role`(`server/operations/base.py`)は `VIEWER < WRITER < ADMIN < ORG_ADMIN <
+PLATFORM_ADMIN` の順に並んでいます。各 op は `required_role` を宣言します。フラットトークンのロールは、そのトークンが読み取るすべての名前空間に適用されます。`loom.namespace_grants` は名前空間ごとにそのロールを引き上げられますが、引き下げることはできません。スコープ付きトークンの `ns_roles` は、そこに挙げられた名前空間に対して優先されます。グラントと `ns_roles` に指定できるのは `viewer`、`writer`、`admin` のみです。`ORG_ADMIN` と `PLATFORM_ADMIN` は、フラットトークンの `roles` にのみ存在します。詳細は[セキュリティ](https://github.com/ClickHouse/loom/blob/main/docs/architecture/security.md#authorization)と[アイデンティティと名前空間](https://github.com/ClickHouse/loom/blob/main/docs/concepts/identities-and-namespaces.md)を参照してください。
+
+
+
+### プロセスモード
+
+1 つのイメージがすべてのロールを担います。プロセスの動作は設定で決まります。
+
+| モード | 設定 | 実行されるもの |
+| ------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| オールインワン | `LOOM_BACKGROUND_WORKERS=auto`(デフォルト) | Web ティアと、そのデプロイメントの ClickHouse リースを保持するプロセス内のワーカー。 |
+| Web レプリカ | `LOOM_BACKGROUND_WORKERS=off` | HTTP、MCP、ダッシュボード。自身の失効スナップショットと署名キーリングを更新します。 |
+| ワーカー | `LOOM_BACKGROUND_WORKERS=auto`, `LOOM_DEPLOYMENT=1`, `LOOM_SERVES_TRAFFIC=false` | スーパーバイザーとそのワーカー。`/v1/health` は引き続き応答します。 |
+| ブランチ / A-B サーバー | `LOOM_BOOT_MIGRATE=false`, `LOOM_INSTANCE_LABEL=::` | マイグレーションを適用せずに共有 ClickHouse を利用します。ここでは `auto` でもワーカーは実行されません。 |
+
+`LOOM_WEB_WORKERS` は、コンテナあたりの uvicorn プロセス数を設定します。未設定の場合、イメージはコンテナが使用できる CPU ごとに 1 つ、ただしメモリ 1 GiB あたり最大 1 つ、かつ最大 8 つまで起動します。各プロセスは完全な lifespan を実行します。`auto` ではデプロイメントのリースによって、ワーカーを実行するプロセスが 1 つ選ばれます。`on` はリースを取得しません。各プロセスがそれぞれワーカーのコピーを実行し、`auto` のプロセスがリースを保持していない限り、他のプロセスは `workers_lease_absent` を報告します。ワーカーコンテナは `auto` で実行します。
+
+**リーダー選出。** `server/workers/leader.py`(`decide_supervisor`、`keep_lease`)は、ClickHouse を通じてデプロイメントごとに 1 つのスーパーバイザーを選出します。キーは Keeper ロックテーブル `loom._migration_lock` 内の `workers_supervisor` です(厳密な KeeperMap のため、2 つの競合者のうち書き込みが成功するのは一方のみです)。有効期限は ClickHouse サーバーの時計で判定されます。保持者は `LOOM_SUPERVISOR_LEASE_TTL_S / 6` ごとに更新し、最後の更新から TTL の半分が経過した時点、または更新時に別の保持者が見つかった時点でワーカーを停止します。保持者が停止した場合は、`LOOM_SUPERVISOR_LEASE_TTL_S`(デフォルトは 30 秒)の経過後に、別の `auto` プロセスがリースを取得します。タイミングの詳細は[障害と復旧](failure-and-recovery.md#background-workers)にあります。正常停止ではリースが即座に解放されます。これにより、blue/green の新しい側が処理を引き継ぎます。
+
+**ClickHouse を使う理由:** ワーカーを実行しうるプロセスはコンテナやホストをまたいで存在し、ClickHouse はそれらすべてが共有する唯一のものだからです。複数のホストが `auto` で動作しても、ワーカーを実行するのは 1 つです([キャパシティ](failure-and-recovery.md#background-workers))。
+
+
+
+## 起動
+
+`server/main.py` の `lifespan` は、すべてのプロセスで次の順に実行されます(各ステップは `server/boot.py` にあります)。
+
+1. **起動ルール。** プロセスはデプロイメント(`LOOM_DEPLOYMENT=1`。compose ファイルが設定します)であるか、空でない `LOOM_INSTANCE_LABEL` を持っている必要があります。それ以外の場合は起動を拒否します。認証を必須とするデプロイメントで、リポジトリにチェックインされた開発用の `LOOM_JWT_SECRET` を使っている場合も起動を拒否します(`require_real_signing_secret`)。例外は `LOOM_INSTANCE_LABEL=deploy:dev` のみです。
+2. ClickHouse に**接続**します。
+3. **マイグレーション**(`LOOM_BOOT_MIGRATE`、デフォルトで有効)。すべてのプロセスは、適用前にデプロイメントのマイグレーションロックを取得します。これは `loom._migration_lock` 内の KeeperMap キーです(`server/core/schema/migrate_lease.py`)。Keeper のないサーバー、またはマイグレーションの失敗は、起動を停止させます。`LOOM_BOOT_MIGRATE=false` の場合、プロセスは未適用のファイルをログに記録し、`/v1/health` で報告します。Postgres オーソリティの下では、最初のハートビートとリースの判定の前に、デプロイメントのセル状態を読み取ります。最初の読み取りに失敗すると起動が停止します(Postgres のマイグレーションが未適用の場合は、ゲートされた未準備の状態で起動し、読み取りが成功するまでそのままです)([セル](https://github.com/ClickHouse/loom/blob/main/docs/architecture/cells.md#the-tenancy-check-and-placement))。
+4. **`agent_events` エミッターを開始**します。
+5. **デフォルトの名前空間。** 認証が無効の場合、設定された名前空間に `loom.namespaces` の行を作成します。ただし、セルゲートがこのプロセスを拒否する場合は作成しません。
+6. **ワーカーリーダーを選出**します。
+7. **リーダーの職務。** 保持期間の TTL オーバーライドを、差異がある箇所に適用し、設定されたトラッカーの名前空間を登録します。
+8. **トークンの状態とオーバーライド。** 失効済みトークンのスナップショット(`server/auth/revocation.py`)と署名キーリング(`server/auth/keyring.py`)を読み込みます。すべてのプロセスが、それぞれ独自のタイマーで両方を更新します。管理者のランタイムオーバーライド(`loom.runtime_overrides`:レート制限、レイテンシ予算、ライブ設定)の取り込みを `LOOM_RUNTIME_OVERRIDES_REFRESH_SECONDS` ごとに開始します。workers 子プロセスも同様に取り込みます。ライブ設定のオーバーライドはプロセス自身の `settings` に重ねて適用されるため、コードからは `settings.` として読み取れます([ランタイム設定](https://github.com/ClickHouse/loom/blob/main/docs/operations/runtime-settings.md))。
+9. リーダーで**ワーカーを開始**し、`auto` ではリースループも開始します(Postgres オーソリティの下では `on` でも開始します。この場合はセルゲートがワーカーとリースループを開始・停止します)。
+10. **プロバイダーレポート。** 解決された LLM プロバイダーをログに記録し、エンベッダーの次元数を調べます。
+11. **ベクトル機能。** 量子化コードの読み取り設定、パッチパーツ、および挿入時にベクトルインデックスの構築を省略できるかどうかを調べます。
+12. エンベッダーから類似度のしきい値を**キャリブレーション**します(`LOOM_ADAPTIVE_THRESHOLDS`)。失敗しても起動は失敗せず、スカラー設定が適用されます。
+
+シャットダウンは、この逆の順序で行われます。ループを停止し、ワーカーをドレインし(10 秒)、リースを解放し、Langfuse キュー、イベントエミッター、遅延書き込み(露出行、書き込み後のプロジェクション、イベントストリーム)をドレインします。ClickHouse クライアントは最後に切断されます。
+
+`/v1/health` は ClickHouse への到達性と、`problems` のリスト(たとえば偽のプロバイダー)を報告します。503 を返すのは ClickHouse がダウンしている場合のみです。`?include=workers,langfuse,otel,embedding_cache` を付けると、サブシステムごとのチェックが追加されます。
+
+
+
+## バックグラウンド処理
+
+`WorkerSupervisor` は、有効化された各ワーカーにつき 1 つの asyncio タスクを、リースホルダー上でのみ実行します。各ワーカーは `server/workers/registry.py` 内の `_Worker` 行であり、有効化フラグと実行間隔を持ちます(多くの場合 `LOOM__ENABLED`、`LOOM__INTERVAL_SECONDS`)。スーパーバイザーは最初の実行をずらし、期限を過ぎた実行をキャンセルし、バックオフ付きで再試行し、すべてのクエリに `background` トラフィッククラスの下で `worker.` タグを付け、実行状態を `loom.worker_status` に記録します(`GET /v1/admin/workers.status`)。詳細は[障害と復旧](failure-and-recovery.md#worker-supervision)と、生成された[ワーカーリファレンス](https://github.com/ClickHouse/loom/blob/main/docs/reference/workers.md)を参照してください。
+
+
+
+## デプロイメントトポロジー
+
+```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
+```
+
+- **サーバープロセスは永続的な状態を持ちません。** レプリカ間で共有する状態(失効情報、署名鍵、ランタイムのオーバーライド、サインイン試行回数、グラフ書き込みマーク、スーパーバイザーのリース、消去のチェックポイント、ブラックリストのバージョン、デフォルトの authority 下の冪等性キャッシュ、記録された authority)とアップロードされたドキュメントの原本は ClickHouse に保存されます。`LOOM_DOCUMENT_OBJECT_STORE=s3` で書き込まれた原本のバイト列は、代わりに S3 互換のバケットに保存されます。Postgres authority の場合、Postgres は [ストレージ authority](storage-authority.md#the-tables) に挙げられたテーブルを保持し、その中には冪等性キャッシュ、独自の消去台帳、記録された authority のコピーが含まれます。同じ ClickHouse(その authority では Postgres も)、環境変数の設定、`LOOM_JWT_SECRET` を使い、行がバケット内のオブジェクトを指している間はそのバケットも使えば、新しい Loom ですべての機能が元に戻ります。
+- **ClickHouse と Postgres の外にある状態。** コードプレーンの git ミラーは `var/code_repos` 配下にあり(キャッシュです。ミラーのないホストは再クローンします)、レート制限のバケットは `loom-shared` ボリューム上にあります。どちらも正本ではありません。また、カタログの行がバケット内のオブジェクトを指している間は、それらの原本のバイト列を保持する `LOOM_DOCUMENT_S3_BUCKET` も該当します。
+- **2 つのコンテナ、1 つのイメージ。** `dev/docker-compose.cloud.yml` は `loom-server`(`LOOM_BACKGROUND_WORKERS=off`)と `loom-workers`(`auto`:リースを保持している間ワーカーを実行)を起動します。そのため、長時間のワーカー処理がリクエストとイベントループを共有することはありません。
+- **ブルー/グリーンのペア。** `dev/docker-compose.colour.yml` はプロキシの背後で 2 つのカラーを実行します。`./redeploy.sh` はアイドル状態のカラーを起動し、ヘルスチェックの成功を待ってからアップストリームを切り替え、古いカラーを停止します。すべてのマイグレーションは追加のみなので、ロールバックにスキーマの手順は不要です。[デプロイ](https://github.com/ClickHouse/loom/blob/main/docs/operations/deployment.md)と[アップグレード](https://github.com/ClickHouse/loom/blob/main/docs/operations/upgrades.md)を参照してください。
+- **ClickHouse。** ClickHouse Cloud、またはセルフマネージドの OSS サーバーを使用します。単一の OSS ノードは高可用性ではありません。
+
+
+
+## 基本となる設計
+
+4つの設計が全体を支えています。いずれかを変更する場合は設計変更として扱い、プルリクエストとこのページで議論します。
+
+
+
+### 単一のエンジン:ClickHouse
+
+デフォルトの ClickHouse authority では、すべてのプレーン(ファクトとベクトル、BM25 とトークンのインデックス、1ホップにつき1つの上限付きクエリでたどるエンティティグラフ、コードインデックス、台帳とコスト)が ClickHouse のテーブル群です。`LOOM_STORAGE_AUTHORITY=postgres` の場合、稼働中のメモリと知識の状態は Postgres に保持されます。これは、バックアップと一貫性ドメインを1つにまとめる利点を手放す代わりに、メモリの書き込みをトランザクションで扱えるようにするものです([2つのストアが必要な理由](storage-authority.md#why-two-stores))。以下の「理由」と「コスト」はデフォルトの場合の説明です。
+
+**理由:** バックアップ、アクセス境界、検索と分析のためのクエリ言語がそれぞれ1つで済み、同期ジョブなしでメモリとそのテレメトリを結合できます。ハイブリッド検索はデータの隣で SQL として実行されます。別のベクトルストアを置くと、2つ目の一貫性ドメイン、二重書き込み、ネットワークをまたぐ結果の統合が加わります。
+
+**コスト:** トランザクション的な行更新はできません。更新可能なテーブルは `ReplacingMergeTree` で、`FINAL` を付けて読み取るため、すべての書き込み経路がすべてのカラムを引き継ぐ必要があります([FINAL の書き込みルール](https://github.com/ClickHouse/loom/blob/main/docs/architecture/clickhouse.md#the-final-write-rule))。また、テーブルをまたぐ書き込みはアトミックではありません([障害と復旧](failure-and-recovery.md))。
+
+
+
+### アイデンティティタプル
+
+すべてのメモリ行は `(org, namespace, agent, user_id, session_id)` を持ちます。最初の3つは必須で、残りのデフォルトは `'-'` です。それ以外のテナントテーブルも、少なくとも `(org, namespace)` を持ちます。メモリの書き込み時には、サーバーが `actor`(`human:` / `process:`、`server.memory.app.provenance.writer_actor`)と `source_class`(`server.memory.domain.provenance.source_class_for`)を付与します。これらはリクエストボディから取られることはなく、`derived`、`external`、`imported` への宣言された格下げのみ例外です。
+
+**理由:** テナンシー、作成者、来歴がカラムとして存在するため、すべての読み取りはソートキーでフィルタでき、各行は結合なしで、誰のものでどこから来たかを示せます。**コスト:** `actor` や `source_class` を付け忘れる新しい書き込み経路があると、帰属先を特定できない行ができます。
+
+
+
+### 行ごとのコンテンツハッシュ監査
+
+監査対象の書き込みは、すべて `loom.audit_log` に行を残します。その `row_hash` は、行の正規化 JSON に対する SHA-256 です(`server/observability/audit.py`)。1時間ごとのチェックポイント(`loom.audit_checkpoints`)は、閉じた各ウィンドウの行数とハッシュのダイジェストを封印し、それぞれ直前のチェックポイントにリンクします。
+
+**行ごとにする理由:** 行から行へのチェーンは、同時書き込みがあると分岐してしまい、Loom は多数のサーバープロセスで動作します。行ごとのハッシュはコンテンツの改ざんを検出し、1つのワーカーが封印するチェックポイントチェーンは、封印済みウィンドウでの行の削除、変更、遅れて追加された行を検出します。**コスト:** ウィンドウが封印される前に削除された行は、痕跡を残しません。詳しくは[セキュリティ](https://github.com/ClickHouse/loom/blob/main/docs/architecture/security.md#audit-log)を参照してください。
+
+
+
+### 5つの信念改訂操作
+
+メモリのライフサイクルは5つの操作からなります。Expand(`memory.set`)、Revise(`memory.update_by_id`)、Contract(`memory.delete`)、Reinforce(`memory.pin`)、Refuse(`blacklist.add`)です。これはコード上の enum ではなく設計上の視点であり、メモリプレーンでこれらのいずれにも対応しないものは疑わしいと見なします。マージ、移動、墨消しは、これらの組み合わせで表現します。詳しくは[メモリ](https://github.com/ClickHouse/loom/blob/main/docs/concepts/memory.md)を参照してください。
+
+
+
+## 不変条件
+
+- op が HTTP と MCP に存在するのは、その op が `ALL_OPERATIONS` に含まれている場合に限られます(MCP は op を非表示にできますが、HTTP は引き続き提供します)。
+- `server/transport/`、`server/cli/`、`server/main.py` 以外から `server.transport` を import してはなりません。
+- 拒否された後にゲートは実行されません。認証が有効な場合、匿名リクエストがボディパーサー、台帳、リミッター、リプレイキャッシュに到達することはありません。
+- レートリミッターは、検証済みトークンの org をキーにします。リプレイは、それを生成した呼び出し元、org、op にのみ返されます。
+- 認証と認可はフェイルクローズです。トラフィック分類とレート制限はフェイルオープンで、その回数はカウントされます。
+- MCP では、拒否は `isError: true` を持つ結果として返されます。JSON-RPC エラーになるのは 401 と 5xx のみです。
+- プロセスはデプロイメントそのものであるか、`LOOM_INSTANCE_LABEL` を持ちます。起動時のマイグレーションに失敗した場合、ワーカーが起動する前にプロセスが停止します。
+- `auto` では、デプロイメント内で最大 1 つのプロセスだけがスーパーバイザーリースを保持します。
+- ClickHouse は、すべてのメモリプレーンの行に対するシステムオブレコードです。
+- メモリ書き込みの `actor` と `source_class` は、呼び出し元ではなくサーバーが設定します。
+
+
+
+## ソースのエントリポイント
+
+| 対象 | 場所 |
+| ------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| アプリ、lifespan、ヘルスチェック | `server/main.py`、lifespan の起動・終了処理は `server/boot.py`、`GET /v1/health` は `server/health.py` |
+| オペレーションの宣言 | `server/operations/base.py`(`Operation`、`Role`)、レジストリは `server/operations/registry.py` |
+| HTTP ルートとフェーズ | `server/transport/http.py`(`build_router`、`_make_endpoint`)、`server/transport/post_rows.py`(`post_handler_rows`) |
+| 共通の受け入れ判定 | `server/transport/gates.py` |
+| 未知の引数 | `server/transport/arg_check.py`、`server/transport/arg_feedback.py` |
+| 冪等性キャッシュ | `server/core/idempotency.py` |
+| MCP のディスパッチと拒否 | `server/transport/mcp.py`、`mcp_call.py`(`_call_tool`)、`mcp_op.py`、`mcp_refusals.py` |
+| ClickHouse クライアント | `server/core/ch.py`(`get_client`、`set_query_tag`) |
+| ワーカーとリーダー | `server/workers/registry.py`、`supervisor.py`、`leader.py` |
+| マイグレーションのリース | `server/core/schema/migrate.py`、`server/core/schema/migrate_lease.py` |
+| レイヤリングのゲート | `tests/unit/test_transport_layering.py` |
+
+
+
+## 関連ドキュメント
+
+- [ClickHouse](https://github.com/ClickHouse/loom/blob/main/docs/architecture/clickhouse.md):テーブル、エンジン、インデックス、マイグレーション。
+- [メモリアーキテクチャ](memory-architecture.md):書き込みパスと読み取りパス。
+- [障害と復旧](failure-and-recovery.md):リトライ、修復、キャパシティ。
+- [セキュリティ](https://github.com/ClickHouse/loom/blob/main/docs/architecture/security.md):トークンと認可のゲートが何を検査するか。
+- [デプロイ](https://github.com/ClickHouse/loom/blob/main/docs/operations/deployment.md):トポロジーを支える手順。
diff --git a/i18n/.pending/ja/docs/development/adding-a-worker.md b/i18n/.pending/ja/docs/development/adding-a-worker.md
new file mode 100644
index 0000000000..2b2f79ba9d
--- /dev/null
+++ b/i18n/.pending/ja/docs/development/adding-a-worker.md
@@ -0,0 +1,186 @@
+
+> このページは[英語の原文](https://github.com/ClickHouse/loom/blob/main/docs/development/adding-a-worker.md)の機械翻訳です。内容は英語の原文が優先されます。
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/development/adding-a-worker.md), which is authoritative.
+
+
+
+# バックグラウンドワーカーを追加する
+
+ワーカーは、`server/workers/registry.py` の行(`_WORKERS`)と、1 つのパス関数を持つモジュールで構成されます。`enabled_workers()` は有効な行を `WorkerSpec` に変換し、`WorkerSupervisor`(`server/workers/supervisor.py`)が各ワーカーの実行、計時、バックオフ、ドレインを行います。生成された[ワーカーリファレンス](https://github.com/ClickHouse/loom/blob/main/docs/reference/workers.md)には、すべての行が一覧されています。
+
+```mermaid
+flowchart LR
+ S["settings <name>_enabled, <name>_interval_seconds"] --> R["_Worker row in _WORKERS"]
+ R --> E["enabled_workers() WorkerSpec"]
+ L["leader.py supervisor lock"] --> V["WorkerSupervisor"]
+ E --> V
+ V --> P["run_pass() server/<domain>/workers/<name>.py"]
+ V --> W["loom.worker_status /v1/admin/workers.status"]
+```
+
+
+
+## 1. パスを書く
+
+`server//workers/.py` に `async def run_pass()` を持つファイルを作成します。スーパーバイザーはこれを間隔ごとに 1 回呼び出し、戻り値は破棄します。小さな例が `server/tasks/workers/lease_sweep.py` です。
+
+```python
+from server.workers import pass_context
+from server.workers.status import record_pass
+
+
+async def run_pass() -> SweepResult:
+ from server.tasks.app.sweep import sweep_once
+
+ with record_pass("task_lease_sweep") as rec:
+ counts = await sweep_once()
+ rec.outcome = dict(counts)
+ result = SweepResult(**counts)
+ if result.total == 0:
+ pass_context.mark_idle()
+ else:
+ log.info("task_lease_sweep: expired=%d ...", result.expired)
+ return result
+```
+
+パスの契約:
+
+- **冪等かつ有界であること。** パスは、デッドラインでキャンセルされたり、クラッシュ後に再実行されたり、デプロイ後に別の色(colour)で実行されたりすることがあります。処理する量には上限を設け、残りは次のパスに任せます。
+- **デッドライン。** デフォルトは `min(4 × interval, 900 s)` で、下限は 60 s です(`default_max_pass_seconds`)。これを超えたパスはキャンセルされ、失敗として扱われます。より長いパスが必要な場合は、行に `max_pass_seconds` または `max_pass_setting` を設定します。
+- **失敗。** 例外が発生するとパスは失敗します。スーパーバイザーは指数バックオフ(1 s から 60 s まで倍増)で再試行し、3 回連続で失敗するとワーカーを `degraded` にします。デッドラインで打ち切られたパスや、間隔がデッドラインを超えるワーカー(日次・週次のパス)は、代わりに間隔いっぱい待機します(`failure_hold_seconds`)。これにより、再試行が同じデータベース時間を再び消費することを避けられます。
+- **部分的な失敗。** パス全体は失敗させずに一部の処理(leg)だけが失敗した場合は、`pass_context.note_failure(exc, what)` を呼び出します。これは連続失敗の回数に加算され、`loom.worker.partial_failures{worker}` に表示されます。
+- **アイドル。** 処理対象が何もなかったパスは `pass_context.mark_idle()` を呼び出します。スーパーバイザーはその後 `idle_interval_seconds` の間スリープします。
+- **カーソル。** ページングを行うワーカーは `pass_context.resume_cursor()` を読み取り、処理を止めた位置で `pass_context.set_cursor(value)` を呼び出します。カーソルはそのパスの `loom.worker_status` 行に保存されるため、再起動したプロセスは続きから再開します。
+- **広範な `except` には理由を書きます:** `# noqa: BLE001 — `。
+
+
+
+## 2. クエリを帰属させる
+
+スーパーバイザーはすべてのパスにタグを付けます。
+
+- ClickHouse のクエリには `log_comment` として `worker.` が付きます(`server/workers/status.py` の `set_worker_identity`)。
+- プロバイダーのスパンには `loom.operation=worker.` が付きます。
+- パスはバックグラウンドのトラフィッククラスで実行されます(`bind_background`)。
+- パスで発生した LLM とエンベッダーの消費は、台帳の 1 行 `worker..pass` に記録されます。
+
+スーパーバイザーの**外**にあるループ(タスク、スレッド、CLI ループ)は、自分でタグを付ける必要があります。付けない場合、そのクエリは `untagged:.` としてログに記録されます。
+
+```python
+from server.core.ch import set_query_tag
+
+set_query_tag("worker.my_loop")
+```
+
+
+
+## 3. 設定を追加する
+
+スイッチと実行間隔を、`server/settings/catalog.py` の該当領域のセクション(`Memory`、`Code`、`Tracker` など)に追加します。各コメントは、生成される[設定リファレンス](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md)の行の説明文になります。
+
+```python
+ # Lease sweeper: return expired leases to todo, resume deferred tasks at
+ # resume_at, escalate stale triage. One read per pass.
+ task_lease_sweep_enabled: bool = True
+ # Seconds between passes while there is work.
+ task_lease_sweep_interval_seconds: int = 60
+ # Seconds between passes that found nothing.
+ task_lease_sweep_idle_interval_seconds: int = 300
+```
+
+ワーカーが認証情報を必要とする場合、プロバイダーで費用が発生する場合、またはオペレーターが明示的に有効にするプレーンを担当する場合は、デフォルトを **off** にします。デフォルトで on のワーカーは、ノート PC を含むすべてのスタックで動作します。
+
+
+
+## 4. レジストリ行を追加する
+
+```python
+(
+ _Worker(
+ "task_lease_sweep",
+ "server.tasks.workers.lease_sweep",
+ "task_lease_sweep_enabled",
+ "task_lease_sweep_interval_seconds",
+ idle_interval="task_lease_sweep_idle_interval_seconds",
+ ),
+)
+```
+
+| `_Worker` フィールド | 意味 |
+| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `name` | ワーカーの名前。ログタグ、台帳の操作、ステータス行に使われます。 |
+| `module` | モジュールの完全なパス。ワーカーが有効な場合にのみインポートされるため、起動は高速なままで、オプションの依存関係はオプションのままです。 |
+| `enabled` | ワーカーを有効にする設定フラグ。`None` の場合は常に有効です。 |
+| `interval` | 実行間隔を秒単位で保持する設定フィールド。 |
+| `pass_attr` | パス関数の名前(デフォルトは `run_pass`)。 |
+| `also_requires` | ワーカーが必要とする 2 つ目の設定フラグ(読み取る台帳、提供するプレーン)。オフの場合、ワーカーもオフになります。 |
+| `idle_interval` | アイドルパスの後にスリープする時間を指定する設定フィールド。 |
+| `max_pass_seconds`, `max_pass_setting` | パスのデッドライン。固定値か、設定から読み取った値を指定します。 |
+| `first_pass_due` | モジュールの属性。開始時に一度だけ呼ばれる非同期チェックで、`True` を返すと、起動時のずらしを待たずに最初のパスを今すぐ実行します。 |
+| `owned_tables` | `True`:モジュールが `OWNED_TABLES` と `due_scope` をエクスポートします。対象範囲内の名前空間に対し、所有するテーブルに行がない場合、最初のパスが実行対象になります。 |
+
+**起動時のずらし。** 最初のパスのフックがない場合、最初のパスは `crc32(name) % interval` だけ待ちます。数時間しか生きないプロセス上の日次ワーカーは、そのため一度も実行されない可能性があります。そこで、ワーカーが埋めるものを宣言します。
+
+```python
+from server.workers.first_pass import OwnedTable
+
+OWNED_TABLES = (OwnedTable("loom.qa_item_embeddings", namespace_column="namespace"),)
+
+
+def due_scope() -> list[tuple[str, str]]: ... # the (org, namespace) pairs this worker fills
+```
+
+これは `server/tracker/workers/embed.py` の宣言です。チェックはテーブルごとに 1 つのステートメントで、`FIRST_PASS_DUE_TIMEOUT_SECONDS` で上限が決まります。読み取れないテーブルは実行対象として扱われます。
+
+
+
+## 5. 実行場所を理解する
+
+**デプロイメントごとに 1 つのスーパーバイザー。** `server/workers/leader.py` は、ClickHouse を介してすべてのコンテナとホストにわたり 1 つのプロセスを選出します。使用するのは、Keeper ロックテーブル `loom._migration_lock` の `workers_supervisor` キーです。保持者は `LOOM_SUPERVISOR_LEASE_TTL_S / 6` ごとにリースを更新します。リースを失った保持者は自身のワーカーを停止します。保持者が停止した場合は、`LOOM_SUPERVISOR_LEASE_TTL_S`(デフォルトは 30 秒)経過後に別のプロセスが引き継ぎます。
+
+| `LOOM_BACKGROUND_WORKERS` | 動作 |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `auto`(デフォルト) | リースを争い、保持している間はスーパーバイザーを実行します。デプロイメントの外(`LOOM_DEPLOYMENT` なし)では `off` になります。 |
+| `on` | 常にスーパーバイザーを実行します。 |
+| `off` | Web のみ。 |
+
+すべてのレプリカを `auto` で実行してください。どのレプリカもリーダーになる可能性があります。`make server` や iso server は、`on` を設定しない限りワーカーを実行しません。
+
+**2 つのコピーが一時的に重なることがあります。** 保持者は、更新できないまま T/2 が経過するとワーカーを停止します。これは別のプロセスが T で引き継ぐより前ですが、すでに送信済みのステートメントは反映されます。また、`on` のプロセスはリースを取得しません。2 つ目のコピーが動いても問題が起きないようにしてください。具体的には、冪等な書き込み、リース付きのクレーム、ストアに保持するカーソルを使います。LLM に費用をかけるワーカーは、2 つのコピーが動いている間、費用が倍になります。
+
+**バッチの合間に停止する。** 長いループは、書き込む各バッチの前に `pass_context.check_stop()` を呼び出します。パスが停止された場合、またはリースが失効した場合に `PassStopped` が送出され、これは `asyncio.to_thread` で実行中の処理にも届きます。`PassBudget.exhausted()` はこれを自動で呼び出します。
+
+**ローリングアップグレード。** 古いビルドは、稼働中の新しいビルドにリースを譲ります([障害と復旧](../architecture/failure-and-recovery.md#background-workers)を参照)。古いリーダーは停止時にリースを解放し、新しいプロセスが次のラウンドで、数秒以内にそれを取得します。
+
+
+
+## 6. テストで固定する
+
+- **レジストリのスナップショット。** `tests/unit/test_worker_registry_snapshot.py` は、3 つの設定プロファイル(`defaults`、`all_on`、`production`)でワーカーの一覧を構築し、すべての `WorkerSpec` フィールドを `tests/unit/snapshots/worker_registry.json` と比較します。スナップショットを再生成するのは、意図した変更の場合だけにしてください。
+
+ ```bash
+ LOOM_UPDATE_WORKER_SNAPSHOT=1 python -m pytest tests/unit/test_worker_registry_snapshot.py
+ ```
+
+ production でワーカーを実行する場合は、そのテスト内の `_PRODUCTION_FLAGS` にワーカーのフラグを追加します。
+
+- **パリティ。** `tests/unit/test_worker_registry_parity.py` は、すべてのフラグを有効にした状態で、`worker_meta()`(`/v1/admin/workers.status` が表示する内容)と `enabled_workers()` が同じ集合を返すことを検証します。
+- **パス本体。** ユニットテストでは、スタブのリポジトリまたはローカルの ClickHouse に対して `run_pass()` を呼び出します。監視下のパスの外では、`pass_context` の呼び出しはログを出力するだけです。
+- **生成されるドキュメント。** `python scripts/codegen/docs_reference.py` は、[ワーカーのリファレンス](https://github.com/ClickHouse/loom/blob/main/docs/reference/workers.md)を再生成します。内容が古いままだと `make lint` は失敗します。
+
+
+
+## 7. 動作を確認する
+
+- `/v1/admin/workers.status` は、このプロセスのレジストリと、ワーカーごとの最新の `loom.worker_status` 行をマージします。そのため、ワーカーコンテナで動作しているワーカーも Web ティアから確認できます。
+- `/v1/health?include=workers` は、ワーカーごとのステータスと `workers_leader` を返します。後者は、応答したプロセスがロックを保持しているかどうかと、その理由を示します。
+- `loom.worker.consecutive_failures{worker}` と `loom.worker.partial_failures{worker}` にアラートを設定してください([モニタリング](https://github.com/ClickHouse/loom/blob/main/docs/operations/monitoring.md))。
+
+
+
+## 関連情報
+
+- [Loom の拡張](https://github.com/ClickHouse/loom/blob/main/docs/development/extending-loom.md)
+- [ワーカーリファレンス](https://github.com/ClickHouse/loom/blob/main/docs/reference/workers.md)
+- [障害と復旧](../architecture/failure-and-recovery.md)
+- [ワーカーのステータス](https://github.com/ClickHouse/loom/blob/main/docs/operations/monitoring.md#worker-status)
diff --git a/i18n/.pending/ja/docs/features/conversations-and-sessions.md b/i18n/.pending/ja/docs/features/conversations-and-sessions.md
new file mode 100644
index 0000000000..40bb69db30
--- /dev/null
+++ b/i18n/.pending/ja/docs/features/conversations-and-sessions.md
@@ -0,0 +1,200 @@
+
+> このページは[英語の原文](https://github.com/ClickHouse/loom/blob/main/docs/features/conversations-and-sessions.md)の機械翻訳です。内容は英語の原文が優先されます。
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/features/conversations-and-sessions.md), which is authoritative.
+
+
+
+# 会話とセッション
+
+Loom は 3 種類のセッション状態を保持し、それぞれ独自のプレーンに置きます。
+
+| プレーン | 保持するもの | 埋め込み・検索 | 書き込み元 |
+| ------------------ | -------------------------------------------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| 会話プレーン | スレッドの発話をそのまま記録したもの(`loom.conversations`) | ユーザーとアシスタントの発話、およびコンパクションの要約。`conversation.search` で検索します | `conversation.append`、プラグインのキャプチャフック、`loom ingest-transcript` |
+| セッションブリーフ | 1 つの作業の流れを要約した、再開可能な状態(`loom.session_briefs`) | いいえ | `session.brief_save`、コンパクション時とセッション終了時のコーディングプラグイン |
+| メモリ | 発言内容から抽出された永続的な事実 | はい。`memory.search` で検索します | `memory.set`、`memory.set_from_messages` |
+
+発話を保存してもメモリは作成されません。会話を事実に変換するには、[`memory.set_from_messages`](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/extraction.md) に会話を送信してください。オーナーは、抽出済みのメモリを失うことなく、トランスクリプトの記録をオフにできます。また、ブリーフが想起時に事実と競合することはありません。
+
+
+
+## 会話
+
+
+
+### 記録するかどうかはオーナーが決める
+
+`conversation.append` は、名前空間で会話ログが有効になっている場合にのみターンを保存します。このスイッチ(`loom.namespaces` の `conversation_logging_enabled`)はデフォルトでオフで、フェイルクローズします。行のない名前空間は記録されません。オーナーは `conversation.set_logging(enabled=true)`(admin)またはダッシュボードの Conversations ページにある **Record conversations** スイッチでオンにします。
+
+ログがオフのとき、append は受理されますが何も保持されません。レスポンスは `stored: false, reason: "logging_disabled"` を返します。クライアントがオーナーの選択を上書きすることはできません。埋め込みの実行中にターンが削除された場合、append は遅れて届いたベクトルを破棄し、`stored: false, reason: "deleted"` を返します。
+
+
+
+### ターンの書き込み
+
+`conversation.append` は `thread_id`、`role`(`user`、`assistant`、`system`、`tool`)、`content` を受け取り、任意で `msg_id`、`reasoning`(モデルの推論を専用のカラムに保持)、`user_id`、`run_id`、`metadata`、`tokens` を受け取ります。スレッドは最初の append で作成されます。`conversation.create` は `title`、`metadata`、`run_id` を事前に付与するだけです。
+
+- **`msg_id` で冪等です。** `(thread_id, msg_id)` がすでに書き込まれているターンは再度書き込まれません(`reason: "duplicate"`)。`msg_id` がない場合、サーバーはスレッド、ロール、内容のハッシュから導出します。そのため、クライアントがターンを再ログしても、トランスクリプトが二重になることはありません。
+- **user ターンと assistant ターンは埋め込まれます。** 対象は先頭 2,048 文字までで、埋め込み行はこの文字列を保持します。再埋め込みは、ベクトルの生成元となったテキストから始まります。以前のビルドで書かれた行は 240 文字を保持しており、再埋め込みはそれをもとに行われます。`system` ターンと `tool` ターンは、コンパクションの要約を除き、インデックスされずにトランスクリプトに残ります。
+- **埋め込みはフェイルオープンです。** 埋め込みに失敗してもターンは保存され、エラーは埋め込み行に記録されます。再試行は行われません。そのターンはベクトル検索の対象外となり、部分文字列によるフォールバックでのみ見つかります。
+- **high と判定されるターンは埋め込まれません。** テキストに high の形(貼り付けられた API キー、`password=` の代入、カード番号、SSN、記載された PIN)が含まれるターンは、そのまま保存されますが、埋め込み行は作られず、テキストがエンベッダーに送られることもありません。`conversation.search` は、ベクトル検索でも部分文字列のフォールバックでも、そのターンを返しません。`conversation.threads` は、そのようなターンが最後にあるスレッドを、空の抜粋(および high と判定されるタイトルは空)で一覧表示します。このとき、抜粋として表示される 240 文字と、それに続く 1,024 文字を確認します。タイトル生成処理は、そのようなターンをモデルに送りません。最初の 8 件の user ターンと assistant ターンがすべて high と判定されるスレッド、または生成されたタイトルが high と判定されるスレッドは、タイトルなしのままとなり、メタデータに `title_refused` が記され、タイトル生成処理が再度問い合わせることはありません。そのようなターンが 8 件に満たないスレッドは、マークされないまま、通常のターンを待ちます。`conversation.update` または `conversation.create` による新しい `metadata` はこのマークを置き換え、タイトル生成処理はもう一度だけ問い合わせて、スレッドに再びマークを付けます。`conversation.get` と `conversation.list` は、引き続きそのターンをスレッド内で返します([機密度](https://github.com/ClickHouse/loom/blob/main/docs/architecture/security.md#sensitivity))。
+
+
+
+### 単一メッセージの保存
+
+チャットクライアントは、名前空間のトランスクリプトを記録せずに、ユーザーが 1 件のメッセージを後で検索できるよう保存させることができます。`conversation.save_message`(writer)がそのオプトインで、`conversation.search_saved_messages`(viewer)がその検索です。保存されたメッセージは会話の行であり、ユーザーの個人コレクションのドキュメントにはなりません([共有](../architecture/sharing.md#saved-messages))。
+
+クライアントがメッセージを保存してよいのは、すべてのレプリカがコンパクション中に保存状態を保持する場合に限られます。[ローリングアップグレードのルール](../architecture/rolling-upgrades.md#the-rules)を参照してください。
+
+これらは `conversation.append` および `conversation.search` と、次の 6 点で異なります。
+
+- **Record conversations スイッチは適用されません。** スイッチ(または `conversation.set_logging`)で記録がオフになっていても保存は行われ、保存によって記録がオンになることはありません。
+- **メッセージにはフラグが付き、ラベルは付け替えられません。** トランスクリプト行とその埋め込み行は、`is_saved` と `saved_at`(ユーザーがメッセージを保存した時刻)を持ちます。トランスクリプトにすでにあるメッセージはその場でフラグが付けられ、`run_id` と内容は記録されたままです。
+- **検索はユーザー単位です。** `conversation.search_saved_messages` は、指定した 1 つの名前空間内で `user_id` が所有するフラグ付きメッセージのみを返します。`conversation.search` は記録されたすべてのターンをランク付けし、デフォルトでは呼び出し元の名前空間全体に展開されます。
+- **検索はハイブリッドです。** ベクトル側はメッセージの先頭 2,048 文字を埋め込み、BM25 側は全文を読みます。そのため、正確な用語(チケット ID、テーブル名)や、長い保存済み回答の奥にあるフレーズでも上位に出ます。`search_mode="hybrid"`(デフォルト)は両者を逆順位で融合し、`semantic` と `lexical` はどちらか一方だけを実行し、`lexical_weight`(0〜1)は BM25 側の重みを調整します。BM25 のヒットの抜粋は、一致した語を中心に切り出されます。対象は 1 人のユーザーの保存メッセージなので、統計はクエリごとに計算されます。
+- **1 人のユーザーに固定されたトークンが使えます。** 1 つの資格情報で多数のユーザーにサービスを提供するインテグレーションは、`--read-scope own_user`(特定のユーザーには `--read-user-id`)を付けてトークンを発行します。以後、保存メッセージの op はそのユーザーとしてのみ動作します。別の `user_id` を指定したボディは 403 で拒否され、すべてのステートメントにトークンのユーザーが付きます。エンドユーザートークンは `namespace: "@me"` でこれらの op を呼び出します([共有](../architecture/sharing.md#saved-messages))。会話テーブルには `session_id` がないため、`own_session` トークンは拒否されます。他のすべての会話 op(`append`、`get`、`list`、`search`、`threads` など)は、スレッドに複数のユーザーが混在し、制限できるユーザー軸がないため、このようなトークンでは引き続き拒否されます。
+- **所有者、削除、ロールは保存のたびに確認されます。** 別の `user_id` の下に保存されたメッセージを保存しようとすると、`indexed: false, reason: "owner_mismatch"` が返ります。トゥームストーン化されたメッセージには `reason: "deleted"` が返り、保存済みの system ターンや tool ターンは埋め込まれないため `reason: "unsupported_role"` が返ります。テキストが high と判定されるメッセージも埋め込まれず、`reason: "high_sensitivity"` が返り、新規には保存されません。以前のビルドで保存されたものは、`conversation.search_saved_messages` のベクトルヒットにもキーワードヒットにもならず、`conversation.list_saved_messages` は空の抜粋で一覧表示します(`conversation.threads` と同様に、表示する `conversation_search_excerpt_chars` 文字と、それに続く 1,024 文字を確認します)。これらの確認は、すでに保存済みのメッセージにも適用されます。
+
+保存と保存解除は、append による埋め込み書き込み、コンパクションによる退避、スレッド削除と、更新可能なスレッドリースを共有します。append とコンパクションは、リースを取得する前にプロバイダーの処理を完了します。
+
+保存メッセージの所有者はトランスクリプト行が決めます。保存は、誰も所有していない行、または呼び出し元が所有する行のみを、ミューテーション内で確保します。したがって、所有者のいない 1 件のメッセージを 2 人のユーザーが保存した場合、先のユーザーが確保し、後のユーザーには `owner_mismatch` が返ります。埋め込み行は、トランスクリプト行が呼び出し元のものとして読み戻された後にのみフラグが付けられます。
+
+保存は安全に再試行できます。新規メッセージの同時保存でも、トランスクリプト行は 1 つしか保存されません。その挿入には、メッセージ ID から導出された重複排除トークンが付いているためです。各呼び出しはメッセージを読み直し、中断または同時の書き込みが残したものを修復します。欠けている埋め込み行を書き込み、直前の埋め込みが失敗していれば再度埋め込み、まだフラグが付いていない行にフラグを付けます。埋め込みに失敗した保存では、メッセージは保存済みとして格納され、`indexed: false, reason: "embed_failed"` が返ります。もう一度保存すると、埋め込みが再試行されます。同時の保存の後に埋め込みが到着したトランスクリプト append は、自身の埋め込み行にフラグを付けます。
+
+`conversation.list_saved_messages`(viewer)は、クエリなしで 1 人のユーザーの保存メッセージを、最近保存したものから順にページ送りします(`limit` は最大 200、不透明な `cursor`、任意の `conversation_id`)。その `ts` はユーザーがメッセージを保存した時刻で、トランスクリプトのメッセージ時刻とは独立しています。保存時刻なしで書かれた行は、メッセージのタイムスタンプを使います。これは「Saved」パネルの最初のビューで、ユーザーが入力すると検索で絞り込まれます。`conversation.saved_status`(viewer)は 1 つの `conversation_id` と最大 500 件の `message_ids` を受け取り、そのうちこのユーザーが保存したものを返します。これにより、クライアントは会話を開いたときに、すべてのメッセージの保存状態を 1 回の呼び出しで描画できます。
+
+`conversation.unsave_message`(writer)は、保存済みメッセージを所有者の検索から取り下げます。名前空間がトランスクリプトを記録している場合、オーナーが記録を選んでいるため、ターンはフラグが解除された状態でトランスクリプトに残ります。記録していない場合、そのターンは保存のためだけに存在していたので、軽量削除で取り除かれます(`removed: true`)。埋め込みはトゥームストーンを保持するため、古いバージョンが再び現れることはありません。呼び出し元のユーザーが保存していないメッセージや、別のユーザーが保存したメッセージには `found: false` が返り、どちらなのかは示されません。保存解除は冪等で、再度保存するとメッセージは復元されます。ユーザー単位の消去は、そのユーザーの他の会話行とともに保存メッセージも削除します。
+
+
+
+### 読み取りと検索
+
+| 操作 | ロール | 内容 |
+| ---------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------- |
+| `conversation.threads` | viewer | 名前空間の最近のスレッドを新しい順に返します(`window_days`、`limit`、最大 100,000 までの `offset`。すべてのエージェントには `agent="*"`)。 |
+| `conversation.get` | viewer | 1 つのスレッドのメタデータを返します。`include_messages=true` でそのターンをページ送りします(末尾からは `order="desc"`)。 |
+| `conversation.list` | viewer | スレッドのターンを、カーソルによるページ送りで返します。`run_id` で絞り込むこともできます。 |
+| `conversation.search` | viewer | 埋め込み済みターンに対するベクトル検索です。スレッド、run、ロールで絞り込むこともできます。 |
+| `conversation.update` | writer | スレッドの `title`、`metadata`、`run_id` を変更します。 |
+
+`conversation.search` はターンをコサイン類似度でランク付けし、`LOOM_CONVERSATION_SEARCH_MIN_SIMILARITY`(0.30)未満のものを除外し、デフォルトでは呼び出し元の名前空間全体に展開されます(`namespace_scope="all_mine"`)。エンベッダーが利用できないときは、op が応答できるように部分文字列一致にフォールバックします。ヒットにはターンの先頭 `LOOM_CONVERSATION_SEARCH_EXCERPT_CHARS` 文字(デフォルトは 240)が表示されます。ターン全体は `conversation.get` または `conversation.list` で読んでください。この op は MCP からは隠されており、エージェントは [`loom_search`](https://github.com/ClickHouse/loom/blob/main/docs/features/unified-search.md) の会話セクションを使います。
+
+`memory.recall` は別の読み取りです。抽出が読んだターン(`loom.memory_evidence` に保持)を検索します。これは会話プレーンが記録しているかどうかにかかわらず存在します。[検索と質問](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/search-and-ask.md)を参照してください。
+
+
+
+### コンパクションと削除
+
+- **`conversation.compact`**(writer、LLM プロバイダーが必要)は、末尾の `keep_recent`(デフォルト 10)より前にある最も古いターンのうち、要約器のプロンプトに収まるものを要約します。要約は、`metadata.compacted_from` に要約された `msg_id` を列挙した、埋め込み済みの 1 件の `system` ターンとして書き込まれ、元のターンとその埋め込みはトゥームストーン化されます。その後 `conversation.search` は、元のターンの代わりに要約を見つけます。スレッド内の別のエージェントが、ターン検索がインデックスするのと同じテキストのターンを有効なまま保持している場合、そのターンは埋め込みを保持します(以下の delete を参照)。新しいターンが `min_to_compact`(デフォルト 4)件に満たないウィンドウは、そのまま残されます。以前の要約は、`min_to_compact` にも `messages_summarized` にも数えられません。ウィンドウの先頭にある要約は、別枠の許容量からプロンプトに取り込まれます。その残りに収まらない要約は有効なまま残り、失敗した実行が残したもの(そのターンがすべて有効でウィンドウ内にあり、最初のターンの `ts` にあるもの)は、読まれずに置き換えられます。ウィンドウのさらに奥にある要約は、通常のターンと同じようにプロンプトの予算を消費し、そのターンとともに置き換えられます。high と判定されるターンはウィンドウから除外されます。そのターンは有効なまま残り、要約器に送られることもないため、ウィンドウの最初のターンに置かれる要約は、スレッド内でそのターンより前に来ることがあります。`conversation.save_message` で保存されたターンも、要約もトゥームストーン化もされず、要約と最近のターンの間にそのまま残ります。埋め込めない要約では何もコンパクションされず(`reason: "embed-failed"`)、いずれにせよ high と判定される要約でも同様です(`reason: "summary-high-sensitivity"`)。そのような要約は埋め込まれないためです。`embed-failed` と違い、この拒否は再試行する価値がありません。ターンが有効な間はウィンドウが変わらないため、再試行しても同じ要約器の呼び出しに費用がかかり、同じ要約が得られる可能性が高いからです。保存済みターンのみ、または high と判定されるターンのみを含むウィンドウには、`reason: "nothing-to-compact"` が返ります。
+- **`conversation.delete`**(admin)は、1 つのスレッドのターン、スレッド行、埋め込みをトゥームストーン化します。`confirm_thread_id` は `thread_id` と等しくなければなりません。スレッド内で別のエージェントもログしたターンは、そのエージェントが、検索がインデックスするのと同じテキスト(user ターンまたは assistant ターン、あるいは要約)の有効なコピーを保持している間、埋め込みを保持します。2 つのコピーが 1 つの埋め込み行を共有するためです。その行はそのコピーのエージェント、ロール、run、ユーザーを引き継ぐので、削除したエージェント自身の検索からは外れます(コンパクションも同様です)。ちょうど 240 文字の行(以前のビルドの切り詰め、またはその長さのターン)は、先頭 2,048 文字がそのエージェントのターンと一致するコピーに対してのみ保持され、照合するメッセージ行が残っていない場合はトゥームストーン化されます。削除は、そのターンについて自身のエージェントが有効なメッセージを保持しなくなったスレッドの行も完了させます。対象は、削除済みまたはコンパクション済みのもの(以前のビルドが残したもの)と、保持期間の TTL が切れたものです。個人や名前空間のデータをすべての場所から削除するには、[`erasure.request`](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/retention-and-erasure.md) を使います。
+
+トゥームストーン化されたターンは、`erasure.export` を除くすべての読み取りから除外されます。これは、`include_tombstoned: false` を指定しない限りそれらを返します。ディスクから削除されるのは、オペレーターがテーブル TTL(`LOOM_RETENTION_CONVERSATIONS_DAYS`、0 = 永久に保持)を設定した場合に限られます。この TTL の対象は `loom.conversations` のみで、テキストを最大 2,048 文字保持するターンの埋め込み行には TTL がありません。メッセージが期限切れになると、そのスレッドの全体削除によって、その行はターンの有効なコピーに引き継がれるか、トゥームストーン化されます。消去リクエストはそれをトゥームストーン化し、実際に取り除くのは `purge` を伴う `namespace_list` の消去のみです。`erasure.export` は埋め込み行を返さないため、TTL で期限切れになったターンの抜粋は、対象者とともに消去されますが、エクスポートには含まれません。
+
+
+
+### スレッドのタイトル
+
+`conversation_titler` ワーカーは、タイトルのないスレッド(`conversation.create` なしの append で作られたもの)に、LLM が書いた短いタイトルを付けます。ダッシュボードの Conversations ページはこのタイトルを先頭に表示します。対象は、会話を記録する名前空間のうち、直近の `LOOM_CONVERSATION_TITLER_WINDOW_HOURS`(168)時間以内にアクティブで、少なくとも `LOOM_CONVERSATION_TITLER_MIN_TURNS`(4)件のターンを持つスレッドで、1 回のパスにつき最大 `LOOM_CONVERSATION_TITLER_MAX_THREADS_PER_PASS`(10)件です。デフォルトで有効(`LOOM_CONVERSATION_TITLER_ENABLED`)で、フェイク LLM では何もしません。
+
+
+
+## クライアントからのセッションのキャプチャ
+
+| クライアント | ターンが Loom に届く仕組み |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Claude Code プラグイン | Stop フック(`hooks/loom-conversation.mjs`)がセッションのトランスクリプトから新しいターンをそれぞれ追記します。`msg_id` にはトランスクリプトの uuid が使われます。`LOOM_CAPTURE_CONVERSATIONS=false` で無効になります。名前空間の記録可否の判定をキャッシュし、記録がオフの間は追記をスキップします。 |
+| Codex プラグイン | 同じキャプチャを行います。詳しくは [Codex](https://github.com/ClickHouse/loom/blob/main/docs/features/integrations/codex.md) を参照してください。 |
+| Cursor | Cursor の会話後フックから実行される `integrations/cursor/cursor-session-hook.sh` が、トランスクリプトを `loom ingest-transcript` に渡します。 |
+| その他のエージェント | エクスポートしたトランスクリプトに対して `integrations/generic/ingest.sh` を実行します。 |
+| 任意の MCP クライアント | デフォルトの `core` 一覧には `conversation.append` が含まれず、モデルにターンの記録を促すものもありません。トランスクリプトフックでキャプチャするか、`loom_conversation_append` を一覧に含む `?toolset=all` をマウントしてください。 |
+| 独自のコード | `conversation.append`、または下記の Python SDK の `Session` を使います。 |
+
+`loom ingest-transcript --namespace NS --file session.md` は、`# user` と `# assistant` のセクションが交互に並ぶ Markdown ファイル、または `{role, content}` の JSON 配列を読み込み、各ターンを追記します(`--dry-run` はターン数を数えるだけで、`--thread-id` は固定の ID を設定します)。
+
+プラグインは、セッション終了時にそのセッションのターンを `memory.set_from_messages(defer=true)` にも渡します。そのため、トランスクリプトが記録されているかどうかにかかわらず事実が抽出されます。また、ツールの操作を `observe.record` / `observe.crystallize` でエピソード的な観測として記録します([抽出](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/extraction.md)を参照)。フックごとの接続方法は [Claude Code](https://github.com/ClickHouse/loom/blob/main/docs/features/integrations/claude-code.md) にあります。
+
+
+
+## セッションブリーフ
+
+セッションブリーフは、1 つの作業の流れについて、再開可能な状態をまとめたものです。目標、ステータス、決定事項、行き止まり、完了した作業、未解決の質問、次のステップ、主要なファイル、制約、参照先を含みます。コンパクション後、翌日、別のクライアント、あるいはチームメイトが読みます。埋め込みは作成されず、`memory.search` からも返されません。名前空間を読めるエージェントであれば、誰でも再開できます。
+
+| オペレーション | ロール | 動作 |
+| ---------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------- |
+| `session.brief_save` | writer | `events`(前回の保存以降に起きたこと)、エージェントが書いた `sections`、またはその両方からブリーフを更新(または新規作成)します。 |
+| `session.brief_get` | viewer | `brief_key` でブリーフを読み込みます。指定がなければ、セッションが最後に書いた最新のブリーフ(`from_session`)、それもなければ `project` の最新のブリーフを読み込みます。 |
+| `session.brief_list` | viewer | 名前空間のブリーフを新しい順に 1 行ずつ一覧表示します(呼び出し元のものだけにするには `mine_only`)。 |
+| `session.brief_delete` | writer | 書き込んだ本人が削除を求めたときに、ブリーフを削除します。 |
+
+**アドレス指定。** `brief_key` が空の場合は `auto//` になるため、同じ作業の流れにあるすべてのセッションが同じブリーフを更新します。project と branch のどちらも分からない場合は `session/` になります。キーは `^[A-Za-z0-9][A-Za-z0-9_.:/@+-]{0,159}$` に一致する必要があります。1 ユーザー(またはセッション)に限定されたトークンは、ブリーフを `~~`(または `~~~`)として保存し、`` として参照します。名前空間全体を対象とするトークンは、そのプレフィックス付きでブリーフを一覧表示でき、同じ形式で取得や削除もできます。限定されたトークンは `~` を含むキーを送信できません。
+
+**更新。** `events`(種類は `user`、`assistant`、`edit`、`command`、`error`、`read`、`search`、`tool`、`note`、`summary`。1 回の呼び出しで最大 4,000 件)を指定した保存は、サーバー側で要約されます。`LOOM_SESSION_BRIEF_LLM` が有効(デフォルト)の場合、`LOOM_SESSION_BRIEF_LLM_MODEL` で指定したモデルが、`LOOM_SESSION_BRIEF_WINDOW_CHARS` 文字のウィンドウごとに 1 回ブリーフを更新します。1 回の保存で処理するウィンドウは最大 `LOOM_SESSION_BRIEF_MAX_WINDOWS` 個です。そのモデルのキーがない場合はデプロイの LLM が書き込み、LLM がまったくない場合は決定論的ビルダーが目標、ステータス、ファイル、エラー、参照先を書き込みます(決定事項と行き止まりは含まれません)。レスポンスの `author` は `llm`、`deterministic`、`model`(呼び出したエージェントがセクションを書いた場合)のいずれかです。オペレーターの[抽出ポリシー](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/extraction.md#operator-extraction-policy)がある場合、ビルダーは実行されず、events からクライアントの要約も取得されません。モデル呼び出しが失敗したウィンドウはスキップされ、残りのウィンドウは更新されます。events だけの保存で呼び出せるモデルがない場合(未設定、`use_llm: false`、または最初のウィンドウを更新する前に組織のモデル呼び出しが無効化された場合)、何も書き込まず、`changed: false`、`reason: "not-revised"` を返します。一部のウィンドウを更新した後に組織が無効化された場合は、更新済みのウィンドウは残り、それ以降の更新は行われません。events だけの保存で、すべてのモデル呼び出しが失敗した、未読のスイッチで保留された、または解析できなかった場合は、クライアントが再送できるよう 503 で拒否されます。エージェントの `sections` も一緒に送る保存は、どちらの場合も既存のブリーフにそれらを上書きして書き込み、events からは何も取り込みません。
+状態セクションは更新のたびに置き換えられます。決定事項、行き止まり、完了した項目は蓄積されます。すべてのリビジョンは `loom.session_brief_revisions` に保持され、`brief_get` の `revision=N` で 1 つを読み取れます。前回の保存と同じセッションおよび `event_cursor` を繰り返す保存は再試行とみなされ、何も書き込みません。`if_revision` を指定すると、保存は compare-and-set になります(不一致の場合は 409)。
+
+**復元は本人の選択です。** コーディングプラグインは、コンパクション時とセッション終了時に、クライアント側のモデルトークンを使わずにブリーフを保存します。セッション開始時のプライマーは、保存済みのブリーフの名前を示すだけです。ブリーフの読み込みは、本人が `loom-session` スキルまたはダッシュボードの Conversations ページのブリーフセクションから求めたときに行われます。`brief_get(full=true)` は、クライアント自身の最後のコンパクション要約を、ブリーフの下にそのまま追加します。ブリーフが自動で読み込まれることはありません。どの作業の流れを再開するのかは、本人だけが知っているためです。
+
+
+
+## 例
+
+Python SDK の `Session` は、これらの op を 1 つの `(user, session)` スコープに結び付けます。`append` はターンをトランスクリプトに書き込み、`flush_every` ターンごとに `memory.set_from_messages` にも書き込みます。`resume` は、そのスコープに対する `context.pack` にトランスクリプトの末尾を加えたものです。
+
+```python
+from loom import Agent
+
+async with Agent("dev", "local", "support-bot", base_url="http://localhost:7777") as bot:
+ s = bot.session("thread-42", user_id="u1")
+ resumed = await s.resume(query="resume the billing migration")
+ await s.append(
+ {"role": "user", "content": "We moved invoices to the new ledger."},
+ {"role": "assistant", "content": "Noted; I'll update the export job."},
+ )
+ print(s.transcript_stored) # False when the namespace does not record
+ await s.close() # flushes the buffered turns to extraction
+
+ await bot.briefs.save(
+ project="billing",
+ branch="ledger-move",
+ sections={
+ "goal": "Move invoices to the new ledger",
+ "next_steps": ["Update the export job"],
+ },
+ )
+```
+
+`close()` 時の抽出でファクトを見つけるには、実際の LLM プロバイダーが必要です。標準のフェイクプロバイダーでも、ターンは記録されます。
+
+
+
+## 設定
+
+| 設定 | 効果 |
+| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `LOOM_CONVERSATION_SEARCH_MIN_SIMILARITY` | `conversation.search` のコサイン類似度の下限([ナレッジ → 会話](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#conversations))。 |
+| `LOOM_CONVERSATION_SEARCH_EXCERPT_CHARS` | 検索ヒットや保存済みメッセージの一覧に、ターンのどこまでを表示するか。即時に反映されます([ナレッジ → 会話](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#conversations))。 |
+| `LOOM_CONVERSATION_TITLER_*` | タイトル生成ワーカーのオン/オフ、実行間隔、対象ウィンドウ、1 回あたりの上限([ナレッジ → 会話](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#conversations))。 |
+| `LOOM_RETENTION_CONVERSATIONS_DAYS`, `LOOM_TIERING_CONVERSATIONS_WARM_DAYS` | トランスクリプトに対する、オプトイン方式の TTL とウォームボリュームへの移動([保持](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#retention)、[ストレージティアリング](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#storage-tiering))。 |
+| `LOOM_SESSION_BRIEF_LLM`, `…_LLM_MODEL`, `…_WINDOW_CHARS`, `…_MAX_WINDOWS` | ブリーフをどのように要約するか([コンテキスト](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#context))。 |
+| `LOOM_MCP_SESSION_RUN_IDLE_SECONDS` | 呼び出しがないまま、この時間が経過すると、MCP セッションの暗黙の実行を終了します([MCP](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#mcp))。 |
+
+
+
+## 制限事項
+
+- **「追記したのに何も残っていない。」** 名前空間で記録がオフになっています。この場合、追記は `stored: false` を返します。`conversation.set_logging` でオンにしてください。
+- **トランスクリプトはマイニングされません。** 記録されたターンが自動的にメモリになることはありません。
+- **`conversation.search` はベクトル検索が優先されます。** エンベディングが捉えない正確な文言は、順位が低くなることがあります。`memory.recall` は、抽出が読み取ったターンに対して、字句検索と時間窓での読み取りを行います。
+- **ブリーフには上限があります。** レンダリングされたブリーフは約 12,000 文字未満に収まります。各リストセクションにも上限があり(たとえば決定事項は 20 件、行き止まりは 12 件、次のステップは 8 件)、古い項目は削除されていきます。
+- **ブリーフはロックではありません。** 同じブランチ上の 2 つのセッションは、同じブリーフを改訂します。これらが交互に混ざってはならない場合は、`if_revision` を渡してください。
+
+
+
+## 関連ドキュメント
+
+- [抽出](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/extraction.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/runs.md) — セッションの書き込みと観測が加わる実行台帳です。
+- [統合検索](https://github.com/ClickHouse/loom/blob/main/docs/features/unified-search.md) — `loom_search` の会話セクションです。
+- [トレースと再開](https://github.com/ClickHouse/loom/blob/main/docs/guides/trace-and-resume.md) — 長時間の実行を再開します。
+- [メモリアーキテクチャ](../architecture/memory-architecture.md) — 会話テーブルとブリーフテーブルを内部から解説します。
diff --git a/i18n/.pending/ja/docs/features/entity-graph.md b/i18n/.pending/ja/docs/features/entity-graph.md
new file mode 100644
index 0000000000..bb2e7ca9c3
--- /dev/null
+++ b/i18n/.pending/ja/docs/features/entity-graph.md
@@ -0,0 +1,188 @@
+
+> このページは[英語の原文](https://github.com/ClickHouse/loom/blob/main/docs/features/entity-graph.md)の機械翻訳です。内容は英語の原文が優先されます。
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/features/entity-graph.md), which is authoritative.
+
+
+
+# エンティティグラフ
+
+Loom は、メモリの行と同じ ClickHouse データベース内に、メモリの行と並べてエンティティグラフを保持します。エンティティがノードです。同じメモリの中で言及された 2 つのエンティティは、共起エッジでつながります。抽出処理は、型付きの `(subject, relation, object)` トリプルを 2 つ目のエッジ集合として追加します。グラフはメモリの射影であり、すべてのエッジは、それを生成した行にさかのぼれます。「billing service につながっているものは何か」のように、ベクトル検索では答えられない問いに使います。
+
+エンティティコミュニティはデフォルトでは無効です(`LOOM_ENTITY_COMMUNITIES_ENABLED`)。
+
+
+
+## グラフが保持するもの
+
+| テーブル | 保持するもの |
+| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `loom.entity_edges` (+ `entity_edge_memories`, `entity_edge_rows`) | 共起の観測ごとに 1 行(`co_occur = 1`)。読み取り側がペアごとに合計します。ペアごとのソースキーと、それを挙げた行および値を保持します。 |
+| `loom.entity_triples` (+ `entity_triple_memories`, `entity_triple_rows`) | `confidence` と、`adapter_name` としての抽出モデルを持つ型付きトリプル。トリプルごとのソースキーと、それを述べた行および値を保持します。 |
+| `loom.entity_degree` | 各エンティティの共起次数の合計(`SummingMergeTree`)。ハブルールがこれを読み取ります。 |
+| `loom.entity_canonical_map` | メンションのテキスト → 正規エンティティ。 |
+| `loom.entity_communities` | レベルごと、エンティティごとのコミュニティ ID。 |
+| `loom.entity_vectors`, `loom.entity_summaries` | 検索のエンティティ系統が読み取る埋め込み。 |
+| `loom.derived_facts` | 単位と日付を持つ数値ファクト。検索での計算による回答に使います。 |
+| `memory.link` edges | エージェントまたは人が明示するエッジ(`supports`、`depends_on`、`caused` など)。グラフモードの検索が読み取ります。 |
+
+エッジとトリプルは、`valid_from` / `valid_to`(ソースとなるメモリの `valid_at` / `valid_to` に由来)と、それらを無効化する `invalid_at` スタンプを持ちます。`as_of` を指定した読み取りでは、その時点で有効な観測だけを合計します。
+
+グラフを ClickHouse に置いているのは、エッジを対応する行と同じリクエストで書き込み、同じ saga で消去し、ネットワークを介さずにメモリと結合できるようにするためです。その代償として、ウォークは上限付きの集計クエリの連続になるため、すべてのウォークに上限が設けられています。
+
+
+
+## グラフの構築方法
+
+最初にメモリ行が書き込まれ、グラフの行はそのメモリ行からの射影です。射影に失敗した場合は `loom.memory_projection_failures` に記録され、行が射影に失敗した値を保持している間に限り再試行されます。書き込み自体が失敗することはありません。感度が `high` のバルクエントリは何も射影しません。感度が `high` の `memory.set` は、書き込み側が宣言したエンティティのエッジのみを射影し、テキストは射影しません。
+
+1. **エンティティ。** 書き込み側が `memory.set` で `entities` を渡すか、`memory.set_from_messages` がエンティティを抽出します。`entity_extractor` ワーカー(`LOOM_ENTITY_EXTRACT_ENABLED`、デフォルトで有効)は、エンティティなしで書き込まれた行に、書き込みパスの外でタグを付けます。このワーカーには実際の LLM プロバイダーが必要です。エンティティのテキストは、書き込み時と読み取り時で同じ方法で正規化されます(冠詞と所有格を除去し、主要名詞を単数形にし、一人称を `user` に対応付けます)。そのため、"The Billing Service's" と "billing service" は 1 つのノードになります。`commit:` や `error:` という名前は識別子であり、同じ方法で正規化されますが、単数形化はされません。`error:Timeouts`、またはバッククォートや引用符で囲んだ同じ名前は、ノード `error:timeouts` になります。コロンの直後が空白またはマークアップの場合(`Error: the build failed`、``error:`Timeouts` ``)は、通常の文章として扱われます。代名詞、感動詞、軽動詞、2 文字のトークンは除外されます。書かれたままの状態、または正規化後(NFKC は `fi` を `fi` にします)に 256 文字を超えるテキストも、書き込み時と `entity_filter` で除外されます。ポイント書き込みでは、そのようなファクトの主語または目的語は拒否されます。
+2. **エッジ。** メモリのエンティティの全ペアが 1 件のオブザベーション行になります。1 メモリあたり最大 100 ペアです。
+3. **トリプル。** 抽出されたファクトのリレーションがトリプルになります。1 メモリあたり最大 8 件です。動詞は `lower_snake` に正規化されます。`namespace.register_ontology`(管理者用)は、推奨するエンティティタイプ、動詞、属性を、カーディナリティとともに登録します。この集合に含まれない名前は `ontology_warnings` を生成しますが、拒否されることはありません。
+4. **置き換えによるトリプルのクローズ。** ある行が別の行を置き換えると、古い行のオープンなトリプルのうち、新しい行が裏付けていないものに `invalid_at` が設定されます。`one` リレーション(勤務先、所在地)では、新しい値が現行のまま残り、古い値は新しい値の開始時にクローズされます。このクローズの実行中に古い値を再度述べる書き込みがあった場合、その値はオープンのままになります。
+ - 値は開始日で順序付けられ(日付のない値は到着時に開始します)、同じ日ならマイクロ秒単位の到着順で決まります。これにより、競合する書き込み側同士でも現行値が 1 つに定まります。1 回の書き込み内では、後から述べられた値の方が新しい値です。
+ - 1 回の書き込み内では、過去形の日付なしの値(`lived_in`、`worked_at`)は、日付付きの値より古いものとして扱われます。順序は問いません。10 月 1 日からの Paris と並んだ "user lived_in london" では、Paris が現行のままです。
+ - 値は最新の行で判定されます。"London from Oct 15, Paris from Oct 14, London from Oct 13" では London が現行のままです。
+ - 自身の終了日付きで述べられた値("London until December")は、早期にクローズされることはありません。その終了日まで、新しい値と並んで現行のままです。
+ - Undo(`memory.restore`)は、復元された値を、復元時点から、またはファクト自身の後の開始日("moving to Berlin on Dec 1")から現行にします。もう一方の値はクローズされますが、その行は有効なままです。後の日付の値は引き続き優先され、Undo の後に述べられた値も同様です。Undo を行き来しても重みは増えません。
+ - 失敗したクローズは、それを引き起こした書き込みまたは Undo の時点を基準に再実行されるため、その後に述べられた値は現行のまま残ります。
+
+ Undo がファクトとエッジをどのように再度述べ、重み付けし、再実行されるかについては、[メモリアーキテクチャ](../architecture/memory-architecture.md#undo)を参照してください。
+
+ポイント書き込み(`memory.set`、`memory.update`、`memory.update_by_id`)は、呼び出し元が `relations` で渡したトリプル(最大 8 件)を、HTTP と SDK の型付き操作で書き込みます(MCP の一覧にはありません)。抽出は行いません。自動抽出はバルクパスで実行されます。`memory.set_from_messages`、またはリレーションを供給するバルク書き込み側が対象です。標準のフェイクプロバイダーでは、渡したエンティティだけがエッジを形成します。
+
+
+
+## オペレーション
+
+| オペレーション | ロール | 答える内容 |
+| ---------------------------- | ------ | ------------------------------------------------------------------------------------------------------------- |
+| `facts.list` | viewer | `subject`、`object`、`relation`(AND)または `entity`(どちらかの端)で絞り込んだトリプル。 |
+| `facts.related` | viewer | 1 つのエンティティと共起するエンティティ。強い順で、シードがどちら側にあるかも返す。 |
+| `facts.traverse` | viewer | シードから N ホップ先までの近傍。 |
+| `facts.path` | viewer | `max_hops` 以内での、2 つのエンティティ間の最短のエッジ連鎖。 |
+| `facts.expire_by_adapter` | admin | 1 つのエクストラクタが書き込んだトリプルを廃棄(tombstone)する。メモリは残る。 |
+| `memory.search`(graph モード) | viewer | `search_mode="graph"`:クエリのエンティティから 1 ホップ先にあるヒット([検索と質問](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/search-and-ask.md))。 |
+| `memory.related` | viewer | 指定したメモリとエンティティを共有するメモリ。 |
+| `memory.timeline` | viewer | あるエンティティのメモリを時系列に並べたもの(`entity=…`)。 |
+| `memory.backlinks` | viewer | ある行のエンティティを共有するメモリ。 |
+| `namespace.taxonomy` | viewer | 名前空間の上位エンティティ。計算済みの場合はコミュニティも返す。 |
+
+フィールド一覧:[ファクト](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/facts.md)、[メモリ](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/memory.md)。graph モード以外では、`entity_filter` が指定したエンティティに関する行をブーストし、検索のエンティティレッグが、クエリ内で別の言葉で言及されたエンティティに関する行を見つけます([検索とランキング](https://github.com/ClickHouse/loom/blob/main/docs/concepts/retrieval-and-ranking.md))。
+
+
+
+### `facts.list`
+
+フィルタなしの場合、`co_occur` が上位のトリプルを返します。`sort_by="recency"` は `last_seen` で並べ替えます。
+
+| フィールド | 効果 |
+| ----------------------- | ---------------------------------------------------------------------------------------------------- |
+| `include_sources` | トリプルごとに最大 10 件程度のソースメモリキーを追加する。 |
+| `include_source_status` | 各ソース行を読み、トリプルが open なのに背後の行がすべて supersede 済みである場合に `stale` と印を付ける。 |
+| `provenance` | `extracted`(両端がソーステキストに含まれる)、`inferred`、または `facet`(Loom が生成したナビゲーション用エッジ)。 |
+| `as_of` | その時点で有効なトリプルだけを残す。 |
+
+
+
+### `facts.traverse`
+
+探索は展開の前に絞り込みます。各ホップはフロンティアを 1 つのクエリとして送り、有効期間内でペアごとの観測数を合計し、訪問済みのエンティティを除外して、各親につき最も強い `top_k_per_hop` 個のペアを残します。ホップ h のフロンティアは最大で K^h 個のエンティティです。各エンティティは、最初に到達したホップで、最も強い親を経由して 1 回だけ報告されるため、結果はツリーとして描画できます。
+
+すべてを展開してから後で絞り込む再帰クエリ 1 本では、近傍全体がマテリアライズされます。大きな名前空間では、3 ホップの探索が ClickHouse のメモリ上限を超えることがあります。ホップごとに絞り込むことで、コストは答えのサイズに抑えられます。
+
+| フィールド | デフォルト | 効果 |
+| ----------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `max_hops` | 2(1–4) | 探索の深さ。 |
+| `top_k_per_hop` | 20(最大 100) | ホップごとに親 1 つあたり残す子の数。 |
+| `min_co_occur` | 1 | ペアあたりの最小観測数。 |
+| `max_nodes` | 400(最大 5,000) | 厳密な上限。到達すると `truncated=true` になる。 |
+| `as_of` | 未設定 | その時点で有効な観測だけを残す。 |
+| `labeled` / `relations` | false / 未設定 | 型付きトリプルをたどる(すべて、またはこれらの動詞のみ)。ノードは `via_relation`、`via_direction`、`via_provenance` を持つ。 |
+| `hub_degree` | 0(オフ) | 総次数がこの値以上のノードをハブとする。 |
+| `hub_share` | `LOOM_FACTS_TRAVERSE_HUB_SHARE` (0.01) | そのノードに到達したエッジが、ノードの次数に占める割合がこの値以下の場合、そのノードをハブとする。 |
+| `rank_by` | `LOOM_FACTS_TRAVERSE_RANK_BY` (`cosine`) | ホップごとの絞り込み:`co_occur`、`specificity`(`via_co_occur / degree`)、または `cosine`(`via_co_occur / sqrt(degree)`)。 |
+
+各ノードは `hop`、`cumulative_weight`、`via_co_occur`、`path`(シードからの連鎖)、`valid_from` / `valid_to`、`degree` を報告し、コミュニティが存在する場合は `community_id` も報告します。ノードはホップ順、次に重み順に並びます。
+
+**ハブ。** 汎用的なエンティティ("user"、"pr")はあらゆるものと共起します。ハブは報告されます(`hub: true`、`hubs` に列挙)が、展開されません。シードは常に展開されるため、ハブの近傍を見るにはハブをシードにしてください。`hub_share` は名前空間の次数のスケールに依存しないため、デフォルトのルールになっています。`hub_degree` は名前空間ごとに固有の値です。設定する前に次数の分布の裾を確認してください。
+
+
+
+### `facts.path`
+
+同じエッジに対する、境界付きの双方向幅優先探索で、途中で出会います。`max_hops`(1–4、デフォルト 3)が全長の上限です。答えは `found`、`path`、`edges` で、各ペアの `co_occur` と有効期間を含みます。`truncated=true` は、答えが不完全な可能性があることを意味します。`found=false` かつ `truncated=false` は、`max_hops` 以内に接続がないことを意味します。
+
+
+
+## 例
+
+```python
+from loom import Agent
+
+async with Agent("dev", "local", "sre-bot", base_url="http://localhost:7777") as agent:
+ await agent.memory.set(
+ "billing/depends_on",
+ "The billing service reads invoices from the ledger database.",
+ entities=["billing service", "ledger database"],
+ )
+ walk = await agent.facts.traverse("billing service", max_hops=2, top_k_per_hop=10)
+ for node in walk["nodes"]:
+ print(node["hop"], " > ".join(node["path"]), node["via_co_occur"])
+
+ route = await agent.facts.path("billing service", "ledger outage")
+ print(route["found"], route["path"], route["truncated"])
+```
+
+HTTP では、過去の時点のグラフに対して探索を実行できます。
+
+```bash
+curl -s localhost:7777/v1/facts.traverse -H "Authorization: Bearer $LOOM_API_KEY" \
+ -H 'content-type: application/json' \
+ -d '{"org":"dev","namespace":"local","seed_entity":"billing service","max_hops":2,"as_of":"'"$AS_OF"'"}'
+```
+
+MCP では、`op="facts.traverse"` を指定して `loom_op` を呼び出します。
+
+
+
+## グラフの保守
+
+| タスク | 方法 |
+| ----------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| 不適切なエクストラクタのトリプルをロールバックする | `facts.expire_by_adapter(adapter_name=…, max_confidence=…)`。メモリは残ります。 |
+| グラフをエクスポートする | `loom entity-export --org O --namespace N --format graphml`(または `jsonld`。`--all` を指定すると無効化されたエッジも含まれます)。 |
+| エンティティをコミュニティにクラスタリングする | `LOOM_ENTITY_COMMUNITIES_ENABLED=true` を設定します(下記)。 |
+| グラフを表示する | ダッシュボードの Graph ビュー([ダッシュボード](https://github.com/ClickHouse/loom/blob/main/docs/features/dashboard.md))。 |
+
+`entity_communities` ワーカーは、名前空間ごとにラベル伝播を実行し、結果を `loom.entity_communities` に書き込みます。この結果は `namespace.taxonomy`、graph モードの拡張、`community_id` から参照されます。対象となるのは、統合(consolidation)が有効な名前空間と、直近の `LOOM_ENTITY_COMMUNITIES_WALKED_DAYS`(14)日以内にたどられた名前空間です。次数の高いエンティティから先に除外し(`LOOM_ENTITY_COMMUNITIES_HUB_DROP_FRACTION`)、1 つのコミュニティがエンティティの `LOOM_ENTITY_COMMUNITIES_GIANT_SHARE` を超える割合を占める間は、その割合を倍にしていきます。これにより、汎用的なトークンによってグラフが 1 つのコミュニティに融合することを防ぎます。
+
+
+
+## 設定
+
+| 設定 | セクション |
+| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `LOOM_FACTS_TRAVERSE_HUB_SHARE`, `…_RANK_BY` | [名前空間の健全性、ナレッジグラフ、コミュニティ](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#namespace-health-knowledge-graph-communities) |
+| `LOOM_ENTITY_COMMUNITIES_*` | 同じセクション。 |
+| `LOOM_ENTITY_EXTRACT_*` | [統合処理](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#consolidation) |
+| `LOOM_MEMORY_SEARCH_GRAPH_SEED` | [メモリ検索](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#memorysearch) |
+
+
+
+## 制限事項
+
+- **共起は関係ではありません。** 1 つのメモリに現れた 2 つのエンティティは、文の内容に関係なくリンクされます。関係が重要な場合は、型付きトリプル(`labeled`、`relations`)または `memory.link` を使用してください。
+- **グラフの品質はエンティティの品質に左右されます。** エンティティを持たない行は、`entity_extractor` ワーカーが処理するまでエッジを追加しません。
+- **探索には上限があります。** 2 つのエンティティが接続されていないと結論づける前に、`truncated` を確認してください。
+- **置き換えられた行に対して、エッジの更新が遅れることがあります。** `facts.list(include_source_status=true)` を使うと、まだオープンなトリプルを確認できます。
+- **有効性は有効時間(valid time)です。** `as_of` が読み取るのは事実が成り立っていた時点であり、Loom がその事実を知った時点ではありません。
+
+
+
+## 関連項目
+
+- [検索と質問](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/search-and-ask.md):グラフモード。
+- [メモリの書き込み](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/writing.md):`entities` の渡し方。
+- [抽出](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/extraction.md):抽出されたエンティティとトリプルの出どころ。
+- [メモリのアーキテクチャ](../architecture/memory-architecture.md):プロジェクションライター。
+- [ワーカーのリファレンス](https://github.com/ClickHouse/loom/blob/main/docs/reference/workers.md)。
diff --git a/i18n/.pending/ja/docs/features/memory/history-and-provenance.md b/i18n/.pending/ja/docs/features/memory/history-and-provenance.md
new file mode 100644
index 0000000000..406907ce89
--- /dev/null
+++ b/i18n/.pending/ja/docs/features/memory/history-and-provenance.md
@@ -0,0 +1,196 @@
+
+> このページは[英語の原文](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/history-and-provenance.md)の機械翻訳です。内容は英語の原文が優先されます。
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/history-and-provenance.md), which is authoritative.
+
+
+
+# 履歴と来歴
+
+メモリへの書き込みはすべて新しいバージョンを作成し、その場で編集されるものはありません。バージョンは追記専用のミラーに保持されるため、バックグラウンドのマージ後も事実の履歴は残ります。各行には、誰が書き込んだか、どのようにメモリに入ったかが記録されます。派生した行にはその元になったソースが記録され、ユーザーは行が正しいことを証明(アテスト)できます。バージョンミラーの仕組みについては、[メモリアーキテクチャ](../../architecture/memory-architecture.md)を参照してください。
+
+
+
+
+
+## 操作
+
+| 操作 | ロール | 内容 |
+| -------------------- | ------ | --------------------------------------------------------------------------------------------------------- |
+| `memory.history` | viewer | キーのすべてのバージョンを新しい順に返します。トゥームストーン化されたバージョンや秘匿化されたバージョンも含みます。 |
+| `memory.provenance` | viewer | 現行の行の出どころを返します。ソーストレース、書き込み者、ソースクラス、抽出元の会話です。 |
+| `memory.evidence` | viewer | ファクトの抽出元となったソースのターンを、裏付けとなる範囲と各リンクの作成方法とともに返します。 |
+| `memory.backlinks` | viewer | 行を指しているものを返します。バージョン、ダイジェスト、双方向の型付きリンク、エビデンス数、エンティティの近傍です。 |
+| `memory.lineage` | viewer | 共有メモリの昇格の経緯を返します。誰が、どの行から、どのレビューを経て昇格したかです。 |
+| `memory.verify` | writer | ログイン中のユーザーまたはサービスアカウントとして、行が正しいことを証明します。または証明を取り消します。 |
+| `memory.redact` | admin | 過去の1バージョンの値を消去します。行とその監査エントリは残ります。 |
+| `namespace.rollback` | admin | 名前空間内のすべてのメモリのヘッドを、ある時点のバージョンに戻します。 |
+| `namespace.snapshot` | admin | 名前空間のキュレート済みの状態を JSON ペイロードとしてエクスポートします。 |
+| `namespace.restore` | viewer | スナップショットを新しい名前空間、または呼び出し元が管理している既存の名前空間にインポートします。コレクションにはインポートできません。 |
+
+`namespace.snapshot` と `namespace.restore` は MCP ツールではありません。フィールドの一覧は、操作リファレンスの [メモリ](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md#memory) と [名前空間](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md#namespace) にあります。
+
+
+
+## バージョン: `memory.history`
+
+`loom.memory` は現在の状態を保持し、`FINAL` を付けて読み取るため、マージ後は各行の最新バージョンだけが残ります。`loom.memory_versions` は追記専用のミラーで、挿入のたびにマテリアライズドビューが書き込みます。`memory.history`、`memory.redact`、`namespace.rollback` が読み取るのはこの履歴です。
+
+履歴の行には `version`(書き込み時のナノ秒エポック)、`written_at`、`value`、`confidence`、`pinned`、`expires_at`、`tombstoned_at`、`redacted_at`、`redaction_reason`、`content_sha256`、`agent`、`actor`、`source_class` が含まれます。`created_at` はその行が最初に書き込まれた時刻で、すべてのバージョンで同じ値になります。`agent="*"` を指定すると、そのキーのすべての書き込み元を対象にします。
+
+```python
+from loom import Agent
+
+async with Agent(org="acme", namespace="support", agent="auditor") as agent:
+ for v in await agent.memory.history("customer/4812/plan", agent_id="*"):
+ print(v["written_at"], v["actor"], v["source_class"], v["value"])
+```
+
+トゥームストーンも 1 つのバージョンなので、削除は履歴に表示され、`memory.restore` で 14 日以内ならキーを復元できます。現在の状態を特定の時点で読み取るには、`memory.get`、`memory.search`、`memory.ask` の `as_of` を使います([有効時間](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/writing.md#validity-time-valid_at-and-valid_to))。
+
+
+
+## 誰が書いたか:actor と source class
+
+サーバーは、トークンと操作から、すべての行に `actor`(`human:` または `process:`)と `source_class` を記録します。`source_class` の値は[メモリの概念](https://github.com/ClickHouse/loom/blob/main/docs/concepts/memory.md)にあります。リクエストでは、クラスを `external`、`imported`、`derived` にダウングレードすることだけができます。
+
+`memory.provenance` は、この両方に加えて次の情報を返します。
+
+- `source_trace` と、そこから導出される `source_kind`(`conversation`、`extracted`、`observed`、`consolidated`、`app`、`manual`、`other`)
+- 書き込み側が引用した `source_resource_id`
+- 会話の `thread_id` と `thread_exists`(名前空間がトランスクリプトを記録しない場合、またはトランスクリプトが失われている場合は false)
+- その行に関係する、作成済みのリンク(`memory.link`)
+
+検索結果には `source_class` と `verified` が含まれます。これらは、オプションのトラスト項(`LOOM_MEMORY_SEARCH_TRUST_WEIGHT`)が参照します。
+
+
+
+## エビデンス:事実の出どころとなったターン
+
+抽出では、各事実を `loom.memory_belief_sources` 内のターンに紐づけます。`memory.evidence(memory_key)` は、それらのリンクを、ターンのテキスト(最大600文字)、ロール、時刻、裏付けとなる `span`、リンクの作成方法とともに返します。
+
+| `scope` | `support_type` | 意味 |
+| --------- | ----------------- | ------------------------------------------------------------ |
+| `cited` | `extracted_from` | 抽出器が裏付けとなるターンを指定した。 |
+| `lexical` | `lexical_support` | サーバーが事実を最も一致するターンに対応づけた。 |
+| `window` | `window` | 一致するものがなく、抽出ウィンドウ全体にリンクした。 |
+| `derived` | `derived_from` | 統合の系譜:アイテムは元のメモリのテキストである。 |
+
+レスポンスはスコープごとにリンク数を集計するため、引用された事実と、ゆるく紐づいた事実を区別して確認できます。会話の正確な文言を知りたい場合は、`memory.recall` が保存済みのターンを検索します([抽出](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/extraction.md))。
+
+
+
+## 系譜
+
+- `memory.consolidate` と期間ダイジェストは、ソースごとに 1 つの `derived_from` リンクを `loom.memory_belief_sources` に書き込みます。`memory.evidence` はそれらを `derived` アイテムとして返します。
+- セッションダイジェストは、圧縮したキーを一覧にします(`summary` ヒットの `derived_from`)。
+- `memory.lineage`(`scope="shared"`)は、共有メモリの昇格経緯をたどります。たどる内容は、イベント、昇格した主体、裏付けとなる行、一致する場合はその元になった learnings 候補(`match_confidence` は `exact` または `inferred`)、および監査イベントです。`mechanism` は `review`、`import`、`auto`、`unknown` のいずれかです。
+- `memory.backlinks` はその逆で、ある行を指しているものを返します。
+
+`memory.delete` は、すべてのソースが失われている統合サマリーを廃止し、ソースが残っているものは `conflicted` に降格します。
+
+
+
+## 証明:`memory.verify`
+
+`pinned` と `confidence` は、誰がそのファクトを確認したかを示しません。`memory.verify` はそれを記録します。記録されるのは、呼び出し元のトークンに含まれるアクターと、そのアクターが証明したコンテンツハッシュです。行は `memory_id` で指定するか、`namespace` と `memory_key` を書き込み側の ID とともに指定します。行の名前空間に対する writer 権限が必要です。
+
+`memory.get` と `memory.get_by_id` は `verification` を返します。これは、保存されているハッシュと行の現在のハッシュから導出されます。
+
+| `verification` | 意味 |
+| -------------- | ----------------------------------------------------------------- |
+| `human` | 人が証明し、その後コンテンツは変更されていません。 |
+| `process` | サービスアカウントが証明し、その後コンテンツは変更されていません。 |
+| `stale` | 誰かが証明しましたが、その後コンテンツが変更されています。 |
+| `none` | 一度も証明されていないか、取り消されています。 |
+
+- 編集しても証明はクリアされません。誰かが再検証するまで、証明は `stale` になります。
+- `revoke=true` を指定すると証明がクリアされます。同じアクターが変更のない行を再検証しても何も起こりません(`changed=false`)。
+- `human:` プレフィックスはトークンから決まるため、エージェントが自分の書き込みを human としてマークすることはできません。本文の `actor` が読み取られるのは、認証なしの dev モードのときだけです。
+- スナップショットとリストアには証明のカラムが含まれ、リストアで `verified_by` が取り除かれることはありません。
+
+
+
+## 履歴の消去:`memory.redact`
+
+`memory.redact(memory_id, version)` は、過去の 1 つのバージョンのテキストを、それがコピーされているすべての場所から消去します。あわせて、そのメモリからモデルが構築したすべてのプロファイルバージョンも消去します。`redacted_at` と `redaction_reason` を記録し、行とその監査エントリは残します。以前のバージョンに漏れたシークレットや個人情報に対して使用します。
+
+| 場所 | 動作 |
+| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `loom.memory`, `loom.memory_versions` | `value` は `"[REDACTED]"` になります。`value_json`、`evidence`、`entities`、`concepts` は消去されます。 |
+| `loom.memory_embeddings`, `loom.memory_chunks` | 抜粋またはチャンクのハッシュが現行ヘッドのものと異なる行は削除されます。現行ヘッドの行は残ります。 |
+| そのメモリから構築されたユーザーのプロファイルバージョン | トレースにそのメモリが含まれるすべてのバージョンが、現行ヘッドを含めて同じ方法で消去されます。そのキーの派生行も対象です。 |
+| `loom.shared`、キーから昇格されたコピー | `value` が消去対象のテキストであるすべてのバージョンが `"[REDACTED]"` になり、その検索行は削除されます。現行のコピーは、管理者が降格するまで昇格されたままです。 |
+
+対象外:タグ、ファイル、`content_sha256`、`loom.memory_evidence`(消去 (erasure) の管轄)、系統テーブル(ID とハッシュのみ)、エンティティグラフ。現行ヘッドも消去対象のテキストを保持している間(編集がバイト単位で元に戻された場合)、共有コピーはそのまま残されます。
+
+- メモリの現行ヘッドは拒否されます(`refused_head=true`)。先にキーを削除するか書き換えてください。消去された現行プロファイルは、ワーカーが再構築するまで、レンダリング、パック、プロファイル検索から除外されます。
+- どちらのロックモードでも拒否されます。これはメモリ自身のキーにも、到達するすべてのプロファイルキーにも当てはまります。
+- そのキー、または共有コピーのキーを引用していた、キャッシュ済みの `memory.ask` と `code.ask` の回答および先例を削除します(`cache_rows_deleted`、`precedent_rows_deleted`)。到達したプロファイルキーに対しては、削除は組織全体に及びます。すべてのユーザーのプロファイルが同じキーを持つため、そのキーをウィンドウに含んでいた組織内のすべてのキャッシュ済み回答と先例が、すべての名前空間で消去されます。
+- 名前空間は取得後に検査されます。拒否された場合は 403 ではなく `redacted=false` が返されます。
+- 存在しないバージョンに対しては `redacted=false` が返され、何も消去されません。プロファイルバージョンも対象外です。
+- 2 つのメモリテーブル(および、コピーがまだそのテキストを保持している場合は `loom.shared`)に対して同期的な `ALTER TABLE … UPDATE` を実行し、派生行に対して軽量な `DELETE` を実行します。これは管理用の呼び出しです。
+
+共有コピーの消去と競合する書き込み:
+
+- 埋め込みワーカーがパージ後に書き込む検索行は、パージ前に読み取ったスタブに由来する場合、そのキーの次回の redact まで残ります。
+- キーの昇格は、再度昇格されるまで検索行を失います。
+- スクラブ前にコピーを読み取った降格は、テキストを含むトンブストーンを書き込み、そのバージョンが再度 redact されるまで残ります。
+
+後続のキーの昇格によって置き換えられ、その後 `loom.shared` でマージされて消えたコピーは、もう見つかりません。`FINAL` がもう提供しないその検索行は、そのキーの後続のパージまで残り、消去対象以外のキーのもとにあるキャッシュ済みの回答は、期限切れになるまで残ります。
+
+値が `"[REDACTED]"` のコピーは、以前の redact で消去されたものとして扱われます。そのため、そのテキスト自体を保持していて昇格されたメモリは、そのキーの次回の redact で検索行を失います。
+
+プロファイルへの到達範囲とその制限は、[セキュリティ](https://github.com/ClickHouse/loom/blob/main/docs/architecture/security.md#sensitivity)を参照してください。個人のデータをすべての場所から削除するには、[消去 (erasure)](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/retention-and-erasure.md#erasure)を使用してください。
+
+
+
+## 名前空間のロールバック:`namespace.rollback`
+
+`namespace.rollback(as_of)` は、キーごとに `as_of` 以前の最も高いバージョンを新しいヘッドとして再挿入し、それ以降に作成されたキーには廃棄マーカー(tombstone)を付けます。ロールバック自体が新しいバージョンとして記録されるため、同じ方法で元に戻せます。
+
+- デフォルトはドライランで、`reinstate`、`remove`、`sample` を報告します。`dry_run=false` を指定すると適用されます。
+- `memory_keys`(最大 500)で対象を絞り込めます。`max_keys`(デフォルトは 5,000)は 1 回の呼び出しの上限で、`truncated` が返された場合は再度呼び出してください。
+- `embedding_worker` が、復元されたヘッドを再埋め込みします。
+- 名前空間の履歴より古い、または未来の `as_of` は拒否されます。
+
+```bash
+curl -sX POST http://localhost:7777/v1/namespace.rollback \
+ -H "Authorization: Bearer $LOOM_API_KEY" -H 'Content-Type: application/json' \
+ -d '{"org":"dev","namespace":"local","as_of":"T09:00:00Z"}' \
+ | jq '{reinstate, remove, truncated, sample}'
+```
+
+
+
+## スナップショット:`namespace.snapshot` と `namespace.restore`
+
+`namespace.snapshot` は、名前空間のキュレーション済みの状態を JSON としてエクスポートします。対象は、`version`、`content_sha256`、`actor`、`source_class`、有効期間および証明(attestation)の各列を持つすべてのメモリ行、型ごとの設定、グラント、そして直近の監査行(最大 `include_audit_tail_n` 件、デフォルトは 1,000)です。`include_embeddings` はデフォルトで false のため、ターゲット側では自身のモデルで再埋め込みを行います。
+
+`namespace.restore(target_namespace, payload)` は、ペイロードをバージョン行として書き戻します。`snapshot_id` に対して冪等です(再実行すると `restored=false` が返ります)。復元先は、新規の名前空間(呼び出し元が admin になります。行を持たないものの、すでにデータやグラントを保持している名前は、呼び出し元がすでに管理している場合を除き拒否されます)、または呼び出し元が管理している名前空間です。`rebind_agent` は、すべての行の書き込み元を再割り当てします。復元された行は `imported` になります。
+
+スナップショットはデプロイメントのバックアップではありません。詳しくは[バックアップとリカバリ](https://github.com/ClickHouse/loom/blob/main/docs/operations/backup-and-recovery.md)を参照してください。
+
+
+
+## 監査ログ
+
+メモリを作成または変更するすべての書き込みは、`loom.audit_log` にハッシュのみの行を 1 行残します(キー、ID、コンテンツハッシュ、アクター、ソースクラス、判定。値そのものは記録しません)。1 時間ごとのチェックポイントがログを連鎖させます。詳細は [監査](https://github.com/ClickHouse/loom/blob/main/docs/features/observability/audit.md) を参照してください。
+
+
+
+## 制限事項
+
+- **マージされて残らなくなったバージョンの墨消しはベストエフォートです**(`loom.memory`)。ミラーはどちらの場合でも消去されます。
+- **履歴はミラーと同じ範囲までしか完全になりません。** `loom.memory` にカラムを追加する場合は、同じマイグレーションで `loom.memory_versions` とそのビューにも追加する必要があります。
+- **有効性は有効時間(valid-time)のみです。** `knowledge_time` は、無効化(`invalid_at`)と削除(`tombstoned_at`)のスタンプに対して `created_at` を再生します。トランザクション時間用の別テーブルはありません。
+- **`thread_exists=false` はエラーではありません。**
+- **ロールバックしても、完全に削除されたキーは復元されません**(`skipped_no_head`)。
+
+
+
+## 関連ドキュメント
+
+- [メモリの書き込み](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/retention-and-erasure.md)
+- [監査](https://github.com/ClickHouse/loom/blob/main/docs/features/observability/audit.md)
diff --git a/i18n/.pending/ja/docs/features/memory/retention-and-erasure.md b/i18n/.pending/ja/docs/features/memory/retention-and-erasure.md
new file mode 100644
index 0000000000..4609789472
--- /dev/null
+++ b/i18n/.pending/ja/docs/features/memory/retention-and-erasure.md
@@ -0,0 +1,252 @@
+
+> このページは[英語の原文](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/retention-and-erasure.md)の機械翻訳です。内容は英語の原文が優先されます。
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/retention-and-erasure.md), which is authoritative.
+
+
+
+# 保持と消去
+
+Loom は、書き込んだ本人、名前空間の所有者、またはオペレーターが求めない限り、メモリを削除しません。メモリにはデフォルトの保存期間がありません。データが削除される経路は 3 つあります。書き込んだ本人による有効期限の設定または削除、所有者やオペレーターが設定した保持ポリシー、そして Loom が保持しているあらゆる場所からスコープを取り除く消去です。
+
+
+
+## 何がどれだけ保持されるか
+
+`schemas/schema.sql` では、メモリ、埋め込み、バージョン履歴、会話、エンティティ、サマリー、ワーキングメモリ、ナレッジの各テーブルに TTL はなく、行を経過時間で削除するワーカーもありません。リンクテーブルの `entity_triple_rows` と `entity_edge_rows` は `entity_triples` と `entity_edges` に従い、TTL はありません。消去(erasure)は、消去対象のメモリのリンクを削除します。古いビルドの消去が残した孤立リンクは `loom erasure-re-verify --completed-since … --resume` で削除します。
+行が提供対象から外れるのは、次の場合のみです。
+
+- **書き込み側が削除した場合**:`memory.delete`、同じキーの上書きによる置き換え、`memory.apply`、`memory.clear`、`conflicts.resolve`、`blacklist.add(sweep=true)`。
+- **書き込み側が有効期限を設定した場合**:`memory.set`、`memory.touch`、`run.complete(retain="expire")` の `ttl_seconds` または `valid_to`、およびリフレクションの `expires_in_days`。
+- **オーナーまたはオペレーターが設定した場合**:[設定による保持](#configured-retention)を参照してください。
+
+運用テーブル(テレメトリ、キャッシュ、キュー)には固定の TTL があります。`loom.search_trace_log` と `loom.memory_exposures` は 180 日、`loom.erasure_requests` と `loom.policy_decisions` は 90 日、`loom.memory_drops`、`loom.memory_extraction_queue`、`loom.events`、`loom.embedding_cache` は 30 日、`loom.llm_response_cache` は 7 日です。各テーブルの TTL は[スキーマリファレンス](https://github.com/ClickHouse/loom/blob/main/docs/reference/schema.md)に一覧があります。
+
+タイマーでデータを削除するワーカーは 1 つだけです。`namespace_gc` は、`kind = 'bench'`(自動登録時に `LOOM_NAMESPACE_BENCH_PREFIXES` で照合)の名前空間のうち、`LOOM_NAMESPACE_GC_IDLE_HOURS` の間書き込みがないものを、消去サガ経由で削除します。他の kind には一切触れません。[名前空間と共有](https://github.com/ClickHouse/loom/blob/main/docs/features/namespaces-and-sharing.md)を参照してください。
+
+
+
+### 削除は消去ではない
+
+トゥームストーン(tombstone)は、`tombstoned_at` が設定された新しいバージョンです。読み取りはただちにその行を返さなくなりますが、その行と `loom.memory_versions` にある過去のバージョンはディスク上に残ります。
+
+- `memory.restore` は、トゥームストーン化されたキーを 14 日以内であれば復元します(それ以降は `expired=true` を返します)。自動的な置き換え(supersession)も元に戻せます。
+- `memory.clear`(admin)は、名前空間内のエージェントまたはユーザーのメモリをすべてトゥームストーン化します。`confirm_subject` には具体的な `user_id` または `agent` を再度指定する必要があります(`'*'` も `'-'` も確認として扱われません)。`user_id` を指定した `agent="*"` は、そのユーザーの行をすべてのエージェントにわたって消去し、`agent` を指定した `user_id="*"` は、そのエージェントの行をすべてのユーザーにわたって消去します。名前空間全体の消去と同様に、`'-'` 以外に誰も指定しないスコープは拒否されます。ロックされた行は残り、`locked_skipped` に数えられます。消去されたキーも同じ方法で復元できます。
+
+バイト列そのものを削除するには、[消去(erasure)](#erasure)を使います。行と監査証跡は残したまま 1 つの値だけを取り除くには、[`memory.redact`](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/history-and-provenance.md#scrubbing-history-memoryredact)を使います。
+
+
+
+### 書き込み側が設定する有効期限
+
+行は `expires_at` を過ぎた瞬間から読み取りで非表示になります。その後、`memory_expiry_sweep` ワーカーが、書き込み側の `on_expire` を新しいバージョンとして適用します。
+
+| `on_expire` | 効果 |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `tombstone`(デフォルト) | トゥームストーン化されます。14 日間の復元期間があります。 |
+| `demote` | 有効期限が解除され、信頼度が `LOOM_MEMORY_EXPIRY_DEMOTE_FACTOR`(0.5)倍されます。ただし `LOOM_MEMORY_EXPIRY_DEMOTE_FLOOR`(0.05)を下回りません。 |
+| `anonymize` | 値がマーカーに置き換えられ、埋め込みが削除されます。行は存在した証拠として残ります。 |
+
+`memory.touch` は行の有効期限だけを変更します。対象は 1 つのキー、または最大 1,000 件(`memory_keys`)で、新しい `ttl_seconds`、`clear_expiry=true`、新しい `on_expire` を指定できます。`memory.sweep_expired`(admin)は、名前空間に対してスイープを 1 回、オンデマンドで実行します(`dry_run` 指定可)。他のフィールドを編集しても、有効な有効期限は維持されます。
+
+
+
+### 設定による保持
+
+すべてデフォルトでは無効です(0 = 永久に保持)。
+
+| 対象 | 設定方法 | 効果 |
+| ---------------------------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 名前空間内のメモリタイプ | `namespace.register` の `tag_registry` エントリの `retention_days` | 有効な有効期限、`ttl_seconds`、`clear_expiry` のいずれも指定せずに `memory.set` が書き込んだ行は `expires_at = now + N days` になります。再度書き込まれた `read_only` 行には設定されません。 |
+| 機密性の高い行 | `LOOM_MEMORY_SENSITIVE_RETENTION_DAYS`、`LOOM_MEMORY_SENSITIVE_ON_EXPIRE`(デフォルトは `anonymize`) | 新しい `medium` / `high` 機密度の行に有効期限が設定されます。呼び出し側の有効期限のほうが短い場合は、そちらが優先されます。 |
+| 実行(run)自身の書き込み | `LOOM_MEMORY_RUN_COMPLETE_RETAIN`(`keep`、`demote`、`expire`)、`LOOM_MEMORY_RUN_COMPLETE_EXPIRE_DAYS`(7) | 呼び出しで指定がない場合に、`run.complete` が実行の行に対して行う処理です。固定(pinned)、検証済み、昇格済み、ロック済み、エピソード、リフレクションの各行は常に保持されます。 |
+| 名前空間全体 | `namespace.register` の `retention_days`、`warm_days` | その名前空間の行に対するテーブル TTL(およびウォームティアへの移動)です。 |
+| デプロイメント | `LOOM_RETENTION_
`、名前空間スコープのドキュメントバケットについては `objects.document_originals`、プロバイダー再構築のコピー全体の合計については `provider_rebuild_copies`(存在しなければ 0。コピーに org 列がない場合はデプロイメント全体で数えます)。カウントは、このスコープでセンサスが残存物として数える行です。有効な行、またはサガがパージする場合やテーブルがトゥームストーンを保持しない場合はすべての行です([センサスのルール](../../architecture/memory-architecture.md#erasure-saga))。`objects.document_originals` は最初の一覧ページを数えるため、「少なくとも」として読みます。
+- `purge`:スコープの削除かトゥームストーンかのモード(単一の名前空間では、要求にかかわらずトゥームストーン)。ミラーを持つスコープ([ドキュメントソース](https://github.com/ClickHouse/loom/blob/main/docs/architecture/document-sources.md#the-mirror))は、この値にかかわらず削除されます。パージなしでは、トゥームストーンにされた行はテーブルがマージされるまでパート内にバイト列を保持します。パージありでは行は削除され、そのバイト列はマージまたはリクレイムワーカーが取り除くまでディスク上に残ります。
+- 対象と時刻は、ステータスの `org`、`scope_type`、`scope_value`、`verified_at` です。
+
+レシートは Loom による集計です。応答は保管してください。`erasure.status` は、要求から 89 日間、台帳行を返します。センサスも含む `erasure.completed` 監査行は、completed の行の後にベストエフォートで書き込まれ、`LOOM_RETENTION_AUDIT_LOG_DAYS` の間保持されます。要求者が応答を受け取っていない場合(リカバリーワーカーが完了させたサガ、デタッチして実行したもの、タイムアウトした呼び出し)は、89 日以内に `erasure.status` を読んでください。
+
+
+
+#### 消去を自分で確認する
+
+`--namespaces '*'` または `--all` を付けた org の SQL サーフェスのグラントを持つオペレーターは([SQL サーフェス](https://github.com/ClickHouse/loom/blob/main/docs/reference/sql-surface.md#access))、センサスの 3 つのキー `loom.memory`、`loom.memory_versions`、`loom.conversations` を再集計し、リクエスト台帳(後述の 4 つ目のステートメント)を確認できます。消去された id とセンサスの時刻をパラメーターとしてバインドします。ClickHouse は、消去自身のステートメント(後述)と同様に、バインドされた値を `system.query_log` に書き込みます。そのため、確認は、プッシュダウンされたテキストが Postgres のステートメントログにもう 1 つのコピーとして残る `pg_clickhouse` 経由ではなく、`clickhouse-client` から実行してください。
+
+```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')};"
+```
+
+`org` フィルタは、複数の org を対象とする grant(`--all`)を、消去対象の org に絞り込みます。各ステートメントは、フィルタする前に grant のスコープ全体を読み取ります([読み取りのコスト](https://github.com/ClickHouse/loom/blob/main/docs/reference/sql-surface.md#what-a-read-costs))。そのため、大きな org や `--all` の grant では、ステートメントが SQL ユーザーの上限(`LOOM_CH_ANALYSIS_MAX_ROWS_TO_READ`、`_MAX_EXECUTION_S`)に達し、件数の代わりにエラーで止まることがあります。確認の間は上限を引き上げてください。名前空間スコープの場合は `--param_ns=''` を渡し、最初の 3 つのステートメントを `user_id` ではなく `namespace = {ns:String}` でフィルタします。`namespace_list` の場合は、`scope_value` の `namespaces` にある名前ごとに 1 回ずつ実行します。`sql_v1_agent_events` のステートメントはユーザースコープ専用です。名前空間の消去では、その名前空間のリクエスト台帳の行が残るためです。消去が完了していれば各件数は 0 になりますが、census との違いが次のようにあります。ビューは制限付きの名前空間を除外します。`sql_v1_memories` は rejected と tombstoned の行を除外し、`sql_v1_memory_history` は rejected のバージョンを除外します(tombstoned のものは残します)。また、ユーザーのメモリから統合された要約は別の `user_id` を持ち、census はそれを数えますが、これらのクエリは数えません。リクエスト台帳の件数は、レシートの外にある別の確認です。消去はユーザーのリクエスト台帳の行を削除せず、`` に書き換えます。リクエスト台帳のビューは自身のウィンドウ分しか保持しません([`sql_v1_agent_events`](https://github.com/ClickHouse/loom/blob/main/docs/reference/sql-surface.md#sql_v1_agent_events))。そのため、書き換えの確認はウィンドウ内の行に限られます。census のそれ以外のキーは、Loom 自身の件数だけです。
+
+レシートがカバーしないもの:
+
+- どちらのサービスについても、バックアップ、ポイントインタイムリカバリ、WAL、スタンバイ。
+- Loom の外で作られたコピー。たとえば、[SQL サーフェス](https://github.com/ClickHouse/loom/blob/main/docs/reference/sql-surface.md)から org 自身の Postgres に作ったテーブル。
+- census の後に、その前に行った読み取りに基づいてワーカーが書き込む行([ストレージの権限](../../architecture/storage-authority.md#erasure))。
+- 消去より前に取得したスナップショットからの `namespace.restore`。行が復元されます。消去をもう一度実行してください。そのときの census が新しいレシートになります。
+- ユーザースコープの場合、バケット内のドキュメントの原本。census が数えるのは名前空間スコープの場合だけです。
+
+消去した ID は、消去の証明に必要な場所に残ります。台帳の行(テーブルの TTL によってリクエストから 90 日後に削除されるまで)、audit、`loom.erasure_reversals`、そしてその ID を指定したステートメントに関するデプロイ自身のログです(ClickHouse のミューテーションログ、それを書き込んだステートメントについては `system.query_log` と `system.text_log`、`log_statement` または `log_min_duration_statement` が有効な場合は Postgres のステートメントログ)。
+
+
+
+### 放棄された saga
+
+5 回試行しても失敗した場合、ワーカーはそのリクエストを恒久的に `failed` とし、`failure_reason` と `steps_completed` を含む `erasure.abandoned` の audit 行を書き込みます。その後は人がエスカレーションする必要があります。`loom erasure-re-verify` は終了状態の saga を再確認します。`--resume` は失敗した saga をチェックポイントから再実行します(外部ステップが失敗し続ける `namespace_list` の saga には `--skip-external` を使います)。`--completed-since ` を指定すると、失敗したものの代わりに、その時刻以降に検証された完了済みの saga を再確認します。これは、アップグレード中に以前のビルドが実行した消去のためのものです。`--resume` と併用すると、孤立した行リンクだけを削除します([メンテナンス](https://github.com/ClickHouse/loom/blob/main/docs/operations/maintenance.md#erasure))。[トラブルシューティング](https://github.com/ClickHouse/loom/blob/main/docs/operations/troubleshooting.md)も参照してください。
+
+
+
+### オペレーション
+
+| Op | ロール | 内容 |
+| ----------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `erasure.request` | writer(対象の admin) | 1 つのスコープに対して saga を実行します。`urgency` は `normal` または `urgent`、ほかに `purge`、`external` があります。 |
+| `erasure.status` | viewer | 1 件のリクエストの状態、現在のステップ、失敗の理由、census。ユーザーの消去に答えるのは、その org の org admin または platform admin だけです。MCP のツールセットには載っていません。 |
+| `erasure.list` | viewer | 最近のリクエスト(`status` でフィルタ可能)。`steps_completed_count`、`reversals_count`、`residue_count` を含みます。 |
+| `erasure.export` | admin | 対象者のデータを JSON で出力します。`memory`、`knowledge`、`conversations`(トランスクリプトのターンと保存されたメッセージ)、`conversation_threads`、`agent_events`、`audit_log` を含み、それぞれ `section_limit`(デフォルト 10,000。超えると `truncated`)で上限が設けられ、`conversations` はさらに `LOOM_ERASURE_EXPORT_CONVERSATION_MAX_BYTES` 分のテキストに制限されます。デフォルトでは tombstoned の行も含みます。 |
+
+`erasure.status` と `erasure.list` は台帳の行を 89 日間読み取ります。テーブルの TTL は 90 日で削除します。フィールドの一覧は[オペレーションリファレンス](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md#erasure)を参照してください。
+
+
+
+### 例
+
+```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"])
+```
+
+SDK の `request` は `purge` と `external` を公開していません。これらは 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}'
+```
+
+
+
+### コントリビューター向け
+
+メモリのコンテンツを保持しうる新しいテーブルには、saga のステップと census のエントリ(`server/erasure/store/census.py` の `_CENSUS` 内の `Substrate(...)` 1 つ)が必要です。そうでない場合は、理由を添えて `STEP_ONLY_TABLES` に 1 行追加します。どちらもないと、ユニットテストが失敗します。saga は `server/erasure/app/saga.py`(`run_saga`)、バックエンドは `server/erasure/app/backends.py`、ワーカーは `server/erasure/workers/recovery.py` にあります。
+
+
+
+## 制限事項
+
+- **コンプライアンスの保証ではありません。** saga、census、監査ハッシュはエンジニアリング上のプリミティブであり、特定の義務を満たすかどうかはお客様の判断になります。
+- **消去には時間がかかります。** 各ステップはミューテーションの完了を待つため、大きなスコープでは数分を見込んでください。SDK は最初の応答を最大 120 秒待ちます。それ以降は `erasure.status` をポーリングしてください。
+- **`org` スコープはありません。** org の名前空間を消去するには `namespace_list` を使います。
+- **テーブル TTL からは復元できません。** ライフサイクルの終了を元に戻せるようにしたい場合は、`on_expire` を使った書き込み側の有効期限を使用してください。
+- **バックアップは saga の対象外です。** 詳しくは[バックアップとリカバリ](https://github.com/ClickHouse/loom/blob/main/docs/operations/backup-and-recovery.md)を参照してください。
+- **分析エクスポートのバケットは saga の対象外です。** 含まれるファイルは、ハッシュ化された org、名前空間、エージェントの名前と使用回数のみで、メモリの内容は含まれません。詳しくは[ハッシュ化された名前](https://github.com/ClickHouse/loom/blob/main/docs/operations/analytics-export.md#hashed-names)を参照してください。
+
+
+
+## 関連ドキュメント
+
+- [履歴と来歴](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/history-and-provenance.md):`memory.history`、`memory.redact`。
+- [メモリの書き込み](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/writing.md):書き込み時の `ttl_seconds`、`valid_to`、`on_expire`。
+- [実行](https://github.com/ClickHouse/loom/blob/main/docs/features/runs.md):`run.complete` の `retain`。
diff --git a/i18n/.pending/ja/docs/features/runs.md b/i18n/.pending/ja/docs/features/runs.md
new file mode 100644
index 0000000000..31474c2336
--- /dev/null
+++ b/i18n/.pending/ja/docs/features/runs.md
@@ -0,0 +1,190 @@
+
+> このページは[英語の原文](https://github.com/ClickHouse/loom/blob/main/docs/features/runs.md)の機械翻訳です。内容は英語の原文が優先されます。
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/features/runs.md), which is authoritative.
+
+
+
+# 実行(Runs)
+
+run とは、「issue 1234 をトリアージする」のような、タスクを 1 回実行することです。`run.begin` が run を開いて `run_id` を返します。エージェントはその id を書き込み(`memory.set`、`memory.update`、`observe.record`)に渡します。`run.complete` は、ステータス、エージェントが依拠したメモリ、および任意でリフレクションを指定して run を閉じます。読み取り(`memory.search`、`memory.ask`)でボディに `run_id` を指定すると、その run 自身の行に絞り込まれます。そのため、読み取りには別の方法でラベルを付けます。HTTP では `X-Loom-Run-Id` ヘッダー(Python SDK では `run_scope`)、MCP ではセッション自身の run を使います。成功した run が依拠したメモリは次回以降のランキングで上位になり、失敗した run が依拠したメモリは、それまでに得たブーストを失います。
+
+
+
+## run が記録する内容
+
+run の行は `loom.agent_runs` に保存されます。`run.get` が表示する内容の大半は、読み取り時に他のプレーンから導出されます。
+
+| フィールド | 保存または導出 | ソース |
+| ---------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `goal`, `user_request`, `model`, … | 保存 | `run.begin` |
+| `status`, `final_response` | 保存 | `run.complete`(それまでは `active`) |
+| `memories_used` | 保存 | `run.complete`:エージェント自身が、何に依拠したかを申告した内容 |
+| `grade`, `grade_source`, … | 保存 | `run.grade`(run の終了後) |
+| `memories_written` | 導出 | run の `run_id` を持つ `loom.memory` の行 |
+| `recalled`, `recalled_keys` | 導出 | `run_id` に紐づく検索トレースログと、`run.complete(recalled_keys)` の和集合 |
+| `observations` | 導出 | `run_id` が付与された、`observe.record` によるエピソード行 |
+| `turns`, `cost_usd` | 導出 | run が開いている間に行われたセッションのターンで、`loom.agent_turn_usage` にあるもの(Claude Code プラグイン、または `cost.record_turns` を使うエージェントが書き込みます) |
+| `budget_usd`, `budget_seconds` | 保存 | `run.begin`(0 = 予算なし) |
+| `elapsed_seconds`, `over_budget` | 導出 | run の開始から終了(または現在)までを、サーバーの時計で計測した値と `cost_usd` を、予算と比較して求めます |
+
+`LOOM_SEARCH_TRACE_LOG_ENABLED` が無効で、`recalled_keys` も送信されていない場合、`recalled` は `-1` になります。
+
+
+
+## 予算
+
+`run.begin` は、任意の `budget_usd`(モデルの支出)と `budget_seconds`(run にかけてよい時間)を受け取ります。`run.get` はこれらを `cost_usd` および `elapsed_seconds` と比較し、超過したものを `over_budget`(`cost`、`time`、またはその両方)に列挙します。Loom はエージェントを実行しないため、予算は実行する側へのシグナルであり、停止させるものではありません。
+
+run の支出は、その run が開いていた間にセッションで行われたターンを、各ターン自身の時刻(トランスクリプト由来の `turn_at`)で集計したものです。そのため `budget_usd` には `session_id` が必要です(ない場合は 422)。コストと同様に小数点以下 6 桁で保持されるので、最小値は $0.000001 です。時間は、クライアントが報告した `duration_ms` に関係なく、サーバーの時計で run の開始から終了までを測ります。予算は run の最初の `run.begin` で設定してください。
+
+セッションで予算超過のアクティブな run を最初に見つけた `run.get` は、メンターヒント `run_over_budget` も返します。プラグインはこれをアドバイスとしてモデルに渡します。終了した run でも `over_budget` は報告されますが、ヒントは付きません。他のメンターヒントと同様、ヒントはセッションごとに 1 回だけ伝えられ、セッションを送らない呼び出し元(SDK、素の HTTP)は名前空間とウェブプロセスごとに 1 つのセッションを共有します。そのため、判断にはヒントではなく `over_budget` を使ってください。
+
+制限事項:
+
+- **プロンプトの合間のみ。** Claude Code プラグインはプロンプトのターンをそのプロンプトの終了時に送信するため(エージェントは `cost.record_turns` で自分で送信することもできます)、コスト予算はプロンプトの合間にチェックされ、単一のヘッドレスプロンプト(`claude -p`)の支出は終了後にしか表示されません。それらのターンは、エージェント自身の `run.complete` の後に届いた場合でも集計されます。呼び出しのコストは戻った後にしか分からないため、run は何かが気づく前に、最後のターンのコスト分だけ `budget_usd` を超えることがあります。
+- **クライアントの時計。** この集計ウィンドウは、クライアント側のターン時刻とサーバー側の run 時刻を比較します。時計が数分ずれていると、run の境界付近のターンが誤った run に割り当てられます。ターンは送信時の時刻を保持するため、再送されたターンは最初に属した run に残ります。時刻なし(または解析できない時刻)で送られたターンは、その `message_id` が記録された時刻、新規であれば現在時刻になります。最初の送信から一瞬のうちに再送した場合は、現在時刻として記録されることがあります。`cost.record_turns` は、サーバーの時計より 5 秒を超えて先の時刻を持つ受信ターンを `turns_dated_ahead` として返すため、自分でターンを送る呼び出し元は時計の進みに気づけます。Claude Code プラグインは応答を読まずにターンを送信します。
+- **1 つのセッションに複数の run。** 同じセッションで同時に開いている run は同じターンを参照します。入れ子の run は両方に計上され、コスト予算を必要とする並行ワーカーには、それぞれ専用のセッションが必要です。
+- **価格未設定のモデル。** 価格表にないモデルのターンのコストは 0 です。`run.get` はそれらを `unpriced_turns` で数え、`budget_usd` には計上しません。
+- **MCP。** MCP ツールが提供するのは `budget_seconds` のみです。モデルは、ターンが記録されるセッション ID を知らないためです。
+- **リトライ。** 再送された `run.begin` は、他のリトライと同様に run の行を置き換えます。再指定されなかったセッションと予算は保持され、0 以外の新しい予算は古いものを置き換え、0 は既存の値を保持します。新しい `budget_usd` は `session_id` と一緒に送る必要があります(ない場合は 422)。新しい `budget_seconds` には他に何も必要ありません。run を別のセッションに移す再送 begin は、古いセッションのターン用に設定されたコスト予算を破棄し、時間予算は保持して、その旨を `next` で伝えます。予算が削除されるのはこの場合だけです。`run.begin` が送ったものと異なる `run_id` を返した場合は、その `run_id` か同じ `session_id` で再送してください。そうしないと、リトライは新しい run を開きます。
+
+
+
+## 取得されたことは、依拠されたことを意味しない
+
+`run.complete` では 2 つのリストが送られます。
+
+- **`memories_used`** — エージェントが実際に依拠したキーです。各キーには `used` 使用イベントが記録され、結果が肯定的な場合は `evidence` イベント、否定的な場合は `harm` イベントも記録されます。`outcome` の既定値は `status` から決まります。`completed` は肯定的、`failed` は否定的、`cancelled` はどちらでもありません。
+- **`recalled_keys`** — 実行中に Loom のツールが返したキーです(Claude Code と Codex のプラグインが `loom_search` と `memory.get` の結果から収集して保持し、セッション終了時に送信します)。これらは `run.get` のために記録されるだけで、評価の対象にはなりません。
+
+返されたものの使われなかった行は何も得ません。検索でヒットしたすべての行を評価すると、上位に表示されたものが無条件に優遇されてしまうためです。`usage_fold` ワーカーは、これらのイベントを強化項にまとめます。この強化項は[メモリ検索](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/search-and-ask.md)の順位付けに使われます。`harm` イベントは獲得済みのブーストを取り消しますが、その行の書き込み時の基準値が下限となります。そのため、1 回の不適切な実行によって行が本来の関連度を下回ることも、削除されることもありません。
+
+`memories_used` に指定されたプロシージャのキーには、プロシージャ台帳にも行が追加されます(パスは空で、`ok` は outcome から決まります)。エージェント自身が `procedure.record_run` を呼び出す場合は、実行が二重に数えられないよう、そのキーを `memories_used` に含めないでください。詳しくは[プロシージャと学習内容](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/procedures-and-learnings.md)を参照してください。
+
+
+
+## リフレクション
+
+`run.complete(reflection=...)` は、`what_worked`、`what_failed`、`assumptions`、`lessons`、`improvements`(それぞれ最大 20 項目)、`confidence`、そして教訓の根拠となる `evidence` キーを記録します。リフレクションは `reflection:` というキーで、タイプ `reflection` の 1 件のメモリとして保存されます。
+
+- 埋め込みが作成されるため、後続の実行は `memory.search(memory_type="reflection")` で見つけられます。ただし、フィルタなしの検索や `memory.ask` の対象からは除外されます。
+- `what_failed` と `lessons` には、少なくとも 1 つの `evidence` キーが必要です(指定がない場合は 422 になります)。
+- `expires_in_days`(デフォルトは 90、`0` は無期限)が経過すると失効します。ただし、`memory.verify` または肯定的な結果によって更新された場合は失効しません。
+- `role`(planner、executor、critic、または独自の名前)を指定して開始した実行は、リフレクションに `role:` タグを付けます。これにより、同じロールのエージェントが `memory.search(role=...)` を実行したときに、そのリフレクションが優先されます。
+
+
+
+## 実行が書き込んだ行はどうなるか
+
+`run.complete` の `retain` は、その実行(run)の下で書き込まれたメモリの扱いを決めます。
+
+| `retain` | 効果 |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `keep` (default) | 何も変更されません。 |
+| `demote` | 信頼度がその時点で下げられます。 |
+| `expire` | `LOOM_MEMORY_RUN_COMPLETE_EXPIRE_DAYS` 日後(デフォルトは 7)を有効期限として `on_expire=demote` とともに設定し、`memory_expiry_sweep` ワーカーがそれを適用します。 |
+
+ピン留め済み、検証済み、昇格済み、ロック済み、エピソード、リフレクションの各行は、どのモードでも保持されます。また、どのモードでも行が論理削除(tombstone)されることはありません。デフォルト値は `LOOM_MEMORY_RUN_COMPLETE_RETAIN` で決まります。MCP セッションの暗黙の run は常に keep になります。これは、run を閉じるトランスポートが作業内容を判断できないためです。
+
+
+
+## 評価付きの run
+
+`status` は run が終了したことを示し、評価(grade)はその結果が妥当だったかどうかを示します。評価は、CI が通ったときやレビュアーがプルリクエストを却下したときなど、数日後に付くことがよくあります。`run.grade` は `grade`(`pass` または `fail`)、`source`(`maintainer`、`ci`、`reviewer` など、自由なテキスト)、`reason`、`ref`(URL、finding key、check run id)を受け取り、1 つの `run_id`、または 1 つの `session_id`(たとえば `pr_1234`)に属するすべての終了済み run を対象にします。再評価すると判定は置き換わります。同じ source からの同じ判定では何も変わりません。アクティブな run は対象外です。
+
+評価付きの run の `memories_used` に含まれるメモリは、すべてその評価に対して集計されます。この集計値が、`memory.proposals` で試用中の各ファクト(`memory.set(proposed=true)` の行)の横に表示されます。Loom が集計値に基づいて提案を決定するのは、名前空間の所有者が `proposal_policy.mode` を `auto` に設定した場合だけです。どちらのモードでも、書き込み権限を持つ任意のエージェントが `memory.proposal_decide` で決定できます。[メモリの書き込み](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/writing.md)を参照してください。
+
+`run.list(grade="ungraded")` は、まだ判定が付いていない終了済みの run を一覧します。
+
+MCP セッションには、要求しなくても暗黙の run が付きます。最初の run スコープのツール呼び出しで run が開始され、`DELETE /mcp` または `mcp_session_run_sweep` ワーカーがそれを閉じます([MCP](https://github.com/ClickHouse/loom/blob/main/docs/reference/mcp.md)を参照)。sweep が閉じるのは、`environment='mcp'` で `metadata.implicit` が true、かつ id が `mcp-` に 40 桁の 16 進文字を続けた形(トランスポートだけが作る形)のアクティブな run です。run のトークンによる呼び出し(トークンを記録しない run では、誰の呼び出しでも)が `LOOM_MCP_SESSION_RUN_IDLE_SECONDS` の間その run に届かなかったとき、sweep はそれを閉じます。run は呼び出し元のデフォルト名前空間に置かれるため、その読み手に見える内容もその名前空間に限られます。goal はラベル `mcp session ()` であり、呼び出しのテキストは入りません(読み取りのクエリは、呼び出し元が読める任意の名前空間に及ぶ可能性があるためです)。`memories_written` には、その名前空間への書き込みだけが載ります(それ以外の書き込みにも、その `run_id` は付きます)。run を閉じても何も判定しません。outcome は `none` で、サーバーのデフォルトの retain モードにかかわらず、メモリは保持されます。したがって、2 つの close が競合しても(2 台のホストでの sweep や `DELETE`)、最悪の場合、同じ completion が 2 回書き込まれるだけです。
+
+run が複数の web プロセスにまたがる仕組み。run の id は、呼び出し元の org、トークンの subject、`Mcp-Session-Id` のハッシュです。そのため、サーバーのどのプロセスも同じセッションに対して同じ run を指し、同じセッション id を送っても他のトークンがその run を指すことはできません。プロセスは、セッションで最初に受理された run スコープの呼び出しで run を登録し、begin 行をバックグラウンドで書き込みます(await する insert では、ClickHouse Cloud 上でその呼び出しが数秒止まってしまいます)。ゲートに拒否された呼び出しは run 行を書きません。行が見つからなかった 2 つのプロセスがそれぞれ最初の begin を書いた場合は、開始が早いほうとその所有者が優先されます(最初の begin の行バージョンは開始時刻から逆算して減っていき、以降の書き込みはすべてそれを上書きします)。各プロセスは、キャッシュした run を台帳と照合する頻度を 1 分に最大 1 回とし、その間に `DELETE` や sweep が閉じていた場合は run を再オープンします。`DELETE` は、どのプロセスに届いても id によって run を閉じ、close はその id への書き込みを、誰が閉じるかに関係なくすべて集計します。begin 行が書き込まれる前に別のプロセスへ届いた `DELETE` は、閉じる対象が見つかりません。その後 begin が書き込まれて open の run ができ、アイドルになった時点で sweep がそれを閉じます。短いリトライでは数秒かかる begin をカバーできず、run を一度も持たなかったすべてのセッションの `DELETE` を遅らせてしまうためです。再オープンされた run は元の `started_at` を保つため、sweep に閉じられた後に再オープンされた run の `duration_ms` は、セッションの最初の呼び出しから、空白期間も含めて数えた値になります。消去(erasure)によって行が削除され、チェックで行がまったく見つからなかった場合は、その時点で開始する新しい run が始まります。そのため、消去より前の日付の run が戻ってくることはありません。
+
+
+
+## オペレーション
+
+| オペレーション | ロール | 内容 |
+| -------------- | ------ | ---- |
+| `run.begin` | writer | run を開始します:`goal`(必須)、`user_request`、`expected_outcome`、`run_id`(空または `-`:自動生成)、`session_id`、`role`、`model`、`metadata`。同じ `run_id` を再送すると行が置き換えられます。MCP トランスポートの形式の ID(`mcp-` と 40 桁の 16 進数)には、別の ID が割り当てられます。 |
+| `run.complete` | writer | run を一度だけ終了します:`status`、`memories_used`、`recalled_keys`、`outcome`、`reflection`、`retain`。冪等ではありません。2 回完了すると使用イベントが 2 回追加されます。 |
+| `run.get` | viewer | 1 件の run を、有効な派生データとともに返します。 |
+| `run.list` | viewer | run の 1 ページ分を返します。`agent`、`session_id`、`status`、`grade`、`q`、`memory_activity` で絞り込めます(`with` はメモリを利用または書き込んだ run を残し、`without` は何も使わなかった run を残します。絞り込みは `limit` の前に適用されます)。 |
+| `run.grade` | writer | 終了済みの run、またはセッションの run に `pass` / `fail` の評価を付けます。 |
+
+`run.list` は `order_by`(開始時刻、所要時間、利用したメモリ数のいずれかを昇順または降順で指定します。デフォルトは `started_desc`、新しい順です)と `offset`(最大 100,000)でページングします。`q` は、ゴール、run id、エージェントのいずれかに指定したテキストを含む run を、大文字小文字を区別せずに残します。`total` は絞り込みに一致するすべての run の件数です。2 ページ目以降の満杯のページでは、そのページだけでは判断できないため null になります。
+
+フィールドの全一覧は[オペレーションリファレンス](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md#run)を参照してください。`memory.outcome_run` は、キーを指定せずにまとめて評価する呼び出し元向けに、run の下で呼び出された各メモリについて helped / hurt の結果を 1 件ずつ記録します。
+
+
+
+## 例
+
+Python SDK の `run.scope` は、ブロックに入るときに実行(run)を開き、抜けるときに閉じます。ブロック内で `memory.ask` の回答が引用したキーと、`used()` に渡したキーが `memories_used` になります。例外が発生した場合、実行は `failed`(outcome は negative)として閉じられ、その後に例外が伝播します。ブロック内の書き込みには、その実行の id が付与されます。
+
+```python
+from loom import Agent
+
+async with Agent(org="acme", namespace="support", agent="triage-bot") as agent:
+ async with agent.run.scope(goal="Answer ticket 4411: refund policy for annual plans") as run:
+ answer = await agent.memory.ask("what is the refund policy for annual plans?")
+ run.used("policy/refunds/annual") # relied on beyond what the answer cited
+ run.final_response = answer["answer"]
+
+ replay = await agent.run.get(run.run_id)
+ print(replay["run"]["status"], replay["memories_written"], replay["recalled"])
+
+ # Later, once the customer confirmed the answer was right:
+ await agent.run.grade("pass", run_id=run.run_id, source="support-lead")
+```
+
+HTTP では、ライフサイクルは 2 回の呼び出しで構成されます。
+
+```bash
+curl -sX POST "$LOOM_BASE_URL/v1/run.begin" -H "Authorization: Bearer $LOOM_API_KEY" \
+ -H 'Content-Type: application/json' \
+ -d '{"org":"acme","namespace":"support","agent":"triage-bot","goal":"Answer ticket 4411"}'
+# → {"run_id":"…","status":"active","started_at":"…","next":"…"}
+
+curl -sX POST "$LOOM_BASE_URL/v1/run.complete" -H "Authorization: Bearer $LOOM_API_KEY" \
+ -H 'Content-Type: application/json' \
+ -d '{"org":"acme","namespace":"support","run_id":"…","status":"completed",
+ "memories_used":["policy/refunds/annual"]}'
+```
+
+`Agent(auto_run=True)`(またはクライアント環境の `LOOM_AUTO_RUN=on`)を指定すると、最初のメモリ操作の呼び出しで実行が遅延的に開かれ、以降のすべての呼び出しがその実行に紐づけられ、`Agent` を閉じるときに outcome `none` で完了されます。そのため、評価の加点も減点も行われません。実行下での書き込みはその実行にスコープされ、別の実行の行を言い換えた内容は統合されず `duplicate` として保存されるため、この設定はデフォルトでは無効です。
+
+
+
+## 設定
+
+| 設定 | 効果 |
+| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `LOOM_MEMORY_RUN_COMPLETE_RETAIN` | 呼び出しで `retain` モードが指定されていない場合に使われるモード(`keep`)。 |
+| `LOOM_MEMORY_RUN_COMPLETE_EXPIRE_DAYS` | `retain=expire` が有効期限を何日先に設定するか(7 日)。 |
+| `LOOM_SEARCH_TRACE_LOG_ENABLED` | すべての検索を `run_id` ごとに記録します。`recalled` はこの記録から導出されます。クエリテキストをログに残すため、デフォルトではオフです。 |
+| `LOOM_USAGE_FOLD_ENABLED` | used / evidence / harm イベントをランキングに反映する `usage_fold` ワーカー。 |
+| `LOOM_MEMORY_SEARCH_REINFORCEMENT_WEIGHT`, `…_HALF_LIFE_DAYS` | 検索で、利用実績が行をどの程度、どのくらいの期間押し上げるか。 |
+
+[設定:重複排除と有効期限](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#dedup-and-expiry)、
+[ワーカー](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#workers)、
+[メモリ検索](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#memorysearch) も参照してください。
+
+
+
+## 制限
+
+- `memories_used` と `recalled_keys` は、それぞれ最大 500 個のキーを受け付けます。`goal` は最大 2,000 文字です。
+- `memories_used` のキーのうち、有効な行に解決されないものは何も得られません。レスポンスの `used_applied` は、解決されたキーの数を示します。
+- `run.complete` は冪等ではありません。完了を再試行すると使用イベントが二重に計上されるため、完了は一度だけ行ってください。
+- SDK の `run.scope` は、ledger をベストエフォートで書き込みます。`run.complete` が失敗しても、ブロック自体の例外が隠されることはありません。そのため、完了に失敗した run は `active` のままになります。
+- `turns` と `cost_usd` は、run に `session_id` がない場合、またはクライアントがターンの使用量を報告しない場合は 0 になります。これらは、run が開いている間に行われたターンだけを集計します。
+
+
+
+## 関連ドキュメント
+
+- [長時間実行のトレースと再開](https://github.com/ClickHouse/loom/blob/main/docs/guides/trace-and-resume.md) — `run_id` をキーとするワーキングメモリ内のチェックポイントと、実行内容をトレースする方法。
+- [検索と質問](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/search-and-ask.md) — 強化がランキングにどのように反映されるか。
+- [タスクと意思決定](https://github.com/ClickHouse/loom/blob/main/docs/features/tasks-and-decisions.md) — `decision.outcome` は、意思決定を行った実行が根拠にしたメモリにクレジットを付与します。
+- [メモリアーキテクチャ](../architecture/memory-architecture.md) — 使用イベントのフォールドと、その背後にあるテーブル。
diff --git a/i18n/.pending/ja/docs/guides/performance-tuning.md b/i18n/.pending/ja/docs/guides/performance-tuning.md
new file mode 100644
index 0000000000..99068b788b
--- /dev/null
+++ b/i18n/.pending/ja/docs/guides/performance-tuning.md
@@ -0,0 +1,153 @@
+
+> このページは[英語の原文](https://github.com/ClickHouse/loom/blob/main/docs/guides/performance-tuning.md)の機械翻訳です。内容は英語の原文が優先されます。
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/guides/performance-tuning.md), which is authoritative.
+
+
+
+# Loom のパフォーマンスをチューニングする
+
+このページで扱う調整項目は、すべて設定またはリクエストのフィールドです。各設定のデフォルト値と意味については、[設定リファレンス](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md)を参照してください。トレードオフを計測できる項目については、計測に使うコマンドを併記しています。
+
+
+
+## まず計測する
+
+| 知りたいこと | コマンド | 必要なもの |
+| -------------------------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------- |
+| 並行数 N での 1 つの op の p50 / p95 / p99 と RPS | `make bench OP=memory.search C=5 D=60` (`scripts/ops/benchmark.py`) | 稼働中のサーバー。書き込みは `bench-…` 名前空間に入る |
+| ランキングや embedder の変更で再現率が下がったか | `make bench-quick` (回答ジャッジ付きの、公開されている長期メモリベンチマークの一部) | 実際のプロバイダー、`OPENAI_API_KEY` |
+| 記録済みベースラインに対する再現率 | `make bench-quality-gate MIN_RECALL=…` | 実際のプロバイダー |
+| 検索モード × rerank × プール幅 | `make bench-matrix` (`bench/MATRIX_RESULTS.md` に書き出す) | 稼働中のサーバー |
+| 抽出およびグラフ抽出のリグレッション | `make bench-algorithm-gate` | 稼働中のサーバー |
+| コードプレーンのシンボル、呼び出し元、再現率、トークンコスト | `make bench-code-intel`, `make bench-code-legs` | 実際の embedder |
+| デプロイ後に何が変わったか | `loom deploy-delta` (入れ替えの前後での、台帳と ClickHouse ステートメントの形) | `var/deployed.json` |
+
+> **警告:** fake embedder で測定した再現率は、実際の検索について何も示しません。品質ゲートが CI に含まれていないのはこのためです。デプロイ予定のプロバイダーを使うサーバーに対して実行し、embedder を変更したらベースラインを取り直してください。
+
+遅いリクエストを 1 件調べる場合は、設定に手を加える前に、その `Server-Timing` ヘッダー (`app` と `ch`) と `system.query_log` の行を確認してください ([デバッグ](https://github.com/ClickHouse/loom/blob/main/docs/guides/debugging.md))。デプロイ全体での操作ごとのコストは、`log_comment` に対する 1 つのクエリで取得できます。
+
+```sql
+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;
+```
+
+入れ替え直後のベンチマークトラフィックはキャッシュが冷えた状態で読み込まれます。デプロイ後のレイテンシーを以前のビルドと比較する前に、しばらく待ってください。
+
+
+
+## ランキングとしきい値
+
+`memory.search` は第 1 段階の候補プールをランク付けし、その後にランク項とゲートを適用します([検索とランキング](https://github.com/ClickHouse/loom/blob/main/docs/concepts/retrieval-and-ranking.md))。ほとんどの項はデプロイごとに設定でき、リクエストごとに上書きもできるため、変更をまず 1 つの呼び出し元で A/B テストできます。
+
+| 調整項目 | 設定(リクエストフィールド) | トレードオフ |
+| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| 類似度ゲート | `LOOM_ADAPTIVE_THRESHOLDS`(デフォルトはオン) | オン:起動時にエンベッダー自身のコサイン分布からゲートを導出します。オフ:下記のスカラーゲートを自分で管理します。 |
+| スカラーゲート(フォールバック) | `LOOM_MEMORY_SEARCH_MIN_SIMILARITY`, `LOOM_MEMORY_SEARCH_ABSTAIN_THRESHOLD`, `LOOM_MEMORY_SEARCH_HYDE_FALLBACK_THRESHOLD`, `LOOM_MEMORY_SEARCH_QUERY_REWRITE_THRESHOLD` | `text-embedding-3-small` 向けに調整されています。偽のエンベッダー、プローブの失敗、適応機能がオフの場合に使われます。 |
+| フロア未満のヒット | `LOOM_MEMORY_SEARCH_FLOOR_MODE`(`floor_mode`) | `readmit` は `top_k` を満たすまで補充し、`below_floor` のタグを付けます。`ids_only` は本文が空の行で補充します。`drop` は少ない件数を返します。 |
+| 候補プール | `LOOM_MEMORY_SEARCH_POOL_MULTIPLIER_STANDARD`, `_RERANK`, `_DEEP`。上限は `LOOM_MEMORY_SEARCH_MAX_POOL_TOP_K` | プールを広げると再現率とリランクの入力が増えます。その分、読み取るベクトル行とリランクのトークンが増えます。 |
+| リランクのスキップ | `LOOM_LLM_RERANK_SKIP_ABOVE`(適応ゲートにプローブがない場合のフォールバック) | ベクトル検索の最上位ヒットがすでに強い場合、リランク呼び出しをスキップします。 |
+| フォールバックカスケード | `LOOM_MEMORY_SEARCH_FALLBACK_MAX_ROUNDS`, `_MAX_WALL_MS`, `_MAX_LLM_CALLS`, `_MAX_VECTOR_QUERIES` | 1 回目の結果が弱い場合に費やせる再試行(クエリ書き換え、HyDE)を制限します。 |
+| 強化 | `LOOM_MEMORY_SEARCH_REINFORCEMENT_WEIGHT`(`reinforcement_weight`), `_HALF_LIFE_DAYS` | 再呼び出しと良好な結果が行をどれだけ押し上げるかを決めます。0 で無効になります。関連度より低く抑えられます。 |
+| 出所 | `LOOM_MEMORY_SEARCH_TRUST_WEIGHT`(デフォルトは 0) | 証明済みのソースを優遇する、上限付きの項です。 |
+| 新しさ | `LOOM_MEMORY_SEARCH_RECENCY_POOL_WEIGHT`(`recency_pool_weight`) | 新しさを意図したクエリで、プールを新しい行寄りに再ランク付けします。0 でオフです。 |
+| コード形状クエリでの字句レッグ | `rrf_adaptive_lexical`(リクエスト), `LOOM_MEMORY_RRF_CODE_SHAPE_LO` / `_HI` | RRF において、パス形状やコード形状のクエリで字句レッグの重みを下げます。 |
+| デフォルトモード | `LOOM_MEMORY_SEARCH_DEFAULT_MODE`(`search_mode`) | 呼び出し元がモードもレシピも指定しない場合に使われます。 |
+| キーごとの重複 | `LOOM_MEMORY_SEARCH_PER_KEY_CAP` | 1 つのキーが 1 ページに寄与できる行数です。 |
+
+> **警告:** あるエンベッダーで調整したしきい値は、別のエンベッダーでは適切ではありません。`LOOM_ADAPTIVE_THRESHOLDS=false` の場合や偽のエンベッダーを使う場合は、エンベッダーを変更するたびにベンチマークをやり直してください(`make bench-quick`、`make bench-quality-gate`)。`calibration.get` を使うと、名前空間で有効なゲートをどのティアが生成したかを確認できます。
+
+
+
+## ベクトル読み取り
+
+ベクトル列は `Array(BFloat16)` です。`enable_quantized_codec` を有効にできる場合、マイグレータは列をコード化した形式で作成します([ClickHouse](https://github.com/ClickHouse/loom/blob/main/docs/architecture/clickhouse.md#gated-clickhouse-settings))。
+
+| 調整項目 | 設定 | トレードオフ |
+| -------------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| コード優先スキャン | `LOOM_VECTOR_SEARCH_QUANTIZED_CODES`(デフォルトはオン)、`LOOM_MEMORY_SEARCH_FACT_CODES_FIRST`(`auto`) | 量子化コードを読み取り、その後フル精度で再スコアリングします。`auto` は、`memory_embeddings` にパッチパートがある間はオフになります。この場合、再スコアリングがスキップされるためです。 |
+| コードのオーバーフェッチ | `LOOM_VECTOR_SEARCH_QUANTIZED_FETCH_MULTIPLIER`、`LOOM_MEMORY_SEARCH_FACT_CODES_FETCH_MULTIPLIER` | 再スコアリングの前に、コード距離で残す行数です。値を小さくするとコストは下がりますが、上位ヒットが変わる頻度が高くなります。 |
+| ファクト文ごとのスレッド数 | `LOOM_MEMORY_SEARCH_FACT_LEG_MAX_THREADS`(0 = 固定なし) | スレッド数を固定すると、文ごとの CPU とピークメモリが制限されますが、レイテンシが多少増えます。 |
+| 一括書き込みのピア読み取り | `LOOM_MEMORY_BULK_PEER_READ`(デフォルトは `batched`、`per_fact`) | `per_fact` は、`memory.set` と同様に、一括書き込みの各ファクトについて、競合ピアと値更新ピアをコード優先で読み取ります。大規模な名前空間向けです。バッチ化されたピア文が `MEMORY_LIMIT_EXCEEDED` で失敗し(サーバーログでは `batched conflict candidates failed`)、さらにファクトごとのフォールバックも失敗した場合、そのエントリは未チェックのまま書き込まれます。距離が同点の場合、ピアが異なることがあります。 |
+
+既存のテーブルをコーデックやレイアウトに移行するには、`scripts/ops/vector_codec_rebuild.py` を使用します(ツインテーブル、整合性ゲートと再現率ゲート、`EXCHANGE`。[手順](https://github.com/ClickHouse/loom/blob/main/docs/operations/deployment.md#recommended-clickhouse-settings))。マイグレーション内で `ALTER` を使用しないでください。
+
+
+
+## ClickHouse の接続とデッドライン
+
+| 項目 | 設定 | トレードオフ |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| プールサイズ | `LOOM_CH_POOL_MAXSIZE`(デフォルトはプロセスあたり 64) | 想定されるリクエストの同時実行数にワーカー数を加え、さらにバッチ挿入が待機中に保持する接続数を足してサイズを決めます。ドライバー自体のデフォルト値は、大量の書き込みでは使い切られます。 |
+| バッチ挿入 | `LOOM_CH_BATCHED_INSERTS`(デフォルトで有効)、`LOOM_CH_BATCHED_INSERT_WAIT_MIN_MS`(10)、`LOOM_CH_BATCHED_INSERT_WAIT_MAX_MS`(50)、`LOOM_CH_BATCHED_INSERT_BACKGROUND_WAIT_MAX_MS`(200) | 同時に行われる挿入は 1 つのパートを共有し、それぞれ最大でウィンドウ分のレイテンシが加わります。単独の挿入は最小値だけ待機します。待機中の挿入はそれぞれプール内の接続を 1 つ保持するため、書き込みレートに応じてプールを大きくする必要があります([バッチ挿入](https://github.com/ClickHouse/loom/blob/main/docs/architecture/clickhouse.md#batched-inserts))。 |
+| プール待機 | `LOOM_CH_POOL_WAIT_MS`(デフォルト 500) | これを超えると、リクエストはキューに入らず 503 `OVERLOADED` で即座に失敗します。0 の場合はゲートなしです。 |
+| キープアライブ | `LOOM_CH_KEEPALIVE_TIMEOUT`(デフォルト 5 秒) | ロードバランサーのアイドル切断時間より短くしておく必要があります。これにより、Loom がプール内の接続を先に閉じます。 |
+| ステートメントのデッドライン | `LOOM_CH_TIMEOUT_READ_S`、`LOOM_CH_TIMEOUT_WRITE_S`、`LOOM_CH_TIMEOUT_DDL_S` | `max_execution_time` として、またプールのスロットを解放するクライアント側の上限として適用されます。0 の場合、そのクラスは無制限です。 |
+| トラフィッククラスごとの優先度 | `LOOM_CH_SETTINGS_BY_TRAFFIC_CLASS`(JSON) | クラス(`production`、`interactive`、`bench`、`background`)ごとの `priority` と `max_threads` を指定します。これにより、ベンチとワーカーが本番の読み取りに道を譲ります。 |
+| Read-your-writes | `LOOM_CH_READ_YOUR_WRITES`、`LOOM_CH_READ_YOUR_WRITES_WINDOW_S` | 書き込み後に逐次一貫性のある読み取りを行います。レプリケーションされたサービスではコストがかかり、単一ノードでは何もしません。 |
+| オペレーションの予算 | `LOOM_LATENCY_BUDGET_MULTIPLIER` | すべての op の `budget_p99_ms` を拡大します。ClickHouse への WAN 経由のホップでは約 20 が必要です。予算は `budget.violated` イベントを発生させるだけで、リクエストを打ち切ることはありません。 |
+
+Web の処理能力は、コンテナあたりの `LOOM_WEB_WORKERS` にコンテナ数を掛けた値です。レートリミッターは、`loom.instances` で数えた稼働中のレプリカ数で上限を割りますが、`LOOM_REPLICA_COUNT` を下回ることはありません([レプリカ](https://github.com/ClickHouse/loom/blob/main/docs/operations/replicas.md#rate-limits))。
+
+
+
+## プロバイダー
+
+| 調整項目 | 設定 | トレードオフ |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| クエリ埋め込みの上限 | `LOOM_MEMORY_SEARCH_EMBED_BOUND_S`, `LOOM_MEMORY_SEARCH_EMBED_BOUND_RETRIES` | クエリ埋め込みの1回ごとの試行に上限を設けます。リトライ後も完了しない場合、検索は 503 `EMBED_TIMEOUT` を返します。 |
+| クエリの綴り | `LOOM_MEMORY_SEARCH_QUERY_SPELLING_MAX_WORDS` | この語数以下のクエリは、埋め込みと並行して名前空間を1回読み取り、小文字の単語をコーパスの綴りで埋め込みます。40k 行の名前空間で 100–300 ms かかり、結果は1分間再利用されます。`0` で無効になります。 |
+| クエリ埋め込みのキャッシュ | `LOOM_EMBEDDING_CACHE_SIZE`, `LOOM_EMBEDDING_CACHE_TTL_S`, `LOOM_EMBEDDING_CACHE_SHARED`, `LOOM_EMBEDDING_CACHE_SHARED_MAX_CHARS` | 共有の `loom.embedding_cache` の手前にプロセスごとの LRU を置きます。繰り返されるクエリはプロバイダー呼び出しを省略します。 |
+| クラスごとの LLM レスポンスキャッシュ | `LOOM_LLM_POLICY_BY_TRAFFIC_CLASS` (JSON) | LLM のレスポンスをキャッシュし(`bench` ではデフォルトで有効)、クラスごとに strong ティアや mid ティアの利用を禁止できます。 |
+| フォールバックモデル | `LOOM_LLM_FALLBACK_MODEL` | リトライ後もプライマリが利用できない場合、op を失敗させる代わりにこのモデルが応答します。 |
+| 支出上限 | `LOOM_DEFAULT_DAILY_COST_CAP_USD`(名前空間ごとの `daily_cost_cap_usd`) | 上限を超えると、LLM を使うワーカーはその名前空間をスキップし、`memory.ask` は `budget_capped` で回答を控えます。通常の読み取りと書き込みは継続します。 |
+
+
+
+### エンベッダーの選択
+
+| エンベッダー (`LOOM_EMBEDDING_MODEL`) | トレードオフ |
+| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
+| `text-embedding-3-large`, `gemini-embedding-001` | Loom のデフォルトである 3072 次元です。品質とコストは、実際のデータで測定する必要があります。 |
+| `text-embedding-3-small` | より狭い 1536 次元のベクトルを使う選択肢です。次元を変更すると再埋め込みが必要です。 |
+| `local`, `local:bge-small`, `local:bge-base`, `local:minilm` | プロセス内で CPU により埋め込みを行います。プロバイダー呼び出しもキーも不要です。品質と引き換えにレイテンシとコストを抑えます。 |
+| `fake-ngram-3072` | 標準の次元で文字 n-gram を使います。テストと配線の確認専用で、再現率の数値には意味がありません。 |
+
+エンベッダーを変更するとベクトル空間が変わります。`LOOM_EMBEDDING_DIM` を合わせて設定し、`loom reembed` を実行してください。適応型しきい値が有効な場合は、起動時のプローブに再較正させます。変更の前後で `make bench-quick` を実行してください。抽出プロンプトが較正されている `LOOM_LLM_MODEL` についても同様です。
+
+
+
+## ワーカーとバッチ
+
+すべてのワーカーには `*_ENABLED` スイッチと `*_INTERVAL_SECONDS` による実行間隔があり、多くのワーカーには、何も見つからなかったパスの後にスリープする `*_IDLE_INTERVAL_SECONDS` もあります([ワーカーのリファレンス](https://github.com/ClickHouse/loom/blob/main/docs/reference/workers.md))。間隔を短くするとバックグラウンド処理の遅延は小さくなりますが、スキャンの回数が増えます。アイドル間隔により、空のキューの負荷は低く抑えられます。
+
+| ワーカー | 調整項目 |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `embedding_worker` | `LOOM_EMBEDDING_WORKER_INTERVAL_SECONDS`、`_IDLE_INTERVAL_SECONDS`。`LOOM_EMBEDDING_WORKER_ORPHAN_FULL_SCAN_SECONDS` / `_ORPHAN_RECENT_SECONDS` は孤立レコードのアンチジョインの範囲を制限します。 |
+| `extraction_queue` | `LOOM_EXTRACTION_QUEUE_INTERVAL_SECONDS`、`_MAX_BATCHES_PER_PASS`、`_NAMESPACE_CONCURRENCY`、`_LEASE_SECONDS`。`LOOM_EXTRACTION_DEFER_AGENTS` は、列挙したエージェントの `set_from_messages` を後回しにし、抽出の前にリクエストが返るようにします。 |
+| `memory_expiry_sweep` | `LOOM_MEMORY_EXPIRY_SWEEP_BATCH_SIZE`。 |
+| `task_lease_sweep` | `LOOM_TASK_LEASE_SWEEP_INTERVAL_SECONDS`、`_IDLE_INTERVAL_SECONDS`。 |
+
+ワーカーは `background` トラフィッククラスで動作するため、`LOOM_CH_SETTINGS_BY_TRAFFIC_CLASS` でも ClickHouse の優先度とスレッド数が制限されます。ワーカープロセスは必ず 1 つだけ実行してください。LLM を使うワーカーを 2 つ起動すると、スキャンとコストが 2 倍になります。コードプレーンのインジェストワーカーとコンパイラティアのワーカーには、それぞれ独自の調整項目があります([コードインデックスの運用](https://github.com/ClickHouse/loom/blob/main/docs/operations/code-index-operations.md))。
+
+
+
+## クライアント側の調整項目
+
+大きな効果が得られるものの多くは、リクエスト側にあります。
+
+- 取得する本文を減らす:`memory.search` では `bodies` と `body_budget_tokens`、`context.pack` と `code.search` では `token_budget` を指定します。
+- ステップごとに検索するのではなく、タスクごとに一度だけコンテキストを読み込む(`context.pack`)。
+- `retrieval_budget` を使って、呼び出しごとに低コストな検索プロファイルか、より深い検索プロファイルを選ぶ。
+- 冪等な op は `Idempotency-Key` ヘッダー付きで再試行する(SDK が自動で生成します)。リプレイすると、op を再実行せずに保存済みのレスポンスが返されます。
+
+
+
+## 関連項目
+
+- [障害と復旧](../architecture/failure-and-recovery.md):キャパシティとスケールの対象
+- [モニタリング](https://github.com/ClickHouse/loom/blob/main/docs/operations/monitoring.md)
+- [ベンチマークの実行](https://github.com/ClickHouse/loom/blob/main/docs/benchmarks/running.md)
+- [デバッグ](https://github.com/ClickHouse/loom/blob/main/docs/guides/debugging.md)
diff --git a/i18n/.pending/ja/docs/operations/okf-sync.md b/i18n/.pending/ja/docs/operations/okf-sync.md
new file mode 100644
index 0000000000..f255cb8a60
--- /dev/null
+++ b/i18n/.pending/ja/docs/operations/okf-sync.md
@@ -0,0 +1,108 @@
+
+> このページは[英語の原文](https://github.com/ClickHouse/loom/blob/main/docs/operations/okf-sync.md)の機械翻訳です。内容は英語の原文が優先されます。
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/operations/okf-sync.md), which is authoritative.
+
+
+
+# 名前空間を別の Loom にコピーする
+
+プライベートネットワーク内のジョブが、スケジュールに従って 1 つの名前空間をプライベートな Loom からパブリックな Loom にコピーします。`loom export-okf` がプライベートな Loom から名前空間を読み取り、`loom import-okf --prune` がパブリックな Loom に書き込みます。パブリック側には、プライベートな Loom へのルートもトークンも渡りません。`deploy/okf-sync/cronjob.yaml` は Kubernetes の例で、15 分ごとに実行される CronJob、その ServiceAccount、および NetworkPolicy を含みます。
+
+```bash
+LOOM_API_KEY="$PRIVATE_VIEWER" loom export-okf --server-url "$PRIVATE_URL" \
+ --namespace shared-lessons --no-evidence --out /tmp/bundle
+LOOM_API_KEY="$PUBLIC_WRITER" loom import-okf /tmp/bundle --server-url "$PUBLIC_URL" \
+ --namespace shared-lessons --agent okf-sync --prune
+```
+
+
+
+## 実行時の書き込み内容
+
+- **変更がなければ何も書き込みません。** インポートは、まず自身の identity 配下の有効な行を読み取り、値、型、タグ、信頼度、`valid_at`、`valid_to`、`source_trace`、`source_class`(宣言されたクラス、なければ `imported`)が同じ行を持つコンセプトをスキップします。バンドルにエンティティが含まれる場合は、エンティティも比較します。`memory.set` 自身が追加するタグ(`sensitivity:`、`attribute:`)は差分に含まれません。すでに有効なエッジもスキップします。バンドル内の複数のコンセプトが同じキーを共有している場合(異なる書き込み元の行)、最後に更新されたものが書き込まれます。同一の行を再送すると強化(reinforcement)として数えられ、実行のたびにバージョン行と監査行が増え、ランキングのブーストも高くなります。`sources:` を持つコンセプトは例外で、実行のたびに書き込まれます。インポートが行う読み取りでは、リンク先のソースが返されないためです。ターゲットが別のキーの行にマージするコンセプトも同様です。実行のたびに再送され、その行を強化し、最終行ではマージ済みとして数えられます。
+- **新規または変更されたコンセプトごとに `memory.set` を 1 回実行します。** 他の書き込みと同じく、競合、ブラックリスト、監査のチェックを通り、トークンが actor になります。ソースが `derived` または `external` とマークした行はそのクラスを保持し、それ以外の行はすべて `imported` として保存されます。これは `okf:` トレースからサーバーが導き出します。両側で org と名前空間が同じ場合、コピーに `origin:` タグは付きません。
+- **プルーニングされた行ごとに `memory.delete_version` を 1 回実行します。** `--prune` が削除するのは、インポートの `--agent` 配下にあり、そのトークンで書き込まれ、`source_trace` が `okf:` で始まり、キーがバンドルにもう存在しない行だけです。名前空間内で他者が書き込んだ行は残ります。名前空間にインポートするバンドルごとに、固有の `--agent` を指定してください(指定がない場合、`--prune` は拒否されます)。削除はトゥームストーンであり、`memory.restore` で 14 日間の期間内なら行を元に戻せます。
+
+最終行にはカウントが報告されます。
+`500 rows from the bundle into acme/shared-lessons: 0 written, 500 unchanged, 0 failed …,
+0 pruned`。
+終了コード 1 は、ターゲットを読み取れなかった、または書き込み、リンク、削除、エビデンスのバッチ、`--verify` のいずれかが失敗したことを意味します。終了コード 2 は、リクエストを送る前にインポートが拒否されたことを意味します。lint の指摘、プルーニングのガード、ディレクトリではないパス、または `--agent`、トークン、org の欠落が該当します。
+
+
+
+## ガード
+
+- `--prune` は、コンセプトを含まないバンドルを拒否します。また、コンセプトファイルのハッシュが、エクスポート時に `index.md` へ書き込まれた `loom.corpus_digest` と一致しないバンドルも拒否します。編集されたバンドルや、古いバンドルが残るディレクトリにエクスポートされたバンドルが、削除を引き起こすことはありません。`index.md` に `loom.complete: true` がないバンドルは書き込まれますが、プルーニングはされず、最終行にその旨が表示されます。エクスポートは、`--limit` で停止した場合、`--include-tombstoned` を付けて実行した場合(このバンドルには削除済みの行が残ります)、または読み取り中にソースが変更された場合(ページング中の書き込み、または全体を読み取る前の行の削除)にマーカーを付けず、その理由を表示します。古いリリースが書き出したバンドルにはマーカーがありません。
+- エクスポートは、ソース側で置き換えられた行と重複した行を `status: deprecated` として含めます。そのため、ソースが別のキーに統合したキーも、プルーニングされずにコピー先に残ります。
+- エクスポートはソースをオフセットでページングするため、一覧取得中にソースへ書き込みがあると、ページがずれて有効な行を取りこぼすことがあります。ページ取得の後、エクスポートは `memory.keys` を読み込みます。これは、すべての有効な行の ID とキーを 1 つのステートメントで返すもので(ある時点の名前空間)、それらの行がすべて一覧に含まれていた場合にのみ、一覧を完全とみなします。その時点より後に書き込まれた行は後の変更であり、次回の実行が引き継ぎます。一覧取得は合計で最大 3 回行われ、それでも完全にならなければ `loom.complete` は付きません。その場合、その実行はコピーのみでプルーニングは行わず、後の、より書き込みの少ない実行でプルーニングします。`memory.keys` に応答できない古いソース、または有効な行が 100,000 を超えるソースは、完全とはみなされません。
+- 各削除の前に、その行を自身の ID で再度読み取り、次のすべてを満たす場合にのみ続行します。その行が自身の `--agent` の下にあること、自身のトークンで書き込まれたこと(エージェント名だけでは呼び出し側が選んだものにすぎません)、インポートの一覧が `okf:` トレース付きで見たバージョンのままであること、`memory.lock` がないことです。それ以外は保持としてカウントされ、その時点で存在しない行や別のエージェントの下にある行はカウントされません。削除には `memory.delete_version` を使い、その正確な ID の下にある該当バージョンだけを削除します。他のエージェントの行は削除しません。削除が実行された時点で進行中の、そのキーに対する `memory.set` または `memory.bulk_set` は、その行を保持します。例外については[メモリアーキテクチャ](../architecture/memory-architecture.md#lifecycle)を参照してください。
+- `memory.delete_version` を知らない古いターゲットレプリカは 404 を返し、何も削除しません。プルーニングはこの失敗をカウントし、インポートは終了コード 1 で終了します。どちらの Loom もローリングアップグレードで一時停止する必要はありません。
+- インポートは、エクスポートが終了コード 0 で終了した場合(`sh -e`)にのみ実行されます。また、各実行はバンドルを新しい `emptyDir` に書き込むため、以前の実行が残したバンドルがインポートされることはありません。
+- `--dry-run` は、同じチェックを行った上で、書き込み・削除される内容を一覧表示し、何も書き込みません。
+- `concurrencyPolicy: Forbid` により、2 つの実行が並行して動作することはありません。
+
+1 回の実行でプルーニングできる行数に上限はありません。意図的に大半の行を失ったソースの名前空間は、オペレーターの介在なしに次回の実行で反映されます。すべての行を失った場合は反映されません。インポートが空のバンドルを拒否するため、ジョブは毎回失敗します。CronJob を停止し(`kubectl patch cronjob okf-sync -p '{"spec":{"suspend":true}}'`)、公開側の Loom にあるコピーを `memory.delete` で削除してください。内容自体を消す必要がある場合は、消去(erasure)を通じて削除します。
+
+誤ってプルーニングされたキーは、そのキーを含むバンドルを持つ次回の実行で、新しい行として再び書き込まれます。このとき `memory_id` は変わります。元の行を復元するには `memory.restore` を使います。
+
+
+
+## 実行のコスト
+
+変更対象が見つからない実行は、読み取りだけを送信します。`sensitivity: high` の行をキーで読み取るたびに監査(`memory.sensitive_read`)が記録されるため、インポートの ID の下に high の行があると、何も変更しない実行でも、その行をキーで読み取る側ごとに、high の行 1 件につき監査行が 1 件追加されます。N 行の名前空間では次のとおりです。
+
+| 側 | リクエスト |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| エクスポート、プライベート Loom | 100 行ごとの `memory.list` ページ(`LOOM_MEMORY_LIST_VIEWER_LIMIT` が viewer トークンのページ上限)、`memory.keys` 1 回、ビルドコミットを取得する `GET /v1/health` 1 回、(agent、user、session)それぞれ 500 行ごとに `memory.bulk_get` 1 回、型付きエッジ 2,000 件ごとに `memory.export_evidence` 1 ページ |
+| インポート、パブリック Loom | 1,000 行ごとの `memory.list` ページ、500 行ごとに `memory.bulk_get` 1 回、エッジのページの再取得。続いて、変更された行ごとに `memory.set` 1 回、新しいエッジごとに `memory.link` 1 回、プルーン候補(`okf:` トレースを持ち、キーがバンドルから消えた行。残すかどうかは問わない)ごとに `memory.bulk_get` 1 回、プルーンされた行ごとに `memory.delete_version` 1 回 |
+
+writer が 1 つの 501 行の名前空間では、合計 15 リクエストです(エクスポート側は `memory.list` 6 回、`memory.keys` 1 回、health 読み取り 1 回、`memory.bulk_get` 2 回、エッジページ 1 回。インポート側は 1、2、1)。1 つの ID の下で 50,000 行ある場合、1 回の実行は約 750 リクエストで、15 分間隔のスケジュールでは 1 秒あたり 1 件未満です。フックが書き込むように多数のセッションに分散した名前空間では、代わりにセッションごとに `memory.bulk_get` が 1 回必要です。また、ページング中にソースが変更された場合、エクスポートはソースを合計で最大 3 回一覧取得します。
+
+
+
+## トークン
+
+ジョブは 2 つのトークンを持ち、それぞれ 1 つの名前空間にスコープされます。
+
+```bash
+# On the private Loom: read the namespace, nothing else.
+loom mint-token --subject okf-sync --org --namespace-role shared-lessons=viewer \
+ --ttl-days 90 --save ./private-viewer.jwt
+# On the public Loom: write the namespace, nothing else.
+loom mint-token --subject okf-sync --org --namespace-role shared-lessons=writer \
+ --ttl-days 90 --save ./public-writer.jwt
+```
+
+CronJob が読み込む Secret に保存します。
+
+```bash
+kubectl create secret generic okf-sync \
+ --from-file=private-viewer=./private-viewer.jwt \
+ --from-file=public-writer=./public-writer.jwt
+```
+
+TTL が切れる前に、同じ `--subject` と同じ種類(デフォルトのサービスアカウント)で再発行し、Secret を置き換えてください。prune が削除するのは、そのトークンの actor が書き込んだ行のみです(サービスアカウントでは `process:`、ユーザートークンでは `human:`)。そのため、subject や種類が異なるトークンを使うと、以前のコピーはそのまま残ります(最後の行では保持として数えられます)。漏洩したトークンは `loom revoke-token` で無効化します。認証がオフのサーバーでは、どの行にも actor が付かないため、prune は何も削除せず、すべての候補を保持として数えます。
+
+- 公開 Loom では、ジョブのトークンがその名前空間で唯一の書き込み権限を持ちます。読み取り側(公開 CI のボットなど)は `viewer` トークンを持ちます。
+- 非公開 Loom では、その名前空間の書き込み権限を持つのは、そこに公開するユーザーとエージェントです。それを読む他のすべてのプリンシパルは `viewer` を持つため、書き込み側が公開するつもりのないものが名前空間に届くことはありません。
+
+
+
+## コピーされた名前空間は公開される
+
+名前空間内のすべての内容は、1 回のスケジュール間隔以内に公開 Loom に反映されます。プライベート側でこの名前空間に書き込むことは公開と同じだと考えてください。機密情報は別の名前空間に置いてください。`sensitivity: high` が付いた行はプライベート側にとどまります(`--include-high` を指定しない限り、エクスポートはそれらを除外します)。行が `high` になった場合は、次の実行時に公開側から削除されます。ただし、それがエクスポートの対象となる最後の行だった場合は例外です。その場合、バンドルにコンセプトが含まれなくなるため、インポートはバンドルを拒否し、公開側のコピーは残ります。公開 Loom 上でこれらを削除するには `memory.delete` を使います。内容自体を消す必要がある場合は、消去(erasure)を使います。エクスポートは、`memory.bulk_get` から読み取る `sensitivity` によって、または `memory.set` と `memory.update` が付与する `sensitivity:high` タグによって、`high` の行を判別します。`memory.bulk_get` が `sensitivity` を返さないプライベート Loom に対しては、すべての行が手元に残ります(エクスポートはそれらを「no known sensitivity」として数えます)。そのためバンドルにコンセプトが含まれず、`--prune` はそれを拒否します。prune はトゥームストーンです。値は 14 日間復元でき、公開 Loom のバージョン履歴にも残ります。公開 Loom から消す必要がある内容は、[消去](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/retention-and-erasure.md)の手順で処理してください。
+
+
+
+## ネットワーク
+
+NetworkPolicy は ingress を一切許可しません。egress は、DNS、プライベート Loom の web Pod への 7777 番ポート、およびパブリック Loom のアドレスへの 443 番ポートに限定されます。NetworkPolicy はホスト名ではなくアドレスで照合します。パブリック Loom のアドレスは `ipBlock` に列挙してください。アドレスが変わる場合は、CNI のホスト名ポリシーまたは egress プロキシを使用してください。
+
+プライベートリリースで `networkPolicy.enabled` を `ingressFrom` とともに設定する場合は、ジョブの Pod(`app.kubernetes.io/name: okf-sync`)またはその名前空間を `ingressFrom` に追加してください。追加しないと、リリース自身のポリシーによってエクスポートが拒否されます。
+
+
+
+## 関連項目
+
+- [OKF バンドル](https://github.com/ClickHouse/loom/blob/main/docs/features/integrations/okf.md):バンドル形式とインポートについて説明します。
+- [Kubernetes](https://github.com/ClickHouse/loom/blob/main/docs/operations/kubernetes.md):CronJob がポッドのセキュリティ設定を引き継ぐチャートです。
diff --git a/i18n/.pending/ja/docs/operations/supported-versions.md b/i18n/.pending/ja/docs/operations/supported-versions.md
new file mode 100644
index 0000000000..793f55c0d0
--- /dev/null
+++ b/i18n/.pending/ja/docs/operations/supported-versions.md
@@ -0,0 +1,52 @@
+
+> このページは[英語の原文](https://github.com/ClickHouse/loom/blob/main/docs/operations/supported-versions.md)の機械翻訳です。内容は英語の原文が優先されます。
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/operations/supported-versions.md), which is authoritative.
+
+
+
+# サポート対象バージョン
+
+リリース N と N−1 には修正が提供されます。`X.Y` の SDK は、`X.Y` または `X.(Y−1)` のサーバーと組み合わせて動作します。Loom は、サーバー、2 つのイメージ、Web アプリ、2 つの SDK、ルートの skills、Helm チャートの `appVersion` に対して、単一のバージョンを配布します([リリース手順](https://github.com/ClickHouse/loom/blob/main/docs/development/release-process.md))。このページでは、コーディングエージェント用プラグインについてと、何かを削除する変更をどのように告知するかについても説明します。
+
+
+
+## リリースライン
+
+| ライン | 提供される内容 |
+| ---- | ------------------------------------------------------------------------------------------------- |
+| N | 最新のマイナーリリース(`X.Y`):すべての修正。待てない場合はパッチリリース(`X.Y.(Z+1)`)として提供されます |
+| N−1 | その1つ前のマイナーリリース:セキュリティ修正、およびデータ損失や誤った回答に対する修正がパッチとして提供されます |
+| N−2 | なし:N または N−1 にアップグレードしてください |
+
+マイナーリリースは約 2 週間ごとに `main` から作られます。パッチは、そのラインの `release/X.Y` ブランチから作られ、修正は先に `main` にマージされます。アップグレードは[アップグレード](https://github.com/ClickHouse/loom/blob/main/docs/operations/upgrades.md)に従います。隣り合う 2 つのバージョンは、一方が他方に置き換わる間、並行して稼働できます([ローリングアップグレード](../architecture/rolling-upgrades.md))。
+
+
+
+## SDK とサーバー
+
+SDK(PyPI の `clickhouse-loom` と npm の `@clickhouse/loom`)は、リリースごとにサーバーと同じバージョンで公開されます。npm の `latest` は最も高い正式版を指し、古いラインへのパッチには `release-X.Y` の dist-tag が付きます。古いサーバーに対しては、次のようになります。
+
+- SDK が送信するフィールドを古いサーバーが認識しない場合、リクエストは処理され、そのフィールドは応答の `ignored_args` に記載されます。ただし、状態を変更する op では、サーバーがそのフィールドのいずれかのつづり間違いと判断するキー(近い名前、同義語、フィールド名の一部の単語)は `422 UNKNOWN_ARGUMENT` で拒否され、何も書き込まれません([不明なフィールドと削除されたフィールド](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#unknown-and-removed-fields))。
+- 古いサーバーが提供しない操作は `404` で応答し、SDK はこれを `NotFound` として送出します(Python では `loom.errors.NotFound`、TypeScript では `NotFound`)。そのため、実行できないサーバーに対する呼び出しが黙って成功することはありません。同じエラーは行が存在しない場合も意味するため、両者を区別する必要があるクライアントは、起動時に `ops.capabilities` を読み取ります([デプロイメントが提供する機能の確認](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#discovering-what-a-deployment-serves))。
+
+メジャーリリース(`X.0`)では、直前の `(X−1).Y` サーバーに対してこのルールが破られる場合があります。`X.0` の SDK に必要な条件は、そのリリースノートに記載されます。
+
+古い SDK は、呼び出す機能をサーバーが提供し続ける限り、新しいサーバーに対して動作し続けます。削除については、以下のルールに従います。
+
+
+
+## コーディングエージェント用プラグイン
+
+Claude Code と Codex のプラグインは独自のバージョンを持ち、フックがサポートする最も古いサーバーを示します(`lib/server-version.mjs` の `MIN_SERVER_VERSION`)。古いサーバーに対するセッションは、その旨を伝える `loom:` の 1 行で始まり、プラグインは可能な範囲で動作し続けます([Claude Code](https://github.com/ClickHouse/loom/blob/main/docs/features/integrations/claude-code.md))。Claude Code プラグインには Claude Code 2.1.139 以降が必要です。これは、フックの `args` をシェルなしで実行する最初のバージョンです。
+
+
+
+## 削除について
+
+削除は、削除を行うリリースの 1 つ前のマイナーリリースのリリースノートにある「What changed for clients」の項に、リリースのプルリクエストで手作業により記載して告知されます。削除までの間、サーバーは古いフィールドや op を提供し続けます。削除後は、削除されたリクエストフィールドも引き続き受け付けられて `ignored_args` に記載されるため、それを送信するクライアントは失敗せずに変更を知ることができます。削除された op は `404`(`NotFound`)で応答し、これは `ops.capabilities` によって行の欠落と区別できます。
+
+
+
+## リリース成果物
+
+すべてのリリースイメージは、実行されるアーキテクチャ上でビルドされ、修正が存在する重大な脆弱性についてスキャンされ、プロベナンスと SBOM とともに公開されます。各イメージのマルチアーキテクチャインデックスには、リリースワークフローによるキーレス署名が付きます。`cosign verify` コマンドについては[コンテナイメージ](https://github.com/ClickHouse/loom/blob/main/docs/operations/deployment.md#container-images)を参照してください。GitHub Release 上の各ファイルも同じ方法で署名され、隣に `.sigstore.json` として置かれます。`cosign verify-blob` コマンドについては[リリースファイル](https://github.com/ClickHouse/loom/blob/main/docs/operations/deployment.md#release-files)を参照してください。
diff --git a/i18n/.pending/ja/docs/operations/upgrades.md b/i18n/.pending/ja/docs/operations/upgrades.md
new file mode 100644
index 0000000000..4ba8965760
--- /dev/null
+++ b/i18n/.pending/ja/docs/operations/upgrades.md
@@ -0,0 +1,211 @@
+
+> このページは[英語の原文](https://github.com/ClickHouse/loom/blob/main/docs/operations/upgrades.md)の機械翻訳です。内容は英語の原文が優先されます。
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/operations/upgrades.md), which is authoritative.
+
+
+
+# アップグレード
+
+アップグレードでは、イメージ(および状態を持たないドキュメント抽出器のイメージ)を置き換え、新しいビルドに含まれるマイグレーションを適用します。それ以外の状態は移動しません。永続的なデータはすべて ClickHouse に保存されており(`LOOM_DOCUMENT_OBJECT_STORE=s3` で書き込まれた原本については、ドキュメントバケットにも保存されています)、コードミラーはそのままマウントされます。このページは運用者向けの内容です。クライアントから見た未知のフィールドや削除されたフィールドの扱いについては、[HTTP API リファレンス](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#unknown-and-removed-fields)を参照してください。修正が提供されるリリースと、サーバーごとに動作する SDK の対応については、[サポート対象バージョン](https://github.com/ClickHouse/loom/blob/main/docs/operations/supported-versions.md)を参照してください。
+
+
+
+## マイグレーションの実行方法
+
+ジャーナル、番号付け、ランナーディレクティブ、マイグレーションを書く際のルールは [マイグレーション](https://github.com/ClickHouse/loom/blob/main/docs/development/migrations.md) にあります。オペレーターが知っておくべき内容は次のとおりです。
+
+- **起動時。** サーバーは、準備完了を報告する前、およびワーカーを起動する前に、未適用のファイルを適用します(`LOOM_BOOT_MIGRATE=true`、デフォルト)。どのコンテナのどのプロセスも `loom._migration_lock` 内の `KeeperMap` ロックを取得するため、各ファイルは一度だけ適用されます。Keeper のないサーバーは拒否されます。
+- **プロバイダーの再構築。** 未適用のファイルがある状態で起動すると、まずプロバイダー参加者として登録します。次にプロバイダー設定ロック(Keeper のキー 1 つで、このチェックの間だけ保持)の下で、未完了のプロバイダー再構築がないことを確認し、あれば `Finish the provider rebuild before applying schema migrations` を出力してマイグレーションを拒否します。その後、ファイルはマイグレーションロックのみの下で適用されます。その間に開始された再構成は、起動中のプロセスが確認応答するまで待機するため、再構築がマイグレーションと並行して実行されることはありません。
+- **マイグレーションや再構成の最中にコンテナが強制終了された場合**、他のコンテナはしばらくの間だけブロックされます。マイグレーションロックは、保持者が更新を止めてから(`ttl_s`)引き継がれます。プロバイダーロック(TTL 60 秒、20 秒ごとに更新)は、期限切れになり、かつ保持者の参加者行も期限切れになった時点で引き継がれます。つまり、60 秒間ハートビートがなく(ハートビートは 10 秒ごと)、どのノードの `system.processes` にもその id でタグ付けされたクエリがない状態です。同時に起動したコンテナは、失敗せずにプロバイダーロックを最大 120 秒待ちます。保持者に参加者行がないロックは、そのプロセスが停止したことを確認してから `loom provider-lock clear --holder ` で解放します。保持者が更新、ハートビート、またはクエリ実行を続けている間は、このコマンドは拒否されます。
+- **ミューテーション。** ファイルは、そのミューテーションが完了して初めて記録されます。ミューテーションが失敗した場合、または `LOOM_MIGRATE_MUTATION_WAIT_S`(デフォルト 600)を超えて実行された場合は、そのファイルが失敗となり、ログにファイル名を示して起動が停止します。
+- **キーの変更。** ソートキーまたはパーティションキーを変更するマイグレーションは、空のテーブルであれば自身で再構築し、行のあるテーブルでは起動を失敗させます。そのテーブルについては、デプロイ前に `scripts/ops/table_rebuild.py` を実行してください。厳密なドライランで検出できます。
+- **新規インストール。** 新規インストールとアップグレードは同じ経路です。サーバーは、台帳にないものをすべて再生します。空のデータベースでは、ジャーナル全体が対象となり、数分かかります。
+- **途中で止まった台帳。** ベースラインが置き換えるファイルの途中で台帳が止まっているデータベースは拒否されます(`stranded`)。先に、そのベースラインより前のビルドでマイグレーションしてください。
+- **番号が振り直されたファイル。** リポジトリに該当ファイルがなくなった台帳の行は `ledger-only` となり、`--strict` は 1 で終了します。ただし、記録された SHA-256 が現行ファイルのものと一致する場合は例外で、これは新しい番号の下にある同じファイルです。ランナーはこれを renamed として報告し、未適用であれば再実行せずに新しい名前を記録し、`--strict` は成功します。古い名前で実行された後に編集されたファイルは SHA-256 が異なるため、ledger-only のままです。新しい名前は未適用ファイルとして実行され、古い行は手動で削除します([トラブルシューティング](https://github.com/ClickHouse/loom/blob/main/docs/operations/troubleshooting.md#migrations-pending-or-checksum-drift))。それまでは、`/v1/health` が古い行を `schema.ledger_only` の下に列挙します。
+
+CLI では、同じランナーを手動で実行できます。
+
+```bash
+loom migrate --status # applied and pending; changes nothing
+loom migrate --dry-run --strict # pending files; exit 1 on ledger-only rows (not renames) or checksum drift
+loom migrate # apply pending migrations
+loom migrate --target N # apply through file number N only
+```
+
+`make migrate`、`make migrate-status`、`make migrate-dry` は、チェックアウトしたリポジトリから同じモジュールを実行します。
+
+
+
+## アップグレード手順
+
+1. リリースの [GitHub リリース](https://github.com/ClickHouse/loom/releases)のノートを読み、オペレーター向けの手順(新しい設定、デプロイメントで実行が必要なバックフィル)と、クライアントから見えるワイヤ形式の変更を確認します。
+2. 新しいビルドのチェックアウトから、本番の ClickHouse に対して `loom migrate --dry-run --strict` を実行します。起動時に適用される内容を一覧し、台帳に問題があれば停止します([トラブルシューティング](https://github.com/ClickHouse/loom/blob/main/docs/operations/troubleshooting.md#migrations-pending-or-checksum-drift))。リリースがテーブルの再構築を宣言している場合は、そのテーブルに対して今のうちに `scripts/ops/table_rebuild.py` を実行します。Postgres authority のデプロイメントが、ナレッジドキュメントのヘッドを Postgres に保持するビルドへ移行する場合は、今のうちに `LOOM_RETENTION_DOCUMENTS_DAYS` を手作業で unset します。新しいビルドはこれが設定されたままだと起動を拒否し、その authority では保持期間の TTL が `loom.documents` に及ばず、名前空間の `retention_days` も `loom.chunks` に及びません([ローリングアップグレード](../architecture/rolling-upgrades.md)、ルール 38)。セッションに印を付け、org トリガー(ルール 47)を備えるビルドへ移行する[セル](https://github.com/ClickHouse/loom/blob/main/docs/architecture/cells.md)は、先に `LOOM_PG_DSN` をプーラーを介さず Postgres へ直接向けます([Postgres](https://github.com/ClickHouse/loom/blob/main/docs/operations/postgres.md))。また、準備したあとに `LOOM_CELL` を unset して取りやめた後発のセルは、先にその状態をクリアします([トラブルシューティング](https://github.com/ClickHouse/loom/blob/main/docs/operations/troubleshooting.md#a-process-with-loom_cell-unset-is-gated))。新しいビルドは、自身のプロセスをその状態でゲートするためです。すでに準備済みの後発のセルでは、新しいビルドの最初のマイグレーション起動で org トリガーが作成されます。そのため、そこで動き続けている古い Pod は、置き換えられるまでテナント org の行の挿入がすべて拒否されます(呼び出し元にはマップされないエラーとなります)。セルは 1 ステップでロールアウトしてください。
+3. 新しいイメージをデプロイします。最初に起動したコンテナがマイグレーションを適用し、他のコンテナはその完了を待って、保留中のものがないことを確認します。
+4. トラフィックを向ける前に、`/v1/health` が `status: ok` を報告し、`schema.pending` が空になるまで待ちます。[ゼロダウンタイムペア](https://github.com/ClickHouse/loom/blob/main/docs/operations/deployment.md#zero-downtime-pair)は、ステップ 2 で挙げた設定の unset を除き、ステップ 2 から 4 を代行します。`redeploy.sh` は事前チェックで strict ドライランを実行し、新しい色の準備ができてから切り替えます。
+5. リリースにバックフィルがあれば実行します([メンテナンス](https://github.com/ClickHouse/loom/blob/main/docs/operations/maintenance.md#backfills-and-repairs))。
+6. リリースでプラグインの変更が触れられている場合は、クライアントプラグインを更新します。フックはクライアントマシン上で動作し、クライアントのプラグインマネージャー(Claude Code では `claude plugin update loom@loom`)からしか変更できず、サーバーのデプロイでは変わりません。
+7. 最後の旧レプリカが停止したら、ロールアウト中に完了した消去を再検証します:`loom erasure-re-verify --completed-since --resume`。旧レプリカの saga は、新しいビルドが追加したテーブルを知りません([ローリングアップグレード](../architecture/rolling-upgrades.md)、ルール 14)。このコマンドが削除するのは孤立した行リンクだけです。つまり、各消去のスコープ内にある `entity_triple_rows` と `entity_edge_rows` の行のうち、そのメモリに有効な行がなく、消去の census 以降に書かれた行もないものです。`--resume` を付けない場合は件数を数え、残りがあれば 1 で終了します。消去の後に書かれたデータは残ります。
+8. 前のビルドが対応できない機能は、すべてのレプリカが新しいビルドで動くようになってから有効にします。対象は次のとおりです。`memory_extract_agent_learnings`:前のビルドは `loom.learnings_supporters` を消去しないためです([ローリングアップグレード](../architecture/rolling-upgrades.md)、ルール 23)。`LOOM_DOCUMENT_OBJECT_STORE=s3`:前のビルドはバケット行の空の `data` を読み、そのダウンロードに `410 BLOB_GONE` を返すためです(ルール 9)。`LOOM_PG_PAYLOAD_CLEAR_ENABLED`:新しいビルドが単独で稼働してから、クリア期間(clearing horizon)1 つ分より早くならないようにします。前のビルドは遅れて届いた配信に印を付けないためです(ルール 43)。
+9. `LOOM_CODE_ASK_MEMORY_NAMESPACE` が現在、または過去のいずれかの時点で設定されているデプロイメントが、キャッシュされた `code.ask` の回答が引用したメモリを示さないビルド(`086_code_answer_memory_scope.sql` より前)から、示すビルドへ移行する場合(ロールバック後のロールフォワードも含む):新しいビルドが単独で稼働し、プロバイダーの再構築が実行されていない状態になったら、`TRUNCATE TABLE .code_answers`(デフォルトでは `loom.code_answers`)で回答キャッシュをクリアします。古いビルドの回答とトゥームストーンはメモリを示さず、ロールアウト中にそのビルドが実行した消去や redact もこのテーブルを知らなかったため([ローリングアップグレード](../architecture/rolling-upgrades.md)、ルール 36)、どの saga もそこに残るものを見つけられません。再構築はテーブルのコピーを上から公開するので、truncate をまたいで実行中の再構築があると、行が戻ってきます。truncate はパートを即座に、レプリケートされたテーブルでは全レプリカで削除し、待つべき mutation はなく、loom ユーザーはその権限を持っています。クリアされた質問は、次に尋ねられたときに 1 回ずつ合成のコストがかかります。
+10. ユーザーのメモリを集約した統合サマリーが取り込んだものにまで、ユーザー消去が及ぶビルドへ移行する場合(ロールバック後のロールフォワードも含む):新しいビルドが単独で稼働したら、それ以前に `purge` なしで要求された各ユーザー消去を再度要求します(`loom.erasure_requests` の `user_id` 行、90 日間保持)。新しいビルドが完了させたものも含みます。古いビルドの saga は、サマリーの履歴、チャンク、ベクトル、グラフ行、共有コピーを残していました([ローリングアップグレード](../architecture/rolling-upgrades.md)、ルール 37)。新しい saga は、そのユーザーがその後に書いたものも消去します。有効なメモリ行を持たないユーザーに対して、または、それが望ましい場合にだけ要求してください。古いビルドが完了させたユーザー purge も同じ行を残しており、以後のユーザー消去ではそれらを見つけられません。ユーザーのキーがすでにないためです。`shared.tombstone` を過ぎるところまで実行された消去は、どのビルドが完了させたかにかかわらず、そのユーザー自身のメモリの共有コピーの検索行も残しました。古いビルドが `agent="*"` で昇格させた共有コピーは、ソースエージェントとして `*` を名乗り、コピー元のユーザーの消去ではどれも見つからないことがあります。それらを一覧し、消去されたユーザーのテキストを保持しているものは、それぞれ確認のうえ `memory.demote` で処理します。
+
+ ```sql
+ SELECT org, namespace, memory_key FROM loom.shared FINAL
+ WHERE tombstoned_at IS NULL AND arrayExists(x -> splitByChar('/', x)[3] = '*', promoted_from)
+ ```
+
+11. Postgres authority のデプロイメントが、ナレッジドキュメントのヘッドを Postgres に保持するビルド(`002_knowledge_documents.sql`)へ移行する場合(ロールバック後のロールフォワードも含む):新しいビルドが単独で稼働したら、新しいビルドが最初に稼働して以降、古いビルドのレプリカが稼働している間に完了したすべての消去を再実行します。古いビルドの消去は、ヘッドも配信も削除しません。消去されたドキュメントのテキストは、消去が再実行されるまで `loom.knowledge_heads` に残り、残された配信は配信ワーカーによって再度公開されます([ローリングアップグレード](../architecture/rolling-upgrades.md)、ルール 38)。パークされた配信を再試行する前に実行してください。
+12. Postgres authority のデプロイメントが、ナレッジ取り込みジョブ(`005_knowledge_jobs.sql`)またはデータセットカタログ(`007_knowledge_datasets.sql`)を Postgres に保持するビルドへ移行する場合(ロールバック後のロールフォワードも含む):新しいビルドが単独で稼働したら、新しいビルドが最初に稼働して以降、古いビルドのレプリカが稼働している間に完了したすべての消去を再実行します。古いビルドの消去は、`loom.knowledge_jobs` からジョブを、`loom.knowledge_datasets` からカタログ行を削除しません。新しいビルドのワーカーはそのようなジョブを `loom.knowledge_ingestions` に射影し直して実行し、カタログ行は消去が再実行されるまで残ります([ローリングアップグレード](../architecture/rolling-upgrades.md)、ルール 40 と 42)。ステップ 11 の実行は、ヘッド、ジョブ、カタログ行をまとめてカバーするため、消去 1 件につき 1 回の実行で足ります。その期間に古いビルドが応答した `knowledge.delete` と `knowledge.bulk_delete` も、それぞれ再度要求してください。これらはソースのデータセットを `loom.datasets` からしか削除しませんでした。
+13. あらゆる名前空間でドキュメントソースを保持するビルドへ移行する場合(ロールバック後のロールフォワードも含む):新しいビルドが単独で稼働したら、古いビルドの `namespace.delete`、`collection.delete`、または名前空間の消去がアクティブなまま残したソースを廃止します([ローリングアップグレード](../architecture/rolling-upgrades.md)、ルール 44)。削除された名前空間上のソースは次のとおりです。
+
+ ```sql
+ SELECT s.org, s.namespace, s.name
+ FROM (SELECT org, namespace, name FROM loom.knowledge_sources FINAL WHERE active) AS s
+ INNER JOIN (SELECT org, namespace FROM loom.namespaces FINAL WHERE NOT active) AS n
+ ON s.org = n.org AND s.namespace = n.namespace
+ ```
+
+ また、名前空間の消去が完了する前に登録され、その消去が廃止しなかったソース(古いビルドが実行した消去のもの、または新しいビルドの消去の実行中に古いビルドが追加したもの)は次のとおりです。
+
+ ```sql
+ SELECT s.org, s.namespace, s.name, e.id
+ FROM (
+ SELECT org, namespace, name, active, created_at, updated_at
+ FROM loom.knowledge_sources FINAL
+ ) AS s
+ INNER JOIN (
+ SELECT id, org, completed_at,
+ arrayJoin(if(scope_type = 'namespace', [scope_value],
+ if(JSONType(scope_value) = 'Array',
+ JSONExtract(scope_value, 'Array(String)'),
+ JSONExtract(scope_value, 'namespaces', 'Array(String)')))) AS namespace
+ FROM loom.erasure_requests FINAL
+ WHERE scope_type IN ('namespace', 'namespace_list') AND status = 'completed'
+ ) AS e ON s.org = e.org AND s.namespace = e.namespace
+ WHERE s.created_at <= e.completed_at AND (s.active OR s.updated_at > e.completed_at)
+ ```
+
+ 1 つ目のクエリの結果については、一覧された各ソースを削除する(`knowledge.source.remove`)か、新しいビルドでその名前空間を再度削除します。再削除すればソースは廃止されます。2 つ目については、一覧された各ソースを `knowledge.source.remove` と `delete_documents=true` で削除します。これにより、そのソースが書き戻したドキュメントが廃止されます(すでに廃止されたソースも受け付けます。たとえば、その名前空間を後から削除して廃止されたソースです)。さらに、それらから抽出された decision 行を `memory.delete` で削除します。新しいビルドによる名前空間の消去は両方を行いますが、最初の消去以降にその名前空間へ書かれたものもすべて消去します。再度要求するのは、それ以降に誰も書き込んでいない名前空間に限ってください。消去の後に登録されたソースは一覧に出ません。その消去はそのソースを対象にしていなかったためです。2 つ目の一覧は一度だけ処理するための作業リストです。上のように削除したソースも、その削除行が消去より新しいため、一覧に残り続けます。
+
+ 古いビルドが開始し、新しいビルドが完了させた名前空間の消去には、ここでの作業は不要です。最終 census が、そのソースが書き戻したドキュメントと decision を見つけてそのステップを再度開くため、それらがなくなって初めて saga が完了します。
+
+14. 名前空間の消去が `loom.shared` に及ぶビルドへ移行する場合(ロールバック後のロールフォワードも含む):新しいビルドが単独で稼働したら、古いビルドの名前空間の消去が残した昇格済みの行をクリアします([ローリングアップグレード](../architecture/rolling-upgrades.md)、ルール 45)。以下のクエリは、台帳(90 日間保持)にある `namespace` または `namespace_list` の消去が及んだ名前空間のうち、昇格済みの行を持つものを一覧します。あわせて、purge なし(`erased_at`)と purge あり(`purged_at`)それぞれの最後の消去が census を実行した時刻を示します。この後の文は、その時刻(秒)より前に昇格された行を対象とするため、census より後に昇格された行は残ります。census と同じ秒の中でそれ以前に昇格された行も、`promoted_at` の秒単位の精度では区別できないため残ることがあります。新しいビルドのステップは、自身が実行した消去ではそのような行もすでに処理しています。purge するのは `namespace_list` だけであり、古いビルドの `namespace` 行には、要求されたフラグが入っていることがあります。
+
+ ```sql
+ SELECT org, namespace,
+ maxIf(counted_at, NOT purged) AS erased_at,
+ maxIf(counted_at, purged) AS purged_at
+ FROM (
+ -- The census's time: a row promoted after it was never in the erasure's reach.
+ SELECT org, ifNull(verified_at, completed_at) AS counted_at,
+ scope_type = 'namespace_list' AND purge AS purged,
+ arrayJoin(if(scope_type = 'namespace', [scope_value],
+ if(JSONType(scope_value) = 'Array',
+ JSONExtract(scope_value, 'Array(String)'),
+ JSONExtract(scope_value, 'namespaces', 'Array(String)')))) AS namespace
+ FROM loom.erasure_requests FINAL
+ WHERE scope_type IN ('namespace', 'namespace_list') AND status = 'completed'
+ )
+ -- Only a namespace that holds a promoted row has anything to clear.
+ WHERE (org, namespace) IN (SELECT org, namespace FROM loom.shared)
+ GROUP BY org, namespace
+ ```
+
+ それぞれについて、新しいビルドのステップが実行する内容を、消去の census より前に昇格されたすべてのバージョンに対して実行します。同じキーの後の昇格によって `FINAL` から隠れたバージョンも含みます。`purged_at` が設定されている場合は、それらを削除します。
+
+ ```sql
+ ALTER TABLE loom.shared DELETE
+ WHERE org = '' AND namespace = '' AND promoted_at < ''
+ SETTINGS mutations_sync = 2
+ ```
+
+ `erased_at` が設定されている場合は、残っている有効な行をトゥームストーンにします。
+
+ ```sql
+ ALTER TABLE loom.shared UPDATE tombstoned_at = toDateTime('')
+ WHERE org = '' AND namespace = '' AND tombstoned_at IS NULL
+ AND promoted_at < ''
+ SETTINGS mutations_sync = 2
+ ```
+
+ この設定により、各文は全レプリカで完了するまで待たれます。時刻はステップがバインドするのと同様にリテラルで書きます。レプリケートされたテーブルは、`now()` のような非決定的な関数を呼ぶ mutation を拒否するためです。台帳の 90 日より前に要求された名前空間の消去は一覧に出ず、それが残した昇格済みの行は有効な名前空間のものと区別できません。それらは古いビルドが残したままになります。
+
+15. 組織を宣言するすべての CLI コマンド(コードインデックスのコマンド、インポート)がデプロイメントを確認するビルドへ移行する場合:どちらの authority でも、その ClickHouse ユーザーには `loom.storage_authority` への `SELECT` が必要で、コマンドは別の authority を記録しているデプロイメントに対しては実行を拒否します。Postgres authority では、さらに `LOOM_PG_DSN` が必要で、セルの状態を読みます(`LOOM_CELL` が unset の場合は、専用のセッションで読みます)。`LOOM_CELL` が設定されている場合、どの org にも書き込まないがセルのストアを変更するコマンド(`loom settings set`、`loom secrets reseal`、`loom code compact` など)やアクセスを取り消すコマンドも、同じ方法でデプロイメントを確認し、専用のセッションでセルの `first` 行を読みます。接続に使う Postgres ロールに、次の権限を付与します。
+ - `LOOM_CELL` が unset の場合:スキーマ `loom` への `USAGE`、`loom.cell_first`、`loom.tenancy_mode`、`loom.authority` への `SELECT`、`loom.cell_self` への `SELECT (updated_at)`、`loom.tenancy` への `SELECT (since)`(列権限により、フィンガープリントと org にはアクセスできません)、そして `LOOM_PG_POOL_MAX_SIZE` に、同時に実行されるそのようなコマンドの数を掛けた値以上の `CONNECTION LIMIT`。各コマンドは書き込み用に専用のプールを開くためです(状態の読み取りは、上限に達した場合に短時間再試行したのち、拒否されます)。
+ - `LOOM_CELL` が設定されている場合:上と同じ権限に加えて、`loom.cell_self` と `loom.tenancy` への `SELECT` を全列に付与します。最初のセルが `recording` の間に新しい org を記録するには、`loom.tenancy` への `INSERT` と `loom.tenancy_mode` への `UPDATE (since)` も付与します。セルが接続(attach)されたら、`LOOM_CELL_ROUTER_TOKEN` とともに両方を取り消します。ドキュメントバケットの設定(`LOOM_DOCUMENT_S3_BUCKET`、`LOOM_DOCUMENT_S3_PREFIX`)はサーバーのものと同じにします。
+
+ 列権限のみを持つロールが、`recording` を過ぎたセルに対して行う書き込みは、`LT001` ではなく権限エラー(SQLSTATE 42501)として拒否されます。
+
+16. 最初のセルの attach の前に、すべての CLI と CI イメージは、その状態を読み取るビルドで実行され、組織向けに書き込むすべての CLI には `LOOM_CELL` が設定されています。CLI はハートビートを送信しないため、attach ではどちらも確認できず、古いビルドの CLI は `enforced` のセルで拒否されません([セル](https://github.com/ClickHouse/loom/blob/main/docs/architecture/cells.md#failure-modes))。
+
+17. 最初のセルのプロセスが、タイマーでルーターからそのセルの状態を読み取るビルドへ移行する場合:どのセルのプロセスよりも先に、すべてのルーターレプリカ(`loom router serve`)がこのビルドで実行されている必要があります。準備済みの最初のセルの各プロセスは、最初のセル状態の読み取りから `serving` を読み取るまで、ルーターの状態ルートに問い合わせます。以前のビルドのルーターは、そのような呼び出しのたびにディレクトリを読み取ります。読み取りは、サーバープロセスごとにおよそ `min(LOOM_INSTANCE_HEARTBEAT_SECONDS, LOOM_TENANCY_MODE_CACHE_S)` あたり 1 回で、デフォルト設定では、8 ワーカーの Pod 1,000 個で毎秒 1,600 回の読み取りになります。このビルドのルーターは、レプリカごとに `LOOM_ROUTER_DIRECTORY_CACHE_S` あたり 1 回の読み取りでこれらに応答します([セル](https://github.com/ClickHouse/loom/blob/main/docs/architecture/cells.md#the-heartbeats-keys))。
+
+マイグレーションの適用中も、古いビルドは稼働し続けます。すべてのマイグレーションは追加的なものだからです。2 つのビルドを並行して稼働させるためのルールは、[ローリングアップグレード](../architecture/rolling-upgrades.md)にあります。
+
+
+
+## ロールバック
+
+以前のイメージを再デプロイします。ペアの場合は `./redeploy.sh --rollback` を実行します。アシスタントターンの learnings を持たないビルドへロールバックする前に、`memory_extract_agent_learnings` をオフにし、`loom.learnings_supporters` の行と、`loom.learnings_queue` の `assistant_turn` 行を削除します([抽出](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/extraction.md#rules-the-assistant-states-about-itself))。以前のビルドは、昇格したボットのルールを、そのボットだけでなく名前空間内のすべてのエージェントに提供します。これを防ぐには、ロールバックの前に `knowledge.delete` で `source-kind:assistant_turn` タグの付いたドキュメントを削除します。削除しない場合は、提供範囲が広がることを受け入れてください。
+名前空間ガイドが存在するようになった後に、以前のビルドが実行した名前空間の消去は、その名前空間のガイドを残します。新しいビルドが再び提供を始めたら、消去をもう一度実行してください([ローリングアップグレード](../architecture/rolling-upgrades.md)、ルール 24)。以前のビルドが実行した名前空間の消去は、その名前空間の昇格済みの行を有効なまま残します。新しいビルドが再び提供を始めたら、アップグレード手順のステップ 14 でそれらを一覧できます(ルール 45)。
+ボットのトークン最大値を持たないビルドへロールバックすると、すべてのボットのトークンの有効期間が 1 時間になり、そのビルドが保存するボットは最大値として 3600 を保持します。新しいビルドが提供を始めたら、より短い値または長い値を再設定してください([ローリングアップグレード](../architecture/rolling-upgrades.md)、ルール 26)。
+以前のビルドが実行したユーザーの消去は、そのユーザーのメモリの要約が取り込んだ内容を残します。新しいビルドが提供を始めたら、`purge` なしで実行した消去をそれぞれ、ステップ 10 と同様にもう一度要求してください。完了した purge は再び見つかりません(ルール 37)。
+ドキュメントバケットを追加したビルドより前へは、カタログのいずれかの行がバケット内のオブジェクトを指している間はロールバックしないでください。古いビルドはそれらのダウンロードに `410 BLOB_GONE` を返し、その消去は行を削除してもオブジェクトには到達できず、そのスイープはバケットを走査しません([原本の保存場所](https://github.com/ClickHouse/loom/blob/main/docs/features/knowledge.md#where-originals-are-stored))。
+`086_code_answer_memory_scope.sql` より前のビルドへロールバックし、メモリの名前空間を `code.ask` にバインドしている場合は、ステップ 9 と同様に回答キャッシュを 2 回クリアします。1 回目は古いビルドだけが提供しているとき、2 回目は新しいビルドが再び提供を始めたときです。マイグレーションはすでに台帳にあるため、ロールフォワードでは 2 回目を促すものは何も適用されません。
+ロールバックの前に `LOOM_PG_PAYLOAD_CLEAR_ENABLED` をオフにします。オンに戻すのは、新しいビルドが再び単独で提供を始めてから、クリアの期間(clearing horizon)が 1 回分経過した後にしてください。クリアのパスが一度実行された後は、`010_revision_delivered_at.sql` を含むビルドでのみ `loom reconcile` を実行し、その後はそのビルドでデプロイメントを起動してください。ロールバックするのは、新しいビルドに、クリア済みリビジョンに対する取得可能な未配信がなくなってからにします。次のクエリが 0 を返せば、その状態です(ルール 43)。
+
+```sql
+SELECT count(*) FROM loom.memory_deliveries d
+JOIN loom.memory_revisions r USING (org, namespace, seq)
+WHERE r.row IS NULL AND NOT d.settled AND d.lease_until <> 'infinity';
+```
+
+0 になるまでは、新しいビルドにそれらを配信させてください。以前のビルドは保留中(parked)の配信を取得しないため、保留中のものは残ってかまいません。以前のビルドが提供している間、再試行はクリア済みのリビジョンを除外し([Postgres の運用](https://github.com/ClickHouse/loom/blob/main/docs/operations/postgres.md#what-the-boot-checks))、`loom reconcile` は実行しません。実行すると、reconcile が保持していたものが以前のビルドに解放されてしまいます。
+準備済みのセル(`loom.cell_first` の行を持つもの)を、[セル](https://github.com/ClickHouse/loom/blob/main/docs/architecture/cells.md)の org トリガーを持たないビルドへロールバックする前に、新しいビルドのすべての Pod を停止してください。その後、[LOOM_CELL が未設定のプロセスはゲートされる](https://github.com/ClickHouse/loom/blob/main/docs/operations/troubleshooting.md#a-process-with-loom_cell-unset-is-gated)のトリガー削除のみを実行し、その状態トランザクションは実行しません(セルは準備済みのままです)。ロールバックが終わる前に新しい Pod がマイグレーション有効で起動した場合は、もう一度実行してください。古いビルドのセッションはテナンシーマーカーを送らないため、新しいビルドがトリガーと `loom.tenancy` ガードを作成した後は、セルがテナンシー行を持たない org に対する書き込みはすべて拒否されます(アタッチ前の後続セルでは、すべてのテナント org が対象です)。新たに配置された各 org のテナンシー行も同様に拒否され、その他の書き込みにはトリガーの状態読み取りのコストがかかります。
+元に戻すマイグレーションはありません。以前のビルドは新しいスキーマを読み書きします。以前のビルドによる `loom.memory` やその他の `ReplacingMergeTree` メモリテーブルへの書き込みは、そのビルドが知らないカラムを保持します([ローリングアップグレード](../architecture/rolling-upgrades.md))。
+
+ダウンマイグレーションはありません。以前のスキーマに戻すには、アップグレード前に取得したバックアップをリストアしてください([バックアップとリカバリ](https://github.com/ClickHouse/loom/blob/main/docs/operations/backup-and-recovery.md))。
+
+
+
+### インストーラーによるインストールのダウングレード
+
+各インストーラーバンドルには、ビルドに使われた ClickHouse のリリースが指定されています。そのため、以前の Loom バージョンをインストールすると、新しい ClickHouse が書き込んだボリュームで以前の ClickHouse も動くことになり、読み取れない場合があります。Loom だけをロールバックするには、新しい ClickHouse を維持します。以前のインストーラーを実行する前に(スタックはすぐに起動します)、現在 ClickHouse が使っているイメージを、インストールディレクトリの `.env` に固定してください。次のコマンドは、そこに記述する行を出力します。既存の `LOOM_CLICKHOUSE_IMAGE` の行があれば置き換えてください。
+
+```bash
+dir=${LOOM_INSTALL_DIR:-$HOME/.loom}
+echo "LOOM_CLICKHOUSE_IMAGE=$(docker inspect -f '{{.Config.Image}}' \
+ "$(docker compose --project-directory "$dir" ps -q clickhouse)")"
+```
+
+次に、以前のリリースのインストーラーをそのバージョンを指定して実行します。古いインストーラーは、新しいインストールに対してそのままでは実行を拒否するためです。
+
+```bash
+curl -fsSL https://github.com/ClickHouse/loom/releases/download/vX.Y.Z/install.sh -o loom-install.sh && LOOM_VERSION=X.Y.Z sh loom-install.sh && rm loom-install.sh
+```
+
+ホームディレクトリ、またはあなただけが書き込める[別のディレクトリ](../getting-started/quickstart.md#fast-path-released-image-no-clone)から実行してください。
+
+インストーラーは `.env` を保持するため、この固定は以降のアップグレードでも ClickHouse を維持します。新しい Loom バージョンをインストールする前に `LOOM_CLICKHOUSE_IMAGE` の行を削除してください。また、シェルに `LOOM_CLICKHOUSE_IMAGE` をエクスポートしたままにしないでください。インストーラーは、与えられた値を `.env` に書き戻すためです。両方を元に戻すには、アップグレード前に取得したバックアップをリストアしてください。
+
+
+
+## アップグレード前後で変わらないこと
+
+| アップグレード前後 | 保証される内容 | 保証する仕組み |
+| --------------------------------------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------- |
+| 新しいスキーマに対する以前のビルド | 既知のすべてのテーブルを引き続き読み書きできるため、ロールバックにスキーマ操作は不要 | `tests/unit/test_migrations_additive.py` |
+| 適用済みのマイグレーションファイル | 編集も削除もしない。修正は新しいファイルとして追加する | ledger のチェックサム、`--dry-run --strict` |
+| サーバーが削除したフィールドを送るクライアント | 処理される。そのフィールドは `ignored_args` に記載される | `server/transport/arg_check.py` |
+| 以前のビルドと新しいビルドの同時稼働 | 新しいカラムを含め、それぞれが相手の書き込んだ内容を読める。ただしロールアウト後(手順 8)に初めて有効にした機能は除く | `make test-mixed-version` |
+
+アップグレードでは、オペレーションやフィールドが変更または削除されることがあります。デプロイメントが提供している内容は、機能カタログで確認できます([HTTP API](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#discovering-what-a-deployment-serves))。2 つのビルド間の変更点は `scripts/codegen/wire_changelog.py ` で一覧できます([コード生成](https://github.com/ClickHouse/loom/blob/main/docs/development/code-generation.md#wire-changelog))。
+
+
+
+## 関連ドキュメント
+
+- [デプロイ](https://github.com/ClickHouse/loom/blob/main/docs/operations/deployment.md#zero-downtime-pair): アップグレードを入れ替えだけで済ませるためのペア構成
+- [マイグレーション](https://github.com/ClickHouse/loom/blob/main/docs/development/migrations.md): 新しいマイグレーションが従うルール
+- [ローリングアップグレード](../architecture/rolling-upgrades.md): ビルド N-1 と N のためのルール
+- [トラブルシューティング](https://github.com/ClickHouse/loom/blob/main/docs/operations/troubleshooting.md#migrations-pending-or-checksum-drift)
diff --git a/i18n/.pending/ja/docs/reference/extractor-contract.md b/i18n/.pending/ja/docs/reference/extractor-contract.md
new file mode 100644
index 0000000000..f7bbb00279
--- /dev/null
+++ b/i18n/.pending/ja/docs/reference/extractor-contract.md
@@ -0,0 +1,178 @@
+
+> このページは[英語の原文](https://github.com/ClickHouse/loom/blob/main/docs/reference/extractor-contract.md)の機械翻訳です。内容は英語の原文が優先されます。
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/reference/extractor-contract.md), which is authoritative.
+
+
+
+# エクストラクターの契約
+
+エクストラクターは、Loom サーバーが元のファイルを送信し、その抽出アーティファクトを受け取る HTTP サービスです。
+このページは、両者間の契約のバージョン 1 です。サービスが提供しなければならないものを定めます。対象は、Loom のリファレンスエクストラクター(`extractor/loom_extractor/`)と、運用者が独自に用意するものです。パース処理をサーバーの外で実行する理由と、サーバーがレスポンスを読み取る方法については、[ドキュメント抽出](../architecture/document-extraction.md)を参照してください。
+
+
+
+## サーバーの設定
+
+| 設定 | 意味 |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `LOOM_DOCUMENT_EXTRACTOR_URL` | どのルートにも名前が挙がっていない形式が送られる先のベース URL |
+| `LOOM_DOCUMENT_EXTRACTORS_JSON` | `{format or media type: base URL}`。形式のキーはそのメディアタイプのキーより優先され(メディアタイプのキーは、そのメディアタイプの形式にのみ適用される)、どちらも上記の URL より優先される。形式を指さないキーや、同じメディアタイプの二つ目の表記は、読み込み時に拒否される |
+| `LOOM_DOCUMENT_EXTRACTOR_TOKEN` | 下記の専用トークンを持たないサービスに送信されるベアラートークン |
+| `LOOM_DOCUMENT_EXTRACTOR_TOKENS_JSON` | `{base URL: token}`。サービス専用のトークンであり、あるサービスが別のサービスが受け付けるトークンを保持することはない。各 URL は上記の二つの設定のいずれかに挙げられているものでなければならない |
+| `LOOM_DOCUMENT_EXTRACTOR_TIMEOUT_S` | 1 回の呼び出し全体に許される秒数。capabilities の読み取り、または元ファイルの送信とレスポンスの読み取りを含む |
+| `LOOM_DOCUMENT_EXTRACTOR_MAX_ARTIFACT_BYTES` | サーバーが読み取るレスポンスの最大サイズ。これを超えるレスポンスは `resource_limit` として拒否される |
+
+形式名は `markdown`、`html`、`text`、`sql`、`toml`、`pdf`、`docx`、`pptx`、`xlsx`、`csv`、`parquet` です。たとえば、PDF をオペレーター自身のサービスに送り、それ以外をリファレンス extractor に送るには、次のようにします。
+
+```bash
+LOOM_DOCUMENT_EXTRACTOR_URL=http://extractor:8790
+LOOM_DOCUMENT_EXTRACTORS_JSON='{"pdf": "http://pdf-extractor:8080"}'
+```
+
+
+
+## エンドポイント
+
+すべての呼び出しに `Authorization: Bearer ` を付けます。トークンがない、または誤っている場合、サービスは `401` を返します。
+
+
+
+### `GET /v1/capabilities`
+
+サービスが抽出できるものを返します。サーバーは、ルーティング先のサービスがここに一覧した形式だけを抽出し、1 分後にこの情報を再度読み込みます。
+
+```json
+{
+ "contract_version": 1,
+ "extractor": { "name": "loom-reference", "version": "1" },
+ "max_bytes": 67108864,
+ "formats": [
+ { "format": "markdown", "options": ["encoding"] },
+ { "format": "sql", "options": ["encoding", "sql_dialect"] }
+ ]
+}
+```
+
+| フィールド | 意味 |
+| ------------------ | ----------------------------------------------------------------------------- |
+| `contract_version` | `1`。サーバーは別のバージョンのサービスを利用不可として扱います |
+| `max_bytes` | サービスが受け付ける原本の最大サイズ。サーバーはこれより大きい原本を送りません |
+| `formats` | サービスが抽出する各形式と、その形式が受け付けるオプション |
+
+
+
+### `POST /v1/extract`
+
+本文は原本のバイト列です(`Content-Type: application/octet-stream`)。サーバーが要求する内容はクエリで指定します。
+
+| パラメーター | 意味 |
+| ------------- | ---------------------------------------------------------------- |
+| `format` | サーバーがファイルのルーティングに使った形式 |
+| `name` | ファイル名。空の場合があります |
+| `encoding` | 任意。自身でエンコーディングを示せないテキストファイル向けのコーデック名 |
+| `sql_dialect` | 任意、SQL のみ。パースに使う方言 |
+
+サービスは、受け付けないオプションを拒否します(`invalid_option`)。また、内容を `format` と照合し、別の形式のファイルは、指定された形式として読まずに拒否します(`format_mismatch`)。
+
+`200` は artifact の JSON を返します。サーバーは `Accept-Encoding: identity` を送信するため、サービスは応答を圧縮してはいけません。圧縮された応答は、ステータスに関わらず、サービスが利用不可であるものとして扱われます。サービスが抽出できないソースには、エラー本文付きの `422` を返します。
+
+```json
+{ "error": { "code": "format_mismatch", "message": "the file is pdf, not markdown" } }
+```
+
+| コード | 意味 |
+| -------------------- | --------------------------------------------------------- |
+| `unsupported_format` | どの抽出器もサポートしていない形式のファイル |
+| `format_unavailable` | このサービスはその形式を抽出しない |
+| `format_mismatch` | 内容が、指定された形式とは別の形式である |
+| `encoding` | テキストをデコードできない |
+| `corrupt` | ファイルが破損している、またはパーサーが処理に失敗する |
+| `invalid_option` | オプションが未知であるか、サービスが拒否する値である |
+| `too_large` | 原本がサービスの `max_bytes` を超えている |
+| `timeout` | 抽出にサービスの許容時間より長くかかった |
+| `resource_limit` | 抽出がメモリまたは出力の上限を超えた |
+
+サーバーは、小文字の英字と `_` からなる最大 40 文字のコードを失敗のコードとして保持し、それ以外のコード、または 64 KiB を超えるエラー本文は `refused` として扱います。`401`、`403`、`407`、`408`、`429`、すべての `5xx`、`200` でも `4xx` でもないその他の応答(リダイレクトや `204`)、`format_unavailable`、およびタイムアウトを過ぎた呼び出しは、サービスが利用不可であるものとして扱い、そのソースは後で再試行できます。それ以外の `4xx` は、ソースが拒否されたものとして扱います。以下のルールに違反する artifact を含む `200` は、`invalid_artifact` として拒否されます。
+
+
+
+## アーティファクト
+
+```json
+{
+ "schema_version": 1,
+ "format": "toml",
+ "parser": "loom-toml",
+ "parser_version": "1+python3.12.13",
+ "options": {},
+ "attrs": {},
+ "warnings": [],
+ "coverage": {
+ "unit": "keys",
+ "total": 1,
+ "extracted": 1,
+ "failed": [],
+ "lost": [],
+ "complete": true
+ },
+ "blocks": [
+ {
+ "id": "b0",
+ "type": "toml_table",
+ "text": "[server]",
+ "section_path": ["server"],
+ "locator": { "line_start": 1, "line_end": 1, "key_path": "server" },
+ "keys": ["server"]
+ },
+ {
+ "id": "b1",
+ "type": "toml_key",
+ "text": "server.port = 7777",
+ "parent": "b0",
+ "section_path": ["server"],
+ "locator": { "line_start": 2, "line_end": 2, "key_path": "server.port" },
+ "keys": ["server.port"],
+ "attrs": { "value": 7777, "value_type": "integer" }
+ }
+ ]
+}
+```
+
+| フィールド | 型 | ルール |
+| -------------------------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `schema_version` | 整数 | `1` |
+| `format` | 文字列 | 要求された `format` |
+| `parser`, `parser_version` | 空でない文字列 | アーティファクトを生成したもの。パーサーが変わると新しいバージョンになる |
+| `options`, `attrs` | オブジェクト | ネストは最大 16 階層 |
+| `warnings` | 文字列のリスト | |
+| `coverage.unit` | 空でない文字列 | フォーマットを構成する単位:`lines`、`statements`、`keys`、`chars`、`pages`、`paragraphs`、`slides`、`rows`、... |
+| `coverage.total`, `coverage.extracted` | 整数 | `0 <= extracted <= total` |
+| `coverage.failed` | `{unit, reason}` のリスト | 抽出されなかった各単位 |
+| `coverage.lost` | 文字列のリスト | アーティファクトが提供できない機能(例:`sql_structure`) |
+| `coverage.complete` | 真偽値、省略可 | 送る場合は、`extracted == total` で、失敗も欠落もないことと等しくなければならない |
+| `blocks` | リスト | 読み順 |
+| `blocks[].id` | 空でない文字列 | アーティファクト内で一意 |
+| `blocks[].type` | 文字列 | `heading`、`paragraph`、`list`、`code`、`sql_statement`、`toml_table`、`toml_key` のいずれか |
+| `blocks[].text` | 文字列 | |
+| `blocks[].parent` | 文字列、省略可 | そのブロックを囲む、より前のブロックの id |
+| `blocks[].depth` | 整数、省略可 | `0` 以上。見出しのレベル |
+| `blocks[].section_path` | 文字列のリスト | ブロックより上にある見出し。最大 64 個、各最大 500 文字 |
+| `blocks[].keys` | 文字列のリスト | ブロックを検索できる完全一致の名前。最大 10,000 個、各最大 1,024 文字 |
+| `blocks[].attrs` | オブジェクト | フォーマット固有の情報(行ブロックの `table_id`:その行が属するテーブルの id。DOCX、PPTX、HTML のテーブルブロックの `table`:その `rows` と `columns`。ページの向きとは別の方向に流れるテキストの PDF ブロックの `orientation`。画像から読み取ったブロックの `ocr`) |
+| `blocks[].locator` | オブジェクト | `line_start`/`line_end`(1 始まり。どちらも `0`、または `1 <= start <= end`)、`char_start`/`char_end`(デコード後のテキストへのオフセット。どちらも `-1`、または `0 <= start <= end`)、`key_path`、`page_start`/`page_end`(PDF のページまたはデッキのスライド。1 始まり。どちらも `0`、または `1 <= start <= end`)、`sheet`(ワークブックのシート名。最大 500 文字)、`row_start`/`row_end`(シートまたは CSV ファイルの行でヘッダーを数える、Parquet ファイルの行は 1 から、または PDF テーブルの行でヘッダー行を 1 とする。1 始まり。どちらも `0`、または `1 <= start <= end`) |
+
+表形式のソース(CSV ファイル、ワークブックのシート、Parquet ファイル)と、テーブルを含む PDF は、検索の対象となる行ブロックに加えて `tables` も持ちます。
+
+| フィールド | 型 | ルール |
+| ------------------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `tables` | リスト、省略可 | ソースの各テーブル |
+| `tables[].id`, `tables[].name` | 文字列 | id は一意で空でないこと。name は、シート名、ファイル名、または PDF テーブルのページと位置(`page 3 table 1`) |
+| `tables[].columns` | `{name, type}` のリスト | 最大 16,384 個。name は最大 500 文字。type は `string`、`number`、`bool`、`date`、`datetime`、`time`、`duration`、`mixed` のいずれか(列の全ての値が何であるか。日付と日時が混在する場合は `datetime`) |
+| `tables[].rows` | リストのリスト | 各行は `columns` と同じ長さ。各値は文字列、数値、真偽値、null、またはセルエラー `{"error": "#DIV/0!"}`。日付と時刻は ISO テキスト、期間は `H:MM:SS` で 1 日を超える時間も含める(`36:00:00`)。小数、または符号付き 64 ビットを超える整数は、`number` 列では正確な桁(`"12.345"`) |
+| `tables[].header_rows` | integer、省略可 | `0` 以上。省略時は `1`:列に名前を付ける値の上にある行。名前がソースの行ではないソース(Parquet のスキーマ)では `0` とし、その場合、行は 1 から数える |
+| `tables[].locator` | object | ブロックのものと同じ:テーブルが及ぶシート(PDF ではページ)と行 |
+| `tables[].attrs` | object | フォーマット固有の情報(非表示シートには `hidden`) |
+
+`tables` を知らないサーバーは、契約に定められていないほかのフィールドと同様にこれを破棄し、行ブロックは引き続き公開します。
+
+すべての文字列は有効な Unicode でなければならず、すべての数値は JSON でなければなりません(`NaN` や `Infinity` は不可)。整数は符号付き 64 ビット(-2^63 から 2^63-1 まで。したがってそれを超える `UInt64` は不可)、それ以外の数値は double の範囲内(`1e999` は不可)です。サーバーは、いずれかの規則に違反するアーティファクトを拒否し、契約に定められていないフィールドは破棄するため、サービスはバージョンを変えずにそれを送れます。古いサーバーが読めない変更は `schema_version` を上げます。ブロックのキーとセクションパスは、そこから切り出されるすべてのチャンクに付随するため、アーティファクトのサイズに加えて、個数と長さでも制限されます。リファレンス抽出器は、長すぎるキーを除外し、先頭 10,000 個のキーと、500 文字に切り詰めた先頭 64 件のセクションエントリを残します。そして、ブロックに `attrs.keys_truncated` または `attrs.section_truncated` を、アーティファクトの `coverage.lost`(`exact_keys`、`section_path`)に印を付けるため、完全であると報告することはありません。ここでの文字、および `char_start`/`char_end` における文字は、デコード後のテキストの Unicode コードポイントです(UTF-16 単位でもバイトでもありません)。行や文字の範囲は原本の内側に収まる必要があります。サーバーは、`char_end` が原本のバイト数を超えるアーティファクト、または `line_end` がそのサイズに 1 を足した値を超えるアーティファクトを拒否します。この上限は、どのエンコーディングでも成り立ちます。
diff --git a/i18n/.pending/ko/docs/architecture/server-layout.md b/i18n/.pending/ko/docs/architecture/server-layout.md
new file mode 100644
index 0000000000..604b741daf
--- /dev/null
+++ b/i18n/.pending/ko/docs/architecture/server-layout.md
@@ -0,0 +1,101 @@
+
+> 이 페이지는 [영어 원문](https://github.com/ClickHouse/loom/blob/main/docs/architecture/server-layout.md)을 기계 번역한 것이며, 영어 원문이 기준입니다.
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/architecture/server-layout.md), which is authoritative.
+
+
+
+# 서버 레이아웃
+
+`server/`는 도메인별로 구성됩니다. 각 제품 플레인은 와이어 선언, 핸들러, 순수 로직, ClickHouse 접근, 백그라운드 루프를 담은 패키지 하나를 소유하며, 임포트가 향할 수 있는 방향은 테스트로 고정되어 있습니다. 이 페이지는 새 모듈을 어디에 둘지 정하고, 컨트랙트 테스트에서 발생하는 임포트 오류를 해석하는 데 쓰는 지도입니다.
+
+
+
+## 패키지
+
+| 패키지 | 담당 범위 | 임포트 가능 대상 |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `server/main.py` | 앱 구성: lifespan, 라우터, 워커, 트랜스포트. `server/boot.py`, `server/health.py`, `server/wiring.py`, `server/worker_main.py`, `server/__init__.py`와 함께 루트에 둘 수 있는 유일한 모듈 | 모든 것 |
+| `server/boot.py` | lifespan의 부팅 및 종료 단계: 직렬화된 부팅 마이그레이션, 리더의 트래커 네임스페이스 행, 폐기 스냅샷과 키링, 슈퍼바이저 리스 루프, 쓰기 드레인 | 모든 것 |
+| `server/health.py` | `GET /v1/health`: 다중 티어 상태 응답(ClickHouse, 프로바이더, 부팅 스냅샷, 보정, 요청 제한기, 요청 시 워커와 관측 가능성) | 모든 것 |
+| `server/wiring.py` | `wire()`: 각 플랫폼 연결 지점에 도메인 구성 요소를 전달(인증 게이트의 네임스페이스 디렉터리, 상태 게이지의 사실 정보). `main.py`, CLI, 테스트 스위트에서 실행 | 모든 것 |
+| `server/worker_main.py` | 워커 자식 프로세스의 컴포지션 루트(`python -m server.worker_main`): 서빙 lifespan 없이 슈퍼바이저와 그 워커가 사용하는 것 | 모든 것 |
+| `server/core/` | 공통 인프라: ClickHouse 클라이언트(`ch`), `errors`, 예산, 날짜/시간, 해싱, 명명, 커서, 멱등성, 요청 제한, 벡터 저장 정책, `schema/`(마이그레이션과 DDL 도구) | `core`, `settings` |
+| `server/settings/` | `catalog.py`에 선언된 모든 설정. 영역별로 한 섹션이며 `Settings`로 구성됨 | `core`, `settings` |
+| `server/operations/` | 레지스트리 코어: `Operation`과 `Role`(`base.py`), 평탄화된 레지스트리(`registry.py`: `ALL_OPERATIONS`, `OPERATIONS_BY_NAME`), `toolsets.py`, 읽기 프로젝션, 도달 범위 집계 | `core`, 플랫폼 패키지, 모든 도메인의 `api` |
+| `server/transport/` | HTTP와 MCP: 수락 처리, 요청 바인딩, 목록, 프라이머 | `core`, 플랫폼 패키지. 도메인의 `api`, `app`, `domain`(`store`나 `workers`는 불가). `cli`는 불가 |
+| `server/cli/` | `loom` 명령, 외부 어댑터 | 모든 것 |
+| `server/workers/` | 워커 레지스트리(`registry.py`), 슈퍼바이저, 패스 컨텍스트, 상태와 그 저장소, 첫 패스 스케줄링, 비용 이벤트. 워커 루프는 각 도메인에 있음 | `core`, 플랫폼 패키지. 도메인의 `workers`(레지스트리의 모듈 문자열) |
+| `server/observability/` | 원장, 이벤트, 감사 행, 메트릭, 트레이싱 내보내기 | `core`, 플랫폼 패키지 |
+| `server/auth/` | 토큰 발급과 검증, 역할 및 네임스페이스 게이트, 요청별 신원 | `core`, 플랫폼 패키지 |
+| `server/embedding/`, `llm/` | 교체 가능한 임베더와 LLM 프로바이더 | `core`, 플랫폼 패키지 |
+| `server/clients/`, `storage/` | 외부 HTTP(공유 풀, GitHub), 보존 조항 | `core`, 플랫폼 패키지 |
+| `server/memory/` | 메모리 플레인: `memory.*`, 검색, ask, 추출, 사실, 절차, 프로필, 작업 메모리, 컨텍스트 팩, 충돌, 블랙리스트, `loom_search` | [레이어](#layers) 참조 |
+| `server/code/` | 코드 플레인: `code.*`, 인덱스(`app/index/`, `domain/index/`, `store/index/`), 파서(`domain/extract/`), 수집 및 컴파일러 티어 워커 | [레이어](#layers) 참조 |
+| `server/tracker/` | 트래커 네임스페이스: `tracker.*`, 중복 검사, 라이브 소스 리더와 그 클라이언트, loom 자체의 트래커 테이블 | [레이어](#layers) 참조 |
+| `server/knowledge/` | 지식 문서와 청크, 대화, 저장소 문서 | [레이어](#layers) 참조 |
+| `server/erasure/` | 삭제 사가, 그 집계, 연합 백엔드, 복구 워커 | [레이어](#layers) 참조 |
+| `server/tasks/` | 작업 인박스, 실행 원장, 그 깨우기 및 웹훅 루프 | [레이어](#layers) 참조 |
+| `server/identity/` | 네임스페이스, 권한 부여, 기록 정책, 읽기 범위, 제한된 접근, 대시보드 페이지와 호출자 API(`/v1/me/*`) | [레이어](#layers) 참조 |
+| `server/insights/` | 운영자용 화면: `ops.*`, `cost.*`, `agents.*`, `audit.list`, `ui.vitals`, `mentor.brief`, `/v1/admin/*` 라우트 | [레이어](#layers) 참조 |
+| `server/assistant/` | 어시스턴트: LibreChat 서비스 사용자와 에이전트 정의. 부팅 시 설정됨 | [레이어](#layers) 참조 |
+
+플랫폼 패키지는 `core`와 위에 나열된 그 외의 비도메인 패키지인 `settings`, `operations`,
+`transport`, `cli`, `workers`, `observability`, `auth`, `embedding`, `llm`, `clients`,
+`storage`입니다. `core`와 `settings`를 제외한 각 패키지는 다른 모든 플랫폼 패키지를
+임포트할 수 있으며, 표에 명시된 경우를 제외하고는 어떤 패키지도 도메인 패키지를
+임포트하지 않습니다.
+
+
+
+## 레이어
+
+도메인 패키지에는 최대 다섯 개의 하위 패키지가 있습니다. 모듈은 주된 책임이 속한 곳에 두며, 작은 도메인은 레이어 수가 더 적습니다.
+
+| 레이어 | 담는 내용 | import 가능 대상 |
+| ---------- | -------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `api/` | 와이어: Pydantic 입력 및 출력 모델(`models*.py`)과 도메인의 op 그룹에 대한 `Operation` 선언(`ops*.py`) | `core`, `operations`, `settings`; 모든 도메인의 `domain`과 `api`; `Operation`이 바인딩하는 핸들러를 위한 자신의 `app` |
+| `app/` | 핸들러와 오케스트레이션: op 또는 워커 패스가 I/O를 수행하며 순서대로 하는 일 | 자신의 `api`, `app`, `domain`, `store`; 다른 도메인의 `app`, `domain` 및 와이어 모델(`api/models*.py`); `core`와 `transport`, `cli`를 제외한 모든 플랫폼 패키지 |
+| `domain/` | 순수 로직, 타입이 지정된 값과 정책: ClickHouse도 네트워크도 없음 | `core`(I/O 모듈인 `ch`, `schema`, `idempotency`, `ratelimit_shared`, `namespace_write_marks` 제외), `settings`, 모든 도메인의 `domain` |
+| `store/` | ClickHouse 리포지토리와 행 빌더: 도메인이 자신의 테이블에 실행하는 모든 구문 | `core`, `settings`, `observability`, `storage`, 자신의 `store`, 모든 도메인의 `domain` |
+| `workers/` | 백그라운드 루프, 레지스트리 행마다 모듈 하나 | `app`과 같되 `api` 대신 `workers`를 사용; 다른 도메인의 `app`, `domain` 및 와이어 모델 |
+
+`domain/` 모듈 하나는 프로세스를 시작합니다. `server/code/domain/extract/bounded_parse.py`는 `domain/`의 모든 tree-sitter 파서가 호출하며, 각 소스를 먼저 리소스 제한이 걸린 로컬 자식 프로세스에서 파싱합니다.
+
+의도적으로 없는 두 가지 연결이 있습니다. `store/`는 `app/`을 호출하지 않습니다. 리포지토리는 값을 받아 행을 반환하므로, app을 가짜 store로 테스트할 수 있습니다. 그리고 어떤 도메인도 다른 도메인의 `store/`를 읽지 않습니다. 해당 도메인의 `app/`을 호출하거나 `domain/` 타입을 읽으며, 따라서 테이블의 소유자만이 그 테이블에 대한 구문을 작성하는 유일한 주체입니다. 다른 도메인의 핸들러를 호출하려면 `app/`과 `workers/`는 그 도메인의 와이어 모델(`api/models*.py`)을 import할 수 있지만, `api/ops*.py`는 절대 import하지 않습니다. `app/`은 와이어 모델만 import하고 `ops` 모듈은 import하지 않으므로, `Operation` 선언이 import 순환 없이 핸들러를 바인딩할 수 있습니다.
+
+
+
+## import 계약
+
+`tests/unit/test_package_contracts.py`는 `ast`로 `server/` 아래의 모든 모듈을 파싱하고, 각 import를 양쪽 끝의 패키지와 레이어를 기준으로 분류합니다. 분류 대상은 최상위 import, `if`/`try` 아래에 중첩된 import, 함수 안의 import, `TYPE_CHECKING` 아래의 import입니다. 위의 규칙이 허용하지 않는 import가 있으면 테스트는 import하는 모듈과 import되는 모듈을 함께 보고하며 실패합니다.
+
+현재 계약을 위반하는 import는 `tests/unit/package_contract_allowlist.txt`에 모듈 경로 기준 `importer -> imported` 형식으로 나열되어 있습니다. 이 목록은 줄어들기만 합니다. 허용된 쌍이 더 이상 나타나지 않는 경우에도 테스트가 실패하므로, import를 고치면 해당 줄을 삭제해야 합니다.
+
+두 번째 검사가 함께 실행됩니다. `server.transport`를 import할 수 있는 것은 `server/transport/`, `server/cli/`, `server/main.py`뿐입니다(`tests/unit/test_transport_layering.py`). 어떤 도메인 모듈도 `server.cli`를 import하지 않습니다.
+
+
+
+## 모듈 추가하기
+
+1. 모듈이 담당하는 테이블, op 그룹 또는 플레인이 속한 도메인을 고릅니다. 모든 플레인을 담당하는 모듈(ClickHouse 헬퍼, 해싱 규칙)은 `core/`에 둡니다. 두 도메인을 담당하는 모듈은 그 모듈이 읽는 행이 속한 도메인에 두고, 다른 도메인이 이를 호출합니다.
+2. 계층은 누가 호출하는지가 아니라 모듈이 하는 일을 기준으로 고릅니다. I/O를 하거나 무언가를 await하는 `async def`는 `app/` 또는 `store/`에 두고, 인자만으로 결정되는 함수는 `domain/`에 둡니다.
+3. 패키지 안에서 모듈이 담고 있는 내용을 기준으로 이름을 짓고, 경로에 있는 단어를 반복하지 않습니다. `server/erasure/app/erasure_saga.py`가 아니라 `server/erasure/app/saga.py`로 짓습니다.
+4. 패키지의 `__init__.py`에는 그 패키지가 무엇을 담당하는지 설명하는 한 줄짜리 docstring을 둡니다. 이름을 다시 내보내는(re-export) 경우는 해당 패키지의 공개 인터페이스일 때뿐입니다(`server/memory/store/`, `server/code/store/index/`).
+5. 백그라운드 루프는 `/workers/`에 있는 모듈 하나와, 전체 모듈 경로를 적은 `server/workers/registry.py`의 행 하나로 구성됩니다.
+6. mock 또는 monkeypatch 대상, 레지스트리 행, 커버리지 하한선은 모듈을 경로로 지정합니다. 재내보내기(re-export)를 거치지 말고 모듈의 실제 경로로 작성합니다.
+7. 서버가 함께 배포하는 파일(마이그레이션, `schema.sql`, 프런트엔드 빌드)은 `server.core.paths`를 통해 찾고, `__file__`의 부모 디렉터리 수를 세는 방식은 쓰지 않습니다(`tests/unit/test_repo_paths.py`).
+
+
+
+## Extractor 모듈
+
+`extractor_stamp.STAGE_MODULES`에 나열된 파일은 코드 인덱스의 버전 스탬프입니다.
+스탬프는 각 파일의 이름과 코드 토큰을 해시하며, import는 가져오는 패키지가 아니라 바인딩하는 이름으로 계산합니다. 스탬프가 바뀌면 모든 코드 네임스페이스의 인덱스를 다시 도출합니다. 이 파일들은 `server/code/domain/extract/`에 `extractor_stamp.py`와 함께 있으며, 이 스탬프 모듈은 자신의 디렉터리에서 이 파일들을 읽고, 파일 이름은 그대로 유지합니다. 언어 레인 모듈은 그 옆에 있습니다. 모듈을 다른 패키지로 옮겨도 스탬프는 그대로이지만, 이름을 바꾸거나, 형식을 다시 지정하거나(`ruff format`은 이 파일들을 제외합니다), 코드를 변경하면 스탬프가 바뀝니다.
+
+
+
+## 관련 문서
+
+- [시스템 개요](https://github.com/ClickHouse/loom/blob/main/docs/architecture/system-overview.md) — 컨트롤 플레인의 구성 요소와 요청 흐름.
+- [코드 인덱스 아키텍처](code-index-architecture.md) — extractor 스탬프와 재인덱싱.
+- [요청 경로](https://github.com/ClickHouse/loom/blob/main/docs/architecture/system-overview.md#request-path) — 요청이 전송 계층, 레지스트리, 핸들러를 거치는 경로.
diff --git a/i18n/.pending/ko/docs/architecture/system-overview.md b/i18n/.pending/ko/docs/architecture/system-overview.md
new file mode 100644
index 0000000000..3644c98327
--- /dev/null
+++ b/i18n/.pending/ko/docs/architecture/system-overview.md
@@ -0,0 +1,405 @@
+
+> 이 페이지는 [영어 원문](https://github.com/ClickHouse/loom/blob/main/docs/architecture/system-overview.md)을 기계 번역한 것이며, 영어 원문이 기준입니다.
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/architecture/system-overview.md), which is authoritative.
+
+
+
+# 시스템 개요
+
+Loom은 Python 서버(FastAPI 애플리케이션과 백그라운드 워커 supervisor)와 ClickHouse로 구성되며, 실시간 메모리와 지식 상태를 위해 선택적으로 Postgres를 사용할 수 있습니다. Loom은 상태를 가집니다. Loom이 아는 모든 것(사실과 그 벡터, 문서, 대화, 엔티티 그래프, 코드 인덱스, 태스크, 감사, 비용, 삭제 진행 상황)은 ClickHouse에 저장됩니다. 다만 `LOOM_STORAGE_AUTHORITY=postgres`로 설정하면 Postgres가 실시간 메모리, 지식 상태, 그리고 그와 함께 쓰이는 레코드를 보관합니다
+([스토리지 권한](https://github.com/ClickHouse/loom/blob/main/docs/architecture/storage-authority.md#the-tables)). 서버 프로세스는 자체적으로 영구 상태를 유지하지 않으므로, 여러 개의 프로세스가 같은 배포를 처리할 수 있고 요청은 어느 프로세스에든 도달할 수 있습니다. 이 저장소 밖에 보관되는 소수의 상태는 [배포 토폴로지](#deployment-topology)에 나열되어 있습니다.
+
+스토리지 레이아웃은 [ClickHouse](clickhouse.md)에 있습니다.
+
+
+
+## 목표와 비목표
+
+| 목표 | 비목표 |
+| ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| 모든 종류의 상태를 위한 하나의 엔진(ClickHouse가 기준): 벡터, 전문 검색, 그래프 엣지, 시계열, 원장. | 서버 내 파일 형식 처리: `knowledge.add`는 `content: str`을 받으며, 파싱은 CLI의 역할입니다. |
+| 한 번 선언하면 HTTP와 MCP에서 동일하게 제공되는 하나의 와이어 인터페이스. | 테이블 간 트랜잭션. 파생 행은 기본 쓰기 이후에 따라잡습니다. |
+| 서버 프로세스는 영속 상태를 갖지 않음: 프로세스를 더 실행해 웹 처리 용량을 늘립니다. | 이중 시간(bi-temporal) 이력. 유효성은 유효 시간(valid-time)만 다루며, 트랜잭션 시간 이력은 버전 미러가 담당합니다. |
+| 모든 행은 테넌트(식별 튜플), 작성자(`actor`), 요청(`log_comment`)에 귀속 가능. | GDPR 준수 보장. 삭제와 감사 해싱은 엔지니어링 기본 요소일 뿐입니다. |
+| 키 없이 설치해도 부팅되고 응답하며, 가짜 프로바이더임을 보고함. | |
+
+
+
+## 구성 요소
+
+```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
+```
+
+| 구성 요소 | 코드 | 역할 |
+| ------------------ | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| 트랜스포트 | `server/transport/http.py`, `server/transport/mcp.py` | 요청을 op 호출로 변환합니다. 둘 다 레지스트리에서 생성됩니다. 모든 op는 `POST /v1/`이며 MCP 도구 `loom_`입니다(점은 밑줄로 바뀝니다). 공통 승인 처리는 `server/transport/gates.py`에 있습니다. |
+| Operation 레지스트리 | `server/operations/` | op마다 하나의 `Operation`이 있습니다(`base.py`). 이름, 입력 및 출력 모델, 핸들러, `required_role`, `idempotent`, `audit`, `maturity`, 범위 지정 플래그를 갖고, `budget_p99_ms`는 `server/settings/catalog.py`의 예산 표에서 가져옵니다. `registry.py`의 `ALL_OPERATIONS`는 모든 그룹의 `OPERATIONS`를 합칩니다. |
+| 도메인 패키지 | `server//` | 플레인마다 하나의 패키지(`memory`, `code`, `tracker`, `knowledge`, `erasure`, `tasks`, `identity`, `insights`)가 있으며, 각각 `api/`(와이어 모델과 `Operation` 선언), `app/`(핸들러와 오케스트레이션), `domain/`(순수 로직), `store/`(ClickHouse 구문과 행 빌더), `workers/`로 구성됩니다. [서버 레이아웃](https://github.com/ClickHouse/loom/blob/main/docs/architecture/server-layout.md)을 참고하세요. |
+| ClickHouse 클라이언트 | `server/core/ch.py` | 유일한 클라이언트입니다. 풀링, 데드라인, 재시도, 쿼리 귀속을 처리합니다. `server/memory/store/rows.py`에는 버전 행 빌더가 있습니다. |
+| 워커 | `server/workers/` | `registry.py`(`_WORKERS`)에 행으로 선언된 백그라운드 루프입니다. 각 루프는 해당 도메인의 `workers/`에 있는 모듈이며 `supervisor.py`가 실행합니다. |
+| 인증 | `server/auth/` | JWT 검증, 폐기, 역할 및 네임스페이스 권한 부여, OIDC, OAuth 서버, 셀프 가입을 담당합니다. [보안](https://github.com/ClickHouse/loom/blob/main/docs/architecture/security.md)을 참고하세요. |
+| 프로바이더 | `server/embedding/`, `server/llm/` | 교체 가능한 임베더 및 LLM 클라이언트이며, 각각 결정적인 가짜 구현을 갖습니다. [LLM 아키텍처](llm-architecture.md)를 참고하세요. |
+| 관측성 | `server/observability/` | op별 원장(`loom.agent_events`), 배치 이벤트 스트림, 감사 행, 프로바이더 상태, OpenTelemetry 및 Langfuse 내보내기를 담당합니다. |
+| 대시보드 | `frontend/` (`/`에서 `frontend/dist/`로 제공) | 동일한 HTTP op 위에서 동작하는 React UI입니다. 빌드하지 않은 체크아웃에서는 페이지 요청에 503으로 응답합니다. |
+| CLI | `server/cli/` | `loom` 명령입니다. 운영자 작업(migrate, 토큰, re-embed, doctor)과 op용 클라이언트를 제공합니다. [CLI 레퍼런스](https://github.com/ClickHouse/loom/blob/main/docs/reference/cli.md)를 참고하세요. |
+
+레지스트리가 와이어 표면 전체입니다. `GET /v1/operations`는 모든 op를 예산 및 역할과 함께 나열하며, [operations 레퍼런스](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md)는 이를 바탕으로 생성됩니다. op를 추가하려면 모델을 정의하고, 핸들러를 작성하고, `Operation`을 선언한 뒤 해당 그룹의 `OPERATIONS` 목록에 추가합니다
+([operation 추가하기](https://github.com/ClickHouse/loom/blob/main/docs/development/adding-an-operation.md)). 두 트랜스포트가 모두 이를 자동으로 반영합니다.
+
+일부 HTTP 라우트는 레지스트리 op가 아닙니다. `/v1/health`, `/v1/whoami`, `/v1/operations`,
+`/v1/.well-known/jwks.json`, `/v1/.well-known/openid-configuration`, `/v1/knowledge.download`, `/v1/auth/login`, 대시보드의
+`/v1/me/*` 및 `/v1/admin/*` 헬퍼, 그리고 OAuth와 OIDC 엔드포인트가 그렇습니다.
+[HTTP API 레퍼런스](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md)에 이들이 정리되어 있습니다.
+
+
+
+### 의존성 방향
+
+```text
+transports → operations → /api → /app → /store → server/core/ch.py
+ ↘ /domain ↙
+```
+
+워커는 트랜스포트와 나란히 위치하며 자신의 도메인의 `app`과 `store`를 호출합니다. 핸들러는 프로바이더를 호출합니다. 트랜스포트보다 아래에 있는 어떤 것도 트랜스포트 모듈을 import하지 않습니다. 어떤 패키지가 어떤 패키지를 import할 수 있는지, 그리고 도메인 내부의 레이어는 [서버 레이아웃](https://github.com/ClickHouse/loom/blob/main/docs/architecture/server-layout.md)에 있으며, `tests/unit/test_package_contracts.py`가 이를 강제합니다.
+
+`tests/unit/test_transport_layering.py`가 트랜스포트 규칙을 강제합니다. `server/transport/`, `server/cli/`, `server/main.py` 밖의 어떤 코드가 `server.transport`를 import하면 이 테스트는 실패합니다. 그래서 하위 레이어에 필요한 요소는 트랜스포트 아래에 있습니다. MCP 툴셋 목록(`server/operations/toolsets.py`), 레지스트리 외 라우트의 bearer 검사(`server/auth/bearer.py`), 코드 범위 컨텍스트 변수(`server/code/domain/scope.py`), 원장 행 빌더(`server/observability/ledger.py`), 지연 시간 예산(`server/observability/budgets.py`), 플레인 기본값(`server/code/app/common.py`)이 그것입니다.
+
+**이유:** 프로토콜(상태 코드, JSON-RPC 프레임, 헤더)은 트랜스포트만 알고 있습니다. 그러면 핸들러는 HTTP, MCP, 워커, 테스트 어디에서든 동일한 입력 모델로 호출할 수 있습니다.
+
+
+
+## 요청 경로
+
+두 전송 방식 모두 `server/transport/gates.py`에서 한 번만 내려진 동일한 승인 결정을 실행합니다.
+차이는 자격 증명과 인자를 읽는 방식, 그리고 거부를 표현하는 방식입니다.
+HTTP는 상태 코드와 `detail` 본문으로 응답하고, MCP는 `isError`를 담은 결과로 응답합니다.
+
+
+
+### HTTP
+
+`server/transport/http.py`의 `build_router()`는 op마다 `POST /v1/` 라우트를 하나씩 추가합니다.
+`BodyLimitMiddleware`는 먼저 `LOOM_MAX_REQUEST_BYTES`(32 MiB)를 넘는 본문을 413으로 거부하며,
+0이면 제한이 해제됩니다. 이후 각 요청은 다음 단계를 순서대로 거칩니다(`_make_endpoint`). 거부가 발생하면 요청은 거기서 끝납니다.
+
+| 단계 | 코드 | 거부 |
+| -------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| 시작 | `_begin_request` | 없음. `X-Request-Id`(호출자가 보낸 값이 영문자, 숫자, `.`, `_`, `-` 1~64자이면 그 값, 아니면 새 UUID), `X-Schema-Version`, 쿼리 태그 `""`를 설정합니다. |
+| 토큰 검증 | `_extract_auth` | 401 `AUTH_INVALID`(인증이 켜져 있는데 토큰이 없음, 알 수 없는 스킴, 검증 실패 토큰); 폐기 목록이 로드되기 전에는 503 `AUTH_UNAVAILABLE`. |
+| 본문 읽기 | `_read_body` | 잘못된 JSON이면 400 `VALIDATION_FAILED`; 쓰기 op에서 알 수 없는 키가 해당 op의 필드와 비슷하면 422 `UNKNOWN_ARGUMENT`. |
+| 신원 채우기 | `gates.with_single_user_identity` | 없음. 단일 사용자 서버에서 토큰 없는 호출에 대해: `code.*`와 `tracker.*`를 제외한 모든 op에는 설치본의 org를, 일상적인 메모리 및 검색 op에는 네임스페이스와 해당 op의 에이전트를 채웁니다([해당 op](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#request)). 네임스페이스를 요구하는 다른 op(코드 및 트래커 op 제외)에서 비어 있거나 `"-"`인 네임스페이스는 제거되며, 따라서 검증 단계에서 누락으로 거부됩니다. HTTP에만 해당합니다. |
+| 검증 | `_validate_payload` | 필드를 지목하는 422 `VALIDATION_FAILED`. |
+| 인가 | `_authorize` → `gates.authorize` | 400 `IDENTITY_INCOMPLETE`(네임스페이스 또는 org 없음), 403 `AUTH_INSUFFICIENT`. |
+| 컨텍스트 바인딩, 정책 | `_bind_context_and_policy` | 인증 컨텍스트와 원장 실행(`X-Loom-Run-Id`)을 설정합니다; 기록 정책이 `enforce` 모드에서 거부하면 403 `POLICY_FORBIDDEN`. |
+| 속도 제한 | `_rate_limit` → `gates.rate_limit` | `Retry-After`가 포함된 429 `RATE_LIMITED`; 제한 대상인 모든 호출에 `X-RateLimit-*` 헤더. |
+| 멱등성 | `_idempotency_gate` | 저장된 응답을 재생하거나(`X-Idempotent-Replay: true`), 같은 키가 다른 본문과 함께 재사용되면 409 `IDEMPOTENT_CONFLICT`. |
+| 핸들러 | `_run_handler` | 핸들러의 `HTTPException`, `LoomServerError`의 코드와 상태, 또는 500 `INTERNAL_ERROR`. |
+| 성공 후 | `_finish_success`, `post_handler_rows` | 없음. 원장 행, 메트릭, `ignored_args`가 포함된 본문을 처리한 뒤 예산 위반, 감사, 멱등성 행을 기록합니다. |
+
+이 순서인 이유:
+
+- **본문보다 토큰이 먼저.** 배포 환경이 거부하는 익명 요청은 본문을 읽기 전에 401을 받습니다.
+ 원장 행을 남기지 않고, 필드 오류도 알아내지 못하며, 어떤 테넌트의 속도 제한 버킷도 건드리지 않습니다.
+- **제한보다 인가가 먼저.** 제한기는 본문 값만이 아니라 검증된 토큰의 org에서 할당량을 차감합니다
+ (`gates._rate_limit_org`).
+- **승인 후 멱등성.** 재생 키의 범위는 호출자의 org, 주체, op입니다
+ (`server/core/idempotency.py`, `scoped_key`). 재생은 익명 호출자, 다른 테넌트, 다른 op에는 도달하지 않습니다.
+
+**실패 시 열리는(fail-open) 게이트.** 트래픽 분류와 속도 제한기는 가용성 제어입니다.
+둘 중 하나가 예외를 던지면 호출은 승인되고, 실패는 집계되며 분당 최대 한 번 로그에 기록됩니다
+(`gates._fail_open`). 인증과 인가는 실패 시 닫힙니다.
+
+**알 수 없는 인자.** 입력 모델은 알 수 없는 키를 무시하므로 `server/transport/arg_check.py`가
+이를 지목합니다. 응답에는 `ignored_args`(그리고 비슷한 필드 이름에 대한 `did_you_mean`)가 담기고,
+HTTP는 `X-Loom-Ignored-Args`를 설정합니다. 둘 다 op가 읽었지만 적용하지 않은 필드를 먼저,
+그다음 읽지 않은 키를 나열합니다. 쓰기 op는 비슷한 키가 있으면 422 `UNKNOWN_ARGUMENT`로 거부합니다.
+신원 키와 전송 계층이 직접 읽는 키(`consumer`, `traffic_class`, `explain`, 멱등성 키)는 보고되지 않습니다.
+
+**핸들러 이후.** 원장 행에는 호출의 지연 시간과 임베딩 및 LLM 비용이 담깁니다.
+예산 위반 행(`budget_p99_ms` × `LOOM_LATENCY_BUDGET_MULTIPLIER` 초과), 감사 행(`op.audit`일 때),
+멱등성 행은 한 번의 왕복으로 기록됩니다(`gather_best_effort`). 각각 최선 노력 방식입니다.
+요청의 모든 ClickHouse 문에는 `log_comment = ""`가 붙습니다([쿼리 귀속](clickhouse.md#query-attribution)).
+
+
+
+### MCP
+
+`POST /mcp`는 JSON-RPC 2.0입니다(`server/transport/mcp.py`, `_handle_request`). `mcp_config.py`의
+`MCP_SUPPORTED_PROTOCOL_VERSIONS`에 있는 프로토콜 버전을 제공하며, `initialize`는 클라이언트의 버전이
+지원되면 그대로 돌려주고 그렇지 않으면 최신 버전을 돌려줍니다. 서버가 먼저 시작하는 이벤트는 없습니다.
+
+| 메서드 | 동작 |
+| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `initialize` | 버전을 협상하고 `instructions`를 반환합니다: 호출자의 프로필 섹션이 포함된 프라이머입니다. 같은 프라이머가 `loom://primer` 리소스, `loom` 프롬프트, `loom_activate` 도구로도 제공됩니다. |
+| `tools/list` | 연결의 도구 세트에 해당하는 목록(URL에 따라 정해지며 호출자와는 무관합니다). |
+| `tools/call` | HTTP와 같은 게이트를 거치는 op 호출 하나. |
+| `prompts/*`, `resources/*`, `ping` | 프라이머 노출 경로와 생존 확인. |
+
+`LOOM_MCP_AUTH_MODE`는 어떤 메서드에 bearer가 필요한지 결정합니다: `required`(기본값, 알림을 제외한 모든 메서드),
+`discovery_only`(`tools/call`만) 또는 `open`. 거부 응답에는 보호된 리소스 메타데이터를 가리키는
+`WWW-Authenticate` 챌린지가 포함되어, 네이티브 커넥터가 OAuth 서버를 찾을 수 있습니다(`mcp_auth.py`).
+
+`tools/list`는 `LOOM_MCP_TOOLSET`(기본값 `core`) 또는 `?toolset=`으로 선택한 목록을 보여줍니다
+(`server/operations/toolsets.py`). 목록은 가시성만 정할 뿐이며, 모든 op는 이름으로 호출할 수 있습니다.
+단 `_MCP_HIDDEN_OPS`에 있는 op는 MCP가 나열하지도 호출하지도 않습니다(HTTP는 계속 제공합니다).
+도구 세트는 [MCP 레퍼런스](https://github.com/ClickHouse/loom/blob/main/docs/reference/mcp.md)에 있습니다. 세 도구에는
+직접 작성한 디스크립터가 있습니다: `loom_search`(`search.query` op로, 텍스트 요약과 간결한 섹션으로 렌더링됨),
+`loom_op`(같은 경로로 이름을 지정해 아무 op나 호출하며, `op: "help"`가 목록을 보여줍니다, `server/transport/mcp_op.py`),
+`loom_activate`(프라이머이며, 레지스트리 op가 아닌 유일한 도구).
+
+`_call_tool`(`mcp_call.py`; 텔레메트리, 응답, 실패 응답은 `mcp_outcome.py`)은 다음 단계를 순서대로 실행합니다:
+
+1. **도구 확인**(`_resolve_tool`). 알 수 없거나 숨겨진 도구는 대신 사용할 것을 알려 주는 `isError`
+ 결과가 됩니다.
+2. **호출자 바인딩**(`_bind_caller_identity`). 요청 id를 발급하고 쿼리 태그를 설정하며,
+ 생략된 네임스페이스와 에이전트를 토큰과 호출자의 저장된 기본값으로 채웁니다.
+ 명시적인 인자가 우선합니다. `code.*` op는 배포 환경의 코드 네임스페이스를 기본값으로 사용합니다.
+ `_MCP_CROSS_AGENT_READS`의 읽기는 `agent` 기본값이 `*`입니다.
+3. **세션 실행.** (org, 토큰 주체, `Mcp-Session-Id`)마다 암묵적인 실행 하나가 있으며 호출자의 기본 네임스페이스에
+ 등록됩니다. 실행을 지정하지 않은 쓰기는 세션의 `run_id`를 받습니다. 단, 자체 실행을 지정하는 `run.*`,
+ 배포 환경의 코드 신원으로 동작하는 `code.*`, 그리고 `run_id`가 행의 범위를 정하거나 행에 바인딩되는
+ `working_memory.*`와 `conversation.update`는 예외입니다.
+4. **멱등성 키.** 멱등성 도구는 인자에서 `_idempotency_key`(또는 `idempotency_key`)를 받으며,
+ 이는 검증 전에 꺼내집니다.
+5. **인자**(`_validated_input`). 철자가 틀린 인자에 대한 거부가 먼저이고, 그다음 검증입니다. 실패는
+ 필드 오류, 알 수 없는 각 키에 대해 의도했을 법한 필드, op의 인자, 예시 호출을 담은 `isError` 결과입니다(`arg_feedback.py`).
+6. **인가**(`_authorize_call`), 공유 게이트.
+7. **승인**(`_admission_refusal`): 트래픽 클래스, 기록 정책, 속도 제한. 짧은 힌트가 있는 429에서는
+ 전송 계층이 한 번 기다린 뒤 다시 확인합니다(최대 `LOOM_MCP_RATELIMIT_RETRY_MAX_WAIT_S`).
+8. **멱등성 재생**, 승인된 호출자에게만 해당합니다.
+9. **핸들러.**
+10. **응답.** `structuredContent`는 순위 및 집계 세부 정보를 제외하며(`lean_results.py`; `explain=true`이면 유지),
+ `ignored_args`를 담습니다.
+
+**거부는 결과이고, 실패는 오류입니다.** 401을 제외한 4xx(`LOCKED`, `PINNED_CONFLICT`, `BLACKLISTED`,
+`RESOURCE_NOT_FOUND`, 태스크 상태 코드, `RATE_LIMITED`)는 구조화된 본문과 함께 `isError: true`로
+돌아오므로(`mcp_refusals.py`) 클라이언트가 안내를 볼 수 있습니다. 401과 5xx(`OVERLOADED`, `BACKEND_TIMEOUT`,
+`SCHEMA_PENDING`)는 HTTP의 본문과 재시도 힌트를 담은 JSON-RPC 오류로 남습니다.
+
+쓰기 하나(`memory.set`)와 읽기 하나(`memory.search`)의 단계별 설명은
+[메모리 아키텍처](memory-architecture.md)에 있습니다.
+
+
+
+## 역할과 프로세스 모드
+
+
+
+### 역할
+
+`Role`(`server/operations/base.py`)의 순서는 `VIEWER < WRITER < ADMIN < ORG_ADMIN <
+PLATFORM_ADMIN`입니다. 각 op는 `required_role`을 선언합니다. 플랫 토큰의 역할은 해당 토큰이 읽는 모든 네임스페이스에 적용되며, `loom.namespace_grants`는 네임스페이스에서 그 역할을 높일 수는 있어도 낮출 수는 없습니다. 범위 지정 토큰의 `ns_roles`는 해당 토큰이 지정한 네임스페이스에 대해 최종 권한을 가집니다. 그랜트와 `ns_roles`에는 `viewer`, `writer`, `admin`만 들어갈 수 있으며, `ORG_ADMIN`과 `PLATFORM_ADMIN`은 플랫 토큰의 `roles`에만 존재합니다. 자세한 내용은 [보안](https://github.com/ClickHouse/loom/blob/main/docs/architecture/security.md#authorization)과
+[ID와 네임스페이스](https://github.com/ClickHouse/loom/blob/main/docs/concepts/identities-and-namespaces.md)를 참고하세요.
+
+
+
+### 프로세스 모드
+
+하나의 이미지가 모든 역할을 담당합니다. 프로세스가 무엇을 하는지는 설정이 결정합니다.
+
+| 모드 | 설정 | 실행되는 것 |
+| ------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| 올인원 | `LOOM_BACKGROUND_WORKERS=auto` (기본값) | 웹 티어, 그리고 배포의 ClickHouse 리스를 보유한 프로세스 안의 워커. |
+| 웹 레플리카 | `LOOM_BACKGROUND_WORKERS=off` | HTTP, MCP, 대시보드. 자체 폐기 스냅샷과 서명 키링을 갱신합니다. |
+| 워커 | `LOOM_BACKGROUND_WORKERS=auto`, `LOOM_DEPLOYMENT=1`, `LOOM_SERVES_TRAFFIC=false` | 슈퍼바이저와 그 워커. `/v1/health`는 계속 응답합니다. |
+| 브랜치 / A-B 서버 | `LOOM_BOOT_MIGRATE=false`, `LOOM_INSTANCE_LABEL=::` | 마이그레이션을 적용하지 않고 공유 ClickHouse를 서비스합니다. 여기서 `auto`는 워커를 실행하지 않습니다. |
+
+`LOOM_WEB_WORKERS`는 컨테이너당 uvicorn 프로세스 수를 설정합니다. 설정하지 않으면 이미지는 컨테이너가 사용할 수 있는 CPU마다 하나씩, 메모리 GiB당 최대 하나, 최대 8개까지 시작합니다. 각 프로세스는 전체 lifespan을 실행하며, `auto`에서는 배포의 리스가 워커를 실행할 프로세스 하나를 정합니다. `on`은 리스를 사용하지 않습니다. 각 프로세스가 워커의 자체 사본을 실행하며, `auto` 프로세스가 리스를 보유하고 있지 않으면 나머지는 `workers_lease_absent`를 보고합니다. 워커 컨테이너는 `auto`로 실행됩니다.
+
+**리더 선출.** `server/workers/leader.py`(`decide_supervisor`, `keep_lease`)는 ClickHouse를 통해 배포당 하나의 슈퍼바이저를 선출합니다. 키는 Keeper 락 테이블 `loom._migration_lock`의 `workers_supervisor`이며(엄격한 KeeperMap이므로 두 경쟁자 중 한쪽의 쓰기만 반영됩니다), 만료는 ClickHouse 서버의 시계를 기준으로 판단합니다. 보유자는 `LOOM_SUPERVISOR_LEASE_TTL_S / 6`마다 갱신하고, 마지막 갱신 후 TTL의 절반이 지나거나 갱신 시 다른 보유자가 확인되면 워커를 중지합니다. 보유자가 죽으면 `LOOM_SUPERVISOR_LEASE_TTL_S`(기본값 30초) 후에 다른 `auto` 프로세스가 리스를 가져갑니다. 타이밍은 [장애와 복구](failure-and-recovery.md#background-workers)에 있습니다. 정상 종료하면 리스가 즉시 해제되며, 블루/그린 쌍의 새 색상이 인계받는 방식이 이것입니다.
+
+**ClickHouse를 쓰는 이유:** 워커를 실행할 수 있는 프로세스는 컨테이너와 호스트에 걸쳐 있고, 이들이 모두 공유하는 것은 ClickHouse뿐입니다. 여러 호스트가 `auto`를 실행할 수 있으며, 워커는 그중 하나에서만 실행됩니다([용량](failure-and-recovery.md#background-workers)).
+
+
+
+## 부팅
+
+`server/main.py`의 `lifespan`은 모든 프로세스에서 다음 순서로 실행됩니다(각 단계는
+`server/boot.py`에 있습니다).
+
+1. **실행 규칙.** 프로세스는 배포 자체(compose 파일이 설정하는 `LOOM_DEPLOYMENT=1`)이거나 비어 있지 않은 `LOOM_INSTANCE_LABEL`을 가져야 하며, 그렇지 않으면 시작을 거부합니다. 인증을 요구하는 배포가 저장소에 포함된 개발용 `LOOM_JWT_SECRET`을 사용하는 경우에도 시작을 거부합니다
+ (`require_real_signing_secret`). `LOOM_INSTANCE_LABEL=deploy:dev`만 예외입니다.
+2. ClickHouse에 **연결합니다**.
+3. **마이그레이션**(`LOOM_BOOT_MIGRATE`, 기본값은 켜짐). 모든 프로세스는 적용하기 전에
+ 배포의 마이그레이션 잠금을 획득합니다. 잠금은 `loom._migration_lock`의 KeeperMap 키입니다
+ (`server/core/schema/migrate_lease.py`). Keeper가 없는 서버이거나 마이그레이션이 실패하면
+ 부팅이 중단됩니다. `LOOM_BOOT_MIGRATE=false`이면 프로세스는 대기 중인 파일을 로그로 남기고
+ `/v1/health`에 보고합니다. Postgres 권한(authority) 하에서는 첫 하트비트와 리스 결정 전에 배포의 셀
+ 상태를 읽습니다. 첫 읽기가 실패하면 부팅이 중단됩니다(Postgres 마이그레이션이 대기 중이면
+ 게이트된 준비 안 됨 상태로 부팅하며, 읽기가 성공할 때까지 유지됩니다)
+ ([셀](https://github.com/ClickHouse/loom/blob/main/docs/architecture/cells.md#the-tenancy-check-and-placement)).
+4. **`agent_events` 이미터를 시작합니다.**
+5. **기본 네임스페이스.** 인증이 꺼져 있으면, 셀 게이트가 이 프로세스를 거부하지 않는 한
+ 설정된 네임스페이스에 `loom.namespaces` 행을 부여합니다.
+6. **워커 리더를 선출합니다.**
+7. **리더의 작업.** 값이 다른 보존 TTL 오버라이드를 적용하고, 설정된 트래커 네임스페이스를
+ 등록합니다.
+8. **토큰 상태와 오버라이드.** 폐기된 토큰 스냅샷(`server/auth/revocation.py`)과 서명 키링
+ (`server/auth/keyring.py`)을 로드합니다. 모든 프로세스는 각자의 타이머로 둘 다 갱신합니다.
+ `LOOM_RUNTIME_OVERRIDES_REFRESH_SECONDS`마다 관리자 런타임 오버라이드
+ (`loom.runtime_overrides`: 속도 제한, 지연 시간 예산, 라이브 설정)를 반영하기 시작하며,
+ workers 자식 프로세스도 이를 반영합니다. 라이브 설정의 오버라이드는 프로세스 자체의
+ `settings` 위에 덮어씌워지므로 코드에서는 `settings.`로 읽습니다
+ ([런타임 설정](https://github.com/ClickHouse/loom/blob/main/docs/operations/runtime-settings.md)).
+9. 리더에서 **워커를 시작하고**, `auto`에서는 리스 루프도 시작합니다(Postgres 권한 하의 `on`에서도
+ 마찬가지이며, 이 경우 셀 게이트가 워커를 시작하고 중지합니다).
+10. **프로바이더 보고.** 확인된 LLM 프로바이더를 로그로 남기고 임베더의 차원을 조사합니다.
+11. **벡터 기능.** 양자화된 코드 읽기 설정, 패치 파트, 삽입 시 벡터 인덱스 빌드를 건너뛸 수
+ 있는지 여부를 조사합니다.
+12. 임베더를 기준으로 유사도 임계값을 **보정합니다**(`LOOM_ADAPTIVE_THRESHOLDS`). 실패해도
+ 부팅은 실패하지 않으며 스칼라 설정이 적용됩니다.
+
+종료는 이 순서를 거꾸로 따릅니다. 루프를 중지하고, 워커를 비우고(10초), 리스를 해제하고,
+Langfuse 큐, 이벤트 이미터, 지연된 쓰기(노출 행, 쓰기 후 프로젝션, 이벤트 스트림)를 비웁니다.
+ClickHouse 클라이언트는 마지막에 연결을 해제합니다.
+
+`/v1/health`는 ClickHouse 도달 가능 여부와 `problems` 목록(예: 가짜 프로바이더)을 보고합니다.
+ClickHouse가 다운된 경우에만 503으로 응답하며,
+`?include=workers,langfuse,otel,embedding_cache`를 붙이면 서브시스템별 검사가 추가됩니다.
+
+
+
+## 백그라운드 처리
+
+`WorkerSupervisor`는 활성화된 워커마다 asyncio 태스크를 하나씩 실행하며, 리스 보유자에서만 실행합니다.
+각 워커는 `server/workers/registry.py`의 `_Worker` 행이며, 활성화 플래그와 실행 간격을 가집니다
+(대부분 `LOOM__ENABLED`, `LOOM__INTERVAL_SECONDS`). 슈퍼바이저는 첫 실행 시점을 분산시키고, 기한을 넘긴 실행을 취소하며,
+백오프를 적용해 재시도하고, 모든 쿼리에 `background` 트래픽 클래스 아래 `worker.` 태그를 붙이며,
+실행 상태를 `loom.worker_status`에 기록합니다 (`GET /v1/admin/workers.status`). 자세한 내용은
+[장애 및 복구](failure-and-recovery.md#worker-supervision)와 생성된
+[워커 레퍼런스](https://github.com/ClickHouse/loom/blob/main/docs/reference/workers.md)를 참고하세요.
+
+
+
+## 배포 토폴로지
+
+```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
+```
+
+- **서버 프로세스는 영구 상태를 보유하지 않습니다.** 복제본 간에 공유되는 상태(폐기 정보, 서명 키, 런타임 재정의, 로그인 시도 횟수, 그래프 쓰기 표시, supervisor 리스, 삭제 체크포인트, 블랙리스트 버전, 기본 authority에서의 멱등성 캐시, 기록된 authority)와 업로드된 문서 원본은 ClickHouse에 저장됩니다. `LOOM_DOCUMENT_OBJECT_STORE=s3`로 기록된 문서의 바이트는 대신 S3 호환 버킷에 저장됩니다. Postgres authority에서는 Postgres가 [스토리지 authority](https://github.com/ClickHouse/loom/blob/main/docs/architecture/storage-authority.md#the-tables)에 나열된 테이블을 보유하며, 여기에는 멱등성 캐시, 자체 삭제 원장, 기록된 authority의 사본이 포함됩니다. 동일한 ClickHouse(해당 authority에서는 Postgres도 포함), 환경 변수 설정, `LOOM_JWT_SECRET`을 가진 새 Loom, 그리고 행이 버킷의 객체를 가리키는 동안 그 버킷만 있으면 모든 기능이 복구됩니다.
+- **ClickHouse와 Postgres 외부의 상태.** `var/code_repos` 아래에 있는 코드 플레인의 git 미러(캐시이므로, 미러가 없는 호스트는 다시 클론합니다)와 `loom-shared` 볼륨의 rate-limit 버킷은 둘 다 기준 저장소(system of record)가 아닙니다. 또한 카탈로그 행이 하나라도 객체를 가리키는 동안에는 해당 원본의 바이트를 보관하는 `LOOM_DOCUMENT_S3_BUCKET`도 여기에 속합니다.
+- **컨테이너 두 개, 이미지 하나.** `dev/docker-compose.cloud.yml`은 `loom-server`(`LOOM_BACKGROUND_WORKERS=off`)와 `loom-workers`(`auto`: 리스를 보유하는 동안 워커를 실행)를 실행하므로, 오래 걸리는 워커 작업이 요청과 이벤트 루프를 공유하지 않습니다.
+- **블루/그린 쌍.** `dev/docker-compose.colour.yml`은 프록시 뒤에서 두 가지 색상을 실행합니다. `./redeploy.sh`는 유휴 색상을 시작하고, 상태 확인을 기다린 뒤 업스트림을 전환하고 이전 색상을 중지합니다. 모든 마이그레이션이 추가형이므로 롤백에 스키마 작업이 필요하지 않습니다. [배포](https://github.com/ClickHouse/loom/blob/main/docs/operations/deployment.md) 및 [업그레이드](https://github.com/ClickHouse/loom/blob/main/docs/operations/upgrades.md)를 참조하십시오.
+- **ClickHouse.** ClickHouse Cloud 또는 자체 관리하는 OSS 서버입니다. 단일 OSS 노드는 고가용성을 제공하지 않습니다.
+
+
+
+## 기초가 되는 구조
+
+네 가지 구조가 시스템을 떠받칩니다. 이 중 하나를 바꾸는 것은 설계 변경이며, 풀 리퀘스트와 이 페이지에서 논증해야 합니다.
+
+
+
+### 하나의 엔진: ClickHouse
+
+기본값인 ClickHouse authority에서는 모든 플레인(팩트와 벡터, BM25와 토큰 인덱스, 홉마다 제한된 쿼리 하나로 탐색하는 엔티티 그래프, 코드 인덱스, 원장과 비용)이 ClickHouse 테이블의 집합입니다. `LOOM_STORAGE_AUTHORITY=postgres`에서는 라이브 메모리와 지식 상태를 Postgres가 보관하며, 백업과 일관성 도메인을 하나로 유지하는 대신 트랜잭션 방식의 메모리 쓰기를 얻습니다([두 개의 저장소를 두는 이유](https://github.com/ClickHouse/loom/blob/main/docs/architecture/storage-authority.md#why-two-stores)). 아래의 이유와 비용은 기본값 기준입니다.
+
+**이유:** 백업, 접근 경계, 검색과 분석을 위한 쿼리 언어가 각각 하나이고, 동기화 작업 없이 메모리와 그 텔레메트리를 조인할 수 있습니다. 하이브리드 검색은 데이터 바로 옆에서 SQL로 실행됩니다. 별도의 벡터 저장소를 두면 두 번째 일관성 도메인, 이중 쓰기, 네트워크 홉을 넘나드는 결과 융합이 추가됩니다.
+
+**비용:** 트랜잭션 방식의 행 업데이트가 없습니다. 변경 가능한 테이블은 `ReplacingMergeTree`이며 `FINAL`로 읽으므로, 모든 쓰기 경로가 모든 컬럼을 그대로 이어서 기록해야 하고([FINAL 쓰기 규칙](clickhouse.md#the-final-write-rule)), 테이블 간 쓰기는 원자적이지 않습니다([장애와 복구](failure-and-recovery.md)).
+
+
+
+### 식별 튜플
+
+모든 메모리 행은 `(org, namespace, agent, user_id, session_id)`를 가집니다. 앞의 세 개는 필수이고 나머지는 기본값이 `'-'`입니다. 그 외의 모든 테넌트 테이블은 최소한 `(org, namespace)`를 가집니다. 메모리 쓰기 시 서버는 `actor`(`human:` / `process:`, `server.memory.app.provenance.writer_actor`)와 `source_class`(`server.memory.domain.provenance.source_class_for`)를 직접 기록하며, `derived`, `external`, `imported`로 명시적으로 낮추는 경우를 제외하면 요청 본문의 값을 사용하지 않습니다.
+
+**이유:** 테넌시, 작성자, 출처가 컬럼이므로 모든 읽기는 정렬 키로 필터링하고, 모든 행은 조인 없이 누구의 것이며 어디서 왔는지를 나타냅니다. **비용:** `actor`나 `source_class`를 빠뜨린 새 쓰기 경로는 귀속을 알 수 없는 행을 만듭니다.
+
+
+
+### 행 단위 콘텐츠 해시 감사
+
+감사 대상 쓰기는 모두 `loom.audit_log` 행을 남기며, 이 행의 `row_hash`는 정규화된 JSON에 대한 SHA-256입니다(`server/observability/audit.py`). 매시간 체크포인트(`loom.audit_checkpoints`)가 닫힌 각 구간의 행 수와 해시의 다이제스트를 봉인하고, 각 체크포인트는 이전 체크포인트와 연결됩니다.
+
+**행 단위로 하는 이유:** 행에서 행으로 이어지는 체인은 동시 작성자가 있으면 갈라지는데, Loom은 여러 서버 프로세스를 실행합니다. 행 단위 해시는 콘텐츠 변조를 탐지하고, 하나의 워커가 봉인하는 체크포인트 체인은 봉인된 구간에서 삭제, 수정, 뒤늦게 추가된 행을 탐지합니다. **비용:** 구간이 봉인되기 전에 제거된 행은 흔적을 남기지 않습니다. [보안](https://github.com/ClickHouse/loom/blob/main/docs/architecture/security.md#audit-log)을 참고하세요.
+
+
+
+### 다섯 가지 신념 수정 연산
+
+메모리 수명 주기는 다섯 가지 연산으로 이루어집니다. Expand(`memory.set`), Revise(`memory.update_by_id`), Contract(`memory.delete`), Reinforce(`memory.pin`), Refuse(`blacklist.add`)입니다. 이는 코드의 enum이 아니라 설계 관점이며, 메모리 플레인에서 이 중 어느 것에도 대응되지 않는 것은 의심스럽습니다. 병합, 이동, 가림 처리는 이 연산들의 조합으로 표현합니다. [메모리](https://github.com/ClickHouse/loom/blob/main/docs/concepts/memory.md)를 참고하세요.
+
+
+
+## 불변 조건
+
+- op는 `ALL_OPERATIONS`에 있는 경우에만, 그리고 그 경우에는 반드시 HTTP와 MCP 양쪽에 존재합니다(MCP는 이를 숨길 수 있지만 HTTP는 계속 제공합니다).
+- `server/transport/`, `server/cli/`, `server/main.py` 밖에서는 어떤 것도 `server.transport`를 import하지 않습니다.
+- 거부된 이후에는 어떤 게이트도 실행되지 않습니다. 인증이 켜져 있으면 익명 요청은 본문 파서, 원장(ledger), 리미터, 재생 캐시에 도달하지 않습니다.
+- 속도 제한기는 검증된 토큰의 조직(org)을 기준으로 키를 정합니다. 재생(replay)은 그것을 만든 호출자, 조직, op에게만 제공됩니다.
+- 인증과 권한 부여는 실패 시 닫히고(fail closed), 트래픽 분류와 속도 제한은 실패 시 열리며(fail open) 그 횟수를 집계합니다.
+- MCP에서 거부는 `isError: true`인 결과로 전달되며, 401과 5xx만 JSON-RPC 오류입니다.
+- 프로세스는 배포 전체이거나 `LOOM_INSTANCE_LABEL`을 가집니다. 부팅 시 마이그레이션이 실패하면 어떤 워커도 시작되기 전에 프로세스가 중단됩니다.
+- `auto` 모드에서는 배포 내에서 최대 하나의 프로세스만 supervisor lease를 보유합니다.
+- ClickHouse는 모든 메모리 플레인 행의 기준 저장소(system of record)입니다.
+- 메모리 쓰기의 `actor`와 `source_class`는 호출자가 아니라 서버가 지정합니다.
+
+
+
+## 소스 진입점
+
+| 항목 | 위치 |
+| ------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| 앱, 라이프스팬, 상태 확인 | `server/main.py`; 라이프스팬의 부팅 및 종료 단계는 `server/boot.py`; `GET /v1/health`는 `server/health.py` |
+| 오퍼레이션 선언 | `server/operations/base.py` (`Operation`, `Role`); 레지스트리는 `server/operations/registry.py` |
+| HTTP 라우트와 단계 | `server/transport/http.py` (`build_router`, `_make_endpoint`); `server/transport/post_rows.py` (`post_handler_rows`) |
+| 공통 허용 검사 | `server/transport/gates.py` |
+| 알 수 없는 인자 | `server/transport/arg_check.py`, `server/transport/arg_feedback.py` |
+| 멱등성 캐시 | `server/core/idempotency.py` |
+| MCP 디스패치와 거부 | `server/transport/mcp.py`, `mcp_call.py` (`_call_tool`), `mcp_op.py`, `mcp_refusals.py` |
+| ClickHouse 클라이언트 | `server/core/ch.py` (`get_client`, `set_query_tag`) |
+| 워커와 리더 | `server/workers/registry.py`, `supervisor.py`, `leader.py` |
+| 마이그레이션 리스 | `server/core/schema/migrate.py`, `server/core/schema/migrate_lease.py` |
+| 계층 검사 | `tests/unit/test_transport_layering.py` |
+
+
+
+## 관련 문서
+
+- [ClickHouse](clickhouse.md): 테이블, 엔진, 인덱스, 마이그레이션.
+- [메모리 아키텍처](memory-architecture.md): 쓰기 경로와 읽기 경로.
+- [장애와 복구](failure-and-recovery.md): 재시도, 복구, 용량.
+- [보안](https://github.com/ClickHouse/loom/blob/main/docs/architecture/security.md): 토큰 및 권한 부여 게이트가 검사하는 항목.
+- [배포](https://github.com/ClickHouse/loom/blob/main/docs/operations/deployment.md): 토폴로지를 구성하는 절차.
diff --git a/i18n/.pending/ko/docs/concepts/retrieval-and-ranking.md b/i18n/.pending/ko/docs/concepts/retrieval-and-ranking.md
new file mode 100644
index 0000000000..d91eb55eaf
--- /dev/null
+++ b/i18n/.pending/ko/docs/concepts/retrieval-and-ranking.md
@@ -0,0 +1,177 @@
+
+> 이 페이지는 [영어 원문](https://github.com/ClickHouse/loom/blob/main/docs/concepts/retrieval-and-ranking.md)을 기계 번역한 것이며, 영어 원문이 기준입니다.
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/concepts/retrieval-and-ranking.md), which is authoritative.
+
+
+
+# 검색과 순위 지정
+
+이 페이지는 `memory.search`가 행을 찾는 방식을 설명합니다. 네임스페이스에 대해 여러 검색 경로를 동시에 실행하고, 각 경로의 후보를 하나의 풀로 합친 뒤, 관련도와 제한된 보정 항목으로 풀의 순위를 매기고, 가장 좋은 결과가 답변의 근거로 삼을 만큼 충분한지 판단합니다. 결과가 약하면 가장 가까운 잡음을 반환하는 대신 **abstain**("Loom이 모름")으로 보고합니다. 요청 및 응답 필드는 [검색과 질문](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/search-and-ask.md)에 있습니다.
+
+
+
+```mermaid
+flowchart LR
+ Q["query"] --> P["plan: mode, budget, HyDE"]
+ P --> F["fact leg: value + key vectors"]
+ P --> L["lexical leg: tokens, stems, BM25"]
+ P --> C["verbatim chunks"]
+ P --> R["records"]
+ P --> S["side legs: summaries, entity boost"]
+ P --> G["graph: entity edges, triples"]
+ F --> U["fused pool"]
+ L --> U
+ C --> U
+ R --> U
+ S --> U
+ G --> U
+ U --> K["rank: relevance + bounded terms"]
+ K --> X["optional reranker"]
+ X --> V{"top hit above abstain threshold?"}
+ V -- yes --> A["hits"]
+ V -- no --> B["abstain + abstain_code"]
+```
+
+
+
+## 검색 레그
+
+각 레그는 다른 레그의 실패를 보완합니다. 더할 것이 없는 레그는 아무것도 반환하지 않으며, 오류가 난 레그는 fail open으로 처리되고 응답의 `degraded`에 그 레그가 명시됩니다.
+
+| 레그 | 읽는 대상 | 다른 레그가 놓치는 것을 찾는 방식 |
+| --------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| **팩트, 벡터** | `loom.memory_embeddings`의 value 벡터 (벡터 인덱스 없음) | 바꿔 말한 표현: 질문과 저장된 주장이 단어가 아니라 의미를 공유합니다. |
+| **팩트, 키 축** | 같은 테이블의 `memory_key` 벡터 | 키가 인코딩하는 속성을 직접 언급하는 질문. `least(value distance, key distance)`로 점수를 매깁니다. |
+| **Lexical** | 소문자화, 어간 추출, 표제어 추출을 거친 발췌문과 키 | 임베딩이 잘 되지 않는 정확한 식별자, 숫자, 드문 단어. 어간 추출은 ClickHouse(`stem`)에서 실행됩니다. |
+| **BM25** | 토큰별 IDF와 코퍼스 길이 롤업 | `bm25_hybrid`를 위한 희귀 용어 가중치. 라이브 테일이 있어 새 행이 즉시 반영됩니다. |
+| **원문 청크** | `loom.memory_chunks` | 긴 `memory.set` 값의 일부 구절은 해당 값을 자른 행으로 합쳐지고, 트랜스크립트의 구절은 그대로 히트가 됩니다. |
+| **세션 다이제스트** | `loom.session_summaries` | "그 세션에서 무슨 일이 있었는가". 다이제스트 하강을 쓰면 상위 다이제스트가 해당 세션의 최고 팩트를 끌어옵니다. |
+| **Entity** | `loom.entity_vectors`, `loom.entity_summaries` | 표현이 달라도 쿼리가 지명한 엔티티에 관한 행. |
+| **Graph** | `loom.entity_edges`, `loom.entity_triples` | 쿼리의 엔티티에서 한 홉 떨어진 행, 그리고 일치하는 (subject, relation, object) 트리플을 가진 행. |
+| **Records** | `loom.memory_records` | 필드가 일치하는 타입 지정 레코드. |
+| **키 매치** | 어간 추출된 키 부분 | 키가 요청된 속성을 정확히 지명하는 행. 동점 처리용입니다 (`LOOM_MEMORY_SEARCH_KEY_MATCH_MODE`). |
+| **계산된 증거** | `loom.derived_facts`, 이벤트 날짜 | 집계("몇 개"), 날짜 차이, 속성의 최신 값. ClickHouse에서 계산됩니다. |
+
+**레그가 이렇게 많은 이유.** 벡터 레그 하나로는 식별자와 숫자(임베딩이 잘 되지 않음), 긴 값의 깊은 곳에 있는 구절(앞부분만 임베딩됨), 다른 표현으로 엔티티를 지칭하는 행을 놓칩니다. 각 레그는 Loom이 이미 기록하는 테이블에 대한 쿼리이므로, 레그를 추가하는 비용은 별도 시스템이 아니라 쿼리문 하나입니다.
+
+**벡터 레그는 벡터 인덱스 없이 스캔합니다.** 스캔은 정확하게 수행되며, [codes-first 읽기](../architecture/clickhouse.md#vector-storage)가 적용되는 경우에는 양자화된 코드를 훑어 후보 풀을 유지한 뒤 전체 정밀도로 다시 점수를 매깁니다.
+
+**키 축**은 네임스페이스의 키가 재사용될 때 네임스페이스별로 켜집니다 (`LOOM_MEMORY_SEARCH_KEY_AXIS=auto`, 임계값 `LOOM_MEMORY_SEARCH_KEY_AXIS_AUTO_REUSE_SHARE`). 벡터 컬럼 두 개를 읽으면 바이트 비용이 대략 두 배가 되며, 키가 의미를 담고 있을 때만 도움이 됩니다.
+
+**계획과 예산.** `retrieval_budget`(`fast`, `standard`, `deep`)이 비용이 큰 레그 중 어느 것을 실행할지 결정합니다. `standard`에서는 저렴한 리콜이 먼저 실행되고, LLM 레그(HyDE, 쿼리 분해, 반복 재시도)는 첫 패스가 약할 때만 사용되며 `LOOM_MEMORY_SEARCH_FALLBACK_MAX_ROUNDS`와 `LOOM_MEMORY_SEARCH_FALLBACK_MAX_WALL_MS`로 제한됩니다. `fast`(또는 `fast` 레시피)에서는 읽기가 LLM을 호출하지 않으며, 임베딩과 ClickHouse 읽기 비용만 듭니다. HyDE는 질문 대신 LLM이 작성한 가상의 답변을 임베딩하여 질문과 저장된 주장의 표현 방식 차이를 줄입니다. `hyde=false`는 원본 쿼리를 강제로 사용합니다.
+
+
+
+## 퓨전
+
+`search_mode`는 팩트 풀의 정렬 방식을 정합니다.
+
+- `search_mode`와 `recipe`를 모두 지정하지 않은 요청에는 네임스페이스의 `retrieval_defaults` 모드가 적용되고, 이것도 없으면 `LOOM_MEMORY_SEARCH_DEFAULT_MODE`(`semantic`)가 적용됩니다. 와이어 스키마에는 `rrf`가 표시되지만, 실제 기본값은 서버가 채웁니다.
+- 그 위에 플래너의 형태 규칙이 적용됩니다. 쿼리에 식별자가 있으면 어휘(lexical) 퓨전을 사용합니다.
+- `recipe`는 이름이 붙은 프리셋(`fast`, `balanced`, `quality`, `verbatim`, `code`, `temporal`, `graph`)을 적용하며, 두 기본값보다 우선합니다.
+
+| 모드 | 정렬 |
+| ------------- | -------------------------------------------------------------------------------------- |
+| `semantic` | 코사인 유사도에 아래의 순위 항을 더합니다. |
+| `rrf` | 어휘 순서와 의미 순서의 Reciprocal Rank Fusion이며, `1/(k + rank)`에서 k = 60입니다. |
+| `hybrid` | `alpha × lexical + (1 − alpha) × cosine`에 순위 항을 더합니다. |
+| `bm25_hybrid` | IDF 가중 BM25를 코사인과 융합합니다. |
+| `lexical` | 콘텐츠와 키의 토큰 겹침을 사용하며, 벡터 순서는 없습니다. |
+| `graph` | 코사인에 엔티티 그래프 신호(1홉 겹침과 일치한 트리플)를 더합니다. |
+| `temporal` | 질문에서 확정된 날짜 기준 일정 구간 안의 행을 대상으로, 그 구간 안에서 코사인을 적용합니다. |
+| `related` | 요청의 `tags` / `entity_filter`와의 태그 및 엔티티 겹침을 사용합니다. |
+
+**Reciprocal Rank Fusion이 모드로 존재하는 이유.** 어휘 겹침 점수는 0에서 1까지 넓게 퍼지는 반면, 실제 임베더의 코사인 값은 좁은 구간에 몰려 있습니다. 그래서 둘의 가중합은 코퍼스마다 alpha를 조정하지 않으면 한쪽의 비중이 낮아집니다. RRF는 점수가 아니라 순위를 결합하므로 조정이 필요 없습니다. 또한 Loom은 코드나 경로 형태의 쿼리에서는 어휘 가중치를 낮춥니다. 이런 쿼리에서 공유되는 경로 토큰은 거의 노이즈이기 때문입니다(`server/memory/app/retrieval/fusion.py`, `_rrf_lexical_weight`). 한 순서에서 동점이면 다른 순서로, 그다음에는 키와 행의 네임스페이스, 작성자, 세션 순으로 결정하므로, 동일한 검색 두 번은 같은 구간을 반환합니다.
+
+
+
+## 랭크 표현식
+
+코사인 순서 모드에서 팩트 행 하나의 점수는 관련도에, 근소한 차이의 순위를 바꿀 수 있지만 관련도를 넘어서지 못하도록 상한이 걸린 항들을 더한 값입니다
+(`server/memory/app/retrieval/fact_rank.py`):
+
+| 항 | 더하는 값 | 제어 수단 |
+| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| 유사도 | 가장 가까운 벡터의 `1 − cosine distance`. | 임베더 |
+| 엔티티 가산점 | 행이 가진 `entity_filter` 엔티티 비율의 최대 0.5배. 쿼리에서 일치한 엔티티 벡터도 포함합니다. | `entity_filter` |
+| 최신성, 시간순, 날짜 | 최신성 의도("latest", "current")나 순서를 묻는 질문일 때, 그리고 질문한 날짜 근처에 고정된 행에 주는 가산점. | 쿼리 자체의 단서. 풀 단위 변형인 `LOOM_MEMORY_SEARCH_RECENCY_POOL_WEIGHT`의 기본값은 0(꺼짐)입니다 |
+| 사전 확률 그룹 | 저장된 `confidence` × `confidence_weight`, 소프트 태그 및 카테고리 가산점, 선호도 가산점. 합산하여 상한이 적용됩니다. | `confidence_weight`, `tags_soft`, `prior_cap` (`LOOM_MEMORY_PRIOR_CAP`) |
+| 강화 | 회상과 긍정적 결과. 반감기에 따라 감쇠하며, `harm` 이벤트는 얻은 가산점을 회수합니다. | `LOOM_MEMORY_SEARCH_REINFORCEMENT_WEIGHT` (0.15), `…_HALF_LIFE_DAYS` (90) |
+| 신뢰 | 주장(asserted) 또는 관찰(observed)은 `+0.5`, 가져온(imported) 것은 `−0.25`, 외부(external)는 `−1`, 증명(attested)된 경우 `+1`. 여기에 가중치를 곱합니다. | `LOOM_MEMORY_SEARCH_TRUST_WEIGHT` (기본값 0 = 꺼짐) |
+| 강등 | `demote_tags`는 행을 제외하지 않고 맨 아래로 내립니다. `sensitivity:medium` 또는 `:high` 레이블이 붙은 행은 점수가 낮아집니다. 단, 쿼리가 연락처 정보나 은행 계좌(IBAN)를 묻는 경우는 예외입니다. | `demote_tags`, `LOOM_MEMORY_SEARCH_SENSITIVITY_DEMOTE` (0.1) |
+
+**고정(pin)은 랭크 항이 아닙니다.** 고정은 행이 덮어쓰이지 않도록 보호할 뿐
+([쓰기가 판정되는 방식](https://github.com/ClickHouse/loom/blob/main/docs/concepts/memory.md#how-a-write-is-judged)), 순위를
+높여 주지는 않습니다. 팩트는 질문에 답하기 때문에 반환됩니다.
+
+`personalization="none"`은 사용자에서 비롯된 모든 항(선호도, 사전 확률 그룹, 강화)을 제거하고 관련도만 남기므로, 한 서버에서 두 랭킹을 비교할 수 있습니다.
+`LOOM_MEMORY_SEARCH_SOURCE_CLASS_BOOST_ELIGIBLE`은 어떤 출처 클래스가 이러한 항을 얻을 수 있는지 제한합니다. `extracted`를 빼면 추론이 사전 확률 때문에 진술보다 높은 순위를 차지하는 일을 막을 수 있습니다.
+
+**리랭커.** 요청의 `rerank` 또는 네임스페이스의 `rerank_endpoint`는 풀을 리랭커로 보냅니다
+(`builtin:openai[:model]`, `builtin:cohere[:model]`, 또는 운영자가 `LOOM_RERANK_ENDPOINTS_JSON`에 구성한 엔드포인트 이름이며, URL은 거부됩니다). 리랭커는 첫 단계에서 나온 결과만 재정렬하므로 풀을 먼저 넓힙니다(`LOOM_MEMORY_SEARCH_POOL_MULTIPLIER_RERANK`).
+실패하면 그대로 통과시키며(fail open) 후보를 버리지 않습니다.
+
+검색마다 호출이 한 번 더 늘어나는 비용보다 풀의 순서가 더 중요할 때 `rerank`를 지정하세요. 자신의 쿼리로 효과를 측정하려면 각 쿼리를 `rerank`를 지정한 경우와 `rerank="none"`(네임스페이스의 `rerank_endpoint`도 끕니다)인 경우로 실행하되, 둘 다 `explain=true`로 하고 실제 서비스하는 예산에서 실행한 다음(`fast` 또는 LLM을 쓰지 않는 읽기는 `builtin:openai` 호출을 하지 않습니다), 두 윈도를 비교하면서 각 히트의 `score_components`를 [이 결과가 이 순위인 이유](#why-did-this-rank-here)에서 설명하는 대로 읽으세요. 리랭커를 쓴 경우와 쓰지 않은 경우의 동일한 검색을 비교한 커밋된 실행 결과는 없습니다([결과](https://github.com/ClickHouse/loom/blob/main/docs/benchmarks/results.md#longmemeval-s)).
+
+랭킹이 끝나면 반환 윈도가 다듬어집니다. `duplicate`와 `superseded` 행은 요청하지 않는 한 숨겨지고, 키당 최대 `LOOM_MEMORY_SEARCH_PER_KEY_CAP`개의 행만 유지되며, `exclude_keys`는 호출자가 이미 가진 행을 제거합니다.
+
+
+
+## 기권
+
+모든 검색은 자신의 결과에 대한 판정으로 끝납니다. 응답에는 `abstain`, `abstain_code`(`no_match`, `below_threshold`, `entity_absent`, `low_calibrated_confidence`, `page_expired`), 서술형 `abstain_reason`, `retrieval_confidence`, 그리고 `low`, `medium`, `high`, `abstain` 중 하나인 `retrieval_risk`가 포함됩니다.
+코드의 정의는 [검색과 질의](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/search-and-ask.md)에 있습니다.
+
+자체 유사도가 임계값보다 낮은 윈도우 내 행에는 `below_threshold: true`가 붙으므로, 행마다 "기권은 기권이다"를 적용하려는 호출자는 이 값으로 필터링할 수 있습니다.
+
+**임계값의 출처.** 고정된 유사도 하한은 특정 임베딩 모델 하나에 맞춰 보정된 값입니다. 모델을 바꾸면 코사인 값의 분포가 달라져, 같은 숫자가 좋은 결과를 걸러내거나 노이즈를 걸러내지 못하게 됩니다. `LOOM_ADAPTIVE_THRESHOLDS`가 켜져 있으면(기본값), 부팅 시 프로브가 작은 코퍼스 세 개를 임베딩하고 임베더 자체의 분포에서 모든 게이트를 도출합니다(`server/memory/app/embedder_calibration.py`):
+
+| 프로브 코퍼스 | 도출되는 게이트 |
+| --------------------- | ----------------------------------------------------------------------------------------------- |
+| 방해 문장 쌍 | 노이즈 하한(90번째 백분위수 + 0.02)과 기권 임계값(하한 + 0.05). |
+| 질문 → 사실 쌍 | 트리거 게이트: 쿼리 재작성, HyDE 폴백, 리랭크 건너뛰기(10번째, 25번째, 75번째 백분위수). |
+| 바꿔 쓴 문장 쌍 | 쓰기 시점의 충돌 및 중복 임계값(중앙값, 75번째 백분위수). |
+
+네임스페이스별 보정값이 저장되어 있으면 클러스터 전체 보정값보다 우선하며, `recalibration` 워커가 프로브를 주기적으로 반복하므로(`LOOM_RECALIBRATION_INTERVAL_SECONDS`) 게이트가 조용히 개정된 임베더를 따라갑니다. 어느 티어가 적용 중인지는 `calibration.get`으로 확인할 수 있습니다. 스칼라 설정(`LOOM_MEMORY_SEARCH_MIN_SIMILARITY` 0.22, `LOOM_MEMORY_SEARCH_ABSTAIN_THRESHOLD` 0.30, `LOOM_MEMORY_SEARCH_HYDE_FALLBACK_THRESHOLD` 0.45, `LOOM_MEMORY_SEARCH_QUERY_REWRITE_THRESHOLD` 0.38)은 가짜 임베더를 쓰거나, 프로브가 실패했거나, 적응형 설정을 끈 경우에 적용됩니다. 이 경우 임베더를 바꾼 뒤 벤치마크를 다시 수행하는 일은 사용자 몫입니다.
+
+**트레이드오프.** 하한은 재현율과 정밀도를 맞바꿉니다. 주제와 무관한 질문에 가장 가까운 행 다섯 개를 받은 에이전트는 그것을 그대로 사용합니다. 기권은 에이전트에게 되묻거나 모른다고 말하라고 알려 줍니다. 하한을 너무 높게 잡으면 질문과 다르게 표현된 답을 숨기게 됩니다. Loom의 입장은 에이전트가 실행에 옮길 수 있는 명시적 기권이 가득 찬 윈도우보다 가치 있다는 것이며, 읽기마다 선택은 호출자에게 맡깁니다:
+
+- `min_similarity`는 이번 읽기의 하한을 설정합니다.
+- `floor_mode`는 하한 미만인 행을 어떻게 처리할지 정합니다. `readmit`(기본값: 신뢰도 높은 행 뒤에 하한 미만으로 표시되어 덧붙여지므로 `top_k`가 채워집니다), `ids_only`(본문이 빈 채로 덧붙여집니다. 키는 약한 일치가 있음을 알려 주되 그 텍스트를 컨텍스트에 넣지 않습니다), `drop` 중에서 고릅니다.
+
+지연된 추출이 진행 중인 스코프에서 빈 결과가 나오면 `pending_extraction`이 보고됩니다. 저장이 진행 중이므로 빈 답이 부재의 증거는 아닙니다.
+
+
+
+## 왜 이 순위가 나왔는가
+
+`memory.search`에 `explain=true`를 지정하면 반환되는 각 히트에 `score_components`가 붙습니다. 여기에는 랭킹 신호, 해당 모드가 실행된 경우의 RRF 점수와 가중치, 리랭커를 거친 뒤 각 행의 이동(`rerank_from`, `rerank_pos`, `rerank_delta`), 그리고 리랭커가 순서를 바꾼 경우 리랭커 자체의 융합 점수(`rank_score_pre_rerank`)가 들어 있습니다. 연결된 코드가 변경되어 순위가 내려간 메모리에는 몇 칸 내려갔는지(`code_changed_places`)가 함께 표시됩니다. 언제 순위가 내려가는지는 [코드에 연결된 메모리](https://github.com/ClickHouse/loom/blob/main/docs/concepts/memory.md#memories-linked-to-code)에서 설명합니다. `memory.search_trace`는 같은 요청을 받아 벡터 단계만 점수화합니다(융합, 조립, 리랭커 없음). 모든 후보에 대해 `similarity`, `entity_boost`, `rank_score`, `rank`, 그리고 후보가 나온 평면(`source`: `fact` 또는 `chunk`)을 반환합니다. `LOOM_SEARCH_TRACE_LOG_ENABLED=true`로 설정하면 모든 검색이 `loom.search_trace_log`에 행(반환된 키, 점수, abstain, risk, 지연 시간)으로도 추가되며, `memory.search_trace_log`로 읽을 수 있습니다. 쿼리 텍스트는 네임스페이스가 텍스트 캡처에 동의한 경우에만 저장됩니다. 대시보드의 Recall Lab(`/recall`)은 쿼리에 대해 메모리 목록이 보여 주는 행, 즉 키워드 일치 결과와 `score_components`가 포함된 `memory.search` 히트를 차례로 보여 줍니다.
+
+`memory.ask`는 같은 방식으로 검색한 다음 더 좁은 풀에서 답변을 작성합니다. 자세한 내용은 [검색과 질문](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/search-and-ask.md)을 참고하세요. `loom_search` MCP 도구(`search.query` 연산)와 `context.pack`은 여러 평면을 한 번에 검색합니다. 자세한 내용은 [통합 검색](https://github.com/ClickHouse/loom/blob/main/docs/features/unified-search.md)을 참고하세요.
+
+
+
+## 제한 사항
+
+- 검색은 라이브 임베딩 모델의 벡터만 읽습니다. 다른 모델로 임베딩된 행은 `loom reembed`가 다시 생성하기 전까지 보이지 않습니다.
+- 긴 값은 앞부분만 임베딩됩니다. 더 뒤에 있는 구절은 청크 레그가 찾아냅니다. 실질적으로 문서에 해당하는 값은 knowledge에 두어야 합니다.
+- abstain 게이트는 rank-1 행을 읽습니다. `rrf`에서는 어휘 일치만 있는 행이 rank 1을 차지하고 더 나은 코사인 값은 rank 2에 있을 수 있습니다. `LOOM_MEMORY_SEARCH_ABSTAIN_TOP_SIM_SCOPE=window`를 설정하면 대신 윈도우 안에서 가장 좋은 코사인 값을 읽습니다.
+- 보정(calibration)은 내장된 작은 프로브 코퍼스에서 게이트를 도출합니다. 이와 다른 코퍼스(코드, 좁은 단일 도메인)에는 네임스페이스별 보정이 필요할 수 있습니다.
+
+
+
+## 관련 문서
+
+- [검색 및 질의](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/search-and-ask.md): 모든 요청 필드와
+ 응답 필드.
+- [통합 검색](https://github.com/ClickHouse/loom/blob/main/docs/features/unified-search.md): `loom_search`와 `context.pack`에 대한
+ 자세한 설명.
+- [엔티티 그래프](https://github.com/ClickHouse/loom/blob/main/docs/features/entity-graph.md): 엔티티 및 그래프 경로의 출처.
+- [메모리](https://github.com/ClickHouse/loom/blob/main/docs/concepts/memory.md): 랭킹이 읽는 필드(`source_class`, `status`, 시간).
+- [성능 튜닝](https://github.com/ClickHouse/loom/blob/main/docs/guides/performance-tuning.md).
+- 오퍼레이션: [메모리](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md#memory),
+ [보정](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md#calibration),
+ [컨텍스트](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md#context). 설정:
+ [메모리 검색](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#memorysearch),
+ [메모리 질의](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#memoryask),
+ [Mcp](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#mcp).
diff --git a/i18n/.pending/ko/docs/development/adding-a-table.md b/i18n/.pending/ko/docs/development/adding-a-table.md
new file mode 100644
index 0000000000..eae82293de
--- /dev/null
+++ b/i18n/.pending/ko/docs/development/adding-a-table.md
@@ -0,0 +1,103 @@
+
+> 이 페이지는 [영어 원문](https://github.com/ClickHouse/loom/blob/main/docs/development/adding-a-table.md)을 기계 번역한 것이며, 영어 원문이 기준입니다.
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/development/adding-a-table.md), which is authoritative.
+
+
+
+# ClickHouse 테이블 또는 컬럼 추가
+
+Loom의 ClickHouse 상태는 `loom` 및 `loom_telemetry` 데이터베이스의 테이블로 구성됩니다. Postgres 메모리 authority를 사용하는 경우 라이브 메모리, 지식 상태, 그리고 이와 함께 있는 레코드는 Postgres에 있습니다. [스토리지 authority](https://github.com/ClickHouse/loom/blob/main/docs/architecture/storage-authority.md#the-tables) 페이지에 Postgres 테이블이 나와 있습니다. 배포 중에는 두 빌드가 동일한 스키마를 사용하므로, ClickHouse 스키마는 번호가 매겨진 추가형(additive) 마이그레이션으로만 변경됩니다. 아래의 각 규칙은 테스트로 검증됩니다. [ClickHouse](../architecture/clickhouse.md)에서 테이블 계열을 설명합니다.
+
+```mermaid
+flowchart TD
+ A["schemas/migrations/NNN_name.sql"] --> B["make migrate (local ClickHouse)"]
+ B --> C["make schema-dump schemas/schema.sql"]
+ C --> D{"table holds memory content?"}
+ D -->|yes| E["erasure saga step + _CENSUS row"]
+ D -->|derived, no read path| F["STEP_ONLY_TABLES"]
+ D -->|no| G["NO_MEMORY_CONTENT + reason"]
+ C --> H{"column on loom.memory / shared / memory_embeddings?"}
+ H -->|yes| I["row builders + memory_versions mirror"]
+```
+
+
+
+## 1. 마이그레이션을 작성하고 스키마를 다시 생성하기
+
+[마이그레이션](https://github.com/ClickHouse/loom/blob/main/docs/development/migrations.md) 문서가 번호 매기기, 추가적(additive) 변경의 기준, 러너 지시문, 정렬 키 재구성, 고정된 ClickHouse 버전을 대상으로 하는 `make schema-dump` / `make schema-check` 등의 규칙을 다룹니다. 요약하면 다음과 같습니다.
+
+- 다음으로 비어 있는 번호를 붙여 `schemas/migrations/_.sql`을 추가합니다. 파일 머리말 주석에는 변경의 목적과 기존 행 및 이전 빌드에서 어떻게 보이는지를 적습니다.
+- 테이블은 `loom.
` 형식으로 지정하고 `IF NOT EXISTS` / `IF EXISTS`를 사용합니다. Loom 자체 테이블에서 파생되는 텔레메트리는 대신 `loom_telemetry`에 둡니다([이유](../architecture/clickhouse.md)). preflight가 이 데이터베이스의 권한을 이미 확인하며, 삭제 대상 조사(erasure census)는 테이블 이름을 데이터베이스와 함께 표기합니다.
+- 병합된 마이그레이션은 수정하거나 삭제하지 않습니다. 실수는 새 파일로 바로잡습니다.
+- `make migrate`, `make schema-dump`를 실행한 다음 `python scripts/codegen/docs_reference.py`를 실행하여 [스키마 레퍼런스](https://github.com/ClickHouse/loom/blob/main/docs/reference/schema.md)에 해당 테이블이 나열되도록 합니다.
+
+배포 환경에 마이그레이션이 적용되기 전까지, 클라이언트의 스키마 가드는 대기 중인 마이그레이션이 생성할 테이블을 지정하는 읽기 또는 쓰기를 `SCHEMA_PENDING`으로 거부합니다.
+
+
+
+## 2. ReplacingMergeTree 쓰기 경로에서 모든 컬럼 미러링하기
+
+`loom.memory`, `loom.shared`, `loom.memory_embeddings`는 `FINAL`로 읽는 `ReplacingMergeTree(version)` 테이블입니다. 새 버전 행을 쓰는 모든 핸들러(set, tombstone, restore, touch, `update_by_id`, `bulk_set`, promote, demote)는 저장되는 컬럼을 **모두** 다음 버전으로 그대로 가져가야 합니다. 이후 버전 행에서 빠진 컬럼은 `FINAL`로 읽을 때 0으로 읽힙니다.
+
+이 테이블에 컬럼을 추가할 때는 다음을 따릅니다.
+
+1. `server/memory/store/rows.py`의 표준 컬럼 목록(`MEMORY_PERSISTED_COLS` 또는 `EMBEDDING_PERSISTED_COLS`)에 추가합니다.
+2. 같은 파일의 빌더(`build_memory_version_row`, `build_revision_row`, `build_first_version_row`, `build_embedding_row`)와, 이 빌더에 값을 공급하는 모든 프로젝션(기존 행을 불러오는 `SELECT`)에 컬럼을 반영합니다.
+3. 핸들러에서 버전 행을 직접 만들지 말고 빌더를 호출합니다.
+
+`tests/unit/test_memory_write_path_mirror.py`와 `tests/unit/test_embedding_mirror_carry.py`가 보조 쓰기 경로를 검사합니다.
+
+**히스토리 미러.** `loom.memory_versions`는 `loom.memory`의 추가 전용(append-only) 쌍둥이 테이블이며 `memory_versions_mv` 구체화 뷰(materialized view)가 채웁니다. 병합 시 `ReplacingMergeTree`에서 대체된 행이 사라지기 때문에 `memory.history`, `memory.redact`, `namespace.rollback`은 이 테이블을 읽습니다. `loom.memory`에 새 컬럼을 추가하면 **같은 마이그레이션에서** `loom.memory_versions`와 뷰의 `SELECT`에도 추가하세요. `tests/unit/test_memory_versions_schema.py`는 `schema.sql`의 두 컬럼 목록을 `MEMORY_PERSISTED_COLS`와 비교합니다.
+
+새 쓰기 경로는 요청 본문의 값이 아니라 서버가 기록하는 `actor`와 `source_class`(`server.memory.domain.provenance`)를 설정해야 합니다.
+
+
+
+## 3. 삭제를 위해 테이블 분류하기
+
+삭제는 사가(saga)로 동작합니다(`server/erasure/app/saga.py`). 마지막 단계는 읽기 경로가 접근하는 모든 테이블에 대한 잔여 데이터 조사(residue census)이며, 범위 안에 살아 있는 행이 하나라도 있으면 사가는 실패로 닫힙니다. `tests/unit/test_every_table_is_classified.py`는 `schema.sql`의 `CREATE TABLE` 중 `server/erasure/store/census.py`의 세 목록 가운데 정확히 한 곳에 들어 있지 않은 것이 있으면 실패합니다.
+
+| 목록 | 이런 경우 테이블을 여기에 넣습니다 | 함께 추가할 것 |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `_CENSUS` | 읽기 경로가 제공하는 메모리 콘텐츠를 담을 수 있는 경우. | 범위 안의 행을 제거하는 사가 단계, 그리고 범위별로 해당 단계를 지정하는 `Substrate(table, live, user_pred, ns_step, user_step)`. |
+| `STEP_ONLY_TABLES` | 사가 단계가 이 테이블을 변경하지만 census는 세지 않는 경우(파생 원장, 별칭 맵). 이유는 dict 위의 주석에 적습니다. | 이름을 키로 하는 단계. |
+| `NO_MEMORY_CONTENT` | 범위 안에 메모리 콘텐츠가 없는 경우(카운트, 커서, 공개 데이터의 캐시). | 한 줄짜리 이유. |
+
+`_CENSUS` 테이블의 경우:
+
+- `live`는 살아 있는 행이 만족하는 조건식입니다(`tombstoned_at IS NULL`, 또는 모든 행을 세는 경우 `"1"`). `user_pred`는 테이블에 사용자 축이 있으면 `user_id = {uid:String}`이고, 네임스페이스 전용 테이블이면 `None`입니다(이 경우 네임스페이스 범위 삭제에서만 집계됩니다).
+- 단계는 `server/erasure/store/steps_*.py`에 있는 함수이며, 해당되는 각 사가 테이블(`server/erasure/app/saga_steps.py`의 `NAMESPACE_STEPS`, `USER_STEPS`)에 단계 이름과 함께 등록합니다. 일반 `MergeTree`에서는 `Substrate`에 `final=False`를 지정합니다(FINAL을 사용할 수 없습니다).
+- 재개된 사가는 마지막 census에서 행이 발견된 테이블의 소유 단계를 다시 실행하므로(`steps_to_reopen`), 단계는 멱등이어야 합니다.
+- `(org, namespace)`를 키로 하는 코드 플레인 테이블은 보통 `CODE_INDEX_STEP_ONLY_TABLES`에 속합니다(사가의 `code_index.purge` 단계가 제거합니다). 이 튜플이 스키마와 일치하는지는 단위 테스트가 확인합니다.
+
+`tests/unit/test_erasure_repo.py`와 `tests/unit/test_erasure_late_steps.py`처럼 스텁 클라이언트로 단계의 구문 형태를 테스트하세요.
+
+
+
+## 4. 모든 뮤테이션 분류하기
+
+`ALTER TABLE loom. UPDATE|DELETE`는 ClickHouse 뮤테이션입니다. 파트를 비동기적으로 다시 쓰며 트랜잭션을 지원하지 않습니다. `tests/unit/test_clickhouse_mutation_inventory.py`는 `server/` 아래에서 눈에 보이는 모든 뮤테이션을 세어 `_EXPECTED_MUTATIONS`와 비교합니다. 새 뮤테이션은 그곳에 이유를 설명하는 주석과 함께 추가하기 전까지 테스트에 실패합니다.
+
+`ReplacingMergeTree`의 새 버전 행, 톰스톤 컬럼 또는 경량 `DELETE FROM`을 사용하는 편이 좋습니다. 요청이 대기하는 클레임이나 잠금으로 뮤테이션을 사용해서는 안 됩니다. 작업 인박스는 대신 `KeeperMap` 리스 테이블을 통해 클레임합니다.
+
+
+
+## 체크리스트
+
+- [ ] 새 `schemas/migrations/_.sql`을 추가합니다. 추가형(additive)이며 멱등이어야 하고, 이미 병합된 파일은 수정하지 않습니다.
+- [ ] 새로 고정된 ClickHouse를 대상으로 `make schema-dump`를 실행하고, `make schema-check`가 깨끗하게 통과해야 합니다.
+- [ ] 스키마 레퍼런스를 위해 `python scripts/codegen/docs_reference.py`를 실행합니다.
+- [ ] RMT 컬럼: `rows.py` 컬럼 목록, 빌더, 프로젝션을 갱신하고, `memory_versions`와 `memory_versions_mv`도 같은 마이그레이션에 포함합니다.
+- [ ] 삭제(erasure) 분류: `_CENSUS`와 saga 단계, `STEP_ONLY_TABLES`, 또는 사유를 적은 `NO_MEMORY_CONTENT` 중 하나로 분류합니다.
+- [ ] 새로운 변경(mutation)은 모두 인벤토리 테스트에 등록합니다.
+- [ ] [스토리지 레이아웃](https://github.com/ClickHouse/loom/blob/main/docs/architecture/storage-layout.md)에 행을 추가합니다. ClickHouse 테이블은 해당 패밀리의 표에, 이름이 `_`로 시작하는 테이블은 `_` 테이블 섹션에 넣고, 모든 컬럼을 채웁니다. `tests/unit/test_storage_layout_rows.py`는 해당 행이 존재하는지(ClickHouse 테이블의 경우 테이블이 삭제되면 행도 사라졌는지, 삭제된 Postgres 테이블의 행은 직접 제거합니다), 그리고 ClickHouse 행의 경우 Today 셀이 스키마와, Erasure 셀이 census와 일치하는지, 인용이 해당 테이블 이름을 포함하는지 검사합니다. 스키마 덤프가 보류 중이면 덤프가 반영될 때까지 실패합니다.
+- [ ] `make test-unit`을 실행합니다(추가형, 번호 매기기, 미러, 분류, 인벤토리 테스트).
+
+
+
+## 관련 문서
+
+- [마이그레이션](https://github.com/ClickHouse/loom/blob/main/docs/development/migrations.md)
+- [ClickHouse](../architecture/clickhouse.md)
+- [보존 및 삭제](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/retention-and-erasure.md)
+- [업그레이드](https://github.com/ClickHouse/loom/blob/main/docs/operations/upgrades.md)
diff --git a/i18n/.pending/ko/docs/development/adding-a-worker.md b/i18n/.pending/ko/docs/development/adding-a-worker.md
new file mode 100644
index 0000000000..18be4aaa2a
--- /dev/null
+++ b/i18n/.pending/ko/docs/development/adding-a-worker.md
@@ -0,0 +1,187 @@
+
+> 이 페이지는 [영어 원문](https://github.com/ClickHouse/loom/blob/main/docs/development/adding-a-worker.md)을 기계 번역한 것이며, 영어 원문이 기준입니다.
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/development/adding-a-worker.md), which is authoritative.
+
+
+
+# 백그라운드 워커 추가
+
+워커는 `server/workers/registry.py`(`_WORKERS`)의 한 행과 패스 함수 하나를 가진 모듈로 구성됩니다. `enabled_workers()`는 활성화된 행을 `WorkerSpec`으로 변환하고, `WorkerSupervisor`(`server/workers/supervisor.py`)는 각 워커를 실행하고, 시간을 측정하고, 백오프를 적용하고, 종료 처리를 합니다. 생성된 [워커 레퍼런스](https://github.com/ClickHouse/loom/blob/main/docs/reference/workers.md)에서 모든 행을 확인할 수 있습니다.
+
+```mermaid
+flowchart LR
+ S["settings <name>_enabled, <name>_interval_seconds"] --> R["_Worker row in _WORKERS"]
+ R --> E["enabled_workers() WorkerSpec"]
+ L["leader.py supervisor lock"] --> V["WorkerSupervisor"]
+ E --> V
+ V --> P["run_pass() server/<domain>/workers/<name>.py"]
+ V --> W["loom.worker_status /v1/admin/workers.status"]
+```
+
+
+
+## 1. 패스 작성하기
+
+`server//workers/.py`에 `async def run_pass()`를 만듭니다. 슈퍼바이저는 이 함수를 간격마다 한 번 호출하고 반환값은 버립니다. 작은 예시는 `server/tasks/workers/lease_sweep.py`입니다.
+
+```python
+from server.workers import pass_context
+from server.workers.status import record_pass
+
+
+async def run_pass() -> SweepResult:
+ from server.tasks.app.sweep import sweep_once
+
+ with record_pass("task_lease_sweep") as rec:
+ counts = await sweep_once()
+ rec.outcome = dict(counts)
+ result = SweepResult(**counts)
+ if result.total == 0:
+ pass_context.mark_idle()
+ else:
+ log.info("task_lease_sweep: expired=%d ...", result.expired)
+ return result
+```
+
+패스 규약은 다음과 같습니다.
+
+- **멱등성과 제한된 작업량.** 패스는 마감 시간에 취소될 수도 있고, 크래시 후 다시 실행될 수도 있으며, 배포 후 다른 색상에서 실행될 수도 있습니다. 제한된 양의 작업만 수행하고 나머지는 다음 패스에 남겨 두세요.
+- **마감 시간.** 기본값은 `min(4 × interval, 900 s)`이며 최소 60 s입니다(`default_max_pass_seconds`). 마감 시간을 넘긴 패스는 취소되며 실패로 집계됩니다. 더 오래 걸리는 패스에는 해당 행에 `max_pass_seconds` 또는 `max_pass_setting`을 설정하세요.
+- **실패.** 예외가 발생하면 패스가 실패합니다. 슈퍼바이저는 지수 백오프(1 s에서 시작해 60 s까지 두 배씩 증가)로 재시도하며, 연속 3회 실패하면 워커를 `degraded`로 표시합니다. 마감 시간에 중단된 패스나, 간격이 마감 시간보다 긴 워커(일간 및 주간 패스)는 전체 간격만큼 기다립니다(`failure_hold_seconds`). 그래서 재시도가 같은 데이터베이스 시간을 다시 소모하지 않습니다.
+- **부분 실패.** 패스 자체는 실패시키지 않고 일부 단계만 실패하는 경우 `pass_context.note_failure(exc, what)`를 호출합니다. 이 호출은 연속 실패 횟수에 반영되며 `loom.worker.partial_failures{worker}`에 표시됩니다.
+- **유휴.** 처리할 것이 없었던 패스는 `pass_context.mark_idle()`을 호출합니다. 그러면 슈퍼바이저는 `idle_interval_seconds`만큼 대기합니다.
+- **커서.** 페이징하는 워커는 `pass_context.resume_cursor()`로 커서를 읽고, 멈춘 지점에서 `pass_context.set_cursor(value)`를 호출합니다. 커서는 해당 패스의 `loom.worker_status` 행에 저장되므로 프로세스를 재시작해도 이어서 실행됩니다.
+- **광범위한 `except`에는 이유를 적습니다.** `# noqa: BLE001 — `
+
+
+
+## 2. 쿼리 출처 지정하기
+
+supervisor는 모든 패스에 태그를 붙입니다.
+
+- ClickHouse 쿼리는 `log_comment` `worker.`을 가집니다(`server/workers/status.py`의 `set_worker_identity`).
+- 프로바이더 스팬은 `loom.operation=worker.`을 가집니다.
+- 패스는 백그라운드 트래픽 클래스(`bind_background`)에서 실행됩니다.
+- 패스의 LLM 및 임베더 사용 비용은 하나의 원장 행 `worker..pass`에 기록됩니다.
+
+supervisor **밖에서** 도는 루프(태스크, 스레드, CLI 루프)는 스스로 태그를 지정해야 합니다. 그렇지 않으면 해당 쿼리가 `untagged:.`으로 기록됩니다.
+
+```python
+from server.core.ch import set_query_tag
+
+set_query_tag("worker.my_loop")
+```
+
+
+
+## 3. 설정 추가하기
+
+`server/settings/catalog.py`에서 해당 영역의 섹션(`Memory`, `Code`, `Tracker` 등)에 스위치와 실행 주기를 추가합니다. 각 주석은 생성되는 [설정 레퍼런스](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md)에서 해당 행의 설명 텍스트가 됩니다.
+
+```python
+ # Lease sweeper: return expired leases to todo, resume deferred tasks at
+ # resume_at, escalate stale triage. One read per pass.
+ task_lease_sweep_enabled: bool = True
+ # Seconds between passes while there is work.
+ task_lease_sweep_interval_seconds: int = 60
+ # Seconds between passes that found nothing.
+ task_lease_sweep_idle_interval_seconds: int = 300
+```
+
+워커가 자격 증명을 필요로 하거나, 외부 제공자에 비용을 지출하거나, 운영자가 직접 선택해 사용하는 플레인을 담당한다면 기본값을 **off**로 설정합니다. 기본값이 on인 워커는 노트북을 포함한 모든 스택에서 실행됩니다.
+
+
+
+## 4. 레지스트리 행 추가
+
+```python
+(
+ _Worker(
+ "task_lease_sweep",
+ "server.tasks.workers.lease_sweep",
+ "task_lease_sweep_enabled",
+ "task_lease_sweep_interval_seconds",
+ idle_interval="task_lease_sweep_idle_interval_seconds",
+ ),
+)
+```
+
+| `_Worker` 필드 | 의미 |
+| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `name` | 워커의 이름입니다. 로그 태그, 원장 operation, 상태 행에 쓰입니다. |
+| `module` | 전체 모듈 경로입니다. 워커가 활성화된 경우에만 import되므로 부팅이 빠르게 유지되고 선택적 의존성은 선택 사항으로 남습니다. |
+| `enabled` | 워커를 켜는 설정 플래그입니다. `None`이면 항상 켜집니다. |
+| `interval` | 주기를 초 단위로 담고 있는 설정 필드입니다. |
+| `pass_attr` | 패스 함수의 이름입니다(기본값 `run_pass`). |
+| `also_requires` | 워커에 필요한 두 번째 설정 플래그입니다(읽는 원장, 제공하는 플레인). 꺼져 있으면 워커도 꺼집니다. |
+| `idle_interval` | 유휴 패스 이후의 대기 시간을 담는 설정 필드입니다. |
+| `max_pass_seconds`, `max_pass_setting` | 패스 제한 시간입니다. 고정값을 쓰거나 설정에서 읽습니다. |
+| `first_pass_due` | 모듈 속성입니다. 시작할 때 한 번 호출되는 비동기 검사이며, `True`이면 부팅 지연 이후가 아니라 지금 첫 패스를 실행합니다. |
+| `owned_tables` | `True`: 모듈이 `OWNED_TABLES`와 `due_scope`를 export합니다. 범위 내 네임스페이스에 대해 소유 테이블에 행이 없으면 첫 패스가 실행 대상이 됩니다. |
+
+**부팅 지연.** 첫 패스 훅이 없으면 첫 패스는 `crc32(name) % interval`만큼 기다립니다. 그러면 몇 시간만 살아 있는 프로세스에서 하루 주기 워커는 한 번도 실행되지 않을 수 있으므로, 워커가 채우는 대상을 선언하세요.
+
+```python
+from server.workers.first_pass import OwnedTable
+
+OWNED_TABLES = (OwnedTable("loom.qa_item_embeddings", namespace_column="namespace"),)
+
+
+def due_scope() -> list[tuple[str, str]]: ... # the (org, namespace) pairs this worker fills
+```
+
+이는 `server/tracker/workers/embed.py`의 선언입니다. 검사는 테이블당 쿼리 한 번이며 `FIRST_PASS_DUE_TIMEOUT_SECONDS`로 제한됩니다. 읽을 수 없는 테이블은 실행 대상으로 간주됩니다.
+
+
+
+## 5. 실행 위치 이해하기
+
+**배포당 하나의 supervisor.** `server/workers/leader.py`는 ClickHouse를 통해 모든 컨테이너와 호스트에 걸쳐 하나의 프로세스를 선출합니다. 이때 Keeper 락 테이블 `loom._migration_lock`의 `workers_supervisor` 키를 사용합니다. 리더는 `LOOM_SUPERVISOR_LEASE_TTL_S / 6`마다 임대를 갱신합니다. 임대를 잃은 리더는 자신의 워커를 중지합니다. 리더가 종료되면 `LOOM_SUPERVISOR_LEASE_TTL_S`(기본값 30초)가 지난 뒤 다른 프로세스가 이를 이어받습니다.
+
+| `LOOM_BACKGROUND_WORKERS` | 효과 |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `auto` (기본값) | 임대를 얻기 위해 경쟁하고, 임대를 보유하는 동안 supervisor를 실행합니다. 배포 환경 밖(`LOOM_DEPLOYMENT` 없음)에서는 `off`입니다. |
+| `on` | 항상 supervisor를 실행합니다. |
+| `off` | 웹만 실행합니다. |
+
+모든 레플리카를 `auto`로 실행하세요. 어떤 레플리카든 리더가 될 수 있습니다. `make server` 또는 iso 서버는 `on`으로 설정하지 않으면 워커를 실행하지 않습니다.
+
+**두 복사본이 잠시 겹칠 수 있습니다.** 리더는 갱신 없이 T/2가 지나면 워커를 중지하며, 이는 다른 프로세스가 T에 이어받기 전입니다. 그러나 이미 전송된 구문은 그대로 반영되며, `on` 프로세스는 임대를 가져가지 않습니다. 두 번째 복사본이 해를 끼치지 않도록 만드세요. 멱등 쓰기, 임대 기반 클레임, 저장소에 보관하는 커서가 그 방법입니다. LLM에 비용을 쓰는 워커는 두 복사본이 실행되는 동안 비용이 두 배가 됩니다.
+
+**배치 사이에서 중단하기.** 오래 도는 루프는 쓰기를 수행하는 배치마다 앞서 `pass_context.check_stop()`을 호출합니다. 이 호출은 패스가 중지되었거나 임대가 만료되면 `PassStopped`를 발생시키며, `asyncio.to_thread`에서 실행 중인 작업에도 전달됩니다. `PassBudget.exhausted()`는 이를 대신 호출해 줍니다.
+
+**롤링 업그레이드.** 이전 빌드는 실행 중인 최신 빌드에 임대를 양보합니다([장애와 복구](../architecture/failure-and-recovery.md#background-workers) 참고). 이전 리더는 중지될 때 임대를 해제하고, 더 새로운 프로세스가 다음 라운드에서 몇 초 안에 이를 가져갑니다.
+
+
+
+## 6. 테스트에 고정하기
+
+- **레지스트리 스냅샷.** `tests/unit/test_worker_registry_snapshot.py`는 세 가지 설정 프로필(`defaults`, `all_on`, `production`)에서 워커 목록을 만들고, 모든 `WorkerSpec` 필드를 `tests/unit/snapshots/worker_registry.json`과 비교합니다. 의도한 변경일 때만 다시 생성하세요.
+
+ ```bash
+ LOOM_UPDATE_WORKER_SNAPSHOT=1 python -m pytest tests/unit/test_worker_registry_snapshot.py
+ ```
+
+ production에서 해당 워커를 실행해야 한다면, 이 테스트의 `_PRODUCTION_FLAGS`에 워커의 플래그를 추가하세요.
+
+- **일치 검사.** `tests/unit/test_worker_registry_parity.py`는 모든 플래그를 켠 상태에서 `worker_meta()`(`/v1/admin/workers.status`가 렌더링하는 내용)와 `enabled_workers()`가 동일한 집합을 나열하는지 확인합니다.
+- **패스 자체.** 단위 테스트에서 스텁 리포지토리 또는 로컬 ClickHouse를 대상으로 `run_pass()`를 호출합니다. 감독되는 패스 밖에서는 `pass_context` 호출이 로그만 남깁니다.
+- **생성된 문서.** `python scripts/codegen/docs_reference.py`는
+ [워커 레퍼런스](https://github.com/ClickHouse/loom/blob/main/docs/reference/workers.md)를 다시 생성합니다. 이 문서가 최신이 아니면 `make lint`가 실패합니다.
+
+
+
+## 7. 실행 확인
+
+- `/v1/admin/workers.status`는 이 프로세스의 레지스트리와 워커별 최신 `loom.worker_status` 행을 병합하므로, 웹 티어에서 workers 컨테이너에서 실행 중인 워커를 확인할 수 있습니다.
+- `/v1/health?include=workers`는 워커별 상태와 `workers_leader`를 보고합니다. 이 값은 응답하는 프로세스가 잠금을 보유하고 있는지와 그 이유를 나타냅니다.
+- `loom.worker.consecutive_failures{worker}`와 `loom.worker.partial_failures{worker}`에 알림을 설정하세요 ([모니터링](https://github.com/ClickHouse/loom/blob/main/docs/operations/monitoring.md)).
+
+
+
+## 관련 문서
+
+- [Loom 확장하기](https://github.com/ClickHouse/loom/blob/main/docs/development/extending-loom.md)
+- [워커 레퍼런스](https://github.com/ClickHouse/loom/blob/main/docs/reference/workers.md)
+- [장애와 복구](../architecture/failure-and-recovery.md)
+- [워커 상태](https://github.com/ClickHouse/loom/blob/main/docs/operations/monitoring.md#worker-status)
diff --git a/i18n/.pending/ko/docs/development/adding-language-support.md b/i18n/.pending/ko/docs/development/adding-language-support.md
new file mode 100644
index 0000000000..4c948f5a2d
--- /dev/null
+++ b/i18n/.pending/ko/docs/development/adding-language-support.md
@@ -0,0 +1,139 @@
+
+> 이 페이지는 [영어 원문](https://github.com/ClickHouse/loom/blob/main/docs/development/adding-language-support.md)을 기계 번역한 것이며, 영어 원문이 기준입니다.
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/development/adding-language-support.md), which is authoritative.
+
+
+
+# 코드 인덱스에 언어 지원 추가하기
+
+코드 인덱스는 저장소를 두 개의 티어로 읽습니다.
+
+- **빠른 티어**(tree-sitter 문법과 직접 작성한 스캐너)는 모든 커밋에서 모든 파일에 대해 실행됩니다. 청크, 심볼, 호출 엣지를 생성합니다.
+- **컴파일러 티어**(변경된 파일에 대한 SCIP 인덱서)는 인덱서가 있는 경우 컴파일러 수준으로 정확한 심볼과 엣지를 추가합니다.
+
+빠른 티어에 해당 언어를 처리하는 레인이 있으면 그 언어를 지원하는 것입니다. [코드 인덱스](https://github.com/ClickHouse/loom/blob/main/docs/features/code-index/overview.md)에서 티어에 대한 설명과 각 언어가 제공받는 기능 목록을 확인할 수 있습니다.
+
+
+
+## 단 하나의 규칙: extractor stamp를 건드리지 않는다
+
+빠른 티어 행에는 해당 행을 만든 코드의 버전 스탬프가 들어 있습니다 (`server/code/domain/extract/extractor_stamp.py`):
+
+- 스탬프는 `STAGE_MODULES`에 속한 모든 모듈의 **코드 토큰**(`logic_tokens`: 주석, 빈 줄, docstring 제외. import는 패키지 경로가 아니라 바인딩되는 이름으로 계산)과 `STAMPED_GRAMMARS`에 있는 grammar(`tree-sitter`, `tree-sitter-cpp`, `tree-sitter-python`, `tree-sitter-bash`)의 설치된 버전에 대한 sha256입니다.
+- 스탬프가 바뀌면 ingest 워커는 영향을 받는 언어 계열에 속한, 인덱싱된 모든 네임스페이스의 모든 파일에 대해 변경된 단계(`chunk`, `symbol`, `edge`, `guard`)를 속도를 조절한 배치로 다시 도출합니다 (`server/code/app/index/ingest_pass.py`의 `_maybe_rechunk`).
+- `MODULE_LANGUAGES`에서 한 계열에만 매핑된 모듈(`lang_python.py`, `ts_*` 모듈)은 해당 계열의 파일만 다시 처리하게 합니다. 공유 모듈(`treesitter.py`, `chunker.py`)이나 핵심 `tree-sitter` grammar가 바뀌면 모든 파일이 다시 처리됩니다.
+- 대규모 배포에서는 ingest에 몇 시간이 걸립니다.
+
+스탬프가 바뀌지 않는 위치에 새 언어를 추가합니다:
+
+| 파일 | 스탬프에 포함? | 들어갈 내용 |
+| -------------------------------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------- |
+| `server/code/domain/extract/lang_.py` | 아니요 | 레인: 심볼, include, 호출 지점을 담은 `parse_(path, source) -> ParsedFile`. |
+| `server/code/domain/extract/lang_detect.py` | 아니요 | `LANG_BY_EXTENSION`(및 셸 규칙): 어떤 파일이 이 언어에 해당하는지 정합니다. |
+| `server/code/app/index/ingest_parse.py` | 아니요 | `_PARSERS`의 `_parse_` 래퍼. 레인에 import가 있으면 `ingest_resolve.py`에 include 해석을 추가합니다. |
+| `server/code/domain/extract/lane_units.py` | 아니요 | grammar가 **없는** 레인을 위한 공유 헬퍼: `span_chunks`와 `bind_sites` 참조 바인더. |
+| `server/code/domain/extract/treesitter.py` | **예** | 스탬프된 핵심 언어 전용 `lang_for_path`. 여기에 확장자를 추가하면 모든 네임스페이스가 다시 청킹됩니다. |
+| `chunker.py`, `edges_treesitter.py`, 그 외 `STAGE_MODULES` | **예** | 공유 청킹 및 edge 추출. 모두에게 적용되는 추출 방식 자체가 바뀔 때만 변경합니다. |
+
+`lang_for_path`에 이름이 없는 언어는 `lang_detect.py`에서 감지하므로, 언어를 추가해도 스탬프는 바뀌지 않습니다. 스탬프된 모듈의 주석과 docstring은 자유롭게 수정해도 됩니다. 이 모듈들은 포매터 대상에서 제외되어 있는데, 포매터가 코드 토큰인 문자열 따옴표를 다시 쓸 수 있기 때문입니다.
+
+`server/code/domain/extract/` 아래의 모든 모듈은 `STAGE_MODULES`의 단계에 속하거나, `tests/unit/test_code_extractor_stamp.py`의 `NON_EXTRACTOR_MODULES`에 이유와 함께 명시되어 있어야 합니다. 새 레인 모듈은 `NON_EXTRACTOR_MODULES`에 넣어야 하며, 그렇지 않으면 해당 테스트가 실패합니다.
+
+
+
+## 1. 레인의 형태 선택
+
+| 형태 | 예시 | 제공해야 할 것 |
+| ----------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 문법 레인 | `lang_typescript.py`, `lang_rust.py`, `lang_go.py`, `lang_java.py` | `pyproject.toml`의 tree-sitter 문법 의존성. 심볼과 호출 지점은 트리에서 추출하며, 청크와 엣지는 공유 청커와 엣지 워커가 만듭니다. |
+| 트리 없는 레인 | `lang_proto.py`, `lang_gotemplate.py`, `lang_hcl.py`, `lang_k8s.py`, `lang_jsonnet.py` (`LANE_UNIT_LANGS`) | 직접 작성한 스캐너. `ParsedFile.tree`는 `None`으로 유지되며, 청크는 `lane_units.span_chunks`에서, 엣지는 `reference_sites` + `SITE_RULES`를 `lane_units.bind_sites`로 바인딩해 만듭니다. |
+| include 전용 레인 | `tla`, `flatbuffers`, `cmake`, `doc` (`_LANE_INCLUDE_LANGS`) | 단순 레인 리졸버가 해석하는 심볼과 include. |
+| 임베디드 언어 | Go와 Java 안의 SQL (`go_sql_units`, `java_sql_units`), Dockerfile과 Makefile 안의 셸 영역 | 호스트 파일의 파싱에 합쳐지는 유닛(`_join_island_symbols`). 보통 킬 스위치 설정이 함께 제공됩니다. |
+| 청크 전용 | `.css`, 텍스트 파일 (`lang_text.py`) | 감지 외에는 필요 없음. 파일은 청크로 나뉘어 검색할 수 있지만 심볼은 없습니다. |
+
+문법 레인의 문법은 `STAMPED_GRAMMARS`에 **포함되지 않으므로**, 문법을 업그레이드해도 스탬프가 바뀌지 않습니다. 레인이 자체 행을 다시 도출할 책임을 집니다.
+
+
+
+## 2. 파서 작성
+
+`parse_(path: str, source: bytes) -> ParsedFile`은 언어 태그, 심볼(`treesitter.Symbol`: 한정 이름(qualified name), 종류, 범위, 시그니처), include, 그리고 엣지 단계에 필요한 정보를 반환합니다. 가장 가까운 기존 레인을 따르세요.
+
+- **한정 이름(qualified name)**은 언어의 모듈 경로를 따릅니다(Rust: 파일 경로에서 얻은 crate 경로이며, `mod.rs` / `lib.rs`는 해당 디렉터리의 이름이 됩니다). 심볼 id는 한정 이름과 정규화된 시그니처를 해시한 값이므로, 이름이 불안정하면 재인덱싱할 때마다 행이 바뀝니다.
+- **Include**는 네임스페이스가 가진 경로를 기준으로 해석합니다(`wanted_paths`, 이어서 레인의 `resolve_imports` / `resolve_uses`를 사용하며 `ingest_resolve.py`에서 호출합니다). 외부 패키지는 추측하지 않고 아무것도 가리키지 않도록 해석합니다.
+- **호출 엣지**는 같은 파일에서 유일한 이름을 먼저 바인딩하고, 그다음 저장소 전체에서 유일한 이름을 더 낮은 신뢰도로 바인딩하며, 이름이 모호하면 바인딩하지 않습니다(트리가 없는 레인에서는 `lane_units.bind_sites`가 이를 처리합니다).
+- **컨테이너 종류**(클래스, impl 블록)는 레인에 속합니다. 청커의 언어별 테이블에 등록하면 `chunker.py`가 바뀌고 스탬프가 달라집니다.
+
+레인을 등록합니다.
+
+```python
+# server/code/app/index/ingest_parse.py
+def _parse_rust(path: str, source: bytes) -> ParsedFile:
+ from server.code.domain.extract.lang_rust import parse_rust
+
+ return parse_rust(path, source)
+
+
+_PARSERS = {
+ ...
+ "rust": _parse_rust,
+ ...
+}
+```
+
+그리고 `LANG_BY_EXTENSION`에 확장자(`".rs": "rust"`)를 추가합니다. 래퍼는 레인을 지연 import하므로 선택적 grammar는 계속 선택적으로 남습니다. 새 tree-sitter grammar는 모든 파싱이 가장 먼저 거치는 `bounded_parse._LOADERS`에도 추가해야 합니다.
+
+
+
+## 3. 레인 테스트
+
+- **레인 테스트**, `tests/unit/test_code_lang_.py`는 작은 인라인 소스를 파싱하고 이름, 종류, 범위, include, 엣지를 검증합니다. 문법(grammar)이 없으면 건너뜁니다: `pytest.importorskip("tree_sitter_rust")`. `test_code_lang_rust.py`와 `test_code_lang_typescript.py`가 모범 사례입니다.
+- **레인 코퍼스.** `tests/fixtures/code_lanes//` 아래에 픽스처를 추가합니다. 직접 만든 합성 코드이거나, 고유한 라이선스를 가진 오픈 소스 발췌본이며, 후자는 `tests/fixtures/code_lanes/NOTICE.md`에 나열합니다. `tests/unit/test_code_lanes_corpus.py`는 모든 픽스처에서 언어, 심볼, 패싯, include, 엣지를 도출하여 `tests/fixtures/code_lanes/expected.json`과 비교합니다. 다시 생성한 뒤 diff를 검토합니다:
+
+ ```bash
+ python -m tests.code_lanes.corpus --write
+ git diff tests/fixtures/code_lanes/expected.json
+ ```
+
+ 여기서 값이 바뀌면 모든 네임스페이스에 저장되는 내용이 달라집니다. 반드시 검토하세요.
+
+- **비용 가드.** `ingest_parse._PARSERS`에 추가한 파서는 `tests/unit/lane_walks.py`에 `SAMPLES` 항목이 필요합니다. 그러면 `tests/unit/test_code_regex_cost.py`가 생성된 여러 형태의 입력으로 레인의 실행 시간을 측정하고, 선형을 넘는 탐색이 있으면 실패합니다.
+- **스탬프 테스트.** `tests/unit/test_code_extractor_stamp.py`에서 새 모듈을
+ `NON_EXTRACTOR_MODULES`에 추가합니다.
+- **검색.** `code.search`나 `code.symbol`에 좋은 답을 내야 하는 레인이라면, 변경 전과 후에 코드 인텔리전스 게이트를 실행합니다. `make bench-code-intel-dry`는 질문 세트를 오프라인으로 검사하고, `make bench-code-intel`은 실제 임베더가 있는 서버를 대상으로 실행합니다. 가짜 임베더는 절대 사용하지 마세요 ([벤치마크 실행](https://github.com/ClickHouse/loom/blob/main/docs/benchmarks/running.md)).
+
+
+
+## 4. 기존 네임스페이스 최신 상태로 갱신하기
+
+스탬프 밖의 레인은 이미 인덱싱된 것을 바꾸지 않습니다. 새 커밋은 해당 레인을 사용하지만, 기존 파일은 이전 행을 그대로 유지합니다(대개 chunk만 있는 상태). 대상을 지정한 backfill로 다시 도출하세요.
+
+```bash
+git -C ls-files '*.rs' > rust-paths.txt
+loom code backfill --org --namespace --paths-file rust-paths.txt
+```
+
+`--paths-file`은 브랜치 팁에서 해당 저장소 상대 경로만 다시 수집하며 워터마크는 건드리지 않습니다. 서버의 `.env`와 저장소 미러가 있는 곳, 예를 들어 workers 컨테이너에서 실행하세요([코드 인덱스 운영](https://github.com/ClickHouse/loom/blob/main/docs/operations/code-index-operations.md)).
+
+> **경고:** 변경이 스탬프된 모듈(`chunker.py` 수정, `treesitter.py` 확장)을 건드려야 한다면 PR에 그 사실을 명시하세요. 해당 변경을 반영하는 모든 배포는 모든 네임스페이스에서 영향받는 계열의 모든 파일에 대해 이동된 단계를 다시 도출합니다. `chunker.py` 변경은 `chunk`만 이동시키고, `edges_treesitter.py` 변경은 `edge`, `chunk`, `guard`를 이동시키며, 파서 변경은 모든 단계를 이동시킵니다.
+
+
+
+## 5. 컴파일러 티어 추가하기 (선택 사항)
+
+빠른 티어의 엣지가 모호하고(오버로드, 동적 디스패치, re-export) SCIP 인덱서가 존재한다면 컴파일러 티어가 도움이 됩니다. `server/code/domain/index/compiler_tiers.py`의 `TIERS`에 티어 목록이 있습니다. 각 `TierSpec`은 인덱서(`scip-clang`, `scip-typescript`, `scip-go`, `scip-python`), 해당 인덱서의 `code_index_state` 워터마크 키(`scip_commit`, `scip_commit_ts`, `scip_commit_go`, `scip_commit_py`), 그리고 이를 진행시키는 워커를 지정합니다. 새 티어에는 다음이 필요합니다.
+
+1. 커밋 범위에서 변경된 파일에 대해 인덱서를 실행하고 그 출력을 Loom의 JSON 델타로 변환하는 하니스: `scripts/scip_harness/` (`run_delta.sh`, `run_typescript_delta.sh`, `run_python_delta.sh`, `run_go_monorepo_delta.sh`, `scip_to_delta.py`).
+2. 델타 워커(`server/code/workers/scip_ts_delta.py`, `scip_py_delta.py`, `scip_go_delta.py`가 모범 사례입니다): 워커의 `run_pass`는 자신의 `_run_repo`를 `server/code/app/index/compiler_tier.py`의 `run_tier`에 넘기며, 이 함수가 엔트리 루프, 실패 격리, 전체 실행 초기화를 담당합니다. 워커에는 `LOOM_CODE_SCIP__DELTA_ENABLED` / `_INTERVAL_SECONDS` / `_TIMEOUT_SECONDS` 설정이 함께 제공됩니다([워커 추가하기](https://github.com/ClickHouse/loom/blob/main/docs/development/adding-a-worker.md)). 외부 생산자는 대신 `code.scip_ingest`로 업로드하며, `code_scip_apply` 워커가 완결된 배치를 적용합니다.
+3. `code_scip_apply`의 `watermark_key_for`에 추가하는 워터마크 키와 `TierSpec` 행. 이를 통해 `code.index_status`와 대시보드가 해당 티어를 보고합니다.
+
+컴파일러 티어 행에는 `tier='scip'`이 지정됩니다. 읽기 시에는 이 행을 빠른 티어와 한정된 심볼 이름(qualified name, 모듈 또는 컨테이너로 한정된 심볼 이름) 기준으로 병합하며, 컴파일러 티어를 우선합니다. 인덱서가 건너뛴 파일과 델타가 반영되기 전의 커밋은 계속 빠른 티어에서 읽습니다.
+
+
+
+## 관련 문서
+
+- [코드 인덱스 개요](https://github.com/ClickHouse/loom/blob/main/docs/features/code-index/overview.md)
+- [코드 인덱스 아키텍처](../architecture/code-index-architecture.md)
+- [코드 인덱스 운영](https://github.com/ClickHouse/loom/blob/main/docs/operations/code-index-operations.md)
+- [Loom 확장하기](https://github.com/ClickHouse/loom/blob/main/docs/development/extending-loom.md)
diff --git a/i18n/.pending/ko/docs/development/migrations.md b/i18n/.pending/ko/docs/development/migrations.md
new file mode 100644
index 0000000000..e90451cb03
--- /dev/null
+++ b/i18n/.pending/ko/docs/development/migrations.md
@@ -0,0 +1,120 @@
+
+> 이 페이지는 [영어 원문](https://github.com/ClickHouse/loom/blob/main/docs/development/migrations.md)을 기계 번역한 것이며, 영어 원문이 기준입니다.
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/development/migrations.md), which is authoritative.
+
+
+
+# 마이그레이션
+
+이 페이지는 마이그레이션을 작성하는 규칙을 다룹니다. 배포 환경에서 마이그레이션을 적용하는 방법과 업그레이드 및 롤백 절차는 [업그레이드](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)는 `schemas/` 디렉터리의 구성을 안내하고 운영자용 도구를 나열합니다.
+
+
+
+## 저널과 원장
+
+- 스키마는 `schemas/migrations/`에 있는 번호가 매겨진 SQL 파일의 저널이며, `server/core/schema/migrate.py`가 숫자 접두사 순서대로 적용합니다. `000_migrations.sql`은 원장을 만들고, `016_baseline.sql`은 시작 스키마이며, 그 이후의 모든 파일은 델타입니다.
+- 적용된 각 파일은 내용의 SHA-256과 함께 `loom._migrations`에 기록됩니다. 다시 실행하면 새 파일만 적용됩니다. 내용이 바뀐 파일은 **체크섬 드리프트**이고, 저장소에 더 이상 없는 파일은 **원장 전용 행**입니다. `loom migrate --dry-run --strict`(CI 단계이자 배포 사전 점검)는 둘 중 어느 쪽이든 실패합니다. 텍스트는 그대로이고 이름만 바뀐 파일은 원장 전용 행이 아닙니다. SHA-256이 그 파일을 식별하므로, 다시 실행하지 않고 새 이름으로 기록됩니다.
+- 모든 파일은 `loom.
`과 `loom_telemetry.
`을 대상으로 합니다. 러너는 각 구문을 전송할 때 이를 `LOOM_CH_DATABASE`와 `LOOM_CH_TELEMETRY_DATABASE`로 매핑하므로(`server/core/ch_names.py`), 체크섬은 작성된 그대로의 파일을 기준으로 계산됩니다. 데이터베이스는 리터럴 `'loom'`이 아니라 `currentDatabase()` 또는 바인딩된 이름으로 값을 비교합니다(`tests/unit/test_ch_names.py`). 이름이 `_`로 시작하는 테이블의 키나 TTL을 변경하거나, 그런 테이블의 이름을 바꾸거나 교환하는 파일은 [스토리지 레이아웃](https://github.com/ClickHouse/loom/blob/main/docs/architecture/storage-layout.md)의 해당 행과 `tests/unit/test_storage_layout_rows.py`의 리셰이프 가드도 함께 갱신해야 합니다.
+
+
+
+## 번호 부여
+
+파일 이름은 `NNN_description.sql` 형식입니다. 러너는 이름이 아니라 정수 접두사를 기준으로 순서를 정하므로(`server/core/schema/journal.py`, `migration_order`), `1030_x.sql`은 `220_y.sql`보다 나중에 실행됩니다. 비어 있는 다음 번호를 사용하되 `main`과 열려 있는 pull request를 확인하고, 한 번 정한 번호는 유지하세요. 번호가 같은 파일 두 개도 적용되기는 하지만 접미사의 사전순으로 적용되며, 이는 누구도 의도하지 않은 순서입니다. 또한 리베이스로 파일 이름이 바뀌어도 다시 적용되는 것은 없습니다. `tests/unit/test_migration_numeric_order.py`는 번호가 겹치면 실패합니다.
+
+
+
+## 마이그레이션 작성 규칙
+
+- **병합된 마이그레이션을 수정하거나 삭제하지 않습니다.** 각 배포의 원장(ledger)에 해당 마이그레이션의 해시가 들어 있습니다. 수정이 필요하면 새 파일로 작성합니다.
+- **추가만 허용합니다.** 테이블, 컬럼, 인덱스, 프로젝션, 뷰는 추가할 수 있습니다. `server/`, `scripts/`, `bench/`, `dev/` 아래의 어떤 코드도 참조하지 않는 스킵 인덱스나 프로젝션은 삭제할 수 있습니다(이전 빌드는 최적화를 잃을 뿐 컬럼을 잃지는 않습니다). 코덱, 기본값, 테이블 설정을 변경하고, 타입을 넓히고, enum을 확장하는 것도 가능합니다. 테이블이나 컬럼을 삭제하거나 이름을 바꾸는 것, 테이블을 교체(exchange)하는 것은 절대 하지 않습니다. `tests/unit/test_migrations_additive.py`가 이를 강제합니다. 뷰와 테이블 중에서는 삽입 시점 materialized view에 대한 `DROP VIEW IF EXISTS`와 대체된 테이블에 대한 `DROP TABLE IF EXISTS`만 허용하며, 둘 다 `server/`, `scripts/`, `bench/`, `dev/` 아래의 어떤 파일도 해당 이름을 참조하지 않을 때만 가능합니다. 서비스 중인 빌드도, 운영자 도구(프로덕션 서비스를 대상으로 실행됨)도 이를 읽지 않기 때문입니다. 타입을 좁히는 것은 정규식으로 넓히는 것과 구별할 수 없으므로 리뷰에서 판단해야 합니다.
+- **컬럼은 두 번의 릴리스에 걸쳐 폐기합니다.** 먼저 해당 컬럼을 더 이상 읽거나 쓰지 않는 코드를 담은 릴리스를 배포합니다. 서비스 중인 어떤 빌드도 그 컬럼을 참조하지 않게 된 후에야 삭제합니다.
+- **모든 쓰기 경로가 새 컬럼을 포함해야 합니다.** `loom.memory` 또는 `loom.shared`에 컬럼을 추가할 때는 같은 변경에서 `server/memory/store/rows.py`의 행 빌더(`build_memory_version_row`, `build_embedding_row`)와 이 빌더에 데이터를 공급하는 모든 프로젝션을 함께 수정해야 합니다. 이 테이블들은 `FINAL`로 읽는 `ReplacingMergeTree(version)` 테이블이라, 컬럼을 빠뜨린 버전 행은 모든 읽기 측에서 해당 컬럼을 조용히 0으로 만듭니다. 새 `loom.memory` 컬럼은 같은 마이그레이션에서 `loom.memory_versions`와 `memory_versions_mv` 뷰의 `SELECT`에도 추가해야 하며, 그렇지 않으면 기록 이력에서 해당 컬럼이 누락됩니다(`tests/unit/test_memory_versions_schema.py`가 컬럼 목록을 비교합니다).
+- **메모리 콘텐츠를 담을 수 있는 테이블**에는 삭제(erasure) saga 단계와 잔여 데이터 조사 행(`server/erasure/store/census.py`의 `_CENSUS`)도 필요합니다. 어떤 목록에도 없는 새 테이블이 있으면 `tests/unit/test_every_table_is_classified.py`가 실패합니다([테이블 추가하기](https://github.com/ClickHouse/loom/blob/main/docs/development/adding-a-table.md)).
+- **엔진에 이식 가능한 DDL을 작성합니다.** 벡터 컬럼은 `Array(BFloat16) CODEC(NONE)`으로 선언합니다. `Quantized` 코덱을 사용할 수 있는 러너에서는 코덱이 적용된 상태로 생성됩니다([제한된 설정](../architecture/clickhouse.md#gated-clickhouse-settings)). 엔진 이름은 일반 `MergeTree`를 사용하며, ClickHouse Cloud에서는 이를 `SharedMergeTree`로 실행합니다.
+
+**추가만 허용하는 이유.** 마이그레이션이 실행되기 전에 서비스 중이던 빌드는 실행 후에도 자신이 알던 모든 테이블을 계속 읽고 쓸 수 있어야 합니다. 그래야 blue/green 롤백이 스키마 롤백이 아닌 프록시 전환으로 끝나고, 새 색상이 부팅 시 마이그레이션을 적용하는 동안 이전 색상이 계속 서비스할 수 있습니다. 그 대가는 여기서 치르게 됩니다. 컬럼 하나를 폐기하는 데 두 번의 릴리스가 필요하고, 키를 바꿀 때는 `ALTER` 대신 재빌드를 해야 합니다.
+
+
+
+## Runner 지시문
+
+마이그레이션 파일에는 runner가 읽는 주석 지시문을 넣을 수 있습니다.
+
+| 지시문 | 효과 |
+| ----------------------------------- | ----------------------------------------------------------------------------------------- |
+| `-- loom: tolerate-error ` | 파일이 지정한 서버 오류 하나를 견뎌 냅니다 (예: 일부 서버만 받아들이는 설정) |
+| `-- loom: rebuild-if-empty
` | `
`의 목표 정렬 키 또는 파티션 키를 선언합니다 (아래 참조) |
+| `-- loom: baseline covers N` | 이 파일은 번호가 N 이하이면서 저장소에 더 이상 없는 모든 파일을 대체합니다 |
+
+**베이스라인.** 베이스라인의 번호는 N이며, 대체하는 파일 중 가장 최신 파일 뒤에 옵니다. 새 데이터베이스는 이 파일을 실행합니다. 원장(ledger)에 파일 N이 있는 데이터베이스는 이 파일을 실행하지 않고 기록만 하며, 대체된 행은 그대로 유지합니다. strict 모드는 이 행을 오류가 아니라 대체됨(superseded)으로 보고합니다. 따라서 스쿼시(squash)할 때 원장을 직접 수정할 필요가 없고, 스쿼시 이전의 빌드도 자신의 파일이 모두 적용된 상태로 확인할 수 있습니다. 원장에 대체된 파일 일부는 있지만 파일 N은 없는 데이터베이스는 중간에 멈춘 것입니다. `loom migrate`는 이를 거부하고(`stranded`) 아무것도 변경하지 않습니다. 베이스라인을 실행하면 없는 파일을 건너뛰게 되고, 기록만 하면 그 파일들의 스키마를 가진 것처럼 표시되기 때문입니다. 스쿼시 이전의 빌드로 누락된 파일을 적용한 다음 다시 마이그레이션하십시오. 스쿼시는 변경마다 하지 말고 릴리스 시점에 하십시오. 스쿼시는 `schemas/schema.sql`(유지되는 파일이 생성하는 객체를 뺀 덤프 본문)로 베이스라인을 만들고, 새 서버, 완전히 마이그레이션된 원장, 중간에 멈춘 원장에서 이를 검증합니다.
+
+runner는 파일과 체크섬을 바꾸지 않고 적용 시점에 구문도 조정합니다. 서버가 금지하는 경우 실험적 NLP 플래그를 제거하고, `Quantized` 코덱을 쓸 수 있으면 이 코덱으로 벡터 컬럼을 만들며, `allow_suspicious_codecs`를 쓸 수 없는 경우에는 그 뒤에 연결된 범용 코덱을 제거합니다(`server/core/schema/vector_codec_ddl.py`). 또한 마이그레이션을 실행하는 사용자 소유로 모든 뷰를 만들고(`DEFINER = CURRENT_USER`: 덤프에는 자체 사용자가 지정되어 있는데 다른 서버에는 그 사용자가 없을 수 있습니다), 파일이 발행하는 모든 뮤테이션이 끝나기를 기다린 뒤 기록합니다(`LOOM_MIGRATE_MUTATION_WAIT_S`).
+
+**사전 검사.** 파일만으로는 알 수 없는 데이터가 있을 때 실행되면 안 되는 파일은 `server/core/schema/prechecks.py`에 검사를 등록합니다. 키는 번호를 뺀 파일 이름이므로, 번호가 바뀐 파일도 검사를 유지합니다. runner는 드라이 런을 포함해 파일보다 먼저 검사를 실행합니다. 검사가 거부하면 해당 메시지와 함께 실행이 중단되고 그 파일은 아무것도 실행되지 않습니다. `097_mirror_names_reserved.sql`이 검사를 하나 사용합니다. 예약된 미러 형식의 네임스페이스가 등록되어 있거나 활성 행을 가지고 있으면 이를 거부합니다.
+
+
+
+## 정렬 키 또는 파티션 키 변경
+
+ClickHouse는 둘 중 어느 것도 제자리에서 변경하지 않으므로, 마이그레이션은 목표 상태를 선언하고 테이블은 변경(alter)되지 않고 다시 빌드됩니다.
+
+```sql
+-- loom: rebuild-if-empty code_test_facets
+CREATE TABLE loom.code_test_facets ( ...every column, unchanged... ) ... ORDER BY (...);
+```
+
+이 문장이 목표 DDL의 유일한 사본입니다. 러너(`server/core/schema/table_rebuild.py`)는 라이브 테이블의 `sorting_key`와 `partition_key`를 이 문장과 비교합니다. 일치하면 파일을 기록하고, 테이블이 비어 있으면(새로 설치한 경우) 그 자리에서 목표 DDL로 만든 쌍둥이 테이블과 교환하며, 행이 있는 테이블이면 도구 이름을 알려 주는 메시지와 함께 부팅이 실패합니다. 부팅은 행을 복사하지 않습니다. 데이터가 있는 배포에서는 운영자가 먼저 도구를 한 번에 테이블 하나씩 실행합니다.
+
+```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
+```
+
+변경을 수행하는 모든 동작(`--yes` 단독, `--rollback`, `--drop-pre-rebuild`)은 연결된 ClickHouse와 실행 계획을 출력하며, `--yes` 없이는 아무것도 변경하지 않습니다. 이 도구는 모든 행(FINAL 아님)을 제한된 배치로 `loom._rebuild`에 복사하고, 그동안 기록된 파트를 복사한 뒤, FINAL 기준의 행 수와 샘플 키들의 최신 버전을 확인하고, `EXCHANGE TABLES`로 교체합니다. 이전 테이블은 `--drop-pre-rebuild`를 실행하기 전까지 `--rollback`을 위해 `loom._pre_rebuild`로 보관됩니다. 복사하는 동안 `ALTER`가 라이브 테이블을 변경했다면 교체를 거부하고 쌍둥이 테이블을 그대로 둡니다. ClickHouse가 뮤테이션으로 실행하는 변경(컬럼 삭제, 이름 변경 또는 타입 변경, 인덱스 삭제, TTL)은 종료 코드 6, 메타데이터 시간만 바꾸는 변경(인덱스, 설정, 컬럼의 기본값 또는 코덱)은 종료 코드 3입니다. 컬럼을 추가하면 복사가 실패하거나(종료 코드 1, 교체 없음), 마지막 검증 단계 이후 종료 코드 3으로 끝납니다. 재빌드는 `ALTER`를 이어받지 않습니다. 목표 문장에 다시 반영한 뒤 `--restart`로 다시 실행하십시오. 또한 어떤 마이그레이션도 선언하지 않은 테이블은 거부합니다.
+`loom migrate --dry-run --strict`는 선언된 테이블이 여전히 이전 레이아웃으로 행을 가지고 있으면 실패하므로, 배포 사전 점검에서 건너뛴 단계를 잡아냅니다.
+
+목표는 테이블의 컬럼을 그대로 유지하며(따라서 교체는 추가적 변경입니다), 정렬 키는 이전 키의 컬럼을 순서만 바꿔 유지합니다. 이 키는 `ReplacingMergeTree`가 병합하는 기준이기도 합니다. 다른 컬럼이 포함된 키는 다른 행을 병합하게 되며, 그 이유와 함께 `tests/unit/test_migrations_additive.py`에 나열됩니다. 릴리스 노트에 재빌드를 운영자 단계로 명시하십시오([릴리스 프로세스](https://github.com/ClickHouse/loom/blob/main/docs/development/release-process.md#release-notes)).
+
+
+
+## Postgres 마이그레이션
+
+`schemas/pg_migrations/NNN_*.sql`도 같은 규칙을 따릅니다. 번호를 매기고, 추가만 하며, 병합된 뒤에는 수정하지 않습니다. 테이블에 대한 모든 `CREATE`, `ALTER`, `DROP`은 `loom.
`을 명시합니다. 단, 이름 변경의 새 이름은 예외이며, 여기서는 Postgres가 스키마를 받지 않습니다(`tests/unit/test_storage_layout_rows.py`). 부팅 시에는 Postgres advisory lock을 잡고 마이그레이션을 적용하며, 각 파일은 해당 ledger 행과 함께 하나의 트랜잭션에서 실행됩니다. 마이그레이션은 테이블 락을 최대 5초까지만 기다립니다(`lock_timeout`, 이후 재시도). 따라서 `ALTER`가 긴 트랜잭션 뒤에서 그 테이블의 모든 쿼리를 대기시키는 일은 없습니다. 빌드는 이후 빌드의 파일이 들어 있는 ledger도 그대로 사용하며, 이때 해당 파일 이름을 담은 경고를 남깁니다. 반면 빌드가 가지고 있지 않은 ledger 파일이 자신의 마지막 파일 번호 이하이거나, 체크섬이 바뀐 파일이 있으면 부팅을 거부합니다.
+
+모든 파일이 하나의 트랜잭션에서 실행되므로, 마이그레이션은 큰 테이블에 인덱스를 만들지 않습니다. 빌드가 끝날 때까지 해당 테이블의 쓰기가 막혀 모든 커밋이 503으로 응답하기 때문입니다. 이런 인덱스는 트랜잭션 밖에서 `CREATE INDEX CONCURRENTLY`로 만들어야 하는데, advisory lock을 기다리는 부팅과는 교착 상태에 빠집니다(대기 중인 세션이 스냅샷을 쥐고 있어 빌드가 그 세션이 끝나기를 기다립니다). 따라서 이런 파일을 추가하는 변경은 `pg_try_advisory_lock`을 재시도하는 방식으로 락도 함께 잡습니다. 테이블에 처음 쓰기를 하는 릴리스가 그 파일을 포함하는 경우에는, 파일이 실행되는 어느 환경에서든 테이블이 작으므로 파일의 트랜잭션 안에서 인덱스를 만들어도 됩니다(`010_revision_delivered_at.sql`).
+
+
+
+## 스키마 덤프와 검사
+
+`schemas/schema.sql`은 모든 마이그레이션을 적용한 결과를 덤프한 파일입니다. 현재 스키마의 형태를 이해하려면 이 파일을 읽고, 직접 수정하지 마세요. 마이그레이션을 변경한 뒤에는 릴리스 CI가 테스트하는 새 ClickHouse(`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
+```
+
+덤프에 실패하면 파일은 이전 상태 그대로 남습니다. ClickHouse 버전이 다르거나, `Quantized` 코덱 또는 그 `LZ4` 체인을 켤 수 없는 서버이거나, 재구축용 트윈 테이블이 있는 데이터베이스에서는 덤프 결과가 달라집니다. 이 때문에 고정된 컨테이너를 사용해야 합니다. 내부 테이블(`_migrations`, 이름이 `_` 또는 `.`로 시작하는 테이블)은 제외됩니다. CI의 `schema-check` 작업은 새 서버에서 모든 마이그레이션을 재실행하고, 엄격한 dry run을 수행한 다음 `make schema-check`를 실행합니다.
+
+CI는 `latest`를 따르므로, DDL을 다르게 출력하는 새 ClickHouse 릴리스가 나오면 Loom 변경이 없어도 `schema-check`가 실패(red)합니다. 작업이 출력하는 diff를 확인하세요. 서식 차이일 뿐이라면 위의 네 명령을 실행하고(새 릴리스를 pull합니다) `schemas/schema.sql`만 따로 커밋합니다. 의미가 바뀐 경우(타입, 기본값, 엔진 설정)는 덤프로 덮어쓰기 전에 먼저 원인을 조사해야 하는 ClickHouse 동작 변경입니다. `LOOM_CLICKHOUSE_IMAGE=clickhouse/clickhouse-server:A.B.C.D`를 지정하면 깨끗하게 덤프되었던 마지막 릴리스에서 위 명령을 실행해 비교할 수 있습니다.
+
+
+
+## 체크리스트
+
+1. 사용 가능한 다음 번호를 사용하고, 파일은 추가 방식(additive)으로 작성합니다.
+2. 변경이 행 빌더, `loom.memory_versions`, 삭제 집계(erasure census), 분석기 케이스에 영향을 준다면 해당 항목을 업데이트합니다.
+3. 로컬 ClickHouse에 대해 `make migrate`를 실행한 다음 `make schema-dump`를 실행하고, `schemas/schema.sql`을 마이그레이션과 함께 커밋합니다.
+4. `make test-unit`(추가 방식, 번호 지정, 스키마 분류 테스트)과, 새로운 형태를 읽는 경로에 대한 통합 테스트 모음을 실행합니다.
+5. 운영자가 수행해야 하는 단계(재빌드, 백필)가 있다면 릴리스 노트에 기록합니다.
+
+
+
+## 관련 문서
+
+- [업그레이드](https://github.com/ClickHouse/loom/blob/main/docs/operations/upgrades.md): 배포 환경에서 러너가 파일을 적용하는 방법
+- [ClickHouse](../architecture/clickhouse.md)
+- [스키마 레퍼런스](https://github.com/ClickHouse/loom/blob/main/docs/reference/schema.md)
diff --git a/i18n/.pending/ko/docs/features/code-index/history-and-prs.md b/i18n/.pending/ko/docs/features/code-index/history-and-prs.md
new file mode 100644
index 0000000000..5037b19294
--- /dev/null
+++ b/i18n/.pending/ko/docs/features/code-index/history-and-prs.md
@@ -0,0 +1,240 @@
+
+> 이 페이지는 [영어 원문](https://github.com/ClickHouse/loom/blob/main/docs/features/code-index/history-and-prs.md)을 기계 번역한 것이며, 영어 원문이 기준입니다.
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/features/code-index/history-and-prs.md), which is authoritative.
+
+
+
+# 히스토리, PR, 릴리스
+
+이 op들을 사용하려면 병합된 PR 히스토리가 필요합니다. `code_pr_history` 워커는 기본적으로 꺼져 있습니다
+(`LOOM_CODE_PR_HISTORY_ENABLED`).
+
+PR 플레인은 "코드가 어떻게 지금의 모습이 되었는가"에 답합니다. 인덱스와 같은 코드 네임스페이스에 있으므로, 히스토리 응답은 병합된 PR의 파일을 현재의 심볼, 호출자, 테스트와 한 번의 읽기로 조인하며, 질문 시점에 GitHub를 호출하지 않습니다. 팀의 이슈 및 인시던트 기록은 연결된 [트래커](https://github.com/ClickHouse/loom/blob/main/docs/features/tracker/overview.md)를 통해 함께 조인됩니다.
+
+
+
+## PR 플레인
+
+| 테이블 | 내용 | 채우는 주체 |
+| ------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| `loom.code_pr_history` | 네임스페이스 브랜치에 병합된 PR당 한 행: 번호, 제목, 작성자, 레이블, 파일, 연결된 이슈, 병합 커밋 | `code_pr_history` 워커; 처음 몇 달치는 `loom code backfill-prs` |
+| `loom.code_pr_reviews` | 병합된 PR의 인라인 리뷰 댓글 | 같은 워커 (`LOOM_CODE_PR_REVIEWS_ENABLED`, 기본값 켜짐; 토큰 필요) |
+| `loom.code_gh_items` | 모든 상태의 이슈와 PR, 열린 PR은 head가 건드리는 파일 포함 | 같은 워커 (`LOOM_CODE_GH_ITEMS_ENABLED`, 기본값 켜짐; 익명일 때는 건너뜀) |
+| `loom.code_backport_gaps` | 매일 밤 생성되는 전체 세트 백포트 보고서 | `code_backport_gaps` 워커 |
+
+워커는 `LOOM_CODE_GITHUB_TOKEN` 또는 항목의 `github_token`을 사용하며, 둘 다 없으면 GitHub의
+익명 요청 제한을 따릅니다. 릴리스 브랜치 네임스페이스는 해당 브랜치에 병합된 PR을 담으므로,
+"2.4에서 무엇이 바뀌었는가"는 2.4 네임스페이스를 읽어 확인합니다. `loom code backfill-prs`는
+새 저장소에 대해 `LOOM_CODE_PR_BACKFILL_MONTHS`(12)개월치 기록을 불러옵니다
+([코드 인덱스 운영](https://github.com/ClickHouse/loom/blob/main/docs/operations/code-index-operations.md#first-index)).
+
+
+
+## 어떤 op가 어떤 질문에 답하는가
+
+| 질문 | Op |
+| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| 이 PR 또는 앞으로 할 변경에 대해 브리핑해 줘 | `code.context_pack` (`pr_number` 또는 `task`; `sections`는 실제로 사용할 블록만 남김) |
+| 이 심볼이나 경로를 수정한 머지된 PR은 무엇이고, 리뷰어는 뭐라고 했는가? | `code.history`, `code.symbol_history` |
+| 릴리스 A와 B 사이에 이 라인들을 마지막으로 수정한 머지된 PR은 무엇인가? | `code.blame_range` |
+| 머지된 이 PR에서 리뷰어는 무엇을 확인했는가? 보통 무엇을 확인하는가? | `code.review_brief`, `code.conventions` |
+| PR을 열기 전에: 비슷한 PR이 이미 있는가? | `code.pr_check` |
+| 이 버그를 유입했을 수 있는 머지된 PR은 무엇인가? | `code.bisect_candidates` |
+| 수정으로 제거된 버그를 아직 가지고 있는 릴리스 브랜치는 무엇인가? | `code.backport_gap` (수정 하나), `code.backport_gaps` (레이블이 붙은 모든 수정) |
+| 어떤 CI 빌드가 이 커밋을 처음 포함했는가? | `code.first_build` |
+
+인자는 [operations 레퍼런스](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md#code)에 있습니다.
+
+
+
+### 심볼, 경로, 라인 범위의 이력
+
+`code.history`는 심볼(`name` 또는 `symbol_id`), `path` 또는 지정한 PR `numbers`를 가장 최근에 수정한 머지된 PR을 나열합니다. 번호, 제목, 작성자, 레이블, 그리고 해당 파일에 달린 사람의 리뷰 코멘트를 최대 `reviews_per_pr`개(기본값 3, `0` = 없음) 보여 줍니다.
+`code.symbol_history`는 이를 한 함수의 회귀 이력으로 좁힙니다. 해당 함수의 범위를 수정한 PR, 연결된 이슈와 리버트, 그리고 그 범위 안의 리뷰 코멘트를 보여 줍니다.
+
+`code.blame_range`는 `path`, 라인 범위(최대 400라인), 그리고 릴리스 버전(`from_version`, `to_version`) 또는 커밋 sha로 지정한 구간을 받습니다. 이 op는 구간 내 PR 원장의 파일 목록(하한)과 미러에서 실행한 `git blame -w -M -L`을 결합하며, blame된 각 커밋은 해당 PR에 매핑됩니다. 릴리스 브랜치 네임스페이스에서는 호출자가 trunk를 읽을 수 있을 때만 trunk 네임스페이스의 원장도 읽습니다. 읽을 수 없으면 trunk의 행은 제외되고 `legs.ledger.skipped`에 그 사실이 표시됩니다. 릴리스 버전은 호출자가 해당 브랜치 네임스페이스를 읽을 수 있으면 그 네임스페이스의 인덱싱된 head로 해석되고, 그렇지 않으면 미러의 브랜치 또는 `-new` 태그를 통해 해석됩니다.
+
+- `stage: "introduced"`(기본값)는 백포트, 리버트, 공백만 또는 이름만 바꾼 수정의 순위를 낮추고, 해당 함수를 이름으로 언급한 PR, 그 안에 리뷰 코멘트가 달린 PR, 또는 연결된 이슈가 `mentions`의 단어를 포함하는 PR의 순위를 높입니다.
+- `stage: "last_touched"`는 blame 순서를 유지합니다.
+
+이 답은 "마지막으로 수정한" PR에 대해서는 정확하지만 "버그를 유입한" PR에 대해서는 그렇지 않으며, `note`에도 그렇게 명시되어 있습니다.
+
+
+
+### 리뷰 브리프와 컨벤션
+
+`code.review_brief`는 PR이 머지될 때 ingest가 만든 브리프를 읽습니다. 변경된 모든 파일의 분류, 수정된 함수와 그 호출자 및 fan-in, 이를 커버하는 테스트, 그리고 리뷰어가 말한 내용이 들어 있습니다.
+
+`standard`와 `full` 티어에서는 브리프에 `rationale` 섹션도 포함됩니다. 이 섹션은 저장소의 trunk 코드 네임스페이스에서 `files` 또는 코드 링크가 PR의 파일과 닿는 설계 결정과 제약(`decision` 타입의 행, 또는 `decision`이나 `constraint`로 태그된 행이며, 수정 전 블록에 표시되는 기준으로 active 또는 conflicted인 것)을 담습니다. 이 섹션은 호출할 때마다 읽으며, 호출자가 읽을 수 있을 때만 trunk 네임스페이스에서 읽고, 브리프와 함께 저장되지 않습니다. 따라서 머지 후에 기록되거나 변경된 결정도 다음 읽기에 나타납니다. 브리프가 저장한 변경 파일 중 소스 파일을 먼저 두고 처음 `LOOM_CODE_REVIEW_BRIEF_RATIONALE_PATHS`(10)개를 읽으며, 확인할 내용이 있는 행을 우선하여 최대 `LOOM_CODE_REVIEW_BRIEF_RATIONALE_ROWS`(8)개의 행만 유지합니다. 행은 통째로 제공되며 `check` 행이 먼저, 그다음 제약 순이고, 최대 `LOOM_CODE_REVIEW_BRIEF_RATIONALE_TOKENS`(250) 토큰까지이며 첫 행은 항상 포함됩니다. 다만 티어의 예산이 다른 섹션과 마찬가지로 이 섹션을 줄일 수는 있습니다. 각 행에는 수정 전 블록의 해당 행 라인이 값을 라인 길이에서 자른 채(출처, `(pinned)`, 코드 변경 노트는 유지) 포함되며, `pinned`, `code_state`, `verdict`도 함께 제공됩니다. 읽은 변경 파일마다 `memory.for_file` 읽기가 한 번 수행되며, 이는 ClickHouse 읽기 네 번(files 매칭, 코드 링크, 그 링크의 메모리, 연결된 행)입니다. 링크가 많은 파일은 마지막 읽기를 나눕니다. 각 읽기는 최대 50개 행을 유지하며 값은 최대 `LOOM_MEMORY_FOR_FILE_WHOLE_TOKENS` × 48바이트입니다.
+
+검사는 두 종류의 이름을 찾습니다. 하나는 행의 `Rejected:` 절(`Realized:` 절이 나오기 전까지)에 있는 코드 형태의 이름(백틱으로 감싼 이름, `A::b`처럼 한정된 이름, `f()`처럼 호출 형태)이고, 다른 하나는 제약의 값 어디에나 있는 snake_case 이름(백틱 여부와 관계없이, 단독 또는 한정된 형태, 예: `Setting::distinct_spill_ratio`)입니다. 이 검사는 diff가 추가한 라인에 대한 전체 단어 일치이며, 게시된 diff는 최대 200,000자, 미러의 diff는 최대 200,000바이트까지 읽습니다. 따라서 `check`는 "이 행을 diff와 대조해 읽어 보라"는 뜻이지 위반이 발견되었다는 뜻이 아닙니다.
+
+| 행 verdict | 의미 |
+| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `check` | diff가 행의 확인 대상 이름(`names`) 중 하나를 추가함 |
+| `clear` | 행에 확인 대상 이름이 있고 diff가 그중 어느 것도 추가하지 않음 |
+| `unknown` | 이름을 찾지 못했지만, 여기서 diff를 읽을 수 없었거나(git 실패, 일부만 읽힌 경우 포함), diff가 잘렸거나, 라인 수가 맞지 않는 hunk가 있거나, 행의 값이 잘림(`diff_unread`, `diff_cut`, `diff_malformed`, `value_cut`) |
+| `""` | 행에 확인할 이름이 없음 |
+
+섹션의 verdict는 어느 행이든 그렇다고 하면 `check`이고, 그다음이 `unknown`, 그다음이 `clear`이며, 확인할 내용이 있는 행이 없으면 `none`입니다. `clear`나 `none`은 변경된 모든 경로와 일치하는 모든 행을 확인했을 때만 나타나며, 그렇지 않으면 `unknown`이 되고 원인이 무엇이 남았는지 알려 줍니다. 네임스페이스에 설정된 저장소가 없음(`no_repo`), 브리프에 저장된 변경 경로가 없음(`no_paths`), 호출자가 trunk 네임스페이스를 읽을 수 없음(`trunk_not_readable`), 저장된 변경 경로 목록이 잘렸을 수 있음(`paths_maybe_cut`: 브리프는 처음 50개 변경 파일과 diff hunk의 파일을 최대 200개까지 저장하므로, 50개 이상인 목록은 PR이 실제로 변경한 파일보다 적을 수 있음), 그 목록의 변경 경로 중 읽지 못한 것이 있음(`paths_not_read`), 읽기가 50개 행 한도에 도달한 경로가 있음(`paths_at_row_ceiling`), 코드 링크 읽기에 실패한 경로가 있음(`links_not_read`), 또는 확인할 내용이 있었는데 행 상한 때문에 제외된 행이 있음(`rows_not_read`)입니다.
+
+`code.conventions`는 저장소의 반복되는 메인테이너 검사를 의견이 아니라 한 PR의 diff(`pr_number`, `head_sha`, `files` 또는 `diff`)에 대한 사실로 기술하며, `rules`로 실행할 검사를 좁힐 수 있습니다. 이 op가 읽는 diff는 `LOOM_CODE_CONVENTIONS_DIFF_MAX_BYTES`로 상한이 정해져 있습니다.
+
+
+
+## PR 전 중복 확인: `code.pr_check`
+
+풀 리퀘스트를 열려는 에이전트가 초안을 전달하면 세 가지 판정 중 하나를 받습니다:
+`duplicate_of`(열린 PR이 이미 같은 작업을 하고 있거나 병합된 PR이 이미 했음),
+`related`, `none`.
+
+```python
+from loom import Agent
+
+async with Agent(org="acme", namespace="code-widgets", agent="pr-bot") as bot:
+ check = await bot.call(
+ "code.pr_check",
+ title="Retry the upload when the token expires",
+ paths=["src/upload/client.py"],
+ symbols=["UploadClient.send"],
+ issues=[1432],
+ )
+ if check["verdict"] == "duplicate_of":
+ for item in check["items"]:
+ print(item["pr_number"], item["state"], item["evidence"])
+```
+
+HTTP로 같은 호출은 `POST /v1/code.pr_check`이며, MCP에서는 `loom_code_pr_check` 도구입니다(`coding` 및 `tracker` 툴셋에 포함). 제목, 변경된 경로 또는 이슈 번호 중 하나는 필수입니다.
+
+후보는 GitHub 호출 없이 Loom 자체 원장에서 네 가지 경로를 통해 가져옵니다:
+
+| 경로 | 읽는 대상 |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| 열린 PR | `code_gh_items`의 모든 열린 PR: 제목과 `refs/pull/N/head`가 변경하는 파일(본문 제외) |
+| 병합 없이 닫힘 | 최근 `LOOM_CODE_PR_CHECK_CLOSED_DAYS`(180)일 이내에 병합 없이 닫힌 PR: "누군가 이미 시도했음"; 최대 `related`까지만 인정 |
+| 병합됨, 경로 기준 | 초안의 `paths`를 변경한 병합된 PR |
+| 병합됨, 텍스트 기준 | 텍스트가 초안의 제목 및 심볼과 일치하여 점수를 받는 병합된 PR, 그리고 같은 `issues`를 닫는 병합된 PR |
+
+각 후보는 하나의 고정된 규칙으로 점수를 매깁니다. 후보가 가진 초안의 제목 및 심볼 토큰 비율(희소성으로 가중), 병합된 PR에 대한 작은 본문 항, 양방향 경로 중첩, 초안에 명시된 이슈를 닫는지 여부입니다. 중복 PR은 병합되지 않고 닫히기 때문에 가중치를 맞출 레이블된 데이터셋이 없습니다. 응답에는 `epistemic: "heuristic"`이 표시되며, 제목만으로는 `duplicate_of`에 도달하지 않습니다.
+
+| 설정 | 기본값 | 효과 |
+| ---------------------------------------- | ------ | --------------------------------------------------------------------- |
+| `LOOM_CODE_PR_CHECK_DUPLICATE_THRESHOLD` | 0.55 | 후보가 `duplicate_of`가 되는 점수 |
+| `LOOM_CODE_PR_CHECK_RELATED_THRESHOLD` | 0.2 | 후보가 `related`가 되는 점수 |
+| `LOOM_CODE_PR_CHECK_MERGED_DAYS` | 365 | 이보다 오래된 병합 PR은 중복으로 투표하지 않음 |
+| `LOOM_CODE_PR_CHECK_MASS_FILES` | 200 | 이보다 많은 파일을 변경하는 후보는 대량 변경으로 보며, 그 파일은 투표하지 않음 |
+
+`tracker.duplicate_check`는 이슈 쪽의 짝이 되는 기능입니다. 판정이 `none` 또는 `related`일 때, 초안을 이미 다루고 있을 수 있는 `code.pr_check`의 PR을 `related_prs`로 함께 반환합니다
+([트래커 개요](https://github.com/ClickHouse/loom/blob/main/docs/features/tracker/overview.md#duplicate-check)).
+
+
+
+## Bisect 후보: `code.bisect_candidates`
+
+버그가 보고되었을 때, 엔지니어는 병합된 PR 중 어떤 것부터 조사해야 할까요?
+`code.bisect_candidates`는 후보의 우선순위를 정하며, 자동화된 `git bisect`가 아닙니다.
+저장소를 빌드하지 않고, 테스트를 실행하지 않으며, 보고된 문제를 재현하지 않고, 정상 버전과 결함 버전을 찾아내지 않으며, 후보가 버그를 일으켰다는 것을 증명하지도 않습니다. 후보의 점수는 조사 순위일 뿐 원인일 확률이 아닙니다.
+
+회귀 경계는 호출 전에 기록된 증거에서 가져옵니다.
+
+| 윈도우 입력 | 출처 | Loom이 하는 일 |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `bad_version`, `good_version` | 사용자, CI 작업, 지원 워크플로 또는 테스트 에이전트가 결함 릴리스에서 버그를 관찰했고 정상 릴리스에서는 문제가 없음을 관찰한 경우입니다. | 두 관찰 사이의 릴리스를 스캔합니다. Loom은 어느 릴리스도 다시 테스트하지 않습니다. |
+| `issue_number` | 연결된 트래커 이슈에 `reproduces_on` 및 `clean_on` 분류(triage) 관찰이 이미 있으며, 트래커 워크플로가 이를 채운 경우입니다. | 명시적인 버전이 제공되지 않았을 때 이 관찰 값을 읽습니다. 이슈나 분류 값이 존재한다고 해서 보고가 유효하다는 증거는 아닙니다. |
+| `after`, `before` | 호출자가 마지막으로 정상이었던 날짜와 처음 발견된 날짜처럼 대략적인 병합 시각 구간만 알고 있는 경우입니다. | PR 이력 스캔을 해당 구간으로 좁힙니다. 날짜는 경계일 뿐 재현 결과가 아닙니다. |
+| `bad_sha` | 호출자가 처음 관찰된 실패 시점이거나 그 이전인 커밋을 알고 있는 경우입니다. | 저장소 미러에서 커밋 시각을 확인하고, `before`가 없으면 이를 `before`로 사용합니다. 해당 커밋을 실행하지는 않습니다. |
+
+그다음 호출자는 가지고 있는 보고 증거를 전달합니다. 크래시 프레임(`symbols`), 소스 `paths`, `patterns`, 자유 형식 `text`, `issue_number`, 그리고 알고 있다면 `fix_pr`입니다.
+정확한 릴리스 범위를 알 수 없으면, 저장소 이력 폴백은 이 스캔을 위해 보관된 최근 이력(`LOOM_CODE_BISECT_HISTORY_DAYS`, 기본값 90)을 사용하며, 이는 더 넓고 덜 정밀한 조사 윈도우입니다.
+
+1. 프레임은 코드 인덱스를 통해 파일로 변환됩니다.
+2. 후보 스캔은 첫 릴리스가 윈도우 안에 있고 해당 파일을 변경한, 병합된 비파생(non-derivative) PR을 읽고, diff에 이름이 나오는 프레임을 기준으로 순위를 매깁니다. 연결된 트래커가 있으면 트래커의 PR diff를 스캔하며, `issue_number`에 이전에 기록된 분류 컬럼(`reproduces_on`, `clean_on`)이 윈도우를 제공할 수 있습니다. 트래커가 없거나 트래커에 변경된 파일이 없으면 저장소 자체의 PR 이력(`LOOM_CODE_BISECT_HISTORY_DAYS`, 기본값 90)을 읽으며, 응답에는 `candidates_from: "code_history"`가 표시됩니다.
+3. 프레임이 없고(잘못된 결과를 보고한 경우) `issue_number`가 있으면, 스캔 범위는 윈도우 diff에서 이슈의 가장 희소한 식별자, 구성 요소의 디렉터리, 수정 PR의 파일로 제한됩니다. `wideners`가 어느 것을 쓸지 선택하고, `widened_by`가 어느 것이 적용되었는지 알려 줍니다.
+4. 보고 시점 융합(report-time fusion)은 diff 스캔을 벡터, 어휘, 경로, 하위 트리, 최신성 순위와 융합합니다. 보고에서 버그를 도입한 것으로 지목한 PR이 맨 앞에 옵니다. 융합 결과의 최상위가 약하면(2위와의 차이가 0.1 미만이고 보고에서 지목한 용의 PR이 아닌 경우) 더 넓은 윈도우(12개 릴리스 또는 `LOOM_CODE_BISECT_WIDE_DAYS`)가 추가되고, LLM 호출 한 번이 상위 20개를 다시 정렬합니다(`LOOM_CODE_BISECT_LLM_RERANK_MODEL`, 타임아웃이 발생하면 융합 순서 유지). `rerank: true`로 이를 직접 요청할 수도 있습니다.
+5. 수정 PR도 이슈도 지정하지 않은 보고는, 중복 확인이 일치시킨 이슈의 수정 PR을 `LOOM_CODE_BISECT_DUPCHECK_TIMEOUT_S` 안에서 가져와 사용합니다.
+
+각 후보에는 표시(backport, revert, reverted, re-land, 공백 전용 또는 이름 변경 전용, diff의 hunk 헤더에서 얻은 `touches_symbol`)가 붙습니다. `marks: false`는 표시 없이 순위 목록만 반환합니다. 어떤 경로를 소스 코드로 볼지는 트래커의 `bisect.code_prefixes`로 정합니다([레코드 규약](https://github.com/ClickHouse/loom/blob/main/docs/features/tracker/record-contract.md#source-entry-options)).
+재정렬에는 실제 LLM 제공자가 필요하며, 나머지 단계는 PR 이력이 로드된 뒤 기본 스택에서 실행됩니다. bisect 설정은 [구성 레퍼런스](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#code)에 나열되어 있습니다.
+
+아래 예시는 정상 릴리스와 결함 릴리스 사이에 병합되고 크래시가 난 함수의 파일을 변경한 PR의 순위를 매깁니다. `bad_version`은 버그가 처음 관찰된 릴리스이고 `good_version`은 문제가 없던 가장 최신 릴리스이며, Loom은 둘 다 테스트하지 않습니다.
+
+버전 윈도우를 사용하려면 `minor_version`이 포함된 PR 레코드를 가진 저장소에 연결된 트래커 네임스페이스가 필요합니다([레코드 규약](https://github.com/ClickHouse/loom/blob/main/docs/features/tracker/record-contract.md)). 병합된 PR 이력만 있는 경우(`LOOM_CODE_PR_HISTORY_ENABLED` 또는 `loom code backfill-prs`, [첫 인덱스](https://github.com/ClickHouse/loom/blob/main/docs/operations/code-index-operations.md#first-index) 참조) 버전은 스캔 범위를 제한하지 않으며, 대신 이 op는 최근 `LOOM_CODE_BISECT_HISTORY_DAYS`(기본값 90)일을 읽습니다.
+
+```python
+from loom import Agent
+
+async with Agent(org="acme", namespace="code-widgets", agent="triage-bot") as bot:
+ result = await bot.call(
+ "code.bisect_candidates",
+ bad_version="26.3",
+ good_version="26.2",
+ symbols=["UploadClient.send"],
+ )
+ for candidate in result["candidates"]:
+ print(candidate["pr_number"], candidate["score"])
+```
+
+후보는 순위대로 반환됩니다. `score`는 어떤 PR부터 조사할지를 알려 줄 뿐, 해당 PR이 버그를 일으켰음을 보여 주지는 않습니다. 버그를 재현하고 후보를 테스트하는 일은 여전히 엔지니어나 CI 작업이 해야 합니다.
+
+최종 검증은 이 작업 밖에서 이루어집니다. 엔지니어, CI 워크플로 또는 테스트 에이전트가 문제를 재현하고 순위가 매겨진 후보를 테스트해야 합니다.
+
+
+
+## 백포트 누락
+
+`code.backport_gap`은 병합된 수정(`pr_number`) 또는 그 수정이 닫는 이슈(`issue_number`, 트래커의 `fixes` 에지 또는 복구된 링크로 확인)를 지정하고, 같은 저장소의 릴리스 브랜치 네임스페이스별로 최신 순으로 결과를 반환합니다. `branches`에 네임스페이스나 `26.4` 같은 버전을 지정하면 해당 브랜치만 대상으로 합니다. 세 가지 근거를 종합합니다. 첫째는 백포트 기록으로, 트래커의 `is_backport_pr`, `upstream_pr_number`, `base_branch`와 브랜치 원장에 병합된 백포트를 함께 봅니다. 둘째는 수정이 처음 포함된 릴리스로, 그 시점 이후에 분기된 브랜치에는 수정이 포함됩니다. 셋째는 수정의 hunk가 건드리는 함수가 각 브랜치에 존재하는지 여부입니다.
+
+| 판정 | 의미 |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `gap` | 백포트가 없고, 브랜치가 수정보다 앞서 분기되었으며, 수정이 건드리는 함수(또는 파일)가 존재함. `cherry_pick`은 PR과 병합 sha를 알려 줌 |
+| `pending` | 백포트 PR이 있으며 아직 열려 있음 |
+| `covered` | 백포트가 병합되었거나, 브랜치가 수정이 처음 포함된 릴리스 이후에 분기되었거나, 이슈의 `fix_versions`에 해당 브랜치가 명시됨 |
+| `not_affected` | 수정이 건드리는 모든 함수(또는 파일)가 브랜치에 없음 |
+| `unknown` | 코드는 존재하지만 기록을 확인할 수 없었거나, 존재 여부 확인이 시간 초과되었거나, 브랜치에 비교할 버전이 없음 |
+
+심볼 수준의 `gap`은 하한값입니다. 코드가 브랜치에 존재한다고 해서 버그도 존재한다는 것이 증명되지는 않습니다.
+
+- `exact: true`는 패치를 hunk 단위로 검사합니다. 제거된 줄이 아직 있고 추가된 줄이 없으면 `gap`이 확정되고, 추가된 줄이 있고 제거된 줄이 없으며 기록된 백포트가 없으면 `not_affected`가 확정됩니다.
+- `history: true`(`exact`를 함의)는 줄 비교로 판정되지 않은 행에 대해 미러에서 브랜치의 트리와 히스토리도 읽습니다.
+- `presence.patch`는 모드와 겹침 정보를 근거로 보여 줍니다.
+
+`code.backport_gaps`는 전체 집합 보고서입니다. 최근 90일 동안 메인테이너가 백포트 대상으로 라벨링한 모든 수정을 릴리스 브랜치별로, 누락이 있는 항목을 먼저 보여 줍니다. `code_backport_gaps` 워커가 수정마다 `code.backport_gap(exact, history)`를 실행해 매일 밤 결과를 `loom.code_backport_gaps`에 기록하며(`LOOM_CODE_BACKPORT_GAPS_ENABLED`, 기본값 켜짐, `LOOM_CODE_PR_HISTORY_ENABLED`가 켜져 있을 때만 유효), 이 op는 해당 테이블을 읽습니다. `wanted_only: false`를 지정하면 라벨이 없는 수정도 포함합니다. 모든 브랜치 네임스페이스는 읽기 전에 권한을 확인하며, 실패 시 접근을 거부합니다.
+
+
+
+## 첫 빌드
+
+`code.first_build`는 커밋 `sha` 또는 병합된 PR의 `pr_number`를 받아 어떤 CI 빌드가 해당 커밋을 처음 포함했는지 알려 줍니다. 연결된 트래커의 `version_history` 테이블이 필요합니다. 해당 sha를 명시한 실행이 있으면 정확한 결과를 반환하고, 그렇지 않으면 병합 이후 실행들의 base를 미러에서 확인하여(`git merge-base --is-ancestor`, 최대 10개) 가장 이른 후손을 찾으며, 이 경우 결과는 하한값입니다.
+
+
+
+## PR 및 트래커 플레인
+
+메인테이너는 `code.repo.set_source`로 트래커를 리포지토리에 연결하며, 기본 트래커를 먼저 지정합니다([트래커 개요](https://github.com/ClickHouse/loom/blob/main/docs/features/tracker/overview.md)). 연결하면 다음과 같이 동작합니다.
+
+- `code.bisect_candidates`는 트래커의 PR diff를 스캔하고 의심되는 변경을 알려진 수정 사항과 대조해 확인합니다.
+- `code.backport_gap`은 백포트 기록을 읽고, `code.first_build`는 트래커의 CI 실행을 읽습니다.
+- `code.history`와 `code.search`, `code.ask`의 히스토리 부분은 바인딩이 해석되고 호출자에게 읽기 권한이 있으면 PR과 함께 트래커 기록도 담습니다.
+- `code.context_pack`은 트래커 항목을 포함할 수 있습니다(`sections=["qa"]`).
+
+트래커가 없으면 op는 가능한 범위에서 PR 플레인으로 응답하고, 트래커에만 있는 부분은 누락된 것으로 표시합니다.
+
+
+
+## 한계와 실패 모드
+
+- **기록이 없으면 답도 없습니다.** `LOOM_CODE_PR_HISTORY_ENABLED`가 꺼져 있고 `backfill-prs`도 실행하지 않았다면 기록 테이블이 비어 있어, op는 순위를 매길 대상이 없는 상태로 응답합니다.
+- **익명 GitHub 접근**은 공개 속도 제한 범위 내에서 공개 저장소만 다룹니다. 리뷰 댓글과 이슈 미러에는 토큰이 필요합니다.
+- **열린 PR은 인덱싱된 코드가 아닙니다.** `code.pr_check`는 열린 PR의 제목과 파일만 볼 수 있으며, 본문이나 심볼은 보지 못합니다.
+- **휴리스틱 판정.** `code.pr_check`는 의도적으로 보정되지 않았습니다. `code.blame_range`는 "마지막으로 수정된 시점"에 대해서만 정확합니다. `code.bisect_candidates`는 용의 대상의 순위를 매길 뿐, 원인 제공자를 사실로 단정하지 않습니다.
+- **트래커 장애는 성능 저하로 처리되며 실패로 이어지지 않습니다.** 트래커 읽기가 시간 초과되거나 차단기가 작동하면 `tracker_unavailable`이 설정되며, PR 플레인 쪽 처리는 계속 응답합니다.
+
+
+
+## 관련 문서
+
+- [트래커 개요](https://github.com/ClickHouse/loom/blob/main/docs/features/tracker/overview.md) 및 [레코드 계약](https://github.com/ClickHouse/loom/blob/main/docs/features/tracker/record-contract.md)
+- [저장소 추가하기](https://github.com/ClickHouse/loom/blob/main/docs/features/code-index/repositories.md)
+- [질문별 코드 인덱스 작업](https://github.com/ClickHouse/loom/blob/main/docs/features/code-index/operations.md)
+- [코드 인덱스 아키텍처](../../architecture/code-index-architecture.md)
+- [작업 레퍼런스](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md#code)
diff --git a/i18n/.pending/ko/docs/features/conversations-and-sessions.md b/i18n/.pending/ko/docs/features/conversations-and-sessions.md
new file mode 100644
index 0000000000..e74c1aaae7
--- /dev/null
+++ b/i18n/.pending/ko/docs/features/conversations-and-sessions.md
@@ -0,0 +1,206 @@
+
+> 이 페이지는 [영어 원문](https://github.com/ClickHouse/loom/blob/main/docs/features/conversations-and-sessions.md)을 기계 번역한 것이며, 영어 원문이 기준입니다.
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/features/conversations-and-sessions.md), which is authoritative.
+
+
+
+# 대화와 세션
+
+Loom은 세 종류의 세션 상태를 각각 별도의 플레인에 보관합니다:
+
+| 플레인 | 보관 내용 | 임베딩 및 검색 | 기록 주체 |
+| ------------------ | -------------------------------------------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| 대화 플레인 | 스레드의 원문 턴 (`loom.conversations`) | 사용자와 어시스턴트의 턴 및 압축 요약, `conversation.search`로 검색 | `conversation.append`, 플러그인의 캡처 훅, `loom ingest-transcript` |
+| 세션 브리프 | 하나의 작업 흐름에 대한 압축된, 재개 가능한 상태 (`loom.session_briefs`) | 아니요 | `session.brief_save`, 압축 및 세션 종료 시점의 코딩 플러그인 |
+| 메모리 | 발화 내용에서 추출한 지속적인 사실 | 예, `memory.search`로 검색 | `memory.set`, `memory.set_from_messages` |
+
+턴을 저장해도 메모리가 생성되지는 않습니다. 대화를 사실로 변환하려면 [`memory.set_from_messages`](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/extraction.md)로 전송하세요. 소유자는 추출된 메모리를 잃지 않고도 대화 기록을 끌 수 있으며, 브리프는 회상 시 사실과 경쟁하지 않습니다.
+
+
+
+## 대화
+
+
+
+### 기록은 소유자가 선택합니다
+
+`conversation.append`는 네임스페이스에서 대화 로깅이 켜져 있을 때만 턴을 저장합니다. 이 스위치(`loom.namespaces`의 `conversation_logging_enabled`)는 기본적으로 꺼져 있고 실패 시 닫히는(fail-closed) 방식으로 동작합니다. 행이 없는 네임스페이스는 기록되지 않습니다. 소유자는 `conversation.set_logging(enabled=true)`(admin) 또는 대시보드의 대화 페이지에 있는 **Record conversations** 스위치로 이를 켭니다.
+
+로깅이 꺼져 있으면 append는 받아들여지지만 아무것도 보관되지 않습니다. 응답은 `stored: false, reason: "logging_disabled"`를 반환합니다. 클라이언트는 소유자의 선택을 무시할 수 없습니다. 임베딩이 실행되는 동안 턴이 삭제되면 append는 늦게 도착한 벡터를 건너뛰고 `stored: false, reason: "deleted"`로 응답합니다.
+
+
+
+### 턴 쓰기
+
+`conversation.append`는 `thread_id`, `role`(`user`, `assistant`, `system` 또는 `tool`), `content`를 받고, 선택적으로 `msg_id`, `reasoning`(별도 컬럼에 보관되는 모델의 추론), `user_id`, `run_id`, `metadata`, `tokens`를 받습니다. 스레드는 첫 append에서 생성됩니다. `conversation.create`는 `title`, `metadata`, `run_id`를 미리 지정할 때만 사용합니다.
+
+- **`msg_id` 기준 멱등성.** `(thread_id, msg_id)`가 이미 기록된 턴은 다시 쓰지 않습니다(`reason: "duplicate"`). `msg_id`가 없으면 서버가 스레드, 역할, 내용의 해시로 하나를 만들어 내므로, 턴을 다시 기록하는 클라이언트가 대화록을 두 배로 만들지 않습니다.
+- **user 및 assistant 턴은 임베딩됩니다.** 처음 2,048자까지 임베딩되며, 임베딩 행이 이 텍스트를 보관하므로 재임베딩은 벡터를 만든 텍스트에서 시작합니다. 이전 빌드가 기록한 행은 240자를 보관하며, 재임베딩은 그 텍스트로 수행됩니다. `system` 및 `tool` 턴은 압축(compaction)의 요약을 제외하고 색인되지 않은 채 대화록에 남습니다.
+- **임베딩은 fail-open입니다.** 임베딩이 실패해도 턴은 저장되며, 오류는 해당 임베딩 행에 기록됩니다. 재시도는 없습니다. 이 턴은 벡터 검색에서 제외되고 부분 문자열 폴백으로만 찾을 수 있습니다.
+- **high로 판단되는 턴은 임베딩되지 않습니다.** 텍스트에 high 형태(붙여넣은 API 키, `password=` 할당, 카드 번호, SSN, 명시된 PIN)가 있는 턴은 작성된 그대로 저장되지만 임베딩 행이 생기지 않고, 텍스트가 임베더로 전송되지도 않습니다. `conversation.search`는 벡터 검색이든 부분 문자열 폴백이든 이런 턴을 반환하지 않습니다. `conversation.threads`는 마지막 턴이 이런 경우 빈 발췌문으로 나열하며(high로 판단되는 제목도 빈 값이 됩니다), 발췌문에 표시되는 240자와 그 뒤 1,024자를 검사합니다. 제목 생성기는 이런 턴을 모델로 보내지 않습니다. 처음 여덟 개의 user 및 assistant 턴이 모두 high로 판단되거나 생성된 제목이 high로 판단되는 스레드는 제목 없이 남고, 제목 생성기가 다시 요청하지 않도록 메타데이터에 `title_refused`로 표시됩니다. 그런 턴이 그보다 적은 스레드는 표시 없이 일반 턴을 기다립니다. `conversation.update` 또는 `conversation.create`로 새 `metadata`를 주면 표시가 대체되며, 제목 생성기는 한 번 더 요청한 뒤 스레드에 다시 표시합니다. `conversation.get`과 `conversation.list`는 여전히 해당 스레드 안에서 그 턴을 제공합니다([민감도](https://github.com/ClickHouse/loom/blob/main/docs/architecture/security.md#sensitivity)).
+
+
+
+### 개별 메시지 저장
+
+채팅 클라이언트는 네임스페이스의 대화록을 기록하지 않고도 사용자가 메시지 하나를 나중에 검색하도록 저장하게 할 수 있습니다. `conversation.save_message`(writer)가 이 옵트인이고, `conversation.search_saved_messages`(viewer)가 그 검색입니다. 저장된 메시지는 대화 행이며, 사용자의 개인 컬렉션에 있는 문서가 아닙니다([공유](https://github.com/ClickHouse/loom/blob/main/docs/architecture/sharing.md#saved-messages)).
+
+클라이언트는 모든 레플리카가 압축 중에 저장된 상태를 보존할 때만 메시지를 저장해야 합니다. [롤링 업그레이드 규칙](https://github.com/ClickHouse/loom/blob/main/docs/architecture/rolling-upgrades.md#the-rules)을 참고하세요.
+
+이 기능은 `conversation.append` 및 `conversation.search`와 여섯 가지 면에서 다릅니다.
+
+- **Record conversations 스위치가 적용되지 않습니다.** 스위치(또는 `conversation.set_logging`)로 기록을 껐더라도 저장은 보관되며, 저장이 기록을 켜지는 않습니다.
+- **메시지에 플래그를 지정하며, 레이블을 바꾸지 않습니다.** 대화록 행과 그 임베딩 행에는 `is_saved`와 `saved_at`(사용자가 메시지를 저장한 시각)이 들어갑니다. 대화록에 이미 있는 메시지는 제자리에서 플래그가 지정되며, `run_id`와 내용은 기록된 그대로 유지됩니다.
+- **검색은 사용자별입니다.** `conversation.search_saved_messages`는 지정한 하나의 네임스페이스에서 `user_id`가 소유하고 플래그가 지정된 메시지만 반환합니다. `conversation.search`는 기록된 모든 턴의 순위를 매기고 기본적으로 호출자의 모든 네임스페이스에 걸쳐 확장됩니다.
+- **검색은 하이브리드입니다.** 벡터 경로는 메시지의 처음 2,048자를 임베딩하고, BM25 경로는 전체 텍스트를 읽으므로 정확한 용어(티켓 ID, 테이블 이름)나 긴 저장 답변 깊은 곳의 구문도 순위에 오릅니다. `search_mode="hybrid"`(기본값)는 두 경로를 역순위 결합(reciprocal rank)으로 합치고, `semantic`과 `lexical`은 한 경로만 실행하며, `lexical_weight`(0–1)는 BM25 경로의 가중치를 조절합니다. BM25 결과의 발췌문은 일치한 용어를 중심으로 구성됩니다. 검색 대상은 한 사용자의 저장된 메시지이므로 통계는 쿼리마다 계산됩니다.
+- **한 사용자에게 고정된 토큰이 여기서 동작합니다.** 하나의 자격 증명으로 여러 사용자를 처리하는 통합은 `--read-scope own_user`(한 사용자를 지정하려면 `--read-user-id`)로 토큰을 발급합니다. 그러면 저장 메시지 op는 해당 사용자로만 동작합니다. 다른 `user_id`를 지정한 본문은 403으로 거부되고, 모든 문장에 토큰의 사용자가 적용됩니다. 최종 사용자 토큰은 `namespace: "@me"`로 이 op를 호출합니다([공유](https://github.com/ClickHouse/loom/blob/main/docs/architecture/sharing.md#saved-messages)). 대화 테이블에는 `session_id`가 없으므로 `own_session` 토큰은 거부됩니다. 다른 모든 대화 op(`append`, `get`, `list`, `search`, `threads` 등)는 스레드가 여러 사용자를 섞고 제한할 사용자 축이 없으므로 이런 토큰에서는 계속 거부됩니다.
+- **소유권, 삭제, 역할은 저장할 때마다 확인됩니다.** 다른 `user_id` 아래에 저장된 메시지를 저장하면 `indexed: false, reason: "owner_mismatch"`로 응답합니다. 삭제 표시(tombstone)된 메시지는 `reason: "deleted"`로 응답하고, 저장된 system 또는 tool 턴은 임베딩되지 않으므로 `reason: "unsupported_role"`로 응답합니다. 텍스트가 high로 판단되는 메시지도 임베딩되지 않으며 `reason: "high_sensitivity"`로 응답하고, 새 메시지는 저장되지 않습니다. 이전 빌드가 저장한 메시지는 `conversation.search_saved_messages`의 벡터 또는 키워드 결과에 나타나지 않으며, `conversation.list_saved_messages`는 이를 빈 발췌문으로 나열합니다(`conversation.threads`처럼 표시되는 `conversation_search_excerpt_chars` 문자와 그 뒤 1,024자를 검사합니다). 이 확인은 이미 저장된 메시지에도 적용됩니다.
+
+저장과 저장 취소는 append 임베딩 쓰기, 압축 정리, 스레드 삭제와 갱신 가능한 스레드 리스를 공유합니다. append와 압축은 리스를 얻기 전에 provider 작업을 마칩니다.
+
+저장된 메시지의 소유자는 대화록 행이 결정합니다. 저장은 변경 작업 자체에서 아무도 소유하지 않았거나 호출자가 소유한 행만 차지하므로, 두 사용자가 소유자 없는 메시지 하나를 저장하면 먼저 한 쪽이 차지하고 나머지는 `owner_mismatch`로 응답받습니다. 임베딩 행은 대화록 행이 호출자의 것으로 다시 읽힌 뒤에만 플래그가 지정됩니다.
+
+저장은 안전하게 재시도할 수 있습니다. 새 메시지를 동시에 두 번 저장해도 대화록 행은 하나만 저장되는데, 삽입에 메시지 식별자에서 파생된 중복 제거 토큰이 들어 있기 때문입니다. 각 호출은 메시지를 다시 읽고 중단되거나 동시에 실행된 쓰기가 남긴 것을 복구합니다. 누락된 임베딩 행을 쓰고, 마지막 임베딩이 실패했다면 다시 임베딩하며, 아직 플래그가 없는 행에 플래그를 지정합니다. 임베딩이 실패한 저장은 메시지를 저장된 상태로 보관하고 `indexed: false, reason: "embed_failed"`로 응답하며, 다시 저장하면 임베딩을 재시도합니다. 동시 저장 이후에 임베딩이 도착하는 대화록 append는 자신의 임베딩 행에 플래그를 지정합니다.
+
+`conversation.list_saved_messages`(viewer)는 쿼리 없이 한 사용자의 저장된 메시지를 최근에 저장한 순으로 페이지 단위로 읽습니다(`limit` 최대 200, 불투명한 `cursor`, 선택적 `conversation_id`). `ts`는 사용자가 메시지를 저장한 시각이며 대화록의 메시지 시각과는 무관합니다. 저장 타임스탬프 없이 기록된 행은 메시지 타임스탬프를 사용합니다. 이것은 "Saved" 패널의 첫 화면이며, 사용자가 입력하면 검색이 결과를 좁힙니다. `conversation.saved_status`(viewer)는 `conversation_id` 하나와 최대 500개의 `message_ids`를 받아 그중 이 사용자가 저장한 것을 응답하므로, 클라이언트는 대화를 열 때 한 번의 호출로 모든 메시지의 저장 상태를 표시할 수 있습니다.
+
+`conversation.unsave_message`(writer)는 저장된 메시지를 소유자의 검색에서 철회합니다. 네임스페이스가 대화록을 기록하는 경우, 소유자가 기록을 선택했으므로 턴은 플래그만 해제된 채 대화록에 남습니다. 기록하지 않는 경우에는 저장 때문에만 존재했으므로 턴이 경량 삭제로 제거됩니다(`removed: true`). 임베딩은 이전 버전이 다시 나타나지 않도록 tombstone을 유지합니다. 호출자의 사용자가 저장하지 않았거나 다른 사용자가 저장한 메시지는 `found: false`로 응답하며, 어느 쪽인지는 알려 주지 않습니다. 저장 취소는 멱등적이고, 다시 저장하면 메시지가 복원됩니다. 사용자 단위 삭제(erasure)는 그 사용자의 나머지 대화 행과 함께 저장된 메시지를 제거합니다.
+
+
+
+### 읽기와 검색
+
+| 작업 | 역할 | 동작 |
+| ---------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------- |
+| `conversation.threads` | viewer | 네임스페이스의 최근 스레드를 최신순으로 반환합니다(`window_days`, `limit`, 최대 100,000까지의 `offset`, 모든 에이전트는 `agent="*"`). |
+| `conversation.get` | viewer | 스레드 하나의 메타데이터를 반환합니다. `include_messages=true`이면 턴을 페이지 단위로 반환합니다(끝부분은 `order="desc"`). |
+| `conversation.list` | viewer | 스레드의 턴을 커서 페이지네이션으로 반환하며, 선택적으로 `run_id`로 거릅니다. |
+| `conversation.search` | viewer | 임베딩된 턴에 대한 벡터 검색이며, 선택적으로 스레드, 실행 또는 역할로 거릅니다. |
+| `conversation.update` | writer | 스레드의 `title`, `metadata` 또는 `run_id`를 변경합니다. |
+
+`conversation.search`는 코사인 유사도로 턴의 순위를 매기고, `LOOM_CONVERSATION_SEARCH_MIN_SIMILARITY`(0.30) 미만은 제외하며, 기본적으로 호출자의 모든 네임스페이스에 걸쳐 확장됩니다(`namespace_scope="all_mine"`). 임베더를 사용할 수 없으면 부분 문자열 일치로 폴백하여 op가 계속 응답합니다. 결과에는 턴의 처음 `LOOM_CONVERSATION_SEARCH_EXCERPT_CHARS`자(기본 240)가 표시되며, 턴 전체는 `conversation.get` 또는 `conversation.list`로 읽습니다. 이 op는 MCP에서 숨겨져 있으며, 에이전트는 [`loom_search`](https://github.com/ClickHouse/loom/blob/main/docs/features/unified-search.md)의 대화 섹션을 사용합니다.
+
+`memory.recall`은 다른 읽기입니다. 추출 과정에서 읽은 턴(`loom.memory_evidence`에 보관)을 검색하며, 이는 대화 플레인이 기록하는지와 무관하게 존재합니다. [검색과 질문](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/search-and-ask.md)을 참고하세요.
+
+
+
+### 압축과 삭제
+
+- **`conversation.compact`**(writer, LLM provider 필요)는 마지막 `keep_recent`(기본 10)개 이전의 가장 오래된 턴 중 요약기의 프롬프트에 들어가는 턴을 요약하고, 요약을 임베딩된 `system` 턴 하나로 기록합니다. 이 턴의 `metadata.compacted_from`에는 요약된 `msg_id`가 나열되며, 원본 턴과 그 임베딩은 tombstone 처리됩니다. 그러면 `conversation.search`는 그 자리에서 요약을 찾습니다. 같은 스레드의 다른 에이전트가 같은 텍스트로 여전히 활성 상태로 보유한 턴은(턴 검색이 색인하는 대로) 임베딩을 유지합니다(아래 delete 참고). 새 턴이 `min_to_compact`(기본 4)개 미만인 범위는 그대로 둡니다. 이전 요약은 `min_to_compact`와 `messages_summarized` 어느 쪽에도 포함되지 않습니다. 범위 시작 부분의 요약은 별도 허용량으로 프롬프트에 합쳐지며, 남은 허용량에 들어가지 않는 요약은 활성 상태로 남습니다. 실패한 실행이 남긴 요약(해당 턴이 모두 여전히 활성 상태이며 범위 안에 있고 첫 턴의 `ts`에 위치한 것)은 읽지 않고 대체됩니다. 범위 더 안쪽의 요약은 다른 턴처럼 프롬프트 예산을 쓰며 그 턴과 함께 대체됩니다. high로 판단되는 턴은 범위에서 제외됩니다. 활성 상태로 남고 요약기로 전송되지 않으므로, 범위의 첫 턴에 놓이는 요약이 스레드에서 그 턴보다 앞에 올 수 있습니다. `conversation.save_message`로 저장된 턴도 요약되거나 tombstone 처리되지 않으며, 요약과 최근 턴 사이에 원문 그대로 남습니다. 임베딩할 수 없는 요약은 아무것도 압축하지 않으며(`reason: "embed-failed"`), 어차피 high로 판단되는 요약도 임베딩되지 않으므로 마찬가지입니다(`reason: "summary-high-sensitivity"`). `embed-failed`와 달리 이 거부는 재시도할 가치가 없습니다. 턴이 활성 상태인 동안 범위는 그대로이므로, 재시도하면 같은 요약기 호출 비용을 내고 같은 요약을 얻을 가능성이 큽니다. 저장된 턴이나 high로 판단되는 턴만 있는 범위는 `reason: "nothing-to-compact"`로 응답합니다.
+- **`conversation.delete`**(admin)는 한 스레드의 턴, 스레드 행, 임베딩을 tombstone 처리하며, `confirm_thread_id`는 `thread_id`와 같아야 합니다. 같은 스레드에서 다른 에이전트도 기록한 턴은, 그 에이전트가 검색이 색인하는 같은 텍스트(user 또는 assistant 턴, 또는 요약)의 활성 사본을 보유하는 동안 임베딩을 유지합니다. 두 사본이 하나의 임베딩 행을 공유하기 때문이며, 행은 그 사본의 에이전트, 역할, 실행, 사용자를 이어받아 삭제한 에이전트의 검색에서는 사라집니다(압축도 동일하게 동작합니다). 정확히 240자인 행(이전 빌드가 자른 것이거나 그 길이의 턴)은 처음 2,048자가 해당 에이전트의 턴과 일치하는 사본이 있을 때만 유지되며, 대조할 메시지 행이 남아 있지 않으면 tombstone 처리됩니다. delete는 또한 해당 턴에 대해 자기 에이전트가 더 이상 활성 메시지를 보유하지 않는 스레드의 행도 마무리합니다. 삭제했거나 압축한 것(이전 빌드가 일부를 남겼습니다), 또는 보존 TTL이 만료시킨 것이 그 대상입니다. 개인이나 네임스페이스의 데이터를 모든 곳에서 지우려면 [`erasure.request`](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/retention-and-erasure.md)를 사용하세요.
+
+tombstone 처리된 턴은 `erasure.export`를 제외한 모든 읽기에서 걸러지며, 이 op는 `include_tombstoned: false`로 요청하지 않는 한 이를 반환합니다. 운영자가 테이블 TTL(`LOOM_RETENTION_CONVERSATIONS_DAYS`, 0 = 영구 보관)을 설정한 경우에만 디스크에서 제거됩니다. 이 TTL은 `loom.conversations`에만 적용됩니다. 텍스트를 최대 2,048자까지 보관하는 턴의 임베딩 행에는 TTL이 없습니다. 메시지가 만료되고 나면, 해당 스레드의 전체 스레드 삭제가 이를 턴의 활성 사본에 넘기거나 tombstone 처리합니다. 삭제 요청(erasure request)은 이를 tombstone 처리하며, `purge`를 지정한 `namespace_list` 삭제에서만 제거합니다. `erasure.export`는 임베딩 행을 반환하지 않으므로, TTL이 만료시킨 턴의 발췌문은 대상자와 함께 지워지지만 그들의 내보내기에는 없습니다.
+
+
+
+### 스레드 제목
+
+`conversation_titler` 워커는 제목 없는 스레드(`conversation.create` 없이 append로 만들어진 스레드)에 LLM이 작성한 짧은 제목을 붙이며, 대시보드의 대화 페이지가 이 제목을 앞세웁니다. 대화를 기록하는 네임스페이스에서, 최근 `LOOM_CONVERSATION_TITLER_WINDOW_HOURS`(168)시간 안에 활동했고 턴이 `LOOM_CONVERSATION_TITLER_MIN_TURNS`(4)개 이상인 스레드를 대상으로 하며, 한 번에 최대 `LOOM_CONVERSATION_TITLER_MAX_THREADS_PER_PASS`(10)개를 처리합니다. 기본적으로 켜져 있으며(`LOOM_CONVERSATION_TITLER_ENABLED`), 가짜 LLM에서는 아무 동작도 하지 않습니다.
+
+
+
+## 클라이언트에서 세션 캡처하기
+
+| 클라이언트 | 턴이 Loom에 전달되는 방식 |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Claude Code 플러그인 | Stop 훅(`hooks/loom-conversation.mjs`)이 세션 트랜스크립트에서 새 턴을 하나씩 추가하며, `msg_id`는 트랜스크립트 uuid입니다. `LOOM_CAPTURE_CONVERSATIONS=false`로 끌 수 있습니다. 네임스페이스의 기록 판정을 캐시해 두었다가 기록이 꺼져 있는 동안에는 추가를 건너뜁니다. |
+| Codex 플러그인 | 동일한 캡처 방식입니다. [Codex](https://github.com/ClickHouse/loom/blob/main/docs/features/integrations/codex.md)를 참고하세요. |
+| Cursor | Cursor의 대화 종료 후 훅이 실행하는 `integrations/cursor/cursor-session-hook.sh`가 트랜스크립트를 `loom ingest-transcript`에 넘깁니다. |
+| 기타 에이전트 | 내보낸 트랜스크립트에 `integrations/generic/ingest.sh`를 사용합니다. |
+| 모든 MCP 클라이언트 | 기본 `core` 목록에는 `conversation.append`가 없으며, 모델이 턴을 기록하도록 유도하는 것도 없습니다. 트랜스크립트 훅으로 캡처하거나 `loom_conversation_append`를 나열하는 `?toolset=all`을 마운트하세요. |
+| 직접 작성한 코드 | `conversation.append` 또는 아래의 Python SDK `Session`을 사용합니다. |
+
+`loom ingest-transcript --namespace NS --file session.md`는 `# user` / `# assistant` 섹션이
+번갈아 나오는 Markdown 파일 또는 `{role, content}` 객체의 JSON 배열을 읽어
+각 턴을 추가합니다(`--dry-run`은 턴 수만 세고, `--thread-id`는 고정 id를 지정합니다).
+
+플러그인은 세션 종료 시 세션의 턴을 `memory.set_from_messages(defer=true)`에도 넘기므로,
+트랜스크립트 기록 여부와 관계없이 사실이 추출됩니다. 또한 `observe.record` /
+`observe.crystallize`를 통해 도구 동작을 에피소드 관찰로 기록합니다
+([추출](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/extraction.md) 참고). 훅별 연결 방법은
+[Claude Code](https://github.com/ClickHouse/loom/blob/main/docs/features/integrations/claude-code.md)에 있습니다.
+
+
+
+## 세션 브리프
+
+세션 브리프는 하나의 작업 흐름에서 재개할 수 있는 상태입니다. 목표, 상태, 결정, 막다른 길, 완료한 일, 미해결 질문, 다음 단계, 주요 파일, 제약 사항, 포인터로 구성됩니다. 컴팩션 이후, 다음 날, 다른 클라이언트, 또는 팀원이 읽습니다. 임베딩되지 않으며 `memory.search`가 반환하지도 않습니다. 네임스페이스를 읽을 수 있는 에이전트라면 누구든 이어서 작업할 수 있습니다.
+
+| 작업 | 역할 | 동작 |
+| ---------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------- |
+| `session.brief_save` | writer | `events`(마지막 저장 이후에 일어난 일), 에이전트가 작성한 `sections`, 또는 둘 모두로 브리프를 수정(또는 새로 시작)합니다. |
+| `session.brief_get` | viewer | `brief_key`로 브리프를 불러오고, 없으면 세션이 가장 최근에 쓴 브리프(`from_session`), 그것도 없으면 `project`의 가장 최근 브리프를 불러옵니다. |
+| `session.brief_list` | viewer | 네임스페이스의 브리프를 최신순으로 한 줄씩 보여 줍니다(`mine_only`는 호출자의 브리프만). |
+| `session.brief_delete` | writer | 작성자가 잊어 달라고 요청하면 브리프를 삭제합니다. |
+
+**주소 지정.** `brief_key`가 비어 있으면 `auto//`가 되므로, 같은 작업 흐름의 모든 세션이 같은 브리프를 수정합니다. 둘 다 알 수 없으면 `session/`가 됩니다. 키는 `^[A-Za-z0-9][A-Za-z0-9_.:/@+-]{0,159}$` 패턴과 일치해야 합니다. 한 사용자(또는 세션)로 범위가 제한된 토큰은 브리프를 `~~`(또는 `~~~`)로 저장하고 ``로 보여 줍니다. 네임스페이스 전체 범위의 토큰은 이 접두사가 붙은 상태로 목록을 보며, 같은 접두사로 조회하거나 삭제할 수 있습니다. 범위가 제한된 토큰은 `~`로 시작하는 키를 보낼 수 없습니다.
+
+**수정.** `events`(종류는 `user`, `assistant`, `edit`, `command`, `error`, `read`, `search`, `tool`, `note`, `summary`이며 호출당 최대 4,000개)를 포함한 저장은 서버에서 요약됩니다. `LOOM_SESSION_BRIEF_LLM`이 켜져 있으면(기본값) `LOOM_SESSION_BRIEF_LLM_MODEL`에 지정된 모델이 `LOOM_SESSION_BRIEF_WINDOW_CHARS` 글자 단위의 윈도우마다 한 번씩 브리프를 수정하며, 저장 한 번당 최대 `LOOM_SESSION_BRIEF_MAX_WINDOWS`개의 윈도우를 처리합니다. 해당 모델의 키가 없으면 배포 환경의 LLM이 작성하고, LLM이 전혀 없으면 결정적 빌더가 목표, 상태, 파일, 오류, 포인터를 작성합니다(결정과 막다른 길은 없음). 응답의 `author`는 `llm`, `deterministic`, `model`(호출한 에이전트가 섹션을 작성함) 중 하나입니다. 운영자의 [추출 정책](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/extraction.md#operator-extraction-policy)이 적용되면 빌더는 실행되지 않으며, events에서 클라이언트 요약도 가져오지 않습니다. 모델 호출이 실패한 윈도우는 건너뛰고 나머지 윈도우는 계속 수정합니다. 호출할 모델이 없는 상태(설정된 모델이 없거나, `use_llm: false`이거나, 첫 윈도우를 수정하기 전에 조직의 모델 호출이 꺼진 경우)에서 events만 저장하면 아무것도 쓰지 않고 `changed: false`, `reason: "not-revised"`로 응답합니다. 일부 윈도우를 수정한 뒤에 조직의 모델 호출이 꺼지면, 이미 수정된 윈도우는 유지되고 그 이후로는 수정하지 않습니다. events만 저장했는데 모든 모델 호출이 실패했거나, 읽지 않은 스위치 때문에 보류되었거나, 파싱에 실패하면 클라이언트가 다시 보낼 수 있도록 503으로 거부됩니다. 에이전트의 `sections`도 함께 보내는 저장은 두 경우 모두 기존 브리프 위에 해당 섹션을 덮어쓰며, events에서는 아무것도 가져오지 않습니다.
+상태 섹션은 수정할 때마다 교체되고, 결정, 막다른 길, 완료 항목은 누적됩니다. 모든 수정본은 `loom.session_brief_revisions`에 보관되며, `brief_get`에서 `revision=N`으로 하나를 읽을 수 있습니다. 이전 저장과 같은 세션 및 `event_cursor`를 반복하는 저장은 재시도로 간주되어 아무것도 쓰지 않습니다. `if_revision`을 쓰면 저장이 compare-and-set으로 동작합니다(불일치 시 409).
+
+**복원은 사용자가 선택합니다.** 코딩 플러그인은 컴팩션 시점과 세션 종료 시점에 클라이언트의 모델 토큰을 쓰지 않고 브리프를 저장하며, 세션 시작 프라이머는 저장된 브리프의 이름만 알려 줍니다. 브리프는 사용자가 요청할 때 `loom-session` 스킬이나 대시보드의 대화 페이지에 있는 브리프 섹션을 통해 불러옵니다. `brief_get(full=true)`는 클라이언트 자체의 마지막 컴팩션 요약을 원문 그대로 브리프 아래에 덧붙입니다. 브리프는 스스로 로드되지 않습니다. 어떤 작업 흐름을 재개할지는 사용자만 알기 때문입니다.
+
+
+
+## 예시
+
+Python SDK의 `Session`은 이러한 op를 하나의 `(user, session)` 범위에 바인딩합니다. `append`는 턴을 대화 기록(transcript)에 쓰고, `flush_every`턴마다 `memory.set_from_messages`에도 씁니다. `resume`은 해당 범위에 대한 `context.pack`에 대화 기록의 마지막 부분을 더한 것입니다.
+
+```python
+from loom import Agent
+
+async with Agent("dev", "local", "support-bot", base_url="http://localhost:7777") as bot:
+ s = bot.session("thread-42", user_id="u1")
+ resumed = await s.resume(query="resume the billing migration")
+ await s.append(
+ {"role": "user", "content": "We moved invoices to the new ledger."},
+ {"role": "assistant", "content": "Noted; I'll update the export job."},
+ )
+ print(s.transcript_stored) # False when the namespace does not record
+ await s.close() # flushes the buffered turns to extraction
+
+ await bot.briefs.save(
+ project="billing",
+ branch="ledger-move",
+ sections={
+ "goal": "Move invoices to the new ledger",
+ "next_steps": ["Update the export job"],
+ },
+ )
+```
+
+`close()` 시점의 추출에서 사실을 찾으려면 실제 LLM 제공자가 필요합니다. 기본 가짜 제공자를 사용하면 턴은 그대로 기록됩니다.
+
+
+
+## 설정
+
+| 설정 | 효과 |
+| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `LOOM_CONVERSATION_SEARCH_MIN_SIMILARITY` | `conversation.search`의 코사인 하한값입니다 ([지식 → 대화](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#conversations)). |
+| `LOOM_CONVERSATION_SEARCH_EXCERPT_CHARS` | 검색 결과나 저장된 메시지 목록에서 한 턴을 얼마나 보여줄지 정하며, 실시간으로 적용됩니다 ([지식 → 대화](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#conversations)). |
+| `LOOM_CONVERSATION_TITLER_*` | 제목 생성 워커의 스위치, 실행 주기, 윈도우, 패스당 상한입니다 ([지식 → 대화](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#conversations)). |
+| `LOOM_RETENTION_CONVERSATIONS_DAYS`, `LOOM_TIERING_CONVERSATIONS_WARM_DAYS` | 대화 기록(transcript)에 대한 선택적 TTL 및 웜 볼륨 이동 설정입니다 ([보존](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#retention), [스토리지 티어링](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#storage-tiering)). |
+| `LOOM_SESSION_BRIEF_LLM`, `…_LLM_MODEL`, `…_WINDOW_CHARS`, `…_MAX_WINDOWS` | 브리프를 요약하는 방식을 정합니다 ([컨텍스트](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#context)). |
+| `LOOM_MCP_SESSION_RUN_IDLE_SECONDS` | 호출 없이 이 시간이 지나면 MCP 세션의 암묵적 실행을 종료합니다 ([MCP](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#mcp)). |
+
+
+
+## 제한 사항
+
+- **"append했는데 아무것도 없습니다."** 해당 네임스페이스에서 기록이 꺼져 있어, append가 `stored: false`로 응답한 경우입니다. `conversation.set_logging`으로 기록을 켜십시오.
+- **대화 기록은 마이닝되지 않습니다.** 기록된 턴은 스스로 메모리가 되지 않습니다.
+- **`conversation.search`는 벡터 우선입니다.** 임베딩이 포착하지 못하는 정확한 표현은 순위가 낮게 나올 수 있습니다. `memory.recall`은 추출 단계에서 읽은 턴을 대상으로 어휘 검색과 시간 범위 읽기를 수행합니다.
+- **브리프에는 크기 제한이 있습니다.** 렌더링된 브리프는 약 12,000자 이내로 유지됩니다. 각 목록 섹션에도 상한이 있어(예: 결정 20개, 막다른 길 12개, 다음 단계 8개), 오래된 항목은 밀려납니다.
+- **브리프는 잠금이 아닙니다.** 같은 브랜치의 두 세션은 같은 브리프를 수정합니다. 수정이 서로 끼어들면 안 되는 경우에는 `if_revision`을 전달하십시오.
+
+
+
+## 관련 문서
+
+- [추출](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/extraction.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/runs.md) — 세션의 쓰기와 관찰 내용이 합류하는 실행 원장.
+- [통합 검색](https://github.com/ClickHouse/loom/blob/main/docs/features/unified-search.md) — `loom_search`의 대화 섹션.
+- [추적과 재개](https://github.com/ClickHouse/loom/blob/main/docs/guides/trace-and-resume.md) — 오래 실행되는 작업을 재개하는 방법.
+- [메모리 아키텍처](../architecture/memory-architecture.md) — 내부에서 본 대화 테이블과 브리프 테이블.
diff --git a/i18n/.pending/ko/docs/features/entity-graph.md b/i18n/.pending/ko/docs/features/entity-graph.md
new file mode 100644
index 0000000000..fad19a63b9
--- /dev/null
+++ b/i18n/.pending/ko/docs/features/entity-graph.md
@@ -0,0 +1,188 @@
+
+> 이 페이지는 [영어 원문](https://github.com/ClickHouse/loom/blob/main/docs/features/entity-graph.md)을 기계 번역한 것이며, 영어 원문이 기준입니다.
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/features/entity-graph.md), which is authoritative.
+
+
+
+# 엔티티 그래프
+
+Loom은 메모리 행 옆에 같은 ClickHouse 데이터베이스로 엔티티 그래프를 유지합니다. 엔티티는 노드입니다. 같은 메모리에서 언급된 두 엔티티는 동시 출현 엣지를 공유하며, 추출 과정에서 유형이 지정된 `(subject, relation, object)` 트리플이 두 번째 엣지 집합으로 추가됩니다. 그래프는 메모리의 투영입니다. 모든 엣지는 그것을 만들어 낸 행까지 추적할 수 있습니다. 벡터 검색으로는 답할 수 없는 질문, 예를 들어 "billing service와 연결된 것은 무엇인가"와 같은 질문에 사용하세요.
+
+엔티티 커뮤니티는 기본적으로 꺼져 있습니다(`LOOM_ENTITY_COMMUNITIES_ENABLED`).
+
+
+
+## 그래프가 담고 있는 것
+
+| 테이블 | 담고 있는 것 |
+| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `loom.entity_edges` (+ `entity_edge_memories`, `entity_edge_rows`) | 공출현 관찰(`co_occur = 1`)당 한 행이며, 읽기 시 쌍별로 합산합니다. 쌍별 소스 키와, 그 쌍을 지목한 행과 값을 담습니다. |
+| `loom.entity_triples` (+ `entity_triple_memories`, `entity_triple_rows`) | `confidence`와, 추출기 모델을 `adapter_name`으로 가진 타입 지정 트리플. 트리플별 소스 키와, 그 트리플을 진술한 행과 값을 담습니다. |
+| `loom.entity_degree` | 각 엔티티의 전체 공출현 차수(`SummingMergeTree`)이며, 허브 규칙이 이를 읽습니다. |
+| `loom.entity_canonical_map` | 언급 텍스트 → 정규 엔티티. |
+| `loom.entity_communities` | 레벨별 엔티티당 커뮤니티 id. |
+| `loom.entity_vectors`, `loom.entity_summaries` | 검색의 엔티티 레그가 읽는 임베딩. |
+| `loom.derived_facts` | 검색에서 계산된 답변에 쓰이는, 단위와 날짜가 있는 숫자 팩트. |
+| `memory.link` 엣지 | 에이전트나 사람이 단언한 엣지(`supports`, `depends_on`, `caused`, …)이며, 그래프 모드 검색이 읽습니다. |
+
+엣지와 트리플은 `valid_from` / `valid_to`(소스 메모리의 `valid_at` / `valid_to`에서 가져옴)와, 이를 폐기하는 `invalid_at` 스탬프를 가집니다. `as_of`를 지정한 읽기는 해당 시점에 유효한 관찰만 합산합니다.
+
+그래프를 ClickHouse에 두는 이유는 엣지가 해당 행과 같은 요청에서 기록되고, 같은 saga로 삭제되며, 네트워크 홉 없이 메모리와 조인될 수 있기 때문입니다. 그 대가로 탐색은 범위가 제한된 집계 쿼리의 연속이 되므로, 모든 탐색에는 상한이 있습니다.
+
+
+
+## 그래프가 만들어지는 방식
+
+메모리 행이 먼저 기록되고, 그래프 행은 그 행에서 파생된 프로젝션입니다. 프로젝션에 실패하면 `loom.memory_projection_failures`에 기록되고 재시도됩니다. 재시도는 해당 행이 프로젝션에 실패했던 값을 여전히 가지고 있는 동안에만 이루어집니다. 프로젝션 실패가 쓰기를 실패시키는 일은 없습니다. `high` 민감도의 대량 항목은 아무것도 프로젝션하지 않으며, `high` 민감도의 `memory.set`은 작성자가 선언한 엔티티의 엣지만 프로젝션하고 텍스트는 프로젝션하지 않습니다.
+
+1. **엔티티.** 작성자가 `memory.set`에 `entities`를 전달하거나, `memory.set_from_messages`가 엔티티를 추출합니다. `entity_extractor` 워커(`LOOM_ENTITY_EXTRACT_ENABLED`, 기본값 켜짐)는 엔티티 없이 기록된 행에 쓰기 경로와 별개로 태그를 붙이며, 실제 LLM 제공자가 필요합니다. 엔티티 텍스트는 쓰기와 읽기에서 같은 방식으로 정규화됩니다(관사와 소유격 제거, 핵심 명사의 단수화, 1인칭은 `user`로 매핑). 그래서 "The Billing Service's"와 "billing service"는 하나의 노드입니다. `commit:` 또는 `error:` 형태의 이름은 식별자로 취급되어 같은 방식으로 정규화되지만 단수화는 하지 않습니다. `error:Timeouts`나 백틱 또는 따옴표로 감싼 같은 이름은 노드 `error:timeouts`가 됩니다. 콜론 바로 뒤에 공백이나 마크업이 오면(`Error: the build failed`, ``error:`Timeouts` ``) 일반 문장으로 간주됩니다. 대명사, 감탄사, 경동사, 두 글자 토큰은 제외됩니다. 작성된 그대로이거나 정규화한 뒤(NFKC는 `fi`를 `fi`로 바꿉니다) 256자를 넘는 텍스트도 쓰기와 `entity_filter`에서 제외됩니다. 포인트 쓰기는 이런 팩트의 주어나 목적어를 제외하는 대신 거부합니다.
+2. **엣지.** 한 메모리의 엔티티로 만들 수 있는 모든 쌍이 각각 하나의 관측 행이 되며, 메모리당 최대 100쌍입니다.
+3. **트리플.** 추출된 팩트의 관계가 트리플이 되며, 메모리당 최대 8개입니다. 동사는 `lower_snake`로 정규화됩니다. `namespace.register_ontology`(관리자)는 선호하는 엔티티 타입, 동사, 속성을 카디널리티와 함께 등록합니다. 이 집합에 없는 이름은 `ontology_warnings`를 생성하며, 거부되는 것은 없습니다.
+4. **대체가 트리플을 닫습니다.** 어떤 행이 다른 행을 대체하면, 이전 행의 열린 트리플 중 새 행이 증명하지 않는 것에 `invalid_at`이 설정됩니다. `one` 관계(고용주, 위치)에서는 더 새로운 값이 현재 값으로 유지되고, 더 오래된 값은 새 값이 시작될 때 닫힙니다. 이 닫기가 진행되는 동안 오래된 값을 다시 기술하는 쓰기는 그 값을 열린 상태로 유지합니다.
+ - 값은 시작일 기준으로 정렬되고(날짜가 없는 값은 도착한 시점에 시작), 그다음 마이크로초 단위의 도착 순서로 정렬됩니다. 따라서 경합하는 작성자들도 하나의 현재 값에 합의합니다. 하나의 쓰기 안에서는 나중에 기술된 값이 더 새롭습니다.
+ - 하나의 쓰기 안에서 과거형(`lived_in`, `worked_at`)의 날짜 없는 값은 순서와 관계없이 날짜가 있는 값보다 오래된 것으로 취급됩니다. 10월 1일부터의 Paris 옆에 "user lived_in london"이 있으면 Paris가 현재 값으로 남습니다.
+ - 값은 가장 새로운 행을 기준으로 판단됩니다. "London from Oct 15, Paris from Oct 14, London from Oct 13"이면 London이 현재 값으로 남습니다.
+ - 자체 종료 시점이 기술된 값("London until December")은 일찍 닫히지 않습니다. 그 종료 시점까지는 더 새로운 값과 함께 현재 값으로 유지됩니다.
+ - 되돌리기(`memory.restore`)는 복원된 값을 복원 시점부터, 또는 팩트 자체의 더 늦은 시작 시점("moving to Berlin on Dec 1")부터 현재 값으로 만듭니다. 다른 값은 닫히며, 그 행은 계속 유효합니다. 더 늦은 날짜의 값이나 되돌리기 이후에 기술된 값이 여전히 우선합니다. 되돌리기를 앞뒤로 반복해도 가중치는 늘어나지 않습니다.
+ - 실패한 닫기는 그것을 발생시킨 쓰기 또는 되돌리기 시점을 기준으로 다시 실행되므로, 그 이후에 기술된 값은 현재 값으로 유지됩니다.
+
+ 되돌리기가 팩트와 엣지를 어떻게 다시 기술하고, 가중치를 매기고, 다시 실행하는지는 [메모리 아키텍처](../architecture/memory-architecture.md#undo)에 있습니다.
+
+포인트 쓰기(`memory.set`, `memory.update`, `memory.update_by_id`)는 호출자가 `relations`로 전달한 트리플을 최대 8개까지 기록하며, HTTP와 SDK의 타입 지정 연산에서 가능합니다(MCP 목록에는 없음). 포인트 쓰기는 추출을 하지 않습니다. 자동 추출은 대량 경로에서 실행됩니다. 즉 `memory.set_from_messages`나 relations를 제공하는 대량 작성자의 경우입니다. 기본 가짜 제공자를 사용하면 직접 전달한 엔티티만 엣지를 형성합니다.
+
+
+
+## 작업
+
+| 작업 | 역할 | 답하는 내용 |
+| ---------------------------- | ------ | ------------------------------------------------------------------------------------------------------------- |
+| `facts.list` | viewer | `subject`, `object`, `relation`(AND) 또는 `entity`(양쪽 끝 중 하나)로 필터링한 트리플. |
+| `facts.related` | viewer | 한 엔티티와 함께 등장하는 엔티티를 강한 순서로 보여 주며, 시드가 어느 쪽에 있는지도 알려 줍니다. |
+| `facts.traverse` | viewer | 시드에서 N홉 떨어진 범위까지의 이웃. |
+| `facts.path` | viewer | `max_hops` 안에서 두 엔티티를 잇는 가장 짧은 엣지 체인. |
+| `facts.expire_by_adapter` | admin | 한 추출기가 기록한 트리플을 툼스톤 처리합니다. 메모리는 그대로 남습니다. |
+| `memory.search` (그래프 모드) | viewer | `search_mode="graph"`: 쿼리의 엔티티에서 한 홉 떨어진 결과([검색과 질문](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/search-and-ask.md)). |
+| `memory.related` | viewer | 주어진 메모리와 엔티티를 공유하는 메모리. |
+| `memory.timeline` | viewer | 한 엔티티의 메모리를 시간순으로 보여 줍니다(`entity=…`). |
+| `memory.backlinks` | viewer | 한 행의 엔티티를 공유하는 메모리. |
+| `namespace.taxonomy` | viewer | 네임스페이스의 상위 엔티티와, 계산된 경우 커뮤니티. |
+
+필드 목록: [팩트](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/facts.md), [메모리](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/memory.md). 그래프 모드가 아닐 때는 `entity_filter`가 지정한 엔티티에 관한 행의 점수를 높이며, 검색의 엔티티 레그는 쿼리가 다른 표현으로 언급한 엔티티에 관한 행을 찾아냅니다([검색과 랭킹](https://github.com/ClickHouse/loom/blob/main/docs/concepts/retrieval-and-ranking.md)).
+
+
+
+### `facts.list`
+
+필터가 없으면 `co_occur` 기준 상위 트리플을 반환하며, `sort_by="recency"`는 `last_seen` 순으로 정렬합니다.
+
+| 필드 | 효과 |
+| ----------------------- | ---------------------------------------------------------------------------------------------------- |
+| `include_sources` | 트리플마다 소스 메모리 키를 최대 10개 정도 추가합니다. |
+| `include_source_status` | 각 소스 행을 읽어, 트리플은 열려 있지만 그 뒤의 모든 행이 대체된 경우 `stale`로 표시합니다. |
+| `provenance` | `extracted`(양쪽 끝이 소스 텍스트에 있음), `inferred`, 또는 `facet`(Loom이 만든 탐색용 엣지). |
+| `as_of` | 해당 시점에 유효한 트리플만 남깁니다. |
+
+
+
+### `facts.traverse`
+
+탐색은 확장하기 전에 먼저 가지치기를 합니다. 각 홉은 프런티어를 하나의 쿼리로 보내고, 유효 기간 안에서 쌍별 관측 횟수를 합산하며, 이미 방문한 엔티티를 제외하고, 각 부모마다 가장 강한 `top_k_per_hop`개의 쌍만 남깁니다. h번째 홉의 프런티어에는 최대 K^h개의 엔티티가 있습니다. 각 엔티티는 처음 도달한 홉에서 가장 강한 부모를 통해 한 번만 보고되므로 결과는 트리 형태로 그려집니다.
+
+모든 것을 확장한 뒤 가지치기하는 단일 재귀 쿼리는 이웃 전체를 구체화하게 되며, 큰 네임스페이스에서는 3홉 탐색이 ClickHouse 메모리 한도를 넘을 수 있습니다. 홉마다 가지치기하면 비용이 결과 크기로 제한됩니다.
+
+| 필드 | 기본값 | 효과 |
+| ----------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `max_hops` | 2 (1–4) | 탐색 깊이. |
+| `top_k_per_hop` | 20 (최대 100) | 홉마다 부모당 유지하는 자식 수. |
+| `min_co_occur` | 1 | 쌍당 최소 관측 횟수. |
+| `max_nodes` | 400 (최대 5,000) | 하드 한도. 도달하면 `truncated=true`. |
+| `as_of` | 미설정 | 해당 시점에 유효한 관측만 유지합니다. |
+| `labeled` / `relations` | false / 미설정 | 타입이 있는 트리플(전체 또는 지정한 동사만)을 따라갑니다. 노드에는 `via_relation`, `via_direction`, `via_provenance`가 포함됩니다. |
+| `hub_degree` | 0 (꺼짐) | 총 차수가 이 값 이상인 노드는 허브입니다. |
+| `hub_share` | `LOOM_FACTS_TRAVERSE_HUB_SHARE` (0.01) | 노드에 도달한 엣지가 그 노드 차수에서 차지하는 비율이 이 값 이하이면 허브입니다. |
+| `rank_by` | `LOOM_FACTS_TRAVERSE_RANK_BY` (`cosine`) | 홉별 가지치기 기준: `co_occur`, `specificity`(`via_co_occur / degree`) 또는 `cosine`(`via_co_occur / sqrt(degree)`). |
+
+각 노드는 `hop`, `cumulative_weight`, `via_co_occur`, `path`(시드에서 이어지는 체인), `valid_from` / `valid_to`, `degree`, 그리고 커뮤니티가 있으면 `community_id`를 보고합니다. 노드는 홉 순, 그다음 가중치 순으로 정렬됩니다.
+
+**허브.** "user", "pr" 같은 일반적인 엔티티는 모든 것과 함께 등장합니다. 허브는 보고되지만(`hub: true`, `hubs`에 나열) 확장되지 않습니다. 시드는 항상 확장되므로, 허브의 이웃을 보려면 허브를 시드로 지정하세요. `hub_share`는 네임스페이스의 차수 규모에 의존하지 않으므로 기본 규칙입니다. `hub_degree`는 네임스페이스마다 다르므로, 설정하기 전에 차수 분포의 꼬리를 확인하세요.
+
+
+
+### `facts.path`
+
+같은 엣지에 대해 중간에서 만나는, 범위가 제한된 양방향 너비 우선 탐색입니다. `max_hops`(1–4, 기본값 3)가 전체 길이를 제한합니다. 응답은 `found`, `path`, 그리고 각 쌍의 `co_occur`와 유효 기간을 담은 `edges`입니다. `truncated=true`는 결과가 불완전할 수 있다는 뜻입니다. `found=false`이면서 `truncated=false`이면 `max_hops` 안에 연결이 없다는 뜻입니다.
+
+
+
+## 예시
+
+```python
+from loom import Agent
+
+async with Agent("dev", "local", "sre-bot", base_url="http://localhost:7777") as agent:
+ await agent.memory.set(
+ "billing/depends_on",
+ "The billing service reads invoices from the ledger database.",
+ entities=["billing service", "ledger database"],
+ )
+ walk = await agent.facts.traverse("billing service", max_hops=2, top_k_per_hop=10)
+ for node in walk["nodes"]:
+ print(node["hop"], " > ".join(node["path"]), node["via_co_occur"])
+
+ route = await agent.facts.path("billing service", "ledger outage")
+ print(route["found"], route["path"], route["truncated"])
+```
+
+HTTP로는 과거 특정 시점의 그래프 상태를 기준으로 탐색할 수 있습니다:
+
+```bash
+curl -s localhost:7777/v1/facts.traverse -H "Authorization: Bearer $LOOM_API_KEY" \
+ -H 'content-type: application/json' \
+ -d '{"org":"dev","namespace":"local","seed_entity":"billing service","max_hops":2,"as_of":"'"$AS_OF"'"}'
+```
+
+MCP로는 `op="facts.traverse"`를 지정해 `loom_op`를 호출합니다.
+
+
+
+## 그래프 유지 관리
+
+| 작업 | 방법 |
+| ----------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| 잘못된 추출기의 트리플 롤백 | `facts.expire_by_adapter(adapter_name=…, max_confidence=…)`. 메모리는 그대로 유지됩니다. |
+| 그래프 내보내기 | `loom entity-export --org O --namespace N --format graphml` (또는 `jsonld`; `--all`은 무효화된 엣지도 포함합니다). |
+| 엔티티를 커뮤니티로 클러스터링 | `LOOM_ENTITY_COMMUNITIES_ENABLED=true`를 설정합니다(아래 참고). |
+| 그래프 보기 | 대시보드의 Graph 보기([대시보드](https://github.com/ClickHouse/loom/blob/main/docs/features/dashboard.md)). |
+
+`entity_communities` 워커는 네임스페이스별로 레이블 전파(label propagation)를 실행하여 그 결과를 `loom.entity_communities`에 기록하며, 이 테이블은 `namespace.taxonomy`, 그래프 모드 확장, `community_id`에서 읽습니다. 통합(consolidation)이 켜져 있는 네임스페이스와, 최근 `LOOM_ENTITY_COMMUNITIES_WALKED_DAYS`(14)일 이내에 탐색된 네임스페이스를 대상으로 합니다. 차수가 가장 높은 엔티티부터 먼저 제외하며(`LOOM_ENTITY_COMMUNITIES_HUB_DROP_FRACTION`), 하나의 커뮤니티가 전체 엔티티의 `LOOM_ENTITY_COMMUNITIES_GIANT_SHARE` 비율을 넘는 동안에는 그 제외 비율을 두 배로 늘립니다. 이렇게 하면 일반적인 토큰 때문에 그래프가 하나의 커뮤니티로 합쳐지는 일을 막을 수 있습니다.
+
+
+
+## 설정
+
+| 설정 | 섹션 |
+| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `LOOM_FACTS_TRAVERSE_HUB_SHARE`, `…_RANK_BY` | [네임스페이스 상태, 지식 그래프, 커뮤니티](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#namespace-health-knowledge-graph-communities) |
+| `LOOM_ENTITY_COMMUNITIES_*` | 같은 섹션. |
+| `LOOM_ENTITY_EXTRACT_*` | [통합](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#consolidation) |
+| `LOOM_MEMORY_SEARCH_GRAPH_SEED` | [메모리 검색](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#memorysearch) |
+
+
+
+## 제한 사항
+
+- **동시 출현은 관계가 아닙니다.** 한 메모리에 함께 나온 두 엔티티는 문장이 무엇을 말하든 연결됩니다. 관계가 중요하다면 타입이 있는 트리플(`labeled`, `relations`) 또는 `memory.link`를 사용하세요.
+- **그래프의 품질은 엔티티의 품질에 좌우됩니다.** 엔티티가 없는 행은 `entity_extractor` 워커가 처리하기 전까지 엣지를 추가하지 않습니다.
+- **탐색에는 한계가 있습니다.** 두 엔티티가 연결되어 있지 않다고 결론 내리기 전에 `truncated`를 확인하세요.
+- **엣지가 대체된 행보다 늦게 갱신될 수 있습니다.** `facts.list(include_source_status=true)`는 아직 열려 있는 트리플을 보여 줍니다.
+- **유효성은 유효 시간(valid time)을 기준으로 합니다.** `as_of`는 사실이 성립했던 시점을 읽으며, Loom이 그 사실을 알게 된 시점을 읽지 않습니다.
+
+
+
+## 관련 문서
+
+- [검색 및 질의](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/search-and-ask.md): 그래프 모드.
+- [메모리 쓰기](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/writing.md): `entities` 전달.
+- [추출](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/extraction.md): 추출된 엔티티와 트리플의 출처.
+- [메모리 아키텍처](../architecture/memory-architecture.md): 프로젝션 라이터.
+- [워커 레퍼런스](https://github.com/ClickHouse/loom/blob/main/docs/reference/workers.md).
diff --git a/i18n/.pending/ko/docs/features/memory/history-and-provenance.md b/i18n/.pending/ko/docs/features/memory/history-and-provenance.md
new file mode 100644
index 0000000000..42391bd1e3
--- /dev/null
+++ b/i18n/.pending/ko/docs/features/memory/history-and-provenance.md
@@ -0,0 +1,209 @@
+
+> 이 페이지는 [영어 원문](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/history-and-provenance.md)을 기계 번역한 것이며, 영어 원문이 기준입니다.
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/history-and-provenance.md), which is authoritative.
+
+
+
+# 기록과 출처
+
+메모리에 대한 모든 쓰기는 새 버전을 만들며, 어떤 것도 제자리에서 수정되지 않습니다. 버전은
+추가 전용(append-only) 미러에 보관되므로, 백그라운드 병합이 일어나도 사실의 이력은 그대로 남습니다. 각 행에는
+누가 작성했는지와 어떤 경로로 메모리에 들어왔는지가 기록되고, 파생된 행에는 그 출처가 기록되며,
+사람이 해당 행이 사실임을 증명할 수 있습니다. 버전 미러가 동작하는 방식은
+[메모리 아키텍처](../../architecture/memory-architecture.md)에서 설명합니다.
+
+
+
+
+
+## 작업
+
+| 작업 | 역할 | 응답 내용 |
+| -------------------- | ------ | --------------------------------------------------------------------------------------------------------- |
+| `memory.history` | viewer | 삭제 표시(tombstone)되거나 마스킹된 버전을 포함해, 키의 모든 버전을 최신순으로 반환합니다. |
+| `memory.provenance` | viewer | 현재 행의 출처를 반환합니다: 소스 트레이스, 작성자, 소스 클래스, 추출된 대화. |
+| `memory.evidence` | viewer | 사실이 추출된 소스 턴과 이를 뒷받침하는 구간, 각 연결이 만들어진 방식을 반환합니다. |
+| `memory.backlinks` | viewer | 행을 가리키는 항목을 반환합니다: 버전, 다이제스트, 들어오고 나가는 타입 링크, 증거 수, 엔티티 이웃. |
+| `memory.lineage` | viewer | 공유 메모리의 승격 경로를 반환합니다: 누가, 어떤 행에서, 어떤 검토를 거쳐 승격했는지. |
+| `memory.verify` | writer | 로그인한 사용자 또는 서비스 계정의 자격으로 행이 사실임을 증명하거나, 그 증명을 철회합니다. |
+| `memory.redact` | admin | 행과 감사 항목은 유지한 채, 과거 버전 하나의 값을 지웁니다. |
+| `namespace.rollback` | admin | 네임스페이스의 모든 메모리 헤드를 특정 시점의 버전으로 되돌립니다. |
+| `namespace.snapshot` | admin | 네임스페이스의 큐레이션된 상태를 JSON 페이로드로 내보냅니다. |
+| `namespace.restore` | viewer | 스냅샷을 새 네임스페이스 또는 호출자가 관리하는 기존 네임스페이스로 가져옵니다. 컬렉션으로는 가져올 수 없습니다. |
+
+`namespace.snapshot`과 `namespace.restore`는 MCP 도구가 아닙니다. 필드 목록은 작업 레퍼런스의 [메모리](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md#memory)와
+[네임스페이스](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md#namespace)에 있습니다.
+
+
+
+## 버전: `memory.history`
+
+`loom.memory`는 현재 상태를 보관하며 `FINAL`로 읽으므로, 병합이 일어나면 각 행의 가장 최신 버전만 남습니다. `loom.memory_versions`는 모든 insert마다 materialized view가 채우는 추가 전용(append-only) 미러이며, `memory.history`, `memory.redact`, `namespace.rollback`이 읽는 기록(history)입니다.
+
+history 행에는 `version`(쓰기 시점의 나노초 단위 epoch), `written_at`, `value`, `confidence`, `pinned`, `expires_at`, `tombstoned_at`, `redacted_at`, `redaction_reason`, `content_sha256`, `agent`, `actor`, `source_class`가 들어 있습니다. `created_at`은 해당 행을 처음 쓴 시점이며 모든 버전에서 같은 값이 반복됩니다. `agent="*"`는 해당 키를 쓴 모든 작성자를 대상으로 합니다.
+
+```python
+from loom import Agent
+
+async with Agent(org="acme", namespace="support", agent="auditor") as agent:
+ for v in await agent.memory.history("customer/4812/plan", agent_id="*"):
+ print(v["written_at"], v["actor"], v["source_class"], v["value"])
+```
+
+툼스톤(tombstone)도 하나의 버전이므로 삭제 내역이 history에 나타나고, `memory.restore`로 14일 이내에는 해당 키를 되살릴 수 있습니다. 현재 상태를 특정 시점 기준으로 읽으려면 `memory.get`, `memory.search`, `memory.ask`에서 `as_of`를 사용하세요
+([유효 시간](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/writing.md#validity-time-valid_at-and-valid_to)).
+
+
+
+## 작성자: actor와 source class
+
+서버는 토큰과 작업을 기반으로 모든 행에 `actor`(`human:` 또는 `process:`)와 `source_class`를 기록합니다. `source_class` 값은 [메모리 개념](https://github.com/ClickHouse/loom/blob/main/docs/concepts/memory.md)에서 확인할 수 있습니다. 요청은 클래스를 `external`, `imported`, `derived`로만 낮출 수 있습니다.
+
+`memory.provenance`는 두 값과 함께 다음을 반환합니다.
+
+- `source_trace`와 이를 바탕으로 도출한 `source_kind`(`conversation`, `extracted`, `observed`, `consolidated`, `app`, `manual`, `other`)
+- 작성자가 인용한 `source_resource_id`
+- 대화의 `thread_id`와 `thread_exists`(네임스페이스가 대화 내용을 기록하지 않거나 대화 내용이 삭제된 경우 false)
+- 해당 행과 연결된, 직접 작성한 링크(`memory.link`)
+
+검색 결과에는 `source_class`와 `verified`가 포함되며, 선택 사항인 신뢰 항(`LOOM_MEMORY_SEARCH_TRUST_WEIGHT`)이 이 값을 읽습니다.
+
+
+
+## 근거: 사실이 어떤 턴에서 나왔는가
+
+추출은 각 사실을 `loom.memory_belief_sources`에 있는 해당 턴과 연결합니다.
+`memory.evidence(memory_key)`는 이러한 연결을 반환하며, 턴의 텍스트(최대 600자), 역할, 시간, 뒷받침하는 `span`, 그리고 연결이 만들어진 방식을 함께 제공합니다.
+
+| `scope` | `support_type` | 의미 |
+| --------- | ----------------- | ------------------------------------------------------------ |
+| `cited` | `extracted_from` | 추출기가 뒷받침하는 턴을 직접 지정했습니다. |
+| `lexical` | `lexical_support` | 서버가 사실을 가장 잘 맞는 턴과 매칭했습니다. |
+| `window` | `window` | 일치하는 항목이 없어 추출 윈도우 전체가 연결됩니다. |
+| `derived` | `derived_from` | 통합 계보: 해당 항목은 원본 메모리의 텍스트입니다. |
+
+응답은 연결을 scope별로 집계하므로, 검사 시 직접 인용된 사실과 느슨하게 연결된 사실을 구분할 수 있습니다. 대화의 정확한 표현이 필요하면 `memory.recall`이 저장된 턴을 검색합니다
+([추출](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/extraction.md)).
+
+
+
+## 계보
+
+- `memory.consolidate`와 기간별 다이제스트는 소스마다 `derived_from` 링크를 하나씩 `loom.memory_belief_sources`에 기록합니다. `memory.evidence`는 이 링크를 `derived` 항목으로 반환합니다.
+- 세션 다이제스트는 압축한 키 목록을 담고 있습니다(`summary` 히트의 `derived_from`).
+- `memory.lineage`(`scope="shared"`)는 공유 메모리의 승격 과정을 따라갑니다. 승격 이벤트, 승격한 주체, 근거가 된 행, 일치하는 항목이 있을 경우 해당 메모리가 유래한 learnings 후보(`match_confidence`는 `exact` 또는 `inferred`), 그리고 감사 이벤트를 보여 줍니다. `mechanism`은 `review`, `import`, `auto`, `unknown` 중 하나입니다.
+- `memory.backlinks`는 그 반대 방향으로, 어떤 행을 가리키는 항목을 보여 줍니다.
+
+`memory.delete`는 모든 소스가 사라진 통합 요약을 폐기하고, 소스가 남아 있는 통합 요약은 `conflicted`로 강등합니다.
+
+
+
+## 증명: `memory.verify`
+
+`pinned`와 `confidence`는 누가 사실을 확인했는지 알려 주지 않습니다. `memory.verify`는 이를 기록합니다. 호출자의 토큰에서 가져온 actor와 그가 증명한 콘텐츠 해시를 저장합니다. 행은 `memory_id`로 지정하거나, `namespace`와 `memory_key`를 writer 식별자와 함께 사용해 지정합니다. 해당 행의 네임스페이스에 대한 writer 권한이 필요합니다.
+
+`memory.get`과 `memory.get_by_id`는 저장된 해시와 행의 현재 해시로부터 도출한 `verification`을 반환합니다.
+
+| `verification` | 의미 |
+| -------------- | ----------------------------------------------------------------- |
+| `human` | 사람이 증명했고 이후 콘텐츠가 변경되지 않았습니다. |
+| `process` | 서비스 계정이 증명했고 이후 콘텐츠가 변경되지 않았습니다. |
+| `stale` | 누군가 증명했지만 이후 콘텐츠가 변경되었습니다. |
+| `none` | 증명된 적이 없거나 철회되었습니다. |
+
+- 편집해도 증명은 지워지지 않습니다. 누군가 다시 verify할 때까지 `stale` 상태가 됩니다.
+- `revoke=true`는 증명을 지웁니다. 변경되지 않은 행을 같은 actor가 다시 verify하는 것은 아무 동작도 하지 않습니다
+ (`changed=false`).
+- `human:` 접두사는 토큰에서 가져오므로, 에이전트는 자신이 쓴 내용을 human으로 표시할 수 없습니다.
+ 본문의 `actor`는 인증이 없는 개발 모드에서만 읽습니다.
+- 스냅샷과 복원은 증명 컬럼을 그대로 유지하며, 복원이 `verified_by`를 제거하는 일은 없습니다.
+
+
+
+## 기록 지우기: `memory.redact`
+
+`memory.redact(memory_id, version)`는 과거 버전 하나의 텍스트를 복사된 모든 위치에서 지우고, 모델이 해당 메모리로부터 만든 모든 프로필 버전도 함께 지웁니다. `redacted_at`과 `redaction_reason`을 기록하며, 행과 감사 항목은 그대로 남깁니다. 이전 버전에 유출된 비밀 정보나 개인 정보를 지울 때 사용합니다.
+
+| 위치 | 동작 |
+| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `loom.memory`, `loom.memory_versions` | `value`는 `"[REDACTED]"`가 되고, `value_json`, `evidence`, `entities`, `concepts`는 비워집니다. |
+| `loom.memory_embeddings`, `loom.memory_chunks` | 발췌문 또는 청크 해시가 현재 헤드의 것이 아닌 행은 삭제되고, 현재 헤드의 행은 남습니다. |
+| 해당 메모리로부터 만들어진 사용자의 프로필 버전 | 트레이스에 해당 메모리가 나오는 모든 버전이 같은 방식으로 지워집니다. 현재 헤드도 포함하며, 해당 키에서 파생된 행도 함께 지워집니다. |
+| `loom.shared`, 키에서 승격된 복사본 | `value`가 지워진 텍스트와 같은 모든 버전은 `"[REDACTED]"`가 되고, 해당 검색 행은 삭제됩니다. 현재 복사본은 관리자가 승격을 해제할 때까지 승격된 상태로 남습니다. |
+
+범위에서 제외되는 항목: 태그, 파일, `content_sha256`, `loom.memory_evidence`(삭제 기능이 관리), 계보 테이블(ID와 해시만 있음), 엔티티 그래프. 현재 헤드도 지워진 텍스트를 가지고 있는 경우(편집을 바이트 단위로 되돌린 경우)에는 공유 복사본을 그대로 둡니다.
+
+- 메모리의 현재 헤드는 거부합니다(`refused_head=true`). 먼저 키를 삭제하거나 다시 작성하세요. 지워진 현재 프로필은 워커가 다시 만들 때까지 렌더, 팩, 프로필 검색에서 제외됩니다.
+- 두 잠금 모드 모두 이를 거부합니다. 메모리 자체의 키와, 이 작업이 영향을 미치는 모든 프로필 키에 적용됩니다.
+- 해당 키 또는 공유 복사본의 키를 인용한 캐시된 `memory.ask`, `code.ask` 응답과 선례를 삭제합니다(`cache_rows_deleted`, `precedent_rows_deleted`). 영향을 미치는 프로필 키의 경우 삭제는 조직 전체에 적용됩니다. 모든 사용자의 프로필이 같은 키를 가지므로, 해당 키가 윈도에 들어 있던 조직 내 모든 캐시 응답과 선례가 모든 네임스페이스에서 삭제됩니다.
+- 네임스페이스는 조회 후에 확인합니다. 거부되면 403이 아니라 `redacted=false`로 응답합니다.
+- 존재하지 않는 버전에는 `redacted=false`로 응답하며 아무것도 지우지 않습니다. 프로필 버전도 지우지 않습니다.
+- 두 메모리 테이블에 대해(복사본이 아직 해당 텍스트를 가지고 있다면 `loom.shared`에도) 동기식 `ALTER TABLE … UPDATE`를 실행하고, 파생 행에 대해서는 경량 `DELETE`를 실행합니다. 즉, 관리용 호출입니다.
+
+공유 복사본의 redact와 경합하는 쓰기:
+
+- 임베딩 워커가 정리 이후에, 그 이전에 읽은 스텁으로 기록한 검색 행은 해당 키를 다음에 redact할 때까지 남습니다.
+- 키를 승격하면 다시 승격될 때까지 해당 검색 행이 사라집니다.
+- 지우기 이전에 복사본을 읽은 승격 해제는 텍스트가 담긴 툼스톤을 기록하며, 이는 해당 버전을 다시 redact할 때까지 남습니다.
+
+이후의 키 승격으로 대체되었고 그 뒤 `loom.shared`에서 병합되어 사라진 복사본은 더 이상 찾을 수 없습니다. `FINAL`이 더 이상 제공하지 않는 그 검색 행은 이후 해당 키를 정리할 때까지 남고, redact된 키가 아닌 다른 키로 저장된 캐시 응답은 만료될 때까지 남습니다.
+
+값이 `"[REDACTED]"`인 복사본은 이전 redact가 지운 것으로 간주합니다. 따라서 그 텍스트 자체를 가지고 있으면서 승격된 메모리는, 해당 키를 다음에 redact할 때 검색 행을 잃습니다.
+
+프로필 영향 범위와 그 한계는 [보안](https://github.com/ClickHouse/loom/blob/main/docs/architecture/security.md#sensitivity)에 있습니다.
+특정 사람의 데이터를 모든 곳에서 제거하려면 [삭제](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/retention-and-erasure.md#erasure)를 사용하세요.
+
+
+
+## 네임스페이스 되돌리기: `namespace.rollback`
+
+`namespace.rollback(as_of)`는 각 키에 대해 `as_of` 시점 또는 그 이전의 가장 높은 버전을 새로운 최신 버전(head)으로 다시 삽입하고, 그 이후에 생성된 키는 tombstone 처리합니다. 롤백 자체도 새로운 버전으로 기록되므로 같은 방법으로 되돌릴 수 있습니다.
+
+- 기본적으로 드라이 런으로 실행되며 `reinstate`, `remove`, `sample`을 보고합니다. `dry_run=false`를 지정하면 실제로 적용됩니다.
+- `memory_keys`(최대 500개)로 대상을 제한할 수 있습니다. `max_keys`(기본값 5,000)는 한 번의 호출에서 처리할 수 있는 키 수의 상한이며, `truncated`가 표시되면 다시 호출하라는 뜻입니다.
+- `embedding_worker`가 복원된 head를 다시 임베딩합니다.
+- 네임스페이스의 기록보다 오래되었거나 미래인 `as_of`는 거부됩니다.
+
+```bash
+curl -sX POST http://localhost:7777/v1/namespace.rollback \
+ -H "Authorization: Bearer $LOOM_API_KEY" -H 'Content-Type: application/json' \
+ -d '{"org":"dev","namespace":"local","as_of":"T09:00:00Z"}' \
+ | jq '{reinstate, remove, truncated, sample}'
+```
+
+
+
+## 스냅샷: `namespace.snapshot` 및 `namespace.restore`
+
+`namespace.snapshot`은 네임스페이스의 큐레이션된 상태를 JSON으로 내보냅니다. 내보내는 내용은 `version`, `content_sha256`, `actor`, `source_class`, 유효 기간 및 증명(attestation) 컬럼을 포함한 모든 메모리 행, 유형별 설정, 권한 부여(grant), 그리고 최대 `include_audit_tail_n`개의 최근 감사 행(기본값 1,000)입니다. `include_embeddings`는 기본적으로 false이므로, 대상 환경에서는 자체 모델로 다시 임베딩합니다.
+
+`namespace.restore(target_namespace, payload)`는 페이로드를 버전 행으로 다시 기록합니다. `snapshot_id` 기준으로 멱등적입니다(다시 실행하면 `restored=false`로 응답합니다). 복원 대상은 새 네임스페이스이거나(호출자가 admin이 되며, 이미 데이터나 권한 부여가 있는 이름에 대해서는 호출자가 이미 해당 네임스페이스를 관리하는 경우가 아니면 거부됩니다) 호출자가 관리하는 네임스페이스입니다. `rebind_agent`는 모든 행의 작성자를 다시 지정합니다. 복원된 행은 `imported`로 표시됩니다.
+
+스냅샷은 배포 백업이 아닙니다. [백업 및 복구](https://github.com/ClickHouse/loom/blob/main/docs/operations/backup-and-recovery.md)를 참고하십시오.
+
+
+
+## 감사 로그
+
+메모리를 생성하거나 변경하는 모든 쓰기는 `loom.audit_log`에 해시만 담은 행을 하나씩 남깁니다
+(키, id, 콘텐츠 해시, 행위자, 소스 클래스, 판정이 기록되며 값은 기록되지 않습니다). 매시간 생성되는
+체크포인트가 로그를 체인으로 연결합니다. [감사](https://github.com/ClickHouse/loom/blob/main/docs/features/observability/audit.md)를 참조하세요.
+
+
+
+## 제한 사항
+
+- **병합되어 사라진 버전의 편집(redaction)은 최선의 노력(best effort)으로 처리됩니다.** `loom.memory`에서는 그렇지만, 미러는 어느 경우에나 정리됩니다.
+- **기록은 미러만큼만 완전합니다.** `loom.memory`에 추가한 컬럼은 같은 마이그레이션에서 `loom.memory_versions`와 해당 뷰에도 추가해야 합니다.
+- **유효성은 유효 시간(valid-time)만 다룹니다.** `knowledge_time`은 `created_at`을 폐기(`invalid_at`) 및 삭제(`tombstoned_at`) 스탬프와 대조하여 재현하며, 별도의 트랜잭션 시간 테이블은 없습니다.
+- **`thread_exists=false`는 오류가 아닙니다.**
+- **롤백은 하드 삭제된 키를 복원하지 않습니다** (`skipped_no_head`).
+
+
+
+## 관련 문서
+
+- [메모리 쓰기](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/retention-and-erasure.md)
+- [감사](https://github.com/ClickHouse/loom/blob/main/docs/features/observability/audit.md)
diff --git a/i18n/.pending/ko/docs/features/memory/retention-and-erasure.md b/i18n/.pending/ko/docs/features/memory/retention-and-erasure.md
new file mode 100644
index 0000000000..5595de9703
--- /dev/null
+++ b/i18n/.pending/ko/docs/features/memory/retention-and-erasure.md
@@ -0,0 +1,256 @@
+
+> 이 페이지는 [영어 원문](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/retention-and-erasure.md)을 기계 번역한 것이며, 영어 원문이 기준입니다.
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/retention-and-erasure.md), which is authoritative.
+
+
+
+# 보존과 삭제
+
+Loom은 작성자, 네임스페이스 소유자 또는 운영자가 요청하지 않는 한 어떤 메모리도 삭제하지 않습니다. 메모리에는 기본 수명이 없습니다. 데이터가 사라지는 경로는 세 가지입니다. 작성자가 지정한 만료 또는 삭제, 소유자나 운영자가 설정한 보존 정책, 그리고 Loom이 보관하는 모든 위치에서 특정 범위를 제거하는 삭제 요청입니다.
+
+
+
+## 무엇을 얼마나 오래 보관하는가
+
+`schemas/schema.sql`의 메모리, 임베딩, 버전 이력, 대화, 엔티티, 요약, 작업 메모리, 지식 테이블에는 TTL이 없으며, 행을 기간에 따라 폐기하는 워커도 없습니다.
+링크 테이블 `entity_triple_rows`와 `entity_edge_rows`는 `entity_triples`와 `entity_edges`를 따르므로 TTL이 없습니다. 삭제(erasure)는 해당 메모리의 링크도 함께 삭제하며, 이전 빌드의 삭제가 남긴 고아 링크는 `loom erasure-re-verify --completed-since … --resume`으로 처리합니다.
+행이 제공 대상에서 빠지는 경우는 다음뿐입니다.
+
+- **작성자가 제거한 경우**: `memory.delete`, 행을 대체하는 같은 키 재작성, `memory.apply`, `memory.clear`, `conflicts.resolve`, `blacklist.add(sweep=true)`.
+- **작성자가 만료를 지정한 경우**: `memory.set`의 `ttl_seconds` 또는 `valid_to`, `memory.touch`, `run.complete(retain="expire")`, 리플렉션의 `expires_in_days`.
+- **소유자나 운영자가 설정한 경우**: [설정된 보존](#configured-retention)을 참고하십시오.
+
+운영 테이블(텔레메트리, 캐시, 큐)에는 고정 TTL이 있습니다. `loom.search_trace_log`와 `loom.memory_exposures`는 180일, `loom.erasure_requests`와 `loom.policy_decisions`는 90일, `loom.memory_drops`, `loom.memory_extraction_queue`, `loom.events`, `loom.embedding_cache`는 30일, `loom.llm_response_cache`는 7일입니다. 모든 테이블의 TTL은 [스키마 레퍼런스](https://github.com/ClickHouse/loom/blob/main/docs/reference/schema.md)에 나와 있습니다.
+
+타이머로 데이터를 제거하는 워커는 하나입니다. `namespace_gc`는 `kind = 'bench'`인 네임스페이스(자동 등록 시 `LOOM_NAMESPACE_BENCH_PREFIXES`로 판별)가 `LOOM_NAMESPACE_GC_IDLE_HOURS` 동안 쓰기가 없으면 삭제(erasure) 사가를 통해 제거합니다. 다른 kind는 건드리지 않습니다. [네임스페이스와 공유](https://github.com/ClickHouse/loom/blob/main/docs/features/namespaces-and-sharing.md)를 참고하십시오.
+
+
+
+### 삭제(delete)는 지우기(erase)가 아닙니다
+
+툼스톤은 `tombstoned_at`이 설정된 새 버전입니다. 읽기에서는 즉시 제공되지 않지만, 해당 행과 `loom.memory_versions`의 이전 버전은 디스크에 남아 있습니다.
+
+- `memory.restore`는 14일 이내에 툼스톤 처리된 키를 되살립니다(이후에는 `expired=true`로 응답합니다). 자동 대체(supersession)도 되돌립니다.
+- `memory.clear`(관리자)는 네임스페이스 안에서 한 에이전트 또는 사용자의 모든 메모리를 툼스톤 처리합니다. `confirm_subject`에는 구체적인 `user_id` 또는 `agent`를 그대로 다시 입력해야 합니다(`'*'`와 `'-'`는 확인으로 인정되지 않습니다). `user_id`와 함께 `agent="*"`를 지정하면 모든 에이전트 아래의 해당 사용자 행을 지우고, `agent`와 함께 `user_id="*"`를 지정하면 모든 사용자에 대한 해당 에이전트의 행을 지웁니다. `'-'`만 지정한 범위는 네임스페이스 전체 삭제와 마찬가지로 거부됩니다. 잠긴 행은 남으며 `locked_skipped`에 집계됩니다. 삭제된 키도 같은 방식으로 되살릴 수 있습니다.
+
+바이트 자체를 제거하려면 [삭제(erasure)](#erasure)를 사용하십시오. 행과 감사 추적은 유지하면서 값 하나만 지우려면 [`memory.redact`](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/history-and-provenance.md#scrubbing-history-memoryredact)를 사용하십시오.
+
+
+
+### 작성자가 지정한 만료
+
+행은 `expires_at`이 지나는 순간 읽기에서 숨겨집니다. 이후 `memory_expiry_sweep` 워커가 작성자가 지정한 `on_expire`를 새 버전으로 적용합니다.
+
+| `on_expire` | 효과 |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `tombstone` (기본값) | 툼스톤 처리되며 14일의 복원 기간이 있습니다. |
+| `demote` | 만료가 해제되고, 신뢰도가 `LOOM_MEMORY_EXPIRY_DEMOTE_FACTOR`(0.5)만큼 곱해지며 `LOOM_MEMORY_EXPIRY_DEMOTE_FLOOR`(0.05) 아래로는 내려가지 않습니다. |
+| `anonymize` | 값이 마커로 대체되고 임베딩이 제거됩니다. 행은 존재했다는 증거로 남습니다. |
+
+`memory.touch`는 행의 만료만 변경하며, 키 하나 또는 최대 1,000개(`memory_keys`)에 적용할 수 있습니다. 새 `ttl_seconds`, `clear_expiry=true`, 새 `on_expire` 중 하나를 지정합니다. `memory.sweep_expired`(관리자)는 네임스페이스에 대해 스윕을 한 번 즉시 실행하며 `dry_run`을 지원합니다. 다른 필드를 수정해도 유효한 만료는 유지됩니다.
+
+
+
+### 설정된 보존
+
+모두 기본적으로 꺼져 있습니다(0 = 영구 보관).
+
+| 위치 | 설정 방법 | 효과 |
+| ---------------------------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 네임스페이스의 메모리 유형 | `namespace.register`의 `tag_registry` 항목에 있는 `retention_days` | 유효한 만료, `ttl_seconds`, `clear_expiry` 없이 `memory.set`이 쓴 행은 `expires_at = now + N days`를 받습니다. 다시 기록된 `read_only` 행은 받지 않습니다. |
+| 민감한 행 | `LOOM_MEMORY_SENSITIVE_RETENTION_DAYS`, `LOOM_MEMORY_SENSITIVE_ON_EXPIRE` (기본값 `anonymize`) | 민감도가 `medium` / `high`인 새 행에 만료가 설정됩니다. 호출자가 지정한 만료가 더 짧으면 그것이 우선합니다. |
+| 실행(run) 자체의 쓰기 | `LOOM_MEMORY_RUN_COMPLETE_RETAIN` (`keep`, `demote`, `expire`), `LOOM_MEMORY_RUN_COMPLETE_EXPIRE_DAYS` (7) | 호출에서 지정하지 않았을 때 `run.complete`가 해당 실행의 행에 적용하는 동작입니다. 고정(pinned), 검증(verified), 승격(promoted), 잠금(locked), 일화(episodic), 리플렉션 행은 항상 유지됩니다. |
+| 네임스페이스 전체 | `namespace.register`의 `retention_days`, `warm_days` | 해당 네임스페이스 행에 대한 테이블 TTL(및 웜 티어 이동)입니다. |
+| 배포 전체 | `LOOM_RETENTION_
_DAYS`, `LOOM_TIERING_
_WARM_DAYS` | `audit_log`, `agent_events`, `memory`, `memory_embeddings`, `conversations`, `chunks`, `documents`의 테이블 TTL(및 웜 티어 이동)입니다. |
+
+Postgres를 기준 스토리지(source of truth)로 사용하는 구성에서는 마지막 두 행 모두 `memory`, `memory_embeddings`, `documents`에 보존 TTL을 적용하지 않습니다. Postgres가 아직 제공 중인 행의 ClickHouse 사본을 삭제하게 되기 때문에, 부팅 시 `LOOM_RETENTION_MEMORY_DAYS`, `LOOM_RETENTION_MEMORY_EMBEDDINGS_DAYS`, `LOOM_RETENTION_DOCUMENTS_DAYS`를 거부합니다
+([기준 스토리지](https://github.com/ClickHouse/loom/blob/main/docs/architecture/storage-authority.md)). 네임스페이스의
+`retention_days`는 `chunks`에도 적용되지 않으므로, 남아 있는 문서는 검색이 해당 문서를 찾는 데 쓰는 청크도 유지합니다. `LOOM_RETENTION_CHUNKS_DAYS`는 여전히 적용됩니다.
+
+`retention_reconcile` 워커는 마지막 두 행을 테이블마다 멱등한 `ALTER TABLE … MODIFY TTL` 하나로 적용하며, 오버라이드가 있으면 `(org, namespace)`마다 적용합니다. 네임스페이스도 배포 단위 기간도 남지 않은 테이블에서는 TTL을 제거합니다. `loom.memory`에서는 TTL이 `coalesce(expires_at, created_at)`을 기준으로 하므로 작성자의 만료가 우선합니다.
+
+- **테이블 TTL은 물리적으로 삭제합니다.** 파트가 다음에 병합될 때 삭제됩니다. 복원 기간이 없으며, 툼스톤은 자신이 숨기던 행과 함께 사라집니다.
+- **되돌리기(Undo)는 해당 기록이 남아 있는 동안만 유효합니다.** 충돌 해결기는 사람이 한 폐기 되돌리기를 `audit_log`의 `memory.unsupersede` 행으로 인정합니다. `audit_log`의 TTL이 쌍의 수명보다 짧으면, 만료된 되돌리기는 더 이상 유효하지 않으며 해결기가 그 쌍을 다시 판단하여 폐기할 수 있습니다.
+- **티어링에는 볼륨이 필요합니다.** `LOOM_TIERING_WARM_VOLUME_NAME`은 스토리지 정책에 있는 볼륨을 가리켜야 하며, 웜 기간은 보존 기간보다 짧아야 합니다.
+
+
+
+## 삭제(Erasure)
+
+`erasure.request`는 Loom이 보관하는 모든 위치에서 하나의 범위를 삭제하고, 범위 안에 남은 것이 없음을 보일 수 있게 되면 응답을 반환합니다. 한 사용자 id가 조직 전체에 가진 모든 데이터를 삭제하려면 조직 관리자가 `user_id` 범위를 요청합니다. 이 요청은 조직의 모든 네임스페이스에서 해당 사용자의 행을 삭제합니다(`purge=true`이면 툼스톤 처리하는 대신 행을 삭제하며, 남는 항목은 아래에 나열되어 있습니다). `memory.clear`는 한 네임스페이스 안에서 한 에이전트 또는 사용자의 메모리만 툼스톤 처리합니다([삭제는 소거가 아닙니다](#delete-is-not-erase)).
+
+| `scope_type` | `scope_value` | 요청할 수 있는 사람 |
+| ---------------- | --------------------------------------------------------------------------- | -------------------------------------------- |
+| `user_id` | 조직의 모든 네임스페이스에 걸친 사용자 id | 조직 관리자 |
+| `namespace` | 하나의 네임스페이스 | 해당 네임스페이스의 관리자(또는 조직 관리자) |
+| `namespace_list` | 1–500개 네임스페이스의 JSON 배열, 또는 `{"namespaces": [...], "purge": bool}` | 조직 관리자 |
+
+이 op는 writer 토큰으로 호출할 수 있지만, 핸들러는 대상에 대한 관리자 권한을 요구합니다(그렇지 않으면 403 `AUTH_INSUFFICIENT`).
+
+카테고리 링크(`loom.memory_categories`)에는 사용자 정보가 없으므로, `user_id` 삭제는 이 링크와 이를 나열하는 `memory.import` 감사 행을 그대로 둡니다. 가져온 항목의 경우 링크의 키는 `import:`와 해당 텍스트의 다이제스트이며, 이는 추측한 텍스트가 맞는지 확인해 줄 수 있습니다. `namespace` 삭제는 링크를 제거합니다.
+
+`user_id` 삭제는 해당 사용자로 기록된 원문 청크와, 사용자 정보 없이(`-`) 기록되었지만 사용자의 `(namespace, key)` 쌍에 속하는 청크를 누구의 메모리에 속하든 제거합니다. `-` 청크에 사용자의 텍스트가 들어 있을 수 있고, 쓰기 경로도 이런 청크를 작성자의 것으로 폐기하기 때문입니다. 다른 사용자로 기록된 청크는 남습니다.
+
+`user_id` 삭제는 또한 사용자의 메모리로 만들어진 통합 요약을, 어떤 신원으로 기록되었든 폐기합니다([해당 요약](../../architecture/memory-architecture.md#background-passes)). 여기에는 그 요약에서 파생된 항목도 함께 포함됩니다. 즉 버전 이력, 원문 청크와 엔티티 벡터, 요약에서 추출된 그래프 행, 요약에서 승격된 네임스페이스 전체 사본입니다. 이를 인용한 캐시된 `memory.ask` 답변과 선례도 삭제합니다.
+
+
+
+### 사가(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"]
+```
+
+- **체크포인트가 있는 멱등 단계.** 완료된 각 단계는 `steps_completed`에 기록됩니다. `erasure_recovery` 워커는 `in_progress` 또는 `failed` 상태로 멈춘 사가를 체크포인트부터 재개합니다. 각 단계는 해당 뮤테이션을 위해 최대 `LOOM_ERASURE_MUTATION_WAIT_S`만큼 기다린 뒤, 그 뮤테이션을 지목하며 실패합니다.
+- **문서 소스는 문서보다 먼저 멈춥니다.** 네임스페이스 삭제는 첫 단계인 `knowledge_sources.retire`에서 해당 네임스페이스의 [문서 소스](https://github.com/ClickHouse/loom/blob/main/docs/features/knowledge.md#document-sources)를 폐기하고 자격 증명을 지운 다음, 아직 실행 중인 각 소스의 동기화 턴이 끝나기를 기다립니다(전체 최대 30초이며, 아직 실행 중인 턴이 있으면 해당 단계가 `OVERLOADED`로 실패하고 `erasure_recovery`가 사가를 재시도합니다). 따라서 이후 단계가 문서를 삭제한 뒤에 동기화가 문서나 추출된 결정을 다시 쓰는 일은 없습니다.
+- **코드 링크는 링크 워커를 기다립니다.** `code_links.delete`는 코드 링크 워커의 큐 리스를 가져가므로, 삭제 이전에 읽은 커서를 게시하는 패스는 없습니다. Keeper가 있으면 호스트 간에, 없으면 한 프로세스 안에서 보장됩니다. 패스가 끝나기를 최대 15분 기다리며, 그 이후에는 해당 단계가 `LeaseBusy`로 실패하고 `erasure_recovery`가 재시도합니다.
+- **툼스톤 또는 purge.** 기본적으로 소프트 삭제 테이블(메모리, 임베딩, 청크, 요약, 링크)은 툼스톤 처리되며, 보존 기간 안에서는 `memory.restore`로 되살릴 수 있습니다. `erasure.list`는 이렇게 되살린 것을 `reversals_count`로 보고합니다. `purge=true`는 대신 행을 삭제합니다(와이드 테이블에서는 경량 `DELETE FROM`). 미러가 한 번이라도 있었던 네임스페이스를 포함하는 범위는 그 안의 모든 네임스페이스를 통째로 purge하므로 어느 곳에도 이런 보존 기간이 없습니다([문서 소스](https://github.com/ClickHouse/loom/blob/main/docs/architecture/document-sources.md#the-mirror)). 사용자 삭제는 사용자의 메모리가 키를 통해 만들어 낸 항목을 찾아내므로, purge에서는 해당 `loom.memory` 행과 그로부터 만들어진 통합 요약이 먼저 툼스톤 처리되고, 이 키들을 읽는 모든 단계가 끝난 뒤 `memory.retire`에서 삭제됩니다. 그때까지는 `memory.restore`로 되살릴 수 있으며(사용자 본인의 행은 되돌림으로 집계되고 요약은 집계되지 않습니다), `memory.retire`는 `memory.restore`가 되살린 항목을 삭제합니다.
+- **업로드된 원본**(지식 문서): 해당 네임스페이스의 `loom.document_blobs` 행이 먼저 삭제되고 `blob_erased_at`이 기록됩니다. 사용자 삭제는 그 사용자가 업로드했고 다른 작성자의 라이브 문서가 공유하지 않는 원본을 삭제하는데, 이는 `loom.blob_uploads`(최종 사용자의 업로드당 한 행. 원본을 가리키던 문서 버전이 교체되어 병합되었을 수 있기 때문입니다)와 해당 사용자의 문서를 통해 찾습니다. 그다음 `loom.blob_uploads`의 해당 행이 삭제됩니다. 센서스는 두 테이블을 모두 집계합니다. S3 호환 버킷(`LOOM_DOCUMENT_OBJECT_STORE=s3`)에 보관된 원본은 해당 행보다 먼저 삭제됩니다. 네임스페이스 삭제는 해당 프리픽스 아래 범위의 모든 오브젝트를 삭제하고 센서스는 거기 남은 것을 집계합니다(`objects.document_originals`). 사용자 삭제는 행이 이름을 지정했든 아니든 사용자 본인 원본의 바이트를 담은 모든 오브젝트를 삭제하고, 그 프리픽스를 다시 나열해 스토어에 남은 것이 있으면 해당 단계를 실패시킵니다. 이어서 행을 삭제하고, 그다음 어떤 행도 가리키지 않지만 그 프리픽스에 아직 남은 것을 삭제합니다. 따라서 행이 삭제로 사라진 사용자 본인의 동일 바이트 업로드도 오브젝트를 잃습니다. 단계가 실행되는 시점에 아직 진행 중인 동일 바이트의 업로드(오브젝트는 저장되었고 행은 아직 들어오지 않은 상태)는 작성자가 누구든 오브젝트를 잃으며, 그 행은 나중에 들어오면 `410 BLOB_GONE`으로 응답합니다. 원본 배치마다 삭제 직전에 다시 읽으므로 그 사이 다른 작성자의 문서가 이름을 지정한 원본은 남습니다. 그 읽기 이후에 같은 네임스페이스에서 다른 작성자가 같은 바이트를 저장하면 그것을 잃을 수 있으며, 이는 ClickHouse 스토어에서도 마찬가지입니다. 버킷이 구성되지 않았는데 행이 오브젝트를 가리키거나, 구성된 버킷과 프리픽스 밖의 오브젝트를 가리키면 바이트를 남겨 두는 대신 해당 단계가 실패합니다. 어느 스토어에서든 사용자 삭제는 원본이 들어갈 수 있는 최소한의 뮤테이션 수로 행을 삭제합니다(각 뮤테이션은 ClickHouse 파라미터 하나가 담을 수 있는 만큼 바인딩합니다). 원본을 ClickHouse에서 버킷으로 옮기는 작업(`loom knowledge migrate-originals`)은 이 원장으로 보호됩니다. 완료되지 않은 삭제가 다루는 원본은 옮기지 않으며, 삭제가 앞질러 버린 이동은 그 삭제가 정한 대로 끝납니다([원본이 저장되는 위치](https://github.com/ClickHouse/loom/blob/main/docs/features/knowledge.md#where-originals-are-stored)).
+- **수집 취소.** 사용자 삭제는 사용자의 수집(ingestion) 행을 삭제하며 취소 행도 그에 포함됩니다. 삭제 대상 사용자가 다른 작성자의 수집 작업에 대해 요청한 취소는, 그 수집 작업이 아직 대기 중이거나 처리 중인 경우(여기서 대기 중 또는 처리 중은 취소 기록이 아니라 다른 작성자의 수집 작업의 상태입니다), 먼저 신원이 없는 행(`agent`, `user_id`, `session_id`는 `'-'`, `actor`는 비어 있음)으로 보존되므로, 그 작업은 계속 취소된 상태로 남습니다.
+- **조직 전체 캐시.** `loom.idempotency`(재생된 응답)와 `loom.embedding_cache`(쿼리 벡터이며 텍스트는 저장하지 않음)는 조직 정보만 있고 네임스페이스나 최종 사용자 정보가 없으므로, 어느 범위의 삭제든 두 테이블에서 조직의 모든 행을 삭제합니다. 비용은 캐시 미스입니다. 센서스는 `loom.idempotency`는 조직 전체에서 집계하지만 `loom.embedding_cache`는 집계하지 않는데, 조직의 어떤 검색이든 이 캐시를 다시 채우기 때문입니다. 각 레플리카의 벡터 프로세스 캐시는 `LOOM_EMBEDDING_CACHE_TTL_S` 안에 만료됩니다.
+- **봇 규칙 학습 항목.** 학습 큐에 있는 사용자의 발언은 `loom.learnings_supporters`의 해당 행에만 존재하며, 사용자 삭제가 이를 삭제합니다. 지지자가 없어진 규칙 후보는 대기 중이면 삭제되고, 아니면 규칙을 비운 채 결정을 유지합니다([추출](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/extraction.md#rules-the-assistant-states-about-itself)). 센서스는 삭제된 사용자의 후보만이 아니라 조직 전체에서 이처럼 지지자가 없는 후보를 집계하므로, 조직 내 다른 삭제가 단계 도중에 남겨 둔 후보 때문에 사가가 실패할 수 있습니다. 다시 열린 해당 단계가 이를 정리합니다.
+
+
+
+### 연합 연쇄 삭제
+
+Loom이 다른 곳으로 보낸 데이터도 같은 사가에서 삭제됩니다. 외부 단계는 안전 실패(fail closed) 방식입니다. 삭제를 확인할 수 없는 백엔드(5xx, 타임아웃, 네트워크 끊김, 버전이 없는 Langfuse 상태 응답)는 해당 단계를 실패시키고 워커가 재시도합니다. "삭제할 것이 없음"(일치하는 행이 0개이거나 서비스에 없는 ClickStack 테이블)은 성공으로 간주합니다.
+
+| 백엔드 | 구성 방법 | 삭제 대상 |
+| ---------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| Langfuse | `LOOM_LANGFUSE_URL` + `LOOM_LANGFUSE_ADMIN_TOKEN` | 조직의 태그 안에서 `userId`로 찾은 트레이스, 또는 `org:` + `namespace:` 태그 쌍으로 찾은 트레이스. |
+| ClickStack | `LOOM_CLICKSTACK_DATABASE`, `LOOM_CLICKSTACK_USER_ID_KEYS` | 같은 ClickHouse 서비스의 OTel 행 중 사용자 id 속성 키 또는 네임스페이스와 일치하는 것. |
+
+ClickStack 네임스페이스 삭제는 `loom.namespace` 행이 삭제를 요청한 조직의 `loom.org`를 가질 때만 일치시킵니다. 따라서 조직 정보가 없는 Loom 자체의 op 및 도메인 메트릭은 네임스페이스 레이블을 유지합니다([ClickStack 삭제](https://github.com/ClickHouse/loom/blob/main/docs/features/integrations/clickstack.md#erasure)).
+
+구성되지 않은 백엔드는 의도만 로그로 남기고 아무것도 삭제하지 않습니다. `namespace_list` 삭제만 `external=false`를 전달할 수 있으며, `user_id`와 `namespace` 삭제는 항상 백엔드를 포함합니다. `LOOM_EXTERNAL_ERASURE_TIMEOUT_S`가 각 호출의 시간 제한입니다. 설정 방법: [Langfuse](https://github.com/ClickHouse/loom/blob/main/docs/features/integrations/langfuse.md) 및 [ClickStack](https://github.com/ClickHouse/loom/blob/main/docs/features/integrations/clickstack.md).
+
+
+
+### 잔여 데이터 센서스
+
+마지막 단계인 `verify.residue`는 읽기 경로가 접근하는 모든 테이블에서 범위 안의 라이브 행을 집계합니다. 남은 행이 하나라도 있으면 사가가 실패하며, 최종 행에는 `residue_count`, `residue`(테이블별), `verified_at`, `census`(모든 집계값, 아래 참조)가 담깁니다. 재개된 사가는 마지막 센서스에서 행이 발견된 테이블을 담당하는 단계를, 체크포인트상 완료되었더라도 다시 실행하며, 항상 다시 집계합니다.
+
+
+
+### 영수증
+
+`erasure.status`(와 `erasure.request`의 응답)에는 가장 최근 실행의 센서스 영수증이 담깁니다. 가장 최근 원장 행에 모든 스토어를 집계한 센서스가 없으면 `census`는 null입니다. 진행 중인 실행, 실행되지 못했거나 집계하지 못한 스토어가 남은 센서스, 센서스를 보관하지 않는 빌드가 쓴 행이 여기에 해당합니다. 영수증의 필드는 다음과 같습니다.
+
+- `census`: 센서스가 집계한 모든 저장소와 그 집계값이며 0도 포함합니다. 키는 테이블 이름이고, 스토리지 기준 저장소(source of truth)인 Postgres는 `pg:
`, 네임스페이스 범위의 문서 버킷은 `objects.document_originals`, 프로바이더 재구축의 복사본 전체 합계는 `provider_rebuild_copies`입니다(복사본이 없으면 0이며, 복사본에 org 컬럼이 없으면 배포 전체 기준으로 집계). 집계값은 센서스가 이 범위에서 잔여 데이터로 세는 행의 수로, 라이브 행이거나, 사가가 purge를 수행하거나 테이블에 툼스톤이 없는 경우에는 모든 행입니다([센서스 규칙](../../architecture/memory-architecture.md#erasure-saga)). `objects.document_originals`는 첫 목록 페이지를 집계하므로 "최소 이 정도"로 읽어야 합니다.
+- `purge`: 범위의 삭제 또는 툼스톤 모드입니다(단일 네임스페이스는 요청과 관계없이 툼스톤). 미러가 있는 범위([문서 소스](https://github.com/ClickHouse/loom/blob/main/docs/architecture/document-sources.md#the-mirror))는 이 값과 관계없이 삭제됩니다. purge가 없으면 툼스톤 처리된 행은 테이블이 병합될 때까지 파트에 바이트를 유지하고, purge가 있으면 행은 삭제되지만 바이트는 병합이나 reclaim 워커가 제거할 때까지 디스크에 남습니다.
+- 대상과 시각은 status의 `org`, `scope_type`, `scope_value`, `verified_at`입니다.
+
+영수증은 Loom이 센 값입니다. 응답을 보관해 두십시오. `erasure.status`는 요청 후 89일 동안 원장 행을 제공하며, 센서스도 담고 있는 `erasure.completed` 감사 행은 completed 행 뒤에 최선 노력(best-effort)으로 기록되어 `LOOM_RETENTION_AUDIT_LOG_DAYS` 동안 보관됩니다. 요청자가 응답을 받지 못한 경우(복구 워커가 끝낸 사가, 분리되어 실행된 것, 타임아웃된 호출)에는 89일 안에 `erasure.status`를 읽으십시오.
+
+
+
+#### 삭제를 직접 확인하기
+
+`--namespaces '*'` 또는 `--all`로 조직의 SQL 서피스 권한을 가진 운영자([SQL 서피스](https://github.com/ClickHouse/loom/blob/main/docs/reference/sql-surface.md#access))는 센서스 키 중 `loom.memory`, `loom.memory_versions`, `loom.conversations` 세 가지를 다시 집계하고 요청 원장(아래 네 번째 문장)을 확인할 수 있습니다. 삭제된 id와 센서스 시각은 파라미터로 바인딩하십시오. ClickHouse는 삭제 자체의 문장(아래)과 마찬가지로 바인딩된 값도 `system.query_log`에 기록하므로, 확인은 `clickhouse-client`로 실행하십시오. `pg_clickhouse`를 거치면 푸시다운된 텍스트가 Postgres 문장 로그에 사본으로 하나 더 남기 때문입니다.
+
+```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')};"
+```
+
+`org` 필터는 둘 이상의 org를 포괄하는 권한(`--all`)을 삭제 요청의 org로 한정합니다.
+각 문은 필터링하기 전에 권한의 전체 범위를 읽습니다([읽기 비용](https://github.com/ClickHouse/loom/blob/main/docs/reference/sql-surface.md#what-a-read-costs)). 따라서 큰 org나 `--all` 권한에서는 문이 SQL 사용자의 한도(`LOOM_CH_ANALYSIS_MAX_ROWS_TO_READ`, `_MAX_EXECUTION_S`)에서 멈추고 개수 대신 오류를 반환할 수 있습니다. 이 확인을 할 때는 한도를 올리십시오. 네임스페이스 범위에서는 `--param_ns=''`를 전달하고, 처음 세 개의 문은 `user_id` 대신 `namespace = {ns:String}`로 필터링합니다. `namespace_list`에서는 `scope_value`의 `namespaces`에 있는 이름마다 한 번씩 실행합니다. `sql_v1_agent_events` 문은 사용자 범위 전용입니다. 네임스페이스 삭제는 해당 네임스페이스의 요청 원장 행을 유지하기 때문입니다. 삭제가 완료된 뒤에는 각 개수가 0이어야 하며, 센서스와는 다음과 같은 차이가 있습니다. 뷰는 제한된 네임스페이스를 제외하고, `sql_v1_memories`는 거부된 행과 삭제 표시된 행을 제외하며, `sql_v1_memory_history`는 거부된 버전을 제외합니다(삭제 표시된 버전은 유지). 또한 사용자의 메모리에서 통합된 요약은 다른 `user_id`를 가지므로, 센서스는 이를 세지만 이 쿼리들은 세지 않습니다. 요청 원장 개수는 영수증 밖의 별도 확인입니다. 삭제는 사용자의 요청 원장 행을 지우지 않고 ``로 덮어쓰며, 요청 원장의 뷰에는 해당 기간의 행만 있습니다([`sql_v1_agent_events`](https://github.com/ClickHouse/loom/blob/main/docs/reference/sql-surface.md#sql_v1_agent_events)). 그래서 이 확인은 그 기간 안의 행에 대해서만 덮어쓰기를 확인해 줍니다. 그 외의 모든 센서스 키는 Loom의 개수일 뿐입니다.
+
+영수증이 다루지 않는 항목:
+
+- 두 서비스의 백업, 특정 시점 복구, WAL 및 대기 서버
+- Loom 밖에서 만든 사본. 예: [SQL 표면](https://github.com/ClickHouse/loom/blob/main/docs/reference/sql-surface.md)으로 org 자체 Postgres에 만든 테이블
+- 워커가 센서스 이후에, 그 이전에 수행한 읽기를 바탕으로 쓰는 행([스토리지 기준 백엔드](https://github.com/ClickHouse/loom/blob/main/docs/architecture/storage-authority.md#erasure))
+- 삭제 이전에 만든 스냅샷에서의 `namespace.restore`. 행이 다시 복원됩니다. 삭제를 다시 실행하면 그 센서스가 새 영수증이 됩니다.
+- 사용자 범위의 경우 버킷에 있는 문서 원본. 센서스는 네임스페이스 범위에 대해서만 이를 셉니다.
+
+삭제된 id는 삭제 증명에 필요한 곳에 남습니다. 원장 행(테이블의 TTL이 요청 후 90일에 삭제할 때까지), 감사, `loom.erasure_reversals`, 그리고 이를 지정한 문에 대한 배포 환경 자체의 로그(이를 기록한 문에 대한 ClickHouse 변경 로그, `system.query_log`, `system.text_log`, 그리고 `log_statement` 또는 `log_min_duration_statement`가 켜진 Postgres 문 로그)에 남습니다.
+
+
+
+### 포기된 saga
+
+5번 시도한 뒤 워커는 요청을 영구적으로 `failed`로 표시하고 `failure_reason`과 `steps_completed`가 담긴 `erasure.abandoned` 감사 행을 기록합니다. 이후에는 사람이 에스컬레이션해야 합니다. `loom erasure-re-verify`는 종료 상태의 saga를 다시 확인하고, `--resume`은 실패한 saga를 체크포인트부터 다시 실행합니다(외부 단계가 계속 실패하는 `namespace_list` saga에는 `--skip-external`). `--completed-since `는 실패한 saga 대신 그 이후에 검증된 완료된 saga를 다시 확인합니다. 이전 빌드가 업그레이드 중에 실행한 삭제를 위한 것이며, `--resume`과 함께 쓰면 고아 행 링크만 삭제합니다([유지보수](https://github.com/ClickHouse/loom/blob/main/docs/operations/maintenance.md#erasure)). [문제 해결](https://github.com/ClickHouse/loom/blob/main/docs/operations/troubleshooting.md)을 참고하십시오.
+
+
+
+### 작업
+
+| Op | 역할 | 동작 |
+| ----------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `erasure.request` | writer (대상의 admin) | 한 범위에 대해 saga를 실행합니다. `urgency`는 `normal` 또는 `urgent`, 그리고 `purge`, `external`. |
+| `erasure.status` | viewer | 한 요청의 상태, 현재 단계, 실패 사유, 센서스. 사용자 삭제는 해당 org의 org admin 또는 platform admin만 조회할 수 있습니다. MCP 툴셋에는 나열되지 않습니다. |
+| `erasure.list` | viewer | 최근 요청(`status`로 필터링)과 `steps_completed_count`, `reversals_count`, `residue_count`. |
+| `erasure.export` | admin | 대상자의 데이터를 JSON으로 내보냅니다: `memory`, `knowledge`, `conversations`(대화 기록 턴과 저장된 메시지), `conversation_threads`, `agent_events`, `audit_log`. 각각 `section_limit`(기본값 10,000, 초과 시 `truncated`)으로 제한되며, `conversations`는 텍스트 `LOOM_ERASURE_EXPORT_CONVERSATION_MAX_BYTES`로도 제한됩니다. 기본적으로 삭제 표시된 행을 포함합니다. |
+
+`erasure.status`와 `erasure.list`는 원장 행을 89일 동안 읽을 수 있으며, 테이블의 TTL은 90일에 이를 삭제합니다. 필드 목록은 [작업 레퍼런스](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md#erasure)를 참고하십시오.
+
+
+
+### 예시
+
+```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"])
+```
+
+SDK의 `request`는 `purge`나 `external`을 노출하지 않으므로 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}'
+```
+
+
+
+### 기여자를 위한 안내
+
+메모리 콘텐츠를 담을 수 있는 새 테이블에는 saga 단계와 센서스 항목(`server/erasure/store/census.py`의 `_CENSUS`에 `Substrate(...)` 하나)이 필요합니다. 그렇지 않으면 사유와 함께 `STEP_ONLY_TABLES`에 한 줄을 추가해야 하며, 둘 다 없으면 단위 테스트가 실패합니다. saga는 `server/erasure/app/saga.py`(`run_saga`), 백엔드는 `server/erasure/app/backends.py`, 워커는 `server/erasure/workers/recovery.py`에 있습니다.
+
+
+
+## 제한 사항
+
+- **규정 준수를 보장하지 않습니다.** saga, census, audit 해시는 엔지니어링 기본 구성 요소이며, 이것이 특정 의무를 충족하는지는 사용자가 판단해야 합니다.
+- **삭제는 느립니다.** 각 단계가 mutation 완료를 기다리므로, 범위가 크면 수 분 정도의 시간을 예상해야 합니다. SDK는 첫 응답을 최대 120초까지 기다리며, 그 이후에는 `erasure.status`를 폴링하세요.
+- **`org` 스코프는 없습니다.** 조직의 네임스페이스를 삭제하려면 `namespace_list`를 사용하세요.
+- **테이블 TTL로 삭제된 데이터는 복원할 수 없습니다.** 수명 종료를 되돌릴 수 있어야 한다면 `on_expire`와 함께 작성자가 설정하는 만료를 사용하세요.
+- **백업은 saga 범위 밖입니다.** 자세한 내용은 [백업 및 복구](https://github.com/ClickHouse/loom/blob/main/docs/operations/backup-and-recovery.md)를 참고하세요.
+- **분석 내보내기 버킷은 saga 범위 밖입니다.** 이 버킷의 파일에는 해시된 org, 네임스페이스, 에이전트 이름과 사용 횟수만 들어 있으며 메모리 내용은 포함되지 않습니다. 자세한 내용은 [해시된 이름](https://github.com/ClickHouse/loom/blob/main/docs/operations/analytics-export.md#hashed-names)을 참고하세요.
+
+
+
+## 관련 문서
+
+- [기록 및 출처](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/history-and-provenance.md): `memory.history`, `memory.redact`.
+- [메모리 쓰기](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/writing.md): 쓰기 시 사용하는 `ttl_seconds`, `valid_to`, `on_expire`.
+- [실행](https://github.com/ClickHouse/loom/blob/main/docs/features/runs.md): `run.complete`의 `retain`.
diff --git a/i18n/.pending/ko/docs/features/runs.md b/i18n/.pending/ko/docs/features/runs.md
new file mode 100644
index 0000000000..fd391565c2
--- /dev/null
+++ b/i18n/.pending/ko/docs/features/runs.md
@@ -0,0 +1,197 @@
+
+> 이 페이지는 [영어 원문](https://github.com/ClickHouse/loom/blob/main/docs/features/runs.md)을 기계 번역한 것이며, 영어 원문이 기준입니다.
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/features/runs.md), which is authoritative.
+
+
+
+# 실행
+
+실행(run)은 "이슈 1234 분류"와 같은 작업 하나를 한 번 수행하는 단위입니다. `run.begin`이 실행을 열고 `run_id`를 반환합니다. 에이전트는 쓰기 작업(`memory.set`, `memory.update`, `observe.record`)에 이 id를 함께 전달합니다. `run.complete`는 상태, 에이전트가 참고한 메모리, 그리고 선택 사항으로 회고(reflection)를 받아 실행을 닫습니다. 읽기 작업(`memory.search`, `memory.ask`)에서 본문의 `run_id`는 해당 실행 자체의 행만 걸러냅니다. 따라서 읽기에는 대신 다른 방식으로 레이블을 붙입니다. HTTP에서는 `X-Loom-Run-Id` 헤더(Python SDK에서는 `run_scope`)를, MCP에서는 세션 자체의 실행을 사용합니다. 성공한 실행이 참고한 메모리는 다음번에 더 높은 순위로 노출되고, 실패한 실행이 참고한 메모리는 그동안 얻은 가중치를 잃습니다.
+
+
+
+## 실행이 기록하는 내용
+
+실행 행은 `loom.agent_runs`에 있습니다. `run.get`이 보여 주는 대부분의 값은 읽는 시점에 다른 plane에서 파생됩니다.
+
+| 필드 | 저장 또는 파생 | 출처 |
+| ---------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `goal`, `user_request`, `model`, … | 저장 | `run.begin` |
+| `status`, `final_response` | 저장 | `run.complete` (그 전까지는 `active`) |
+| `memories_used` | 저장 | `run.complete`: 에이전트가 의존했다고 직접 밝힌 내용 |
+| `grade`, `grade_source`, … | 저장 | 실행이 종료된 후의 `run.grade` |
+| `memories_written` | 파생 | 실행의 `run_id`를 가진 `loom.memory`의 행 |
+| `recalled`, `recalled_keys` | 파생 | `run_id`에 대한 검색 트레이스 로그와 `run.complete(recalled_keys)`의 합집합 |
+| `observations` | 파생 | `run_id`가 태그된 `observe.record`의 에피소드 행 |
+| `turns`, `cost_usd` | 파생 | 실행이 열려 있는 동안 발생한 세션의 턴(`loom.agent_turn_usage`에 기록됨, Claude Code 플러그인 또는 `cost.record_turns`를 사용하는 에이전트가 기록) |
+| `budget_usd`, `budget_seconds` | 저장 | `run.begin` (0 = 예산 없음) |
+| `elapsed_seconds`, `over_budget` | 파생 | 서버 시계 기준으로 실행 시작부터 종료(또는 현재)까지의 시간과 `cost_usd`를 예산과 비교하여 계산 |
+
+`LOOM_SEARCH_TRACE_LOG_ENABLED`가 꺼져 있고 `recalled_keys`도 전송되지 않았다면 `recalled`는 `-1`입니다.
+
+
+
+## 예산
+
+`run.begin`은 선택 항목인 `budget_usd`(모델 지출)와 `budget_seconds`(실행에 걸릴 수 있는 시간)를 받습니다. `run.get`은 이 값을 `cost_usd`, `elapsed_seconds`와 비교하여 실행이 초과한 항목을 `over_budget`에 나열합니다(`cost`, `time`, 또는 둘 다). Loom은 에이전트를 실행하지 않으므로, 예산은 에이전트를 실행하는 쪽에 보내는 신호일 뿐 실행을 중단시키지 않습니다.
+
+실행의 지출은 실행이 열려 있는 동안 해당 세션에서 발생한 턴의 비용이며, 각 턴의 고유 시각(대화 기록의 `turn_at`)을 기준으로 합산합니다. 따라서 `budget_usd`에는 `session_id`가 필요합니다(없으면 422). 비용과 마찬가지로 소수점 6자리까지 유지하므로 가장 작은 값은 $0.000001입니다. 시간은 클라이언트가 보고한 `duration_ms`와 관계없이 서버 시계를 기준으로 실행 시작부터 종료까지 계산합니다. 예산은 실행의 첫 `run.begin`에서 설정하세요.
+
+세션에서 활성 실행이 예산을 초과한 것을 처음 발견한 `run.get`에는 멘토 힌트 `run_over_budget`도 함께 담기며, 플러그인이 이를 조언으로 모델에 전달합니다. 종료된 실행도 `over_budget`은 보고하지만 힌트는 받지 않습니다. 다른 멘토 힌트와 마찬가지로 세션당 한 번만 전달되며, 세션을 보내지 않는 호출자(SDK, 일반 HTTP)는 네임스페이스와 웹 프로세스마다 하나를 공유하므로, 힌트가 아니라 `over_budget`을 기준으로 판단하세요.
+
+제한 사항:
+
+- **프롬프트 사이에서만 확인됩니다.** Claude Code 플러그인은 프롬프트가 끝날 때 해당 프롬프트의 턴을 전송하므로(에이전트가 `cost.record_turns`로 직접 전송할 수도 있습니다), 비용 예산은 프롬프트 사이에서 확인되고, 단일 헤드리스 프롬프트(`claude -p`)의 지출은 끝난 뒤에야 나타납니다. 에이전트 자신의 `run.complete` 이후에 도착한 턴도 계속 합산됩니다. 호출의 비용은 호출이 반환된 뒤에야 알 수 있으므로, 실행은 어떤 곳에서 감지하기 전에 마지막 턴의 비용만큼 `budget_usd`를 넘어설 수 있습니다.
+- **클라이언트의 시계.** 이 구간은 클라이언트의 턴 시각을 서버의 실행 시각과 비교하므로, 시계가 몇 분 어긋나면 실행 경계의 턴이 잘못 분류됩니다. 턴은 전송될 때의 시각을 유지하므로, 다시 전송한 턴은 처음 속했던 실행에 그대로 남습니다. 시각 없이(또는 해석할 수 없는 시각으로) 전송한 턴은 `message_id`가 기록된 시각을 사용하며, 새 턴이면 현재 시각을 사용합니다. 처음 전송 후 1초도 안 되어 다시 전송하면 현재 시각으로 기록될 수 있습니다. `cost.record_turns`는 서버 시계보다 5초를 넘게 앞선 시각의 턴을 `turns_dated_ahead`로 응답하므로, 턴을 직접 전송하는 호출자는 시계가 빠른지 확인할 수 있습니다. Claude Code 플러그인은 응답을 읽지 않고 전송합니다.
+- **하나의 세션, 여러 실행.** 한 세션에서 동시에 열린 실행은 같은 턴을 봅니다. 중첩된 실행은 양쪽 모두에 합산되며, 비용 예산이 각각 필요한 동시 워커는 각자의 세션이 있어야 합니다.
+- **가격 정보가 없는 모델.** 가격표에 없는 모델의 턴은 비용이 0이며, `run.get`은 이런 턴을 `unpriced_turns`로 집계하고 `budget_usd`에는 합산하지 않습니다.
+- **MCP.** MCP 도구는 `budget_seconds`만 제공합니다. 모델은 턴이 기록되는 세션 id를 알지 못하기 때문입니다.
+- **재시도.** 다시 전송한 `run.begin`은 다른 재시도와 마찬가지로 실행의 행을 교체합니다. 다시 지정하지 않은 세션과 예산은 유지하고, 0이 아닌 새 예산은 기존 예산을 대체하며, 0은 기존 값을 유지합니다.
+ 새 `budget_usd`는 `session_id`와 함께 보내야 하며(없으면 422), 새 `budget_seconds`는 다른 값이 필요 없습니다.
+ 실행을 다른 세션으로 옮기는 재전송 begin은 이전 세션의 턴을 기준으로 설정된 비용 예산을 제거하고 시간 예산은 유지하며, 이를 `next`에 알려 줍니다. 예산을 제거하는 방법은 이것뿐입니다.
+ `run.begin`이 보낸 것과 다른 `run_id`로 응답했다면 그 `run_id`를 다시 보내거나 같은 `session_id`를 보내세요. 그렇지 않으면 재시도가 새 실행을 엽니다.
+
+
+
+## 불러왔다고 해서 의존한 것은 아니다
+
+`run.complete`에는 두 개의 목록이 함께 전달됩니다.
+
+- **`memories_used`** — 에이전트가 실제로 의존한 키입니다. 각 키에는 `used` 사용 이벤트가 기록되며, 결과가 긍정적이면 `evidence` 이벤트가, 부정적이면 `harm` 이벤트가 추가로 기록됩니다. `outcome`의 기본값은 `status`에서 정해집니다. `completed`는 긍정, `failed`는 부정, `cancelled`는 없음입니다.
+- **`recalled_keys`** — 실행 중에 Loom의 도구가 제공한 키입니다(Claude Code와 Codex 플러그인은 `loom_search`와 `memory.get` 결과에서 이 키를 따로 보관해 두었다가 세션이 끝날 때 전송합니다). 이 키는 `run.get`을 위해 기록될 뿐, 보상에는 반영되지 않습니다.
+
+반환되었지만 사용되지 않은 행은 아무런 보상도 받지 못합니다. 검색에 적중한 모든 행에 보상을 주면 가장 먼저 노출된 항목에 보상을 주는 셈이 되기 때문입니다.
+`usage_fold` 워커는 이 이벤트들을 강화 항으로 합산하며, [메모리 검색](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/search-and-ask.md)은 이 값을 기준으로 순위를 매깁니다. `harm` 이벤트는 얻은 가산점을 회수하되 해당 행의 작성 시점 기본값을 하한으로 하므로, 한 번의 나쁜 실행으로 행이 관련도 아래로 밀려나거나 삭제되는 일은 없습니다.
+
+`memories_used`에 지정된 프로시저 키는 프로시저 원장에도 행이 추가됩니다(경로는 비어 있고 `ok`는 결과에서 가져옵니다). `procedure.record_run`을 직접 호출하는 에이전트는 실행이 두 번 집계되지 않도록 해당 키를 `memories_used`에서 빼야 합니다. [프로시저와 학습 내용](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/procedures-and-learnings.md)을 참고하세요.
+
+
+
+## 회고
+
+`run.complete(reflection=...)`는 `what_worked`, `what_failed`, `assumptions`, `lessons`, `improvements`(각각 최대
+20개 항목), `confidence`, 그리고 교훈의 근거가 되는 `evidence` 키를 기록합니다. 이 내용은 `reflection:` 아래에 `reflection` 유형의 메모리 하나로 저장됩니다.
+
+- 임베딩되므로 이후 실행에서 `memory.search(memory_type="reflection")`으로 찾을 수 있지만,
+ 필터 없는 검색과 `memory.ask`에서는 제외됩니다.
+- `what_failed`와 `lessons`에는 `evidence` 키가 하나 이상 필요합니다(없으면 422가 반환됩니다).
+- `expires_in_days`가 지나면 만료됩니다(기본값 90, `0`은 만료 없음). 단, `memory.verify`나 긍정적인 결과가 있으면 만료가 갱신됩니다.
+- `role`(planner, executor, critic 또는 직접 정한 이름)을 지정해 시작한 실행은 회고에 `role:` 태그를 붙이므로, 같은 역할의 에이전트가 `memory.search(role=...)`를 호출하면 이 회고가 우선적으로 검색됩니다.
+
+
+
+## 실행이 기록한 행은 어떻게 되는가
+
+`run.complete`의 `retain`은 해당 실행(run) 아래에서 기록된 메모리의 처리 방식을 결정합니다.
+
+| `retain` | 효과 |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `keep` (기본값) | 아무것도 변경되지 않습니다. |
+| `demote` | 해당 메모리의 신뢰도가 즉시 낮아집니다. |
+| `expire` | `LOOM_MEMORY_RUN_COMPLETE_EXPIRE_DAYS`(기본값 7)일 뒤의 만료 시점이 `on_expire=demote`와 함께 설정되며, `memory_expiry_sweep` 워커가 이를 적용합니다. |
+
+고정(pinned), 검증(verified), 승격(promoted), 잠금(locked), 에피소딕(episodic), 리플렉션(reflection) 행은 모드와 관계없이 유지되며, 어떤 모드도 행을 삭제 표시(tombstone)하지 않습니다. 기본값은 `LOOM_MEMORY_RUN_COMPLETE_RETAIN`에서 가져옵니다. MCP 세션의 암묵적 실행은 이를 종료하는 전송 계층이 작업의 성과를 판단할 수 없으므로 항상 유지(keep)됩니다.
+
+
+
+## 평가된 실행
+
+`status`는 실행이 끝났음을 알려 주고, 평가(grade)는 그 결과가 유지되었는지를 알려 줍니다. 평가는 CI가 통과하거나 리뷰어가 풀 리퀘스트를 거절하는 시점, 즉 며칠 뒤에 도착하는 경우가 많습니다. `run.grade`는 `grade`(`pass` 또는 `fail`), `source`(`maintainer`, `ci`, `reviewer` 등 자유 텍스트), `reason`, `ref`(URL, finding key, check run id)를 받으며, 하나의 `run_id` 또는 하나의 `session_id`(예: `pr_1234`)에 속한 종료된 모든 실행을 대상으로 지정합니다. 다시 평가하면 이전 판정을 대체하고, 같은 source가 같은 판정을 내리면 아무것도 바뀌지 않습니다. 진행 중인 실행은 건너뜁니다.
+
+평가된 실행의 `memories_used`에 있는 모든 메모리는 그 평가에 반영되어 집계됩니다. 이 집계값은 `memory.proposals`가 시험 중인 각 사실(`memory.set(proposed=true)` 행) 옆에 보여 주는 값입니다. Loom이 이 값으로 제안을 결정하는 경우는 네임스페이스 소유자가 `proposal_policy.mode`를 `auto`로 설정했을 때뿐이며, 어느 모드에서든 작성자는 `memory.proposal_decide`로 직접 결정할 수 있습니다. [메모리 쓰기](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/writing.md)를 참고하세요.
+
+`run.list(grade="ungraded")`는 아직 판정을 받지 못한 종료된 실행을 나열합니다.
+
+MCP 세션은 요청하지 않아도 암묵적 실행(implicit run)을 갖습니다. 실행 범위를 가지는 첫 도구 호출이 실행을 시작하고, `DELETE /mcp` 또는 `mcp_session_run_sweep` 워커가 이를 종료합니다([MCP](https://github.com/ClickHouse/loom/blob/main/docs/reference/mcp.md) 참고). 스윕은 `environment='mcp'`이고 `metadata.implicit`가 true이며 id가 `mcp-` 뒤에 16진수 40자가 붙은 형태(전송 계층만 만들 수 있는 형태)인 활성 실행을 종료합니다. 종료 조건은 해당 실행의 토큰으로 이루어진 호출이(토큰을 기록하지 않는 실행이라면 누구의 호출이든) `LOOM_MCP_SESSION_RUN_IDLE_SECONDS` 안에 도달하지 않았을 때입니다. 이 실행은 호출자의 기본 네임스페이스에 속하므로, 그 실행을 읽는 쪽에서 보이는 내용도 그 네임스페이스 안에 머뭅니다. 실행의 goal은 `mcp session ()`라는 레이블이며 호출의 텍스트는 절대 들어가지 않습니다(읽기 호출의 쿼리는 호출자가 읽을 수 있는 어느 네임스페이스든 대상으로 삼을 수 있기 때문입니다). 또한 `memories_written`에는 그 네임스페이스의 쓰기만 나열됩니다(다른 네임스페이스의 쓰기에도 해당 `run_id`는 여전히 붙습니다). 종료는 아무것도 판정하지 않습니다. outcome은 `none`이고, 서버의 기본 retain 모드가 무엇이든 그 메모리는 유지됩니다. 따라서 두 종료가 경합하더라도(두 호스트의 스윕, 또는 `DELETE`) 최악의 경우 같은 완료 기록이 두 번 쓰일 뿐입니다.
+
+실행이 여러 웹 프로세스에 걸치는 방식은 다음과 같습니다. 실행 id는 호출자의 org, 토큰의 subject, `Mcp-Session-Id`의 해시이므로, 서버의 모든 프로세스가 같은 세션에 대해 같은 실행을 가리키고, 다른 토큰은 같은 세션 id를 보내더라도 그 실행을 지정할 수 없습니다. 프로세스는 세션의 첫 번째로 허용된 실행 범위 호출에서 실행을 등록하고, begin 행을 백그라운드에서 씁니다(대기하는 insert는 ClickHouse Cloud에서 그 호출을 수 초간 붙잡아 둘 수 있습니다). 게이트가 거부한 호출은 실행 행을 쓰지 않습니다. 행을 찾지 못한 두 프로세스가 각각 첫 begin을 쓰면, 더 이른 시작과 그 소유자가 우선합니다(첫 begin의 행 버전은 시작 시점부터 거꾸로 세며, 이후의 모든 쓰기가 이를 대체합니다). 각 프로세스는 캐시된 실행을 원장(ledger)과 대조해 최대 1분에 한 번 확인하고, 그동안 `DELETE`나 스윕이 실행을 종료했다면 다시 엽니다. `DELETE`는 어느 프로세스에 도달하든 id로 실행을 종료하며, 종료 시에는 누가 닫든 그 id로 쓰인 모든 쓰기를 집계합니다. begin 행이 아직 기록되기 전에 다른 프로세스에 도달한 `DELETE`는 종료할 대상을 찾지 못하고, 이후 begin이 열린 실행으로 기록되면 스윕이 그 실행이 유휴 상태가 된 뒤 종료합니다. 짧은 재시도로는 수 초가 걸리는 begin을 감당할 수 없고, 실행을 만든 적 없는 모든 세션의 `DELETE`를 지연시키기 때문입니다. 다시 열린 실행은 원래의 `started_at`을 유지하므로, 스윕이 종료한 뒤 나중에 다시 열린 실행의 `duration_ms`는 중간의 공백을 포함해 세션의 첫 호출부터 계산됩니다. 삭제(erasure)로 행이 지워져 확인 시 행이 전혀 없으면 그 시점에 시작하는 새 실행을 시작하므로, 삭제 이전 날짜의 실행이 되살아나지 않습니다.
+
+
+
+## 작업
+
+| 작업 | 역할 | 기능 |
+| -------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `run.begin` | writer | 실행을 시작합니다: `goal`(필수), `user_request`, `expected_outcome`, `run_id`(비어 있거나 `-`이면 새로 생성), `session_id`, `role`, `model`, `metadata`. 같은 `run_id`를 다시 보내면 해당 행을 교체하며, MCP 전송 방식의 형태(`mcp-` 뒤에 16진수 40자리)인 id에는 별도의 id가 부여됩니다. |
+| `run.complete` | writer | 실행을 한 번 종료합니다: `status`, `memories_used`, `recalled_keys`, `outcome`, `reflection`, `retain`. 멱등이 아니므로 두 번 완료하면 사용 이벤트가 두 번 추가됩니다. |
+| `run.get` | viewer | 실시간 파생 정보와 함께 실행 하나를 가져옵니다. |
+| `run.list` | viewer | 실행 목록의 한 페이지를 가져옵니다. `agent`, `session_id`, `status`, `grade`, `q`, `memory_activity`로 필터링합니다(`with`는 메모리를 활용했거나 기록한 실행만, `without`은 메모리 활동이 없는 실행만 남기며, 필터는 `limit`보다 먼저 적용됩니다). |
+| `run.grade` | writer | 종료된 실행 또는 세션의 실행들에 `pass` / `fail` 등급을 매깁니다. |
+
+`run.list`는 `order_by`(시작 시각, 소요 시간, 활용한 메모리 수를 각각 오름차순 또는 내림차순으로 지정하며, 기본값은 최신순인 `started_desc`)와 `offset`(최대 100,000)으로 페이지를 나눕니다. `q`는 목표, 실행 id 또는 에이전트에 해당 텍스트가 포함된 실행을 대소문자 구분 없이 남깁니다. `total`은 필터에 일치하는 모든 실행의 수이며, 첫 페이지 이후의 가득 찬 페이지에서는 해당 페이지만으로 알 수 없으므로 null입니다.
+
+전체 필드 목록은 [작업 레퍼런스](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md#run)에 있습니다.
+`memory.outcome_run`은 키를 지정하는 대신 일괄로 등급을 매기는 호출자를 위해, 실행 중 호출된 모든 메모리에 대해 helped / hurt 결과를 하나씩 기록합니다.
+
+
+
+## 예시
+
+Python SDK의 `run.scope`는 진입 시 실행(run)을 열고 종료 시 닫습니다. 블록 안에서 `memory.ask` 답변이 인용한 키와 `used()`에 전달된 키는 `memories_used`가 됩니다. 예외가 발생하면 실행은 `failed`(결과는 부정)로 닫힌 뒤 예외가 그대로 전파됩니다. 블록 안의 쓰기에는 해당 실행의 id가 함께 기록됩니다.
+
+```python
+from loom import Agent
+
+async with Agent(org="acme", namespace="support", agent="triage-bot") as agent:
+ async with agent.run.scope(goal="Answer ticket 4411: refund policy for annual plans") as run:
+ answer = await agent.memory.ask("what is the refund policy for annual plans?")
+ run.used("policy/refunds/annual") # relied on beyond what the answer cited
+ run.final_response = answer["answer"]
+
+ replay = await agent.run.get(run.run_id)
+ print(replay["run"]["status"], replay["memories_written"], replay["recalled"])
+
+ # Later, once the customer confirmed the answer was right:
+ await agent.run.grade("pass", run_id=run.run_id, source="support-lead")
+```
+
+HTTP를 사용할 때 수명 주기는 두 번의 호출로 이루어집니다.
+
+```bash
+curl -sX POST "$LOOM_BASE_URL/v1/run.begin" -H "Authorization: Bearer $LOOM_API_KEY" \
+ -H 'Content-Type: application/json' \
+ -d '{"org":"acme","namespace":"support","agent":"triage-bot","goal":"Answer ticket 4411"}'
+# → {"run_id":"…","status":"active","started_at":"…","next":"…"}
+
+curl -sX POST "$LOOM_BASE_URL/v1/run.complete" -H "Authorization: Bearer $LOOM_API_KEY" \
+ -H 'Content-Type: application/json' \
+ -d '{"org":"acme","namespace":"support","run_id":"…","status":"completed",
+ "memories_used":["policy/refunds/annual"]}'
+```
+
+`Agent(auto_run=True)`(또는 클라이언트 환경의 `LOOM_AUTO_RUN=on`)를 사용하면 첫 번째 메모리 플레인 호출 시점에 실행을 지연 생성하고, 이후의 모든 호출을 그 실행에 연결하며, `Agent`가 닫힐 때 결과 `none`으로 실행을 완료하므로 어떤 것에도 점수를 더하거나 차감하지 않습니다. 이 옵션은 기본적으로 꺼져 있습니다. 실행 중의 쓰기는 해당 실행으로 범위가 한정되어, 다른 실행의 행을 다시 서술한 내용은 병합되지 않고 `duplicate`로 저장되기 때문입니다.
+
+
+
+## 설정
+
+| 설정 | 효과 |
+| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `LOOM_MEMORY_RUN_COMPLETE_RETAIN` | 호출에서 `retain` 모드를 지정하지 않았을 때 사용하는 모드(`keep`)입니다. |
+| `LOOM_MEMORY_RUN_COMPLETE_EXPIRE_DAYS` | `retain=expire`가 만료 시점을 얼마나 먼 미래로 설정하는지를 정합니다(7일). |
+| `LOOM_SEARCH_TRACE_LOG_ENABLED` | 모든 검색을 해당 `run_id`로 기록하며, `recalled`는 이 기록에서 도출됩니다. 쿼리 텍스트를 로그에 남기므로 기본값은 꺼짐입니다. |
+| `LOOM_USAGE_FOLD_ENABLED` | 사용됨 / 근거 / 피해 이벤트를 랭킹으로 변환하는 `usage_fold` 워커입니다. |
+| `LOOM_MEMORY_SEARCH_REINFORCEMENT_WEIGHT`, `…_HALF_LIFE_DAYS` | 의존 이력이 검색에서 행의 순위를 얼마나, 얼마 동안 끌어올리는지를 정합니다. |
+
+[설정: 중복 제거와 만료](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#dedup-and-expiry),
+[워커](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#workers),
+[메모리 검색](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#memorysearch)를 참고하세요.
+
+
+
+## 제한
+
+- `memories_used`와 `recalled_keys`는 각각 최대 500개의 키를 받으며, `goal`은 최대 2,000자까지 허용됩니다.
+- `memories_used`의 키 중 활성 상태의 행으로 확인되지 않는 키는 아무런 효과가 없습니다. 응답의 `used_applied`는 확인된 키의 개수입니다.
+- `run.complete`는 멱등이 아닙니다. 완료를 재시도하면 사용 이벤트가 중복 집계되므로 한 번만 완료하세요.
+- SDK의 `run.scope`는 원장을 최선의 노력(best-effort)으로 기록합니다. `run.complete`가 실패해도 블록 자체의 예외가 가려지지 않으며, 완료에 실패한 실행은 `active` 상태로 남습니다.
+- 실행에 `session_id`가 없거나 클라이언트가 턴 사용량을 보고하지 않으면 `turns`와 `cost_usd`는 0입니다. 이 값은 실행이 열려 있는 동안 이루어진 턴만 집계합니다.
+
+
+
+## 관련 문서
+
+- [장시간 실행 추적 및 재개](https://github.com/ClickHouse/loom/blob/main/docs/guides/trace-and-resume.md) — `run_id`를 키로 하는 작업 메모리의 체크포인트와, 실행이 수행한 작업을 추적하는 방법.
+- [검색 및 질문](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/search-and-ask.md) — 강화(reinforcement)가 순위 결정에 반영되는 방식.
+- [작업과 결정](https://github.com/ClickHouse/loom/blob/main/docs/features/tasks-and-decisions.md) — `decision.outcome`은 결정을 내린 실행이 근거로 삼은 메모리에 기여도를 부여합니다.
+- [메모리 아키텍처](../architecture/memory-architecture.md) — 사용 이벤트 폴드(usage-event fold)와 그 기반이 되는 테이블.
diff --git a/i18n/.pending/ko/docs/glossary.md b/i18n/.pending/ko/docs/glossary.md
new file mode 100644
index 0000000000..a0d1fa7335
--- /dev/null
+++ b/i18n/.pending/ko/docs/glossary.md
@@ -0,0 +1,158 @@
+
+> 이 페이지는 [영어 원문](https://github.com/ClickHouse/loom/blob/main/docs/glossary.md)을 기계 번역한 것이며, 영어 원문이 기준입니다.
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/glossary.md), which is authoritative.
+
+
+
+# 용어집
+
+Loom의 용어를 알파벳순으로 정리하며, 각 용어는 한 번만 정의합니다. 코드 식별자는 백틱으로 표시합니다.
+
+**Abstain** — 가장 좋은 결과가 임베더에 맞게 보정된 abstain 기준 아래일 때, `memory.search`가 가장 가까운 약한 일치 항목 대신 이유 코드와 함께 `abstain=true`를 반환하는 동작입니다.
+"저장된 것이 없음"과 "관련 없는 항목이 0.3점을 받음"을 구분합니다.
+[검색과 순위 지정](https://github.com/ClickHouse/loom/blob/main/docs/concepts/retrieval-and-ranking.md)을 참고하세요.
+
+**Actor** — 누가 행을 썼는지 나타내는, 서버가 기록하는 컬럼입니다. `human:` 또는 `process:` 형태이며, 종류는 토큰에서 가져옵니다. 요청 본문에서는 읽지 않습니다.
+[ID와 네임스페이스](https://github.com/ClickHouse/loom/blob/main/docs/concepts/identities-and-namespaces.md)를 참고하세요.
+
+**Agent** — ID 튜플의 세 번째 요소로, 쓰고 읽는 프로그램의 이름입니다(`claude-code`, `support-bot`). 작성자를 기록할 뿐 읽기 경계는 아닙니다. 네임스페이스의 모든 구성원은 모든 에이전트의 행을 읽습니다.
+
+**Attestation** — 행이 검증되었음을 기록하는 `verified_*` 컬럼입니다. 편집해도 이 컬럼은 그대로 남고 오래된 것으로 표시되며, 읽는 쪽은 증명된 콘텐츠 해시를 비교해 신뢰 여부를 판단합니다. [이력과 출처](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/history-and-provenance.md)를 참고하세요.
+
+**Audit log** — `loom.audit_log`: 감사 대상 작업마다 콘텐츠 해시가 있는 행 하나를 두며, 이 행들은 해시로 연결된 시간별 체크포인트로 묶입니다. 행에는 콘텐츠가 아닌 해시가 담깁니다.
+[감사](https://github.com/ClickHouse/loom/blob/main/docs/features/observability/audit.md)를 참고하세요.
+
+**Belief revision** — 메모리 수명 주기를 바라보는 설계 관점입니다: Expand(`memory.set`), Revise(`memory.update_by_id`), Contract(`memory.delete`), Reinforce(`memory.pin`), Refuse(`blacklist.add`). [쓰기가 판정되는 방식](https://github.com/ClickHouse/loom/blob/main/docs/concepts/memory.md#how-a-write-is-judged)을 참고하세요.
+
+**Blacklist** — 일치하는 쓰기를 거부하도록 등록된 부분 문자열 또는 정규식입니다(`422 BLACKLISTED`). `sweep=true`를 지정하면 기존에 일치하는 항목도 tombstone 처리합니다.
+
+**Chunk** — 지식 문서나 소스 파일의 일부로, 검색이 문서 전체가 아닌 해당 구절을 반환할 수 있도록 따로 저장하고 임베딩합니다.
+
+**Code link** — 메모리가 언급하는 정의나 파일로의 링크이며, 이름 변경과 편집을 따라갑니다. 상태는 `fresh`, `moved`, `changed`, `unresolved`, `missing` 중 하나입니다. 아직 trunk에 없는 코드 이름은 `memory_code_links_pending_days`(14일)까지 기다립니다.
+[코드에 연결된 메모리](https://github.com/ClickHouse/loom/blob/main/docs/concepts/memory.md#memories-linked-to-code)를 참고하세요.
+
+**Code namespace** — git 저장소 하나를 인덱싱해 담는 `code` 종류의 네임스페이스로, 청크, 심볼, 엣지, 커밋, PR 이력을 포함합니다.
+[코드 인덱스](https://github.com/ClickHouse/loom/blob/main/docs/features/code-index/overview.md)를 참고하세요.
+
+**Commit coverage** — 모든 인덱스 티어가 특정 커밋을 처리했는지 여부입니다. `code.index_status(commit=...)`가 이를 알려주고, `code.coverage.watch`는 참이 되면 알립니다. [최신성](https://github.com/ClickHouse/loom/blob/main/docs/features/code-index/freshness.md)을 참고하세요.
+
+**Compiler tier** — 파서 티어가 아닌 컴파일러 수준 인덱서(SCIP)에서 도출한 코드 인덱스 사실로, 타입 정보로 해석한 호출 엣지와 참조를 말합니다.
+
+**Conflict** — 기존 메모리와 의미상 가까운 쓰기입니다(코사인 ≥ `LOOM_CONFLICT_THRESHOLD`). 두 행 모두 `conflicted`로 표시되고 서로 연결되며, 사람이나 에이전트가 해결합니다. [충돌과 거부](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/conflicts-and-refusal.md)를 참고하세요.
+
+**Consolidation** — 같은 주제에 대해 조각난 메모리를 병합하고 계보(`memory_belief_sources`, `support_type='derived_from'`)를 기록하는 백그라운드 작업입니다.
+
+**Content hash** — 메모리 값의 `content_sha256`입니다. 정확히 반복된 쓰기를 중복 제거하고, `if_match_sha256` 사전 조건을 뒷받침하며, 감사 행의 기준이 됩니다.
+
+**Context pack** — `context.pack`: 작업 메모리, 프로필, 관련 메모리, 절차, 결정을 한정된 크기로 묶어 세션 시작 시 한 번 불러오는 번들입니다.
+[통합 검색](https://github.com/ClickHouse/loom/blob/main/docs/features/unified-search.md#contextpack)을 참고하세요.
+
+**Dashboard** — 서버 루트에서 제공하는 사람용 웹 애플리케이션으로, 메모리, 활동, 소스, 검토 대기열, 작업, 저장소, 설정을 다룹니다. [대시보드](https://github.com/ClickHouse/loom/blob/main/docs/features/dashboard.md)를 참고하세요.
+
+**Decision** — 선택을 기록하는 일급 레코드(`decision.record`)로, 근거와 기각된 대안, 이후에는 결과(`decision.outcome`)를 담습니다.
+[작업과 결정](https://github.com/ClickHouse/loom/blob/main/docs/features/tasks-and-decisions.md)을 참고하세요.
+
+**Entity edge** — `loom.entity_edges`에 있는 두 엔티티 사이의 가중치가 있는 동시 출현 링크로, 유효 구간을 가지며 `facts.traverse`가 순회하는 그래프입니다.
+[엔티티 그래프](https://github.com/ClickHouse/loom/blob/main/docs/features/entity-graph.md)를 참고하세요.
+
+**Erasure saga** — `erasure.request`가 실행하는, 재개 가능하고 실패 시 닫히는(fail-closed) 단계 순서로, 모든 테이블(및 설정된 외부 백엔드)에서 대상자의 데이터를 제거하고 잔여 데이터 조사로 끝납니다. [보존과 삭제](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/retention-and-erasure.md)를 참고하세요.
+
+**Extraction** — 대화 메시지를 LLM과 품질 필터로 후보 메모리로 바꾸는 과정입니다(`memory.set_from_messages`).
+[추출](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/extraction.md)을 참고하세요.
+
+**Extractor stamp** — 코드 인덱스 추출기 모듈의 코드 토큰에 대한 해시입니다. 이 값이 바뀌면 인덱싱된 모든 저장소를 다시 청크로 나누며, 주석과 docstring은 포함되지 않습니다.
+[코드 인덱스 아키텍처](architecture/code-index-architecture.md)를 참고하세요.
+
+**FINAL** — 읽는 시점에 `ReplacingMergeTree` 테이블을 키별 최신 버전으로 합치는 ClickHouse 수정자입니다. Loom은 `loom.memory`를 이 수정자로 읽습니다.
+[ClickHouse](architecture/clickhouse.md)를 참고하세요.
+
+**Fence** — `task.claim`이 임대(lease)와 함께 반환하는 토큰입니다. 이후의 `task.progress`, `task.heartbeat`, `task.complete`, `task.fail` 호출은 이 토큰을 제시해야 하므로, 임대가 만료된 요청자는 쓸 수 없습니다.
+
+**Grant** — 주체에게 네임스페이스에 대한 역할을 부여하는 행입니다(`grants.*`).
+[토큰과 권한 부여](https://github.com/ClickHouse/loom/blob/main/docs/guides/tokens-and-grants.md)를 참고하세요.
+
+**Identity tuple** — 모든 행에 있는 `(org, namespace, agent, user_id, session_id)`입니다. 앞의 세 개는 필수이고, 뒤의 두 개는 기본값이 `'-'`입니다.
+[ID와 네임스페이스](https://github.com/ClickHouse/loom/blob/main/docs/concepts/identities-and-namespaces.md)를 참고하세요.
+
+**`ignored_args`** — 서버가 사용하지 않은 요청 필드(알 수 없거나 폐기된 필드)를 알려주는 응답 필드로, 클라이언트가 실패 없이 변경 사항을 파악할 수 있게 합니다.
+
+**Inbox** — 네임스페이스가 소유하는, 이름이 있는 작업 대기열입니다(`task.*`, `inbox.*`).
+[작업과 결정](https://github.com/ClickHouse/loom/blob/main/docs/features/tasks-and-decisions.md)을 참고하세요.
+
+**Knowledge document** — `knowledge.add`로 추가하고 검색을 위해 청크로 나눠 임베딩한 문서입니다. 메모리와는 다르며, 믿음이 아니라 참고 자료입니다.
+[지식 문서](https://github.com/ClickHouse/loom/blob/main/docs/features/knowledge.md)를 참고하세요.
+
+**Learning** — 사람의 결정을 기다리며 `loom.learnings_queue`에 있는 후보입니다(`learnings.list`, `learnings.review`). 여러 작성자가 뒷받침하는 사실은 공유 계층으로, 대화에서 시드된 사실은 네임스페이스 메모리 행으로, 봇이 자신에 대해 말한 규칙은 네임스페이스의 지식으로 승격됩니다.
+
+**`log_comment`** — Loom이 호출한 op, 워커 또는 CLI 명령으로 채우는 ClickHouse 쿼리 설정으로, `system.query_log`가 모든 문장의 출처를 알 수 있게 합니다.
+
+**`maturity`** — op가 선언하는 `stable`/`experimental` 필드입니다. core와 atomic 툴셋 어느 쪽에도 나열되지 않은 experimental op는 `all` 목록에서 빠지지만, 이름으로는 여전히 호출할 수 있습니다. [MCP 툴셋](https://github.com/ClickHouse/loom/blob/main/docs/reference/mcp.md#toolsets)을 참고하세요.
+
+**MCP tool** — op를 Model Context Protocol로 투영한 것으로, 점을 밑줄로 바꿔 `loom_`(`loom_memory_set`)로 이름 붙이며, `loom_search`, `loom_op` 같은 몇 가지 합성 도구가 추가됩니다. [MCP](https://github.com/ClickHouse/loom/blob/main/docs/reference/mcp.md)를 참고하세요.
+
+**Memory** — `loom.memory`의 행 하나: 키, 값, ID 튜플, 타입, 태그, 유효 기간, 출처로 구성됩니다. [메모리](https://github.com/ClickHouse/loom/blob/main/docs/concepts/memory.md)를 참고하세요.
+
+**Memory key** — 네임스페이스와 에이전트 안에서 메모리를 가리키는 읽기 쉬운 식별자로, 관례상 `//` 형식입니다. 기존 키에 쓰면 그 키를 대체합니다.
+
+**Memory type** — 메모리의 종류로 `semantic`, `episodic`, `procedural`, `preference`, `profile` 등이 있으며, 타입에 따라 임베딩 여부와 검색 방식이 정해집니다.
+
+**Mentor hint** — Loom이 결과에 덧붙이거나 `mentor.brief`로 제공하는 짧은 사용 제안으로, 에이전트가 잘 활용하지 못하는 plane이나 op를 알려줍니다.
+
+**Namespace** — 저장, 공유, 접근의 단위로, 조직 안의 이름 있는 작업 공간입니다. 종류는 `memory`, `code`, `bench`입니다.
+[네임스페이스와 공유](https://github.com/ClickHouse/loom/blob/main/docs/features/namespaces-and-sharing.md)를 참고하세요.
+
+**Operation (op)** — 레지스트리(`server.operations.registry.ALL_OPERATIONS`)에 선언된 항목 하나로, `POST /v1/`, MCP 도구, SDK를 통해 제공됩니다.
+[op 레퍼런스](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md)를 참고하세요.
+
+**Org** — 최상위 테넌트이며 ID 튜플의 첫 번째 요소입니다.
+
+**Pinned** — `memory.pin`으로 표시한 메모리입니다. 고정된 메모리와 충돌하는 쓰기는 `409 PINNED_CONFLICT`로 거부됩니다.
+
+**Plane** — 고유한 op와 테이블을 가진 제품 영역으로, 메모리, 지식, 대화, 그래프, 코드, 트래커, 실행과 작업, 감사가 있습니다.
+
+**Procedure** — 재사용할 수 있는 방법 안내(`procedure.add` / `match`)로, `procedural` 타입의 메모리로 저장됩니다. [절차와 learning](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/procedures-and-learnings.md)을 참고하세요.
+
+**Profile** — 에이전트나 사용자의 기본 컨텍스트(`profile.*`)로, `context.pack`이 가장 먼저 불러옵니다.
+
+**Projection** — 쓰기에서 파생된 행(임베딩, 그래프 엣지, 요약)입니다.
+실패한 projection은 기록되고 재시도됩니다(`ops.projection_failures.*`).
+
+**Read scope** — 하나의 네임스페이스 안에서 읽기를 제한하는 `read_scope`로, `namespace`(모든 행, 기본값), `own_user`, `own_session` 중 하나입니다. 토큰의 클레임은 상한이며, 요청은 이를 좁힐 수는 있어도 넓힐 수는 없습니다.
+[ID와 네임스페이스](https://github.com/ClickHouse/loom/blob/main/docs/concepts/identities-and-namespaces.md#read-scope-inside-a-namespace)를 참고하세요.
+
+**Record** — 등록된 레코드 스키마(`memory_schema.*`)로 검증된 구조화 메모리입니다. 트래커 레코드와 혼동하지 마세요.
+
+**ReplacingMergeTree (RMT)** — 대부분의 Loom 테이블을 뒷받침하는 ClickHouse 엔진입니다. 새 버전 행이 병합 시점이나 `FINAL` 읽기 시점에 이전 행을 대체하므로, 모든 쓰기 경로는 모든 컬럼을 그대로 이어서 기록해야 합니다. [ClickHouse](architecture/clickhouse.md)를 참고하세요.
+
+**Residue census** — 삭제 saga의 마지막 단계로, 읽기 경로가 접근하는 모든 테이블에서 범위 안의 살아 있는 행 수를 셉니다. 잔여 데이터가 하나라도 있으면 saga는 실패합니다.
+
+**Role** — 권한이 높아지는 순서로 `viewer`, `writer`, `admin`, `org_admin`, `platform_admin`이 있습니다. 각 op는 필요한 최소 역할을 선언합니다.
+
+**Run** — `run.begin`과 `run.complete`로 묶이는 에이전트 실행 한 번으로, 무엇을 불러오고 썼는지 기록합니다. [실행](https://github.com/ClickHouse/loom/blob/main/docs/features/runs.md)을 참고하세요.
+
+**Session** — 대화 또는 작업 기간으로, ID 튜플의 다섯 번째 요소입니다. **session brief**(`session.brief_*`)는 나중에 재개할 수 있도록 저장한 요약입니다.
+
+**Shared layer** — `(org, namespace, memory_key)`마다 하나의 표준 행이 있으며, 에이전트가 쓴 행에서 승격됩니다(`memory.promote` / `memory.demote`, 테이블 `loom.shared`).
+다른 계층의 "비공개"는 승격되지 않았다는 뜻이지, 숨겨져 있다는 뜻이 아닙니다.
+
+**Source class** — 서버가 기록하는 행의 출처 분류로, `asserted`, `extracted`, `observed`, `derived`, `imported`, `external` 중 하나입니다. 요청으로는 등급을 낮추는 것만 가능합니다.
+
+**Tier** — 코드 인덱스 사실을 만든 추출기(파서 또는 컴파일러)를 가리키며, 응답에는 어느 티어가 뒷받침하는지 표시됩니다.
+
+**Tombstone** — 메모리가 삭제되었음을 표시하는 더 높은 버전의 행입니다. `memory.restore`로 유예 기간 안에 되돌릴 수 있으며, `memory.delete`는 물리적으로 아무것도 삭제하지 않습니다.
+
+**Toolset** — 클라이언트가 요청하는 MCP 목록(`core`, `coding`, `atomic`, `tasks`, `tracker`, `readonly`, `all`)입니다. 무엇이 나열되는지를 바꿀 뿐, 토큰이 호출할 수 있는 범위는 바꾸지 않습니다.
+
+**Tracker** — 이슈 트래커의 레코드(이슈, PR, CI 실행)를 설정된 소스에서 읽어 중복 확인, bisect, 테스트 이력에 사용하는 plane입니다.
+[트래커](https://github.com/ClickHouse/loom/blob/main/docs/features/tracker/overview.md)를 참고하세요.
+
+**Trust mode** — inbox 소유자가 게시자에 대해 설정하는 수락 정책으로, Loom은 이를 저장만 하고 스스로 바꾸지 않습니다.
+
+**Valid time** — 메모리의 `valid_at` / `valid_to`(엔티티 엣지에서는 `valid_from` / `valid_to`)로, 사실이 현실에서 참이었던 기간입니다. Loom은 유효 시간만 기록하며 이중 시간(bi-temporal)은 아닙니다.
+
+**Version** — `ReplacingMergeTree`가 가장 큰 값을 유지하는, 단조 증가하는 컬럼입니다. 삭제를 포함해 메모리에 대한 모든 쓰기는 새 버전이 됩니다.
+
+**Worker** — `server/workers/registry.py`(`_WORKERS`)에 행으로 등록된, 감독되는 백그라운드 루프입니다. [워커](https://github.com/ClickHouse/loom/blob/main/docs/reference/workers.md)를 참고하세요.
+
+**Working memory** — 현재 작업을 위한 스크래치패드 블록(`working_memory.*`)으로, 임베딩하거나 순위를 매기지 않으며 `context.pack`이 영구 메모리보다 먼저 불러옵니다.
+[작업 메모리와 프로필](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/working-memory-and-profiles.md)을 참고하세요.
diff --git a/i18n/.pending/ko/docs/guides/performance-tuning.md b/i18n/.pending/ko/docs/guides/performance-tuning.md
new file mode 100644
index 0000000000..6df2a1ec65
--- /dev/null
+++ b/i18n/.pending/ko/docs/guides/performance-tuning.md
@@ -0,0 +1,160 @@
+
+> 이 페이지는 [영어 원문](https://github.com/ClickHouse/loom/blob/main/docs/guides/performance-tuning.md)을 기계 번역한 것이며, 영어 원문이 기준입니다.
+> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/guides/performance-tuning.md), which is authoritative.
+
+
+
+# Loom 성능 튜닝
+
+이 페이지의 모든 조정 항목은 설정 또는 요청 필드입니다.
+[구성 레퍼런스](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md)에서 각 설정의 기본값과
+의미를 확인할 수 있습니다. 트레이드오프를 측정할 수 있는 경우, 이 페이지에 측정에 사용하는 명령을 명시합니다.
+
+
+
+## 먼저 측정하기
+
+| 질문 | 명령 | 필요한 것 |
+| -------------------------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------- |
+| 동시성 N에서 한 op의 p50 / p95 / p99 및 RPS | `make bench OP=memory.search C=5 D=60` (`scripts/ops/benchmark.py`) | 실행 중인 서버. 쓰기는 `bench-…` 네임스페이스로 들어감 |
+| 랭킹 또는 임베더 변경이 recall을 떨어뜨렸는가? | `make bench-quick` (답변 판정기를 사용하는 공개 장기 메모리 벤치마크의 일부) | 실제 provider, `OPENAI_API_KEY` |
+| 기록된 기준선 대비 recall | `make bench-quality-gate MIN_RECALL=…` | 실제 provider |
+| 검색 모드 × rerank × 풀 너비 | `make bench-matrix` (`bench/MATRIX_RESULTS.md`에 기록) | 실행 중인 서버 |
+| 추출 및 그래프 추출 회귀 | `make bench-algorithm-gate` | 실행 중인 서버 |
+| 코드 플레인의 심볼, 호출자, recall, 토큰 비용 | `make bench-code-intel`, `make bench-code-legs` | 실제 임베더 |
+| 배포 후 무엇이 바뀌었는가 | `loom deploy-delta` (교체 전후의 ledger와 ClickHouse 구문 형태) | `var/deployed.json` |
+
+> **경고:** 가짜 임베더로 측정한 recall 수치는 실제 검색 성능에 대해 아무것도 알려 주지 않습니다. 이 때문에 품질 게이트는 CI에서 제외되어 있습니다. 배포할 provider를 사용하는 서버에서 실행하고, 임베더를 바꾼 뒤에는 기준선을 다시 잡으세요.
+
+느린 요청 하나를 분석할 때는 설정을 건드리기 전에 `Server-Timing` 헤더(`app` 대 `ch`)와 `system.query_log` 행을 먼저 확인하세요([디버깅](https://github.com/ClickHouse/loom/blob/main/docs/guides/debugging.md)). 배포 전체의 연산별 비용은 `log_comment`에 대한 쿼리 하나로 구할 수 있습니다.
+
+```sql
+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;
+```
+
+교체 직후의 벤치마크 트래픽은 비어 있는 캐시를 읽습니다. 배포의 지연 시간을 이전 빌드와 비교하려면 잠시 기다리세요.
+
+
+
+## 랭킹과 임계값
+
+`memory.search`는 첫 단계 후보 풀의 순위를 매긴 뒤 랭킹 항목과 게이트를 적용합니다
+([검색과 랭킹](https://github.com/ClickHouse/loom/blob/main/docs/concepts/retrieval-and-ranking.md)). 대부분의 항목은 배포 단위로 설정할 수 있고 요청 단위로 덮어쓸 수 있으므로, 변경 사항을 먼저 한 호출자에게만 A/B 테스트할 수 있습니다.
+
+| 조정 항목 | 설정 (요청 필드) | 트레이드오프 |
+| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| 유사도 게이트 | `LOOM_ADAPTIVE_THRESHOLDS` (기본값 on) | On: 부팅 시 임베더 자체의 코사인 분포에서 게이트를 도출합니다. Off: 아래의 스칼라 게이트를 직접 관리해야 합니다. |
+| 스칼라 게이트 (대체) | `LOOM_MEMORY_SEARCH_MIN_SIMILARITY`, `LOOM_MEMORY_SEARCH_ABSTAIN_THRESHOLD`, `LOOM_MEMORY_SEARCH_HYDE_FALLBACK_THRESHOLD`, `LOOM_MEMORY_SEARCH_QUERY_REWRITE_THRESHOLD` | `text-embedding-3-small`에 맞춰 조정되어 있으며, 가짜 임베더, 프로브 실패, 적응형 기능이 꺼진 경우에 사용됩니다. |
+| 하한 미만 결과 | `LOOM_MEMORY_SEARCH_FLOOR_MODE` (`floor_mode`) | `readmit`은 `top_k`를 채우고 `below_floor`로 태그하며, `ids_only`는 본문이 빈 항목으로 채우고, `drop`은 더 적게 반환합니다. |
+| 후보 풀 | `LOOM_MEMORY_SEARCH_POOL_MULTIPLIER_STANDARD`, `_RERANK`, `_DEEP`, 상한은 `LOOM_MEMORY_SEARCH_MAX_POOL_TOP_K` | 풀이 넓을수록 재현율과 리랭크 입력이 늘어나는 대신, 읽는 벡터 행과 리랭크 토큰 비용이 듭니다. |
+| 리랭크 생략 | `LOOM_LLM_RERANK_SKIP_ABOVE` (적응형 게이트에 프로브가 없을 때의 대체값) | 최상위 벡터 결과가 이미 충분히 강하면 리랭크 호출을 건너뜁니다. |
+| 대체 캐스케이드 | `LOOM_MEMORY_SEARCH_FALLBACK_MAX_ROUNDS`, `_MAX_WALL_MS`, `_MAX_LLM_CALLS`, `_MAX_VECTOR_QUERIES` | 약한 첫 패스가 쓸 수 있는 재시도(쿼리 재작성, HyDE)의 한도를 정합니다. |
+| 강화 | `LOOM_MEMORY_SEARCH_REINFORCEMENT_WEIGHT` (`reinforcement_weight`), `_HALF_LIFE_DAYS` | 회상과 긍정적 결과가 행의 순위를 얼마나 끌어올릴지 정하며, 0이면 비활성화됩니다. 관련도보다 낮은 값으로 제한됩니다. |
+| 출처 | `LOOM_MEMORY_SEARCH_TRUST_WEIGHT` (기본값 0) | 검증된 출처를 선호하는 제한된 항목입니다. |
+| 최신성 | `LOOM_MEMORY_SEARCH_RECENCY_POOL_WEIGHT` (`recency_pool_weight`) | 최신성 의도가 있는 쿼리에서 풀을 최근 행 쪽으로 다시 정렬하며, 0이면 꺼집니다. |
+| 코드 형태 쿼리의 어휘 레그 | `rrf_adaptive_lexical` (요청), `LOOM_MEMORY_RRF_CODE_SHAPE_LO` / `_HI` | RRF에서 경로나 코드 형태의 쿼리에 대해 어휘 레그의 가중치를 낮춥니다. |
+| 기본 모드 | `LOOM_MEMORY_SEARCH_DEFAULT_MODE` (`search_mode`) | 호출자가 모드나 레시피를 지정하지 않았을 때 사용됩니다. |
+| 키당 중복 | `LOOM_MEMORY_SEARCH_PER_KEY_CAP` | 하나의 키가 한 페이지에 기여할 수 있는 행 수입니다. |
+
+> **경고:** 한 임베더에 맞춰 조정한 임계값은 다음 임베더에서는 맞지 않습니다.
+> `LOOM_ADAPTIVE_THRESHOLDS=false`이거나 가짜 임베더를 사용하는 경우, 임베더를 바꿀 때마다
+> 벤치마크(`make bench-quick`, `make bench-quality-gate`)를 다시 실행하세요.
+> `calibration.get`은 네임스페이스에 적용 중인 게이트를 어떤 티어가 만들었는지 보여 줍니다.
+
+
+
+## 벡터 읽기
+
+벡터 컬럼은 `Array(BFloat16)`입니다. `enable_quantized_codec`을 켤 수 있는 환경에서는 마이그레이터가 코덱을 적용한 상태로 컬럼을 생성합니다 ([ClickHouse](../architecture/clickhouse.md#gated-clickhouse-settings)).
+
+| 조정 항목 | 설정 | 트레이드오프 |
+| -------------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 코드 우선 스캔 | `LOOM_VECTOR_SEARCH_QUANTIZED_CODES` (기본값: 켜짐), `LOOM_MEMORY_SEARCH_FACT_CODES_FIRST` (`auto`) | 양자화된 코드를 먼저 읽은 다음 전체 정밀도로 다시 점수를 계산합니다. `auto`는 `memory_embeddings`에 패치 파트가 있는 동안 이 기능을 끕니다. 이 경우 재점수 계산이 건너뛰어지기 때문입니다. |
+| 코드 오버페치 | `LOOM_VECTOR_SEARCH_QUANTIZED_FETCH_MULTIPLIER`, `LOOM_MEMORY_SEARCH_FACT_CODES_FETCH_MULTIPLIER` | 재점수 계산 전에 코드 거리 기준으로 남겨 두는 행 수입니다. 값이 낮을수록 비용은 줄지만 상위 결과가 바뀌는 경우가 더 잦아집니다. |
+| 팩트 구문당 스레드 | `LOOM_MEMORY_SEARCH_FACT_LEG_MAX_THREADS` (0 = 고정 안 함) | 스레드를 고정하면 구문당 CPU와 최대 메모리 사용량이 제한되지만, 지연 시간이 다소 늘어납니다. |
+| 대량 쓰기의 피어 읽기 | `LOOM_MEMORY_BULK_PEER_READ` (기본값 `batched`, `per_fact`) | `per_fact`는 `memory.set`처럼 대량 쓰기의 각 팩트에 대한 충돌 피어와 값 업데이트 피어를 코드 우선으로 읽습니다. 배치 피어 구문이 `MEMORY_LIMIT_EXCEEDED`로 실패하고(서버 로그의 `batched conflict candidates failed`) 팩트별 폴백도 실패하면 해당 항목이 검사 없이 기록되는 대규모 네임스페이스에 사용합니다. 거리가 같은 경우 피어가 달라질 수 있습니다. |
+
+기존 테이블에 코덱이나 레이아웃을 적용하려면 `scripts/ops/vector_codec_rebuild.py`(트윈 테이블, 일관성 및 재현율 게이트, `EXCHANGE`. [단계](https://github.com/ClickHouse/loom/blob/main/docs/operations/deployment.md#recommended-clickhouse-settings))를 사용하세요. 마이그레이션에서 `ALTER`를 사용해서는 안 됩니다.
+
+
+
+## ClickHouse 연결과 데드라인
+
+| 조절 항목 | 설정 | 트레이드오프 |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 풀 크기 | `LOOM_CH_POOL_MAXSIZE` (기본값: 프로세스당 64) | 예상되는 요청 동시성에 워커 수를 더하고, 배치 insert가 대기하는 동안 점유하는 연결 수까지 더해 크기를 정합니다. 드라이버의 기본값은 대량 쓰기에서 고갈됩니다. |
+| 배치 insert | `LOOM_CH_BATCHED_INSERTS` (기본값: 켜짐), `LOOM_CH_BATCHED_INSERT_WAIT_MIN_MS` (10), `LOOM_CH_BATCHED_INSERT_WAIT_MAX_MS` (50), `LOOM_CH_BATCHED_INSERT_BACKGROUND_WAIT_MAX_MS` (200) | 동시에 들어온 insert는 하나의 파트를 공유하며, 각각 최대 윈도우 길이만큼의 지연이 생깁니다. 단독 insert는 최소 시간만큼 대기합니다. 대기 중인 insert는 각각 풀 연결을 하나씩 점유하므로 쓰기 빈도에 따라 풀이 커집니다 ([배치 insert](../architecture/clickhouse.md#batched-inserts)). |
+| 풀 대기 | `LOOM_CH_POOL_WAIT_MS` (기본값: 500) | 이 시간을 넘으면 요청은 큐에 쌓이지 않고 503 `OVERLOADED`로 즉시 실패합니다. 0이면 제한이 없습니다. |
+| Keep-alive | `LOOM_CH_KEEPALIVE_TIMEOUT` (기본값: 5초) | 로드 밸런서의 유휴 종료 시간보다 짧아야 Loom이 풀의 연결을 먼저 닫습니다. |
+| 구문 데드라인 | `LOOM_CH_TIMEOUT_READ_S`, `LOOM_CH_TIMEOUT_WRITE_S`, `LOOM_CH_TIMEOUT_DDL_S` | `max_execution_time`으로 적용되며, 풀 슬롯을 해제하는 클라이언트 측 제한으로도 적용됩니다. 0이면 해당 클래스에는 제한이 없습니다. |
+| 트래픽 클래스별 우선순위 | `LOOM_CH_SETTINGS_BY_TRAFFIC_CLASS` (JSON) | 클래스(`production`, `interactive`, `bench`, `background`)별 `priority`와 `max_threads`를 지정하여, 벤치와 워커가 프로덕션 읽기에 양보하도록 합니다. |
+| Read-your-writes | `LOOM_CH_READ_YOUR_WRITES`, `LOOM_CH_READ_YOUR_WRITES_WINDOW_S` | 쓰기 이후의 읽기가 순차적 일관성을 갖습니다. 복제 서비스에서는 비용이 들고, 단일 노드에서는 아무 영향이 없습니다. |
+| 작업 예산 | `LOOM_LATENCY_BUDGET_MULTIPLIER` | 모든 op의 `budget_p99_ms`를 배율로 조정합니다. ClickHouse까지 WAN 구간이 있으면 약 20이 필요합니다. 예산은 `budget.violated` 이벤트를 발생시킬 뿐 요청을 끊지는 않습니다. |
+
+웹 처리 용량은 컨테이너당 `LOOM_WEB_WORKERS`에 컨테이너 수를 곱한 값입니다. 속도 제한기는 `loom.instances`에서 확인한 활성 레플리카 수로 제한값을 나누며, 그 수는 `LOOM_REPLICA_COUNT`보다 작아지지 않습니다 ([레플리카](https://github.com/ClickHouse/loom/blob/main/docs/operations/replicas.md#rate-limits)).
+
+
+
+## 프로바이더
+
+| 조절 항목 | 설정 | 트레이드오프 |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 쿼리 임베딩 제한 | `LOOM_MEMORY_SEARCH_EMBED_BOUND_S`, `LOOM_MEMORY_SEARCH_EMBED_BOUND_RETRIES` | 쿼리 임베딩의 시도당 제한 시간입니다. 재시도 후에도 실패하면 검색은 503 `EMBED_TIMEOUT`으로 응답합니다. |
+| 쿼리 철자 | `LOOM_MEMORY_SEARCH_QUERY_SPELLING_MAX_WORDS` | 이 단어 수 이하의 쿼리는 임베딩과 나란히 네임스페이스를 한 번 읽어, 소문자 단어를 코퍼스의 철자로 임베딩합니다. 40k 행 네임스페이스 기준 100–300 ms가 걸리며 1분간 재사용됩니다. `0` = 끔. |
+| 쿼리 임베딩 캐시 | `LOOM_EMBEDDING_CACHE_SIZE`, `LOOM_EMBEDDING_CACHE_TTL_S`, `LOOM_EMBEDDING_CACHE_SHARED`, `LOOM_EMBEDDING_CACHE_SHARED_MAX_CHARS` | 공유 `loom.embedding_cache` 앞단에 프로세스별 LRU를 둡니다. 반복되는 쿼리는 프로바이더 호출을 건너뜁니다. |
+| 클래스별 LLM 응답 캐시 | `LOOM_LLM_POLICY_BY_TRAFFIC_CLASS` (JSON) | LLM 응답을 캐시하며(`bench`는 기본값으로 켜짐), 특정 클래스가 강력한 티어나 중간 티어를 사용하지 못하게 막을 수 있습니다. |
+| 폴백 모델 | `LOOM_LLM_FALLBACK_MODEL` | 재시도 후에도 기본 모델을 사용할 수 없을 때 op를 실패시키는 대신 이 모델이 응답합니다. |
+| 지출 한도 | `LOOM_DEFAULT_DAILY_COST_CAP_USD` (네임스페이스별 `daily_cost_cap_usd`) | 한도를 넘으면 LLM 기반 워커는 해당 네임스페이스를 건너뛰고 `memory.ask`는 `budget_capped`로 응답을 보류합니다. 일반 읽기와 쓰기는 계속됩니다. |
+
+
+
+### 임베더 선택
+
+| 임베더 (`LOOM_EMBEDDING_MODEL`) | 트레이드오프 |
+| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
+| `text-embedding-3-large`, `gemini-embedding-001` | Loom의 3072차원 기본값입니다. 품질과 비용은 여전히 사용자의 데이터로 측정해야 합니다. |
+| `text-embedding-3-small` | 더 좁은 1536차원 벡터 옵션입니다. 차원을 바꾸려면 다시 임베딩해야 합니다. |
+| `local`, `local:bge-small`, `local:bge-base`, `local:minilm` | 프로세스 내에서 CPU로 임베딩하며 프로바이더 호출이나 키가 필요 없습니다. 품질을 낮추는 대신 지연 시간과 비용을 줄입니다. |
+| `fake-ngram-3072` | 표준 차원에서 문자 n-gram을 사용하며 테스트와 연동 확인용입니다. 재현율 수치는 의미가 없습니다. |
+
+임베더를 바꾸면 벡터 공간이 바뀝니다. `LOOM_EMBEDDING_DIM`을 그에 맞게 설정하고 `loom reembed`를 실행한 뒤, 적응형 임계값을 켜 두었다면 부팅 프로브가 다시 보정하도록 두세요. 전후로 `make bench-quick`을 실행하세요. 추출 프롬프트가 맞춰져 있는 `LOOM_LLM_MODEL`도 마찬가지입니다.
+
+
+
+## 워커와 배치
+
+모든 워커에는 `*_ENABLED` 스위치와 `*_INTERVAL_SECONDS` 주기가 있으며, 많은 워커에는 아무것도 찾지 못한 패스 이후에 대기하는 `*_IDLE_INTERVAL_SECONDS`도 있습니다
+([워커 레퍼런스](https://github.com/ClickHouse/loom/blob/main/docs/reference/workers.md)). 간격을 짧게 하면 백그라운드 작업의 지연은 줄어들지만 스캔이 늘어납니다. 유휴 간격은 빈 큐의 비용을 낮게 유지합니다.
+
+| 워커 | 조정 항목 |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `embedding_worker` | `LOOM_EMBEDDING_WORKER_INTERVAL_SECONDS`, `_IDLE_INTERVAL_SECONDS`; `LOOM_EMBEDDING_WORKER_ORPHAN_FULL_SCAN_SECONDS` / `_ORPHAN_RECENT_SECONDS`는 고아 항목 anti-join의 범위를 제한합니다. |
+| `extraction_queue` | `LOOM_EXTRACTION_QUEUE_INTERVAL_SECONDS`, `_MAX_BATCHES_PER_PASS`, `_NAMESPACE_CONCURRENCY`, `_LEASE_SECONDS`; `LOOM_EXTRACTION_DEFER_AGENTS`는 나열된 에이전트의 `set_from_messages`를 미루어 추출이 끝나기 전에 요청이 반환되도록 합니다。 |
+| `memory_expiry_sweep` | `LOOM_MEMORY_EXPIRY_SWEEP_BATCH_SIZE`. |
+| `task_lease_sweep` | `LOOM_TASK_LEASE_SWEEP_INTERVAL_SECONDS`, `_IDLE_INTERVAL_SECONDS`. |
+
+워커는 `background` 트래픽 클래스에서 실행되므로 `LOOM_CH_SETTINGS_BY_TRAFFIC_CLASS`로 ClickHouse 우선순위와 스레드 수도 제한할 수 있습니다. 워커 프로세스는 정확히 하나만 실행하십시오. LLM 기반 워커를 하나 더 실행하면 스캔과 비용이 두 배가 됩니다. 코드 플레인의 수집 워커와 컴파일러 티어 워커에는 별도의 조정 항목이 있습니다([코드 인덱스 운영](https://github.com/ClickHouse/loom/blob/main/docs/operations/code-index-operations.md)).
+
+
+
+## 클라이언트 측 조절 방법
+
+가장 큰 효과 중 일부는 요청 자체에서 나옵니다.
+
+- 더 적은 본문 요청하기: `memory.search`의 `bodies`와 `body_budget_tokens`, `context.pack`과 `code.search`의 `token_budget`.
+- 단계마다 검색하는 대신 작업당 한 번만 컨텍스트 로드하기(`context.pack`).
+- 호출마다 `retrieval_budget`을 사용해 더 저렴하거나 더 깊은 검색 프로필 선택하기.
+- 멱등성 있는 op는 `Idempotency-Key` 헤더와 함께 재시도하기(SDK가 헤더를 생성합니다). 재전송하면 op를 다시 실행하지 않고 저장된 응답을 반환합니다.
+
+
+
+## 관련 문서
+
+- [장애 및 복구](../architecture/failure-and-recovery.md): 용량과 확장 대상
+- [모니터링](https://github.com/ClickHouse/loom/blob/main/docs/operations/monitoring.md)
+- [벤치마크 실행](https://github.com/ClickHouse/loom/blob/main/docs/benchmarks/running.md)
+- [디버깅](https://github.com/ClickHouse/loom/blob/main/docs/guides/debugging.md)
diff --git a/i18n/.pending/ko/docs/operations/backup-and-recovery.md b/i18n/.pending/ko/docs/operations/backup-and-recovery.md
new file mode 100644
index 0000000000..90febbce93
--- /dev/null
+++ b/i18n/.pending/ko/docs/operations/backup-and-recovery.md
@@ -0,0 +1,267 @@
+
+> 이 페이지는 [영어 원문](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`) | 예 | 원장을 다시 접어(refold) 복구할 수 있는 31일을 넘어 SLO 이력을 보관 |
+| `dev/backup_loom.py` 이식 가능한 덤프 | 모든 Loom 테이블 (아래 참조) | 테이블 단위, 테이블 간에는 아님 | 배포, 조직 또는 네임스페이스 이전 (원본이 버킷에 있는 경우: [아래](#the-portable-dump)), 콜드 복사본 |
+| `namespace.snapshot` | 하나의 네임스페이스의 큐레이션된 메모리, 타입, 권한, 감사 로그 말미 | 한 번의 호출 | API를 통한 네임스페이스 복사 또는 동결 |
+
+
+
+## 이식 가능한 덤프
+
+`dev/backup_loom.py`는 테이블마다 `JSONEachRow` 파일 하나를 쓰고, 이어서 `manifest.json`을 씁니다. 매니페스트에는 원본 데이터베이스와, 테이블별로 파일, 행 수, 바이트 크기, SHA-256, `CREATE` 문(또는 덤프를 중단시킨 오류)이 담깁니다. 종료 코드 1은 테이블 하나가 실패했다는 뜻이고(`complete: false`), 종료 코드 2는 인자가 잘못되었거나 ClickHouse 대상이 없거나 출력 디렉터리에 이미 백업이 있다는 뜻입니다.
+
+이 도구는 `system.tables`에서 읽은 데이터베이스의 모든 MergeTree 계열 테이블을 덤프합니다. 마이그레이션 러너의 `_` 접두사 테이블, `.inner` 테이블, KeeperMap 리스(데이터가 아니라 실시간 조정 정보), 그리고 `loom migrate`가 만드는 뷰는 제외합니다. 매니페스트의 `backup_version`은 3입니다. `--org`는 `org` 컬럼이 있는 모든 테이블을 필터링하고, 컬럼이 없는 테이블(`idempotency`, `signing_keys` 등)은 건너뜁니다. 이런 테이블에는 모든 org의 행이 들어 있습니다.
+
+`dev/restore_loom.py`는 모든 파일을 매니페스트와 대조해 검증하고(크기, 행 수, SHA-256), 계획을 출력합니다. 그다음 기록된 `CREATE` 문으로 대상 데이터베이스와 없는 테이블을 만들고, 각 파일을 해당 테이블의 스테이징 복사본에 로드한 뒤 스테이징된 파트를 테이블에 attach합니다. attach는 materialized view를 실행하지 않으므로, 복원된 행이 백업이 함께 복원하는 테이블에 다시 복사되지 않습니다(그렇지 않으면 `memory_versions`에 모든 버전이 두 번 들어갑니다). 뷰는 라이브 데이터베이스에 대한 쓰기에서는 계속 동작합니다. `loom migrate`가 준비한 데이터베이스(뷰가 있음)나 임시 데이터베이스(기록된 DDL로 테이블 생성)로 복원하십시오. 코드화된 벡터 테이블(기록된 `CREATE`에 `Quantized(`가 있음)이 들어 있는 백업은, 대상의 코덱 설정을 읽을 수 없거나 `enable_quantized_codec`을 켤 수 없는 경우 `--dry-run`을 포함해 아무것도 쓰기 전에 거부됩니다. 켤 수 있는 경우에도 `allow_suspicious_codecs`를 켤 수 없으면 해당 테이블은 `Quantized` 뒤의 일반 코덱을 잃습니다
+([제한된 설정](../architecture/clickhouse.md#gated-clickhouse-settings)). insert는 `optimize_on_insert = 0`으로 실행되므로, `ReplacingMergeTree` 키가 중복된 행을 포함해 덤프된 모든 행이 그대로 들어가고, 테이블은 자체 머지에서 이를 합칩니다.
+각 테이블은 attach 전에 `… attaching
`을, attach 후에 `✓`를 출력합니다. 실행이 중간에 끊기면 마지막 줄이 그 시점에 처리 중이던 테이블을 알려 줍니다. `--into-nonempty`로 다시 실행하기 전에 해당 테이블의 행 수를 확인하십시오. 그대로 다시 실행하면 그 테이블에 행이 한 번 더 추가됩니다.
+
+매니페스트에는 insert로 실행되는 각 materialized view의 소스 테이블과 대상 테이블이 기록됩니다. attach는 뷰를 실행하지 않으므로, 복원은 뷰의 한쪽 끝만 포함하는 선택을 거부합니다. `memory_versions`(및 `memory_code_link_queue`) 없이 `memory`만 복원하면 `memory.history`, `memory.redact`, `namespace.rollback`이 복원된 버전을 보지 못하게 되고, `code_chunks` 없이 `code_term_freq`만 복원하면 코드를 다시 수집할 때 그 테이블이 다시 채워집니다. `documents`와 `document_blobs`를 잇는 뷰는 없지만, 복원은 한쪽만 선택하는 것도 거부합니다. 원본이 없는 문서는 모든 다운로드에 410으로 응답하고, 문서가 없는 원본은 원본 정리 작업이 삭제하는 대상입니다. 두 도구 모두 `documents`를 다른 어떤 테이블보다 먼저 처리하므로, `--into-live`로 워커가 실행 중이어도 정리 작업이 그 원본을 가리키는 문서보다 먼저 복원된 원본 행을 보는 일은 없습니다(버킷의 객체는 아래를 참고하십시오). 양쪽 끝을 모두 선택하거나, 대상에 이미 그 행이 있다면 `--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` 행이 들어오지 않은 객체를 버킷 순회가 삭제하기 때문입니다.
+
+버저닝된 버킷은 삭제된 모든 객체를 noncurrent 버전으로 보관하고, 복제는 기본적으로 삭제를 복제하지 않습니다. 따라서 지워지거나 정리된 원본은 수명 주기 규칙(`NoncurrentVersionExpiration`, 복제본의 만료 포함)이 제거할 때까지 버킷(또는 그 복제본)에 남습니다. 이 규칙의 기간이, 행에 대해 ClickHouse 백업의 보존 기간이 하는 역할처럼, 지워진 원본을 여전히 복원할 수 있는 기간입니다.
+
+덤프에는 이런 행의 원본 바이트가 들어 있지 않으므로 옮길 수 없습니다. 다른 배포로 복원된 행은 여전히 원본 버킷을 가리키고, 지우기는 버킷과 접두사 밖이라며 이를 거부하며, 원본의 행이 사라지면 원본의 정리 작업이 그 객체를 삭제합니다. 또한 원본의 버킷과 접두사를 가리키도록 설정된 대상은 대상 카탈로그가 가리키지 않는 원본의 모든 객체를 정리해 버립니다. 문서를 대상에 다시 업로드해서 옮기거나, 원본을 중지한 상태에서 배포 전체를 옮기십시오.
+
+스테이징 복사본은 해당 테이블의 엔진을 그대로 반복합니다. 단, `Replicated`가 아닌 데이터베이스에 있는 복제 엔진은 같은 매개변수의 로컬 형태가 됩니다(복사본이 테이블의 Keeper 경로를 다시 차지하는 일을 막기 위해서입니다). 이후 attach가 파트를 복제합니다.
+복원이 만드는 복제 테이블은 백업 자체의 데이터베이스에서만, 그리고 그 경로로 복제하는 것이 더 이상 없을 때에만 기록된 Keeper 경로를 유지합니다(라이브 복제본이 남아 있으면 거부합니다). 다른 데이터베이스에서는 독립적인 경로를 받습니다. 서버의 `default_replica_path` 아래 새 UUID를 쓰거나, Replicated 데이터베이스에서는 그 데이터베이스 자체의 경로를 씁니다. 그 기본값에 필요한 매크로가 서버에 없으면 거부합니다.
+각 실행은 스테이징 테이블 이름을 `_restore__
`로 정하고 실행 ID를 가장 먼저 출력하며, 각 실행은 자신의 테이블만 삭제합니다. 한 데이터베이스로의 복원(예: org 두 개)은 한 번에 하나씩 실행됩니다. 실행은 `default._loom_restore_lock_`를 점유하고(다른 실행의 점유를 최대 5분 기다립니다), 대상을 다시 확인한 뒤, 이전 실행이 남긴 상태에 아래의 거부 규칙을 적용합니다. 그래서 같은 범위를 두 번째로 복원하면 첫 번째 행에 합쳐질 행을 attach하는 대신 거부합니다. 점유는 `default`의 테이블이므로 자체 관리 클러스터에서는 같은 서버를 거치는 실행끼리만 순서가 정해집니다. 모든 복원을 한 서버로 향하게 하십시오. 비정상 종료한 실행은 스테이징 테이블과 점유를 남깁니다. 그 실행의 프로세스가 남아 있지 않다면 `restore_loom.py --database --drop-staging `로 삭제하십시오.
+insert 단계 전에는 아무것도 쓰지 않으며, `--dry-run`은 계획까지만 보여 주고 멈춥니다. 다음은 거부됩니다.
+
+- `--into-live` 없이 라이브 데이터베이스(`loom` 또는 서버 설정이 지정한 데이터베이스)로 복원하는 경우
+- `--into-nonempty` 없이, 백업 범위에서 이미 행이 있는 테이블로 복원하는 경우. insert는 행을 추가하므로 일반 MergeTree 테이블(`audit_log`, `agent_events`)에는 모든 행이 두 번 들어갑니다.
+
+두 도구 모두 서버와 같은 방식으로 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`는 라이브 데이터베이스를 임시 디렉터리에 덤프하고 매니페스트를 행 수 스냅샷과 대조합니다. `--full-restore`를 주면 임시 데이터베이스 `_drill`로 복원하고, 모든 테이블의 행 수를 비교한 뒤, 종료할 때 임시 데이터베이스를 삭제합니다. 같은 키의 행을 합치는 테이블(`ReplacingMergeTree`, `AggregatingMergeTree` 등)은 attach 직후 임시 데이터베이스에서 머지될 수 있습니다. 머지가 실행된 뒤라면 행이 더 적어도 경고이고, 그렇지 않으면 실패입니다. 이 스크립트는 라이브 데이터베이스를 읽기만 합니다. 드릴은 일정에 따라 실행하십시오.
+
+덤프는 테이블 단위이며 테이블 간 스냅샷이 아닙니다. 클러스터 간에 데이터를 옮기는 용도로 사용하고, 재해 복구에는 사용하지 마십시오.
+
+
+
+## 복원 후 감사 로그 검증
+
+`python dev/verify_audit_chain.py [--org X] [--ts-since YYYY-MM-DD] [--json]`은 모든 `audit_log` 행의 콘텐츠 해시를 다시 계산하며, 불일치가 있으면 1로, 검증을 수행하지 못했을 때(잘못된 인수, 대상 없음, 쿼리 실패)는 2로, 그 외에는 0으로 종료합니다(행이 없으면 통과로 처리합니다). 불일치 보고서는 해당 행을 파티션, 타임스탬프, 요청 ID로 식별하며, 행의 actor, subject, 네임스페이스는 절대 표시하지 않습니다. `audit_verifier` 워커는 동일한 행별 검사를 일정에 따라 실행합니다. 이 검사는 행 간 해시 체인이 아니라 행별 변조 탐지입니다. 매시간 생성되는 체크포인트는 별도로 체인으로 연결됩니다([감사](https://github.com/ClickHouse/loom/blob/main/docs/features/observability/audit.md)).
+
+
+
+## 네임스페이스 내부의 변경 되돌리기
+
+이 operation들은 ClickHouse 복원 없이 잘못된 쓰기, 오작동하는 에이전트, 잘못된 import를 되돌립니다. 각 operation은 하나의 네임스페이스에 한정됩니다. `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` | tombstone 처리된 키 하나를 되살립니다 |
+| `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` | 모든 메모리 head(또는 `memory_keys`)를 `as_of` 시점의 버전으로 되돌립니다. 이전 버전을 새 head로 복구하고, 그 이후에 생성된 키는 tombstone 처리합니다. 기본은 dry run입니다(`dry_run=false`로 적용). 호출당 최대 `max_keys`개까지 처리하며(`truncated`는 다시 호출해야 할 때를 알려 줍니다) |
+
+Postgres authority에서는 복원 시, 삭제(erasure)로 대상에서 제거된 메모리 중 [삭제 증거](https://github.com/ClickHouse/loom/blob/main/docs/architecture/storage-authority.md)가 남아 있는 것은 제외하고 `counts.erased_skipped`에 집계합니다. 이 증거는 삭제가 해당 메모리를 제거한 네임스페이스만 다룹니다. 따라서 삭제 이전의 스냅샷을 다른 곳에 복원하면 삭제된 메모리가 되살아납니다. 이런 복원 후에는 같은 삭제(그 scope)를 다시 실행하세요.
+
+`namespace.rollback`과 `memory.history`는 `loom.memory_versions`를 읽습니다. 이것은 `loom.memory`에 대한 모든 insert를 기록하는 append-only 미러입니다(병합 시 대체된 버전은 `loom.memory` 자체에서 제거됩니다). 롤백은 다음과 같이 동작합니다.
+
+- 네임스페이스의 이력보다 오래되었거나 미래인 `as_of`는 거부합니다.
+- 하드 삭제된 키는 건너뜁니다(`skipped_no_head`).
+- 복구된 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에 있으며([권위 저장소](https://github.com/ClickHouse/loom/blob/main/docs/architecture/storage-authority.md)), 배포 하나에 백업할 저장소는 Postgres와 ClickHouse 두 개입니다.
+
+| 저장소 | 단독으로 보유하는 것 | RPO | 백업 방식 |
+| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| Postgres | 모든 메모리 헤드와 리비전, 지식 헤드, 수집 작업, 데이터셋 카탈로그, 멱등성 응답 | 동기식 스탠바이로 장애 조치(failover)해도 확인된 쓰기는 0; 특정 시점 복구(point-in-time restore)는 그 시점 이후의 데이터를 잃음 | 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)에 설명된 대로 백업을 선택하십시오. 정리 패스가 한 번 실행된 뒤에는 `010_revision_delivered_at.sql`을 포함한 빌드로 3단계의 `loom reconcile`을 실행하고, 4단계에서도 그 빌드로 배포를 시작하십시오(롤링 업그레이드 [규칙 43](https://github.com/ClickHouse/loom/blob/main/docs/architecture/rolling-upgrades.md#the-rules)). 그다음 진행합니다.
+
+1. 배포의 모든 서버와 워커를 중지합니다.
+2. 백업에서 저장소를 복구하고, 백업 자체의 메타데이터에서 백업 시각을 기록해 둡니다(ClickHouse는 `BACKUP`의 시작 시각, Postgres는 복구 목표 시점).
+3. `loom reconcile --restored clickhouse --point