From 91fe47160235957bc46b2215afbe412346e2a9b5 Mon Sep 17 00:00:00 2001 From: zlareb1 Date: Tue, 17 Nov 2026 23:15:18 +0000 Subject: [PATCH 01/22] Release 1.3.0 Align published version pins and set the coding-agent plugins minimum server version for the new code lessons calls. Signed-off-by: zlareb1 --- .claude-plugin/plugin.json | 2 +- .cursor-plugin/plugin.json | 2 +- deploy/helm/loom/Chart.yaml | 4 ++-- frontend/package-lock.json | 4 ++-- frontend/package.json | 2 +- gemini-extension.json | 2 +- integrations/claude-code-plugin/.claude-plugin/plugin.json | 2 +- integrations/claude-code-plugin/lib/server-version.mjs | 2 +- integrations/codex-plugin/.codex-plugin/plugin.json | 2 +- integrations/codex-plugin/lib/server-version.mjs | 2 +- plugin.json | 2 +- pyproject.toml | 2 +- sdk/python/loom/_version.py | 2 +- sdk/python/pyproject.toml | 2 +- sdk/typescript/package-lock.json | 4 ++-- sdk/typescript/package.json | 2 +- sdk/typescript/src/version.ts | 2 +- server.json | 2 +- server/__init__.py | 2 +- skills/loom-code/SKILL.md | 2 +- skills/loom/SKILL.md | 2 +- uv.lock | 2 +- 22 files changed, 25 insertions(+), 25 deletions(-) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index f436e4b56e..3c3c7a7e12 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "loom-code-skill", - "version": "1.2.0", + "version": "1.3.0", "description": "Code search and code intelligence for repositories in a Loom code index (the loom-code Agent Skill: code.* first, then read only that), and the loom Agent Skill: how an agent uses Loom. Skills only, no hooks.", "author": { "name": "ClickHouse" }, "homepage": "https://clickhouse.github.io/loom/", diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index 98182b16c0..a5e7e69544 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "clickhouse-loom", - "version": "1.2.0", + "version": "1.3.0", "displayName": "ClickHouse Loom", "description": "Shared long-term memory, document search and a code index for Cursor from a self-hosted ClickHouse Loom server, over MCP, with the loom and loom-code skills that say when to recall, save and ask the code index.", "author": { "name": "ClickHouse" }, diff --git a/deploy/helm/loom/Chart.yaml b/deploy/helm/loom/Chart.yaml index 283ed54f8f..c7f2145d64 100644 --- a/deploy/helm/loom/Chart.yaml +++ b/deploy/helm/loom/Chart.yaml @@ -2,8 +2,8 @@ apiVersion: v2 name: loom description: Loom on Kubernetes, N identical replicas over one ClickHouse service. type: application -version: 0.2.0 -appVersion: "1.2.0" +version: 0.3.0 +appVersion: "1.3.0" kubeVersion: ">=1.27.0-0" home: https://clickhouse.github.io/loom/ sources: diff --git a/frontend/package-lock.json b/frontend/package-lock.json index f6e55e9f7f..7c573890b7 100644 --- a/frontend/package-lock.json +++ b/frontend/package-lock.json @@ -1,12 +1,12 @@ { "name": "loom-dashboard", - "version": "1.2.0", + "version": "1.3.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "loom-dashboard", - "version": "1.2.0", + "version": "1.3.0", "dependencies": { "@clickhouse/click-ui": "0.13.0", "@fontsource-variable/inconsolata": "5.3.0", diff --git a/frontend/package.json b/frontend/package.json index 64c1ccbc2c..4aa71111eb 100644 --- a/frontend/package.json +++ b/frontend/package.json @@ -1,6 +1,6 @@ { "name": "loom-dashboard", - "version": "1.2.0", + "version": "1.3.0", "private": true, "type": "module", "engines": { diff --git a/gemini-extension.json b/gemini-extension.json index 7ff4b06b44..423f2fd3fc 100644 --- a/gemini-extension.json +++ b/gemini-extension.json @@ -1,6 +1,6 @@ { "name": "clickhouse-loom", - "version": "1.2.0", + "version": "1.3.0", "description": "Shared long-term memory, document search and a code index for Gemini CLI from a self-hosted ClickHouse Loom server, over MCP.", "mcpServers": { "loom": { diff --git a/integrations/claude-code-plugin/.claude-plugin/plugin.json b/integrations/claude-code-plugin/.claude-plugin/plugin.json index e0269c2845..21bc23c36b 100644 --- a/integrations/claude-code-plugin/.claude-plugin/plugin.json +++ b/integrations/claude-code-plugin/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "loom", "displayName": "ClickHouse Loom", - "version": "1.2.23", + "version": "1.2.27", "description": "Shared long-term memory and code intelligence for Claude Code, self-hosted on ClickHouse. MCP tools to save and recall decisions, preferences and corrections across sessions and teammates; lifecycle hooks that capture each session with no model call; a code index that answers where-is, who-calls and blast-radius questions with line-accurate units instead of whole-file reads.", "author": { "name": "ClickHouse" diff --git a/integrations/claude-code-plugin/lib/server-version.mjs b/integrations/claude-code-plugin/lib/server-version.mjs index 6e88276dd8..1e9a26f576 100644 --- a/integrations/claude-code-plugin/lib/server-version.mjs +++ b/integrations/claude-code-plugin/lib/server-version.mjs @@ -12,7 +12,7 @@ const MANIFESTS = ["../.claude-plugin/plugin.json", "../.codex-plugin/plugin.jso // The oldest Loom server the hooks support. lib/ is synced, so both plugins // carry the same minimum; a release raises it (docs/development/release-process.md). -export const MIN_SERVER_VERSION = "1.0.0"; +export const MIN_SERVER_VERSION = "1.3.0"; const SEMVER = /^(\d+)\.(\d+)\.(\d+)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/; diff --git a/integrations/codex-plugin/.codex-plugin/plugin.json b/integrations/codex-plugin/.codex-plugin/plugin.json index e5631cdf30..96ab0f380b 100644 --- a/integrations/codex-plugin/.codex-plugin/plugin.json +++ b/integrations/codex-plugin/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "loom", - "version": "1.2.23", + "version": "1.2.27", "description": "Shared long-term memory and code intelligence for Codex, self-hosted on ClickHouse. MCP tools to save and recall decisions, preferences and corrections across sessions and teammates; lifecycle hooks that capture each session with no model call; a code index that answers where-is, who-calls and blast-radius questions with line-accurate units instead of whole-file reads.", "author": { "name": "ClickHouse" diff --git a/integrations/codex-plugin/lib/server-version.mjs b/integrations/codex-plugin/lib/server-version.mjs index 6e88276dd8..1e9a26f576 100644 --- a/integrations/codex-plugin/lib/server-version.mjs +++ b/integrations/codex-plugin/lib/server-version.mjs @@ -12,7 +12,7 @@ const MANIFESTS = ["../.claude-plugin/plugin.json", "../.codex-plugin/plugin.jso // The oldest Loom server the hooks support. lib/ is synced, so both plugins // carry the same minimum; a release raises it (docs/development/release-process.md). -export const MIN_SERVER_VERSION = "1.0.0"; +export const MIN_SERVER_VERSION = "1.3.0"; const SEMVER = /^(\d+)\.(\d+)\.(\d+)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/; diff --git a/plugin.json b/plugin.json index 47fd3099bc..0d25fe54e4 100644 --- a/plugin.json +++ b/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", "name": "clickhouse-loom", - "version": "1.2.0", + "version": "1.3.0", "description": "Shared long-term memory, document search and a code index from a self-hosted ClickHouse Loom server, over MCP, with the loom and loom-code skills that say when to recall, save and ask the code index. Experimental: checked with Copilot CLI 1.0.112.", "author": { "name": "ClickHouse", "url": "https://github.com/ClickHouse" }, "homepage": "https://clickhouse.github.io/loom/features/integrations/mcp-clients/#other-editors-and-agents", diff --git a/pyproject.toml b/pyproject.toml index 4d2465b82c..9a6188d49a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "clickhouse-loom-server" -version = "1.2.0" +version = "1.3.0" description = "Loom server (control plane). Shared-production agent memory + knowledge plane on ClickHouse. Distributed as a Docker image (ghcr.io/clickhouse/loom) — `pip install` is for local dev / Docker-image build only; do NOT run the server from pip in production." requires-python = ">=3.12" license = { text = "Apache-2.0" } diff --git a/sdk/python/loom/_version.py b/sdk/python/loom/_version.py index 518e23df89..2cb0748f59 100644 --- a/sdk/python/loom/_version.py +++ b/sdk/python/loom/_version.py @@ -1,4 +1,4 @@ """The package version. `pyproject.toml` carries the same string, and the transport sends it in `User-Agent` and `X-Loom-SDK`.""" -__version__ = "1.2.0" +__version__ = "1.3.0" diff --git a/sdk/python/pyproject.toml b/sdk/python/pyproject.toml index eafbda22d2..71c32e0da6 100644 --- a/sdk/python/pyproject.toml +++ b/sdk/python/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "clickhouse-loom" -version = "1.2.0" +version = "1.3.0" description = "Python SDK for ClickHouse Loom, a self-hosted server that gives AI agents shared long-term memory, document search and a code index." requires-python = ">=3.11" license = "Apache-2.0" diff --git a/sdk/typescript/package-lock.json b/sdk/typescript/package-lock.json index b01bfc6816..78a49fe836 100644 --- a/sdk/typescript/package-lock.json +++ b/sdk/typescript/package-lock.json @@ -1,12 +1,12 @@ { "name": "@clickhouse/loom", - "version": "1.2.0", + "version": "1.3.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@clickhouse/loom", - "version": "1.2.0", + "version": "1.3.0", "license": "Apache-2.0", "devDependencies": { "@anthropic-ai/sdk": "1.8.0", diff --git a/sdk/typescript/package.json b/sdk/typescript/package.json index 3d896c4e76..f24ab044e9 100644 --- a/sdk/typescript/package.json +++ b/sdk/typescript/package.json @@ -1,6 +1,6 @@ { "name": "@clickhouse/loom", - "version": "1.2.0", + "version": "1.3.0", "description": "TypeScript SDK for ClickHouse Loom, a self-hosted server that gives AI agents shared long-term memory, document search and a code index. Typed over every wire operation the server declares, with retries, rate-limit pacing, idempotency keys and an Agent identity binding.", "type": "module", "sideEffects": false, diff --git a/sdk/typescript/src/version.ts b/sdk/typescript/src/version.ts index b327f2f2a6..4ae4204ee0 100644 --- a/sdk/typescript/src/version.ts +++ b/sdk/typescript/src/version.ts @@ -4,5 +4,5 @@ * transport sends it in `User-Agent` and `X-Loom-SDK`. */ export const SDK_NAME = "loom-ts"; -export const SDK_VERSION = "1.2.0"; +export const SDK_VERSION = "1.3.0"; export const SDK_IDENT = `${SDK_NAME}/${SDK_VERSION}`; diff --git a/server.json b/server.json index ff65512e32..b38d1b97b8 100644 --- a/server.json +++ b/server.json @@ -3,7 +3,7 @@ "name": "io.github.ClickHouse/loom", "title": "ClickHouse Loom", "description": "Shared long-term memory, document search and a code index for AI agents, self-hosted on ClickHouse.", - "version": "1.2.0", + "version": "1.3.0", "websiteUrl": "https://clickhouse.github.io/loom/", "repository": { "url": "https://github.com/ClickHouse/loom", diff --git a/server/__init__.py b/server/__init__.py index 0d24d2aa11..6e40f5feda 100644 --- a/server/__init__.py +++ b/server/__init__.py @@ -1,3 +1,3 @@ """Loom server: the control plane over ClickHouse.""" -__version__ = "1.2.0" +__version__ = "1.3.0" diff --git a/skills/loom-code/SKILL.md b/skills/loom-code/SKILL.md index 2f2b4d1591..d14e731250 100644 --- a/skills/loom-code/SKILL.md +++ b/skills/loom-code/SKILL.md @@ -2,7 +2,7 @@ name: loom-code license: Apache-2.0 metadata: - version: "1.2.0" + version: "1.3.0" description: "Route-then-read code intelligence for a loom-indexed repository. WHEN: the repo is indexed by loom (LOOM_BASE_URL set, or a `.loom` marker), and you would otherwise read whole files, grep the tree, or guess who calls a function. Use loom's code.* tools to find the exact unit first, then read only that. FOR SINGLE OPERATIONS: call the code.* MCP tool directly." --- diff --git a/skills/loom/SKILL.md b/skills/loom/SKILL.md index 96ea47fc73..4249cd3ada 100644 --- a/skills/loom/SKILL.md +++ b/skills/loom/SKILL.md @@ -2,7 +2,7 @@ name: loom license: Apache-2.0 metadata: - version: "1.2.0" + version: "1.3.0" description: "How an agent uses Loom: memory, documents, working state, runs and code intelligence that persist across sessions and are shared with other agents. WHEN: you have a Loom server (LOOM_BASE_URL, an SDK `Agent`, `loom_*` MCP tools) and you start a task, learn a durable fact, hold a document or a large blob, need to resume, hand work to another agent, or answer from what an earlier session knew. Covers MCP, the Python and TypeScript SDKs and plain HTTP." --- diff --git a/uv.lock b/uv.lock index fceb873c26..c5aced7164 100644 --- a/uv.lock +++ b/uv.lock @@ -778,7 +778,7 @@ wheels = [ [[package]] name = "clickhouse-loom-server" -version = "1.2.0" +version = "1.3.0" source = { editable = "." } dependencies = [ { name = "aiohttp" }, From 7086580582cda6e07ca70a05fd188711541df860 Mon Sep 17 00:00:00 2001 From: Mohammad Lareb Zafar Date: Wed, 18 Nov 2026 15:42:13 +0530 Subject: [PATCH 02/22] Prepare release 1.3.0 with plugin 1.2.30 (#809) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Draft definitions from query history and search gaps (#768) * Draft metric definitions from query history and search gaps Keep generated drafts private until an administrator publishes their content. Register opt-in read-only query-history sources and bound generation by privacy thresholds and namespace caps. Signed-off-by: zlareb1 * Allow an isolated name for mixed-version checks Use the requested container name for both creation and cleanup. A failed creation leaves any existing container untouched. Signed-off-by: zlareb1 * Pin query-history setting defaults Signed-off-by: zlareb1 * Query-history settings distinguish cadence from deadlines Signed-off-by: zlareb1 * Describe definition draft operations and review reads Signed-off-by: zlareb1 * Document retained definition heads during draft recovery Signed-off-by: zlareb1 * Show complete definition drafts before publication Reviewers can inspect the full body and evidence before promoting a definition. Describe private draft destinations and authenticated approval attribution. Signed-off-by: zlareb1 * Keep definition support counts in memory lineage Private definition drafts retain a supporting-account count without storing identities. Both exact lineage paths use that count while ordinary and assistant-rule candidates keep their existing accounting. Signed-off-by: zlareb1 * Fence private definition decisions against erasure Private queue writes retain their proposal time and share a bounded writer lease with namespace deletion. Check erasure under that lease and retain uncertain sends so a delayed decision or model completion cannot restore erased evidence. Signed-off-by: zlareb1 * Fence private publication and source registry erasure Signed-off-by: zlareb1 * Expect retained writer fences in namespace erasure traces Signed-off-by: zlareb1 * Allocate query-history migration after mirrored erasure Signed-off-by: zlareb1 * Require private draft cleanup before older readers serve Signed-off-by: zlareb1 * Keep gap input out of stored draft evidence Signed-off-by: zlareb1 * Regenerate statement shapes on the composed schema Signed-off-by: zlareb1 * Keep definition review tests within their type contracts Signed-off-by: zlareb1 * Complete definition drafting contracts and Library composition Signed-off-by: zlareb1 * Curation rollout names the existing absence precondition Signed-off-by: zlareb1 --------- Signed-off-by: zlareb1 * Entity filters refuse oversized alias expansion (#800) * Entity filters refuse oversized alias expansion Bound raw inputs and distinct canonical aliases before constructing the search filter. Preserve supported filter order and propagate size refusals through optional paths. Signed-off-by: zlareb1 * The SDK error inventory includes oversized vector input The new server refusal uses the existing SDK validation error. Include its code in the exhaustive inventory so the registry assertion continues to cover every server error. Signed-off-by: zlareb1 * The alias ceiling states its fixed input contract The effective entity-filter ceiling is a documented input boundary rather than an operator resource setting. Explain that distinction beside the constant without changing the value or the settings checks. Signed-off-by: zlareb1 * Analyzer corpus tracks the bounded distinct entity query Signed-off-by: zlareb1 --------- Signed-off-by: zlareb1 * Checked document reads enforce current source permissions (#799) * Personal-agent tokens name their reader through an explicit signed claim Signed-off-by: zlareb1 * Resolve mirrored readers from verified account evidence Signed-off-by: zlareb1 * Stage source-bound permission checks for mirror reads Signed-off-by: zlareb1 * Keep mirror candidates out of shared lexical statistics Signed-off-by: zlareb1 * Fill mirrored candidate pools after current permission checks Signed-off-by: zlareb1 * Hydrate only exact chunks that retain current mirrored access Signed-off-by: zlareb1 * Rank complete admitted source copies before projecting public addresses Signed-off-by: zlareb1 * Refresh all mirrored search passes before selecting a route Signed-off-by: zlareb1 * Collect ordinary search legs separately from fusion Signed-off-by: zlareb1 * Use checked source pools in knowledge search Signed-off-by: zlareb1 * Read source documents at exact admitted identities Signed-off-by: zlareb1 * Check source access on document gets and keep mining ordinary Signed-off-by: zlareb1 * Read admitted document chunks including embedding stubs Signed-off-by: zlareb1 * Read checked source sections in document outlines Signed-off-by: zlareb1 * Refresh source and reader evidence before checked reads Signed-off-by: zlareb1 * Read checked source originals through guarded streams Signed-off-by: zlareb1 * Read checked list fields and counts from one admitted copy Signed-off-by: zlareb1 * Group list metadata before admission and public pagination Signed-off-by: zlareb1 * List admitted document families before filtering and pagination Signed-off-by: zlareb1 * Get and download the newest admitted mirror copy Signed-off-by: zlareb1 * Invalidate synthesis proofs after a document identity or permission change Signed-off-by: zlareb1 * Assemble synthesis from checked whole document copies Keep ordinary chunks and document precedence. Pin one mirrored copy per address and discard all mirrored chunks when a checked read fails. Signed-off-by: zlareb1 * Recheck document access around synthesis calls Validate every mirrored copy before and after each model call and before returning an answer. Discard generated output after permission loss, drain concurrent calls, and report only documents the synthesis read. Signed-off-by: zlareb1 * Read admitted source titles without document diagnostics Signed-off-by: zlareb1 * Include checked source titles in document inspections Signed-off-by: zlareb1 * Retain metadata proofs for live search chunks Signed-off-by: zlareb1 * Renew checked search proofs across provider work Signed-off-by: zlareb1 * Retain permission deadlines for composed document reads Signed-off-by: zlareb1 * Renew composed document reads before rendering their results Signed-off-by: zlareb1 * Keep checked repository listings out of shared caches Signed-off-by: zlareb1 * Renew repository search permissions after both search legs Signed-off-by: zlareb1 * Renew document access before unified search assembly Signed-off-by: zlareb1 * Keep checked stack knowledge through final assembly Prepare mirror access before stack reads and retain the checked selection through rendering. Rebuild the complete ordinary suffix when its evidence expires. Signed-off-by: zlareb1 * Prepare checked reads before context-pack providers Signed-off-by: zlareb1 * Prepare checked ask requests before provider work Retain source proofs through answer assembly and rebuild the ordinary result after permission loss. Drain owned provider work before publishing the replacement answer. Signed-off-by: zlareb1 * The analyzer corpus covers checked source reads Drive metadata discovery, admitted chunk and document reads through the existing statement recorder, and regenerate group-membership erasure shapes. Signed-off-by: zlareb1 * Run checked source regressions under their required CI profiles Keep signed HTTP cases in authenticated steps under both storage authorities, include the native Postgres cases, and close partial native acquisitions on every exit. Signed-off-by: zlareb1 * Preserve checked-read contracts across query and provider boundaries Keep materialized views in place, analyze explicitly formatted SQL without appending another format, and retain the caller stage around checked providers. Align delegation, context-pack and auth-data controls with their actual paths. Signed-off-by: zlareb1 * Keep checked-read migrations after query-history storage Preserve the merged query-history schema, erasure fences and generated references while assigning the unmerged reader-evidence migrations their own numbers. Signed-off-by: zlareb1 * Keep the generated checked-read schema and journal controls current Regenerate the schema from an empty database in the composed migration order. Remove the RENAME regression with its unused parser now that the views change query in place. Signed-off-by: zlareb1 --------- Signed-off-by: zlareb1 * docs: connect the autonomous agent verification workflow (#802) Signed-off-by: zlareb1 * docs: clarify fake-provider extraction output (#804) Signed-off-by: zlareb1 * Postgres summary downgrade test publishes its starting vectors (#805) A new write answers at its commit. Wait for the initial vectors before deleting a source so the downgrade can copy them and settle its document within the delete. Signed-off-by: zlareb1 * Expose a private cell probe in the Helm chart (#806) Signed-off-by: zlareb1 * General search includes readable tracker issues and pull requests (#773) * Draft metric definitions from query history and search gaps Keep generated drafts private until an administrator publishes their content. Register opt-in read-only query-history sources and bound generation by privacy thresholds and namespace caps. Signed-off-by: zlareb1 * Allow an isolated name for mixed-version checks Use the requested container name for both creation and cleanup. A failed creation leaves any existing container untouched. Signed-off-by: zlareb1 * Pin query-history setting defaults Signed-off-by: zlareb1 * Query-history settings distinguish cadence from deadlines Signed-off-by: zlareb1 * Describe definition draft operations and review reads Signed-off-by: zlareb1 * Document retained definition heads during draft recovery Signed-off-by: zlareb1 * Show complete definition drafts before publication Reviewers can inspect the full body and evidence before promoting a definition. Describe private draft destinations and authenticated approval attribution. Signed-off-by: zlareb1 * Keep definition support counts in memory lineage Private definition drafts retain a supporting-account count without storing identities. Both exact lineage paths use that count while ordinary and assistant-rule candidates keep their existing accounting. Signed-off-by: zlareb1 * Fence private definition decisions against erasure Private queue writes retain their proposal time and share a bounded writer lease with namespace deletion. Check erasure under that lease and retain uncertain sends so a delayed decision or model completion cannot restore erased evidence. Signed-off-by: zlareb1 * Fence private publication and source registry erasure Signed-off-by: zlareb1 * Expect retained writer fences in namespace erasure traces Signed-off-by: zlareb1 * Allocate query-history migration after mirrored erasure Signed-off-by: zlareb1 * Require private draft cleanup before older readers serve Signed-off-by: zlareb1 * Keep gap input out of stored draft evidence Signed-off-by: zlareb1 * Regenerate statement shapes on the composed schema Signed-off-by: zlareb1 * Keep definition review tests within their type contracts Signed-off-by: zlareb1 * Complete definition drafting contracts and Library composition Signed-off-by: zlareb1 * Search readable issues and pull requests with loom_search Resolve authorized tracker targets before narrowing capture consent and searching the other planes. Keep duplicate verdicts for scoped defect reports and leave memory and knowledge ranking unchanged for general tracker matches. Signed-off-by: zlareb1 * Unified search descriptions include readable issues and pull requests Signed-off-by: zlareb1 * Refresh persisted tracker links before discovery Signed-off-by: zlareb1 * Describe tracker search results and tag scope Empty duplicate verdicts remain useful evidence, while tag filters apply to memory and knowledge rather than tracker matches. Signed-off-by: zlareb1 * Curation rollout names the existing absence precondition Signed-off-by: zlareb1 * Format the unified search argument table Signed-off-by: zlareb1 * Keep tracker search regression fixtures on the planned call path Signed-off-by: zlareb1 * Use the configured test target for tracker ASGI requests Signed-off-by: zlareb1 --------- Signed-off-by: zlareb1 * Release preparation uses plugin version 1.2.28 Give the minimum-server warning a version distinct from other pending plugin changes. Signed-off-by: zlareb1 * Local development documents the fake LLM's test output (#807) The deterministic fake client can synthesize facts. Match the development guide to that behavior. Signed-off-by: zlareb1 * Getting started distinguishes fake LLM output from meaningful results ### Changelog category (leave one): - Documentation (changelog entry is not required) ### Changelog entry (one or two sentences a user of Loom can read without the diff; the release pull request collects these into the release notes): Not required. ### Why The fake LLM can synthesize facts and return deterministic answer text for development and tests. The quickstart and first-agent guide distinguish that output from meaningful extraction and grounded answers, which need a configured real LLM. The troubleshooting row explains that an empty extraction can also be valid when there is nothing memorable to retain. ### Scope and risk The two guides describe existing provider behavior consistently in their introductions, provider table, session and ask explanations, and extraction troubleshooting. The quickstart table also receives formatter padding. Setup commands, conversation logging, expiry and permission guidance remain unchanged. The risk is confusing test output with meaningful results; both guides distinguish them. ### Compatibility, rollout and rollback - Wire: none. - Operator steps: none. - Rollback: reverting restores the inaccurate fake-output descriptions; no stored data or generated files are involved. ### Tests - Prettier 3.9.9 checks both changed Markdown files. - The prose checker passes for both files and this description. - A focused source comparison confirms the six related passages and table padding are the complete diff; headings, first sentences and links remain unchanged. - `git diff --check` passes. - Runtime tests were not run because this changes prose only. Full GitHub PR CI passes for this head. ### AI assistance in the code (leave one; writing this description with AI is fine): - AI-generated (an agent wrote most of the diff): Codex; checked against the fake extraction helper, client selection, SDK session flush and answer synthesis paths. - [x] I can explain every line of this diff and how it interacts with the rest of Loom. ### Checklist - [x] `make format-check`, `make lint`, `make typecheck` and `make test-unit` pass in GitHub CI; the integration suite also passes. Only the focused checks above ran locally. - [ ] Generated files are regenerated in this PR, not by hand: the SDK op tables, `docs/reference/configuration.md` and the `docs/reference/` tables (`python scripts/codegen/docs_reference.py`), the reach manifest, `schemas/schema.sql` (`make schema-dump`) and the Codex plugin copies (`python3 scripts/codegen/agent_plugin_sync.py`). Not applicable: no generated source changed. - [ ] A new migration is additive and numbered after the latest on `main`; no merged migration is edited. Not applicable. - [ ] A behaviour change to any file a plugin ships (`hooks/`, `lib/`, `bin/`, `skills/`, `.mcp.json`, the Codex `plugin-defaults.json`) bumps both plugin manifests' version, and no other open PR uses that version. Not applicable. - [ ] The frontend builds (`npm --prefix frontend run build`) and its tests pass, if `frontend/` changed. Not applicable. - [x] Docs under `docs/` describe the system as it now is, and this description names any operator steps and wire changes. - [x] Repository text has no dates, people, host names, internal namespaces, ticket or decision numbers; the history goes in this description (`tests/unit/test_public_copy.py`). - [x] Commits are signed off (`git commit -s`), as CONTRIBUTING.md asks. * Marked document requests keep accounting behind their privacy boundary (#803) * Preserve marked request protections for dependency composition Signed-off-by: zlareb1 * Run marked event controls under both storage authorities Keep private database cleanup tied to an explicit UUID even when creation loses its reply. Classify the fixed required-publication cleanup ceiling without changing its bound. Signed-off-by: zlareb1 * Check marked durable folds and scoped SQL reads Signed-off-by: zlareb1 * Keep marked event migration after checked source reads Retain the query-history migration and its dependent schema while assigning the unmerged marked-event cutover a distinct journal number. Signed-off-by: zlareb1 * Regenerate marked-reader query shapes after dependency composition Signed-off-by: zlareb1 * Retain selected source proofs through response publication Renew the exact selected content after required accounting and awaited sends. Discard abandoned branches and unopened downloads, preserve derived metadata dependencies, and keep cancellation accounting. Probe the physical memory relation when its analysis policy is removed. Signed-off-by: zlareb1 * Type selected publication proofs explicitly The strict type checker needs the element type before extending the retained proof list. Runtime behavior is unchanged. Signed-off-by: zlareb1 * Keep marked event projections within the privacy boundary Retain permitted numeric work without copying document identifiers or error prose. Supply expired scope settings only while provisioning the signed analyst view, and keep existing regression controls aligned with their producers. Signed-off-by: zlareb1 * Format the event storage reference Signed-off-by: zlareb1 * Keep source proofs through metadata and outline publication Signed-off-by: zlareb1 * Keep response completion independent of expired publication proofs Renew access before headers and every byte-bearing body frame. Empty completion frames must finish after a Content-Length client has consumed the response. Give each integration test ownership of its offline client signer so in-process snapshots cannot stale the next test issuer. Preserve production key freshness and restore the exact prior snapshot on every exit. Signed-off-by: zlareb1 --------- Signed-off-by: zlareb1 * Entity summary reads reject oversized seed sets without partial fallback (#808) * Bound entity summary seeds and preserve typed refusals Signed-off-by: zlareb1 * Optional read docstrings distinguish typed input refusals Signed-off-by: zlareb1 * Wrap the composed search failure contract Signed-off-by: zlareb1 * Document the fixed summary seed input bound Signed-off-by: zlareb1 * Tracker integration restores the test client's keyring view The in-process server lifespan loads a timestamped keyring snapshot. Restore the original client snapshot at fixture teardown so later tests do not inherit a stale server view. Production freshness checks remain unchanged. Signed-off-by: zlareb1 * Search cleanup preserves cancellation inside handled caller exceptions Pass the search body exception through the owned async context rather than reading ambient exception state. A successful search awaited from an exception handler still propagates cancellation after joining its children. Signed-off-by: zlareb1 --------- Signed-off-by: zlareb1 * docs: show metadata-first code retrieval in the cost guide (#818) Signed-off-by: zlareb1 * Memory-linked code guide shows an indexed change (#816) * Memory-linked code guide shows an indexed change Show how a saved lesson reads before and after a committed expression change and link the existing regression for the state transitions. Signed-off-by: zlareb1 * Change walkthrough uses trunk and checks capped lesson cards The link worker maintains trunk commits, while symbol cards can omit a changed lesson. Name trunk and point to the saved memory links when the card leaves it out. Signed-off-by: zlareb1 --------- Signed-off-by: zlareb1 * test: pin audit privacy fixture target IDs (#821) Signed-off-by: zlareb1 * Investigation guide uses unified search for document retrieval (#815) Signed-off-by: zlareb1 * Governed-page tests wait for a served definition before mutation (#817) An approval refresh can withhold a parked hit within its bounded wait. Keep empty no-match pages in the existing preparation deadline so the case reaches its edit or demotion only after proving the governed hit. Signed-off-by: zlareb1 * OIDC tests allocate Loom's port after the identity provider binds (#812) Selecting both ports before either listener starts can assign the same unreserved port twice. Keep the identity provider listening while choosing Loom's port so the allocator excludes it. Signed-off-by: zlareb1 * Documentation publishes and maintains five translation locales (#764) ### Changelog category (leave one): - Improvement ### Changelog entry The documentation site publishes available machine translations in Simplified Chinese, Japanese, Korean, Brazilian Portuguese and Spanish alongside canonical English. Translation maintenance discovers tracked documentation changes and prepares bounded, validated updates after English changes merge. ### Why Generated translations need published routes and a maintenance path that follows additions, edits, renames and deletions. The site and updater share route mapping, preserve English fallbacks, and expose stale translations without treating pending coverage as current. ### Scope and risk This change combines localized site rendering, the translation lifecycle workflow and 34 reviewed generated updates. Language links, canonical URLs, alternate-language metadata, sitemaps, Markdown copies and indexing submissions use the available pages. Translation batches preserve verified pending output and repair surviving links before removing obsolete generated pages. The role-bearing runner executes trusted main code. Hosted validation checks the exact generated branch before merge. The cumulative reservation ledger and batch limits constrain provider calls; a missing allowance defers generation. No server operations, storage schema or tenant authorization changes are included. ### Compatibility, rollout and rollback - Wire: none. English remains canonical and the default. All five translation locales are selected by default. - Operator steps: site publication uses the existing Pages workflow. Automatic generation requires restricted runner labels, an initialized budget ledger and an explicitly approved cumulative allowance, as documented in `CONTRIBUTING.md`. No AWS credential is stored in the repository. The allowance defaults to zero. - Coverage: the existing translated documentation pages are published. Missing pages and retained stale documentation translations remain pending; this change does not include a full translation backfill. - Rollback: reverting restores the English site and earlier updater. No database migration or running-service change is required. ### Tests - `make format`, `make format-check`, `make lint` and `make typecheck`: pass. - Combined translation lifecycle and localized-site tests: 669 passed; the workflow branch-filter correction adds eight passing focused checks. - README finalization regression: ten passed after reproducing three failures; eleven existing security and lifecycle checks also passed. - Documentation links, public copy and agent instructions: 451 passed. - Strict documentation build and rendered checks across all five locales: pass. - Heavy local browser and full-suite runs are omitted; full suites run in CI. - Full unit suite, offline tests and required integration checks: required in CI. - No provider calls were made for integration or validation. The generated updates retain their original machine output and review evidence. ### AI assistance in the code (leave one; writing this description with AI is fine): - AI-generated: Codex integrated the reviewed components and checked their combined diff and validation results. - [ ] I can explain every line of this diff and how it interacts with the rest of Loom. ### Checklist - [ ] Local formatting, lint, types and focused tests pass; the full unit suite, offline tests and all other required checks pass in CI. - [x] Generated files are regenerated rather than edited by hand; the translation bytes match their reviewed source outputs. - [x] No migration, server wire field, plugin payload or frontend change is included. - [x] Documentation describes the configured workflow and its remaining coverage and operator requirements. - [x] Commits are signed off. Signed-off-by: zlareb1 * Postgres projection tests publish their starting rows (#790) Related: https://github.com/ClickHouse/loom/pull/764 ### Changelog category (leave one): - CI Fix or Improvement ### Why Postgres projection tests depend on initial memory rows and vectors being published before they replace or delete authority heads. A new-key `memory.set` can answer at its Postgres commit, before publication. If a later change overtakes the first publication, the tests can time out on an obsolete delivery or assert against rows that never reached ClickHouse. The vector-retirement, history-retention, reconciliation, summary-retirement, live-claim redaction and cleared-payload tests wait for initial publication before changing those heads. The vector-retirement test also asserts that a live vector exists. The reconciliation, summary-retirement, live-claim redaction and cleared-payload tests retain their divergence counts and text-free vector tombstone assertions. ### Scope and risk Six integration tests, including the four existing vector-retirement write variants and both live/parked lease cases. The existing publication helper establishes each fixture's initial state. Final publication waits, vector retirement, zero targets, history horizons and redaction assertions remain intact. No timeout, retry, skip, worker setting or production behavior changes. ### Compatibility, rollout and rollback - Wire: none. - Operator steps: none. - Rollback: reverting removes the explicit initial publication preconditions. ### Tests - `ruff check tests/integration/test_pg_authority.py`: pass. - `ruff format --check tests/integration/test_pg_authority.py`: pass. - Python AST parsing of the changed file and `git diff --check`: pass. - Integration tests were not run locally. Full CI, including both Postgres authority jobs, must pass before merge. ### AI assistance in the code (leave one; writing this description with AI is fine): - AI-generated: Codex traced publication timing and added the publication preconditions and live-vector assertion. - [ ] I can explain every line of this diff and how it interacts with the rest of Loom. ### Checklist - [x] Focused formatting, lint and syntax checks pass. - [ ] Full CI and both Postgres authority jobs pass. - [x] All six tests retain their existing timeouts and final assertions. - [x] No generated file, schema, migration, wire field, plugin or frontend change is included. - [x] Commits are signed off. Signed-off-by: zlareb1 * Desktop browser launch survives installer terminal hangup (#822) Ignore HUP before forking the asynchronous Linux opener and restore the parent handler afterwards. The opener cannot establish its own signal handling before it is scheduled. Exercise inherited handling with a self-HUP before the existing exact-once URL assertion. Signed-off-by: zlareb1 * Named users have daily cost caps and inbox warnings (#777) * Draft metric definitions from query history and search gaps Keep generated drafts private until an administrator publishes their content. Register opt-in read-only query-history sources and bound generation by privacy thresholds and namespace caps. Signed-off-by: zlareb1 * Allow an isolated name for mixed-version checks Use the requested container name for both creation and cleanup. A failed creation leaves any existing container untouched. Signed-off-by: zlareb1 * Pin query-history setting defaults Signed-off-by: zlareb1 * Query-history settings distinguish cadence from deadlines Signed-off-by: zlareb1 * Describe definition draft operations and review reads Signed-off-by: zlareb1 * Document retained definition heads during draft recovery Signed-off-by: zlareb1 * Show complete definition drafts before publication Reviewers can inspect the full body and evidence before promoting a definition. Describe private draft destinations and authenticated approval attribution. Signed-off-by: zlareb1 * Keep definition support counts in memory lineage Private definition drafts retain a supporting-account count without storing identities. Both exact lineage paths use that count while ordinary and assistant-rule candidates keep their existing accounting. Signed-off-by: zlareb1 * Fence private definition decisions against erasure Private queue writes retain their proposal time and share a bounded writer lease with namespace deletion. Check erasure under that lease and retain uncertain sends so a delayed decision or model completion cannot restore erased evidence. Signed-off-by: zlareb1 * Fence private publication and source registry erasure Signed-off-by: zlareb1 * Expect retained writer fences in namespace erasure traces Signed-off-by: zlareb1 * Allocate query-history migration after mirrored erasure Signed-off-by: zlareb1 * Require private draft cleanup before older readers serve Signed-off-by: zlareb1 * Keep gap input out of stored draft evidence Signed-off-by: zlareb1 * Regenerate statement shapes on the composed schema Signed-off-by: zlareb1 * Keep definition review tests within their type contracts Signed-off-by: zlareb1 * Complete definition drafting contracts and Library composition Signed-off-by: zlareb1 * Search readable issues and pull requests with loom_search Resolve authorized tracker targets before narrowing capture consent and searching the other planes. Keep duplicate verdicts for scoped defect reports and leave memory and knowledge ranking unchanged for general tracker matches. Signed-off-by: zlareb1 * Unified search descriptions include readable issues and pull requests Signed-off-by: zlareb1 * Refresh persisted tracker links before discovery Signed-off-by: zlareb1 * Describe tracker search results and tag scope Empty duplicate verdicts remain useful evidence, while tag filters apply to memory and knowledge rather than tracker matches. Signed-off-by: zlareb1 * Add named-user cost caps and inbox budget warnings Signed-off-by: zlareb1 * Include the user budget migration in the schema journal inventory Signed-off-by: zlareb1 * User budgets cover synthesis and scoped warning streams Signed-off-by: zlareb1 * Name budget source entry points and invariants Signed-off-by: zlareb1 * Define user-budget activation and rollback boundaries Older replicas neither preserve user policy nor protect private warnings. Activate after the fleet upgrade and settle and remove warning events before a maintenance rollback, then restore saved policy on upgrade. Signed-off-by: zlareb1 * Allocate user budgets after query-history registrations Signed-off-by: zlareb1 * Reuse the shared writer fence for budget warnings Signed-off-by: zlareb1 * Number the budget upgrade rule after mirror erasure Signed-off-by: zlareb1 * Curation rollout names the existing absence precondition Signed-off-by: zlareb1 * Format the unified search argument table Signed-off-by: zlareb1 * Keep tracker search regression fixtures on the planned call path Signed-off-by: zlareb1 * Use the configured test target for tracker ASGI requests Signed-off-by: zlareb1 * Regenerate schema for user cost budgets Signed-off-by: zlareb1 * Align user budget contracts with checked synthesis Carry warning identity columns through task event reads and register the warning pipeline. Preserve named-user budget assertions while updating checked-search fixtures and their explicit keyword contracts, and regenerate the SDK surface and statement catalog. Signed-off-by: zlareb1 * Regenerate schema and statement catalog for user budgets Signed-off-by: zlareb1 * Test marked namespace spend through the shared budget snapshot The native marked-spend check uses the same rolling spend read as budget status and admission, including when the namespace has no cost cap. Signed-off-by: zlareb1 * Bound leased sends by the received server clock Signed-off-by: zlareb1 * Withhold exact user spend from budget status and warnings Named-user cap verdicts and warning thresholds count all ledger spend. Status reveals exact user spend only to a platform admin without namespace role restrictions; user warnings always redact the amount for recipients. Signed-off-by: zlareb1 --------- Signed-off-by: zlareb1 * Translation requests stay bounded and preserve technical literals (#797) Related: https://github.com/ClickHouse/loom/pull/792 Related: https://github.com/ClickHouse/loom/pull/764 ### Changelog category (leave one): - Bug Fix (user-visible misbehavior in a release) ### Changelog entry Machine translation bounds documentation requests, preserves source-attested names and technical values, and verifies the assembled page before writing it. ### Why Splitting long pages only at second-level headings leaves some sections larger than one translation reply can hold. A truncated reply stops generation. The request planner now caps each source slice at 16 KiB while retaining paragraph, list-item, code, HTML and table-row boundaries. The cost estimate uses the same slices that translation sends. The assembled page is checked again for content invariants and table layout before it is written. An indivisible oversized unit is refused before a provider call. Indented code remains whole, including tables that site extensions render differently; an oversized ambiguous block is refused. Correct names and filenames can otherwise be rejected as untranslated English, while translated return-value strings can pass. Source context distinguishes protected spellings from ordinary descriptions. It checks preserved values in their original structural positions and keeps adjacent explanatory prose subject to translation checks. ### Scope and risk Shared Markdown tokens move into the request-splitting module so the verifier and planner use one lexer. Maintained Markdown token ranges identify list items and table rows; the assembled table check parses both the site dialect and CommonMark tables. Code source ranges mask literal tags before HTML analysis. Site cell text is measured after serialization and raw HTML restoration. An indentation scan also covers the site extension’s two-space ordered-list continuations, which differ from CommonMark’s marker-width indentation. Their container rules differ. This avoids a partial table grammar that missed quoted tables and raw HTML contexts. Parser versions and runtime requirements are pinned; provider packages retain their versions. The architecture page describes the planning and validation boundaries. Source bytes, page-wide anchors and order survive reconstruction. The workflow installs its isolated, hash-locked runtime before checking freshness. Provider, model, output-token limit, retry, concurrency, budget, runner and permission settings retain their values. Source-context checks use the same English page and source identity throughout retry, assembly and stored-page validation. Table context survives slices that begin after the header. Protection applies to attested name spans, repository file labels and declared technical values; capitalization, quotation marks and table position alone do not exempt English prose. The verifier rejects removed or changed protected spellings. A documented model default is tied to its source page, setting and default-value cell. Tracker contract type families are tied to their source page, ordered field group and Family cell, with tests against the implemented schema. Their literal spellings are preserved while ordinary headings, qualifiers and descriptions still require translation. Stored-page lifecycle validation uses the same source identity and both table parsers before staging, importing or activating output. The existing all-document inventory, README/subset safeguards, proof checks and HTML-tag counter remain in place. These checks do not certify semantic fidelity or current-source publication eligibility. A source-byte bound reduces oversized requests; it does not guarantee that every model response fits. Existing truncated-reply refusal remains in place. A Markdown unit larger than the bound needs an English-source edit before translation can proceed. ### Compatibility, rollout and rollback - Wire: none. - Operator steps: none. This source change does not alter running generation jobs. - Rollback: reverting restores the previous request planner and label checks. Generated output and budget history remain unchanged. ### Tests - Nine regression cases fail before the change, covering oversized sections, multibyte input, protected Markdown units, provider admission, usage accounting and assembled table validation. - Focused regressions cover two-space ordered-list continuations in plain text, quotes and admonitions, tab-indented lists, optional outer pipes, row loss, delimiters, single-column tables, nested containers, raw HTML and HTML elements spanning headings. Header and body cells cannot lose all text in CommonMark-only tables, including when empty inline markup remains in either dialect. Literal HTML in indented and nested fenced code stays protected. Translated cell text and valid pipe reflow are accepted in plain text, quotes, lists and admonitions. Existing section/assembly checks also pass. - Focused HTML token controls cover the shared lexer. A parsed workflow comparison checks that runtime installation precedes the first CLI call; generation remains conditional on stale work and all other workflow settings retain their values. - Three affected English inputs reconstruct exactly, with every source request at most 16 KiB. No provider was called for validation. - Focused source-context cases cover exact names and file labels, ordinary residual descriptions, escaped pipes, literal-value changes, headerless table slices, retry feedback, assembled-page refusal and stored-page checks. Model-default regressions reject wrong settings, columns, paths, mutations and moves, and preserve full table context for headerless slices. Existing cached responses are examined without provider calls; remaining genuine differences stay reported. - The related main composition passes 84 focused cases across lifecycle, README/subset/proof controls, stored metadata, bounded staging, tracker types and CI input guards. Stored-page regressions first reproduce eight source-context/table-layout failures; the corrected lifecycle rejects missing rows, extra cells and changed protected names. Existing cached tracker output passes the corrected type-family check without another provider call; the earlier untranslated phrase still rejects. - Full suites must pass in CI on this final head. The tokenizer and all-document lifecycle changes are merged. ### AI assistance in the code (leave one; writing this description with AI is fine): - AI-generated: Codex traced the oversized requests, implemented Markdown slicing and source-context checks, and checked focused regressions. - [ ] I can explain every line of this diff and how it interacts with the rest of Loom. ### Checklist - [x] Focused formatting, lint and regression checks pass. - [ ] Full CI passes on the final main-based head. - [ ] Fresh technical and content reviews have no findings. - [x] Provider settings, financial guards and active generation inputs are preserved. - [x] Commits are signed off. Signed-off-by: zlareb1 * Documentation navigation keeps the reader's language (#794) Related: https://github.com/ClickHouse/loom/pull/764 ### Changelog category (leave one): - Documentation ### Why Readers can choose an available language from every documentation page. When that page has no translation, the language link names an existing translated landing page. Native READMEs link to their available documentation. Translated pages keep available sidebar and footer destinations in the reader’s language. Missing translations carry an explicit English label. Language controls, search labels and translation-status notices use the page’s language. Videos use their translated fallback text for accessible labels. ### Scope and risk The site projects navigation per page without changing shared navigation objects. Equivalent-page metadata remains separate from landing-page choices. The README generator maintains its existing owned regions and reuses the configured site base and landing priority. Quickstart and other available owned pages provide native website links when translated indexes are absent. Shared interface copy participates in site indexing and README maintenance inputs. Video labels are derived during rendering while preserving media URLs, controls and other attributes. Retained obsolete landing pages keep their README links until the selected locale retires them; retirement repairs that locale's generated navigation in the same batch. The change covers English and the five configured translation languages. Translation coverage and search-tokenizer quality require separate validation. ### Compatibility, rollout and rollback - Wire: none. - Operator steps: none. - Rollback: reverting restores the prior navigation and generated README regions. ### Tests - Nine focused checks for navigation ownership, language choices, native stale notices and generated README destinations pass. - The supplied strict Material fixture covers 13 pages across all six languages, with native search labels, active navigation, English fallbacks, Markdown notices, metadata and sitemap checks. - Thirteen focused video-label and page-language checks pass, including English preservation, escaping and multiple-video cases. - Nine focused lifecycle cases pass, including landing removal, preferred-landing fallback, subset ownership, selected-page progress, deferred README activation, stale/conflicted output and proof preservation. Two new cases reproduce the failure before the fix and verify the site still serves an unselected retained landing. - Eight focused fallback and retirement cases pass, including quickstart-only and other-page landings, retained locale ownership, selected-page progress, the last native landing and unchanged site/indexing behavior. The two missing-link cases fail before the fallback change. - Nine focused README and retirement checks pass. Quoted filenames and Unicode paths fail before URL encoding and produce complete, encoded links after it. - Full suites run in CI and must pass on the public head before merge. Deployed routes remain a separate publication check. ### AI assistance in the code (leave one; writing this description with AI is fine): - AI-generated: Codex implemented navigation projection, native interface copy and accessible video labels. Independent technical and interface-copy review is required on the public head. - [ ] I can explain every line of this diff and how it interacts with the rest of Loom. ### Checklist - [x] Focused checks exercise the changed user paths. - [ ] Full CI passes on the public head. - [ ] Fresh technical and interface-copy reviews have no findings. - [x] Generated README regions come from the existing generator. - [x] Commits are signed off. Signed-off-by: zlareb1 * Session-content admission uses durable deployment protection (#819) * Guard automatic session operations with a durable deployment latch Signed-off-by: zlareb1 * Generate the deployment session latch schema Signed-off-by: zlareb1 * Session admission validates complete Keeper storage metadata ClickHouse engine_full includes each primary key. Match the actual storage clause while refusing wrong paths and keys, and classify automatic document-search fallbacks. Regenerate schema references and pin the new setting and error contracts. Signed-off-by: zlareb1 * Session admission preserves request context and attests positive writes Scope query tags through proof cleanup and reject positive writes on a backend that was not validated. Reuse strict Boolean claim validation and isolate the MCP refusal phase so both entry points remain within their size limits. Signed-off-by: zlareb1 * Admission heartbeat and lease checks follow real callbacks Assert repair precedes the holder read. Control only the lease test clocks and renewal wakes so healthy renewals cross the original expiry without assuming a prompt wall-clock schedule; keep the half-TTL cancellation policy unchanged. Signed-off-by: zlareb1 * Regenerate analyzer shapes for the composed latch schema Signed-off-by: zlareb1 --------- Signed-off-by: zlareb1 * Retain completed translation units across English edits (#824) Related: https://github.com/ClickHouse/loom/pull/797 ### Changelog category (leave one): - Improvement ### Changelog entry (one or two sentences a user of Loom can read without the diff; the release pull request collects these into the release notes): Add a pure translation reconciliation API that retains authenticated completed requests across English edits and plans affected or unfinished ranges within the request bound. ### Why Planning every request again from current English changes the cuts of completed work. A partial run also needs to distinguish completed replies from original units that have no completion. The reconciler takes a complete authenticated original-unit manifest, preserves whole completed payloads and exact separator ownership, and returns current scoped dispositions or explicit conflicts. Headerless table gaps use the existing bounded planner with their complete source context. Changed-input corrections carry bounded ASCII feedback in the canonical SYSTEM, without replaying an old-input assistant response. Empty feedback preserves the existing SYSTEM and initial message. ### Scope and risk This adds a pure planning API, contextual request splitting, initial-feedback construction and architecture documentation. The caller remains responsible for authenticating original plans, completion statuses, selected receipts and refusals. A metadata digest or missing cache file cannot establish that a completion is absent. The API does not resolve replies, admit provider calls or publish translations. Repeated or unsafe mappings return conflicts. Replacing a completed whole-page unit and assigning unproven cuts among several unmatched original units remain unsupported. Every resolved or generated unit needs current-context validation, followed by whole-page invariants and semantic/completeness review. The main risk is incorrect source-range or separator ownership; focused regressions check exact reconstruction and preserved completed payloads. ### Compatibility, rollout and rollback - Wire: no operation or field changes. The translation Python API gains reconciliation helpers, optional source context on `chunks.split`, and optional `initial_feedback` on `translate_text`. - Operator steps: none. Consumers opt into the pure API; this PR adds no CLI, generation loop, dependency or execution controls. Default model, provider settings and spending code are unchanged. - Rollback: reverting removes these APIs and their documentation. There are no migrations or stored-data changes to undo. ### Tests The focused Python run passed 66 cases: reconciliation, canonical initial feedback and three existing default splitter regressions. It covers partial completion, mixed empty/LF separators, headerless table tails, source insertions/deletions, ambiguous or unsafe ranges, refusal, fault coalescing, request bounds and rejection before provider calls. ```sh PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=. python -m pytest --noconftest -o addopts='' -q \ tests/unit/test_i18n_reconcile.py \ tests/unit/test_i18n_initial_feedback.py \ tests/unit/test_i18n_request_bounds.py::test_one_large_section_splits_at_complete_table_rows \ tests/unit/test_i18n_request_bounds.py::test_a_short_multibyte_page_still_obeys_the_byte_bound \ tests/unit/test_i18n_request_bounds.py::test_slices_keep_code_html_and_anchor_heading_pairs_together ``` Targeted Ruff and whitespace checks pass. The writing checker validates the architecture text and this description. Broad local suites were not run; full PR CI and independent review remain required before merge. No provider calls were made. ### AI assistance in the code (leave one; writing this description with AI is fine): - AI-generated: Codex wrote the implementation and tests, checked source-range and request-payload assertions, and ran the focused checks above. Maintainer review remains required. - [ ] I can explain every line of this diff and how it interacts with the rest of Loom. ### Checklist - [ ] `make format-check`, `make lint`, `make typecheck` and `make test-unit` pass; the integration suite passes if server behaviour changed. - [ ] Generated files are regenerated in this PR, not by hand: the SDK op tables, `docs/reference/configuration.md` and the `docs/reference/` tables (`python scripts/codegen/docs_reference.py`), the reach manifest, `schemas/schema.sql` (`make schema-dump`) and the Codex plugin copies (`python3 scripts/codegen/agent_plugin_sync.py`). Not applicable: no generated surfaces changed. - [ ] A new migration is additive and numbered after the latest on `main`; no merged migration is edited. Not applicable: no migrations changed. - [ ] A behaviour change to any file a plugin ships (`hooks/`, `lib/`, `bin/`, `skills/`, `.mcp.json`, the Codex `plugin-defaults.json`) bumps both plugin manifests' version, and no other open PR uses that version. Not applicable: no plugin files changed. - [ ] The frontend builds (`npm --prefix frontend run build`) and its tests pass, if `frontend/` changed. Not applicable: no frontend files changed. - [x] Docs under `docs/` describe the system as it now is, and this description names any operator steps and wire changes. - [x] Repository text has no dates, people, host names, internal namespaces, ticket or decision numbers; the history goes in this description (`tests/unit/test_public_copy.py`). - [x] Commits are signed off (`git commit -s`), as CONTRIBUTING.md asks. Signed-off-by: zlareb1 * Docker smoke checks code-linked memories over MCP ### Changelog category (leave one): - CI Fix or Improvement (changelog entry is not required) ### Changelog entry (one or two sentences a user of Loom can read without the diff; the release pull request collects these into the release notes): Not required. ### Why The Docker smoke verifies compiler indexes and restart persistence. Code-linked memory integration tests exercise handlers in process, so they do not check a packaged server returning a lesson's changed state over MCP after its source is reindexed. Extend the existing smoke with that round trip. ### Scope and risk The existing Python fixture saves a lesson over MCP, waits for the link worker to mark it fresh, commits an expression change, and waits for the ingest and link workers to report the new commit and changed link. The lifecycle also waits for the scheduled Python compiler worker to publish that commit. Restart verification reads the changed link again, then deletes that smoke memory and checks its absence. The installed environment template enables scheduled ingest. Before the first boot, the smoke explicitly sets `LOOM_CODE_INGEST_ENABLED=false` in its disposable environment so its initial seed and compiler checks finish before scheduled ingest starts. It then sets the same switch to `true` and recreates its existing server service. Scheduled compiler flags retain their existing installed values; this change does not disable them during the initial seed. Worker intervals, memory settling, product defaults, compiler checks and the 45-minute CI job timeout are unchanged. Each lifecycle invocation has one shared 1,020-second bound at the default worker intervals. Waiting for the normal Python compiler cadence can add about nine to ten minutes to CI; both architecture jobs must establish that the complete smoke fits its existing timeout. The status endpoint can return a cached repository head after the link has changed. The smoke polls until that endpoint also reports the exact edited commit, within the same lifecycle deadline. The other language fixtures retain their existing checks. A failed smoke still tears down its own Compose stack and volumes. The installed smoke configuration uses single-user mode, a local embedder and the fake LLM. These assertions check transport, indexing, link states and persistence; they do not measure model quality or authenticated-client behavior. ### Compatibility, rollout and rollback - Wire: none. - Operator steps: none. The ingest switch is set only in the disposable smoke environment. - Rollback: reverting removes the added smoke checks; no deployed data or schema changes are involved. ### Tests - Ruff 0.16.9 lint and format checks pass for both changed scripts. - The prose checker and `git diff --check` pass. - A focused extracted environment-updater check verifies the explicit false-to-true phase configuration and source ordering. Fifteen earlier tiny extracted-helper checks cover MCP response errors, saved-value and namespace checks, fresh and changed states, exact commit checks and source compilation. They do not start a server or run a native smoke. - Nine focused checks run the extracted status poller with inert MCP responses. The previous poller passes five and fails four; the corrected poller passes all nine. The checks cover transient cached heads, a permanently stale head reaching the existing deadline, and rejection of incorrect link commits, symbol paths and included lesson states. - The previous native amd64 run returned the fresh link, then failed when the status endpoint returned an older cached head immediately after the scheduled Python compiler applied the edit. This corrects the smoke observation; it does not increase timeouts or change the status cache. - No local server, database, Docker, browser or provider test ran. Full current-head PR CI passes, including both existing Docker Quickstart architecture jobs. The packaged checks pass the fresh link, committed source edit, exact changed commit, restart readback and exact-key deletion assertions. ### AI assistance in the code (leave one; writing this description with AI is fine): - AI-generated (an agent wrote most of the diff): Codex; checked against the existing smoke, worker configuration, MCP contract and code-link integration test. - [x] I can explain every line of this diff and how it interacts with the rest of Loom. ### Checklist - [x] `make format-check`, `make lint`, `make typecheck` and `make test-unit` pass in GitHub CI, including the integration and native image checks. Only the focused checks above ran locally. - [ ] Generated files are regenerated in this PR, not by hand: the SDK op tables, `docs/reference/configuration.md` and the `docs/reference/` tables (`python scripts/codegen/docs_reference.py`), the reach manifest, `schemas/schema.sql` (`make schema-dump`) and the Codex plugin copies (`python3 scripts/codegen/agent_plugin_sync.py`). Not applicable: no generated source changed. - [ ] A new migration is additive and numbered after the latest on `main`; no merged migration is edited. Not applicable. - [ ] A behaviour change to any file a plugin ships (`hooks/`, `lib/`, `bin/`, `skills/`, `.mcp.json`, the Codex `plugin-defaults.json`) bumps both plugin manifests' version, and no other open PR uses that version. Not applicable. - [ ] The frontend builds (`npm --prefix frontend run build`) and its tests pass, if `frontend/` changed. Not applicable. - [x] Docs under `docs/` describe the system as it now is, and this description names any operator steps and wire changes. No documentation source changed. - [x] Repository text has no dates, people, host names, internal namespaces, ticket or decision numbers; the history goes in this description (`tests/unit/test_public_copy.py`). - [x] Commits are signed off (`git commit -s`), as CONTRIBUTING.md asks. * Provider notifications request document source syncs (#784) * Draft metric definitions from query history and search gaps Keep generated drafts private until an administrator publishes their content. Register opt-in read-only query-history sources and bound generation by privacy thresholds and namespace caps. Signed-off-by: zlareb1 * Allow an isolated name for mixed-version checks Use the requested container name for both creation and cleanup. A failed creation leaves any existing container untouched. Signed-off-by: zlareb1 * Pin query-history setting defaults Signed-off-by: zlareb1 * Query-history settings distinguish cadence from deadlines Signed-off-by: zlareb1 * Describe definition draft operations and review reads Signed-off-by: zlareb1 * Document retained definition heads during draft recovery Signed-off-by: zlareb1 * Show complete definition drafts before publication Reviewers can inspect the full body and evidence before promoting a definition. Describe private draft destinations and authenticated approval attribution. Signed-off-by: zlareb1 * Keep definition support counts in memory lineage Private definition drafts retain a supporting-account count without storing identities. Both exact lineage paths use that count while ordinary and assistant-rule candidates keep their existing accounting. Signed-off-by: zlareb1 * Fence private definition decisions against erasure Private queue writes retain their proposal time and share a bounded writer lease with namespace deletion. Check erasure under that lease and retain uncertain sends so a delayed decision or model completion cannot restore erased evidence. Signed-off-by: zlareb1 * Fence private publication and source registry erasure Signed-off-by: zlareb1 * Expect retained writer fences in namespace erasure traces Signed-off-by: zlareb1 * Allocate query-history migration after mirrored erasure Signed-off-by: zlareb1 * Require private draft cleanup before older readers serve Signed-off-by: zlareb1 * Keep gap input out of stored draft evidence Signed-off-by: zlareb1 * Regenerate statement shapes on the composed schema Signed-off-by: zlareb1 * Keep definition review tests within their type contracts Signed-off-by: zlareb1 * Complete definition drafting contracts and Library composition Signed-off-by: zlareb1 * Search readable issues and pull requests with loom_search Resolve authorized tracker targets before narrowing capture consent and searching the other planes. Keep duplicate verdicts for scoped defect reports and leave memory and knowledge ranking unchanged for general tracker matches. Signed-off-by: zlareb1 * Unified search descriptions include readable issues and pull requests Signed-off-by: zlareb1 * Refresh persisted tracker links before discovery Signed-off-by: zlareb1 * Describe tracker search results and tag scope Empty duplicate verdicts remain useful evidence, while tag filters apply to memory and knowledge rather than tracker matches. Signed-off-by: zlareb1 * Add named-user cost caps and inbox budget warnings Signed-off-by: zlareb1 * Include the user budget migration in the schema journal inventory Signed-off-by: zlareb1 * User budgets cover synthesis and scoped warning streams Signed-off-by: zlareb1 * Name budget source entry points and invariants Signed-off-by: zlareb1 * Define user-budget activation and rollback boundaries Older replicas neither preserve user policy nor protect private warnings. Activate after the fleet upgrade and settle and remove warning events before a maintenance rollback, then restore saved policy on upgrade. Signed-off-by: zlareb1 * Allocate user budgets after query-history registrations Signed-off-by: zlareb1 * Reuse the shared writer fence for budget warnings Signed-off-by: zlareb1 * Number the budget upgrade rule after mirror erasure Signed-off-by: zlareb1 * Curation rollout names the existing absence precondition Signed-off-by: zlareb1 * Source push notifications request bounded document sync Bind provider hints to the current source generation, verify provider proof, and keep polling as the recovery path. Fence sealed setup and sync hints against namespace erasure. Signed-off-by: zlareb1 * Allocate source push migration after query history and budgets Signed-off-by: zlareb1 * Compose push erasure fences with user budget delivery Signed-off-by: zlareb1 * Regenerate the composed source push schema and statement corpus Signed-off-by: zlareb1 * Document source push entry points and lifecycle invariants Signed-off-by: zlareb1 * Push setup SDK summaries contain complete sentences Signed-off-by: zlareb1 * Keep push retirement available and restrict callbacks to held orgs Signed-off-by: zlareb1 * Allocate source push after user cost budgets Signed-off-by: zlareb1 * Keep push erasure traces aligned with authority order Signed-off-by: zlareb1 * Pin source push table ownership and replacement rows Signed-off-by: zlareb1 * Format the unified search argument table Signed-off-by: zlareb1 * Keep tracker search regression fixtures on the planned call path Signed-off-by: zlareb1 * Use the configured test target for tracker ASGI requests Signed-off-by: zlareb1 * Regenerate schema for user cost budgets Signed-off-by: zlareb1 * Record the official source push schema artifact Signed-off-by: zlareb1 * Align user budget contracts with checked synthesis Carry warning identity columns through task event reads and register the warning pipeline. Preserve named-user budget assertions while updating checked-search fixtures and their explicit keyword contracts, and regenerate the SDK surface and statement catalog. Signed-off-by: zlareb1 * Regenerate schema and statement catalog for user budgets Signed-off-by: zlareb1 * Register source push provenance and scope contracts Signed-off-by: zlareb1 * Test marked namespace spend through the shared budget snapshot The native marked-spend check uses the same rolling spend read as budget status and admission, including when the namespace has no cost cap. Signed-off-by: zlareb1 * Bound leased sends by the received server clock Signed-off-by: zlareb1 * Withhold exact user spend from budget status and warnings Named-user cap verdicts and warning thresholds count all ledger spend. Status reveals exact user spend only to a platform admin without namespace role restrictions; user warnings always redact the amount for recipients. Signed-off-by: zlareb1 * Test the push notification action in the source menu Keep the exact admin menu assertion aligned with the supported source actions. Signed-off-by: zlareb1 * Keep push maintenance on its connected client and configured deadlines Carry the connected store through registry resealing and its lifecycle fences. Keep timeout defaults in the configuration catalog, and align source contracts and generated snapshots. Signed-off-by: zlareb1 * Scope push registry keys and callback lookups by namespace Namespace name checks must not scan every retained source registration in an organization. Keep callback lookups and maintenance cursors on the same physical key prefix. Signed-off-by: zlareb1 * Generate the namespace-keyed push registry schema Record the official schema and statement catalog for namespace-scoped push lookups. Signed-off-by: zlareb1 * Keep push renewal deadlines inside the lease work window The renewal lease permits work for forty percent of its lifetime. Reject provider and cleanup budgets that exceed that window while retaining the existing defaults and lease policy. Signed-off-by: zlareb1 * Generate the combined mirror and push schema Record the namespace-keyed registry and deployment latch in one official schema. Signed-off-by: zlareb1 * Round-trip callback organizations through query encoding A permitted slash in an organization must not become a callback path separator. Signed-off-by: zlareb1 --------- Signed-off-by: zlareb1 * Publish reviewed documentation translations (#829) Related: https://github.com/ClickHouse/loom/pull/764 Related: https://github.com/ClickHouse/loom/pull/794 Related: https://github.com/ClickHouse/loom/pull/797 ### Changelog category (leave one): - Documentation ### Why Readers can open more documentation in Simplified Chinese, Japanese, Korean, Brazilian Portuguese and Spanish. English remains canonical. Included translation bodies have complete source-bound semantic reviews. Versions held for semantic or language-completeness defects remain excluded. ### Scope and risk This change publishes 307 generated pages and preserves 150 validated pages as pending until their link dependencies can activate. The maintained data-only importer rejected 44 other candidates; those versions are excluded. Current English source blobs, model and ownership stamps, protected source text, code, links, anchors and both table layouts must validate before staging. Dependency-safe activation determines which pages are published. Missing translations continue to open the named English page or an available native landing. Existing stale translations retain their notices. Rejected versions, unreviewed outputs and pages with provider refusals remain excluded. This batch does not claim complete translation coverage or enable recurring paid automation. The site records anchors from rendered page HTML. Raw Markdown code literals such as `" + 'Missing
' + ) + page = SimpleNamespace(present_anchor_ids={"code-only", "missing"}) + assert hooks.on_page_content(rendered, page, None, None) == rendered + assert page.present_anchor_ids == {"legacy", "real"} diff --git a/tests/unit/test_docs_site_indexnow.py b/tests/unit/test_docs_site_indexnow.py index 75bf651abb..ed80b524fd 100644 --- a/tests/unit/test_docs_site_indexnow.py +++ b/tests/unit/test_docs_site_indexnow.py @@ -24,7 +24,10 @@ def test_a_changed_page_maps_to_the_url_the_site_serves_it_at() -> None: assert indexnow.page_url("docs/benchmarks/results.csv") is None -def test_only_changed_pages_are_submitted_when_the_build_did_not_change() -> None: +def test_only_changed_pages_are_submitted_without_translation_dependencies( + tmp_path, monkeypatch +) -> None: + monkeypatch.setattr(indexnow, "DOCS", tmp_path / "docs") urls = indexnow.urls_for(["docs/a.md", "docs/a.md", "README.md", "docs/b/index.md"]) assert urls == [SITE + "a/", SITE + "b/"] @@ -43,6 +46,9 @@ def test_a_change_to_the_build_submits_every_page() -> None: for path in ( "mkdocs.yml", "scripts/docs_site/overrides/main.html", + "scripts/docs_site/locales.py", + "scripts/docs_site/video_labels.py", + "scripts/docs_site/paths.py", "scripts/docs_site/hooks.py", "scripts/docs_site/requirements.txt", "scripts/codegen/page_summary.py", @@ -64,7 +70,14 @@ def test_every_submitted_url_is_on_the_key_files_host_and_under_its_directory() assert all(urlsplit(u).hostname == body["host"] for u in body["urlList"]) -def test_main_posts_only_the_changed_pages_and_posts_nothing_when_none_changed(monkeypatch) -> None: +def test_main_posts_only_the_changed_pages_and_posts_nothing_when_none_changed( + tmp_path, monkeypatch +) -> None: + docs = tmp_path / "docs" + docs.mkdir() + key = "a" * 32 + (docs / f"{key}.txt").write_text(key) + monkeypatch.setattr(indexnow, "DOCS", docs) sent: list[dict] = [] class _Resp: @@ -86,3 +99,10 @@ def fake_urlopen(req, timeout): assert sent == [] assert indexnow.main(["docs/a.md"]) == 0 assert [s["urlList"] for s in sent] == [[SITE + "a/"]] + + +def test_shared_language_route_mapping_is_a_render_input() -> None: + from scripts.docs_site import locales + + helper = Path(locales.page_path.__code__.co_filename).resolve().relative_to(ROOT) + assert indexnow.urls_for([helper.as_posix()]) == indexnow.every_page() diff --git a/tests/unit/test_docs_site_locales.py b/tests/unit/test_docs_site_locales.py new file mode 100644 index 0000000000..90cd89693e --- /dev/null +++ b/tests/unit/test_docs_site_locales.py @@ -0,0 +1,726 @@ +"""Translation routes and alternate links follow the translations that exist.""" + +from __future__ import annotations + +import hashlib +import subprocess +import sys +from pathlib import Path +from types import SimpleNamespace +from urllib.parse import quote + +import pytest + +from scripts.docs_site import locales +from scripts.docs_site.messages import COPY + +URL = "https://example.com/loom/" + + +def _source(root: Path, uri: str, text: str = "# Page\n\nThe current page.\n") -> str: + path = root / "docs" / uri + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(text, encoding="utf-8") + content = path.read_bytes() + return hashlib.sha1(f"blob {len(content)}\0".encode() + content).hexdigest() + + +def _translation(root: Path, language: str, source: str, blob: str) -> None: + path = root / "i18n" / language / "docs" / source + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(f"\n# Page\n") + + +def test_routes_report_stale_stamps_and_retain_only_owned_obsolete_translations(tmp_path): + blob = _source(tmp_path, "use-cases/index.md") + _translation(tmp_path, "ja", "use-cases/index.md", blob) + _translation(tmp_path, "es", "use-cases/index.md", "0" * 40) + _translation(tmp_path, "ko", "missing.md", blob) + pages = locales.translations(tmp_path, languages=locales.LANGUAGES) + assert set(pages) == {"ja/use-cases/index.md", "es/use-cases/index.md", "ko/missing.md"} + assert pages["ja/use-cases/index.md"]["stale"] is False + assert pages["es/use-cases/index.md"]["stale"] is True + assert pages["ko/missing.md"]["obsolete"] is True + assert pages["ko/missing.md"]["stale"] is True + _source(tmp_path, "use-cases/index.md", "# Changed\n") + assert ( + locales.translations(tmp_path, languages=locales.LANGUAGES)["ja/use-cases/index.md"][ + "stale" + ] + is True + ) + + +def test_equivalent_links_are_reciprocal_and_missing_locales_are_absent(tmp_path): + blob = _source(tmp_path, "use-cases/index.md") + _translation(tmp_path, "ja", "use-cases/index.md", blob) + pages = locales.translations(tmp_path, languages=locales.LANGUAGES) + expected = [ + ("en", URL + "use-cases/"), + ("ja", URL + "ja/use-cases/"), + ("x-default", URL + "use-cases/"), + ] + assert [ + (a["lang"], a["url"]) for a in locales.alternates("use-cases/index.md", pages, URL) + ] == expected + for uri in ("use-cases/index.md", "ja/use-cases/index.md"): + page = SimpleNamespace(file=SimpleNamespace(src_uri=uri), meta={}) + config = SimpleNamespace(extra={"locale_pages": pages}, site_url=URL) + locales.on_page_markdown("# Page", page, config, None) + assert [(a["lang"], a["url"]) for a in page.meta["alternates"]] == expected + assert locales.alternates("index.md", pages, URL) == [] + + +def test_localized_root_links_resolve_from_source_and_banner_stays_english(tmp_path, monkeypatch): + source = "use-cases/index.md" + blob = _source(tmp_path, source) + for uri in ("use-cases/memory.md", "getting-started/quickstart.md", "features/setup.md"): + _source(tmp_path, uri) + _translation(tmp_path, "ja", source, blob) + _translation(tmp_path, "ja", "use-cases/memory.md", blob) + asset = tmp_path / "docs" / "assets" / "figure.svg" + asset.parent.mkdir() + asset.write_text("") + pages = locales.translations(tmp_path, languages=locales.LANGUAGES) + monkeypatch.setattr(locales, "ROOT", tmp_path) + body = ( + f"\n> [English]({locales.BLOB}docs/{source})\n\n" + "# Page\n\n[memory](memory.md#save) [setup](../features/setup.md) " + "![figure](../assets/figure.svg) " + f"[absolute]({locales.BLOB}i18n/ja/docs/use-cases/memory.md) " + f"[English docs]({locales.BLOB}docs/getting-started/quickstart.md) " + "`[code](memory.md)`\n```md\n[fenced](memory.md)\n```\n[same](#anchor)" + ) + out = locales.translated_markdown(body, pages["ja/use-cases/index.md"], pages, URL) + assert f"[English]({URL}use-cases/)" in out + assert f"[memory]({URL}ja/use-cases/memory/#save)" in out + assert f"[absolute]({URL}ja/use-cases/memory/)" in out + assert f"[setup]({URL}features/setup/)" in out + assert f"![figure]({URL}assets/figure.svg)" in out + assert f"[English docs]({locales.BLOB}docs/getting-started/quickstart.md)" in out + assert "`[code](memory.md)`" in out and "[fenced](memory.md)" in out + assert "[same](#anchor)" in out + + +def test_homepage_links_to_landings_without_claiming_equivalent_content(tmp_path): + blob = _source(tmp_path, "use-cases/index.md") + _translation(tmp_path, "ja", "use-cases/index.md", blob) + page = SimpleNamespace(file=SimpleNamespace(src_uri="index.md"), meta={}) + config = SimpleNamespace( + extra={"locale_pages": locales.translations(tmp_path, languages=locales.LANGUAGES)}, + site_url=URL, + ) + locales.on_page_markdown("# Home", page, config, None) + choices = page.meta["language_choices"] + assert [(item["lang"], item["url"]) for item in choices] == [ + ("en", URL), + ("ja", URL + "ja/use-cases/"), + ] + assert choices[1]["landing"] == "Page" + assert page.meta["alternates"] == [] + + +def test_html_language_matches_the_page(): + page = SimpleNamespace(meta={"language": "pt-BR"}) + assert ( + locales.on_post_page('

Source

', page, None) + == '

Source

' + ) + + +def test_indexnow_maps_translation_paths_and_omits_readme(): + from scripts.docs_site import indexnow + + assert indexnow.page_url("i18n/ja/docs/use-cases/index.md") == indexnow.SITE + "ja/use-cases/" + assert ( + locales.localized_page_path( + "i18n/es/docs/getting-started/quickstart.md", languages=locales.LANGUAGES + ) + == "es/getting-started/quickstart/" + ) + assert indexnow.page_url("i18n/es/docs/getting-started/quickstart.md") == ( + indexnow.SITE + "es/getting-started/quickstart/" + ) + assert indexnow.page_url("i18n/ja/README.md") is None + assert indexnow.page_url("i18n/unknown/docs/page.md") is None + + +def test_locale_render_changes_submit_all_existing_translations(tmp_path, monkeypatch): + from scripts.docs_site import indexnow + + blob = _source(tmp_path, "use-cases/index.md") + _translation(tmp_path, "ja", "use-cases/index.md", blob) + monkeypatch.setattr(indexnow, "DOCS", tmp_path / "docs") + for changed in ( + "scripts/docs_site/locales.py", + "scripts/docs_site/overrides/partials/locales-head.html", + "scripts/docs_site/overrides/partials/locales-switch.html", + "scripts/docs_site/overrides/sitemap.xml", + ): + assert indexnow.urls_for([changed]) == [ + indexnow.SITE + "ja/use-cases/", + indexnow.SITE + "use-cases/", + ] + + +def test_translated_heading_sets_page_and_metadata_title_after_the_source_banner(tmp_path): + blob = _source(tmp_path, "use-cases/index.md") + _translation(tmp_path, "ja", "use-cases/index.md", blob) + pages = locales.translations(tmp_path, languages=locales.LANGUAGES) + path = Path(pages["ja/use-cases/index.md"]["path"]) + stamp = path.read_text().splitlines()[0] + markdown = ( + f'{stamp}\n> Machine translation.\n\n\n\n# ユースケース\n\n本文。\n' + ) + path.write_text(markdown) + page = SimpleNamespace( + file=SimpleNamespace(src_uri="ja/use-cases/index.md"), meta={}, title="Index" + ) + config = SimpleNamespace(extra={"locale_pages": pages}, site_url=URL) + locales.on_page_markdown(markdown, page, config, None) + assert page.title == "ユースケース" + assert page.meta["title"] == "ユースケース" + + +def test_full_indexnow_submission_retains_owned_orphans_and_excludes_unowned_output( + tmp_path, monkeypatch +): + from scripts.docs_site import indexnow + + (tmp_path / "docs").mkdir() + _translation(tmp_path, "ja", "missing.md", "0" * 40) + assert "ja/missing.md" in locales.translations(tmp_path, languages=locales.LANGUAGES) + monkeypatch.setattr(indexnow, "DOCS", tmp_path / "docs") + assert indexnow.every_page() == [indexnow.SITE + "ja/missing/"] + assert indexnow.urls_for(["scripts/docs_site/locales.py"]) == [indexnow.SITE + "ja/missing/"] + (tmp_path / "i18n/ja/docs/missing.md").write_text("# Unstamped orphan\n") + _translation(tmp_path, "unknown", "hidden.md", "0" * 40) + _translation(tmp_path, ".pending/ja", "hidden.md", "0" * 40) + _translation(tmp_path, "es", "mismatch.md", "0" * 40) + (tmp_path / "i18n/es/docs/mismatch.md").write_text( + "\n# Wrong source\n" + ) + assert locales.translations(tmp_path, languages=locales.LANGUAGES) == {} + assert indexnow.every_page() == [] + assert indexnow.urls_for(["scripts/docs_site/locales.py"]) == [] + assert indexnow.urls_for(["i18n/ja/docs/missing.md"]) == [indexnow.SITE + "ja/missing/"] + + +def test_open_graph_locales_require_a_language_and_territory(tmp_path): + blob = _source(tmp_path, "use-cases/index.md") + for language in locales.LANGUAGES: + _translation(tmp_path, language, "use-cases/index.md", blob) + pages = locales.translations(tmp_path, languages=locales.LANGUAGES) + expected = {"zh-CN": "zh_CN", "pt-BR": "pt_BR"} + config = SimpleNamespace(extra={"locale_pages": pages}, site_url=URL) + for uri in ["use-cases/index.md", *pages]: + page = SimpleNamespace(file=SimpleNamespace(src_uri=uri), meta={}) + locales.on_page_markdown("# Page", page, config, None) + assert page.meta.get("og_locale") == expected.get(page.meta["language"]) + + +def test_the_hook_loads_without_an_editable_repository_install(): + hook = Path(__file__).resolve().parents[2] / "scripts/docs_site/locales.py" + result = subprocess.run( + [ + sys.executable, + "-I", + "-S", + "-c", + "import runpy, sys; runpy.run_path(sys.argv[1])", + str(hook), + ], + cwd=hook.parent, + capture_output=True, + text=True, + ) + assert result.returncode == 0, result.stderr + + +def test_translation_changes_resubmit_pages_with_alternates_and_rewritten_links( + tmp_path, monkeypatch +): + from scripts.docs_site import indexnow + + blob = _source(tmp_path, "use-cases/index.md") + _source(tmp_path, "other.md") + _translation(tmp_path, "ja", "use-cases/index.md", blob) + monkeypatch.setattr(indexnow, "DOCS", tmp_path / "docs") + every = indexnow.every_page() + assert indexnow.urls_for(["docs/use-cases/index.md"]) == every + assert indexnow.urls_for(["i18n/ja/docs/use-cases/index.md"]) == every + deleted = "i18n/ja/docs/use-cases/deleted.md" + assert indexnow.urls_for([deleted]) == sorted([*every, indexnow.SITE + "ja/use-cases/deleted/"]) + assert indexnow.urls_for(["docs/other.md"]) == every + + +def test_deleted_english_source_announces_removed_translated_routes(tmp_path, monkeypatch): + from scripts.docs_site import indexnow + + _source(tmp_path, "other.md") + _translation(tmp_path, "ja", "use-cases/index.md", "0" * 40) + monkeypatch.setattr(indexnow, "DOCS", tmp_path / "docs") + assert indexnow.urls_for(["docs/use-cases/index.md"]) == [ + indexnow.SITE + "ja/use-cases/", + indexnow.SITE + "other/", + indexnow.SITE + "use-cases/", + ] + + +def test_removed_untranslated_target_resubmits_translations_with_rewritten_links( + tmp_path, monkeypatch +): + from scripts.docs_site import indexnow + + blob = _source(tmp_path, "use-cases/index.md") + _source(tmp_path, "features/setup.md") + _translation(tmp_path, "ja", "use-cases/index.md", blob) + monkeypatch.setattr(indexnow, "DOCS", tmp_path / "docs") + monkeypatch.setattr(locales, "ROOT", tmp_path) + pages = locales.translations(tmp_path, languages=locales.LANGUAGES) + entry = pages["ja/use-cases/index.md"] + body = f"\n\n[setup]({locales.BLOB}docs/features/setup.md)" + assert locales.translated_markdown(body, entry, pages, URL) == body + (tmp_path / "docs/features/setup.md").unlink() + assert locales.translated_markdown(body, entry, pages, URL) == body + assert indexnow.urls_for(["docs/features/setup.md"]) == sorted( + [*indexnow.every_page(), indexnow.SITE + "features/setup/"] + ) + + +def test_translated_section_index_serves_the_same_markdown_aliases(tmp_path, monkeypatch): + blob = _source(tmp_path, "use-cases/index.md") + _translation(tmp_path, "ja", "use-cases/index.md", blob) + pages = locales.translations(tmp_path, languages=locales.LANGUAGES) + site = tmp_path / "site" + monkeypatch.setattr(locales, "ROOT", tmp_path) + locales.on_post_build( + SimpleNamespace(site_dir=site, site_url=URL, extra={"locale_pages": pages}) + ) + body = (site / "ja/use-cases/index.md").read_text() + assert (site / "ja/use-cases.md").read_text() == body + assert (site / "ja/use-cases/index.html.md").read_text() == body + + +@pytest.mark.parametrize("source", ["use-cases/index.md", "getting-started/quickstart.md"]) +@pytest.mark.parametrize("stale", [False, True]) +def test_markdown_aliases_warn_only_when_the_english_source_changes( + tmp_path, monkeypatch, source, stale +): + blob = _source(tmp_path, source) + _translation(tmp_path, "ja", source, blob) + if stale: + _source(tmp_path, source, "# Updated instructions\n") + pages = locales.translations(tmp_path, languages=locales.LANGUAGES) + site = tmp_path / "site" + monkeypatch.setattr(locales, "ROOT", tmp_path) + locales.on_post_build( + SimpleNamespace(site_dir=site, site_url=URL, extra={"locale_pages": pages}) + ) + uri = locales.localized_uri("ja", source) + directory = ( + "ja/use-cases" if source == "use-cases/index.md" else "ja/getting-started/quickstart" + ) + paths = [site / uri, site / directory / "index.html.md"] + if source == "use-cases/index.md": + paths.append(site / "ja/use-cases.md") + notice = COPY["ja"]["stale_before"] + english = "use-cases/" if source == "use-cases/index.md" else "getting-started/quickstart/" + for path in paths: + text = path.read_text() + assert (notice in text) is stale + if stale: + assert f"[{COPY['ja']['english_page']}]({URL}{english})" in text + + +def test_explicit_english_anchor_fallback_is_not_redirected_to_a_translation(tmp_path, monkeypatch): + source = "use-cases/index.md" + blob = _source(tmp_path, source) + memory = _source(tmp_path, "use-cases/agent-memory.md", "# Memory\n\n## Measured\n") + _translation(tmp_path, "ja", source, blob) + _translation(tmp_path, "ja", "use-cases/agent-memory.md", memory) + pages = locales.translations(tmp_path, languages=locales.LANGUAGES) + monkeypatch.setattr(locales, "ROOT", tmp_path) + body = ( + "\n\n" + f"[measured]({locales.BLOB}docs/use-cases/agent-memory.md#measured) " + f"[translated]({locales.BLOB}i18n/ja/docs/use-cases/agent-memory.md)" + ) + result = locales.translated_markdown(body, pages["ja/use-cases/index.md"], pages, URL) + assert f"[measured]({locales.BLOB}docs/use-cases/agent-memory.md#measured)" in result + assert f"[translated]({URL}ja/use-cases/agent-memory/)" in result + + +@pytest.mark.parametrize("source", ["use-cases/agent-memory.md", "use-cases/index.md"]) +def test_retained_machine_translation_survives_source_rename_until_dependency_cleanup( + tmp_path, monkeypatch, source +): + blob = _source(tmp_path, source) + _translation(tmp_path, "ja", source, blob) + path = tmp_path / "i18n/ja/docs" / source + path.write_text( + f"\n" + f"> Machine-translated from the [English page]({locales.BLOB}docs/{source}).\n\n" + '# Retained page\n\n\n' + ) + monkeypatch.setattr(locales, "ROOT", tmp_path) + uri = locales.localized_uri("ja", source) + assert uri in locales.translations(tmp_path, languages=locales.LANGUAGES) + (tmp_path / "docs" / source).rename(tmp_path / "docs/use-cases/replacement.md") + pages = locales.translations(tmp_path, languages=locales.LANGUAGES) + assert uri in pages + assert pages[uri]["stale"] is True + page = SimpleNamespace(file=SimpleNamespace(src_uri=uri), meta={}, title="Page") + config = SimpleNamespace( + extra={"locale_pages": pages}, site_url=URL, site_dir=tmp_path / "site" + ) + result = locales.on_page_markdown(path.read_text(), page, config, None) + assert page.meta["alternates"] == [] + assert COPY["ja"]["retained_before"] in result + assert f"]({locales.BLOB}docs/{source})" not in result + assert "# Retained page" in result and 'id="measured"' in result + referring = {"language": "ja", "source": "use-cases/index.md"} + link = ( + f"\n\n[retained]({locales.BLOB}i18n/ja/docs/{source}#measured) " + f"[relative]({Path(source).name}#measured)" + ) + assert ( + locales.translated_markdown(link, referring, pages, URL).count( + URL + locales.page_path(f"docs/{uri}") + "#measured" + ) + == 2 + ) + locales.on_post_build(config) + aliases = [ + config.site_dir / uri, + config.site_dir / locales.page_path(f"docs/{uri}") / "index.html.md", + ] + if source == "use-cases/index.md": + aliases.append(config.site_dir / "ja/use-cases.md") + for alias in aliases: + text = alias.read_text() + assert COPY["ja"]["retained_before"] in text + assert f"]({locales.BLOB}docs/{source})" not in text + assert "Read the [English page]" not in text + path.unlink() + assert uri not in locales.translations(tmp_path, languages=locales.LANGUAGES) + + +@pytest.mark.parametrize("language", ["ja", "es"]) +def test_home_and_use_case_indexes_keep_distinct_routes_and_aliases( + tmp_path, monkeypatch, language +): + from scripts.docs_site import indexnow + + for source, title in (("index.md", "Home"), ("use-cases/index.md", "Use cases")): + blob = _source(tmp_path, source, f"# {title}\n") + _translation(tmp_path, language, source, blob) + path = tmp_path / "i18n" / language / "docs" / source + path.write_text(path.read_text() + f"\n{title} body\n") + monkeypatch.setattr(locales, "ROOT", tmp_path) + monkeypatch.setattr(indexnow, "DOCS", tmp_path / "docs") + pages = locales.translations(tmp_path, languages=locales.LANGUAGES) + assert {uri: entry["source"] for uri, entry in pages.items()} == { + f"{language}/index.md": "index.md", + f"{language}/use-cases/index.md": "use-cases/index.md", + } + config = SimpleNamespace( + extra={"locale_pages": pages}, site_url=URL, site_dir=tmp_path / "site" + ) + for source, suffix in (("index.md", ""), ("use-cases/index.md", "use-cases/")): + expected = [ + ("en", URL + suffix), + (language, URL + language + "/" + suffix), + ("x-default", URL + suffix), + ] + for uri in (source, f"{language}/{source}"): + page = SimpleNamespace(file=SimpleNamespace(src_uri=uri), meta={}) + locales.on_page_markdown("# Page", page, config, None) + assert [(a["lang"], a["url"]) for a in page.meta["alternates"]] == expected + homepage = SimpleNamespace(file=SimpleNamespace(src_uri="index.md"), meta={}) + locales.on_page_markdown("# Home", homepage, config, None) + assert [(item["lang"], item["url"]) for item in homepage.meta["language_choices"]] == [ + ("en", URL), + (language, URL + language + "/"), + ] + body = "\n\n[home](../index.md#intro)" + assert f"[home]({URL}{language}/#intro)" in locales.translated_markdown( + body, pages[f"{language}/use-cases/index.md"], pages, URL + ) + locales.on_post_build(config) + for suffix, title in (("", "Home"), ("/use-cases", "Use cases")): + directory = language + suffix + aliases = [f"{directory}/index.md", f"{directory}.md", f"{directory}/index.html.md"] + texts = [(config.site_dir / alias).read_text() for alias in aliases] + assert texts[0] == texts[1] == texts[2] + assert f"{title} body" in texts[0] + assert ( + locales.localized_page_path(f"i18n/{language}/docs/index.md", languages=locales.LANGUAGES) + == language + "/" + ) + assert ( + locales.localized_page_path( + f"i18n/{language}/docs/use-cases/index.md", languages=locales.LANGUAGES + ) + == language + "/use-cases/" + ) + published = language in locales.PUBLISHED_LANGUAGES + for source, suffix in (("index.md", "/"), ("use-cases/index.md", "/use-cases/")): + assert indexnow.page_url(f"i18n/{language}/docs/{source}") == ( + indexnow.SITE + language + suffix if published else None + ) + expected = ["", "use-cases/"] + if published: + expected.extend([language + "/", language + "/use-cases/"]) + assert indexnow.every_page() == sorted(indexnow.SITE + suffix for suffix in expected) + + +@pytest.mark.parametrize("source", ["space name.md", "日本語 guide.md"]) +def test_space_named_source_stamp_tracks_fresh_stale_and_retained_states(tmp_path, source): + blob = _source(tmp_path, source) + _translation(tmp_path, "ja", source, blob) + uri = f"ja/{source}" + assert locales.translations(tmp_path, languages=locales.LANGUAGES)[uri]["stale"] is False + _source(tmp_path, source, "# Changed\n") + assert locales.translations(tmp_path, languages=locales.LANGUAGES)[uri]["stale"] is True + (tmp_path / "docs" / source).unlink() + retained = locales.translations(tmp_path, languages=locales.LANGUAGES)[uri] + assert retained["obsolete"] is True and retained["stale"] is True + + +@pytest.mark.parametrize("language", ["ja", "es"]) +def test_relative_translated_readme_stays_on_repository_in_html_and_aliases( + tmp_path, monkeypatch, language +): + source = "development/repository-guide.md" + blob = _source(tmp_path, source) + _translation(tmp_path, language, source, blob) + (tmp_path / "README.md").write_text("# Loom\n") + (tmp_path / "i18n" / language / "README.md").write_text("# Loom\n") + path = tmp_path / "i18n" / language / "docs" / source + path.write_text(path.read_text() + "\n[README](../../README.md#loom)\n") + monkeypatch.setattr(locales, "ROOT", tmp_path) + pages = locales.translations(tmp_path, languages=locales.LANGUAGES) + uri = f"{language}/{source}" + page = SimpleNamespace(file=SimpleNamespace(src_uri=uri), meta={}) + config = SimpleNamespace( + extra={"locale_pages": pages}, site_url=URL, site_dir=tmp_path / "site" + ) + expected = f"[README]({locales.BLOB}i18n/{language}/README.md#loom)" + assert expected in locales.on_page_markdown(path.read_text(), page, config, None) + locales.on_post_build(config) + for alias in (uri, f"{language}/development/repository-guide/index.html.md"): + assert expected in (config.site_dir / alias).read_text() + assert set(pages) == {uri} + + +def test_default_site_publishes_all_five_locales_and_keeps_artifacts(tmp_path, monkeypatch): + from scripts.docs_site import indexnow + + blob = _source(tmp_path, "use-cases/index.md") + _source(tmp_path, "index.md") + for language in locales.LANGUAGES: + _translation(tmp_path, language, "use-cases/index.md", blob) + monkeypatch.setattr(indexnow, "DOCS", tmp_path / "docs") + pages = locales.translations(tmp_path) + assert set(pages) == {f"{language}/use-cases/index.md" for language in locales.LANGUAGES} + assert {a["lang"] for a in locales.alternates("use-cases/index.md", pages, URL)} == { + "en", + *locales.LANGUAGES, + "x-default", + } + assert locales.language_landings(pages, URL) == [ + {"lang": language, "name": name, "url": URL + language + "/use-cases/"} + for language, name in locales.LANGUAGES.items() + ] + every = sorted( + indexnow.SITE + suffix + for suffix in ( + "", + "use-cases/", + *(language + "/use-cases/" for language in locales.LANGUAGES), + ) + ) + assert indexnow.every_page() == every + for language in locales.LANGUAGES: + path = f"i18n/{language}/docs/use-cases/index.md" + assert (tmp_path / path).is_file() + assert indexnow.page_url(path) == indexnow.SITE + language + "/use-cases/" + assert indexnow.urls_for([path]) == every + + +@pytest.mark.parametrize("source", ["use-cases/agent-memory.md", "use-cases/index.md"]) +@pytest.mark.parametrize("target", ["space name.md", "日本語 guide.md", "percent%25 guide.md"]) +def test_encoded_translated_links_keep_destinations_in_every_markdown_alias( + tmp_path, monkeypatch, source, target +): + blob = _source(tmp_path, source) + _translation(tmp_path, "ja", source, blob) + target_source = "use-cases/" + target + target_blob = _source(tmp_path, target_source, '# Target\n\n\n') + _translation(tmp_path, "ja", target_source, target_blob) + target_path = tmp_path / "i18n/ja/docs" / target_source + target_path.write_text(target_path.read_text() + '\n\n') + path = tmp_path / "i18n/ja/docs" / source + path.write_text( + path.read_text() + f"\n[relative]({quote(target)}#beta) " + f"[absolute]({locales.BLOB}i18n/ja/docs/{quote(target_source)}#beta) " + f"[English]({locales.BLOB}docs/{quote(target_source)}#beta)\n" + ) + monkeypatch.setattr(locales, "ROOT", tmp_path) + pages = locales.translations(tmp_path) + uri = "ja/" + source + page = SimpleNamespace(file=SimpleNamespace(src_uri=uri), meta={}) + config = SimpleNamespace( + extra={"locale_pages": pages}, site_url=URL, site_dir=tmp_path / "site" + ) + expected = URL + "ja/use-cases/" + quote(target.removesuffix(".md")) + "/#beta" + html_markdown = locales.on_page_markdown(path.read_text(), page, config, None) + locales.on_post_build(config) + aliases = [uri, locales.page_path("docs/" + uri) + "index.html.md"] + if source.endswith("/index.md"): + aliases.append("ja/use-cases.md") + for output in [html_markdown, *((config.site_dir / alias).read_text() for alias in aliases)]: + assert f"[relative]({expected})" in output + assert f"[absolute]({expected})" in output + assert f"[English]({locales.BLOB}docs/{quote(target_source)}#beta)" in output + + +@pytest.mark.parametrize("name", ["space name.md", "日本語 guide.md"]) +def test_encoded_english_source_banner_and_stale_alias_keep_source_url(tmp_path, monkeypatch, name): + from scripts.docs_site import indexnow + + source = "use-cases/" + name + blob = _source(tmp_path, source) + _translation(tmp_path, "ja", source, blob) + path = tmp_path / "i18n/ja/docs" / source + path.write_text( + f"\n" + f"> [English]({locales.BLOB}docs/{quote(source)})\n\n# Page\n" + ) + _source(tmp_path, source, "# Changed\n") + monkeypatch.setattr(locales, "ROOT", tmp_path) + pages = locales.translations(tmp_path) + uri = "ja/" + source + page = SimpleNamespace(file=SimpleNamespace(src_uri=uri), meta={}) + config = SimpleNamespace( + extra={"locale_pages": pages}, site_url=URL, site_dir=tmp_path / "site" + ) + expected = URL + "use-cases/" + quote(name.removesuffix(".md")) + "/" + monkeypatch.setattr(indexnow, "DOCS", tmp_path / "docs") + assert f"[English]({expected})" in locales.on_page_markdown( + path.read_text(), page, config, None + ) + localized = URL + "ja/use-cases/" + quote(name.removesuffix(".md")) + "/" + assert [a["url"] for a in page.meta["alternates"]] == [expected, localized, expected] + site_suffix = "use-cases/" + quote(name.removesuffix(".md")) + "/" + assert indexnow.page_url("i18n/ja/docs/" + source) == indexnow.SITE + "ja/" + site_suffix + assert indexnow.every_page() == sorted( + [indexnow.SITE + site_suffix, indexnow.SITE + "ja/" + site_suffix] + ) + locales.on_post_build(config) + for alias in (uri, locales.page_path("docs/" + uri) + "index.html.md"): + output = (config.site_dir / alias).read_text() + assert f"[English]({expected})" in output + assert f"[{COPY['ja']['english_page']}]({expected})" in output + assert f"> Source: {localized} (Markdown: {URL}{quote(uri)})" in output + + +def _nav_page(uri: str, title: str): + return SimpleNamespace( + file=SimpleNamespace(src_uri=uri), + title=title, + url=locales.page_path("docs/" + uri), + is_page=True, + is_section=False, + active=False, + parent=None, + previous_page=None, + next_page=None, + ) + + +def test_navigation_keeps_locale_and_labels_missing_pages_without_shared_mutation(tmp_path): + a = _source(tmp_path, "use-cases/a.md") + _source(tmp_path, "use-cases/b.md") + _translation(tmp_path, "es", "use-cases/a.md", a) + path = tmp_path / "i18n/es/docs/use-cases/a.md" + path.write_text(path.read_text().replace("# Page", "# Memoria compartida")) + english_a, english_b = ( + _nav_page("use-cases/a.md", "Memory"), + _nav_page("use-cases/b.md", "Code"), + ) + spanish = _nav_page("es/use-cases/a.md", "Memoria compartida") + spanish.meta = {"language": "es"} + section = SimpleNamespace( + title="Use cases", + is_page=False, + is_section=True, + children=[english_a, english_b], + active=False, + parent=None, + ) + english_a.parent = english_b.parent = section + nav = SimpleNamespace(items=[section], pages=[english_a, english_b], homepage=None) + config = SimpleNamespace( + extra={ + "locale_pages": locales.translations(tmp_path), + "locale_nav_pages": {"es/use-cases/a.md": spanish}, + } + ) + context = {"page": spanish, "nav": nav} + locales.on_page_context(context, spanish, config, nav) + projected = context["nav"] + assert projected.items[0].title == "Casos de uso" + assert projected.pages[0].url == "es/use-cases/a/" + assert projected.pages[0].title == "Memoria compartida" + assert projected.pages[0].active is True + assert projected.pages[1].url == "use-cases/b/" + assert projected.pages[1].title == "Code (Inglés)" + assert context["locale_has_english_fallback"] is True + assert context["page"].next_page is projected.pages[1] + assert nav.items[0].title == "Use cases" and nav.items[0].active is False + assert english_a.parent is section and english_a.title == "Memory" + assert english_a.next_page is None and spanish.next_page is None + english = {"nav": nav} + english_a.meta = {"language": "en"} + assert locales.on_page_context(english, english_a, config, nav)["nav"] is nav + + +def test_every_english_page_offers_available_languages_without_false_alternates(tmp_path): + _source(tmp_path, "other.md") + blob = _source(tmp_path, "getting-started/quickstart.md") + for language in locales.LANGUAGES: + _translation(tmp_path, language, "getting-started/quickstart.md", blob) + pages = locales.translations(tmp_path) + page = SimpleNamespace(file=SimpleNamespace(src_uri="other.md"), meta={}) + config = SimpleNamespace(extra={"locale_pages": pages}, site_url=URL) + locales.on_page_markdown("# Other", page, config, None) + assert page.meta["alternates"] == [] + assert {item["lang"] for item in page.meta["language_choices"]} == {"en", *locales.LANGUAGES} + assert [item["url"] for item in page.meta["language_choices"][1:]] == [ + URL + language + "/getting-started/quickstart/" for language in locales.LANGUAGES + ] + assert all(item["landing"] == "Page" for item in page.meta["language_choices"][1:]) + + +@pytest.mark.parametrize("language", list(locales.LANGUAGES)) +def test_stale_notices_and_theme_language_follow_the_reader(tmp_path, monkeypatch, language): + source = "page.md" + blob = _source(tmp_path, source) + _translation(tmp_path, language, source, blob) + _source(tmp_path, source, "# Changed\n") + monkeypatch.setattr(locales, "ROOT", tmp_path) + pages = locales.translations(tmp_path) + page = SimpleNamespace(file=SimpleNamespace(src_uri=language + "/page.md"), meta={}) + config = SimpleNamespace( + extra={"locale_pages": pages}, site_url=URL, site_dir=tmp_path / "site" + ) + locales.on_page_markdown("# Page", page, config, None) + assert page.meta["theme_language"] == ("zh" if language == "zh-CN" else language) + assert page.meta["locale_ui"]["language"] != "Language" + locales.on_post_build(config) + body = (config.site_dir / language / "page.md").read_text() + assert COPY[language]["stale_before"] in body + assert f"[{COPY[language]['english_page']}]({URL}page/)" in body + assert "The English source has changed" not in body diff --git a/tests/unit/test_docs_site_video_labels.py b/tests/unit/test_docs_site_video_labels.py new file mode 100644 index 0000000000..fbc0d080d6 --- /dev/null +++ b/tests/unit/test_docs_site_video_labels.py @@ -0,0 +1,76 @@ +"""Localized video labels use the translated fallback text without changing source files.""" + +from html.parser import HTMLParser +from types import SimpleNamespace + +import pytest + +from scripts.docs_site import locales + + +class _Videos(HTMLParser): + def __init__(self, text): + super().__init__() + self.attributes = [] + self.feed(text) + + def handle_starttag(self, tag, attrs): + if tag == "video": + self.attributes.append(dict(attrs)) + + +@pytest.mark.parametrize( + ("language", "caption", "label"), + [ + ( + "pt-BR", + "Ask AI respondendo com fontes verificadas (clipe)", + "Ask AI respondendo com fontes verificadas (clipe)", + ), + ("ja", "出典を確認して回答 & 検証", "出典を確認して回答 & 検証"), + ("ja", "出典を確認", "出典を確認"), + ], +) +def test_localized_video_uses_its_translated_fallback(language, caption, label): + text = ( + '' + ) + page = SimpleNamespace(meta={"language": language}) + output = locales.on_post_page(text, page, None) + before, after = _Videos(text).attributes[0], _Videos(output).attributes[0] + assert after.pop("aria-label") == label + before.pop("aria-label") + assert after == before + assert f'{caption}' in output + + +@pytest.mark.parametrize( + ("language", "body"), + [ + ("en", ''), + ("ja", ''), + ("ja", ''), + ("ja", ""), + ("ja", '
<video aria-label="Example">
'), + ("ja", ''), + ("ja", '<video aria-label="Example"><a>Literal</a></video>'), + ("ja", ""), + ], +) +def test_video_label_projection_leaves_other_content(language, body): + text = f'{body}' + assert locales.on_post_page(text, SimpleNamespace(meta={"language": language}), None) == text + + +def test_each_video_keeps_its_own_fallback_and_escaped_label(): + text = ( + '\n' + '' + ) + output = locales.on_post_page(text, SimpleNamespace(meta={"language": "ja"}), None) + assert [attrs["aria-label"] for attrs in _Videos(output).attributes] == [ + '最初 "引用"', + "次の <例>", + ] diff --git a/tests/unit/test_dupcheck_links.py b/tests/unit/test_dupcheck_links.py index b4464af1b7..6c19987434 100644 --- a/tests/unit/test_dupcheck_links.py +++ b/tests/unit/test_dupcheck_links.py @@ -323,12 +323,23 @@ async def failing() -> Any: assert (await h._with_links(unavailable, ORG, PUB, None)) is unavailable -def test_the_search_legs_budget_has_no_room_for_the_pr_search() -> None: - import inspect +@pytest.mark.asyncio +async def test_the_search_legs_budget_has_no_room_for_the_pr_search(monkeypatch) -> None: + from unittest.mock import AsyncMock + from server.identity.domain.read_scope import WHOLE_NAMESPACE from server.memory.app.loom_search import tracker_leg - assert "related_prs=False" in inspect.getsource(tracker_leg.tracker_leg) + prepare = AsyncMock(return_value=types.SimpleNamespace(targets=(PUB,))) + monkeypatch.setattr("server.tracker.app.dupcheck.prepare_duplicate_check", prepare) + monkeypatch.setattr("server.identity.app.request_scope.request_scope", lambda: WHOLE_NAMESPACE) + monkeypatch.setattr("server.code.domain.scope.current_code_scope", lambda: (ORG, PUB)) + plan = await tracker_leg.prepare_tracker_search( + "LOGICAL_ERROR crash — already reported?", org=ORG + ) + assert plan is not None + prepare.assert_awaited_once() + assert prepare.await_args.args[0].related_prs is False sec = tracker_leg.lean_tracker_section( _output( verdict="duplicate_of", diff --git a/tests/unit/test_entity_communities_walked.py b/tests/unit/test_entity_communities_walked.py index 771d41d9ed..d85b7721b0 100644 --- a/tests/unit/test_entity_communities_walked.py +++ b/tests/unit/test_entity_communities_walked.py @@ -23,6 +23,7 @@ run_entity_communities, summarize_communities, ) +from server.observability.store.event_reads import MASKED_EVENTS class _CH: @@ -68,9 +69,9 @@ async def test_selection_is_the_union_of_opted_in_and_walked() -> None: optin_sql, _ = ch.calls[0] walked_sql, walked_params = ch.calls[1] assert "consolidation_enabled = true" in optin_sql - assert "FROM loom.agent_events AS a" in walked_sql + assert f"FROM {MASKED_EVENTS} AS a" in walked_sql # the ts range leads the predicate (agent_events is partitioned by month) - where = walked_sql.split("WHERE", 1)[1] + where = walked_sql.rsplit("WHERE", 1)[1] assert where.lstrip().startswith("a.ts >= now() - INTERVAL {days:UInt32} DAY") assert "a.operation IN {ops:Array(String)}" in walked_sql assert "a.success = true" in walked_sql and "n.active = true" in walked_sql diff --git a/tests/unit/test_entity_summary_handle_seed.py b/tests/unit/test_entity_summary_handle_seed.py index cb526cbe7f..0ee7992f03 100644 --- a/tests/unit/test_entity_summary_handle_seed.py +++ b/tests/unit/test_entity_summary_handle_seed.py @@ -99,3 +99,25 @@ def test_snake_case_non_entity_still_ignored(): known = frozenset({"00084_external_aggregation"}) out = seed("what is the memory_limit_exceeded remedy", [], known_entities=known) assert out == [] + + +def test_summary_seed_accepts256_in_original_order_with_cross_source_duplicates(): + existing = [f"entity{i:03d}" for i in range(254)] + assert seed( + "@entity000 @handle known known @HANDLE", + existing, + known_entities=frozenset({"entity000", "handle", "known"}), + ) == [*existing, "handle", "known"] + assert existing == [f"entity{i:03d}" for i in range(254)] + + +def test_summary_seed257_refuses_before_returning_a_truncated_union(): + import pytest + + from server.core.errors import VectorInputTooLargeError + + existing = [f"entity{i:03d}" for i in range(255)] + with pytest.raises(VectorInputTooLargeError, match="256") as raised: + seed("@handle known", existing, known_entities=frozenset({"known"})) + assert raised.value.code == "VECTOR_INPUT_TOO_LARGE" + assert existing == [f"entity{i:03d}" for i in range(255)] diff --git a/tests/unit/test_erasure_cache_key_axis.py b/tests/unit/test_erasure_cache_key_axis.py index 4a2528565b..f69933e156 100644 --- a/tests/unit/test_erasure_cache_key_axis.py +++ b/tests/unit/test_erasure_cache_key_axis.py @@ -453,34 +453,42 @@ async def _announce(changes: list[Any]) -> int: # --------------------------------------------------------------------------- -def test_events_scrub_rewrites_memory_key_and_the_identifier_args_in_one_mutation() -> None: +def test_events_scrub_rewrites_memory_key_and_identifier_args_in_both_streams() -> None: from server.observability.event_args import IDENTITY_KEYS ch = _RecCH(count=5) n = asyncio.run(memory_steps.scrub_events_by_user("o", "alice", ch=ch)) - assert n == 5 - sql, params = ch.commands[0] - assert sql.startswith( - "ALTER TABLE loom.agent_events UPDATE user_id = '', memory_key = if(memory_key = '', '', ''), args = mapApply((k, v) -> (k, if(k IN (" - ) - for key in ( - "memory_key", - "memory_keys", - "memory_id", - "thread_id", - "block_key", - "handoff_id", - "entity", - "subject", + assert n == 10 + assert len(ch.commands) == 2 + for table, (sql, params) in zip( + ("loom.agent_events", "loom.agent_events_private"), ch.commands, strict=True ): - assert f"'{key}'" in sql, key - # A gateway's end user is named by its subject too. - assert "WHERE (org = {org:String} AND (user_id = {uid:String} OR subject = {p:String}))" in sql - assert "subject = if(subject = {p:String}, '', subject)" in sql - assert (params["uid"], params["p"]) == ("alice", "user:alice") + assert sql.startswith( + f"ALTER TABLE {table} UPDATE user_id = '', memory_key = if(memory_key = '', '', ''), args = mapApply((k, v) -> (k, if(k IN (" + ) + for key in ( + "memory_key", + "memory_keys", + "memory_id", + "thread_id", + "block_key", + "handoff_id", + "entity", + "subject", + ): + assert f"'{key}'" in sql, key + # A gateway's end user is named by its subject too. + assert ( + "WHERE (org = {org:String} AND (user_id = {uid:String} OR subject = {p:String}))" in sql + ) + assert "subject = if(subject = {p:String}, '', subject)" in sql + assert (params["uid"], params["p"]) == ("alice", "user:alice") # the identity tuple never reaches args (event_args strips it); the scrub list is the rest assert not (set(memory_steps.ARGS_SCRUB_KEYS) & IDENTITY_KEYS) - assert erasure_census.STEP_ONLY_TABLES["agent_events.scrub"] == ("loom.agent_events",) + assert erasure_census.STEP_ONLY_TABLES["agent_events.scrub"] == ( + "loom.agent_events", + "loom.agent_events_private", + ) @pytest.mark.parametrize("scope", ["namespace", "user_id"]) diff --git a/tests/unit/test_erasure_late_steps.py b/tests/unit/test_erasure_late_steps.py index 8a4b989509..07da0cdecf 100644 --- a/tests/unit/test_erasure_late_steps.py +++ b/tests/unit/test_erasure_late_steps.py @@ -15,6 +15,7 @@ from server.erasure.store import census as erasure_census from server.erasure.store import mutations as erasure_mutations from server.erasure.store import steps_ledgers as ledger_steps +from tests.unit.definition_queue_fake import install class _StubCH: @@ -66,6 +67,17 @@ def test_conversations_user_scope_uses_the_user_column() -> None: assert "user_id = {uid:String}" in sql and params["uid"] == "alice" +def test_query_history_registration_leaves_with_its_namespace(monkeypatch) -> None: + install(monkeypatch) + ch = _StubCH() + count = asyncio.run(ledger_steps.delete_query_history_by_namespace("o", ["a", "b"], ch=ch)) + assert count == 1 + [(sql, params)] = ch.commands + assert "loom.query_history_sources" in sql + assert "org = {org:String}" in sql and params["org"] == "o" + assert "namespace IN {ns:Array(String)}" in sql and params["ns"] == ["a", "b"] + + @pytest.mark.parametrize( ("fn", "tables"), [ @@ -86,7 +98,11 @@ def test_conversations_user_scope_uses_the_user_column() -> None: (ledger_steps.delete_projection_failures_by_namespace, ["loom.memory_projection_failures"]), ], ) -def test_delete_steps_are_keyed_alter_deletes_over_the_namespace_list(fn, tables) -> None: +def test_delete_steps_are_keyed_alter_deletes_over_the_namespace_list( + fn, tables, monkeypatch +) -> None: + if fn is ledger_steps.delete_learnings_queue_by_namespace: + install(monkeypatch) ch = _StubCH(count=3) n = asyncio.run(fn("o", ["a", "b"], ch=ch)) assert n == 3 * len(tables) diff --git a/tests/unit/test_erasure_repo.py b/tests/unit/test_erasure_repo.py index 3c50dde655..1c2453a0ea 100644 --- a/tests/unit/test_erasure_repo.py +++ b/tests/unit/test_erasure_repo.py @@ -103,13 +103,19 @@ async def test_scrub_events_by_user_no_final_clause() -> None: """agent_events is MergeTree (append-only) — must NOT use FINAL on the count, that would be a syntax error.""" ch = StubCH() - ch.query_one_returns.append({"n": 7}) - await memory_steps.scrub_events_by_user("clickhouse", "alice", ch=ch) - sel_sql, _ = ch.query_one_calls[0] - assert "FROM loom.agent_events" in sel_sql - assert "FINAL" not in sel_sql - mut_sql, _ = ch.execute_calls[0] - assert "UPDATE user_id = ''" in mut_sql + ch.query_one_returns.extend([{"n": 7}, {"n": 3}]) + assert await memory_steps.scrub_events_by_user("clickhouse", "alice", ch=ch) == 10 + assert len(ch.query_one_calls) == len(ch.execute_calls) == 2 + for table, (sel_sql, _), (mut_sql, _) in zip( + ("loom.agent_events", "loom.agent_events_private"), + ch.query_one_calls, + ch.execute_calls, + strict=True, + ): + assert f"FROM {table}" in sel_sql and "FINAL" not in sel_sql + assert " ".join(mut_sql.split()).startswith( + f"ALTER TABLE {table} UPDATE user_id = ''" + ) @pytest.mark.asyncio diff --git a/tests/unit/test_erasure_step_order.py b/tests/unit/test_erasure_step_order.py index b3cdfab283..588af3483f 100644 --- a/tests/unit/test_erasure_step_order.py +++ b/tests/unit/test_erasure_step_order.py @@ -49,6 +49,14 @@ def run(monkeypatch: pytest.MonkeyPatch) -> Any: _SOURCES_RETIRE = ("knowledge_sources.retire", (("OTHER", "INSERT"), (D, "loom._migration_lock"))) +def _push_delete(namespaces: int) -> tuple[str, tuple[tuple[str, str], ...]]: + return ( + "knowledge_source_push.delete", + (("OTHER", "INSERT"), (D, "loom.knowledge_source_push"), (D, "loom._migration_lock")) + * namespaces, + ) + + USER_TRACE: list[tuple[str, tuple[tuple[str, str], ...]]] = [ ("memory.tombstone", ((U, "loom.memory"),)), ("memory_embeddings.tombstone", ((U, "loom.memory_embeddings"),)), @@ -60,7 +68,7 @@ def run(monkeypatch: pytest.MonkeyPatch) -> Any: ("working_memory.tombstone", ((U, "loom.working_memory"),)), ("shared_embeddings.tombstone", ((U, "loom.memory_embeddings"),)), ("shared.tombstone", ((U, "loom.shared"),)), - ("agent_events.scrub", ((U, "loom.agent_events"),)), + ("agent_events.scrub", ((U, "loom.agent_events"), (U, "loom.agent_events_private"))), ("derived_facts.delete", ((D, "loom.derived_facts"),)), ("memory_reinforcement.delete", ((D, "loom.memory_reinforcement"),)), ("raw_evidence.delete", ((D, "loom.memory_evidence"), (D, "loom.memory_extraction_queue"))), @@ -137,6 +145,7 @@ def run(monkeypatch: pytest.MonkeyPatch) -> Any: ("personal.retire", (("OTHER", "INSERT"),)), ("collections.forget_owner", (("OTHER", "INSERT"), ("OTHER", "INSERT"))), ("subject_last_seen.delete", ((D, "loom.subject_last_seen"),)), + ("tasks.delete", (("OTHER", "INSERT"), (D, "loom.task_events"), (D, "loom._migration_lock"))), ( "conversations.tombstone", ( @@ -253,9 +262,25 @@ def run(monkeypatch: pytest.MonkeyPatch) -> Any: ("memory_drops.delete", ((D, "loom.memory_drops"),)), ("delete_version_checks.delete", ((D, "loom.delete_version_checks"),)), ("memory_webhook_outbox.delete", ((D, "loom.memory_webhook_outbox"),)), - ("learnings_queue.delete", ((D, "loom.learnings_supporters"), (D, "loom.learnings_queue"))), + ( + "learnings_queue.delete", + ( + ("OTHER", "INSERT"), + (D, "loom.learnings_supporters"), + (D, "loom.learnings_queue"), + (D, "loom._migration_lock"), + ), + ), ("namespace_guides.delete", ((D, "loom.namespace_guides"),)), - ("tasks.delete", ((D, "loom.tasks"), (D, "loom.task_events"))), + ( + "tasks.delete", + ( + ("OTHER", "INSERT"), + (D, "loom.tasks"), + (D, "loom.task_events"), + (D, "loom._migration_lock"), + ), + ), ("agent_runs.delete", ((D, "loom.agent_run_claims"), (D, "loom.agent_runs"))), ( "curation.tombstone", @@ -266,6 +291,7 @@ def run(monkeypatch: pytest.MonkeyPatch) -> Any: ("idempotency.delete", ((D, "loom.idempotency"), (L, "loom.embedding_cache"))), ("code_index.purge", ()), ("knowledge_source_listings.delete", ((D, "loom.knowledge_source_listings"),)), + ("knowledge_group_members.delete", ((D, "loom.knowledge_group_members"),)), ("knowledge_mirrors.forget", ()), ] @@ -361,9 +387,25 @@ def run(monkeypatch: pytest.MonkeyPatch) -> Any: ("memory_drops.delete", ((D, "loom.memory_drops"),)), ("delete_version_checks.delete", ((D, "loom.delete_version_checks"),)), ("memory_webhook_outbox.delete", ((D, "loom.memory_webhook_outbox"),)), - ("learnings_queue.delete", ((D, "loom.learnings_supporters"), (D, "loom.learnings_queue"))), + ( + "learnings_queue.delete", + ( + ("OTHER", "INSERT"), + (D, "loom.learnings_supporters"), + (D, "loom.learnings_queue"), + (D, "loom._migration_lock"), + ), + ), ("namespace_guides.delete", ((D, "loom.namespace_guides"),)), - ("tasks.delete", ((D, "loom.tasks"), (D, "loom.task_events"))), + ( + "tasks.delete", + ( + ("OTHER", "INSERT"), + (D, "loom.tasks"), + (D, "loom.task_events"), + (D, "loom._migration_lock"), + ), + ), ("agent_runs.delete", ((D, "loom.agent_run_claims"), (D, "loom.agent_runs"))), ( "curation.tombstone", @@ -374,6 +416,7 @@ def run(monkeypatch: pytest.MonkeyPatch) -> Any: ("idempotency.delete", ((D, "loom.idempotency"), (L, "loom.embedding_cache"))), ("code_index.purge", ()), ("knowledge_source_listings.delete", ((D, "loom.knowledge_source_listings"),)), + ("knowledge_group_members.delete", ((D, "loom.knowledge_group_members"),)), ("knowledge_mirrors.forget", ()), ] @@ -395,7 +438,7 @@ def run(monkeypatch: pytest.MonkeyPatch) -> Any: ("working_memory.tombstone", ((D, "loom.working_memory"),)), ("shared_embeddings.tombstone", ((L, "loom.memory_embeddings"),)), ("shared.tombstone", ((D, "loom.shared"),)), - ("agent_events.scrub", ((U, "loom.agent_events"),)), + ("agent_events.scrub", ((U, "loom.agent_events"), (U, "loom.agent_events_private"))), ("derived_facts.delete", ((D, "loom.derived_facts"),)), ("memory_reinforcement.delete", ((D, "loom.memory_reinforcement"),)), ( @@ -512,6 +555,7 @@ def run(monkeypatch: pytest.MonkeyPatch) -> Any: ), ), ("subject_last_seen.delete", ((D, "loom.subject_last_seen"),)), + ("tasks.delete", (("OTHER", "INSERT"), (D, "loom.task_events"), (D, "loom._migration_lock"))), ( "conversations.tombstone", ( @@ -580,7 +624,19 @@ async def test_user_purge_saga_trace(run: Any) -> None: async def test_namespace_saga_trace( run: Any, scope_type: str, scope_value: str, backends: list[str] ) -> None: - want = [_SOURCES_RETIRE, *_with_tail(NS_TRACE, backends)] + want = [ + _SOURCES_RETIRE, + _push_delete(1 if scope_type == "namespace" else 2), + ( + "query_history_sources.delete", + ( + ("OTHER", "INSERT"), + (D, "loom.query_history_sources"), + (D, "loom._migration_lock"), + ), + ), + *_with_tail(NS_TRACE, backends), + ] assert await run(scope_type, scope_value) == want @@ -589,7 +645,19 @@ async def test_namespace_purge_saga_trace(run: Any, external: bool) -> None: """Under purge every tombstone becomes a delete: the wide tables by a lightweight DELETE, the narrow ones by an ALTER DELETE. Same steps.""" got = await run("namespace_list", _ns_list(purge=True, external=external)) - assert got == [_SOURCES_RETIRE, *_with_tail(NS_PURGE_TRACE, NS_BACKENDS if external else [])] + assert got == [ + _SOURCES_RETIRE, + _push_delete(2), + ( + "query_history_sources.delete", + ( + ("OTHER", "INSERT"), + (D, "loom.query_history_sources"), + (D, "loom._migration_lock"), + ), + ), + *_with_tail(NS_PURGE_TRACE, NS_BACKENDS if external else []), + ] @pytest.mark.parametrize(("scope_type", "scope_value"), [("user_id", "alice"), ("namespace", "a")]) diff --git a/tests/unit/test_erasure_verify.py b/tests/unit/test_erasure_verify.py index 85e5308999..ba84219e5f 100644 --- a/tests/unit/test_erasure_verify.py +++ b/tests/unit/test_erasure_verify.py @@ -137,7 +137,7 @@ def test_census_covers_every_substrate_and_uses_final_on_soft_deleted_tables() - out = asyncio.run(erasure_census.residue_census("o", "namespace", "ns", ch=ch)) assert set(out) == set(erasure_census.census_tables("namespace")) # every namespace-scoped substrate, entity, cache, chunk-link and code table - assert len(out) == 72 and sum(out.values()) == 0 + assert len(out) == 74 and sum(out.values()) == 0 by_table = {sql.split("FROM ")[1].split()[0]: sql for sql, _ in ch.query_one_calls} assert ( " FINAL" in by_table["loom.memory"] and "tombstoned_at IS NULL" in by_table["loom.memory"] @@ -149,6 +149,8 @@ def test_census_covers_every_substrate_and_uses_final_on_soft_deleted_tables() - " FINAL" not in by_table["loom.conversations"] and "tombstoned_at IS NULL" in by_table["loom.conversations"] ) + # Historical sealed versions must be gone too, not only the current version. + assert " FINAL" not in by_table["loom.knowledge_source_push"] assert " FINAL" in by_table["loom.conversation_threads"] assert " FINAL" not in by_table["loom.search_trace_log"] # The knowledge plane: chunks by the readers' live predicate (plain @@ -213,9 +215,10 @@ def test_census_user_scope_skips_namespace_only_tables() -> None: "loom.memory_ask_precedents", "loom.llm_response_cache", "loom.code_answers", + "loom.task_events", } <= set(out) assert "loom.memory_answers" not in out - assert len(out) == 54 + assert len(out) == 55 assert "loom.blob_uploads" in out # who uploaded what: the user's go # the user's supporter rows, and any bot-rule candidate left with no supporter assert {"loom.learnings_queue", "loom.learnings_supporters"} <= set(out) diff --git a/tests/unit/test_gdrive_push.py b/tests/unit/test_gdrive_push.py new file mode 100644 index 0000000000..075a2d606d --- /dev/null +++ b/tests/unit/test_gdrive_push.py @@ -0,0 +1,89 @@ +"""Drive channel requests use the provider API and bounded complete corpora.""" + +from __future__ import annotations + +from unittest.mock import AsyncMock + +import pytest + +from server.clients import gdrive_push as client +from server.clients._vendor import VendorError + + +@pytest.mark.asyncio +@pytest.mark.parametrize( + "result,expected", [({}, set()), ({"drives": [{"id": "drive"}]}, {"drive"})] +) +async def test_complete_memberships_include_empty_account( + monkeypatch: pytest.MonkeyPatch, result: dict, expected: set +) -> None: + monkeypatch.setattr(client, "bearer_get", AsyncMock(return_value=result)) + assert await client.member_drives("token") == expected + + +@pytest.mark.asyncio +@pytest.mark.parametrize( + "result", + [ + {"nextPageToken": "more"}, + {"drives": [{"id": str(i)} for i in range(20)]}, + {"drives": [{}]}, + {"drives": "wrong"}, + ], +) +async def test_incomplete_or_over_limit_memberships_refuse( + monkeypatch: pytest.MonkeyPatch, result: dict +) -> None: + monkeypatch.setattr(client, "bearer_get", AsyncMock(return_value=result)) + with pytest.raises(VendorError): + await client.member_drives("token") + + +@pytest.mark.asyncio +async def test_shared_drive_cursor_and_watch_name_same_corpus( + monkeypatch: pytest.MonkeyPatch, +) -> None: + monkeypatch.setattr(client.time, "time", lambda: 1000) + cursor = AsyncMock(return_value={"startPageToken": "cursor"}) + watch = AsyncMock( + return_value={"id": "channel", "resourceId": "resource", "expiration": "2000000"} + ) + monkeypatch.setattr(client, "bearer_get", cursor) + monkeypatch.setattr(client, "request_json", watch) + result = await client.watch( + "token", + channel_id="channel", + channel_token="proof", + address="https://loom.example/hook", + drive_id="drive", + ) + assert cursor.call_args.kwargs["params"]["driveId"] == "drive" + assert watch.call_args.kwargs["params"]["driveId"] == "drive" + assert watch.call_args.kwargs["params"]["pageToken"] == "cursor" + assert watch.call_args.kwargs["json"]["token"] == "proof" + assert result["resource_id"] == "resource" and result["expiration"] == 2000 + + +@pytest.mark.asyncio +@pytest.mark.parametrize( + "response", + [ + {"id": "other", "resourceId": "resource", "expiration": "2000000"}, + {"id": "channel", "expiration": "2000000"}, + {"id": "channel", "resourceId": "resource", "expiration": "bad"}, + ], +) +async def test_watch_response_must_bind_requested_channel( + monkeypatch: pytest.MonkeyPatch, response: dict +) -> None: + monkeypatch.setattr(client.time, "time", lambda: 1000) + monkeypatch.setattr(client, "bearer_get", AsyncMock(return_value={"startPageToken": "cursor"})) + monkeypatch.setattr(client, "request_json", AsyncMock(return_value=response)) + with pytest.raises(VendorError): + await client.watch( + "token", + channel_id="channel", + channel_token="proof", + address="https://loom.example/hook", + drive_id="", + ) diff --git a/tests/unit/test_health_error_text.py b/tests/unit/test_health_error_text.py index 7c6e203e60..0e05dab47c 100644 --- a/tests/unit/test_health_error_text.py +++ b/tests/unit/test_health_error_text.py @@ -169,7 +169,11 @@ def test_an_extra_analyst_grant_names_no_database( from server.observability import problems async def run(sql: str, **_: Any) -> Any: - if sql.startswith("SELECT count()") and "system." not in sql: + if ( + sql.startswith("SELECT count()") + and "system." not in sql + and ".agent_events_private" not in sql + ): return [], [], [(1,)] if boundary.CANARY_TABLE in sql else [(0,)] raise RuntimeError("Code: 497. DB::Exception: Not enough privileges") diff --git a/tests/unit/test_helm_cell_probe.py b/tests/unit/test_helm_cell_probe.py new file mode 100644 index 0000000000..9c254bd058 --- /dev/null +++ b/tests/unit/test_helm_cell_probe.py @@ -0,0 +1,127 @@ +"""The standalone render gate and pytest exercise the same cell probe contract.""" + +from __future__ import annotations + +import shutil +from pathlib import Path +from typing import Any + +import pytest + +from scripts.gates import helm_cell_probe as probe + +ENABLED = probe.ENABLED +pytestmark = pytest.mark.skipif( + not shutil.which("helm"), reason="needs helm (the CI helm job runs it)" +) + + +@pytest.mark.parametrize("workers", [False, True]) +def test_probe_is_off_by_default_even_with_other_env_sources(workers: bool) -> None: + probe.check_probe_is_off_by_default_even_with_other_env_sources(workers) + + +@pytest.mark.parametrize("workers", [False, True]) +def test_probe_selects_every_listener_workload_and_no_hook_or_test_pod(workers: bool) -> None: + probe.check_probe_selects_every_listener_workload_and_no_hook_or_test_pod(workers) + + +@pytest.mark.parametrize( + "overlay", + [ + (), + ("values-kind.yaml",), + ("values-eks.yaml",), + ("values-eks.yaml", "values-clickhouse-cloud.yaml"), + ], +) +@pytest.mark.parametrize("policy", [False, True]) +def test_probe_changes_no_traffic_route_or_network_policy( + overlay: tuple[str, ...], policy: bool +) -> None: + probe.check_probe_changes_no_traffic_route_or_network_policy(overlay, policy) + + +@pytest.mark.parametrize("port", [1, 7776, 7778, 65535]) +def test_numeric_ports_reach_listener_and_service(port: int) -> None: + probe.check_numeric_ports_reach_listener_and_service(port) + + +@pytest.mark.parametrize("port", [0, ENABLED]) +def test_values_file_and_json_numbers_are_accepted(tmp_path: Path, port: int) -> None: + probe.check_values_file_and_json_numbers_are_accepted(tmp_path, port) + + +@pytest.mark.parametrize("value", [None, {"port": None}]) +def test_an_absent_port_after_value_coalescing_is_off(value: Any) -> None: + probe.check_an_absent_port_after_value_coalescing_is_off(value) + + +@pytest.mark.parametrize("port", [0, ENABLED]) +def test_the_explicit_port_takes_precedence_over_env_from(port: int) -> None: + probe.check_the_explicit_port_takes_precedence_over_env_from(port) + + +@pytest.mark.parametrize("port", [0, ENABLED]) +def test_every_configured_pod_has_one_explicit_port_beside_external_env_from(port: int) -> None: + probe.check_every_configured_pod_has_one_explicit_port_beside_external_env_from(port) + + +def test_probe_service_keeps_its_suffix_with_a_long_fullname() -> None: + probe.check_probe_service_keeps_its_suffix_with_a_long_fullname() + + +@pytest.mark.parametrize("value", [-1, 65536, 7777, 8777.5, True, False, "8777", "0", "", [], {}]) +def test_bad_probe_ports_are_refused_by_name(value: Any) -> None: + probe.check_bad_probe_ports_are_refused_by_name(value) + + +@pytest.mark.parametrize("value", ["0", "8777"]) +def test_set_string_ports_are_refused(value: str) -> None: + probe.check_set_string_ports_are_refused(value) + + +@pytest.mark.parametrize("value", [False, True, "8777", 8777, []]) +def test_bad_probe_blocks_are_refused_by_name(value: Any) -> None: + probe.check_bad_probe_blocks_are_refused_by_name(value) + + +@pytest.mark.parametrize("port", [0, ENABLED]) +@pytest.mark.parametrize("source", ["env", "extraEnv", "secrets.extra", "settingsFile"]) +def test_probe_port_cannot_be_set_twice(port: int, source: str) -> None: + probe.check_probe_port_cannot_be_set_twice(port, source) + + +@pytest.mark.parametrize("value", ["false", "true"]) +def test_user_pod_labels_cannot_override_probe_endpoint_membership(value: str) -> None: + probe.check_user_pod_labels_cannot_override_probe_endpoint_membership(value) + + +@pytest.mark.parametrize("policy", [False, True]) +def test_the_main_service_and_ingress_use_the_web_http_port(policy: bool) -> None: + probe.check_the_main_service_and_ingress_use_the_web_http_port(policy) + + +def test_other_settings_and_pod_labels_still_render() -> None: + probe.check_other_settings_and_pod_labels_still_render() + + +@pytest.mark.parametrize( + ("name", "through"), + [ + ("LOOM_EMBEDDING_PROVIDER", "embedding.*"), + ("LOOM_EMBEDDING_MODEL", "embedding.*"), + ("LOOM_EMBEDDING_DIM", "embedding.*"), + ("LOOM_EMBEDDING_BASE_URL", "embedding.*"), + ("LOOM_EMBEDDING_SEND_DIMENSIONS", "embedding.*"), + ("LOOM_JWT_SECRET", "secrets.jwtSecret"), + ("LOOM_JWT_SECRET_PREVIOUS", "secrets.jwtSecretPrevious"), + ], +) +@pytest.mark.parametrize("source", ["env", "extraEnv", "secrets.extra", "settingsFile"]) +def test_existing_embedding_and_root_names_keep_their_config_route_refusal( + name: str, through: str, source: str +) -> None: + probe.check_existing_embedding_and_root_names_keep_their_config_route_refusal( + name, through, source + ) diff --git a/tests/unit/test_i18n.py b/tests/unit/test_i18n.py index b4aad1fd35..3f65e57a3c 100644 --- a/tests/unit/test_i18n.py +++ b/tests/unit/test_i18n.py @@ -7,8 +7,8 @@ import pathlib import re +import subprocess import sys -import time import types from collections import Counter @@ -20,10 +20,10 @@ ROOT = t.ROOT -@pytest.mark.parametrize("source", t.SOURCES) -def test_a_page_cuts_into_sections_that_join_back_to_it(source: str) -> None: +@pytest.mark.parametrize("source", t.sources()) +def test_page_requests_reconstruct_the_anchored_source(source: str) -> None: text, _ = t.prepare(source, t.LANGUAGES[0]) - assert "\n".join(t.sections(text)) == text + assert "\n".join(t.english_requests(text)) == t.anchor_headings(text, Counter()) def test_a_short_page_goes_in_one_request_and_a_long_one_by_section() -> None: @@ -36,9 +36,10 @@ def test_a_short_page_goes_in_one_request_and_a_long_one_by_section() -> None: assert '' in joined and '' in joined -def test_sections_start_at_level_two_headings_outside_code() -> None: - page = "# Title\n\nintro\n\n## One\n\n```md\n## not a heading\n```\n\n## Two\n" - assert [s.split("\n")[0] for s in t.sections(page)] == ["# Title", "## One", "## Two"] +def test_request_heading_cuts_ignore_fenced_headings() -> None: + page = "# Title\n\n" + "Loom\n\n" * 1400 + page += "## One\n\n```md\n## not a heading\n```\n\n## Two\n" + assert [s.split("\n")[2] for s in t.english_requests(page)] == ["# Title", "## One", "## Two"] def test_anchors_follow_github_slugs_across_sections() -> None: @@ -49,15 +50,42 @@ def test_anchors_follow_github_slugs_across_sections() -> None: assert '' in first and '' in second -@pytest.mark.parametrize("source", t.SOURCES) +@pytest.mark.parametrize("source", t.sources()) def test_anchors_match_the_ones_the_english_links_are_checked_against(source: str) -> None: seen: Counter[str] = Counter() page = t.anchor_headings(t.prepare(source, t.LANGUAGES[0])[0], seen) ids = re.findall(r'^$', page, re.MULTILINE) - assert set(ids) == markdown_links.anchors(ROOT / source) + explicit = { + m.group(1) + for line, code in t.outside_fences((ROOT / source).read_text()) + if not code and (m := t.ANCHOR.match(line)) + } + assert set(ids) == markdown_links.anchors(ROOT / source) | explicit + + +@pytest.fixture +def link_repository(update_repository: None) -> None: + for source in ( + "docs/use-cases/agent-memory.md", + "docs/use-cases/multi-agent.md", + "docs/operations/deployment.md", + "docs/concepts/memory.md", + ): + path = t.ROOT / source + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text("# Source\n") + subprocess.run(["git", "add", "docs"], cwd=t.ROOT, check=True) + for code, source in ( + ("ja", "docs/use-cases/agent-memory.md"), + ("ko", "docs/use-cases/agent-memory.md"), + ("ko", "docs/use-cases/multi-agent.md"), + ): + path = t.ROOT / t.target_path(code, source) + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text('\n# Translated\n') -def test_links_point_at_translations_or_the_english_files() -> None: +def test_links_point_at_translations_or_the_english_files(link_repository: None) -> None: page = ( "[uc](../use-cases/agent-memory.md#measured) [ops](../operations/deployment.md) " "![shot](../images/a.png) [web](https://example.com/x) [here](#local)" @@ -69,7 +97,7 @@ def test_links_point_at_translations_or_the_english_files() -> None: assert "[web](https://example.com/x)" in out and "[here](#local)" in out -def test_html_links_badges_and_reference_definitions_are_rewritten() -> None: +def test_html_links_badges_and_reference_definitions_are_rewritten(link_repository: None) -> None: page = ( '[![badge](b.svg)](agent-memory.md) ![i](a.png) m ' 'x \n\n[ref]: ../concepts/memory.md\n' @@ -82,7 +110,7 @@ def test_html_links_badges_and_reference_definitions_are_rewritten() -> None: assert f"[ref]: {blob}/concepts/memory.md" in out -def test_links_inside_code_are_left_alone() -> None: +def test_links_inside_code_are_left_alone(link_repository: None) -> None: page = 'See `[a](b.md)` and:\n\n```md\n[a](b.md) \n```\n\n[a](b.md)\n' out = t.rewrite_links(page, "docs/use-cases/index.md", "ja") assert out.count("[a](b.md)") == 2 and '' in out @@ -221,7 +249,7 @@ def test_the_cost_cap_is_checked_before_the_next_call() -> None: spend.add({"input_tokens": 0, "output_tokens": 1000}) with pytest.raises(SystemExit, match="LOOM_I18N_MAX_USD"): spend.before_call() - assert spend.stopped.is_set() + assert spend.stopped def test_a_label_borrowed_from_another_section_keeps_the_page_unwritten( @@ -237,51 +265,72 @@ def test_a_label_borrowed_from_another_section_keeps_the_page_unwritten( monkeypatch.setattr( t, "translate_text", - lambda text, lang, client, spend: replies["A" if "## A" in text else "B"], + lambda text, lang, client, spend, **_kwargs: replies["A" if "## A" in text else "B"], ) with pytest.raises(t.TranslationDiffers, match="Get a token"): t.translate_page("docs/x.md", t.LANGUAGES[1], None, t.Spend("claude-sonnet-5-5", 1.0)) assert not (tmp_path / "i18n").exists() +@pytest.fixture +def update_repository(tmp_path: pathlib.Path, monkeypatch: pytest.MonkeyPatch) -> None: + for args in ( + ("init", "-q"), + ("config", "user.name", "test"), + ("config", "user.email", "test@example.test"), + ): + subprocess.run(["git", *args], cwd=tmp_path, check=True, capture_output=True) + for source in ("README.md", "docs/a.md", "docs/b.md"): + path = tmp_path / source + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text("# Start\n") + subprocess.run(["git", "add", "."], cwd=tmp_path, check=True) + subprocess.run(["git", "commit", "-qm", "English"], cwd=tmp_path, check=True) + monkeypatch.setattr(t, "ROOT", tmp_path) + + def test_a_page_that_still_differs_lets_the_others_finish( monkeypatch: pytest.MonkeyPatch, + update_repository: None, ) -> None: written: list[str] = [] def fake_page(source: str, lang: t.Language, client: object, spend: t.Spend) -> None: - if source == t.SOURCES[0]: + if source == t.sources()[0]: raise t.TranslationDiffers("still differs after a retry") written.append(source) + text, line = t.prepare(source, lang) + body = "\n".join(t.english_requests(text)).replace("# Start", "# Entrée") + t.lifecycle.stage( + t.target_path(lang.code, source), t.render(source, lang, body, line, spend.model) + ) monkeypatch.setattr(t, "bedrock_client", lambda: None) monkeypatch.setattr(t, "translate_page", fake_page) - monkeypatch.setattr(t, "write_language_lines", lambda: None) + monkeypatch.setattr(t, "write_language_lines", lambda codes=None: None) monkeypatch.setattr(t, "request_chars", lambda source, lang: 1) with pytest.raises( SystemExit, match="pages not written:\ni18n/ja/README.md: still differs after a retry" ): t.update(every=True, codes=["ja"]) - assert sorted(written) == sorted(t.SOURCES[1:]) + assert sorted(written) == sorted(t.sources()[1:]) def test_a_fatal_error_after_a_differing_page_still_names_that_page( monkeypatch: pytest.MonkeyPatch, + update_repository: None, ) -> None: def fake_page(source: str, lang: t.Language, client: object, spend: t.Spend) -> None: - if source == t.SOURCES[0]: + if source == t.sources()[0]: raise t.TranslationDiffers("still differs after a retry") - time.sleep(0.05) raise SystemExit("Bedrock 500") monkeypatch.setattr(t, "bedrock_client", lambda: None) monkeypatch.setattr(t, "translate_page", fake_page) - monkeypatch.setattr(t, "write_language_lines", lambda: None) + monkeypatch.setattr(t, "write_language_lines", lambda codes=None: None) monkeypatch.setattr(t, "request_chars", lambda source, lang: 1) - with pytest.raises(SystemExit) as stopped: + with pytest.raises(SystemExit, match="Bedrock 500"): t.update(every=True, codes=["ja"]) - message = str(stopped.value) - assert "Bedrock 500" in message and "not written: i18n/ja/README.md" in message def test_code_inside_an_html_link_is_not_a_label() -> None: @@ -295,36 +344,26 @@ def test_a_link_or_alt_text_shown_as_code_is_not_a_label() -> None: def test_a_fatal_error_stops_the_other_pages( - monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] + monkeypatch: pytest.MonkeyPatch, + capsys: pytest.CaptureFixture[str], + update_repository: None, ) -> None: calls: list[str] = [] def fake_page(source: str, lang: t.Language, client: object, spend: t.Spend) -> None: - if source == t.SOURCES[0]: - raise SystemExit("boom") - for _ in range(200): - spend.before_call() - calls.append(source) - time.sleep(0.005) + calls.append(source) + raise SystemExit("boom") monkeypatch.setattr(t, "bedrock_client", lambda: None) monkeypatch.setattr(t, "translate_page", fake_page) - monkeypatch.setattr(t, "write_language_lines", lambda: None) + monkeypatch.setattr(t, "write_language_lines", lambda codes=None: None) monkeypatch.setattr(t, "request_chars", lambda source, lang: 1) with pytest.raises(SystemExit, match="boom"): t.update(every=True, codes=["ja"]) - # Pages already running stop at their next call, and no more than one per worker started. - assert len(set(calls)) <= t.WORKERS and t.SOURCES[-1] not in calls and len(calls) < 200 + assert calls == [t.sources()[0]] assert "spent:" in capsys.readouterr().out -def test_a_missing_source_stops_check_and_update(monkeypatch: pytest.MonkeyPatch) -> None: - monkeypatch.setattr(t, "SOURCES", (*t.SOURCES, "docs/no-such-page.md")) - for command in (t.check, t.update): - with pytest.raises(SystemExit, match="no-such-page.md"): - command() - - @pytest.mark.parametrize( "args", [["check", "--all"], ["check", "--lang", "ja"], ["update", "--skip-stale"]] ) @@ -333,24 +372,34 @@ def test_each_command_refuses_the_other_ones_flags(args: list[str]) -> None: t.main(args) -def test_another_model_or_banner_makes_every_page_stale() -> None: +def test_another_model_or_banner_makes_every_page_stale(update_repository: None) -> None: ja = t.LANGUAGES[1] - assert t.stale((ja,), model="claude-opus-5-5") == [(s, ja) for s in t.SOURCES] + for source in t.sources(): + path = t.ROOT / t.target_path(ja.code, source) + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(t.header(source, ja, t.DEFAULT_MODEL, t.blob(source)) + "# Inicio\n") + assert t.stale((ja,), model=t.DEFAULT_MODEL) == [] + assert t.stale((ja,), model="claude-opus-5-5") == [(s, ja) for s in t.sources()] edited = t.Language(ja.code, ja.name, ja.english, ja.banner + "!", ja.style) - assert len(t.stale((edited,))) == len(t.SOURCES) + assert len(t.stale((edited,))) == len(t.sources()) -def test_an_unpriced_model_is_refused(monkeypatch: pytest.MonkeyPatch) -> None: +def test_an_unpriced_model_is_refused( + monkeypatch: pytest.MonkeyPatch, update_repository: None +) -> None: monkeypatch.setenv("LOOM_I18N_MODEL", "some-model") with pytest.raises(SystemExit, match="no price"): t.update() -def test_the_estimate_refuses_a_run_over_the_cap(monkeypatch: pytest.MonkeyPatch) -> None: - monkeypatch.setenv("LOOM_I18N_MAX_USD", "0.001") - monkeypatch.setattr(t, "write_language_lines", lambda: None) - with pytest.raises(SystemExit, match="nothing translated"): - t.update(every=True, codes=["ja"]) +def test_the_estimate_defers_pages_outside_the_batch_cap( + monkeypatch: pytest.MonkeyPatch, update_repository: None +) -> None: + monkeypatch.setattr( + t, "bedrock_client", lambda: pytest.fail("deferred pages must not call Bedrock") + ) + selected, deferred = t.batch(True, ["ja"], 0) + assert not selected and deferred == len(t.sources()) def test_a_section_that_differs_is_retried_once_with_the_differences( @@ -402,6 +451,14 @@ def test_a_new_language_is_linked_from_every_readme_without_translating( for path in t.readmes(): (tmp_path / path).parent.mkdir(parents=True, exist_ok=True) (tmp_path / path).write_text((ROOT / path).read_text()) + for args in ( + ("init", "-q"), + ("config", "user.name", "test"), + ("config", "user.email", "test@example.test"), + ("add", "."), + ("commit", "-qm", "Copied documentation"), + ): + subprocess.run(["git", *args], cwd=tmp_path, check=True, capture_output=True) monkeypatch.setattr(t, "ROOT", tmp_path) ja = t.LANGUAGES[1] extra = t.Language("xx", "Xx", "Xx", ja.banner, ja.style) @@ -409,29 +466,117 @@ def test_a_new_language_is_linked_from_every_readme_without_translating( assert t.language_lines_differ() == t.readmes() t.write_language_lines() assert t.language_lines_differ() == [] - assert 'Xx' in (tmp_path / "i18n/ja/README.md").read_text() + text = (tmp_path / "i18n/ja/README.md").read_text() + assert "Xx" in text and "../xx/README.md" not in text + + +def test_translated_readme_links_to_its_existing_site_landing(tmp_path, monkeypatch) -> None: + from scripts.docs_site import indexnow + + monkeypatch.setattr(t, "ROOT", tmp_path) + monkeypatch.setattr(indexnow, "SITE", "https://example.com/docs/") + for source in ("README.md", "docs/index.md", "docs/use-cases/index.md"): + path = tmp_path / source + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text("# Source\n") + monkeypatch.setattr( + t, "sources", lambda: ("README.md", "docs/index.md", "docs/use-cases/index.md") + ) + spanish = next(lang for lang in t.LANGUAGES if lang.code == "es") + for source in ("README.md", "docs/use-cases/index.md"): + path = tmp_path / t.target_path("es", source) + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(t.header(source, spanish, t.DEFAULT_MODEL, "a" * 40) + "# Página\n") + assert 'Documentación' in t.language_line( + "i18n/es/README.md" + ) + assert "https://example.com" not in t.language_line("README.md") + path = tmp_path / "i18n/es/docs/index.md" + path.write_text(t.header("docs/index.md", spanish, t.DEFAULT_MODEL, "a" * 40) + "# Inicio\n") + assert 'Documentación' in t.language_line( + "i18n/es/README.md" + ) + path.unlink() + (tmp_path / "i18n/es/docs/use-cases/index.md").unlink() + assert "https://example.com" not in t.language_line("i18n/es/README.md") + + +def test_generated_readme_uses_the_same_site_base_as_mkdocs() -> None: + import yaml + + from scripts.docs_site import indexnow + + config = yaml.compose((ROOT / "mkdocs.yml").read_text()) + site_url = next(value.value for key, value in config.value if key.value == "site_url") + assert site_url == indexnow.SITE + + +@pytest.mark.parametrize( + "sources,expected,route", + [ + ( + ("getting-started/quickstart.md",), + "getting-started/quickstart.md", + "getting-started/quickstart/", + ), + (("zeta.md", "guide.md"), "guide.md", "guide/"), + (('guide "advanced".md',), 'guide "advanced".md', "guide%20%22advanced%22/"), + (("guía & casos.md",), "guía & casos.md", "gu%C3%ADa%20%26%20casos/"), + ], +) +def test_readme_keeps_a_native_site_link_without_a_translated_index( + tmp_path, monkeypatch, sources, expected, route +) -> None: + from html.parser import HTMLParser + + from scripts.docs_site import indexnow, locales + + class Links(HTMLParser): + def handle_starttag(self, tag, attrs): + if tag == "a" and dict(attrs).get("href", "").startswith(indexnow.SITE): + links.append(dict(attrs)) + + monkeypatch.setattr(t, "ROOT", tmp_path) + language = next(lang for lang in t.LANGUAGES if lang.code == "ja") + for source in ("README.md", *("docs/" + source for source in sources)): + english = tmp_path / source + english.parent.mkdir(parents=True, exist_ok=True) + english.write_text("# Loom\n") + target = tmp_path / t.target_path(language.code, source) + target.parent.mkdir(parents=True, exist_ok=True) + target.write_text(t.header(source, language, t.DEFAULT_MODEL, t.blob(source)) + "# Loom\n") + uri = locales.landing_uri(language.code, locales.translations(tmp_path)) + assert uri == language.code + "/" + expected + links = [] + Links().feed(t.language_line("i18n/ja/README.md")) + assert links == [{"href": indexnow.SITE + "ja/" + route}] def _translations() -> list[tuple[str, t.Language]]: return [ (s, lang) - for s in t.SOURCES + for s in t.sources() for lang in t.LANGUAGES if (ROOT / t.target_path(lang.code, s)).is_file() ] -def test_every_use_case_page_is_translated() -> None: +def test_every_use_case_page_is_in_source_inventory() -> None: pages = {p.relative_to(ROOT).as_posix() for p in (ROOT / "docs/use-cases").glob("*.md")} - assert pages <= set(t.SOURCES) + assert pages <= set(t.sources()) -def test_no_translation_is_orphaned() -> None: - assert t.orphans() == [] +def test_every_output_has_generator_ownership() -> None: + for path in t.lifecycle.all_files(): + assert t.lifecycle.regular(path) + if path == t.refresh.PATH: + assert t.refresh.read() is not None + else: + assert t.lifecycle.owner(path, (t.ROOT / path).read_text()) is not None, path def test_every_translation_exists_with_its_stamp_and_banner() -> None: - assert len(_translations()) == len(t.SOURCES) * len(t.LANGUAGES) + assert _translations() for source, lang in _translations(): text = (ROOT / t.target_path(lang.code, source)).read_text() stamp = t.STAMP.match(text) @@ -439,42 +584,25 @@ def test_every_translation_exists_with_its_stamp_and_banner() -> None: assert "Machine-translated from the [English page]" in text.split("\n\n", 1)[0] -def test_an_anchor_into_a_stale_page_waits_for_that_page( - monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path -) -> None: - (tmp_path / "i18n/ja").mkdir(parents=True) - (tmp_path / "i18n/ja/a.md").write_text("[b](b.md#new-heading)\n") - (tmp_path / "i18n/ja/b.md").write_text('\n') - monkeypatch.setattr(t, "ROOT", tmp_path) - assert len(t.link_problems()) == 1 - assert t.link_problems(frozenset({"i18n/ja/b.md"})) == [] - # The other way round: a's link is old, b is new. - assert t.link_problems(frozenset({"i18n/ja/a.md"})) == [] - - -def test_check_skips_anchors_of_stale_pages_only_when_asked( +def test_async_check_still_rejects_a_missing_anchor( monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path, capsys: pytest.CaptureFixture[str] ) -> None: ja = t.LANGUAGES[1] - (tmp_path / "i18n/ja").mkdir(parents=True) - (tmp_path / "i18n/ja/a.md").write_text("[b](b.md#new-heading)\n") - (tmp_path / "i18n/ja/b.md").write_text('\n') + (tmp_path / "i18n/ja/docs").mkdir(parents=True) + for name, body in (("a", "[b](b.md#new-heading)\n"), ("b", '\n')): + source = f"docs/{name}.md" + (tmp_path / t.target_path("ja", source)).write_text( + t.header(source, ja, t.DEFAULT_MODEL, "0" * 40) + body + ) monkeypatch.setattr(t, "ROOT", tmp_path) - monkeypatch.setattr(t, "require_sources", lambda: None) - monkeypatch.setattr(t, "orphans", lambda: []) - monkeypatch.setattr(t, "untranslated_pages", lambda: []) - monkeypatch.setattr(t, "language_lines_differ", lambda: []) - monkeypatch.setattr(t, "stale", lambda model=t.DEFAULT_MODEL: [("b.md", ja)]) - assert t.check(skip_stale=True) == 0 - assert t.check() == 1 - out = capsys.readouterr().out - assert "i18n/ja/a.md links to b.md#new-heading, which has no such anchor" in out + monkeypatch.setattr(t, "sources", lambda: ()) + assert t.check(skip_stale=True) == 1 + assert "which has no such anchor" in capsys.readouterr().out def test_the_committed_translations_pass_check() -> None: """Fresh or not, every committed page keeps its links, anchors and translated labels.""" - assert t.link_problems() == [] - assert t.untranslated_pages() == [] + assert t.check(skip_stale=True) == 0 class _StatusError(Exception): @@ -580,3 +708,57 @@ def test_a_lost_connection_is_retried_up_to_four_attempts(monkeypatch: pytest.Mo with pytest.raises(SystemExit, match="unreachable"): t.call(types.SimpleNamespace(messages=messages), "claude-sonnet-5-5", "s", []) assert len(messages.sent) == 4 + + +def test_update_cli_selects_only_rollout_languages_by_default( + monkeypatch: pytest.MonkeyPatch, +) -> None: + calls: list[tuple[bool, list[str] | None]] = [] + monkeypatch.setattr(t, "update", lambda every, codes: calls.append((every, codes)) or 0) + assert t.ROLLOUT_LANGUAGES == ("zh-CN", "ja", "ko", "pt-BR", "es") + assert {language.code for language in t.LANGUAGES} == {"zh-CN", "ja", "ko", "pt-BR", "es"} + assert t.main(["update"]) == 0 + assert calls == [(False, list(t.ROLLOUT_LANGUAGES))] + + +@pytest.mark.parametrize("code", ["fr", "id", "xx"]) +def test_update_cli_refuses_additional_languages_before_any_mutation( + monkeypatch: pytest.MonkeyPatch, + code: str, +) -> None: + ja = t.LANGUAGES[1] + extra = t.Language(code, code, code, ja.banner, ja.style) + monkeypatch.setattr(t, "LANGUAGES", (*t.LANGUAGES, extra)) + monkeypatch.setattr(t, "update", lambda *args: pytest.fail("additional locale reached update")) + with pytest.raises(SystemExit): + t.main(["update", "--all", "--lang", code]) + + +@pytest.mark.parametrize("code", ["zh-CN", "ja", "ko", "pt-BR", "es"]) +def test_update_cli_accepts_each_retained_locale( + monkeypatch: pytest.MonkeyPatch, code: str +) -> None: + calls: list[tuple[bool, list[str]]] = [] + monkeypatch.setattr(t, "update", lambda every, codes: calls.append((every, codes)) or 0) + assert t.main(["update", "--lang", code]) == 0 + assert calls == [(False, [code])] + + +def test_language_line_maintenance_preserves_nonselected_locale_bytes( + tmp_path: pathlib.Path, + monkeypatch: pytest.MonkeyPatch, +) -> None: + monkeypatch.setattr(t, "ROOT", tmp_path) + original = "# Loom\n\nretained\n" + paths = ["README.md"] + [t.target_path(lg.code, "README.md") for lg in t.LANGUAGES] + for name in paths: + path = tmp_path / name + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(original) + t.write_language_lines(["ja"]) + for name in paths: + text = (tmp_path / name).read_text() + if name in {"README.md", "i18n/ja/README.md"}: + assert t.language_line(name) in text + else: + assert text == original diff --git a/tests/unit/test_i18n_automation.py b/tests/unit/test_i18n_automation.py new file mode 100644 index 0000000000..b9fcc31022 --- /dev/null +++ b/tests/unit/test_i18n_automation.py @@ -0,0 +1,847 @@ +"""Translation automation admits generated data and books allowance before provider calls.""" + +from __future__ import annotations + +import json +import os +import subprocess +from decimal import Decimal +from pathlib import Path +from typing import Any + +import pytest +import yaml + +from scripts.i18n import automation as a + + +@pytest.fixture +def repository(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path: + monkeypatch.setattr(a.t, "ROOT", tmp_path) + a.git("init", "-q", "-b", "main") + a.configure_git() + (tmp_path / ".github/workflows").mkdir(parents=True) + (tmp_path / ".github/workflows/ci.yml").write_text("name: trusted\n") + (tmp_path / "README.md").write_text("# English\n") + a.git("add", ".") + a.git("commit", "-qm", "English source") + return tmp_path + + +def commit_all() -> str: + a.git("add", ".") + a.git("commit", "-qm", "Generated data") + return a.git("rev-parse", "HEAD") + + +def output(repository: Path, source: str = "README.md", code: str = "ja") -> Path: + lang = next(lang for lang in a.t.LANGUAGES if lang.code == code) + path = repository / a.t.target_path(lang.code, source) + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(a.t.header(source, lang, a.t.DEFAULT_MODEL, a.t.blob(source)) + "# 日本語\n") + return path + + +def test_publisher_accepts_generated_data_and_refuses_workflow_changes(repository: Path) -> None: + base = a.git("rev-parse", "HEAD") + output(repository) + a.validate_changes(base, commit_all()) + (repository / ".github/workflows/ci.yml").write_text("name: hostile\n") + with pytest.raises(ValueError, match="refuses path"): + a.validate_changes(base, commit_all()) + + +def test_publisher_refuses_plain_files_and_symlinks(repository: Path) -> None: + base = a.git("rev-parse", "HEAD") + path = repository / "i18n/ja/private.md" + path.parent.mkdir(parents=True) + path.write_text("not generated\n") + with pytest.raises(ValueError, match="refuses path"): + a.validate_changes(base, commit_all()) + path.unlink() + path.symlink_to("../../README.md") + with pytest.raises(ValueError, match="nonregular"): + a.validate_changes(base, commit_all()) + + +def test_publisher_refuses_stale_generated_output(repository: Path) -> None: + base = a.git("rev-parse", "HEAD") + path = output(repository) + path.write_text(path.read_text().replace(a.t.blob("README.md"), "0" * 40)) + with pytest.raises(ValueError, match="refuses path"): + a.validate_changes(base, commit_all()) + + +def test_publisher_refuses_deletion_of_live_generated_output(repository: Path) -> None: + path = output(repository) + base = commit_all() + path.unlink() + with pytest.raises(ValueError, match="refuses path"): + a.validate_changes(base, commit_all()) + + +def test_publisher_accepts_only_generated_readme_language_line(repository: Path) -> None: + path = repository / "README.md" + path.write_text("# English\n\nold\n") + base = commit_all() + path.write_text("# English\n\n" + a.t.language_line("README.md") + "\n") + a.validate_changes(base, commit_all()) + path.write_text(path.read_text().replace("# English", "# Other text")) + with pytest.raises(ValueError, match="refuses path"): + a.validate_changes(base, commit_all()) + + +@pytest.mark.parametrize("value", ["NaN", "Infinity", "-1", "invalid"]) +def test_budget_rejects_nonfinite_or_negative_allowance(value: str) -> None: + with pytest.raises(ValueError, match="finite nonnegative"): + a.money(value) + + +def test_default_budget_never_reads_or_changes_ledger(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setattr(a, "fetch", lambda ref: pytest.fail("zero allowance must stay offline")) + assert a.reserve(Decimal(0), False, None) == 0 + + +def test_positive_budget_never_resets_missing_ledger(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setattr(a, "fetch", lambda ref: None) + with pytest.raises(ValueError, match="missing"): + a.reserve(Decimal(100), False, None) + + +def test_budget_reservation_precedes_update_and_is_not_refunded( + monkeypatch: pytest.MonkeyPatch, +) -> None: + events: list[Any] = [] + monkeypatch.setenv("LOOM_I18N_TOTAL_USD", "20") + monkeypatch.setenv("LOOM_I18N_LANGUAGES", "ja") + monkeypatch.setattr(a, "configure_git", lambda: None) + monkeypatch.setattr(a, "fetch", lambda ref: "a" * 40) + monkeypatch.setattr(a, "budget_total", lambda tip: Decimal(12)) + monkeypatch.setattr(a.t, "batch_reservation", lambda every, codes, cap: cap * 2) + monkeypatch.setattr(a, "append_budget", lambda *args: events.append(("reserve", args))) + + def rejected(every: bool, codes: list[str] | None) -> int: + assert a.os.environ["LOOM_I18N_MAX_USD"] == "2.5" + events.append(("provider",)) + raise RuntimeError("uncertain request") + + monkeypatch.setattr(a.t, "update", rejected) + with pytest.raises(RuntimeError, match="uncertain"): + a.update(False, None) + assert events == [("reserve", ("a" * 40, Decimal(12), Decimal("5.0"))), ("provider",)] + + +def test_failed_budget_push_prevents_provider_calls(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setenv("LOOM_I18N_TOTAL_USD", "20") + monkeypatch.setenv("LOOM_I18N_LANGUAGES", "ja") + monkeypatch.setattr(a, "configure_git", lambda: None) + monkeypatch.setattr(a, "fetch", lambda ref: "a" * 40) + monkeypatch.setattr(a, "budget_total", lambda tip: Decimal(0)) + monkeypatch.setattr(a.t, "batch_reservation", lambda *args, **kwargs: 1) + monkeypatch.setattr(a.t, "update", lambda *args: pytest.fail("unreserved paid call")) + + def denied(*args: Any) -> None: + raise RuntimeError("lease refused") + + monkeypatch.setattr(a, "append_budget", denied) + with pytest.raises(RuntimeError, match="lease refused"): + a.update(False, None) + + +def test_ledger_records_separate_monotonic_commits_and_rejects_rewrite( + repository: Path, + monkeypatch: pytest.MonkeyPatch, +) -> None: + pushes: list[tuple[str, ...]] = [] + real_git = a.git + + def no_network(*args: str, **kwargs: Any) -> str: + if args[0] == "push": + pushes.append(args) + return "" + return real_git(*args, **kwargs) + + monkeypatch.setattr(a, "git", no_network) + first = a.append_budget(None, Decimal(0), Decimal(0)) + second = a.append_budget(first, Decimal(0), Decimal("2.125")) + assert a.budget_total(second) == Decimal("2.125") + assert pushes[1][-1] == f"--force-with-lease={a.BUDGET}:{first}" + assert a.git("ls-tree", "--name-only", second) == "budget.json" + bad = a.append_budget(second, Decimal(0), Decimal(1)) + with pytest.raises(ValueError, match="invalid translation budget"): + a.budget_total(bad) + + +def test_publisher_dispatches_ci_without_merging_the_unchecked_generated_sha( + repository: Path, + monkeypatch: pytest.MonkeyPatch, +) -> None: + output(repository) + monkeypatch.setattr(a.t, "check", lambda **kwargs: 0) + monkeypatch.setattr(a, "fetch", lambda ref: None) + real_git = a.git + pushed: list[str] = [] + calls: list[tuple[str, ...]] = [] + + def local_git(*args: str, **kwargs: Any) -> str: + if args[0] == "push": + pushed.append(args[2].split(":")[0]) + return "" + return real_git(*args, **kwargs) + + monkeypatch.setattr(a, "git", local_git) + real_command = a.command + + def gh(*args: str, **kwargs: Any) -> str: + if args[0] != "gh": + return real_command(*args, **kwargs) + calls.append(args) + if args[1:3] == ("pr", "create"): + body = Path(args[args.index("--body-file") + 1]).read_text() + assert "### Changelog category" in body + assert "### Compatibility, rollout and rollback" in body + assert "### Tests" in body + assert "[ ] Hosted CI" in body + return json.dumps([]) if args[1:3] == ("pr", "list") else "" + + monkeypatch.setattr(a, "command", gh) + a.publish() + assert len(pushed) == 1 + assert calls[-1][-1] == f"expected_sha={pushed[0]}" + assert not any(call[1:3] == ("pr", "merge") for call in calls) + + +def test_hosted_ci_gates_every_job_and_keeps_original_dependencies() -> None: + root = Path(__file__).resolve().parents[2] + workflow = yaml.load((root / ".github/workflows/ci.yml").read_text(), Loader=yaml.BaseLoader) + jobs = workflow["jobs"] + for name, job in jobs.items(): + if name != "validate-ref": + needs = job["needs"] + assert "validate-ref" in ([needs] if isinstance(needs, str) else needs), name + assert "clickhouse" in jobs["unit"]["needs"] + assert "unit" in jobs["unit-coverage"]["needs"] + gate = jobs["validate-ref"]["steps"][0]["run"] + assert 'test "$SHA" = "$EXPECTED_SHA"' in gate + assert 'test "$REF" = "refs/heads/i18n/update"' in gate + assert workflow["on"]["workflow_dispatch"]["inputs"]["expected_sha"]["required"] == "true" + + +def test_paid_runner_remains_main_only_with_finite_cumulative_default() -> None: + root = Path(__file__).resolve().parents[2] + workflow = yaml.load((root / ".github/workflows/i18n.yml").read_text(), Loader=yaml.BaseLoader) + assert "pull_request" not in workflow["on"] + assert workflow["on"]["workflow_run"]["branches"] == ["i18n/update"] + update = workflow["jobs"]["update"] + assert update["env"]["LOOM_I18N_BATCH_LANGUAGES"] == "${{ inputs.languages }}" + assert "github.ref == 'refs/heads/main'" in update["if"] + assert update["environment"] == "i18n" + assert "workflow_run" not in update["if"] + assert workflow["jobs"]["finalize"]["runs-on"] == "ubuntu-latest" + assert "environment" not in workflow["jobs"]["finalize"] + assert workflow["jobs"]["finalize"]["steps"][0]["with"]["ref"] == "main" + steps = update["steps"] + assert steps[0]["with"]["ref"] == "${{ github.sha }}" + paid = next(step for step in steps if step.get("id") == "translate") + assert paid["env"]["LOOM_I18N_TOTAL_USD"] == "${{ vars.LOOM_I18N_TOTAL_USD || '0' }}" + + +def test_verified_checkpoint_can_be_published_and_removed_on_activation(repository: Path) -> None: + base = a.git("rev-parse", "HEAD") + published = output(repository) + path = repository / "i18n/.pending/ja/README.md" + path.parent.mkdir(parents=True) + path.write_text(published.read_text()) + a.validate_changes(base, commit_all()) + base = a.git("rev-parse", "HEAD") + path.unlink() + a.validate_changes(base, commit_all()) + + +def test_publisher_refuses_to_overwrite_pending_updates_after_import( + repository: Path, + monkeypatch: pytest.MonkeyPatch, +) -> None: + output(repository) + monkeypatch.setattr(a.t, "check", lambda **kwargs: 0) + monkeypatch.setenv("LOOM_I18N_PENDING_SHA", "a" * 40) + monkeypatch.setattr(a, "fetch", lambda ref: "b" * 40) + with pytest.raises(ValueError, match="changed after import"): + a.publish() + + +def test_prepare_reports_only_the_successfully_imported_pending_tip( + tmp_path: Path, + monkeypatch: pytest.MonkeyPatch, +) -> None: + output_path = tmp_path / "outputs" + monkeypatch.setenv("GITHUB_OUTPUT", str(output_path)) + monkeypatch.setattr(a, "fetch", lambda ref: "a" * 40) + imported: list[str] = [] + monkeypatch.setattr(a.t, "import_pending", lambda ref, codes=None: imported.append(ref)) + a.prepare() + assert imported == ["a" * 40] + assert output_path.read_text() == f"pending_sha={'a' * 40}\n" + + +def ci_run(sha: str) -> dict[str, Any]: + return { + "event": "workflow_dispatch", + "path": ".github/workflows/ci.yml", + "head_branch": "i18n/update", + "head_sha": sha, + "head_repository": {"full_name": "ClickHouse/loom"}, + "status": "completed", + "conclusion": "success", + } + + +@pytest.mark.parametrize( + "field,value", + [ + ("event", "pull_request"), + ("head_branch", "attacker"), + ("head_sha", "b" * 40), + ("path", ".github/workflows/other.yml"), + ("head_repository", {"full_name": "other/repo"}), + ("status", "in_progress"), + ("conclusion", "failure"), + ], +) +def test_finalizer_rejects_unrelated_or_unsuccessful_ci(field: str, value: Any) -> None: + run = ci_run("a" * 40) + assert a.trusted_ci(run, "ClickHouse/loom", "a" * 40) + run[field] = value + assert not a.trusted_ci(run, "ClickHouse/loom", "a" * 40) + + +@pytest.mark.parametrize( + "checks", + [ + [], + [{"state": "PENDING"}], + [ + {"status": "COMPLETED", "conclusion": "SUCCESS"}, + {"status": "COMPLETED", "conclusion": "SKIPPED"}, + ], + ], +) +def test_finalizer_requires_nonempty_successful_checks(checks: list[dict[str, Any]]) -> None: + assert not a.checks_succeeded(checks) + + +@pytest.mark.parametrize( + "review,merge_state,merged", + [ + ("REVIEW_REQUIRED", "BLOCKED", False), + ("CHANGES_REQUESTED", "BLOCKED", False), + ("APPROVED", "CLEAN", True), + ("", "CLEAN", True), + ], +) +@pytest.mark.parametrize("site_raises", [False, True]) +@pytest.mark.parametrize( + "published_code,approved,deleted", + [ + ("ja", "ja", False), + ("es", "ja", False), + ("es", "", False), + ("es", "ja", True), + ("ja", "ja", True), + ], +) +def test_hosted_finalizer_respects_reviews_and_merges_only_exact_successful_head( + repository: Path, + monkeypatch: pytest.MonkeyPatch, + review: str, + merge_state: str, + merged: bool, + site_raises: bool, + published_code: str, + approved: str, + deleted: bool, +) -> None: + output(repository, code="ko") + if deleted: + lang = next(lang for lang in a.t.LANGUAGES if lang.code == published_code) + path = repository / a.t.target_path(published_code, "docs/obsolete.md") + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text( + a.t.header("docs/obsolete.md", lang, a.t.DEFAULT_MODEL, "0" * 40) + "# Original\n" + ) + base = commit_all() + if deleted: + path.unlink() + else: + output(repository, code=published_code) + a.git("add", ".") + sha = a.git("commit-tree", a.git("write-tree"), "-p", base, input_text="Generated\n") + monkeypatch.setenv("GITHUB_REPOSITORY", "ClickHouse/loom") + monkeypatch.setenv("GITHUB_EVENT_NAME", "schedule") + monkeypatch.setenv("LOOM_I18N_LANGUAGES", approved) + monkeypatch.setattr(a, "fetch", lambda ref: sha) + monkeypatch.setattr(a.t, "check", lambda **kwargs: 0) + pr = { + "number": 42, + "draft": False, + "head": {"sha": sha, "repo": {"full_name": "ClickHouse/loom"}}, + } + + def api(path: str) -> Any: + if "state=closed" in path: + return [] + if "state=open" in path: + return [pr] + if "actions/workflows/ci.yml/runs" in path: + return {"workflow_runs": [ci_run(sha)]} + assert path.endswith("/pulls/42") + return {"merged": True, "head": {"sha": sha}} + + monkeypatch.setattr(a, "api", api) + calls: list[tuple[str, ...]] = [] + actual = a.command + + def command(*args: str, **kwargs: Any) -> str: + if args[0] == "mkdocs": + calls.append(args) + if site_raises: + raise RuntimeError("strict site build failed") + return "" + if args[0] != "gh": + return actual(*args, **kwargs) + calls.append(args) + if args[1:3] == ("pr", "view"): + return json.dumps( + { + "reviewDecision": review, + "mergeStateStatus": merge_state, + "statusCheckRollup": [{"status": "COMPLETED", "conclusion": "SUCCESS"}], + } + ) + return "" + + monkeypatch.setattr(a, "command", command) + permitted = published_code in (approved.split() or list(a.t.ROLLOUT_LANGUAGES)) + if merged and permitted and site_raises: + with pytest.raises(RuntimeError, match="strict site build failed"): + a.finalize() + else: + a.finalize() + merge_calls = [call for call in calls if call[1:3] == ("pr", "merge")] + if merged and permitted and not site_raises: + assert len(merge_calls) == 1 + assert calls.index(("mkdocs", "build", "--strict")) < calls.index(merge_calls[0]) + assert merge_calls[0][-2:] == ("--match-head-commit", sha) + assert "--admin" not in merge_calls[0] and "--auto" not in merge_calls[0] + assert calls[-1] == ("gh", "workflow", "run", "docs-site.yml", "--ref", "main") + else: + assert merge_calls == [] + assert not any(call[1:3] == ("workflow", "run") for call in calls) + + +def test_unchanged_pending_data_keeps_the_reviewed_commit( + repository: Path, + monkeypatch: pytest.MonkeyPatch, +) -> None: + base = a.git("rev-parse", "HEAD") + output(repository) + a.git("add", ".") + previous = a.git("commit-tree", a.git("write-tree"), "-p", base, input_text="Generated\n") + monkeypatch.setattr(a, "fetch", lambda ref: previous) + monkeypatch.setattr(a.t, "check", lambda **kwargs: 0) + calls: list[tuple[str, ...]] = [] + actual = a.command + + def command(*args: str, **kwargs: Any) -> str: + if args[:2] == ("git", "push"): + pytest.fail("unchanged output must retain the reviewed branch head") + if args[0] != "gh": + return actual(*args, **kwargs) + calls.append(args) + return json.dumps([{"number": 42}]) if args[1:3] == ("pr", "list") else "" + + monkeypatch.setattr(a, "command", command) + a.publish() + assert calls[-1][-1] == f"expected_sha={previous}" + + +@pytest.mark.parametrize( + "site_result,expected_dispatch", [(None, True), ("failure", True), ("success", False)] +) +def test_scheduled_reconciliation_retries_suppressed_or_failed_site_deployment( + repository: Path, + monkeypatch: pytest.MonkeyPatch, + site_result: str | None, + expected_dispatch: bool, +) -> None: + sha = a.git("rev-parse", "HEAD") + runs = ( + [] + if site_result is None + else [ + { + "head_branch": "main", + "head_sha": sha, + "status": "completed", + "conclusion": site_result, + } + ] + ) + + def api(path: str) -> Any: + if "/pulls?" in path: + return [{"merged_at": "one", "merge_commit_sha": sha}] + return {"workflow_runs": runs} + + monkeypatch.setattr(a, "api", api) + actual = a.command + calls: list[tuple[str, ...]] = [] + + def command(*args: str, **kwargs: Any) -> str: + if args[0] == "gh": + calls.append(args) + return "" + return actual(*args, **kwargs) + + monkeypatch.setattr(a, "command", command) + a.sync_site("ClickHouse/loom") + assert bool(calls) is expected_dispatch + if expected_dispatch: + assert calls == [("gh", "workflow", "run", "docs-site.yml", "--ref", "main")] + + +@pytest.mark.parametrize( + "event,ref,expected,passed", + [ + ("workflow_dispatch", "refs/heads/i18n/update", "a" * 40, True), + ("workflow_dispatch", "refs/heads/main", "a" * 40, False), + ("workflow_dispatch", "refs/heads/i18n/update", "b" * 40, False), + ("workflow_dispatch", "refs/heads/i18n/update", "$(exit 0)", False), + ("pull_request", "refs/pull/1/merge", "", True), + ], +) +def test_ci_gate_executes_only_the_requested_exact_bot_commit( + event: str, + ref: str, + expected: str, + passed: bool, +) -> None: + root = Path(__file__).resolve().parents[2] + workflow = yaml.load((root / ".github/workflows/ci.yml").read_text(), Loader=yaml.BaseLoader) + gate = workflow["jobs"]["validate-ref"]["steps"][0]["run"] + result = subprocess.run( + ["bash", "-e", "-c", gate], + check=False, + capture_output=True, + env={**os.environ, "EVENT": event, "REF": ref, "SHA": "a" * 40, "EXPECTED_SHA": expected}, + ) + assert (result.returncode == 0) is passed + + +@pytest.mark.parametrize("source", ["docs/日本語.md", "docs/日本語 guide.md"]) +def test_publisher_validates_unicode_and_space_paths_without_git_quote_parsing( + repository: Path, + source: str, +) -> None: + a.git("config", "core.quotepath", "true") + source_file = repository / source + source_file.parent.mkdir(parents=True, exist_ok=True) + source_file.write_text("# English\n") + base = commit_all() + path = output(repository, source) + a.validate_changes(base, commit_all()) + # The regression must cover Git's default quoted-path output. + assert "\\" in a.git("diff", "--name-status", base, "HEAD") + path.write_text(path.read_text().replace(a.t.blob(source), "0" * 40)) + with pytest.raises(ValueError, match="refuses path"): + a.validate_changes(base, commit_all()) + + +@pytest.mark.parametrize("configured", [None, ""]) +def test_default_selection_keeps_all_five_locales_with_zero_allowance( + monkeypatch: pytest.MonkeyPatch, + configured: str | None, +) -> None: + if configured is None: + monkeypatch.delenv("LOOM_I18N_LANGUAGES", raising=False) + else: + monkeypatch.setenv("LOOM_I18N_LANGUAGES", configured) + monkeypatch.delenv("LOOM_I18N_TOTAL_USD", raising=False) + monkeypatch.setattr(a, "configure_git", lambda: None) + reservations: list[tuple[Any, ...]] = [] + monkeypatch.setattr(a, "reserve", lambda *args: reservations.append(args) or 0.0) + calls: list[tuple[bool, list[str] | None, str]] = [] + monkeypatch.setattr( + a.t, + "update", + lambda every, codes: calls.append((every, codes, a.os.environ["LOOM_I18N_MAX_USD"])) or 0, + ) + a.update(True, None) + expected = sorted(a.t.ROLLOUT_LANGUAGES) + assert reservations == [(Decimal(0), True, expected)] + assert calls == [(True, expected, "0.0")] + + +def test_persistent_approval_selects_only_configured_languages( + monkeypatch: pytest.MonkeyPatch, +) -> None: + monkeypatch.setenv("LOOM_I18N_LANGUAGES", "ja") + monkeypatch.setenv("LOOM_I18N_TOTAL_USD", "20") + monkeypatch.setattr(a, "configure_git", lambda: None) + reservations: list[tuple[Any, ...]] = [] + monkeypatch.setattr(a, "reserve", lambda *args: reservations.append(args) or 1.0) + calls: list[list[str] | None] = [] + monkeypatch.setattr(a.t, "update", lambda every, codes: calls.append(codes) or 0) + a.update(False, None) + assert reservations == [(Decimal(20), False, ["ja"])] + assert calls == [["ja"]] + + +@pytest.mark.parametrize( + "approved,requested", + [ + ("unknown", None), + ("ja", ["es"]), + ("ja", ["zh-CN"]), + ("fr", None), + ("ko", ["pt-BR"]), + ("pt-BR", ["es"]), + ], +) +def test_unapproved_or_unknown_languages_refuse_before_budget_reservation( + monkeypatch: pytest.MonkeyPatch, + approved: str, + requested: list[str] | None, +) -> None: + monkeypatch.setenv("LOOM_I18N_LANGUAGES", approved) + monkeypatch.setattr(a, "reserve", lambda *args: pytest.fail("unapproved reservation")) + with pytest.raises(ValueError, match="language"): + a.update(False, requested) + + +@pytest.mark.parametrize( + "configured,batch,requested", + [("", "fr", None), ("ja", "es", None), ("", "ja", ["es"])], +) +def test_invalid_batch_selection_refuses_before_mutation_or_reservation( + monkeypatch: pytest.MonkeyPatch, + configured: str, + batch: str, + requested: list[str] | None, +) -> None: + monkeypatch.setenv("LOOM_I18N_LANGUAGES", configured) + monkeypatch.setenv("LOOM_I18N_BATCH_LANGUAGES", batch) + monkeypatch.setattr(a, "configure_git", lambda: pytest.fail("invalid batch mutated Git")) + monkeypatch.setattr(a, "reserve", lambda *args: pytest.fail("invalid batch reserved money")) + with pytest.raises(ValueError, match="language"): + a.update(False, requested) + + +def test_publisher_refuses_changes_outside_requested_batch_before_push( + repository: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + monkeypatch.delenv("LOOM_I18N_LANGUAGES", raising=False) + monkeypatch.delenv("LOOM_I18N_PENDING_SHA", raising=False) + monkeypatch.setenv("LOOM_I18N_BATCH_LANGUAGES", "ja") + monkeypatch.setattr(a.t, "check", lambda **kwargs: 0) + monkeypatch.setattr(a, "fetch", lambda ref: None) + monkeypatch.setattr(a, "publish_pr", lambda *args: pytest.fail("excluded output reached PR")) + output(repository, code="es") + actual = a.command + + def command(*args: str, **kwargs: Any) -> str: + if args[:2] == ("git", "push"): + pytest.fail("excluded output reached push") + return actual(*args, **kwargs) + + monkeypatch.setattr(a, "command", command) + with pytest.raises(ValueError, match="outside the selected batch"): + a.publish() + + +def test_finalize_retries_merged_site_while_next_translation_pr_waits_for_ci( + repository: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + monkeypatch.setenv("GITHUB_REPOSITORY", "ClickHouse/loom") + monkeypatch.setenv("GITHUB_EVENT_NAME", "schedule") + sha = a.git("rev-parse", "HEAD") + calls: list[tuple[str, ...]] = [] + + def api(path: str) -> Any: + if "/pulls?state=closed" in path: + return [{"merged_at": "one", "merge_commit_sha": sha}] + if "/pulls?state=open" in path: + return [ + {"draft": False, "head": {"sha": sha, "repo": {"full_name": "ClickHouse/loom"}}} + ] + if "/actions/workflows/" in path: + return {"workflow_runs": []} + raise AssertionError(path) + + monkeypatch.setattr(a, "api", api) + monkeypatch.setattr(a, "command", lambda *args: calls.append(args) or "") + a.finalize() + assert calls == [("gh", "workflow", "run", "docs-site.yml", "--ref", "main")] + + +def test_rollout_scope_preserves_generic_language_capability() -> None: + assert a.t.ROLLOUT_LANGUAGES == ("zh-CN", "ja", "ko", "pt-BR", "es") + assert {lang.code for lang in a.t.LANGUAGES} == {"zh-CN", "ja", "ko", "pt-BR", "es"} + + +@pytest.mark.parametrize("action", ["replace", "delete"]) +def test_rollout_retains_deferred_checkpoints_while_accepting_new_preservation_copies( + repository: Path, action: str +) -> None: + base = a.git("rev-parse", "HEAD") + published = output(repository, code="es") + checkpoint = repository / "i18n/.pending/es/README.md" + checkpoint.parent.mkdir(parents=True) + published.rename(checkpoint) + added = commit_all() + assert a.rollout_changes_allowed(base, added, ["ja"]) + if action == "replace": + checkpoint.write_text(checkpoint.read_text() + "\nTexto.\n") + else: + checkpoint.unlink() + changed = commit_all() + assert not a.rollout_changes_allowed(added, changed, ["ja"]) + + +@pytest.mark.parametrize("source", ["README.md", "docs/removed.md"]) +@pytest.mark.parametrize("code", ["zh-CN", "ja", "ko", "pt-BR", "es"]) +def test_publisher_accepts_owned_archives_but_never_stale_publication( + repository: Path, source: str, code: str +) -> None: + base = a.git("rev-parse", "HEAD") + lang = next(lang for lang in a.t.LANGUAGES if lang.code == code) + published = a.t.target_path(code, source) + path = repository / a.t.lifecycle.checkpoint_path(published) + path.parent.mkdir(parents=True, exist_ok=True) + original = a.t.header(source, lang, a.t.DEFAULT_MODEL, "0" * 40) + "# Archivo\n" + path.write_text(original) + a.validate_changes(base, commit_all()) + assert published not in a.t.lifecycle.current_checkpoints() + banner = lang.banner.format(url=f"{a.t.REPO_URL}/blob/main/{source}") + invalid = original.replace(banner, "Unknown ownership", 1) + assert invalid != original + path.write_text(invalid) + with pytest.raises(ValueError, match="refuses path"): + a.validate_changes(base, commit_all()) + path.write_text(original) + destination = repository / published + destination.parent.mkdir(parents=True, exist_ok=True) + destination.write_text(original) + with pytest.raises(ValueError, match="refuses path"): + a.validate_changes(base, commit_all()) + + +def test_requested_batch_preserves_excluded_data_through_prepare_update_and_finalizer_validation( + repository: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + monkeypatch.delenv("LOOM_I18N_LANGUAGES", raising=False) + monkeypatch.setenv("LOOM_I18N_BATCH_LANGUAGES", "ja") + monkeypatch.setenv("LOOM_I18N_TOTAL_USD", "0") + monkeypatch.setattr(a.t, "bedrock_client", lambda: pytest.fail("zero allowance provider")) + readme = repository / "README.md" + readme.write_text("# English\n\n" + a.t.language_line("README.md") + "\n") + ko = output(repository, code="ko") + language = next(lang for lang in a.t.LANGUAGES if lang.code == "ko") + english, line = a.t.prepare("README.md", language) + body = "\n".join(a.t.english_requests(english)).replace("# English", "# 한국어") + incoming_ko = a.t.render("README.md", language, body, line, a.t.DEFAULT_MODEL) + assert a.t.lifecycle.candidate_problems("i18n/ko/README.md", incoming_ko) == [] + retained = incoming_ko.replace(a.t.blob("README.md"), "0" * 40) + ko.write_text(retained) + base = commit_all() + a.git("switch", "-qc", "i18n/update") + ko.write_text(incoming_ko) + es = output(repository, code="es") + archived = es.read_text().replace(a.t.blob("README.md"), "0" * 40) + es.write_text(archived) + pending = commit_all() + a.git("switch", "-q", "main") + monkeypatch.setattr(a, "fetch", lambda ref: pending) + a.prepare() + assert ko.read_text() == retained + assert not (repository / "i18n/es/README.md").exists() + assert (repository / "i18n/.pending/es/README.md").read_text() == archived + assert (repository / "i18n/.pending/ko/README.md").read_text() == incoming_ko + assert a.update(False, None) == 0 + assert ko.read_text() == retained + a.git("add", ".") + candidate = a.git("commit-tree", a.git("write-tree"), "-p", base, input_text="Batch\n") + a.validate_changes(base, candidate) + assert a.rollout_changes_allowed(base, candidate, a.approved_languages()) + # The hosted finalizer sees current configuration, without manual-run batch context. + monkeypatch.delenv("LOOM_I18N_BATCH_LANGUAGES") + assert set(a.approved_languages()) == set(a.t.ROLLOUT_LANGUAGES) + a.validate_changes(base, candidate) + assert a.rollout_changes_allowed(base, candidate, a.approved_languages()) + assert "i18n/es/README.md" not in a.t.lifecycle.current_checkpoints() + + +def readme_candidate( + repository: Path, *, existing: bool = False, invalid: str = "" +) -> tuple[str, str]: + readme = repository / "README.md" + japanese = repository / "i18n/ja/README.md" + japanese.parent.mkdir(parents=True, exist_ok=True) + if existing: + japanese.write_text("temporary") + readme.write_text("# Loom\n\n" + a.t.language_line("README.md") + "\n") + lang = next(item for item in a.t.LANGUAGES if item.code == "ja") + if existing: + japanese.write_text( + a.t.header("README.md", lang, a.t.DEFAULT_MODEL, a.t.blob("README.md")) + + "# 日本語\n\n" + + a.t.language_line("i18n/ja/README.md") + + "\n" + ) + base = commit_all() + old_blob = a.t.blob("README.md") + japanese.write_text("temporary") + bar = a.t.language_line("README.md") + if invalid == "bar": + bar = bar.replace("日本語", "Invalid generated link") + heading = "# Changed prose" if invalid == "prose" else "# Loom" + readme.write_text(heading + "\n\n" + bar + "\n") + blob = old_blob if invalid == "stamp" else a.t.blob("README.md") + japanese.write_text( + a.t.header("README.md", lang, a.t.DEFAULT_MODEL, blob) + + "# 日本語の文書\n\n" + + a.t.language_line("i18n/ja/README.md") + + "\n" + ) + return base, commit_all() + + +@pytest.mark.parametrize("existing", [False, True]) +@pytest.mark.parametrize("untracked_readme", [False, True]) +def test_generated_readme_validation_uses_candidate_data_from_clean_main( + repository: Path, existing: bool, untracked_readme: bool +) -> None: + base, candidate = readme_candidate(repository, existing=existing) + a.validate_changes(base, candidate) + a.git("switch", "--detach", "-q", base) + if untracked_readme and not existing: + path = repository / "i18n/ja/README.md" + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text("Untracked data must not control candidate validation") + before = a.git("status", "--porcelain") + a.validate_changes(base, candidate) + assert a.git("rev-parse", "HEAD") == base + assert a.git("status", "--porcelain") == before + + +@pytest.mark.parametrize("invalid", ["prose", "bar", "stamp"]) +@pytest.mark.parametrize("checkout", ["candidate", "main"]) +def test_candidate_readme_projection_refuses_prose_bars_and_stale_stamps( + repository: Path, invalid: str, checkout: str +) -> None: + base, candidate = readme_candidate(repository, invalid=invalid) + if checkout == "main": + a.git("switch", "--detach", "-q", base) + path = "i18n/ja/README.md" if invalid == "stamp" else "README.md" + with pytest.raises(ValueError, match=f"refuses path: {path}"): + a.validate_changes(base, candidate) diff --git a/tests/unit/test_i18n_context.py b/tests/unit/test_i18n_context.py new file mode 100644 index 0000000000..afb9902a79 --- /dev/null +++ b/tests/unit/test_i18n_context.py @@ -0,0 +1,439 @@ +"""Source declarations distinguish protected spellings from ordinary descriptions.""" + +import pytest + +from scripts.i18n import translate as t +from scripts.i18n.context import Label, SourceContext, project, protected + + +@pytest.mark.parametrize( + ("source_path", "label", "expected"), + [ + ("docs/features/integrations/frameworks.md", "n8n", ("n8n",)), + ("docs/features/integrations/index.md", "Agent Substrate", ("Agent Substrate",)), + ( + "docs/features/integrations/index.md", + "LibreChat v0.8.8", + ("LibreChat v0.8.8", "LibreChat"), + ), + ("docs/benchmarks/results.md", "MemoryAgentBench samples", ("MemoryAgentBench",)), + ("docs/reference/mcp.md", "OAuth", ("OAuth",)), + ("docs/other.md", "Agent Substrate", ()), + ("docs/other.md", "Getting started", ()), + ], +) +def test_names_are_source_scoped_spans(source_path, label, expected): + assert protected(Label(label), source_path) == expected + + +def test_a_product_name_does_not_hide_its_ordinary_descriptor(): + node = Label("MemoryAgentBench samples", minimum=2) + atoms = protected(node, "docs/benchmarks/results.md") + residual, spelling = project(node, atoms) + assert residual.strip() == "samples" + assert spelling == ("MemoryAgentBench",) + assert project(Label("MemoryAgentBench サンプル"), atoms)[0].strip() == "サンプル" + + +@pytest.mark.parametrize("name", ["README", "README.md", "claude-code.md"]) +def test_filename_identity_comes_from_the_source_link_target(name): + target = "README.md" if name == "README" else name + node = Label(name, links=((name, target),)) + files = frozenset({"docs/" + target}) + assert protected(node, "docs/other.md", files=files) == (name,) + assert protected(node, "docs/other.md") == () + assert protected(Label(name, links=((name, "other.md"),)), "docs/other.md", files=files) == () + + +def test_quoted_prose_is_not_a_returned_string_declaration(): + quoted = '"Install the package" / "Getting started"' + assert protected(Label(quoted), "docs/other.md") == () + assert ( + protected( + Label(quoted, field="example", string_field=True), "docs/reference/operations/a.md" + ) + == () + ) + + +def test_returned_literal_alternatives_require_a_string_field_context(): + quoted = '"namespace" / "cluster" / "scalar"' + path = "docs/reference/operations/calibration.md" + assert protected(Label(quoted), path) == () + atoms = protected(Label(quoted, field="source", string_field=True), path) + assert project(Label(quoted), atoms)[1] == ("namespace", "cluster", "scalar") + assert project(Label("命名空间级 / 集群级 / 标量"), atoms)[1] == () + + +def test_only_the_attested_field_formula_is_protected(): + node = Label("len(content) / char_limit.", field="fill_ratio") + assert protected(node, "docs/reference/operations/working_memory.md") == ( + "len(content) / char_limit", + ) + assert protected(node, "docs/other.md") == () + assert ( + protected( + Label("len(content) / char_limit.", field="example"), + "docs/reference/operations/working_memory.md", + ) + == () + ) + + +def _table(rows: str) -> str: + return "| Field | Type | Meaning |\n| --- | --- | --- |\n" + rows + "\n" + + +@pytest.mark.parametrize( + ("path", "name"), + [ + ("docs/features/integrations/frameworks.md", "n8n"), + ("docs/features/integrations/index.md", "Agent Substrate"), + ("docs/features/integrations/index.md", "LibreChat v0.8.8"), + ("docs/benchmarks/results.md", "MemBench"), + ("docs/benchmarks/results.md", "MemoryAgentBench"), + ("docs/benchmarks/results.md", "MuSiQue-Ans"), + ("docs/benchmarks/results.md", "PerLTQA"), + ("docs/development/documentation-style.md", "ClickHouse Cloud / ClickHouse OSS"), + ("docs/reference/mcp.md", "OAuth"), + ], +) +def test_exact_source_names_pass_but_changed_or_relocated_names_fail(path, name): + source = f"## {name}\n\n## Details\n" + assert t.differences(source, f"## {name}\n\n## 詳細\n", source_path=path) == [] + assert t.differences(source, "## 名前\n\n## 詳細\n", source_path=path) + assert t.differences(source, f"## 名前\n\n## {name}\n", source_path=path) + assert t.differences( + source, f'## 名前 \n\n## 詳細\n', source_path=path + ) + + +@pytest.mark.parametrize("name", ["README", "README.md", "claude-code.md"]) +def test_source_filename_links_pass_and_cannot_be_translated(name): + target = "README.md" if name == "README" else name + target = "../../../integrations/ax/README.md" if target == "README.md" else target + path = "docs/features/integrations/index.md" + source = f"[{name}]({target})\n" + assert t.differences(source, source, source_path=path) == [] + assert t.differences(source, f"[名前]({target})\n", source_path=path) + mixed = f"[{name} guide]({target})\n" + assert t.differences(mixed, mixed, source_path=path) + assert t.differences(mixed, f"[{name} ガイド]({target})\n", source_path=path) == [] + + +@pytest.mark.parametrize( + ("path", "label", "translated"), + [ + ("docs/benchmarks/results.md", "MemoryAgentBench samples", "MemoryAgentBench サンプル"), + ( + "docs/features/integrations/index.md", + "GitHub Copilot CLI (experimental)", + "GitHub Copilot CLI(実験的)", + ), + ( + "docs/features/integrations/frameworks.md", + "Claude API memory tool", + "Claude API メモリツール", + ), + ], +) +def test_names_do_not_exempt_one_word_qualifiers_or_mixed_cells(path, label, translated): + source = _table(f"| {label} | | |") + assert t.differences(source, source, source_path=path) + assert t.differences(source, _table(f"| {translated} | | |"), source_path=path) == [] + + +def test_returned_wire_values_are_required_even_without_backticks(): + path = "docs/reference/operations/calibration.md" + source = _table('| `source` | `str` | "namespace" / "cluster" / "scalar" |') + assert t.differences(source, source, source_path=path) == [] + native_quotes = source.replace( + '"namespace" / "cluster" / "scalar"', "“namespace” / “cluster” / “scalar”" + ) + assert t.differences(source, native_quotes, source_path=path) == [] + for replacement in [ + "命名空间级 / 集群级 / 标量", + '"cluster" / "namespace" / "scalar"', + '"namespace" / "cluster"', + '"namespace" / "cluster" / "cluster"', + ]: + changed = source.replace('"namespace" / "cluster" / "scalar"', replacement) + assert any( + "protected source strings" in p + for p in t.differences(source, changed, source_path=path) + ) + + +def test_escaped_and_inline_code_pipes_do_not_create_fake_english_cells(): + path = "docs/reference/operations/code.md" + row = r"| `verdict` | `str` | gap \| pending \| covered \| not_affected \| unknown — the worst branch's word |" + source = _table(row) + target = _table(row.replace("the worst branch's word", "最も悪いブランチの判定")) + assert t.differences(source, target, source_path=path) == [] + assert t.differences(source, target.replace("not_affected", "対象外"), source_path=path) + union = _table(r"| `state` | `str \| None` | Install the package |") + assert t.differences(union, union, source_path=path) + + +def test_policy_syntax_is_protected_but_its_explanation_is_translated(): + path = "docs/reference/operations/policy.md" + row = r"| `condition` | `dict[str, Any]` | required | history condition: {op: formerly\|count_within\|not_since\|all\|any\|not, ...}; leaves take within ('1h'), operation, key (agent\|session\|user), success, args_equal |" + header = "| Field | Type | Default | Meaning |\n| --- | --- | --- | --- |\n" + source = header + row + "\n" + target = ( + source.replace("required", "必須") + .replace("history condition", "履歴条件") + .replace("leaves take", "リーフの指定") + ) + assert t.differences(source, target, source_path=path) == [] + assert t.differences(source, target.replace("args_equal", "引数一致"), source_path=path) + assert t.differences(source, source, source_path=path) + + +def test_formula_exemption_is_limited_to_the_attested_operation_field(): + row = "| `fill_ratio` | `float` | len(content) / char_limit. |" + source = _table(row) + path = "docs/reference/operations/working_memory.md" + assert t.differences(source, source, source_path=path) == [] + assert t.differences(source, source.replace(" / ", " * "), source_path=path) + assert t.differences(source, source, source_path="docs/other.md") + + +def test_headerless_request_keeps_its_full_source_table_context(): + path = "docs/reference/operations/calibration.md" + row = '| `source` | `str` | "namespace" / "cluster" / "scalar" |\n' + english = _table("| `model` | `str` | Current model |\n" + row.rstrip()) + start = english.index(row) + scope = SourceContext(path, english, start, start + len(row)) + assert t.differences(row, row, source_context=scope) == [] + bad = row.replace('"namespace" / "cluster" / "scalar"', "命名空间级 / 集群级 / 标量") + assert t.differences(row, bad, source_context=scope) + with pytest.raises(ValueError, match="does not match"): + t.differences("wrong source", row, source_context=scope) + + +def test_preserved_name_does_not_spend_a_retry(monkeypatch): + source = "## n8n\n" + sent = [] + + def reply(client, model, system, messages): + sent.append(list(messages)) + return {"stop_reason": "end_turn", "content": [{"type": "text", "text": source}]} + + monkeypatch.setattr(t, "call", reply) + scope = SourceContext("docs/features/integrations/frameworks.md", source, 0, len(source)) + assert ( + t.translate_text( + source, t.LANGUAGES[1], None, t.Spend(t.DEFAULT_MODEL, 1), source_context=scope + ) + == source + ) + assert sent == [[{"role": "user", "content": source}]] + + +def test_a_changed_returned_literal_gets_precise_retry_feedback(monkeypatch): + path = "docs/reference/operations/calibration.md" + source = _table('| `source` | `str` | "namespace" / "cluster" / "scalar" |') + replies = iter([source.replace('"namespace"', '"命名空间"'), source]) + sent = [] + + def reply(client, model, system, messages): + sent.append(list(messages)) + return {"stop_reason": "end_turn", "content": [{"type": "text", "text": next(replies)}]} + + monkeypatch.setattr(t, "call", reply) + scope = SourceContext(path, source, 0, len(source)) + assert ( + t.translate_text( + source, t.LANGUAGES[1], None, t.Spend(t.DEFAULT_MODEL, 1), source_context=scope + ) + == source + ) + assert len(sent) == 2 + assert "protected source strings" in sent[1][-1]["content"] + assert "namespace" in sent[1][-1]["content"] + + +def test_assembly_refuses_a_changed_literal_before_creating_output(monkeypatch, tmp_path): + path = "docs/reference/operations/calibration.md" + source = _table('| `source` | `str` | "namespace" / "cluster" / "scalar" |') + monkeypatch.setattr(t, "ROOT", tmp_path) + monkeypatch.setattr(t, "prepare", lambda source_path, lang: (source, "")) + monkeypatch.setattr( + t, "translate_text", lambda text, *args, **kwargs: text.replace('"namespace"', '"命名空间"') + ) + with pytest.raises(t.TranslationDiffers, match="protected source strings"): + t.translate_page(path, t.LANGUAGES[1], None, t.Spend(t.DEFAULT_MODEL, 1)) + assert not (tmp_path / "i18n").exists() + + +def test_stored_page_check_uses_the_same_source_preservation_guard(monkeypatch, tmp_path): + source_path = "docs/reference/operations/calibration.md" + source = _table('| `source` | `str` | "namespace" / "cluster" / "scalar" |') + lang = t.LANGUAGES[1] + monkeypatch.setattr(t, "ROOT", tmp_path) + monkeypatch.setattr(t, "sources", lambda: (source_path,)) + monkeypatch.setattr(t, "LANGUAGES", (lang,)) + monkeypatch.setattr(t, "prepare", lambda source_path, lang: (source, "")) + output = tmp_path / t.target_path(lang.code, source_path) + output.parent.mkdir(parents=True) + output.write_text(source) + assert t.untranslated_pages() == [] + output.write_text(source.replace('"namespace"', '"命名空间"')) + assert any("protected source strings" in p for p in t.untranslated_pages()) + + +@pytest.mark.parametrize( + ("operation", "row", "english", "native", "literal"), + [ + ( + "tracker", + r"| `verdict` | `str` | planned \| answered \| empty \| unknown (no anchor to plan on) |", + "no anchor to plan on", + "計画の基準がない", + "answered", + ), + ( + "observe", + "| `kind` | `str` | file_edit / command_run / error / web_fetch / file_read / tool_use. |", + "", + "", + "file_edit", + ), + ], +) +def test_attested_returned_vocabularies_preserve_values_and_translate_descriptions( + operation, row, english, native, literal +): + source = _table(row) + output = source.replace(english, native) if english else source + path = f"docs/reference/operations/{operation}.md" + assert t.differences(source, output, source_path=path) == [] + assert t.differences(source, output.replace(literal, "値"), source_path=path) + if english: + assert t.differences(source, source, source_path=path) + + +def test_narrative_tier_descriptions_are_not_returned_wire_values(): + source = "## Scope (namespace, cluster, scalar)\n" + output = "## 範囲(名前空間、クラスター、スカラー)\n" + assert t.differences(source, output, source_path="docs/guides/debugging.md") == [] + + +@pytest.mark.parametrize("particle", ["を", "の", "용", "的"]) +@pytest.mark.parametrize("name,path", [("n8n", "frameworks"), ("Agent Substrate", "index")]) +def test_native_particles_preserve_the_complete_name(particle, name, path): + source = f"## {name}\n" + assert ( + t.differences( + source, f"## {name}{particle}\n", source_path=f"docs/features/integrations/{path}.md" + ) + == [] + ) + assert t.differences( + source, f"## {name}Custom\n", source_path=f"docs/features/integrations/{path}.md" + ) + + +@pytest.mark.parametrize("target", ["https://arbitrary.example/report.txt", "missing.txt"]) +def test_a_remote_or_untracked_basename_does_not_attest_a_filename(target): + name = target.rsplit("/", 1)[-1] + source = f"[{name}]({target})\n" + assert t.differences(source, source, source_path="docs/other.md") + assert t.differences(source, f"[レポート]({target})\n", source_path="docs/other.md") == [] + + +def test_canonical_repo_url_requires_the_actual_tracked_target(): + target = t.REPO_URL + "/blob/main/docs/features/integrations/claude-code.md" + source = f"[claude-code.md]({target})\n" + assert t.differences(source, source, source_path="docs/features/integrations/index.md") == [] + assert t.differences( + source, f"[名前]({target})\n", source_path="docs/features/integrations/index.md" + ) + wrong = source.replace("/blob/main/", "/blob/arbitrary/") + assert t.differences(wrong, wrong, source_path="docs/features/integrations/index.md") + + +@pytest.mark.parametrize( + "name,changed", [("n8n", "n8n_extra"), ("n8n", "n8né"), ("Mastra", "Mastração")] +) +def test_longer_unicode_or_latin_identifiers_do_not_preserve_a_name(name, changed): + assert t.differences( + f"## {name}\n", f"## {changed}\n", source_path="docs/features/integrations/frameworks.md" + ) + + +_MODEL_PATH = "docs/features/memory/conflicts-and-refusal.md" +_MODEL_HEADER = "| Setting | Default | Effect |\n| --- | --- | --- |\n" +_MODEL_ROW = "| `LOOM_CONFLICT_RESOLVER_MODEL` | gpt-6.1-sol | The resolver's judge. |\n" + + +def test_model_default_preserves_its_attested_setting_cell(): + source = _MODEL_HEADER + _MODEL_ROW + output = source.replace("The resolver's judge.", "判定するモデル。") + assert t.differences(source, output, source_path=_MODEL_PATH) == [] + assert t.differences(source, source, source_path=_MODEL_PATH) + assert any( + "protected source strings" in problem + for problem in t.differences( + source, output.replace("gpt-6.1-sol", "gpt-6.1-terra"), source_path=_MODEL_PATH + ) + ) + + +@pytest.mark.parametrize("case", ["path", "setting", "column", "model", "prose"]) +def test_model_defaults_do_not_exempt_other_source_nodes(case): + source = _MODEL_HEADER + _MODEL_ROW + path = _MODEL_PATH + if case == "path": + path = "docs/other.md" + elif case == "setting": + source = source.replace("LOOM_CONFLICT_RESOLVER_MODEL", "LOOM_OTHER_MODEL") + elif case == "column": + source = _MODEL_HEADER + "| `LOOM_CONFLICT_RESOLVER_MODEL` | 0 | gpt-6.1-sol |\n" + elif case == "model": + source = source.replace("gpt-6.1-sol", "gpt-6.1-terra") + else: + source = "## gpt-6.1-sol\n" + output = source.replace("The resolver's judge.", "判定するモデル。") + assert t.differences(source, output, source_path=path) + + +def test_a_model_default_does_not_exempt_its_ordinary_qualifier(): + source = (_MODEL_HEADER + _MODEL_ROW).replace("gpt-6.1-sol", "gpt-6.1-sol recommended") + output = source.replace("The resolver's judge.", "判定するモデル。") + assert t.differences(source, output, source_path=_MODEL_PATH) + assert ( + t.differences(source, output.replace("recommended", "推奨"), source_path=_MODEL_PATH) == [] + ) + + +def test_a_model_default_cannot_move_to_another_column_or_setting(): + source = _MODEL_HEADER + _MODEL_ROW + "| `LOOM_OTHER_MODEL` | 0 | Another model. |\n" + output = source.replace("The resolver's judge.", "判定するモデル。").replace( + "Another model.", "別のモデル。" + ) + moved_column = output.replace( + "gpt-6.1-sol | 判定するモデル。", "判定するモデル。 | gpt-6.1-sol" + ) + moved_setting = ( + output.replace("LOOM_CONFLICT_RESOLVER_MODEL", "SETTING_PLACEHOLDER") + .replace("LOOM_OTHER_MODEL", "LOOM_CONFLICT_RESOLVER_MODEL") + .replace("SETTING_PLACEHOLDER", "LOOM_OTHER_MODEL") + ) + for changed in (moved_column, moved_setting): + assert any( + "protected source strings" in problem + for problem in t.differences(source, changed, source_path=_MODEL_PATH) + ) + + +@pytest.mark.parametrize("newline", ["\n", "\r\n"], ids=["LF", "CRLF"]) +def test_a_headerless_model_default_request_keeps_its_setting_context(newline): + english = (_MODEL_HEADER + _MODEL_ROW).replace("\n", newline) + row = _MODEL_ROW.rstrip("\n").replace("\n", newline) + start = english.index(row) + scope = SourceContext(_MODEL_PATH, english, start, start + len(row)) + output = row.replace("The resolver's judge.", "判定するモデル。") + assert t.differences(row, output, source_context=scope) == [] + assert t.differences(row, output.replace("gpt-6.1-sol", "別のモデル"), source_context=scope) diff --git a/tests/unit/test_i18n_context_boundary.py b/tests/unit/test_i18n_context_boundary.py new file mode 100644 index 0000000000..4105c4e624 --- /dev/null +++ b/tests/unit/test_i18n_context_boundary.py @@ -0,0 +1,71 @@ +"""The final table row in a bounded request still carries its source contract.""" + +import pytest + +from scripts.i18n import translate as t +from scripts.i18n.context import SourceContext + +PATH = "docs/reference/operations/calibration.md" +HEADER = "| Field | Type | Meaning |\n| --- | --- | --- |\n" +ROW = '| `source` | `str` | "namespace" / "cluster" / "scalar" |\n' + + +def _planned(newline): + requests = t.english_requests((HEADER + ROW * 600).replace("\n", newline)) + assert len(requests) == 3 + if newline == "\n": + assert [len(p.encode()) for p in requests] == [16344, 16355, 2146] + return requests + + +def _change_last(text): + prefix, suffix = text.rsplit('"namespace"', 1) + return prefix + '"命名空间"' + suffix + + +@pytest.mark.parametrize("newline", ["\n", "\r\n"], ids=["LF", "CRLF"]) +@pytest.mark.parametrize("index", [0, 1, 2], ids=["first", "middle", "final"]) +def test_planned_request_final_row_and_neighbor_keep_wire_literals(newline, index): + requests = _planned(newline) + english = "\n".join(requests) + start = sum(len(p) + 1 for p in requests[:index]) + source = requests[index] + scope = SourceContext(PATH, english, start, start + len(source)) + assert english[scope.start : scope.end] == source + assert t.differences(source, source, source_context=scope) == [] + assert any( + "protected source strings" in p + for p in t.differences(source, _change_last(source), source_context=scope) + ) + previous, final = source.rsplit('"namespace"', 1) + neighbor = _change_last(previous) + '"namespace"' + final + assert any( + "protected source strings" in p + for p in t.differences(source, neighbor, source_context=scope) + ) + + +def test_split_row_refuses_the_bad_reply_and_asks_for_repair(monkeypatch): + requests = _planned("\n") + source = requests[0] + english = "\n".join(requests) + bad = _change_last(source) + scope = SourceContext(PATH, english, 0, len(source)) + replies = iter([bad, source]) + sent = [] + + def reply(client, model, system, messages): + sent.append(list(messages)) + return {"stop_reason": "end_turn", "content": [{"type": "text", "text": next(replies)}]} + + monkeypatch.setattr(t, "call", reply) + assert ( + t.translate_text( + source, t.LANGUAGES[0], None, t.Spend(t.DEFAULT_MODEL, 1), source_context=scope + ) + == source + ) + assert len(sent) == 2 + assert "protected source strings" in sent[1][-1]["content"] + assembled = "\n".join([bad, *requests[1:]]) + assert any("('cell', 281, 2)" in p for p in t.differences(english, assembled, source_path=PATH)) diff --git a/tests/unit/test_i18n_initial_feedback.py b/tests/unit/test_i18n_initial_feedback.py new file mode 100644 index 0000000000..d2fb9c3ff4 --- /dev/null +++ b/tests/unit/test_i18n_initial_feedback.py @@ -0,0 +1,143 @@ +"""Current-input corrections are part of the canonical request, without old replies.""" + +import pytest + +from scripts.i18n import translate as t +from scripts.i18n.context import SourceContext + +SOURCE = "Use the `keeper` backend.\n" +REPLY = "使用 `keeper` 后端。\n" +FEEDBACK = "Keep the source's backend choice and negation.\nTranslate ordinary annotations." + + +def _scope(): + return SourceContext("docs/guide.md", SOURCE, 0, len(SOURCE)) + + +def _record(monkeypatch, replies=(REPLY,)): + answers, sent = iter(replies), [] + + def call(client, model, system, messages): + sent.append((system, list(messages))) + return {"stop_reason": "end_turn", "content": [{"type": "text", "text": next(answers)}]} + + monkeypatch.setattr(t, "call", call) + return sent + + +def test_empty_feedback_keeps_existing_canonical_system_and_messages(monkeypatch): + sent = _record(monkeypatch) + lang = t.LANGUAGES[0] + assert t.request_system(lang) == t.SYSTEM.format(language=lang.english, style=lang.style) + assert t.translate_text(SOURCE, lang, None, t.Spend(t.DEFAULT_MODEL, 1)) == REPLY + assert sent == [(t.request_system(lang), [{"role": "user", "content": SOURCE}])] + + +def test_current_feedback_is_received_exactly_in_the_actual_system(monkeypatch): + sent = _record(monkeypatch) + lang = t.LANGUAGES[0] + assert ( + t.translate_text( + SOURCE, + lang, + None, + t.Spend(t.DEFAULT_MODEL, 1), + source_context=_scope(), + initial_feedback=FEEDBACK, + ) + == REPLY + ) + actual_system, messages = sent[0] + assert actual_system == t.request_system(lang, initial_feedback=FEEDBACK) + assert actual_system.startswith(t.request_system(lang) + "\n\n") + assert actual_system.endswith("\n" + FEEDBACK) + assert messages == [{"role": "user", "content": SOURCE}] + assert t.request_system(lang, initial_feedback=FEEDBACK + "!") != actual_system + + +def test_mechanical_retry_echoes_only_the_new_current_input_reply(monkeypatch): + bad = REPLY.replace("`keeper`", "`log`") + sent = _record(monkeypatch, (bad, REPLY)) + lang = t.LANGUAGES[0] + assert ( + t.translate_text( + SOURCE, + lang, + None, + t.Spend(t.DEFAULT_MODEL, 1), + source_context=_scope(), + initial_feedback=FEEDBACK, + ) + == REPLY + ) + assert len(sent) == 2 + assert sent[0][0] == sent[1][0] == t.request_system(lang, initial_feedback=FEEDBACK) + assert sent[0][1] == [{"role": "user", "content": SOURCE}] + assert sent[1][1][:2] == [ + {"role": "user", "content": SOURCE}, + {"role": "assistant", "content": bad}, + ] + assert sent[1][1][-1]["role"] == "user" + assert "inline code" in sent[1][1][-1]["content"] + + +@pytest.mark.parametrize( + "feedback", + ["x" * 4097, "非 ASCII", "a\x00b", "a\tb", "a\rb", "a\x7fb"], + ids=["oversize", "nonascii", "nul", "tab", "cr", "del"], +) +def test_invalid_feedback_is_rejected_before_spend_or_provider(monkeypatch, feedback): + sent = _record(monkeypatch) + spend = t.Spend(t.DEFAULT_MODEL, 0) + with pytest.raises(ValueError, match="feedback"): + t.translate_text( + SOURCE, t.LANGUAGES[0], None, spend, source_context=_scope(), initial_feedback=feedback + ) + assert sent == [] + + +def test_exact_feedback_byte_limit_is_allowed(): + feedback = "x" * 4096 + assert t.request_system(t.LANGUAGES[0], initial_feedback=feedback).endswith(feedback) + + +def test_nonempty_feedback_requires_current_source_context_before_spend(monkeypatch): + sent = _record(monkeypatch) + with pytest.raises(ValueError, match="source context"): + t.translate_text( + SOURCE, t.LANGUAGES[0], None, t.Spend(t.DEFAULT_MODEL, 0), initial_feedback=FEEDBACK + ) + assert not sent + + +@pytest.mark.parametrize("feedback", [FEEDBACK, ""], ids=["feedback", "default"]) +@pytest.mark.parametrize( + "start,end", [(0, len(SOURCE) - 1), (-1, len(SOURCE)), (0, len(SOURCE) + 1)] +) +def test_mismatched_context_fails_before_spend_or_provider(monkeypatch, start, end, feedback): + sent = _record(monkeypatch) + scope = SourceContext("docs/guide.md", SOURCE, start, end) + with pytest.raises(ValueError, match="source context"): + t.translate_text( + SOURCE, + t.LANGUAGES[0], + None, + t.Spend(t.DEFAULT_MODEL, 0), + source_context=scope, + initial_feedback=feedback, + ) + assert not sent + + +def test_feedback_cannot_use_an_unnamed_source_context(monkeypatch): + sent = _record(monkeypatch) + with pytest.raises(ValueError, match="source context"): + t.translate_text( + SOURCE, + t.LANGUAGES[0], + None, + t.Spend(t.DEFAULT_MODEL, 0), + source_context=SourceContext("", SOURCE, 0, len(SOURCE)), + initial_feedback=FEEDBACK, + ) + assert not sent diff --git a/tests/unit/test_i18n_lifecycle.py b/tests/unit/test_i18n_lifecycle.py new file mode 100644 index 0000000000..82f0b9b2fa --- /dev/null +++ b/tests/unit/test_i18n_lifecycle.py @@ -0,0 +1,919 @@ +"""Lifecycle changes use private Git fixtures and fake translators, with no provider calls.""" + +from __future__ import annotations + +import pathlib +import subprocess + +import pytest + +from scripts.i18n import lifecycle as lc +from scripts.i18n import translate as t + +JA = t.LANGUAGES[1] + + +def git(root: pathlib.Path, *args: str) -> str: + return subprocess.check_output(["git", *args], cwd=root, text=True).strip() + + +def put(root: pathlib.Path, name: str, text: str) -> None: + path = root / name + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(text) + + +@pytest.fixture +def repo(tmp_path: pathlib.Path, monkeypatch: pytest.MonkeyPatch) -> pathlib.Path: + git(tmp_path, "init", "-q", "-b", "main") + git(tmp_path, "config", "user.name", "test") + git(tmp_path, "config", "user.email", "test@example.test") + put(tmp_path, "docs/a.md", "# Alpha\n") + put(tmp_path, "docs/b.md", "# Beta\n") + git(tmp_path, "add", "docs") + git(tmp_path, "commit", "-qm", "English") + monkeypatch.setattr(t, "ROOT", tmp_path) + monkeypatch.setenv("LOOM_I18N_MODEL", t.DEFAULT_MODEL) + return tmp_path + + +def translated(source: str) -> str: + text, line = t.prepare(source, JA) + body = "\n".join(t.english_requests(text)) + for english, spanish in ( + ("Alpha", "Uno"), + ("Beta", "Dos"), + ("New", "Nuevo"), + ("Peer", "Par"), + ("guide", "guía"), + ): + # Anchors preserve the English spelling; translate only heading and link prose. + body = body.replace("# " + english, "# " + spanish).replace( + "[" + english + "]", "[" + spanish + "]" + ) + return t.render(source, JA, body, line, t.DEFAULT_MODEL) + + +def publish(root: pathlib.Path, source: str) -> None: + put(root, t.target_path("ja", source), translated(source)) + + +@pytest.mark.parametrize("preferred", ["docs/use-cases/index.md", "docs/index.md"]) +def test_subset_retires_its_landing_and_preserves_other_readme_navigation( + repo: pathlib.Path, monkeypatch: pytest.MonkeyPatch, preferred: str +) -> None: + from scripts.docs_site import locales + + put(repo, "README.md", "# Loom\n\n\n\n") + landings = {preferred, "docs/use-cases/index.md"} + for source in landings: + put(repo, source, "# Alpha\n") + git(repo, "add", "README.md", "docs") + for code in ("ja", "es"): + lang = next(lg for lg in t.LANGUAGES if lg.code == code) + for source in ("README.md", *sorted(landings)): + text, line = t.prepare(source, lang) + body = "\n".join(t.english_requests(text)).replace("# Alpha", "# Uno") + put( + repo, + t.target_path(code, source), + t.render(source, lang, body, line, t.DEFAULT_MODEL), + ) + publish(repo, "docs/a.md") + publish(repo, "docs/b.md") + t.write_language_lines() + assert not t.language_lines_differ() + spanish = repo / "i18n/es/README.md" + retained = spanish.read_bytes() + (repo / preferred).unlink() + t.write_language_lines(["ja"]) + assert spanish.read_bytes() == retained + assert not t.language_lines_differ() + + # An unrelated selected page still progresses through the normal fake-provider path. + put(repo, "docs/extra.md", "# Alpha\n") + git(repo, "add", "docs/extra.md") + calls = [] + monkeypatch.setenv("LOOM_I18N_MAX_USD", "5") + monkeypatch.setattr(t, "bedrock_client", object) + + def translate(source, lang, client, spend): + calls.append((source, lang.code)) + lc.stage(t.target_path(lang.code, source), translated(source)) + + monkeypatch.setattr(t, "translate_page", translate) + assert t.update(codes=["ja"]) == 0 + assert calls == [("docs/extra.md", "ja")] + assert not (repo / t.target_path("ja", preferred)).exists() + assert (repo / t.target_path("es", preferred)).is_file() + retained_uri = locales.localized_uri("es", preferred.removeprefix("docs/")) + assert locales.translations(repo)[retained_uri]["obsolete"] + assert spanish.read_bytes() == retained + assert not t.language_lines_differ() + assert t.check(skip_stale=True) == 0 + + assert lc.retire_obsolete() == (1, 0) + assert not (repo / t.target_path("es", preferred)).exists() + assert not t.language_lines_differ() + assert t.check(skip_stale=True) == 0 + + +def test_retiring_the_last_native_landing_removes_the_readme_site_link(repo: pathlib.Path) -> None: + from scripts.docs_site import indexnow + + put(repo, "README.md", "# Loom\n\n\n\n") + put(repo, "docs/index.md", "# Alpha\n") + git(repo, "add", "README.md", "docs/index.md") + for source in ("README.md", "docs/index.md"): + publish(repo, source) + t.write_language_lines() + assert indexnow.SITE in t.language_line("i18n/ja/README.md") + (repo / "docs/index.md").unlink() + assert lc.retire_obsolete(["ja"]) == (1, 0) + assert indexnow.SITE not in (repo / "i18n/ja/README.md").read_text() + assert not t.language_lines_differ() + assert t.check(skip_stale=True) == 0 + + +def test_inventory_tracks_nested_generated_additions_but_not_untracked_or_deleted( + repo: pathlib.Path, +) -> None: + put(repo, "README.md", "# Loom\n") + put(repo, "docs/reference/operations/deep.md", "# Nested\n\n") + put(repo, "docs/not tracked.md", "# Draft\n") + git(repo, "add", "README.md", "docs/reference") + (repo / "docs/a.md").unlink() + assert t.sources() == ("README.md", "docs/b.md", "docs/reference/operations/deep.md") + git(repo, "mv", "docs/b.md", "docs/renamed.md") + assert "docs/renamed.md" in t.sources() and "docs/b.md" not in t.sources() + + +def test_edit_invalidates_only_the_changed_source(repo: pathlib.Path) -> None: + publish(repo, "docs/a.md") + publish(repo, "docs/b.md") + assert t.stale((JA,)) == [] + put(repo, "docs/a.md", "# Alpha\n\nChanged.\n") + assert t.stale((JA,)) == [("docs/a.md", JA)] + + +def test_links_fall_back_until_the_translated_target_and_anchor_exist(repo: pathlib.Path) -> None: + text = "[guide](b.md#beta) ![image](asset.svg)" + assert f"[guide]({t.REPO_URL}/blob/main/docs/b.md#beta)" in t.rewrite_links( + text, "docs/a.md", "ja" + ) + publish(repo, "docs/b.md") + output = t.rewrite_links(text, "docs/a.md", "ja") + assert "[guide](b.md#beta)" in output + assert f"![image]({t.REPO_URL}/raw/main/docs/asset.svg)" in output + assert "blob/main/docs/b.md#missing" in t.rewrite_links( + "[guide](b.md#missing)", "docs/a.md", "ja" + ) + + +def test_bounded_batches_progress_without_repeating_completed_pages( + repo: pathlib.Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] +) -> None: + calls = [] + + def fake(source: str, lang: t.Language, client: object, spend: t.Spend) -> None: + calls.append(source) + lc.stage(t.target_path(lang.code, source), translated(source)) + + monkeypatch.setenv("LOOM_I18N_MAX_USD", "1") + monkeypatch.setattr(t, "estimate_usd", lambda model, chars: 1.0) + monkeypatch.setattr(t, "bedrock_client", lambda: None) + monkeypatch.setattr(t, "translate_page", fake) + assert t.update(codes=["ja"]) == 0 + assert calls == ["docs/a.md"] + assert t.update(codes=["ja"]) == 0 + assert calls == ["docs/a.md", "docs/b.md"] + assert t.stale((JA,)) == [] + assert "translated=1 failed=0 deferred=1 obsolete=0" in capsys.readouterr().out + + +def test_changed_present_pages_precede_new_pages(repo: pathlib.Path) -> None: + publish(repo, "docs/b.md") + put(repo, "docs/b.md", "# Beta\n\nEdited.\n") + selected, _ = t.batch(False, ["ja"], 5) + assert selected[0] == ("docs/b.md", JA) + + +def test_default_batches_progress_across_all_five_locales_with_one_shared_cap( + repo: pathlib.Path, monkeypatch: pytest.MonkeyPatch +) -> None: + calls: list[tuple[str, str]] = [] + + def fake(source: str, lang: t.Language, client: object, spend: t.Spend) -> None: + calls.append((source, lang.code)) + text, line = t.prepare(source, lang) + body = "\n".join(t.english_requests(text)) + body = body.replace("# Alpha", "# Uno").replace("# Beta", "# Dos") + lc.stage( + t.target_path(lang.code, source), t.render(source, lang, body, line, t.DEFAULT_MODEL) + ) + + monkeypatch.setenv("LOOM_I18N_MAX_USD", "1") + monkeypatch.setattr(t, "estimate_usd", lambda model, chars: 1.0) + monkeypatch.setattr(t, "bedrock_client", lambda: None) + monkeypatch.setattr(t, "translate_page", fake) + expected = {(source, code) for source in t.sources() for code in t.ROLLOUT_LANGUAGES} + for completed in range(1, len(expected) + 1): + assert t.main(["update"]) == 0 + assert len(calls) == completed + assert len(set(calls)) == completed + assert set(calls) == expected + assert t.stale() == [] + + +def test_checkpoint_waits_for_inbound_anchor_repair_without_retranslation( + repo: pathlib.Path, +) -> None: + put(repo, "docs/a.md", "# New\n") + put(repo, "docs/b.md", "# Peer\n\n[guide](a.md#new)\n") + put( + repo, + "i18n/ja/docs/a.md", + t.header("docs/a.md", JA, t.DEFAULT_MODEL, "0" * 40) + '\n# Anterior\n', + ) + put( + repo, + "i18n/ja/docs/b.md", + t.header("docs/b.md", JA, t.DEFAULT_MODEL, "0" * 40) + + '\n# Par\n[guía](a.md#old)\n', + ) + lc.stage("i18n/ja/docs/a.md", translated("docs/a.md")) + assert lc.activate_ready() == 0 + assert '' in (repo / "i18n/ja/docs/a.md").read_text() + selected, _ = t.batch(False, ["ja"], 5) + assert selected == [("docs/b.md", JA)] + lc.stage("i18n/ja/docs/b.md", translated("docs/b.md")) + assert lc.activate_ready() == 2 + assert t.stale((JA,)) == [] and t.link_problems() == [] + assert lc.checkpoint_files() == [] + + +def test_delete_waits_for_inbound_dependency_closure_and_removes_cycles(repo: pathlib.Path) -> None: + publish(repo, "docs/a.md") + publish(repo, "docs/b.md") + for path, target in (("a", "b"), ("b", "a")): + with (repo / f"i18n/ja/docs/{path}.md").open("a") as stream: + stream.write(f"[otra]({target}.md)\n") + put(repo, "docs/keep.md", "# Peer\n") + git(repo, "add", "docs/keep.md") + publish(repo, "docs/keep.md") + with (repo / "i18n/ja/docs/keep.md").open("a") as stream: + stream.write("[guía](a.md)\n") + (repo / "docs/a.md").unlink() + (repo / "docs/b.md").unlink() + assert lc.retire_obsolete() == (0, 2) + lc.stage("i18n/ja/docs/keep.md", translated("docs/keep.md")) + assert lc.activate_ready() == 1 + assert lc.retire_obsolete() == (2, 0) + assert t.link_problems() == [] + + +def test_unknown_output_is_never_deleted_or_overwritten( + repo: pathlib.Path, monkeypatch: pytest.MonkeyPatch +) -> None: + put(repo, "i18n/ja/docs/mine.md", "# My notes\n") + assert lc.retire_obsolete() == (0, 1) + monkeypatch.setenv("LOOM_I18N_MAX_USD", "0") + with pytest.raises(SystemExit, match="without generator ownership"): + t.update() + assert (repo / "i18n/ja/docs/mine.md").read_text() == "# My notes\n" + + +def test_rename_retires_the_old_page_after_surviving_links_are_repaired(repo: pathlib.Path) -> None: + publish(repo, "docs/a.md") + put(repo, "docs/b.md", "# Beta\n\n[guide](a.md)\n") + publish(repo, "docs/b.md") + git(repo, "mv", "docs/a.md", "docs/new.md") + put(repo, "docs/b.md", "# Beta\n\n[guide](new.md)\n") + assert lc.retire_obsolete() == (0, 1) + for source in ("docs/new.md", "docs/b.md"): + lc.stage(t.target_path("ja", source), translated(source)) + assert lc.activate_ready() == 2 + assert lc.retire_obsolete() == (1, 0) + assert t.link_problems() == [] + + +def pending_branch(repo: pathlib.Path, path: str, text: str) -> str: + git(repo, "switch", "-qc", "i18n/update") + put(repo, path, text) + git(repo, "add", "i18n") + git(repo, "commit", "-qm", "Generated") + sha = git(repo, "rev-parse", "HEAD") + git(repo, "switch", "-q", "main") + return sha + + +def test_pending_branch_data_is_reused_and_fresh_main_wins(repo: pathlib.Path) -> None: + text = translated("docs/a.md") + sha = pending_branch(repo, "i18n/ja/docs/a.md", text) + assert t.import_pending(sha) == 1 + assert (repo / "i18n/ja/docs/a.md").read_text() == text + fresh = text + "\nTexto revisado.\n" + put(repo, "i18n/ja/docs/a.md", fresh) + assert t.import_pending(sha) == 0 + assert (repo / "i18n/ja/docs/a.md").read_text() == fresh + + +@pytest.mark.parametrize("change", ["stale", "html", "banner", "model", "code"]) +def test_invalid_pending_output_is_rejected(repo: pathlib.Path, change: str) -> None: + text = translated("docs/a.md") + if change == "html": + text += '\n' + elif change == "banner": + text = text.replace("Machine-translated", "Translated") + elif change == "model": + text = text.replace(t.DEFAULT_MODEL, "unknown-model") + elif change == "code": + text += "```sh\nunsafe-command\n```\n" + sha = pending_branch(repo, "i18n/ja/docs/a.md", text) + if change == "stale": + put(repo, "docs/a.md", "# Alpha\n\nEdited.\n") + assert t.import_pending(sha) == 0 + assert not (repo / "i18n/ja/docs/a.md").exists() + + +def test_symlink_source_or_output_is_refused( + repo: pathlib.Path, monkeypatch: pytest.MonkeyPatch +) -> None: + (repo / "docs/a.md").unlink() + (repo / "docs/a.md").symlink_to("b.md") + with pytest.raises(SystemExit, match="not a regular"): + t.sources() + (repo / "docs/a.md").unlink() + put(repo, "i18n/ja/docs/a.md", "temporary") + (repo / "i18n/ja/docs/a.md").unlink() + (repo / "i18n/ja/docs/a.md").symlink_to(repo / "docs/b.md") + monkeypatch.setenv("LOOM_I18N_MAX_USD", "0") + with pytest.raises(SystemExit, match="nonregular"): + t.update() + assert (repo / "docs/b.md").read_text() == "# Beta\n" + + +def test_strict_reports_missing_stale_and_obsolete_while_async_validates_present_files( + repo: pathlib.Path, capsys: pytest.CaptureFixture[str] +) -> None: + publish(repo, "docs/a.md") + publish(repo, "docs/b.md") + put(repo, "docs/b.md", "# Beta\n\nEdited.\n") + (repo / "docs/a.md").unlink() + put(repo, "docs/new.md", "# New\n") + git(repo, "add", "docs/new.md") + assert t.check() == 1 + output = capsys.readouterr().out + assert "i18n/ja/docs/a.md is outside" in output + assert "i18n/ja/docs/new.md is missing or stale" in output + assert "i18n/ja/docs/b.md is missing or stale" in output + assert t.check(skip_stale=True) == 0 + with (repo / "i18n/ja/docs/a.md").open("a") as stream: + stream.write("[rota](absent.md)\n") + assert t.check(skip_stale=True) == 1 + + +def test_reservation_books_all_verifier_and_api_attempts(repo: pathlib.Path) -> None: + reservation = t.batch_reservation(codes=["ja"], cap=5) + minimum_outputs = 2 * 2 * 4 * t.MAX_TOKENS * t.PRICES[t.DEFAULT_MODEL][1] / 1e6 + assert reservation > minimum_outputs + assert t.batch_reservation(codes=["ja"], cap=0) == 0 + + +def test_encoded_source_paths_are_resolved_and_encoded_once(repo: pathlib.Path) -> None: + put(repo, "docs/space name.md", "# Beta\n") + git(repo, "add", "docs/space name.md") + text = "[guide](space%20name.md#beta)" + fallback = t.rewrite_links(text, "docs/a.md", "ja") + assert fallback == f"[guide]({t.REPO_URL}/blob/main/docs/space%20name.md#beta)" + publish(repo, "docs/space name.md") + localized = t.rewrite_links(text, "docs/a.md", "ja") + assert localized == text + assert lc.canonical_links(localized, "i18n/ja/docs/a.md") == fallback + + +def test_import_refuses_to_overwrite_unowned_published_data(repo: pathlib.Path) -> None: + text = translated("docs/a.md") + sha = pending_branch(repo, "i18n/ja/docs/a.md", text) + put(repo, "i18n/ja/docs/a.md", "# My notes\n") + with pytest.raises(SystemExit, match="without generator ownership"): + t.import_pending(sha) + assert (repo / "i18n/ja/docs/a.md").read_text() == "# My notes\n" + + +@pytest.mark.parametrize("limit", ["page", "total"]) +def test_import_refuses_size_before_reading_blob_contents( + repo: pathlib.Path, monkeypatch: pytest.MonkeyPatch, limit: str +) -> None: + text = translated("docs/a.md") + sha = pending_branch(repo, "i18n/ja/docs/a.md", text) + monkeypatch.setattr(lc, "MAX_PAGE_BYTES" if limit == "page" else "MAX_PENDING_BYTES", 1) + run = subprocess.run + + def checked(*args, **kwargs): + assert args[0][0:3] != ["git", "cat-file", "blob"], "oversized content was loaded" + return run(*args, **kwargs) + + monkeypatch.setattr(lc.subprocess, "run", checked) + with pytest.raises(SystemExit, match="size limit"): + t.import_pending(sha) + assert not (repo / "i18n/ja/docs/a.md").exists() + + +def test_deleted_english_body_fallback_repairs_to_owned_target_before_retirement( + repo: pathlib.Path, +) -> None: + put(repo, "docs/b.md", "# Beta\n\n[guide](a.md#alpha)\n") + publish(repo, "docs/b.md") + old_url = f"{t.REPO_URL}/blob/main/docs/a.md#alpha" + assert old_url in (repo / "i18n/ja/docs/b.md").read_text() + publish(repo, "docs/a.md") + provenance = (repo / "i18n/ja/docs/a.md").read_text() + git(repo, "mv", "docs/a.md", "docs/new.md") + put(repo, "docs/b.md", "# Beta\n\n[guide](new.md#alpha)\n") + assert any("English destination or anchor" in problem for problem in lc.link_problems()) + assert lc.retire_obsolete() == (0, 1) + assert "[guía](a.md#alpha)" in (repo / "i18n/ja/docs/b.md").read_text() + assert old_url not in (repo / "i18n/ja/docs/b.md").read_text() + assert (repo / "i18n/ja/docs/a.md").read_text() == provenance + assert lc.link_problems() == [] + for source in ("docs/new.md", "docs/b.md"): + lc.stage(t.target_path("ja", source), translated(source)) + assert lc.activate_ready() == 2 + assert lc.retire_obsolete() == (1, 0) + assert lc.link_problems() == [] + + +@pytest.mark.parametrize("target", ["missing", "wrong-fragment"]) +def test_unrepairable_deleted_english_fallback_refuses_closure_and_retains_target( + repo: pathlib.Path, + target: str, +) -> None: + put(repo, "docs/b.md", "# Beta\n\n[guide](a.md#alpha)\n") + publish(repo, "docs/b.md") + if target == "wrong-fragment": + put( + repo, + "i18n/ja/docs/a.md", + t.header("docs/a.md", JA, t.DEFAULT_MODEL, "0" * 40) + '\n# Otro\n', + ) + before = (repo / "i18n/ja/docs/b.md").read_text() + git(repo, "mv", "docs/a.md", "docs/new.md") + put(repo, "docs/b.md", "# Beta\n\n[guide](new.md#alpha)\n") + assert lc.retire_obsolete() == (0, int(target == "wrong-fragment")) + assert (repo / "i18n/ja/docs/b.md").read_text() == before + assert any("English destination or anchor" in problem for problem in lc.link_problems()) + assert t.check(skip_stale=True) == 1 + + +def test_fallback_validation_checks_english_fragments_but_excludes_banner_and_external_urls( + repo: pathlib.Path, +) -> None: + put(repo, "docs/b.md", "# Beta\n\n[guide](a.md#alpha)\n") + publish(repo, "docs/b.md") + assert lc.link_problems() == [] + path = repo / "i18n/ja/docs/b.md" + path.write_text(path.read_text().replace("a.md#alpha", "a.md#missing")) + assert any("English destination or anchor" in problem for problem in lc.link_problems()) + path.unlink() + publish(repo, "docs/a.md") + with (repo / "i18n/ja/docs/a.md").open("a") as stream: + stream.write("[externo](https://example.test/blob/main/docs/missing.md#missing)\n") + (repo / "docs/a.md").unlink() + assert ( + lc.link_problems() == [] + ) # Missing original-source provenance is distinct from body links. + assert lc.retire_obsolete() == (1, 0) + + +def test_selected_retirement_preserves_deferred_locale_artifacts_and_cross_locale_dependencies( + repo: pathlib.Path, +) -> None: + publish(repo, "docs/a.md") + es = next(lang for lang in t.LANGUAGES if lang.code == "es") + preserved = t.header("docs/a.md", es, t.DEFAULT_MODEL, t.blob("docs/a.md")) + "# Uno\n" + put(repo, "i18n/es/docs/a.md", preserved) + cross_locale = ( + t.header("docs/b.md", es, t.DEFAULT_MODEL, t.blob("docs/b.md")) + + "[guía](../../ja/docs/a.md)\n" + ) + put(repo, "i18n/es/docs/b.md", cross_locale) + (repo / "docs/a.md").unlink() + assert lc.retire_obsolete(["ja"]) == (0, 2) + assert (repo / "i18n/es/docs/a.md").read_text() == preserved + assert (repo / "i18n/es/docs/b.md").read_text() == cross_locale + # The retained nonselected inbound edge prevents deleting the Japanese target. + assert (repo / "i18n/ja/docs/a.md").exists() + + +def test_selected_fallback_repair_leaves_deferred_body_bytes_untouched(repo: pathlib.Path) -> None: + put(repo, "docs/b.md", "# Beta\n\n[guide](a.md#alpha)\n") + publish(repo, "docs/b.md") + es = next(lang for lang in t.LANGUAGES if lang.code == "es") + spanish = translated("docs/b.md").replace( + t.header("docs/b.md", JA, t.DEFAULT_MODEL, t.blob("docs/b.md")), + t.header("docs/b.md", es, t.DEFAULT_MODEL, t.blob("docs/b.md")), + 1, + ) + put(repo, "i18n/es/docs/b.md", spanish) + publish(repo, "docs/a.md") + put( + repo, + "i18n/es/docs/a.md", + translated("docs/a.md").replace( + t.header("docs/a.md", JA, t.DEFAULT_MODEL, t.blob("docs/a.md")), + t.header("docs/a.md", es, t.DEFAULT_MODEL, t.blob("docs/a.md")), + 1, + ), + ) + git(repo, "mv", "docs/a.md", "docs/new.md") + put(repo, "docs/b.md", "# Beta\n\n[guide](new.md#alpha)\n") + lc.retire_obsolete(["ja"]) + assert "[guía](a.md#alpha)" in (repo / "i18n/ja/docs/b.md").read_text() + assert (repo / "i18n/es/docs/b.md").read_text() == spanish + assert (repo / "i18n/es/docs/a.md").exists() + + +def test_selected_activation_never_deletes_deferred_stale_checkpoint(repo: pathlib.Path) -> None: + es = next(lang for lang in t.LANGUAGES if lang.code == "es") + retained = t.header("docs/a.md", es, t.DEFAULT_MODEL, "0" * 40) + "# Conservado\n" + put(repo, "i18n/.pending/es/docs/a.md", retained) + assert lc.activate_ready(["ja"]) == 0 + assert (repo / "i18n/.pending/es/docs/a.md").read_text() == retained + + +def test_import_never_overwrites_existing_nonselected_published_or_checkpoint_bytes( + repo: pathlib.Path, +) -> None: + es = next(lang for lang in t.LANGUAGES if lang.code == "es") + base = translated("docs/a.md").replace( + t.header("docs/a.md", JA, t.DEFAULT_MODEL, t.blob("docs/a.md")), + t.header("docs/a.md", es, t.DEFAULT_MODEL, t.blob("docs/a.md")), + 1, + ) + incoming = base + "\nTexto remoto.\n" + sha = pending_branch(repo, "i18n/es/docs/a.md", incoming) + published = base.replace(t.blob("docs/a.md"), "0" * 40) + checkpoint = base + "\nTexto conservado.\n" + put(repo, "i18n/es/docs/a.md", published) + put(repo, "i18n/.pending/es/docs/a.md", checkpoint) + with pytest.raises(SystemExit, match="pending replacement refused"): + t.import_pending(sha, ["ja"]) + assert (repo / "i18n/es/docs/a.md").read_text() == published + assert (repo / "i18n/.pending/es/docs/a.md").read_text() == checkpoint + + +@pytest.mark.parametrize("source_state", ["stale", "deleted"]) +@pytest.mark.parametrize("incoming_path", ["i18n/es/docs/a.md", "i18n/.pending/es/docs/a.md"]) +def test_replacing_pending_branch_preserves_remote_only_deferred_stale_or_orphan_bytes( + repo: pathlib.Path, + monkeypatch: pytest.MonkeyPatch, + source_state: str, + incoming_path: str, +) -> None: + es = next(lang for lang in t.LANGUAGES if lang.code == "es") + retained = ( + t.header("docs/a.md", es, t.DEFAULT_MODEL, t.blob("docs/a.md")) + + '\n# Uno\n\nTexto conservado.\n' + ) + previous = pending_branch(repo, incoming_path, retained) + if source_state == "deleted": + (repo / "docs/a.md").unlink() + else: + put(repo, "docs/a.md", "# Alpha\n\nContenido cambiado.\n") + git(repo, "add", "docs") + git(repo, "commit", "-qm", "English lifecycle") + monkeypatch.setenv("LOOM_I18N_MAX_USD", "0") + monkeypatch.setattr( + t, "bedrock_client", lambda: pytest.fail("archival data must not regenerate") + ) + assert t.import_pending(previous, ["ja"]) == 1 + archive = "i18n/.pending/es/docs/a.md" + assert (repo / archive).read_bytes() == retained.encode() + assert not (repo / "i18n/es/docs/a.md").exists() + assert "i18n/es/docs/a.md" not in lc.current_checkpoints() + assert t.update(codes=["ja"]) == 0 + assert (repo / archive).read_bytes() == retained.encode() + git(repo, "add", "i18n") + tree = git(repo, "write-tree") + replacement = git( + repo, + "commit-tree", + tree, + "-p", + git(repo, "rev-parse", "HEAD"), + "-m", + "Prepared Japanese batch", + ) + git(repo, "update-ref", "refs/heads/i18n/update", replacement, previous) + assert ( + subprocess.check_output(["git", "show", f"i18n/update:{archive}"], cwd=repo) + == retained.encode() + ) + + +@pytest.mark.parametrize("damage", ["banner", "model"]) +def test_deferred_archival_refuses_unknown_ownership_metadata( + repo: pathlib.Path, + damage: str, +) -> None: + es = next(lang for lang in t.LANGUAGES if lang.code == "es") + text = t.header("docs/a.md", es, t.DEFAULT_MODEL, "0" * 40) + "# Uno\n" + text = ( + text.replace("Machine-translated", "Altered") + if damage == "banner" + else text.replace(t.DEFAULT_MODEL, "unknown-model") + ) + sha = pending_branch(repo, "i18n/.pending/es/docs/a.md", text) + with pytest.raises(SystemExit, match="ownership/banner/model"): + t.import_pending(sha, ["ja"]) + assert not (repo / "i18n/.pending/es/docs/a.md").exists() + + +def readme_baseline(repo: pathlib.Path, codes: list[str]) -> None: + put(repo, "README.md", "# Source\n\n\n\n") + for code in codes: + lang = next(item for item in t.LANGUAGES if item.code == code) + put(repo, t.target_path(code, "README.md"), readme_translation("README.md", lang)) + t.write_language_lines() + for code in codes: + lang = next(item for item in t.LANGUAGES if item.code == code) + put(repo, t.target_path(code, "README.md"), readme_translation("README.md", lang)) + put(repo, ".github/workflows/ci.yml", "name: trusted\n") + git(repo, "add", ".") + git(repo, "commit", "-qm", "Current language links") + + +def readme_translation(source: str, lang: t.Language) -> str: + text, line = t.prepare(source, lang) + body = "\n".join(t.english_requests(text)) + for english, target in (("Source", "Traducido"), ("Alpha", "Uno"), ("Beta", "Dos")): + body = body.replace("# " + english, "# " + target) + return t.render(source, lang, body, line, t.DEFAULT_MODEL) + + +def fake_readme_generation( + monkeypatch: pytest.MonkeyPatch, calls: list[tuple[str, str]], *, cap: str = "1" +) -> None: + def fake(source: str, lang: t.Language, client: object, spend: t.Spend) -> None: + calls.append((source, lang.code)) + lc.stage(t.target_path(lang.code, source), readme_translation(source, lang)) + + monkeypatch.setenv("LOOM_I18N_MAX_USD", cap) + monkeypatch.setattr(t, "estimate_usd", lambda model, chars: 1.0) + monkeypatch.setattr(t, "bedrock_client", lambda: None) + monkeypatch.setattr(t, "translate_page", fake) + + +@pytest.mark.parametrize("codes", [None, list(t.ROLLOUT_LANGUAGES)]) +@pytest.mark.parametrize("japanese_exists", [False, True]) +def test_readme_bootstrap_publishes_valid_language_lines( + repo: pathlib.Path, + monkeypatch: pytest.MonkeyPatch, + codes: list[str] | None, + japanese_exists: bool, +) -> None: + from scripts.i18n import automation + + readme_baseline(repo, ["es", "ja"] if japanese_exists else ["es"]) + calls: list[tuple[str, str]] = [] + fake_readme_generation(monkeypatch, calls, cap="0" if japanese_exists else "1") + assert t.check(skip_stale=True) == 0 + assert t.update(codes=codes) == 0 + assert calls == ([] if japanese_exists else [("README.md", "ja")]) + assert (repo / "i18n/ja/README.md").is_file() + assert t.check(skip_stale=True) == 0 + assert t.language_lines_differ() == [] + base = git(repo, "rev-parse", "HEAD") + git(repo, "add", ".") + candidate = git(repo, "commit-tree", git(repo, "write-tree"), "-p", base, "-m", "Generated") + automation.validate_changes(base, candidate) + + +def test_partial_batch_defers_new_readme_without_spending_or_changing_other_locales( + repo: pathlib.Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] +) -> None: + readme_baseline(repo, ["es"]) + spanish = (repo / "i18n/es/README.md").read_bytes() + calls: list[tuple[str, str]] = [] + fake_readme_generation(monkeypatch, calls) + assert t.update(codes=["ja"]) == 0 + assert calls == [("docs/a.md", "ja")] + assert "deferred i18n/ja/README.md" in capsys.readouterr().out + assert (repo / "i18n/es/README.md").read_bytes() == spanish + assert not (repo / "i18n/ja/README.md").exists() + assert t.check(skip_stale=True) == 0 + pending = repo / lc.checkpoint_path(t.target_path("ja", "README.md")) + lc.stage(t.target_path("ja", "README.md"), readme_translation("README.md", JA)) + retained = pending.read_bytes() + assert lc.activate_ready(["ja"]) == 0 + assert pending.read_bytes() == retained + assert (repo / "i18n/es/README.md").read_bytes() == spanish + assert t.check(skip_stale=True) == 0 + assert lc.activate_ready(list(t.ROLLOUT_LANGUAGES)) == 1 + assert not pending.exists() + assert (repo / "i18n/ja/README.md").is_file() + assert t.check(skip_stale=True) == 0 + + +def test_new_readme_waits_for_a_stale_published_readme_instead_of_restamping_it( + repo: pathlib.Path, +) -> None: + readme_baseline(repo, ["es"]) + path = repo / "README.md" + path.write_text(path.read_text().replace("# Source", "# Changed")) + spanish = (repo / "i18n/es/README.md").read_bytes() + t.write_language_lines() + assert (repo / "i18n/es/README.md").read_bytes() == spanish + text, line = t.prepare("README.md", JA) + body = "\n".join(t.english_requests(text)).replace("# Changed", "# Nuevo") + lc.stage( + t.target_path("ja", "README.md"), t.render("README.md", JA, body, line, t.DEFAULT_MODEL) + ) + pending = repo / lc.checkpoint_path(t.target_path("ja", "README.md")) + retained = pending.read_bytes() + assert lc.activate_ready(list(t.ROLLOUT_LANGUAGES)) == 0 + assert pending.read_bytes() == retained + assert (repo / "i18n/es/README.md").read_bytes() == spanish + assert not (repo / "i18n/ja/README.md").exists() + + +def test_readme_bar_repair_preserves_refresh_proofs_without_a_second_provider_call( + repo: pathlib.Path, monkeypatch: pytest.MonkeyPatch +) -> None: + from scripts.i18n import refresh + + readme_baseline(repo, ["es"]) + calls: list[tuple[str, str]] = [] + fake_readme_generation(monkeypatch, calls) + assert t.update(every=True, codes=list(t.ROLLOUT_LANGUAGES)) == 0 + assert t.update(codes=list(t.ROLLOUT_LANGUAGES)) == 0 + assert calls == [("README.md", "es"), ("README.md", "ja")] + job = refresh.read() + assert job is not None + for code in ("es", "ja"): + path = t.target_path(code, "README.md") + assert refresh.done(path, job) + assert job["completed"][path]["blob"] == t.blob("README.md") + assert job["completed"][path]["sha256"] == refresh.digest((repo / path).read_text()) + monkeypatch.setenv("LOOM_I18N_MAX_USD", "0") + assert t.update(codes=list(t.ROLLOUT_LANGUAGES)) == 0 + assert calls == [("README.md", "es"), ("README.md", "ja")] + assert t.check(skip_stale=True) == 0 + + +def test_readme_bootstrap_retains_conflicted_refresh_candidate( + repo: pathlib.Path, monkeypatch: pytest.MonkeyPatch +) -> None: + from scripts.i18n import refresh + + readme_baseline(repo, ["es"]) + calls: list[tuple[str, str]] = [] + fake_readme_generation(monkeypatch, calls) + assert t.update(every=True, codes=list(t.ROLLOUT_LANGUAGES)) == 0 + spanish_path = repo / "i18n/es/README.md" + generated = spanish_path.read_text() + spanish_path.write_text(generated + "\nTexto manual.\n") + manual = spanish_path.read_bytes() + lc.stage("i18n/es/README.md", generated) + lc.stage("i18n/ja/README.md", readme_translation("README.md", JA)) + refresh.record("README.md", JA, "") + proof = refresh.read() + assert proof is not None and refresh.blocked("i18n/es/README.md", proof) + pending = { + name: (repo / name).read_bytes() + for name in ("i18n/.pending/es/README.md", "i18n/.pending/ja/README.md") + } + assert lc.activate_ready(list(t.ROLLOUT_LANGUAGES)) == 0 + assert spanish_path.read_bytes() == manual + assert not (repo / "i18n/ja/README.md").exists() + assert all((repo / name).read_bytes() == text for name, text in pending.items()) + assert refresh.read() == proof + assert calls == [("README.md", "es")] + + +@pytest.mark.parametrize("every", [False, True]) +@pytest.mark.parametrize("english_changed", [False, True]) +def test_pending_readme_bootstrap_is_reused_before_its_english_bar_merges( + repo: pathlib.Path, + monkeypatch: pytest.MonkeyPatch, + every: bool, + english_changed: bool, +) -> None: + readme_baseline(repo, ["es"]) + base = git(repo, "rev-parse", "HEAD") + calls: list[tuple[str, str]] = [] + fake_readme_generation(monkeypatch, calls) + assert t.update(every=every, codes=list(t.ROLLOUT_LANGUAGES)) == 0 + if every: + assert t.update(codes=list(t.ROLLOUT_LANGUAGES)) == 0 + japanese = (repo / "i18n/ja/README.md").read_bytes() + git(repo, "add", ".") + git(repo, "commit", "-qm", "Pending verified translations") + candidate = git(repo, "rev-parse", "HEAD") + git(repo, "switch", "-qc", "unmerged-main", base) + assert not (repo / "i18n/ja/README.md").exists() + if english_changed: + readme = repo / "README.md" + readme.write_text(readme.read_text().replace("# Source", "# Changed")) + english = readme.read_bytes() + spanish = (repo / "i18n/es/README.md").read_bytes() + assert t.import_pending(candidate, list(t.ROLLOUT_LANGUAGES)) == 0 + assert not (repo / "i18n/ja/README.md").exists() + assert readme.read_bytes() == english + assert (repo / "i18n/es/README.md").read_bytes() == spanish + return + retained = lc.pending_blobs(candidate) + called = list(calls) + with pytest.raises(SystemExit, match="full approved language selection"): + t.import_pending(candidate, ["ja"]) + assert git(repo, "status", "--porcelain") == "" + assert lc.pending_blobs(candidate) == retained + assert calls == called + assert t.import_pending(candidate, list(t.ROLLOUT_LANGUAGES)) > 0 + assert (repo / "i18n/ja/README.md").read_bytes() == japanese + assert t.check(skip_stale=True) == 0 + assert t.update(codes=list(t.ROLLOUT_LANGUAGES)) == 0 + assert calls.count(("README.md", "ja")) == 1 + assert calls.count(("README.md", "es")) == int(every) + assert calls[-1] == ("README.md", "ko") + + +@pytest.mark.parametrize("change", ["exact", "spelling", "qualifier"]) +def test_composed_lifecycle_keeps_source_attested_name_obligations( + repo: pathlib.Path, change: str +) -> None: + source = "docs/benchmarks/results.md" + english = "# MemBench\n\n## Details\n" + if change == "qualifier": + english = english.replace("# MemBench", "# MemBench samples") + put(repo, source, english) + git(repo, "add", source) + body = "\n".join(t.english_requests(english)).replace("## Details", "## 詳細") + if change == "spelling": + body = body.replace("# MemBench", "# MemBenxh") + candidate = t.render(source, JA, body, "", t.DEFAULT_MODEL) + problems = lc.candidate_problems(t.target_path("ja", source), candidate) + assert bool(problems) == (change != "exact") + + +@pytest.mark.parametrize("action", ["candidate", "stage", "import"]) +@pytest.mark.parametrize("change", ["row", "column"]) +def test_composed_stored_table_layout_is_checked_before_reuse( + repo: pathlib.Path, action: str, change: str +) -> None: + source = "docs/a.md" + english = "# Alpha\n\n| Name | Value |\n| --- | --- |\n| First label | First value |\n" + english += "| Second label | Second value |\n" + put(repo, source, english) + body = "\n".join(t.english_requests(english)) + for old, new in ( + ("# Alpha", "# 日本語"), + ("Name", "名称"), + ("Value", "値"), + ("First label", "最初の名前"), + ("First value", "最初の値"), + ("Second label", "次の名前"), + ("Second value", "次の値"), + ): + body = body.replace(old, new) + if change == "row": + body = body.replace("| 次の名前 | 次の値 |\n", "") + else: + body = body.replace("| 名称 | 値 |", "| 名称 | 値 | 追加 |") + body = body.replace("| --- | --- |", "| --- | --- | --- |") + path = t.target_path("ja", source) + candidate = t.render(source, JA, body, "", t.DEFAULT_MODEL) + if action == "candidate": + assert any( + "table row/cell layout" in problem for problem in lc.candidate_problems(path, candidate) + ) + elif action == "stage": + with pytest.raises(t.TranslationDiffers, match="table row/cell layout"): + lc.stage(path, candidate) + assert not (repo / lc.checkpoint_path(path)).exists() + else: + sha = pending_branch(repo, path, candidate) + assert t.import_pending(sha) == 0 + assert not (repo / path).exists() + + +def test_composed_lifecycle_stages_native_table_rows_without_changing_body( + repo: pathlib.Path, +) -> None: + source = "docs/a.md" + put(repo, source, "# Alpha\n\n| Name | Value |\n| --- | --- |\n| First label | First value |\n") + body = "\n".join(t.english_requests((repo / source).read_text())) + for old, new in ( + ("# Alpha", "# 日本語"), + ("Name", "名称"), + ("Value", "値"), + ("First label", "名前"), + ("First value", "値"), + ): + body = body.replace(old, new) + path = t.target_path("ja", source) + candidate = t.render(source, JA, body, "", t.DEFAULT_MODEL) + assert lc.candidate_problems(path, candidate) == [] + lc.stage(path, candidate) + assert (repo / lc.checkpoint_path(path)).read_text() == candidate diff --git a/tests/unit/test_i18n_reconcile.py b/tests/unit/test_i18n_reconcile.py new file mode 100644 index 0000000000..109618b38a --- /dev/null +++ b/tests/unit/test_i18n_reconcile.py @@ -0,0 +1,551 @@ +"""Completed translation units retain their authenticated cuts across source edits.""" + +from dataclasses import replace +from hashlib import sha256 +from itertools import pairwise + +import pytest + +from scripts.i18n import chunks +from scripts.i18n.context import SourceContext +from scripts.i18n.reconcile import ( + OriginalUnit, + PreparedSource, + UnitFault, + original_unit_manifest_sha256, + reconcile_completed_units, +) + + +def _reconcile(historical, current, units, **kwargs): + return reconcile_completed_units( + historical, + current, + units, + unit_manifest_sha256=original_unit_manifest_sha256(units), + **kwargs, + ) + + +def _source(text): + return PreparedSource("docs/guide.md", text, sha256(text.encode()).hexdigest()) + + +def _history(*parts): + return _history_with_separators(parts, ("\n",) * (len(parts) - 1)) + + +def _history_with_separators(parts, separators): + source = _source("".join(p + s for p, s in zip(parts, (*separators, ""), strict=True))) + units, start = [], 0 + for i, (part, separator) in enumerate(zip(parts, (*separators, ""), strict=True)): + units.append( + OriginalUnit(start, start + len(part), sha256(part.encode()).hexdigest(), str(i)) + ) + start += len(part) + len(separator) + return source, tuple(units) + + +def _texts(plan): + return [u.scope.english[u.scope.start : u.scope.end] for u in plan.units] + + +def _assert_assembly(plan): + assert not plan.conflicts + assert ( + "".join(u.separator_before + text for u, text in zip(plan.units, _texts(plan), strict=True)) + + plan.trailing_separator + == plan.current.english + ) + + +def test_large_completed_whole_page_is_free_reuse(): + old, units = _history("An indivisible paragraph " + "界" * 6000) + plan = _reconcile(old, old, units) + _assert_assembly(plan) + assert [u.disposition for u in plan.units] == ["reuse"] + assert plan.units[0].original == units[0] + + +def test_insertion_uses_current_context_and_keeps_original_neighbors(): + old, units = _history("First paragraph.\n", "Final paragraph.\n") + current = _source("First paragraph.\n\nInserted paragraph.\n\nFinal paragraph.\n") + plan = _reconcile(old, current, units) + _assert_assembly(plan) + assert [u.disposition for u in plan.units] == ["reuse", "new", "reuse"] + assert [u.original for u in plan.units] == [units[0], None, units[1]] + assert all( + u.scope.path == current.path and u.scope.english == current.english for u in plan.units + ) + + +def test_removal_never_repackages_retained_units(): + old, units = _history("First.\n", "Removed.\n", "Last.\n") + current = _source("First.\n\nLast.\n") + plan = _reconcile(old, current, units) + _assert_assembly(plan) + assert [u.original for u in plan.units] == [units[0], units[2]] + assert plan.removed == (units[1],) + + +def test_changed_unit_coalesces_faults_without_old_assistant_replay(): + old, units = _history("First.\n", "Old statement.\n", "Last.\n") + current = _source("First.\n\nChanged statement.\n\nLast.\n") + faults = (UnitFault("1", "semantic"), UnitFault("1", "language"), UnitFault("1", "semantic")) + plan = _reconcile(old, current, units, faults=faults) + _assert_assembly(plan) + assert [u.disposition for u in plan.units] == ["reuse", "changed", "reuse"] + assert plan.units[1].fault_ids == ("language", "semantic") + assert _texts(plan)[1] == "Changed statement.\n" + + +def test_unchanged_fault_is_explicit_original_unit_correction(): + old, units = _history("First.\n", "Last.\n") + plan = _reconcile(old, old, units, faults=(UnitFault("1", "semantic"),)) + _assert_assembly(plan) + assert [u.disposition for u in plan.units] == ["reuse", "correction"] + assert plan.units[1].original == units[1] + + +@pytest.mark.parametrize("text", ["Repeated.\n\nRepeated.\n", "Repeated.\n\nExtra.\n\nRepeated.\n"]) +def test_repeated_whole_unit_is_an_explicit_ambiguity(text): + old, units = _history("Repeated.\n", "Repeated.\n") + plan = _reconcile(old, _source(text), units) + assert [c.kind for c in plan.conflicts] == ["ambiguity"] + assert not plan.units + + +@pytest.mark.parametrize("wrapper", [("
\n\n", "\n
\n"), ("```text\n", "```\n")]) +def test_identical_text_inside_a_new_protected_container_is_not_reused(wrapper): + old, units = _history("First.\n", "Last.\n") + current = _source(wrapper[0] + old.english + wrapper[1]) + plan = _reconcile(old, current, units) + assert plan.conflicts + assert not plan.units + + +def test_pair_refusal_blocks_even_unchanged_source(): + old, units = _history("A paragraph.\n") + plan = _reconcile(old, old, units, pair_refused=True) + assert [c.kind for c in plan.conflicts] == ["refusal"] + assert not plan.units + + +@pytest.mark.parametrize("change", ["container", "unit", "gap", "context"]) +def test_unauthenticated_or_incomplete_history_is_a_conflict(change): + old, units = _history("First.\n", "Last.\n") + current = old + if change == "container": + old = replace(old, sha256="wrong") + elif change == "unit": + units = (replace(units[0], source_sha256="wrong"), units[1]) + elif change == "gap": + units = units[1:] + else: + current = replace(current, path="docs/other.md") + plan = _reconcile(old, current, units) + assert plan.conflicts + assert not plan.units + + +def test_changed_historical_whole_page_is_not_repaid(): + old, units = _history("Original page.\n") + plan = _reconcile(old, _source("Changed page.\n"), units) + assert [c.kind for c in plan.conflicts] == ["whole_page_replacement"] + + +def test_multiple_changed_units_refuse_to_guess_a_new_partition(): + old, units = _history("First.\n", "Old one.\n", "Old two.\n", "Last.\n") + current = _source("First.\n\nReplacement one.\n\nReplacement two.\n\nLast.\n") + plan = _reconcile(old, current, units) + assert [c.kind for c in plan.conflicts] == ["boundary"] + assert not plan.units + + +def test_reordered_units_are_not_reused_in_new_order(): + old, units = _history("First.\n", "Last.\n") + plan = _reconcile(old, _source("Last.\n\nFirst.\n"), units) + assert [c.kind for c in plan.conflicts] == ["ambiguity"] + + +def test_fault_cannot_target_an_unknown_reply(): + old, units = _history("First.\n", "Last.\n") + plan = _reconcile(old, old, units, faults=(UnitFault("absent", "fault"),)) + assert [c.kind for c in plan.conflicts] == ["context"] + + +def test_faulty_large_original_unit_cannot_be_sent_again(): + old, units = _history("First.\n", "界" * 6000 + "\n", "Last.\n") + free = _reconcile(old, old, units) + _assert_assembly(free) + repair = _reconcile(old, old, units, faults=(UnitFault("1", "fault"),)) + assert [c.kind for c in repair.conflicts] == ["boundary"] + assert not repair.units + + +def test_new_gap_is_bounded_without_splitting_completed_neighbors(): + old, units = _history("First.\n", "Last.\n") + paragraphs = "Inserted paragraph " + "界" * 2000 + "\n\n" + current = _source("First.\n\n" + paragraphs * 3 + "Last.\n") + plan = _reconcile(old, current, units) + _assert_assembly(plan) + assert plan.units[0].original == units[0] and plan.units[-1].original == units[-1] + assert len(plan.units) > 3 + assert all( + len(text.encode()) <= chunks.MAX_BYTES + for u, text in zip(plan.units, _texts(plan), strict=True) + if u.disposition != "reuse" + ) + + +def test_twenty_one_original_units_with_only_first_two_completed(): + old, units = _history(*(f"Unit {i:02d}. " + "source " * 200 + "\n" for i in range(21))) + units = tuple(unit if i < 2 else replace(unit, reply_ref=None) for i, unit in enumerate(units)) + plan = _reconcile(old, old, units) + _assert_assembly(plan) + assert [unit.original for unit in plan.units if unit.disposition == "reuse"] == list(units[:2]) + assert all(unit.original is None for unit in plan.units if unit.disposition == "new") + assert plan.original_units == units + assert plan.unit_manifest_sha256 == original_unit_manifest_sha256(units) + assert all( + len(text.encode()) <= chunks.MAX_BYTES + for unit, text in zip(plan.units, _texts(plan), strict=True) + if unit.disposition == "new" + ) + + +@pytest.mark.parametrize("incomplete", [0, 1, 2], ids=["start", "middle", "end"]) +def test_explicit_incomplete_unit_is_new_without_repaying_completed_neighbors(incomplete): + old, units = _history("First.\n", "Middle.\n", "Last.\n") + units = tuple( + replace(unit, reply_ref=None) if i == incomplete else unit for i, unit in enumerate(units) + ) + plan = _reconcile(old, old, units) + _assert_assembly(plan) + assert [unit.disposition for unit in plan.units] == [ + "new" if i == incomplete else "reuse" for i in range(3) + ] + assert [unit.original for unit in plan.units if unit.disposition == "reuse"] == [ + unit for unit in units if unit.reply_ref is not None + ] + + +def test_incomplete_gap_tracks_changed_english_outside_completed_cuts(): + old, units = _history("First.\n", "Unfinished one.\n", "Unfinished two.\n", "Last.\n") + units = ( + units[0], + replace(units[1], reply_ref=None), + replace(units[2], reply_ref=None), + units[3], + ) + current = _source("First.\n\nA changed gap.\n\nAnother new paragraph.\n\nLast.\n") + plan = _reconcile(old, current, units) + _assert_assembly(plan) + assert [unit.disposition for unit in plan.units] == ["reuse", "new", "reuse"] + assert plan.units[0].original == units[0] and plan.units[-1].original == units[-1] + # New work owns its full safe current gap; no historical completed cut is changed. + assert _texts(plan)[1] == "A changed gap.\n\nAnother new paragraph.\n\n" + assert plan.units[-1].separator_before == "" + + +def test_partial_plan_preserves_completed_deletion_and_incomplete_gaps(): + old, units = _history("Prefix.\n", "First.\n", "Removed.\n", "Last.\n", "Suffix.\n") + units = (replace(units[0], reply_ref=None), *units[1:4], replace(units[4], reply_ref=None)) + current = _source("Prefix.\n\nFirst.\n\nLast.\n\nSuffix.\n") + plan = _reconcile(old, current, units) + _assert_assembly(plan) + assert plan.removed == (units[2],) + assert [unit.disposition for unit in plan.units] == ["new", "reuse", "reuse", "new"] + + +def test_deleted_mixed_completed_and_incomplete_gap_creates_no_replacement(): + old, units = _history("First.\n", "Finished then removed.\n", "Unfinished.\n", "Last.\n") + units = (units[0], units[1], replace(units[2], reply_ref=None), units[3]) + plan = _reconcile(old, _source("First.\n\nLast.\n"), units) + _assert_assembly(plan) + assert plan.removed == units[1:3] + assert [unit.disposition for unit in plan.units] == ["reuse", "reuse"] + + +def test_missing_incomplete_manifest_range_is_still_an_authentication_failure(): + old, units = _history("First.\n", "Unfinished.\n", "Last.\n") + units = (units[0], replace(units[1], reply_ref=None), units[2]) + plan = _reconcile(old, old, (units[0], units[2])) + assert [conflict.kind for conflict in plan.conflicts] == ["authentication"] + + +def test_completed_reply_cannot_be_relabelled_incomplete_under_authenticated_manifest(): + old, units = _history("First.\n", "Bad settled reply.\n", "Last.\n") + digest = original_unit_manifest_sha256(units) + changed = (units[0], replace(units[1], reply_ref=None), units[2]) + plan = reconcile_completed_units(old, old, changed, unit_manifest_sha256=digest) + assert [conflict.kind for conflict in plan.conflicts] == ["authentication"] + correction = _reconcile(old, old, units, faults=(UnitFault("1", "semantic"),)) + _assert_assembly(correction) + assert correction.units[1].disposition == "correction" + + +def test_uncompleted_unit_cannot_be_a_settled_reply_fault_target(): + old, units = _history("First.\n", "Unfinished.\n", "Last.\n") + units = (units[0], replace(units[1], reply_ref=None), units[2]) + plan = _reconcile(old, old, units, faults=(UnitFault("1", "fault"),)) + assert [conflict.kind for conflict in plan.conflicts] == ["context"] + + +def test_partial_history_does_not_clear_repeated_completed_unit_ambiguity_or_refusal(): + old, units = _history("Repeated.\n", "Unfinished.\n", "Repeated.\n") + units = (units[0], replace(units[1], reply_ref=None), units[2]) + ambiguous = _reconcile(old, old, units) + assert [conflict.kind for conflict in ambiguous.conflicts] == ["ambiguity"] + refused = _reconcile(old, old, units, pair_refused=True) + assert [conflict.kind for conflict in refused.conflicts] == ["refusal"] + + +def test_never_completed_whole_page_can_receive_its_first_bounded_plan(): + old, units = _history("Not completed.\n") + units = (replace(units[0], reply_ref=None),) + plan = _reconcile(old, _source("Current English.\n"), units) + _assert_assembly(plan) + assert [unit.disposition for unit in plan.units] == ["new"] + + +def _results_original_cut_layout(): + # Exact original cut lengths and separator ownership; the prose itself is synthetic. + ends = [ + 7743, + 15093, + 22443, + 30553, + 38672, + 46676, + 54724, + 62801, + 70902, + 78853, + 87016, + 94631, + 102627, + 110343, + 111578, + ] + sizes = [ends[0], *(b - a for a, b in pairwise(ends))] + intro = "Intro " + "a" * (671 - len("Intro ") - 1) + "\n" + table = [] + for i, size in enumerate(sizes): + prefix = ("| Item | Value |\n| --- | --- |\n" if i == 0 else "") + f"| Row {i} | " + table.append(prefix + "a" * (size - len(prefix) - 3) + " |\n") + tail = [ + f"Tail {i} " + "a" * (size - len(f"Tail {i} ") - 1) + "\n" + for i, size in enumerate([2083, 1675, 942, 1045, 289]) + ] + parts = [intro, *table, *tail] + old, units = _history_with_separators(parts, ("\n", *("",) * 14, *("\n",) * 5)) + units = tuple(unit if i < 2 else replace(unit, reply_ref=None) for i, unit in enumerate(units)) + assert len(old.english) == 118289 + assert (units[1].start, units[1].end, units[2].start) == (672, 8415, 8415) + return old, units + + +@pytest.mark.parametrize("insert", [False, True], ids=["unchanged", "paragraph-insertion"]) +def test_actual_twenty_one_cut_layout_keeps_two_completed_payloads(insert): + old, units = _results_original_cut_layout() + current = ( + _source(old.english[:672] + "A new paragraph.\n\n" + old.english[672:]) if insert else old + ) + plan = _reconcile(old, current, units) + _assert_assembly(plan) + assert [unit.original for unit in plan.units if unit.disposition == "reuse"] == list(units[:2]) + assert all( + len(text.encode()) <= chunks.MAX_BYTES + for unit, text in zip(plan.units, _texts(plan), strict=True) + if unit.disposition == "new" + ) + + +def test_contiguous_completed_anchors_accept_no_assembly_separator(): + old, units = _history_with_separators(("First.\n\n", "Last.\n"), ("",)) + plan = _reconcile(old, old, units) + _assert_assembly(plan) + assert [unit.disposition for unit in plan.units] == ["reuse", "reuse"] + assert plan.units[1].separator_before == "" + + +def test_changed_contiguous_completed_counterpart_preserves_its_outer_newlines(): + old, units = _history_with_separators(("First.\n\n", "Old.\n\n", "Last.\n"), ("", "")) + current = _source("First.\n\nChanged.\n\nLast.\n") + plan = _reconcile(old, current, units, faults=(UnitFault("1", "fault"),)) + _assert_assembly(plan) + assert [unit.disposition for unit in plan.units] == ["reuse", "changed", "reuse"] + assert _texts(plan)[1] == "Changed.\n\n" + + +def test_contiguous_completed_deletion_preserves_neighbors(): + old, units = _history_with_separators(("First.\n\n", "Removed.\n\n", "Last.\n"), ("", "")) + plan = _reconcile(old, _source("First.\n\nLast.\n"), units) + _assert_assembly(plan) + assert plan.removed == (units[1],) + assert [unit.original for unit in plan.units] == [units[0], units[2]] + + +def test_incomplete_unsafe_old_cut_is_replanned_outside_completed_ranges(): + old, units = _history_with_separators(("First.\n\n", "New para", "graph.\n"), ("", "")) + units = (units[0], replace(units[1], reply_ref=None), replace(units[2], reply_ref=None)) + plan = _reconcile(old, old, units) + _assert_assembly(plan) + assert [unit.disposition for unit in plan.units] == ["reuse", "new"] + assert _texts(plan)[1] == "New paragraph.\n" + + +def test_contiguous_completed_cut_inside_a_paragraph_is_still_refused(): + old, units = _history_with_separators(("First para", "graph.\n"), ("",)) + plan = _reconcile(old, old, units) + assert [conflict.kind for conflict in plan.conflicts] == ["boundary"] + + +def test_headerless_gap_uses_full_current_table_rows_and_preserves_separator_lf(): + header = "| Item | Value |\n| --- | --- |\n" + rows = [f"| Row {i} | " + "a" * 1000 + " |\n" for i in range(25)] + english = header + "".join(rows) + start, end = len(header + rows[0]), len(english) - 1 + text = english[start:end] + scope = SourceContext("docs/table.md", english, start, end) + parts = chunks.split(text, source_context=scope) + assert len(parts) >= 2 + assert "\n".join(parts) == text + assert all(len(part.encode()) <= chunks.MAX_BYTES for part in parts) + assert all(part.startswith("| Row ") for part in parts) + + +@pytest.mark.parametrize("invalid", ["foreign", "negative", "past_end", "cell", "fence"]) +def test_contextual_split_refuses_foreign_or_unsafe_ranges_before_shortcut(invalid): + english = "| Field | Meaning |\n| --- | --- |\n| A | inside a cell |\n" + start, end = 0, len(english) + if invalid == "foreign": + text = "A different input." + else: + if invalid == "negative": + start = -1 + elif invalid == "past_end": + end += 1 + elif invalid == "cell": + end = english.index("inside") + 3 + else: + english = "```text\ninside code\n```\n" + end = english.index("code") + len("code\n") + text = english[start:end] + scope = SourceContext("docs/table.md", english, start, end) + with pytest.raises(ValueError, match="source context|parser-safe"): + chunks.split(text, source_context=scope) + + +@pytest.mark.parametrize("insert", [False, True], ids=["unchanged", "insertion"]) +def test_request_bound_preserves_completed_table_payloads_and_default_plan(insert): + old, units = _results_original_cut_layout() + current = ( + _source(old.english[:672] + "Inserted paragraph.\n\n" + old.english[672:]) + if insert + else old + ) + default = _reconcile(old, current, units) + assert _reconcile(old, current, units, bounded_new_request_bytes=chunks.MAX_BYTES) == default + smaller = _reconcile(old, current, units, bounded_new_request_bytes=8192) + _assert_assembly(smaller) + assert smaller.original_units == units + assert smaller.unit_manifest_sha256 == default.unit_manifest_sha256 + assert [u.original for u in smaller.units if u.disposition == "reuse"] == list(units[:2]) + assert all( + u.scope.path == current.path and u.scope.english == current.english for u in smaller.units + ) + assert any( + len(text.encode()) > 8192 + for u, text in zip(default.units, _texts(default), strict=True) + if u.disposition == "new" + ) + assert all( + len(text.encode()) <= 8192 + for u, text in zip(smaller.units, _texts(smaller), strict=True) + if u.disposition != "reuse" + ) + + +def test_request_bound_counts_utf8_and_preserves_default_split(): + text = ("Paragraph " + "界" * 1800 + "\n\n") * 4 + assert len(text) < 8192 < len(text.encode()) + assert chunks.split(text, bounded_new_request_bytes=chunks.MAX_BYTES) == chunks.split(text) + parts = chunks.split(text, bounded_new_request_bytes=8192) + assert len(parts) > 1 + assert "\n".join(parts) == text + assert all(len(part.encode()) <= 8192 for part in parts) + + +def test_request_bound_keeps_headerless_rows_in_their_current_container(): + header = "| Item | Value |\n| --- | --- |\n" + rows = [f"| Row {i} | " + "a" * 1000 + " |\n" for i in range(12)] + english = header + "".join(rows) + start, end = len(header + rows[0]), len(english) - 1 + text = english[start:end] + scope = SourceContext("docs/table.md", english, start, end) + assert chunks.split(text, source_context=scope) == [text] + parts = chunks.split(text, source_context=scope, bounded_new_request_bytes=8192) + assert len(parts) > 1 + assert "\n".join(parts) == text + assert all(part.startswith("| Row ") and len(part.encode()) <= 8192 for part in parts) + + +def test_request_bound_refuses_an_indivisible_unit_that_fits_the_default(): + text = "An indivisible paragraph " + "a" * 9000 + assert chunks.split(text) == [text] + with pytest.raises(ValueError, match="8192-byte"): + chunks.split(text, bounded_new_request_bytes=8192) + + +@pytest.mark.parametrize("bound", [1, 8192]) +def test_request_bound_never_reslices_a_large_free_completed_page(bound): + old, units = _history("An indivisible paragraph " + "界" * 6000) + plan = _reconcile(old, old, units, bounded_new_request_bytes=bound) + _assert_assembly(plan) + assert len(plan.units) == 1 + assert plan.units[0].disposition == "reuse" and plan.units[0].original == units[0] + assert _texts(plan) == [old.english] + + +@pytest.mark.parametrize("disposition", ["changed", "correction"]) +@pytest.mark.parametrize("bound", [8192, 10240], ids=["conflict", "whole-request"]) +def test_request_bound_keeps_completed_repairs_whole_or_conflicts(disposition, bound): + old, units = _history("First.\n", "Old " + "a" * 9000 + "\n", "Last.\n") + current = _source(old.english.replace("Old ", "New ")) if disposition == "changed" else old + faults = (UnitFault("1", "semantic"), UnitFault("1", "language")) + plan = _reconcile(old, current, units, faults=faults, bounded_new_request_bytes=bound) + if bound == 8192: + assert [c.kind for c in plan.conflicts] == ["boundary"] + assert not plan.units + else: + _assert_assembly(plan) + assert [u.disposition for u in plan.units] == ["reuse", disposition, "reuse"] + assert plan.units[1].original == units[1] + assert plan.units[1].fault_ids == ("language", "semantic") + assert _texts(plan)[1] == current.english[units[1].start : units[1].end] + + +@pytest.mark.parametrize("bound", [True, 0, -1, 1.5, "8192", chunks.MAX_BYTES + 1]) +@pytest.mark.parametrize("text", ["", "A short paragraph.\n"], ids=["empty", "short"]) +def test_invalid_request_bound_is_rejected_before_split_shortcuts(bound, text): + with pytest.raises(ValueError, match="byte bound"): + chunks.split(text, bounded_new_request_bytes=bound) + + +@pytest.mark.parametrize("bound", [True, 0, -1, 1.5, "8192", chunks.MAX_BYTES + 1]) +@pytest.mark.parametrize("empty", [False, True], ids=["all-reuse", "empty"]) +def test_invalid_request_bound_is_rejected_before_reconciliation_shortcuts(bound, empty): + old, units = (_source(""), ()) if empty else _history("A completed paragraph.\n") + with pytest.raises(ValueError, match="byte bound"): + _reconcile(old, old, units, bounded_new_request_bytes=bound) + + +def test_request_bound_allows_a_one_byte_new_request(): + old, units = _history("x") + units = (replace(units[0], reply_ref=None),) + plan = _reconcile(old, old, units, bounded_new_request_bytes=1) + _assert_assembly(plan) + assert _texts(plan) == ["x"] + assert [u.disposition for u in plan.units] == ["new"] diff --git a/tests/unit/test_i18n_refresh.py b/tests/unit/test_i18n_refresh.py new file mode 100644 index 0000000000..d2fa52a1bd --- /dev/null +++ b/tests/unit/test_i18n_refresh.py @@ -0,0 +1,353 @@ +"""Explicit refresh jobs advance through private repositories without provider calls.""" + +from __future__ import annotations + +import json +import pathlib + +import pytest + +from scripts.i18n import lifecycle as lc +from scripts.i18n import refresh as r +from scripts.i18n import translate as t +from tests.unit.test_i18n_lifecycle import JA, git, publish, put, translated + + +@pytest.fixture +def repo(tmp_path: pathlib.Path, monkeypatch: pytest.MonkeyPatch) -> pathlib.Path: + git(tmp_path, "init", "-q", "-b", "main") + git(tmp_path, "config", "user.name", "test") + git(tmp_path, "config", "user.email", "test@example.test") + monkeypatch.setattr(t, "ROOT", tmp_path) + monkeypatch.setenv("LOOM_I18N_MODEL", t.DEFAULT_MODEL) + monkeypatch.setenv("LOOM_I18N_MAX_USD", "1") + monkeypatch.setattr(t, "estimate_usd", lambda model, chars: 1.0) + monkeypatch.setattr(t, "bedrock_client", lambda: None) + for source in ("docs/a.md", "docs/b.md", "docs/c.md"): + put(tmp_path, source, "# Alpha\n") + git(tmp_path, "add", ".") + git(tmp_path, "commit", "-qm", "English") + for source in t.sources(): + publish(tmp_path, source) + git(tmp_path, "add", ".") + git(tmp_path, "commit", "-qm", "Current translations") + return tmp_path + + +def translator(calls: list[str]): + def fake(source: str, lang: t.Language, client: object, spend: t.Spend) -> None: + calls.append(source) + lc.stage(t.target_path(lang.code, source), translated(source) + "\nTexto renovado.\n") + + return fake + + +def test_force_refresh_continues_in_default_batches_without_repeating_fresh_pages( + repo: pathlib.Path, + monkeypatch: pytest.MonkeyPatch, +) -> None: + calls: list[str] = [] + monkeypatch.setattr(t, "translate_page", translator(calls)) + assert t.stale((JA,)) == [] + t.update(every=True, codes=["ja"]) + t.update(codes=["ja"]) + t.update(codes=["ja"]) + assert calls == list(t.sources()) + assert r.read()["complete"] + t.update(codes=["ja"]) + assert calls == list(t.sources()) + # Materialized pending data is insufficient proof that main contains the receipt. + assert (repo / r.PATH).exists() + git(repo, "add", ".") + git(repo, "commit", "-qm", "Verified refresh") + monkeypatch.setenv("LOOM_I18N_MAX_USD", "0") + t.update(codes=["ja"]) + assert not (repo / r.PATH).exists() + + +def test_unmerged_refresh_receipt_authorizes_only_verified_same_source_replacements( + repo: pathlib.Path, + monkeypatch: pytest.MonkeyPatch, +) -> None: + calls: list[str] = [] + monkeypatch.setattr(t, "translate_page", translator(calls)) + git(repo, "switch", "-qc", "i18n/update") + t.update(every=True, codes=["ja"]) + git(repo, "add", ".") + git(repo, "commit", "-qm", "Partial refresh") + sha = git(repo, "rev-parse", "HEAD") + git(repo, "switch", "-q", "main") + assert "Texto renovado" not in (repo / "i18n/ja/docs/a.md").read_text() + assert t.import_pending(sha) == 1 + assert "Texto renovado" in (repo / "i18n/ja/docs/a.md").read_text() + assert "Texto renovado" not in (repo / "i18n/ja/docs/b.md").read_text() + t.update(codes=["ja"]) + t.update(codes=["ja"]) + assert calls == list(t.sources()) + + +def test_failure_retains_verified_progress_and_remaining_refresh_work( + repo: pathlib.Path, + monkeypatch: pytest.MonkeyPatch, +) -> None: + calls: list[str] = [] + success = translator(calls) + monkeypatch.setenv("LOOM_I18N_MAX_USD", "3") + + def failing(source: str, lang: t.Language, client: object, spend: t.Spend) -> None: + if source == "docs/b.md": + raise SystemExit("uncertain provider request") + success(source, lang, client, spend) + + monkeypatch.setattr(t, "translate_page", failing) + with pytest.raises(SystemExit, match="uncertain"): + t.update(every=True, codes=["ja"]) + assert set(r.read()["completed"]) == {"i18n/ja/docs/a.md"} + monkeypatch.setattr(t, "translate_page", success) + t.update(codes=["ja"]) + assert calls == list(t.sources()) + + +def test_reservation_planning_is_pure_and_zero_allowance_records_only_the_job( + repo: pathlib.Path, + monkeypatch: pytest.MonkeyPatch, +) -> None: + assert t.batch_reservation(True, ["ja"], cap=1) > 0 + assert not (repo / r.PATH).exists() + monkeypatch.setenv("LOOM_I18N_MAX_USD", "0") + monkeypatch.setattr( + t, "bedrock_client", lambda: pytest.fail("zero allowance requested provider") + ) + t.update(every=True, codes=["ja"]) + assert r.read()["completed"] == {} + assert len(r.work(r.plan())) == 3 + + +def test_prompt_change_invalidates_completion_and_does_not_activate_old_checkpoints( + repo: pathlib.Path, + monkeypatch: pytest.MonkeyPatch, +) -> None: + calls: list[str] = [] + monkeypatch.setattr(t, "translate_page", translator(calls)) + t.update(every=True, codes=["ja"]) + old = translated("docs/b.md") + lc.stage("i18n/ja/docs/b.md", old) + monkeypatch.setattr(t, "SYSTEM", t.SYSTEM + "\nUse concise prose.") + assert r.plan()["completed"] == {} + assert "i18n/ja/docs/b.md" not in lc.current_checkpoints() + t.update(codes=["ja"]) + assert calls == ["docs/a.md", "docs/a.md"] + + +@pytest.mark.parametrize("change", ["owner", "schema", "language", "mapping", "hash"]) +def test_malformed_refresh_metadata_is_never_overwritten_or_deleted( + repo: pathlib.Path, + monkeypatch: pytest.MonkeyPatch, + change: str, +) -> None: + data = r.plan(True, ["ja"]) + if change == "owner": + data["owner"] = "personal notes" + elif change == "schema": + data["schema"] = 2 + elif change == "language": + data["languages"] = ["unknown"] + else: + path = "i18n/ja/../../private.md" if change == "mapping" else "i18n/ja/docs/a.md" + data["completed"][path] = {"blob": "0" * 40, "sha256": "invalid", "base": ""} + original = json.dumps(data) + put(repo, r.PATH, original) + monkeypatch.setenv("LOOM_I18N_MAX_USD", "0") + with pytest.raises(SystemExit, match="ownership"): + t.update() + assert (repo / r.PATH).read_text() == original + + +def test_unknown_json_remains_unowned_output(repo: pathlib.Path) -> None: + put(repo, "i18n/.pending/personal.json", "{}") + with pytest.raises(SystemExit, match="ownership"): + lc.require_owned_outputs() + assert (repo / "i18n/.pending/personal.json").read_text() == "{}" + + +def test_selected_batch_does_not_spend_on_other_active_refresh_languages( + repo: pathlib.Path, + monkeypatch: pytest.MonkeyPatch, +) -> None: + r.save(r.plan(True, ["ja", "es"])) + calls: list[str] = [] + monkeypatch.setattr(t, "translate_page", translator(calls)) + t.update(codes=["ja"]) + assert calls == ["docs/a.md"] + assert {lg.code for _, lg in r.work(r.plan())} == {"ja", "es"} + assert t.batch(False, [], 100) == ([], 0) + + +def test_import_with_empty_approval_preserves_new_coverage_as_hidden_data( + repo: pathlib.Path, +) -> None: + (repo / "i18n/ja/docs/a.md").unlink() + git(repo, "add", ".") + git(repo, "commit", "-qm", "Pending coverage") + git(repo, "switch", "-qc", "i18n/update") + publish(repo, "docs/a.md") + git(repo, "add", ".") + git(repo, "commit", "-qm", "Verified output") + sha = git(repo, "rev-parse", "HEAD") + git(repo, "switch", "-q", "main") + assert t.import_pending(sha, []) == 1 + assert not (repo / "i18n/ja/docs/a.md").exists() + assert (repo / "i18n/.pending/ja/docs/a.md").exists() + assert lc.activate_ready(["es"]) == 0 + assert lc.activate_ready(["ja"]) == 1 + + +def test_incomplete_receipt_cannot_claim_completion_and_disappear(repo: pathlib.Path) -> None: + data = r.plan(True, ["ja"]) + data["complete"] = True + r.save(data) + r.clear_merged() + assert (repo / r.PATH).exists() + lc.activate_ready([]) + assert r.read()["complete"] is False + + +def test_completed_unmerged_receipt_keeps_force_authority_until_main_incorporates_it( + repo: pathlib.Path, + monkeypatch: pytest.MonkeyPatch, +) -> None: + calls: list[str] = [] + monkeypatch.setattr(t, "translate_page", translator(calls)) + monkeypatch.setenv("LOOM_I18N_MAX_USD", "3") + git(repo, "switch", "-qc", "i18n/update") + t.update(every=True, codes=["ja"]) + assert r.read()["complete"] + git(repo, "add", ".") + git(repo, "commit", "-qm", "Completed refresh") + sha = git(repo, "rev-parse", "HEAD") + git(repo, "switch", "-q", "main") + assert t.import_pending(sha) == 3 + assert r.read()["complete"] + t.update(codes=["ja"]) + assert calls == list(t.sources()) + assert (repo / r.PATH).exists() + + +def test_forged_hash_receipt_is_rejected_before_replacing_current_main( + repo: pathlib.Path, + monkeypatch: pytest.MonkeyPatch, +) -> None: + calls: list[str] = [] + monkeypatch.setattr(t, "translate_page", translator(calls)) + git(repo, "switch", "-qc", "i18n/update") + t.update(every=True, codes=["ja"]) + data = r.read() + data["completed"]["i18n/ja/docs/a.md"]["sha256"] = "0" * 64 + r.save(data) + git(repo, "add", ".") + git(repo, "commit", "-qm", "Invalid receipt") + sha = git(repo, "rev-parse", "HEAD") + git(repo, "switch", "-q", "main") + before = (repo / "i18n/ja/docs/a.md").read_text() + with pytest.raises(ValueError, match="matching verified output"): + t.import_pending(sha) + assert (repo / "i18n/ja/docs/a.md").read_text() == before + assert not (repo / r.PATH).exists() + + +def test_import_preserves_independent_main_refresh_and_defers_conflicting_checkpoint( + repo: pathlib.Path, + monkeypatch: pytest.MonkeyPatch, + capsys: pytest.CaptureFixture[str], +) -> None: + calls: list[str] = [] + monkeypatch.setattr(t, "translate_page", translator(calls)) + git(repo, "switch", "-qc", "i18n/update") + t.update(every=True, codes=["ja"]) + candidate = (repo / "i18n/ja/docs/a.md").read_text() + git(repo, "add", ".") + git(repo, "commit", "-qm", "Candidate refresh") + sha = git(repo, "rev-parse", "HEAD") + git(repo, "switch", "-q", "main") + independent = translated("docs/a.md") + "\nTexto independiente.\n" + put(repo, "i18n/ja/docs/a.md", independent) + git(repo, "add", ".") + git(repo, "commit", "-qm", "Independent verified refresh") + assert t.import_pending(sha) == 1 + assert (repo / "i18n/ja/docs/a.md").read_text() == independent + assert (repo / "i18n/.pending/ja/docs/a.md").read_text() == candidate + assert "i18n/ja/docs/a.md" not in lc.current_checkpoints() + assert not r.done("i18n/ja/docs/a.md", r.plan()) + assert t.check() == 1 + assert "i18n/ja/docs/a.md is missing or stale" in capsys.readouterr().out + monkeypatch.setenv("LOOM_I18N_MAX_USD", "0") + monkeypatch.setattr(t, "bedrock_client", lambda: pytest.fail("conflict must not be repaid")) + t.update(codes=["ja"]) + assert "translated=0 failed=0 deferred=3" in capsys.readouterr().out + assert (repo / "i18n/ja/docs/a.md").read_text() == independent + assert (repo / "i18n/.pending/ja/docs/a.md").read_text() == candidate + + +def test_delayed_checkpoint_activation_checks_its_original_published_base( + repo: pathlib.Path, + monkeypatch: pytest.MonkeyPatch, +) -> None: + calls: list[str] = [] + monkeypatch.setattr(t, "translate_page", translator(calls)) + activate = lc.activate_ready + monkeypatch.setattr(lc, "activate_ready", lambda codes=None: 0) + t.update(every=True, codes=["ja"]) + candidate = (repo / "i18n/.pending/ja/docs/a.md").read_text() + independent = translated("docs/a.md") + "\nTexto independiente.\n" + put(repo, "i18n/ja/docs/a.md", independent) + # Removing the delay must not permit a candidate to replace independently changed output. + monkeypatch.setattr(lc, "activate_ready", activate) + assert lc.activate_ready(["ja"]) == 0 + assert (repo / "i18n/ja/docs/a.md").read_text() == independent + assert (repo / "i18n/.pending/ja/docs/a.md").read_text() == candidate + + +def test_merged_receipt_projection_matches_reservation_and_mutation_after_source_edit( + repo: pathlib.Path, + monkeypatch: pytest.MonkeyPatch, +) -> None: + calls: list[str] = [] + monkeypatch.setattr(t, "translate_page", translator(calls)) + monkeypatch.setenv("LOOM_I18N_MAX_USD", "3") + t.update(every=True, codes=["ja"]) + git(repo, "add", ".") + git(repo, "commit", "-qm", "Verified completed refresh") + put(repo, "docs/a.md", "# Alpha\n\nTexto adicional.\n") + before = (repo / r.PATH).read_text() + reserved, deferred = t.batch(True, ["ja"], 3) + assert [source for source, _ in reserved] == list(t.sources()) and deferred == 0 + assert (repo / r.PATH).read_text() == before + assert t.batch_reservation(True, ["ja"], cap=3) > 0 + calls.clear() + t.update(every=True, codes=["ja"]) + assert calls == [source for source, _ in reserved] + + +def test_generated_refresh_tree_satisfies_repository_ownership_contract( + repo: pathlib.Path, monkeypatch: pytest.MonkeyPatch +) -> None: + from tests.unit.test_i18n import test_every_output_has_generator_ownership as contract + + monkeypatch.setattr(t, "translate_page", translator([])) + t.update(every=True, codes=["ja"]) + assert (repo / r.PATH).exists() + contract() + put(repo, "i18n/.pending/personal.json", "{}") + with pytest.raises(AssertionError): + contract() + + +def test_invalid_model_refuses_before_mutating_existing_refresh_receipt( + repo: pathlib.Path, monkeypatch: pytest.MonkeyPatch +) -> None: + r.save(r.plan(True, ["ja"])) + before = (repo / r.PATH).read_text() + monkeypatch.setenv("LOOM_I18N_MODEL", "unpriced-model") + with pytest.raises(SystemExit, match="no price"): + t.update(codes=["ja"]) + assert (repo / r.PATH).read_text() == before diff --git a/tests/unit/test_i18n_request_bounds.py b/tests/unit/test_i18n_request_bounds.py new file mode 100644 index 0000000000..8311a2f27f --- /dev/null +++ b/tests/unit/test_i18n_request_bounds.py @@ -0,0 +1,385 @@ +"""Translation requests bound source bytes without breaking Markdown units.""" + +from collections import Counter +from dataclasses import replace +from types import SimpleNamespace + +import pytest + +from scripts.i18n import chunks +from scripts.i18n import translate as t +from scripts.i18n.context import Label + +MAXIMUM = 16_384 + + +def assert_bounded(text: str) -> list[str]: + requests = t.english_requests(text) + assert "\n".join(requests) == t.anchor_headings(text, Counter()) + assert all(len(part.encode()) <= MAXIMUM for part in requests) + return requests + + +def test_one_large_section_splits_at_complete_table_rows() -> None: + header = "| Loom | Loom |\n| --- | --- |\n" + text = "# Loom\n\n## Loom\n\n" + header + text += "".join(f"| Loom {i} | `Loom` |\n" for i in range(1800)) + requests = assert_bounded(text) + assert len(requests) > 2 + assert any(header in part for part in requests) + assert all(not part.startswith("| --- |") for part in requests) + + +def test_a_short_multibyte_page_still_obeys_the_byte_bound() -> None: + text = "# Loom\n\n" + ("메모리" * 400 + "\n\n") * 6 + assert len(text) < t.WHOLE_PAGE_CHARS + assert len(assert_bounded(text)) > 1 + + +def test_slices_keep_code_html_and_anchor_heading_pairs_together() -> None: + fence = "```python\nvalue = 12\n\n# Loom\n```" + inline = "`one\n\ntwo`" + html = '
Loom\n\nLoom\n
' + comment = "" + blocks = [fence, inline, html, comment, "## Next"] + text = "# Loom\n\n" + "\n\n".join(("Loom " * 900 + "\n\n" + block) for block in blocks) + requests = assert_bounded(text) + assert len(requests) > 1 + for block in blocks[:-1]: + assert any(block in part for part in requests) + assert any('\n\n## Next' in part for part in requests) + + +@pytest.mark.parametrize( + "code", + [ + "
\n content\n", + "
\n content\n", + " ```python\n
\n", + "- ```python\n
\n ```\n", + ], + ids=["opening-tag", "closing-tag", "literal-fence", "nested-fence"], +) +def test_html_literals_inside_code_remain_one_request(code): + requests = assert_bounded("Loom\n\n" * 3000 + code) + assert any(code.rstrip("\n") in request for request in requests) + + +@pytest.mark.parametrize("marker", ["-", "1."]) +def test_multiline_list_continuation_never_becomes_a_separate_request(marker) -> None: + item = marker + " Loom " + "x" * 4000 + "\n\n continued " + "y" * 4000 + "\n" + text = "# Loom\n\n" + "Loom\n\n" * 1800 + item + "\n- next\n" + requests = assert_bounded(text) + assert any(item.rstrip("\n") in part for part in requests) + + +def test_html_crossing_a_heading_stays_in_one_request() -> None: + html = "
\n\n## Loom\n\nLoom\n
\n" + text = "# Loom\n\n" + "Loom\n\n" * 3000 + html + requests = assert_bounded(text) + assert any(t.anchor_headings(html, Counter({"loom": 1})) in part for part in requests) + + +def test_table_without_outer_pipes_splits_between_complete_rows() -> None: + header = "Loom | Loom\n--- | ---\n" + text = header + "Loom | Loom\n" * 2000 + requests = assert_bounded(text) + assert len(requests) > 1 + assert requests[0].startswith(header) + + +def test_single_column_table_keeps_header_with_delimiter_at_byte_boundary() -> None: + header = "| " + "x" * 176 + " |\n| --- |\n" + text = "Loom\n\n" * 2700 + header + requests = assert_bounded(text) + assert any(header in part for part in requests) + assert all(not part.startswith("| --- |") for part in requests) + + +@pytest.mark.parametrize( + "unit", + [ + "```\n" + "x" * MAXIMUM + "\n```\n", + "
\n" + "x" * MAXIMUM + "\n
\n", + "- Loom " + "x" * 9000 + "\n\n continued " + "y" * 9000 + "\n", + "- " + "x" * 9000 + "\n\n\t" + "y" * 9000 + "\n", + "1. Loom " + "x" * 9000 + "\n\n continued " + "y" * 9000 + "\n", + "> 1. Loom " + "x" * 9000 + "\n>\n> continued " + "y" * 9000 + "\n", + "!!! note\n\n 1. Loom " + "x" * 9000 + "\n\n continued " + "y" * 9000 + "\n", + ], + ids=["fence", "html", "list", "tab-list", "site-ordered", "quote-ordered", "note-ordered"], +) +def test_indivisible_oversize_input_stops_before_any_provider_call(monkeypatch, unit) -> None: + calls = [] + + def unexpected_call(*args): + calls.append(args) + raise AssertionError("indivisible oversized input reached the provider") + + monkeypatch.setattr(t, "prepare", lambda source, lang: (unit, "")) + monkeypatch.setattr(t, "call", unexpected_call) + with pytest.raises(t.TranslationDiffers, match="indivisible"): + t.translate_page("docs/example.md", t.LANGUAGES[0], None, t.Spend(t.DEFAULT_MODEL, 1)) + assert calls == [] + + +def test_request_estimate_and_calls_use_the_same_slices_and_usage(monkeypatch) -> None: + text = "# Loom\n\n" + "Loom\n\n" * 6000 + calls = [] + + def reply(client, model, system, messages): + source = messages[0]["content"] + assert len(source.encode()) <= MAXIMUM + calls.append(source) + return { + "stop_reason": "end_turn", + "content": [{"type": "text", "text": source}], + "usage": {"input_tokens": 7, "output_tokens": 11}, + } + + monkeypatch.setattr(t, "call", reply) + monkeypatch.setattr(t, "prepare", lambda source, lang: (text, "")) + lang = t.LANGUAGES[0] + spend = t.Spend(t.DEFAULT_MODEL, 1) + requests = assert_bounded(text) + result = "\n".join(t.translate_text(part, lang, None, spend) for part in requests) + assert result == "\n".join(requests) + assert calls == requests + assert spend.input_tokens == 7 * len(requests) + assert spend.output_tokens == 11 * len(requests) + system = t.SYSTEM.format(language=lang.english, style=lang.style) + assert t.request_chars("docs/example.md", lang) == sum(len(p) + len(system) for p in calls) + + +def test_assembled_table_layout_is_verified_before_writing(monkeypatch, tmp_path) -> None: + source = "# Loom\n\n| Loom | Loom |\n| --- | --- |\n| Loom | Loom |\n" + monkeypatch.setattr(t, "ROOT", tmp_path) + monkeypatch.setattr(t, "prepare", lambda path, lang: (source, "")) + monkeypatch.setattr(t, "blob", lambda path: "0" * 40) + monkeypatch.setattr( + t, "translate_text", lambda part, *args, **_kwargs: part + "| Loom | Loom | Loom |\n" + ) + with pytest.raises(t.TranslationDiffers, match="table"): + t.translate_page("docs/example.md", t.LANGUAGES[0], None, t.Spend(t.DEFAULT_MODEL, 1)) + assert not (tmp_path / "i18n").exists() + + +def test_assembled_table_without_outer_pipes_rejects_row_loss(monkeypatch, tmp_path) -> None: + source = "Loom | Loom\n--- | ---\nLoom | Loom\n" + monkeypatch.setattr(t, "ROOT", tmp_path) + monkeypatch.setattr(t, "prepare", lambda path, lang: (source, "")) + monkeypatch.setattr(t, "blob", lambda path: "0" * 40) + monkeypatch.setattr(t, "translate_text", lambda *args, **_kwargs: "Loom | Loom\n--- | ---\n") + with pytest.raises(t.TranslationDiffers, match="table"): + t.translate_page("docs/example.md", t.LANGUAGES[0], None, t.Spend(t.DEFAULT_MODEL, 1)) + assert not (tmp_path / "i18n").exists() + + +@pytest.mark.parametrize("delimiter", ["| Loom | Loom |\n", "| --- | --- |\n\n"]) +def test_assembled_table_preserves_delimiter_and_membership(monkeypatch, tmp_path, delimiter): + source = "| Loom | Loom |\n| --- | --- |\n| Loom | Loom |\n" + reply = "| Loom | Loom |\n" + delimiter + "| Loom | Loom |\n" + monkeypatch.setattr(t, "ROOT", tmp_path) + monkeypatch.setattr(t, "prepare", lambda path, lang: (source, "")) + monkeypatch.setattr(t, "blob", lambda path: "0" * 40) + monkeypatch.setattr(t, "translate_text", lambda *args, **_kwargs: reply) + with pytest.raises(t.TranslationDiffers, match="table"): + t.translate_page("docs/example.md", t.LANGUAGES[0], None, t.Spend(t.DEFAULT_MODEL, 1)) + assert not (tmp_path / "i18n").exists() + + +@pytest.mark.parametrize("context", ["quote", "list", "indented-code"]) +def test_assembled_table_cannot_become_another_block(monkeypatch, tmp_path, context): + header = "Loom | Loom\n--- | ---\n" + source = header + "Loom | Loom\n" + if context == "indented-code": + reply = "".join(" " + line for line in source.splitlines(keepends=True)) + else: + reply = header + ("> " if context == "quote" else "- ") + "Loom | Loom\n" + monkeypatch.setattr(t, "ROOT", tmp_path) + monkeypatch.setattr(t, "prepare", lambda path, lang: (source, "")) + monkeypatch.setattr(t, "blob", lambda path: "0" * 40) + monkeypatch.setattr(t, "translate_text", lambda *args, **_kwargs: reply) + with pytest.raises(t.TranslationDiffers, match="table"): + t.translate_page("docs/example.md", t.LANGUAGES[0], None, t.Spend(t.DEFAULT_MODEL, 1)) + assert not (tmp_path / "i18n").exists() + + +@pytest.mark.parametrize("context", ["quote-row-loss", "raw-pre"]) +def test_assembled_tables_preserve_nested_and_raw_html_context(monkeypatch, tmp_path, context): + table = "| Loom | Loom |\n| --- | --- |\n| Loom | Loom |\n" + if context == "quote-row-loss": + source = "".join("> " + line for line in table.splitlines(keepends=True)) + reply = "> | Loom | Loom |\n> | --- | --- |\n" + else: + source, reply = table, "
\n" + table + "
\n" + monkeypatch.setattr(t, "ROOT", tmp_path) + monkeypatch.setattr(t, "prepare", lambda path, lang: (source, "")) + monkeypatch.setattr(t, "blob", lambda path: "0" * 40) + monkeypatch.setattr(t, "translate_text", lambda *args, **_kwargs: reply) + with pytest.raises(t.TranslationDiffers, match="table"): + t.translate_page("docs/example.md", t.LANGUAGES[0], None, t.Spend(t.DEFAULT_MODEL, 1)) + assert not (tmp_path / "i18n").exists() + + +@pytest.mark.parametrize("container", ["list", "admonition"]) +def test_assembled_tables_inside_site_containers_reject_row_loss(monkeypatch, tmp_path, container): + table = "| Loom | Loom |\n| --- | --- |\n| Loom | Loom |\n" + prefix, indent = ("- Loom\n\n", " ") if container == "list" else ("!!! note\n\n", " ") + source = prefix + "".join(indent + line for line in table.splitlines(keepends=True)) + reply = "\n".join(source.splitlines()[:-1]) + "\n" + monkeypatch.setattr(t, "ROOT", tmp_path) + monkeypatch.setattr(t, "prepare", lambda path, lang: (source, "")) + monkeypatch.setattr(t, "blob", lambda path: "0" * 40) + monkeypatch.setattr(t, "translate_text", lambda *args, **_kwargs: reply) + with pytest.raises(t.TranslationDiffers, match="table"): + t.translate_page("docs/example.md", t.LANGUAGES[0], None, t.Spend(t.DEFAULT_MODEL, 1)) + assert not (tmp_path / "i18n").exists() + + +@pytest.mark.parametrize("cell", ["header", "body"]) +@pytest.mark.parametrize("markup", [False, True]) +@pytest.mark.parametrize("container", ["commonmark-list", "admonition"]) +def test_assembled_tables_reject_emptying_a_cell(monkeypatch, tmp_path, cell, markup, container): + value, empty = ("Loom", "") if markup else ("Loom", "") + prefix, indent = ( + ("1. Loom\n\n", " ") if container == "commonmark-list" else ("!!! note\n\n", " ") + ) + row = f"{indent}| Loom | {value} |\n" + source = prefix + row + indent + "| --- | --- |\n" + row + lines = source.splitlines(keepends=True) + index = 2 if cell == "header" else 4 + lines[index] = lines[index].replace(f"| {value} |\n", f"| {empty} |\n") + monkeypatch.setattr(t, "ROOT", tmp_path) + monkeypatch.setattr(t, "prepare", lambda path, lang: (source, "")) + monkeypatch.setattr(t, "blob", lambda path: "0" * 40) + monkeypatch.setattr(t, "translate_text", lambda *args, **_kwargs: "".join(lines)) + with pytest.raises(t.TranslationDiffers, match="table"): + t.translate_page("docs/example.md", t.LANGUAGES[0], None, t.Spend(t.DEFAULT_MODEL, 1)) + assert not (tmp_path / "i18n").exists() + + +@pytest.mark.parametrize("container", ["plain", "quote", "list", "admonition", "commonmark-list"]) +@pytest.mark.parametrize("markup", [False, True]) +def test_valid_table_reflow_is_written_in_each_supported_container( + monkeypatch, tmp_path, container, markup +): + value = "Memory" if markup else "Memory" + translated = value.replace("Memory", "记忆") + row = f"| {value} | {value} |\n" + table = row + "| --- | --- |\n" + row + prefix, indent = { + "plain": ("", ""), + "quote": ("", "> "), + "list": ("- Loom\n\n", " "), + "admonition": ("!!! note\n\n", " "), + "commonmark-list": ("1. Loom\n\n", " "), + }[container] + source = prefix + "".join(indent + line for line in table.splitlines(keepends=True)) + source_file = tmp_path / "docs/example.md" + source_file.parent.mkdir(parents=True) + source_file.write_text(source) + monkeypatch.setattr(t, "ROOT", tmp_path) + monkeypatch.setattr(t, "sources", lambda: ("docs/example.md",)) + monkeypatch.setattr(t, "prepare", lambda path, lang: (source, "")) + monkeypatch.setattr(t, "blob", lambda path: "0" * 40) + monkeypatch.setattr( + t, + "translate_text", + lambda part, *args, **_kwargs: part.replace( + f"| {value} | {value} |", f"{translated} | {translated}" + ).replace("| --- | --- |", "--- | ---"), + ) + t.translate_page("docs/example.md", t.LANGUAGES[0], None, t.Spend(t.DEFAULT_MODEL, 1)) + assert ( + f"{translated} | {translated}" + in ( + tmp_path + / t.lifecycle.checkpoint_path(t.target_path(t.LANGUAGES[0].code, "docs/example.md")) + ).read_text() + ) + assert not (tmp_path / t.target_path(t.LANGUAGES[0].code, "docs/example.md")).exists() + + +@pytest.mark.parametrize( + ("text", "protected", "expected"), + [ + ( + "- one\n continued\n\noutside\n- two\n", + [(10, 11), (7, 27), (0, 0), (23, 22)], + [(0, 27), (27, 33)], + ), + ( + "- one\n continued\n\n> outside\n- two\n", + [(19, 19), (10, 11), (7, 29)], + [(0, 19), (29, 35)], + ), + ( + "- one\n\noutside\n- two\n", + [(7, 15)], + [(0, 7), (15, 21)], + ), + ], +) +def test_site_list_boundaries_keep_overlaps_and_exact_starts(text, protected, expected): + assert chunks._site_lists(text, protected) == expected + + +def test_site_lists_do_not_revisit_every_interval_for_each_line(): + class Intervals(list): + visits = 0 + + def __iter__(self): + for interval in super().__iter__(): + self.visits += 1 + yield interval + + protected = Intervals((i * 6 + 1, i * 6 + 2) for i in range(64)) + assert chunks._site_lists("plain\n" * 64, protected) == [] + assert protected.visits <= 4 * len(protected) + + +def test_table_labels_keep_first_duplicate_offsets_and_unmatched_dialect_rows(monkeypatch): + def row(text, start=0, end=0): + return [Label(text, minimum=2, start=start, end=end)] + + github = [ + row("one", 1, 2), + row("repeat", 3, 4), + row("unmatched", 5, 6), + row("repeat", 7, 8), + row("last", 9, 10), + ] + site = [row("repeat"), row("site"), row("one"), row("repeat"), row("repeat")] + monkeypatch.setattr(chunks, "_github_rows", lambda text: github) + monkeypatch.setattr(chunks, "_site_tables", lambda text: SimpleNamespace(rows=site)) + assert list(chunks.table_labels("x" * 20).values()) == [ + Label("repeat", minimum=2, start=3, end=4), + Label("site", minimum=2, end=20), + Label("one", minimum=2, start=1, end=2), + Label("repeat", minimum=2, start=7, end=8), + Label("repeat", minimum=2, end=20), + Label("unmatched", minimum=2, start=5, end=6), + Label("last", minimum=2, start=9, end=10), + ] + + +def test_table_labels_copy_cells_in_proportion_to_rows(monkeypatch): + github = [[Label(f"github {i}", start=i, end=i + 1)] for i in range(64)] + site = [[Label(f"site {i}")] for i in range(64)] + copies = 0 + + def counted_replace(*args, **kwargs): + nonlocal copies + copies += 1 + return replace(*args, **kwargs) + + monkeypatch.setattr(chunks, "_github_rows", lambda text: github) + monkeypatch.setattr(chunks, "_site_tables", lambda text: SimpleNamespace(rows=site)) + monkeypatch.setattr(chunks, "replace", counted_replace) + labels = chunks.table_labels("example") + assert list(labels.values()) == [ + *[Label(f"site {i}", end=7) for i in range(64)], + *[row[0] for row in github], + ] + assert copies <= 4 * (len(github) + len(site)) diff --git a/tests/unit/test_i18n_stored_context.py b/tests/unit/test_i18n_stored_context.py new file mode 100644 index 0000000000..aa07ef23ec --- /dev/null +++ b/tests/unit/test_i18n_stored_context.py @@ -0,0 +1,88 @@ +"""Stored bodies retain source identities without treating metadata as source prose.""" + +from pathlib import Path + +import pytest + +from scripts.i18n import translate as t + +ROOT = t.ROOT +CODE = "docs/reference/operations/code.md" +HEADER = "| Field | Type | Meaning |\n| --- | --- | --- |\n" + + +def _code_row(field): + return next( + line + for line in (ROOT / CODE).read_text().splitlines() + if line.startswith(f"| `{field}` |") + and "worst branch" in line + or line.startswith(f"| `{field}` |") + and "per-branch unknown reasons" in line + ) + + +def test_actual_causes_explanation_translates_without_changing_its_wire_tokens(): + source = HEADER + _code_row("causes") + "\n" + output = ( + source.replace("Field", "フィールド") + .replace("Type", "型") + .replace("Meaning", "意味") + .replace("per-branch unknown reasons", "ブランチごとの不明な理由") + ) + assert t.differences(source, output, source_path=CODE) == [] + assert t.differences(source, output.replace("no_branch_version", "版なし"), source_path=CODE) + assert t.differences(source, source, source_path=CODE) + + +def test_actual_verdict_unknown_remains_a_protected_wire_value(): + source = HEADER + _code_row("verdict") + "\n" + output = source.replace("the worst branch's word", "最も悪いブランチの判定") + assert t.differences(source, output, source_path=CODE) == [] + assert t.differences(source, output.replace("unknown", "不明"), source_path=CODE) + + +def _stored_page(monkeypatch, source): + lang = t.LANGUAGES[1] + path = ROOT / t.target_path(lang.code, "README.md") + stored = [t.render("README.md", lang, source, "", t.DEFAULT_MODEL)] + read_text = Path.read_text + monkeypatch.setattr(t, "sources", lambda: ("README.md",)) + monkeypatch.setattr(t, "LANGUAGES", (lang,)) + monkeypatch.setattr(t, "prepare", lambda source_path, language: (source, "")) + monkeypatch.setattr( + Path, + "read_text", + lambda p, *args, **kwargs: stored[0] if p == path else read_text(p, *args, **kwargs), + ) + return lang, stored + + +@pytest.mark.parametrize("name", ["README", "README.md"]) +def test_real_rendered_self_filename_passes_stored_check_but_mutation_fails(monkeypatch, name): + target = t.REPO_URL + "/blob/main/README.md" + source = f"[{name}]({target})\n" + assert t.differences(source, source, source_path="README.md") == [] + lang, stored = _stored_page(monkeypatch, source) + assert t.untranslated_pages() == [] + assert t.stale((lang,), t.DEFAULT_MODEL) == [] + changed = source.replace(f"[{name}]", "[名前]") + stored[0] = t.render("README.md", lang, changed, "", t.DEFAULT_MODEL) + assert any("protected source strings" in p for p in t.untranslated_pages()) + + +@pytest.mark.parametrize("changed", ["source", "banner", "blob"]) +def test_rendered_metadata_tampering_remains_stale(monkeypatch, changed): + source = f"[README.md]({t.REPO_URL}/blob/main/README.md)\n" + lang, stored = _stored_page(monkeypatch, source) + if changed == "source": + stored[0] = stored[0].replace("source=README.md", "source=other.md", 1) + elif changed == "banner": + stored[0] = stored[0].replace("which is authoritative", "different banner", 1) + else: + stored[0] = stored[0].replace(t.blob("README.md"), "0" * 40, 1) + assert t.stale((lang,), t.DEFAULT_MODEL) == [("README.md", lang)] + if changed in {"source", "banner"}: + assert any("protected source strings" in p for p in t.untranslated_pages()) + else: + assert t.untranslated_pages() == [] diff --git a/tests/unit/test_i18n_tracker_types.py b/tests/unit/test_i18n_tracker_types.py new file mode 100644 index 0000000000..c8f949e9f3 --- /dev/null +++ b/tests/unit/test_i18n_tracker_types.py @@ -0,0 +1,114 @@ +"""Tracker contract family spellings retain their source cell and field binding.""" + +import pytest + +from scripts.i18n import translate as t +from scripts.i18n.context import SourceContext +from server.tracker.domain.contract import REQUIRED + +PATH = "docs/features/tracker/record-contract.md" +HEADER = "| Column | Family | Meaning |\n| --- | --- | --- |\n" +FIELDS = ( + ("labels", "assignees"), + ("affected_versions", "fix_versions"), + ("triage_reproduces_on", "triage_clean_on"), + ("test_types", "reviewers", "src_components"), +) + + +def _row(fields, family="Array(String)", meaning=""): + return "| " + ", ".join(f"`{field}`" for field in fields) + f" | {family} | {meaning} |\n" + + +@pytest.mark.parametrize("fields", FIELDS) +def test_contract_family_cells_preserve_the_implemented_type(fields): + contract = REQUIRED["github_prs" if "test_types" in fields else "github_issues"] + assert all(contract[field] == "Array(String)" for field in fields) + source = HEADER + _row(fields) + assert t.differences(source, source, source_path=PATH) == [] + + +@pytest.mark.parametrize("case", ["path", "field", "column", "heading", "prose"]) +def test_type_words_are_not_exempt_in_unrelated_source_nodes(case): + source, path = HEADER + _row(FIELDS[0]), PATH + if case == "path": + path = "docs/other.md" + elif case == "field": + source = HEADER + _row(("other", "fields")) + elif case == "column": + source = HEADER + _row(FIELDS[0], "", "Array(String)") + elif case == "heading": + source = "## Array(String)\n" + else: + source = HEADER + "| Array(String) | | |\n" + assert t.differences(source, source, source_path=path) + + +@pytest.mark.parametrize( + "fields", + [("labels",), ("assignees", "labels"), ("labels", "assignees", "other"), ("labels", "labels")], +) +def test_a_type_requires_its_complete_ordered_field_declaration(fields): + source = HEADER + _row(fields) + assert t.differences(source, source, source_path=PATH) + + +def test_a_mutated_source_type_or_descriptive_field_gets_no_protection(): + source = HEADER + _row(FIELDS[0], "Array(Int)") + assert t.differences(source, source, source_path=PATH) + source = (HEADER + _row(FIELDS[0])).replace( + "`labels`, `assignees`", "`labels`, `assignees` example" + ) + assert t.differences(source, source, source_path=PATH) + + +def test_type_protection_does_not_exempt_translatable_headers(): + source = HEADER.replace("Family", "Type family") + _row(FIELDS[0]) + assert t.differences(source, source, source_path=PATH) + assert ( + t.differences(source, source.replace("Type family", "型のファミリー"), source_path=PATH) + == [] + ) + + +@pytest.mark.parametrize("changed", ["Array(Int)", "Array(String) Array(String)", "配列", ""]) +def test_family_type_spelling_and_multiplicity_cannot_change(changed): + source = HEADER + _row(FIELDS[0]) + assert t.differences(source, HEADER + _row(FIELDS[0], changed), source_path=PATH) + + +def test_family_qualifiers_and_neighboring_descriptions_still_need_translation(): + source = HEADER + _row(FIELDS[0], "Array(String) required", "The assigned labels.") + assert t.differences(source, source, source_path=PATH) + output = source.replace("required", "必須").replace( + "The assigned labels.", "割り当てたラベル。" + ) + assert t.differences(source, output, source_path=PATH) == [] + + +@pytest.mark.parametrize("case", ["field", "column", "row"]) +def test_family_type_cannot_move_away_from_its_source_binding(case): + source = HEADER + _row(FIELDS[0]) + _row(("unrelated",), "", "Other values.") + output = source.replace("Other values.", "別の値。") + if case == "field": + output = output.replace("`labels`, `assignees`", "`unrelated`").replace( + "`unrelated` | |", "`labels`, `assignees` | |" + ) + elif case == "column": + output = output.replace("Array(String) | |", " | Array(String) |") + else: + output = output.replace("Array(String) | |", " | |").replace( + " | | 別の値。", " | Array(String) | 別の値。" + ) + assert t.differences(source, output, source_path=PATH) + + +@pytest.mark.parametrize("newline", ["\n", "\r\n"]) +def test_headerless_family_request_uses_the_complete_source_context(newline): + english = (HEADER + _row(FIELDS[0], meaning="The assigned labels.")).replace("\n", newline) + row = _row(FIELDS[0], meaning="The assigned labels.").rstrip("\n") + start = english.index(row) + scope = SourceContext(PATH, english, start, start + len(row)) + output = row.replace("The assigned labels.", "割り当てたラベル。") + assert t.differences(row, output, source_context=scope) == [] + assert t.differences(row, output.replace("Array(String)", "Array(Int)"), source_context=scope) diff --git a/tests/unit/test_in_use_coverage.py b/tests/unit/test_in_use_coverage.py index 8d124b8c85..079eb227ed 100644 --- a/tests/unit/test_in_use_coverage.py +++ b/tests/unit/test_in_use_coverage.py @@ -56,6 +56,7 @@ # requests "loom.agent_cost_rollup_daily": _REQUEST, "loom.agent_events": _REQUEST, + "loom.agent_events_private": _REQUEST, "loom.agent_turn_usage": _REQUEST, "loom.audit_log": _REQUEST, "loom.policy_decisions": _REQUEST, diff --git a/tests/unit/test_install_script.py b/tests/unit/test_install_script.py index a9e61231db..2a7cd31c4f 100644 --- a/tests/unit/test_install_script.py +++ b/tests/unit/test_install_script.py @@ -1503,11 +1503,19 @@ def _opened(log: Path, wait: float = 1) -> list[str]: def test_a_new_install_on_a_desktop_opens_the_dashboard_once(installer_env: dict[str, str]) -> None: _start_stubs(installer_env) env, log = _desktop(installer_env) - _on_terminal(env, [], None) - assert _opened(log, wait=60) == ["http://127.0.0.1:7777/"] + opener = log.parent / "xdg-open" + attempts = log.with_suffix(".attempts") + # HUP must be ignored before fork, even before the opener can install a trap. + opener.write_text( + f'#!/bin/sh\necho invoked >> "{attempts}"\nkill -HUP "$$"\necho "$*" >> "{log}"\n' + ) + transcript = _on_terminal(env, [], None) + assert _opened(log, wait=60) == ["http://127.0.0.1:7777/"], transcript + assert attempts.read_text().splitlines() == ["invoked"] log.unlink() _on_terminal(env, [], None) # a rerun keeps its .env assert _opened(log) == [] + assert attempts.read_text().splitlines() == ["invoked"] def test_the_first_run_that_starts_loom_opens_the_dashboard(installer_env: dict[str, str]) -> None: diff --git a/tests/unit/test_instances.py b/tests/unit/test_instances.py index 897c75d3b5..f82ae014f0 100644 --- a/tests/unit/test_instances.py +++ b/tests/unit/test_instances.py @@ -310,4 +310,4 @@ def test_the_lifespan_reads_the_workers_lease_on_each_beat() -> None: from server import main - assert "on_beat=_leader.read_holder" in inspect.getsource(main.lifespan) + assert "on_beat=boot.refresh_instance_state" in inspect.getsource(main.lifespan) diff --git a/tests/unit/test_integration_credentials.py b/tests/unit/test_integration_credentials.py index 25c8f05e08..2fb63edf16 100644 --- a/tests/unit/test_integration_credentials.py +++ b/tests/unit/test_integration_credentials.py @@ -33,10 +33,14 @@ def pytest_sessionstart(session): ) (tmp_path / "test_credentials.py").write_text( """ +import dataclasses import os +import time import jwt from conftest import clock +from server.auth import keyring +from server.settings import settings def check_token(): token = os.environ["LOOM_API_KEY"] @@ -51,6 +55,12 @@ def check_token(): def test_first(): check_token() clock["now"] += 3601 + # In-process handlers can load the server keyring without a refresh worker. + keyring._view = dataclasses.replace( + keyring._view, + read_at=time.monotonic() - settings.jwt_revocation_max_stale_seconds - 1, + ) + assert keyring.stale() def test_later(): check_token() @@ -81,3 +91,52 @@ def test_later(): check=False, ) assert result.returncode == 0, result.stdout + result.stderr + + +@pytest.mark.parametrize("provided", [False, True]) +@pytest.mark.parametrize("body_fails", [False, True]) +def test_client_signer_restores_exact_snapshot_on_every_exit(monkeypatch, provided, body_fails): + import dataclasses + import time + + import jwt + + from server.auth import keyring + from server.core.errors import BackendUnavailableError + from server.settings import settings + from tests.conftest import _seed_test_api_key + + stale = dataclasses.replace( + keyring._view, + loaded=True, + read_at=time.monotonic() - settings.jwt_revocation_max_stale_seconds - 1, + ) + monkeypatch.setattr(keyring, "_view", stale) + if provided: + monkeypatch.setenv("LOOM_API_KEY", "caller-token") + else: + monkeypatch.delenv("LOOM_API_KEY", raising=False) + with pytest.raises(BackendUnavailableError, match="stale"): + keyring.signing_key() + + lifecycle = _seed_test_api_key.__wrapped__(None) + next(lifecycle) + assert keyring._view is not stale + token = os.environ["LOOM_API_KEY"] + if provided: + assert token == "caller-token" + else: + assert jwt.get_unverified_header(token)["kid"] == "default" + assert jwt.decode(token, options={"verify_signature": False})["org"] == "*" + # A handler can replace its own snapshot; teardown still restores the original. + keyring._view = dataclasses.replace(keyring._view, read_at=time.monotonic()) + if body_fails: + with pytest.raises(RuntimeError, match="body failed"): + lifecycle.throw(RuntimeError("body failed")) + else: + with pytest.raises(StopIteration): + next(lifecycle) + assert keyring._view is stale + assert os.environ.get("LOOM_API_KEY") == ("caller-token" if provided else None) + with pytest.raises(BackendUnavailableError, match="stale"): + keyring.signing_key() diff --git a/tests/unit/test_knowledge_download_text.py b/tests/unit/test_knowledge_download_text.py index 4183d65f7b..80e37d206b 100644 --- a/tests/unit/test_knowledge_download_text.py +++ b/tests/unit/test_knowledge_download_text.py @@ -59,6 +59,12 @@ def client(monkeypatch: pytest.MonkeyPatch) -> TestClient: def _serve( monkeypatch: pytest.MonkeyPatch, row: DocumentRow | None, blobs: dict[str, bytes] | None = None ) -> None: + from unittest.mock import AsyncMock + + from server.knowledge.store import source_access + + monkeypatch.setattr(source_access, "active_sources", AsyncMock(return_value=[])) + async def fake_get_one( org: str, namespace: str, source_uri: str, **_: Any ) -> DocumentRow | None: diff --git a/tests/unit/test_knowledge_maintenance_cli.py b/tests/unit/test_knowledge_maintenance_cli.py index 783b5ebce1..812e322762 100644 --- a/tests/unit/test_knowledge_maintenance_cli.py +++ b/tests/unit/test_knowledge_maintenance_cli.py @@ -182,3 +182,18 @@ async def _list(org: str, namespaces: list[str], *, cursor: Any, **kw: Any) -> l monkeypatch.setattr(documents_repo, "list_with_chunk_counts", _list) asyncio.run(ops.rechunk_namespace("o", "ns", page_size=1, dry_run=True)) assert seen == [(["ns"], None), (["ns"], (at, "ns", "kb://a"))] + + +def test_lexical_stats_rebuild_never_reads_or_writes_mirror_statistics() -> None: + from server.memory.store.term_freq import rebuild + + class NoPrivateReads(_FakeCH): + async def query_one(self, *args, **kwargs): + raise AssertionError("mirror statistics must not be read") + + ch = NoPrivateReads({}) + assert asyncio.run(rebuild(ch, org="o", namespace="acl-" + "1" * 24)) == { + "knowledge": 0, + "memory": 0, + } + assert ch.executed == [] diff --git a/tests/unit/test_knowledge_search_rerank.py b/tests/unit/test_knowledge_search_rerank.py index a8a10ef50e..c86613723a 100644 --- a/tests/unit/test_knowledge_search_rerank.py +++ b/tests/unit/test_knowledge_search_rerank.py @@ -122,7 +122,8 @@ class _Embedder: async def embed(self, text: str) -> list[float]: return [1.0] - def _search(input: Any, embedder: Any, vec: Any, pool: int, dropped: Any): + def _search(input: Any, embedder: Any, vec: Any, pool: int, dropped: Any, *, checked: Any): + assert checked is None if pools is not None: pools.append(pool) @@ -190,7 +191,9 @@ async def test_each_chunk_shows_its_own_namespaces_context(monkeypatch) -> None: for ns, d in (("n", 0.1), ("m", 0.2)) ] - def _search(input: Any, embedder: Any, vec: Any, pool: int, dropped: Any): + def _search(input: Any, embedder: Any, vec: Any, pool: int, dropped: Any, *, checked: Any): + assert checked is None + async def _run(namespaces: list[str]) -> list[tuple[str, list[Any]]]: return per_ns diff --git a/tests/unit/test_knowledge_serving.py b/tests/unit/test_knowledge_serving.py index 1d41d34827..e0907866aa 100644 --- a/tests/unit/test_knowledge_serving.py +++ b/tests/unit/test_knowledge_serving.py @@ -322,8 +322,9 @@ async def test_a_memory_stack_serves_only_the_heads_version( """`memory.stack` reads chunks itself: under the Postgres authority its knowledge section takes the same check and refill as a search.""" from server.knowledge.app import search + from server.knowledge.app.source_access import ReadPlan from server.memory.api.models_lifecycle import MemoryStackInput - from server.memory.app import stack + from server.memory.app import stack, stack_knowledge class _Embedder: model_name = "m" @@ -350,13 +351,18 @@ async def heads(org: str, sources: Any) -> dict[Any, Serving]: monkeypatch.setattr(pg, "enabled", lambda: True) monkeypatch.setattr(pg_documents, "serving", heads) fill = stack._StackFill(budget=10_000) - await stack._stack_knowledge( - MemoryStackInput( - org="o", namespace="ns", agent="a", include_knowledge=True, knowledge_top_k=2 - ), - fill, + knowledge_input = MemoryStackInput( + org="o", namespace="ns", agent="a", include_knowledge=True, knowledge_top_k=2 + ) + knowledge = await stack_knowledge.collect( + knowledge_input.org, + knowledge_input.namespace, + knowledge_input.agent, "text", + int(knowledge_input.knowledge_top_k), + ReadPlan(knowledge_input.org), ) + fill = stack._render(fill, knowledge.hits) assert [e.value for e in fill.entries] == ["new text", "other"] assert asked[:2] == [2, 4] # the page of two held a stale hit: fetched again, deeper diff --git a/tests/unit/test_knowledge_sources.py b/tests/unit/test_knowledge_sources.py index 03753d4aa3..d90ca64718 100644 --- a/tests/unit/test_knowledge_sources.py +++ b/tests/unit/test_knowledge_sources.py @@ -123,6 +123,12 @@ async def count_documents(self, org: str, ns: str, tag: str) -> int: @pytest.fixture def fake(monkeypatch: pytest.MonkeyPatch) -> _Store: + from server.knowledge.store import source_push as push_store + + async def no_push(*args: Any, **kwargs: Any) -> None: + return None + + monkeypatch.setattr(push_store, "get", no_push) fake = _Store() monkeypatch.setattr(app, "store", fake) monkeypatch.setattr(settings, "jwt_secret", "unit-test-root-secret") @@ -153,7 +159,7 @@ async def _has_live_holder(name: str, **_kw: Any) -> bool: monkeypatch.setattr(leases, "holding", _holding) monkeypatch.setattr(leases, "has_live_holder", _has_live_holder) - async def _open(org: str) -> list[dict[str, Any]]: + async def _open(org: str, *, ch=None) -> list[dict[str, Any]]: return list(fake.erasures) from server.erasure.app import ledger_reads diff --git a/tests/unit/test_lease_writes.py b/tests/unit/test_lease_writes.py new file mode 100644 index 0000000000..242b92623d --- /dev/null +++ b/tests/unit/test_lease_writes.py @@ -0,0 +1,64 @@ +"""An uncertain send keeps its durable fence until its server deadline passes.""" + +from __future__ import annotations + +import asyncio +from contextlib import contextmanager +from types import SimpleNamespace +from unittest.mock import AsyncMock + +import pytest + +from server.core import lease_writes as writes + + +@pytest.mark.asyncio +@pytest.mark.parametrize("failure", [None, TimeoutError, asyncio.CancelledError]) +async def test_fence_retains_only_uncertain_holder( + monkeypatch: pytest.MonkeyPatch, failure: type[BaseException] | None +) -> None: + state = SimpleNamespace(expired=False, deadline=0.0) + + def expire() -> None: + state.expired = True + + lease = SimpleNamespace(let_expire=expire) + take = AsyncMock(return_value=lease) + release = AsyncMock() + monkeypatch.setattr(writes.leases, "take", take) + monkeypatch.setattr(writes.leases, "release_shielded", release) + monkeypatch.setattr(writes.leases, "work_left", lambda *args: 24.0) + monkeypatch.setattr(writes.rmt_carry, "send_bound_s", lambda: 30) + + @contextmanager + def deadline(value: float): + state.deadline = value + yield + + monkeypatch.setattr(writes.rmt_carry, "under_lease", deadline) + + async def work() -> None: + async with writes.fenced("scope") as uncertain: + uncertain(True) + if failure: + raise failure() + uncertain(False) + + if failure: + with pytest.raises(failure): + await work() + else: + await work() + assert state.expired == bool(failure) + assert state.deadline > writes.time.monotonic() + ttl = take.call_args.kwargs["ttl_s"] + assert 0.4 * ttl + 30 + 5 <= ttl + release.assert_awaited_once_with(lease) + + +@pytest.mark.asyncio +async def test_unavailable_fence_never_enters_writer(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setattr(writes.leases, "take", AsyncMock(return_value=None)) + with pytest.raises(writes.BackendUnavailableError): + async with writes.fenced("scope"): + pytest.fail("writer admitted without fence") diff --git a/tests/unit/test_leases.py b/tests/unit/test_leases.py index 82569da79c..bc940c0460 100644 --- a/tests/unit/test_leases.py +++ b/tests/unit/test_leases.py @@ -4,6 +4,7 @@ from __future__ import annotations import asyncio +from types import SimpleNamespace from typing import Any import pytest @@ -11,6 +12,54 @@ from server.core import leases from server.core.errors import BackendUnavailableError from tests.unit.claims_fake import FakeLockTable +from tests.unit.clock_fake import ManualClock + + +class _ScheduledLockTable(FakeLockTable): + """Run real renewals while the test controls both clocks and each wake.""" + + def __init__(self) -> None: + super().__init__() + self.clock = ManualClock(t=1000.0) + self.sleeps: asyncio.Queue[tuple[float, asyncio.Future[None]]] = asyncio.Queue() + self.pending: tuple[float, asyncio.Future[None]] | None = None + + def now(self) -> float: + return self.clock.monotonic() + self.offset + + async def sleep(self, delay: float) -> None: + wake = asyncio.get_running_loop().create_future() + self.sleeps.put_nowait((delay, wake)) + await wake + + async def wake(self, *, elapsed: float | None = None) -> None: + delay, wake = self.pending or await self.sleeps.get() + self.pending = None + self.clock.advance(delay if elapsed is None else elapsed) + wake.set_result(None) + + async def renew_once(self) -> None: + before = self.sql.count(leases.LOCK_RENEW) + await self.wake() + # The next sleep starts only after the real renewal and ownership read finish. + self.pending = await self.sleeps.get() + assert self.sql.count(leases.LOCK_RENEW) == before + 1 + + +@pytest.fixture +def scheduled_lock_table(monkeypatch: Any) -> _ScheduledLockTable: + ch = _ScheduledLockTable() + + class LeaseAsyncio: + sleep = staticmethod(ch.sleep) + + def __getattr__(self, name: str) -> Any: + return getattr(asyncio, name) + + # Patch module bindings, never the event loop's shared time or asyncio modules. + monkeypatch.setattr(leases, "time", SimpleNamespace(monotonic=ch.clock.monotonic)) + monkeypatch.setattr(leases, "asyncio", LeaseAsyncio()) + return ch def _inserts(ch: FakeLockTable) -> list[str]: @@ -137,15 +186,27 @@ async def test_a_store_that_cannot_answer_is_unavailable_not_busy() -> None: assert not issubclass(leases.LeaseUnavailable, leases.LeaseBusy) -async def test_a_lease_is_renewed_while_its_block_runs() -> None: - ch = FakeLockTable() +async def test_a_lease_is_renewed_while_its_block_runs(scheduled_lock_table) -> None: + ch = scheduled_lock_table async with leases.cluster_lease("job", ttl_s=0.6, ch=ch) as lease: - ch.advance(0.4) # the server's clock: past the TTL of the first stamp - await asyncio.sleep(0.5) + initial = dict(ch.keys["job"]) + ch.advance(0.4) + for _ in range(8): + await ch.renew_once() + assert ch._stale(initial) and ch.keys["job"]["renewed"] > initial["renewed"] assert lease.held and not ch._stale(ch.keys["job"]) assert ch.keys == {} +async def test_a_delayed_renewal_wake_still_cancels_the_block(scheduled_lock_table) -> None: + ch = scheduled_lock_table + with pytest.raises(leases.LeaseLost): + async with leases.cluster_lease("job", ttl_s=0.6, ch=ch): + await ch.wake(elapsed=0.31) + await asyncio.Future() + assert leases.LOCK_RENEW not in ch.sql and ch.keys == {} + + async def test_a_lease_taken_over_cancels_its_block() -> None: ch = FakeLockTable() ran_on = False @@ -187,12 +248,15 @@ async def test_a_pause_past_half_the_ttl_counts_as_lost_without_a_call() -> None assert not lease.held -async def test_a_renewed_claim_outlives_its_ttl_until_released() -> None: - ch = FakeLockTable() +async def test_a_renewed_claim_outlives_its_ttl_until_released(scheduled_lock_table) -> None: + ch = scheduled_lock_table lease = await leases.take("idem:k", ttl_s=0.6, renew=True, ch=ch) assert lease is not None + initial = dict(ch.keys["idem:k"]) ch.advance(0.4) - await asyncio.sleep(0.8) + for _ in range(8): + await ch.renew_once() + assert ch._stale(initial) and ch.keys["idem:k"]["renewed"] > initial["renewed"] assert lease.held and not ch._stale(ch.keys["idem:k"]) await lease.release() assert ch.keys == {} diff --git a/tests/unit/test_ledger_schema_skew.py b/tests/unit/test_ledger_schema_skew.py index fda7bd21e7..69eeccfc4b 100644 --- a/tests/unit/test_ledger_schema_skew.py +++ b/tests/unit/test_ledger_schema_skew.py @@ -135,6 +135,7 @@ async def test_ledger_insert_drops_the_unknown_columns_not_the_batch( "slo_class", "status_class", "budget_ms", + "mirror_marked", ) assert len(warned) == len(newer) assert {c for c in newer if any(f"'{c}'" in w for w in warned)} == set(newer) diff --git a/tests/unit/test_llm_cache_visibility.py b/tests/unit/test_llm_cache_visibility.py index c92f6c7340..fe4aac3e9a 100644 --- a/tests/unit/test_llm_cache_visibility.py +++ b/tests/unit/test_llm_cache_visibility.py @@ -110,7 +110,7 @@ def __init__( async def query_all(self, sql, params=None): flat = " ".join(sql.split()) self.calls.append((flat, dict(params or {}))) - if "cache_hits" in flat and "UNION ALL" not in flat and "count()" not in flat: + if "cache_hits" in flat and "agent_cost_rollup_daily" not in flat and "count()" not in flat: return self.cache_rows return self.rows @@ -145,7 +145,8 @@ def test_rollup_path_reads_the_cache_totals_in_one_bounded_statement(monkeypatch "the roll-up read is unchanged" ) assert cache_sql.startswith("SELECT " + " ".join(cost_store.CACHE_SELECT.split())) - assert "FROM loom.agent_events WHERE org = {org:String}" in cache_sql + assert "FROM loom.agent_events UNION ALL" in cache_sql + assert "FROM loom.agent_events_private) WHERE org = {org:String}" in cache_sql assert "toDate(ts) BETWEEN {from_d:Date} AND {to_d:Date}" in cache_sql assert "operation = 'memory.ask'" in cache_sql and "namespace = {ns:String}" in cache_sql assert "PREWHERE" not in cache_sql @@ -183,7 +184,9 @@ def test_events_scan_path_folds_the_cache_columns_into_its_statement(monkeypatch out = _run(monkeypatch, ch, group_by=["model"]) assert len(ch.calls) == 1, "the scan path pays nothing extra" sql = ch.calls[0][0] - assert "toUInt64OrZero(args['out_llm_cache_hits'])" in sql and "UNION ALL" not in sql + assert "toUInt64OrZero(args['out_llm_cache_hits'])" in sql + assert sql.count("UNION ALL") == 1 and "agent_cost_rollup_daily" not in sql + assert "FROM loom.agent_events UNION ALL" in sql and "FROM loom.agent_events_private)" in sql assert [r.cache_hits for r in out.rows] == [2, 3] assert out.cache_hits == 5 and abs(out.cache_saved_usd - 0.3) < 1e-9 diff --git a/tests/unit/test_loom_search_mcp_render.py b/tests/unit/test_loom_search_mcp_render.py index 13a5a6aa36..dd72807024 100644 --- a/tests/unit/test_loom_search_mcp_render.py +++ b/tests/unit/test_loom_search_mcp_render.py @@ -166,7 +166,7 @@ def _make_harness(monkeypatch: pytest.MonkeyPatch) -> Any: state: dict[str, Any] = {"payload": "full", "asked": []} async def _sections(**kw: Any) -> dict[str, Any]: - state["asked"].append({k: v for k, v in kw.items()}) + state["asked"].append({k: v for k, v in kw.items() if k != "tracker_plan"}) return _payload(state["payload"]) async def _fanout(org: str, *_: object) -> Fanout: @@ -191,6 +191,9 @@ class _Limiter: def check(self, *_a: Any, **_k: Any) -> None: return None + from unittest.mock import AsyncMock + + monkeypatch.setattr(handler_mod, "prepare_tracker_search", AsyncMock(return_value=None)) for mod in (handler_mod, mcp_tools): monkeypatch.setattr(mod, "search_sections", _sections, raising=False) for mod in (mcp_call, mcp_tools): diff --git a/tests/unit/test_loom_search_repo_decisions.py b/tests/unit/test_loom_search_repo_decisions.py index c90d322be8..fb73d00130 100644 --- a/tests/unit/test_loom_search_repo_decisions.py +++ b/tests/unit/test_loom_search_repo_decisions.py @@ -26,6 +26,7 @@ from server.memory.app.search.scoring import per_key_fetch from server.memory.app.search.telemetry import credit_merged_hits from server.memory.domain.search_types import SearchHit +from tests.unit.checked_repo_search_fakes import install_repo_search from tests.unit.memory_search_fakes import install_search_fakes ORG = "acme" @@ -134,7 +135,7 @@ async def knowledge_leg(inp: Any, *, repo_namespace: str) -> Any: _stub_side_legs(monkeypatch) monkeypatch.setattr(fanout, "memory_with_repo_decisions", memory_leg) - monkeypatch.setattr(fanout, "knowledge_with_repo_docs", knowledge_leg) + install_repo_search(monkeypatch, knowledge_leg) return await fanout.search_sections( org=ORG, namespace=namespace, @@ -148,6 +149,7 @@ async def knowledge_leg(inp: Any, *, repo_namespace: str) -> Any: page="", explain=explain, repo_namespace=TRUNK, + tracker_plan=None, ) @@ -692,7 +694,7 @@ async def knowledge_leg(inp: Any, *, repo_namespace: str) -> Any: monkeypatch.setattr("server.observability.capture_consent.narrow_to", narrow_to) _stub_side_legs(monkeypatch) monkeypatch.setattr(fanout, "memory_with_repo_decisions", memory_leg) - monkeypatch.setattr(fanout, "knowledge_with_repo_docs", knowledge_leg) + install_repo_search(monkeypatch, knowledge_leg) out = await handler.handle_search( SearchInput(org=ORG, namespace="me", agent="a", query="why", page="p2") ) diff --git a/tests/unit/test_loom_search_tracker_general.py b/tests/unit/test_loom_search_tracker_general.py new file mode 100644 index 0000000000..46f21e05e2 --- /dev/null +++ b/tests/unit/test_loom_search_tracker_general.py @@ -0,0 +1,243 @@ +"""Ordinary questions read authorized trackers without changing memory ranking.""" + +import asyncio +from copy import deepcopy +from typing import Any +from unittest.mock import AsyncMock + +import pytest + +from server.identity.domain.read_scope import WHOLE_NAMESPACE, ReadFilters +from server.memory.app.loom_search import tracker_leg as leg +from server.memory.app.loom_search.answer_first import answer_first +from server.tracker.api.models import TrackerSimilarOutput + + +async def _run( + query: str, *, org: str, top_k: int = 5, timeout_s: float | None = None +) -> dict[str, Any] | None: + plan = await leg.prepare_tracker_search(query, org=org, top_k=top_k, timeout_s=timeout_s) + return await leg.tracker_leg(query, plan=plan, top_k=top_k) + + +@pytest.fixture +def trackers(monkeypatch: pytest.MonkeyPatch) -> AsyncMock: + monkeypatch.setattr("server.code.domain.scope.current_code_scope", lambda: None) + monkeypatch.setattr("server.identity.app.request_scope.request_scope", lambda: WHOLE_NAMESPACE) + monkeypatch.setattr( + "server.tracker.app.dupcheck_fanout.readable_tracker_namespaces", + AsyncMock(return_value=["tracker-one", "tracker-two"]), + ) + + async def search(input: Any) -> TrackerSimilarOutput: + assert input.org == "o" + assert input.kinds == ["issue", "pr"] + assert "vector" not in input.legs + return TrackerSimilarOutput( + items=[ + { + "kind": "pr", + "number": 7, + "title": "Retention decision", + "state": "closed", + "score": 0.5 if input.namespace == "tracker-one" else 0.8, + "url": "https://example.test/pull/7", + } + ] + ) + + call = AsyncMock(side_effect=search) + monkeypatch.setattr("server.tracker.app.similar.similar_in_namespace", call) + return call + + +async def test_ordinary_question_searches_readable_trackers_without_code_scope( + trackers: AsyncMock, +) -> None: + result = await _run("what did we decide about retention?", org="o", top_k=2) + assert result is not None and result["mode"] == "search" + assert trackers.await_count == 2 + assert [r["namespace"] for r in result["results"]] == ["tracker-two", "tracker-one"] + assert all(r["url"] == "https://example.test/pull/7" for r in result["results"]) + assert "verdict" not in result + lines = "\n".join(leg.tracker_text_lines(result)) + assert "Retention decision" in lines and "[tracker-two] #7" in lines + assert "duplicate" not in lines.lower() + + +async def test_read_narrowed_search_reads_no_tracker( + trackers: AsyncMock, monkeypatch: pytest.MonkeyPatch +) -> None: + monkeypatch.setattr( + "server.identity.app.request_scope.request_scope", + lambda: ReadFilters(scope="own_user", user_id="u", session_id=None), + ) + assert await _run("retention decision", org="o") is None + trackers.assert_not_awaited() + + +async def test_empty_tracker_results_add_no_section(trackers: AsyncMock) -> None: + trackers.side_effect = None + trackers.return_value = TrackerSimilarOutput() + assert await _run("retention decision", org="o") is None + + +async def test_timeout_covers_namespace_discovery( + trackers: AsyncMock, monkeypatch: pytest.MonkeyPatch +) -> None: + cancelled = asyncio.Event() + + async def discover(*args: Any, **kwargs: Any) -> list[str]: + try: + await asyncio.Event().wait() + finally: + cancelled.set() + return [] + + monkeypatch.setattr("server.tracker.app.dupcheck_fanout.readable_tracker_namespaces", discover) + assert await _run("retention decision", org="o", timeout_s=0.01) is None + assert cancelled.is_set() + trackers.assert_not_awaited() + + +def test_general_matches_preserve_the_existing_answer_first_sections() -> None: + payload = { + "memory": { + "results": [ + { + "memory_key": "home", + "namespace": "home", + "memory_type": "fact", + "similarity": 0.9, + }, + { + "memory_key": "other", + "namespace": "away", + "memory_type": "fact", + "similarity": 0.4, + }, + ] + }, + "knowledge": { + "results": [{"namespace": "away", "content": "related document", "similarity": 0.5}] + }, + "profile": {"results": []}, + "conversations": {"results": [{"content": "earlier discussion"}]}, + } + baseline = answer_first(deepcopy(payload), "home") + treatment = answer_first( + { + **deepcopy(payload), + "tracker": {"mode": "search", "results": [{"title": "Retention decision"}]}, + }, + "home", + ) + for section in ("memory", "knowledge", "profile", "conversations", "withheld"): + assert treatment.get(section) == baseline.get(section) + + +@pytest.mark.parametrize("scoped_defect", [False, True]) +async def test_tracker_consent_is_narrowed_in_parent_before_any_search_leg( + trackers: AsyncMock, monkeypatch: pytest.MonkeyPatch, scoped_defect: bool +) -> None: + from contextvars import ContextVar + + from server.memory.api.models_loom_search import SearchInput + from server.memory.app.loom_search import handler + + capture = ContextVar("tracker_test_capture", default="full") + calls: list[tuple[str, list[str]]] = [] + + async def narrow(org: str, namespaces: list[str]) -> None: + calls.append((org, namespaces)) + if "tracker-two" in namespaces: + capture.set("off") + + async def sections(**kwargs: Any) -> dict[str, Any]: + async def sibling() -> str: + return capture.get() + + assert await asyncio.create_task(sibling()) == "off" + return {k: {"results": []} for k in ("memory", "knowledge", "profile", "conversations")} + + monkeypatch.setattr( + "server.auth.fanout.namespaces_to_search", AsyncMock(return_value=(["home"], [])) + ) + monkeypatch.setattr(handler, "repo_namespace_in_scope", AsyncMock(return_value="")) + monkeypatch.setattr("server.observability.capture_consent.narrow_to", narrow) + monkeypatch.setattr(handler, "search_sections", sections) + query = "retention" + if scoped_defect: + from server.tracker.app.dupcheck import DuplicateCheckPlan + + query = "LOGICAL_ERROR in DB::MergeTree::merge: already reported?" + monkeypatch.setattr( + "server.code.domain.scope.current_code_scope", lambda: ("other-org", "code-example") + ) + + async def prepare(inp: Any) -> DuplicateCheckPlan: + return DuplicateCheckPlan( + inp, ("tracker-one", "tracker-two"), inp.namespace, False, False + ) + + monkeypatch.setattr("server.tracker.app.dupcheck.prepare_duplicate_check", prepare) + try: + await handler.handle_search(SearchInput(org="o", namespace="home", query=query)) + assert calls == ( + [("o", ["home"]), ("other-org", ["tracker-one", "tracker-two"])] + if scoped_defect + else [("o", ["home", "tracker-one", "tracker-two"])] + ) + finally: + capture.set("full") + + +async def test_prepared_targets_do_not_widen_after_discovery( + trackers: AsyncMock, monkeypatch: pytest.MonkeyPatch +) -> None: + discovered = ["tracker-one"] + discover = AsyncMock(return_value=discovered) + monkeypatch.setattr("server.tracker.app.dupcheck_fanout.readable_tracker_namespaces", discover) + plan = await leg.prepare_tracker_search("retention", org="o") + assert plan is not None + discovered.append("tracker-without-consent") + result = await leg.tracker_leg("retention", plan=plan) + assert result is not None and result["namespaces"] == ["tracker-one"] + discover.assert_awaited_once() + assert [call.args[0].namespace for call in trackers.await_args_list] == ["tracker-one"] + + +async def test_preflight_consumes_the_same_execution_budget(trackers: AsyncMock) -> None: + from dataclasses import replace + + plan = await leg.prepare_tracker_search("retention", org="o") + assert plan is not None + expired = replace(plan, deadline=asyncio.get_running_loop().time() - 1) + assert await leg.tracker_leg("retention", plan=expired) is None + trackers.assert_not_awaited() + + +@pytest.mark.parametrize("kind", ["full", "empty", "failed_legs", "no_block"]) +@pytest.mark.parametrize("namespace", ["alice", "team", "other"]) +@pytest.mark.parametrize("explain", [False, True]) +def test_recorded_sections_are_neutral_with_general_tracker_matches( + kind: str, namespace: str, explain: bool +) -> None: + from tests.unit.test_loom_search_mcp_render import _payload + + payload = _payload(kind) + baseline = answer_first(deepcopy(payload), namespace, explain=explain) + payload["tracker"] = { + "mode": "search", + "results": [ + { + "namespace": "tracker-one", + "kind": "issue", + "number": 7, + "title": "Retention decision", + } + ], + } + treatment = answer_first(payload, namespace, explain=explain) + for section in ("memory", "knowledge", "profile", "conversations", "withheld"): + assert treatment.get(section) == baseline.get(section) diff --git a/tests/unit/test_loom_search_tracker_leg.py b/tests/unit/test_loom_search_tracker_leg.py index d7d70e2c25..ac952280f0 100644 --- a/tests/unit/test_loom_search_tracker_leg.py +++ b/tests/unit/test_loom_search_tracker_leg.py @@ -12,6 +12,14 @@ from server.tracker.api.models import TrackerDuplicateCheckOutput from server.transport import mcp_tools + +async def _run( + query: str, *, org: str, top_k: int = 5, timeout_s: float | None = None +) -> dict[str, Any] | None: + plan = await ql.prepare_tracker_search(query, org=org, top_k=top_k, timeout_s=timeout_s) + return await ql.tracker_leg(query, plan=plan, top_k=top_k) + + DRAFT = ( "Is this already reported? LOGICAL_ERROR in MergeTreeData::renameTempPartAndAdd: added part covers " "existing parts\nAfter ALTER TABLE UPDATE under heavy inserts the replica restarted. " @@ -73,28 +81,44 @@ def _out(**kw: Any) -> TrackerDuplicateCheckOutput: @pytest.mark.asyncio -async def test_the_leg_runs_only_under_a_code_scope_for_a_defect_shape_and_fails_open( +async def test_the_duplicate_verdict_runs_only_for_a_scoped_defect_and_fails_open( monkeypatch, ) -> None: + from unittest.mock import AsyncMock + + from server.identity.domain.read_scope import WHOLE_NAMESPACE + + monkeypatch.setattr("server.identity.app.request_scope.request_scope", lambda: WHOLE_NAMESPACE) + monkeypatch.setattr( + "server.tracker.app.dupcheck_fanout.readable_tracker_namespaces", AsyncMock(return_value=[]) + ) + from server.tracker.app.dupcheck import DuplicateCheckPlan + + async def prepare(inp): + return DuplicateCheckPlan( + inp, ("tracker-example-private", "tracker-clickhouse"), inp.namespace, False, False + ) + + monkeypatch.setattr("server.tracker.app.dupcheck.prepare_duplicate_check", prepare) calls: list[dict[str, Any]] = [] - async def _check(inp): - calls.append(inp.model_dump()) + async def _check(plan): + calls.append(plan.input.model_dump()) return _out() - monkeypatch.setattr("server.tracker.app.dupcheck.handle_tracker_duplicate_check", _check) + monkeypatch.setattr("server.tracker.app.dupcheck.execute_duplicate_check", _check) monkeypatch.setattr("server.code.domain.scope.current_code_scope", lambda: None) - assert await ql.tracker_leg(DRAFT) is None and calls == [], ( + assert await _run(DRAFT, org="clickhouse") is None and calls == [], ( "no checkout scope: memory answers alone" ) monkeypatch.setattr( "server.code.domain.scope.current_code_scope", lambda: ("clickhouse", "code-example-private"), ) - assert await ql.tracker_leg("what is my coffee type?") is None and calls == [], ( + assert await _run("what is my coffee type?", org="clickhouse") is None and calls == [], ( "not a defect shape" ) - section = await ql.tracker_leg(DRAFT, top_k=3) + section = await _run(DRAFT, org="clickhouse", top_k=3) assert calls[0]["org"] == "clickhouse" and calls[0]["namespace"] == "code-example-private" assert calls[0]["frames"][0] == "MergeTreeData::renameTempPartAndAdd" and calls[0]["top_k"] == 3 assert section == { @@ -118,7 +142,7 @@ async def _check(inp): ], }, "the lean section: verdict, records read, items a reader acts on — no fit bookkeeping" - async def _down(inp): + async def _down(plan): return _out( verdict="none", epistemic="unavailable", @@ -127,25 +151,27 @@ async def _down(inp): namespaces=[], ) - monkeypatch.setattr("server.tracker.app.dupcheck.handle_tracker_duplicate_check", _down) - assert await ql.tracker_leg(DRAFT) is None, "an unavailable record is no section" + monkeypatch.setattr("server.tracker.app.dupcheck.execute_duplicate_check", _down) + assert await _run(DRAFT, org="clickhouse") is None, "an unavailable record is no section" - async def _boom(inp): + async def _boom(plan): raise RuntimeError("gate closed") - monkeypatch.setattr("server.tracker.app.dupcheck.handle_tracker_duplicate_check", _boom) - assert await ql.tracker_leg(DRAFT) is None, "an error is no section" + monkeypatch.setattr("server.tracker.app.dupcheck.execute_duplicate_check", _boom) + assert await _run(DRAFT, org="clickhouse") is None, "an error is no section" - async def _slow(inp): + async def _slow(plan): await asyncio.sleep(0.2) return _out() - monkeypatch.setattr("server.tracker.app.dupcheck.handle_tracker_duplicate_check", _slow) - assert await ql.tracker_leg(DRAFT, timeout_s=0.01) is None, "a timeout is no section" + monkeypatch.setattr("server.tracker.app.dupcheck.execute_duplicate_check", _slow) + assert await _run(DRAFT, org="clickhouse", timeout_s=0.01) is None, "a timeout is no section" from server.settings import settings monkeypatch.setattr(settings, "mcp_loom_search_tracker_timeout_s", 0.01) - assert await ql.tracker_leg(DRAFT) is None, "the setting bounds a leg that names no timeout" + assert await _run(DRAFT, org="clickhouse") is None, ( + "the setting bounds a leg that names no timeout" + ) def test_the_text_block_leads_with_the_verdict() -> None: @@ -177,7 +203,9 @@ def test_the_handler_gathers_the_leg_and_leads_the_payload_with_it() -> None: from server.memory.app.loom_search import fanout fan = inspect.getsource(fanout.search_sections) - assert "tracker_leg(query, top_k=top_k)" in fan, "the fifth leg rides the same gather" + assert "tracker_leg(query, plan=tracker_plan, top_k=top_k)" in fan, ( + "the fifth leg rides the same gather" + ) assert '{"tracker": t_section} if isinstance(t_section, dict) else {}' in fan src = inspect.getsource(mcp_tools.search_answer) assert 'lines = tracker_text_lines(payload.get("tracker"), top_k) + [' in src, ( diff --git a/tests/unit/test_marked_admitted_identity.py b/tests/unit/test_marked_admitted_identity.py new file mode 100644 index 0000000000..fb2bfab680 --- /dev/null +++ b/tests/unit/test_marked_admitted_identity.py @@ -0,0 +1,68 @@ +"""Private diagnostics retain admitted identity without exposing their work bag.""" + +from __future__ import annotations + +import contextvars +from contextlib import nullcontext + +import pytest + +from server.auth.context import set_current_auth +from server.auth.jwt import AuthInfo +from server.core import request_work +from server.core.diagnostics import private_work +from server.operations.base import Role +from server.transport._common import ledger_identity + + +def principal(): + return AuthInfo( + subject="reader@example.test", + org="org-a", + namespaces=("team-a",), + roles=(Role.VIEWER,), + is_service_account=True, + read_user_id="reader-user", + ) + + +@pytest.mark.parametrize("private", [False, True]) +@pytest.mark.parametrize("explicit", [False, True]) +@pytest.mark.parametrize("authenticated", [False, True]) +def test_admitted_ledger_identity_survives_diagnostic_suppression(private, explicit, authenticated): + def exercise(): + set_current_auth(principal() if authenticated else None) + request_work.begin().admitted = ("org-a", "team-a") + body = {"agent": "reader", "user_id": "body-user", "session_id": "session-a"} + if explicit: + body.update(org=" org-a ", namespace=" team-a ") + with private_work() if private else nullcontext(): + assert (request_work.current() is None) is private + assert ledger_identity(body) == { + "org": "org-a", + "namespace": "team-a", + "agent": "reader", + "user_id": "reader-user" if authenticated else "body-user", + "session_id": "session-a", + } + + contextvars.copy_context().run(exercise) + + +@pytest.mark.parametrize("private", [False, True]) +def test_a_fresh_logical_call_cannot_inherit_an_earlier_admitted_scope(private): + def exercise(): + set_current_auth(principal()) + with request_work.http_owner({"type": "http"}): + request_work.begin().admitted = ("org-a", "team-a") + request_work.begin() + with private_work() if private else nullcontext(): + assert ledger_identity({}) == { + "org": "org-a", + "namespace": "-", + "agent": "-", + "user_id": "reader-user", + "session_id": "-", + } + + contextvars.copy_context().run(exercise) diff --git a/tests/unit/test_marked_assistant_support.py b/tests/unit/test_marked_assistant_support.py new file mode 100644 index 0000000000..43c0cbcae0 --- /dev/null +++ b/tests/unit/test_marked_assistant_support.py @@ -0,0 +1,69 @@ +"""Protected ledger participation is unknown evidence for assistant support.""" + +from __future__ import annotations + +import pytest + +from server.assistant.app.support import streamed_support +from server.assistant.domain.steps import Step, steps_of +from server.assistant.domain.support import RUN_ROWS, CallRow +from server.assistant.store import ledger + + +def decoded(operation: str, success: bool, *, marked: bool) -> list[CallRow]: + return ledger._rows( + [ + { + "operation": operation, + "success": success, + "out_found": "false", + "out_hits": "0", + "mirror_marked": int(marked), + } + ] + ) + + +@pytest.mark.parametrize("operation", ["knowledge.search", "knowledge.get", "insights.query"]) +@pytest.mark.parametrize("success", [False, True]) +def test_protected_calls_neither_claim_failure_nor_decide_support( + operation: str, success: bool +) -> None: + rows = decoded(operation, success, marked=True) + assert steps_of(rows) == ([], False) + assert streamed_support([], "An answer", rows) == "unchecked" + + +@pytest.mark.parametrize( + ("operation", "success", "text", "support"), + [ + ("knowledge.search", True, "Searched documents", "unsupported"), + ("knowledge.search", False, "Couldn't search documents", "unchecked"), + ("knowledge.get", True, "Read a document", "unsupported"), + ("knowledge.get", False, "Couldn't read a document", "unchecked"), + ], +) +def test_ordinary_empty_calls_keep_their_step_and_support( + operation: str, success: bool, text: str, support: str +) -> None: + rows = decoded(operation, success, marked=False) + assert steps_of(rows) == ([Step(operation, text, success)], False) + assert streamed_support([], "An answer", rows) == support + + +@pytest.mark.parametrize("protected_success", [False, True]) +def test_empty_ordinary_evidence_cannot_make_protected_evidence_negative( + protected_success: bool, +) -> None: + rows = [ + *decoded("knowledge.search", True, marked=False), + *decoded("knowledge.get", protected_success, marked=True), + ] + assert steps_of(rows) == ([Step("knowledge.search", "Searched documents", True)], False) + assert streamed_support([], "An answer", rows) == "unchecked" + + +def test_protected_participation_keeps_the_run_bound_without_failure_steps() -> None: + rows = decoded("knowledge.get", False, marked=True) * (RUN_ROWS + 1) + assert steps_of(rows) == ([], True) + assert streamed_support([], "An answer", rows) == "unchecked" diff --git a/tests/unit/test_marked_event_delivery.py b/tests/unit/test_marked_event_delivery.py new file mode 100644 index 0000000000..aebd01e5ac --- /dev/null +++ b/tests/unit/test_marked_event_delivery.py @@ -0,0 +1,302 @@ +"""Marked logical calls commit one captured event through their request tail.""" + +from __future__ import annotations + +import asyncio +import copy +from contextlib import nullcontext +from dataclasses import replace +from types import SimpleNamespace +from unittest.mock import AsyncMock + +import pytest + +from server.auth import tenancy +from server.core import request_tail, request_work +from server.core.diagnostics import private_work +from server.observability import cost_accumulator, events, ledger + + +@pytest.fixture +def world(monkeypatch): + rows, queued, held = [], [], [] + + async def insert(table, data, *, settings, required_columns): + assert table == "loom.agent_events_private" + assert required_columns == frozenset({"mirror_marked"}) + assert settings["async_insert"] == settings["wait_for_async_insert"] == 1 + rows.extend(copy.deepcopy(data)) + + def hold(event): + held.append(event) + return False + + client = SimpleNamespace(insert=AsyncMock(side_effect=insert)) + emitter = SimpleNamespace(emit=queued.append) + monkeypatch.setattr(tenancy, "attributable", lambda org: True) + monkeypatch.setattr(events, "get_client", lambda: client) + monkeypatch.setattr(events, "get_emitter", lambda: emitter) + monkeypatch.setattr(events, "stamp_row", lambda row: row) + monkeypatch.setattr(events, "for_this_cell", lambda event: event) + monkeypatch.setattr(ledger, "get_emitter", lambda: emitter) + monkeypatch.setattr(ledger, "_event_hold", hold) + spend = SimpleNamespace( + cost_usd=0.125, + embed_tokens=13, + llm_input_tokens=17, + llm_output_tokens=19, + llm_calls=2, + dominant_model=lambda: "test-model", + ) + monkeypatch.setattr(cost_accumulator, "current", lambda: spend) + local_token = request_work._current.set(None) + tail = request_tail._Tail() + tail_token = request_tail._tail.set(tail) + request_work.begin() + try: + yield SimpleNamespace( + rows=rows, queued=queued, held=held, client=client, tail=tail, spend=spend + ) + finally: + request_tail._tail.reset(tail_token) + request_work._current.reset(local_token) + + +def emit(): + ledger.emit_agent_event( + op_name="knowledge.get", + identity={ + "org": "org-a", + "namespace": "team", + "agent": "reader", + "user_id": "user-a", + "session_id": "session-a", + }, + request_id="request-a", + latency_ms=23, + success=True, + error_code="", + raw_args={"mirror_marked": False}, + subject="subject-a", + consumer="test-client", + traffic_class="interactive", + ) + + +@pytest.mark.parametrize("private", [False, True]) +@pytest.mark.parametrize("hold_enabled", [False, True]) +async def test_marked_delivery_is_required_once_even_without_a_named_policy( + monkeypatch, world, private, hold_enabled +): + if not hold_enabled: + monkeypatch.setattr(ledger, "_event_hold", None) + assert request_work.mark_mirrored() + with private_work() if private else nullcontext(): + emit() + emit() + assert world.tail.has_required + assert world.rows == world.queued == world.held == [] + request_work.begin() + world.spend.cost_usd = 9.0 + await request_tail.drain_required() + await request_tail.drain_required() + await request_tail.settle(world.tail) + assert len(world.rows) == 1 + assert world.client.insert.await_count == 1 + assert world.queued == world.held == [] + row = world.rows[0] + assert "ts" not in row and row["mirror_marked"] == 1 + assert {name: row[name] for name in ("org", "namespace", "agent", "user_id", "session_id")} == { + "org": "org-a", + "namespace": "team", + "agent": "reader", + "user_id": "user-a", + "session_id": "session-a", + } + assert row["subject"] == "subject-a" and row["request_id"] == "request-a" + assert row["operation"] == "knowledge.get" and row["latency_ms"] == 23 + assert row["success"] is True and row["upstream_cost_usd"] == 0.125 + assert ( + row["embedding_tokens"], + row["input_tokens"], + row["output_tokens"], + row["llm_calls"], + ) == (13, 17, 19, 2) + assert row["model"] == "test-model" and "mirror_marked" not in row["args"] + + +async def test_required_insert_failure_stays_fatal_without_queue_fallback(world): + world.client.insert.side_effect = RuntimeError("private backend detail") + assert request_work.mark_mirrored() + emit() + assert world.tail.has_required + with pytest.raises(request_tail.RequiredTailError) as failed: + await request_tail.drain_required() + assert "private backend detail" not in str(failed.value) + with pytest.raises(request_tail.RequiredTailError): + await request_tail.settle(world.tail) + assert world.client.insert.await_count == 1 + assert world.rows == world.queued == world.held == [] + + +@pytest.mark.parametrize("closed", [False, True]) +async def test_unavailable_tail_cannot_queue_a_marked_request(world, closed): + if closed: + await request_tail.settle(world.tail) + else: + request_tail._tail.set(None) + assert request_work.mark_mirrored() + assert request_work.mirror_marked() + with pytest.raises(request_tail.RequiredTailError): + emit() + assert world.client.insert.await_count == 0 + assert world.rows == world.queued == world.held == [] + + +async def test_waiter_cancellation_drains_the_one_registered_insert(world): + started, release = asyncio.Event(), asyncio.Event() + original = world.client.insert.side_effect + + async def paused(*args, **kwargs): + started.set() + await release.wait() + await original(*args, **kwargs) + + world.client.insert.side_effect = paused + assert request_work.mark_mirrored() + emit() + assert world.tail.has_required + waiter = asyncio.create_task(request_tail.drain_required()) + try: + await asyncio.wait_for(started.wait(), 1) + waiter.cancel() + await asyncio.sleep(0) + waiter.cancel() + release.set() + with pytest.raises(asyncio.CancelledError): + await waiter + await request_tail.settle(world.tail) + assert len(world.rows) == 1 and world.client.insert.await_count == 1 + assert world.queued == world.held == [] + finally: + release.set() + if not waiter.done(): + waiter.cancel() + await asyncio.gather(waiter, return_exceptions=True) + + +def test_ordinary_event_still_uses_the_existing_queue(world): + emit() + assert not world.tail.has_required and world.client.insert.await_count == 0 + assert len(world.queued) == len(world.held) == 1 + assert world.queued[0].mirror_marked is False + assert world.rows == [] + + +@pytest.mark.parametrize("marked", [False, True]) +@pytest.mark.parametrize("failed", [False, True]) +async def test_ordinary_flush_excludes_private_rows_and_their_loss_counts(world, marked, failed): + emit() + ordinary = world.queued[0] + private = replace( + ordinary, + namespace=ordinary.namespace if marked else "acl-" + "a" * 24, + mirror_marked=marked, + request_id="private-request-canary", + ) + emitter = events.EventEmitter() + emitter.emit(private) + assert emitter.queue.empty() and all(v == 0 for v in emitter.stats().values()) + # The flush boundary also rejects a private row inserted around emit's guard. + emitter.queue.put_nowait(private) + emitter.emit(ordinary) + world.client.insert.side_effect = RuntimeError("ordinary insert failed") if failed else None + await emitter._flush_once() + args, _ = world.client.insert.call_args + assert args == ("loom.agent_events", [ordinary.to_row()]) + assert emitter.queue.empty() and emitter._inflight == 0 + assert emitter.dropped_flush_failed == int(failed) + assert emitter.dropped_queue_full == emitter.dropped_batch_repeat == 0 + + +@pytest.mark.parametrize("marked", [False, True]) +@pytest.mark.parametrize("found", [False, True]) +async def test_stored_marked_row_keeps_work_but_no_document_projection(world, marked, found): + from server.knowledge.api.models_knowledge import KnowledgeGetOutput + + if marked: + assert request_work.mark_mirrored() + bag = request_work.current() + bag.ch_statements, bag.ch_read_rows, bag.ch_read_bytes = 3, 17, 91 + bag.ch_elapsed_ms, bag.injected_facts, bag.injected_chunks = 4.5, 2, 5 + bag.schema_skipped = ["private-schema-canary"] + bag.stage_ms["private-stage-canary"] = 3.0 + ledger.emit_agent_event( + op_name="knowledge.get", + identity={ + "org": "org-a", + "namespace": "team", + "agent": "reader", + "user_id": "user-a", + "session_id": "session-a", + }, + request_id="request-a", + latency_ms=23, + success=True, + error_code="", + raw_args={"source_uri": "private-address-canary", "query": "private-query-canary"}, + result=KnowledgeGetOutput( + found=found, + source_uri="private-address-canary", + title="private-title-canary", + content="private-body-canary", + tags=["private-tag-canary"], + ), + ) + if marked: + await request_tail.drain_required() + row = world.rows[0] + assert row["args"] == { + "out_ch_statements": "3", + "out_ch_read_rows": "17", + "out_ch_read_bytes": "91", + "out_ch_elapsed_ms": "4.5", + "out_injected_facts": "2", + "out_injected_chunks": "5", + } + assert not any("private-" in str(value) for value in row.values()) + assert row["input_tokens"] == 17 and row["upstream_cost_usd"] == 0.125 + else: + row = world.queued[0].to_row() + assert row["args"]["out_found"] == str(found).lower() + assert "private-tag-canary" in row["args"]["out_tags"] + assert "private-address-canary" in str(row["args"]) + + +@pytest.mark.parametrize("marked", [False, True]) +async def test_stored_marked_failure_keeps_constant_outcome_without_error_text(world, marked): + if marked: + assert request_work.mark_mirrored() + ledger.emit_agent_event( + op_name="knowledge.get", + identity={ + "org": "org-a", + "namespace": "team", + "agent": "reader", + "user_id": "user-a", + "session_id": "session-a", + }, + request_id="request-a", + latency_ms=23, + success=False, + error_code="UNAVAILABLE", + error=RuntimeError("unquoted-private-backend-canary"), + ) + if marked: + await request_tail.drain_required() + row = world.rows[0] + assert row["args"] == {} + assert "unquoted-private-backend-canary" not in str(row) + assert row["success"] is False and row["error_code"] == "UNAVAILABLE" + else: + assert "unquoted-private-backend-canary" in world.queued[0].to_row()["args"]["error"] diff --git a/tests/unit/test_marked_request_event_writer.py b/tests/unit/test_marked_request_event_writer.py new file mode 100644 index 0000000000..925c80853e --- /dev/null +++ b/tests/unit/test_marked_request_event_writer.py @@ -0,0 +1,225 @@ +"""Captured marked requests use awaited insertion outside the ordinary queue.""" + +from __future__ import annotations + +import asyncio +import copy +import logging +from datetime import UTC, datetime +from types import SimpleNamespace +from unittest.mock import AsyncMock, Mock + +import pytest + +from server.core import ch_writes, diagnostics +from server.core.diagnostics import private_work +from server.observability import events + + +@pytest.fixture(autouse=True) +def diagnostic_handlers(): + token = diagnostics._codes_only.set(False) + handlers = [*logging.getLogger().handlers, logging.lastResort] + saved = [(handler, handler.filters[:]) for handler in handlers if handler] + try: + yield + finally: + diagnostics._codes_only.reset(token) + for handler, filters in saved: + handler.filters[:] = filters + + +@pytest.fixture +def writer(monkeypatch): + rows = [] + + async def insert(table, data, *, settings, required_columns): + assert required_columns == frozenset({"mirror_marked"}) + rows.append((table, copy.deepcopy(data), dict(settings))) + + client = SimpleNamespace(insert=AsyncMock(side_effect=insert)) + emitter = events.EventEmitter() + monkeypatch.setattr(events, "get_client", lambda: client) + monkeypatch.setattr(events, "get_emitter", lambda: emitter) + monkeypatch.setattr(events, "stamp_row", lambda row: row) + monkeypatch.setattr(events, "for_this_cell", lambda event: event) + return SimpleNamespace(client=client, emitter=emitter, rows=rows) + + +def captured_event(**changes): + values = dict( + ts=datetime.fromtimestamp(0, UTC), + org="org", + namespace="team", + agent="agent", + user_id="user", + session_id="session", + operation="memory.search", + request_id="request", + latency_ms=13, + success=False, + input_tokens=17, + output_tokens=19, + embedding_tokens=23, + upstream_cost_usd=0.125, + bytes_written=29, + error_code="UNAVAILABLE", + kind="request", + args={"field": "digest"}, + model="model", + llm_calls=2, + subject="subject", + transport="http", + mirror_marked=True, + ) + values.update(changes) + return events.AgentEvent(**values) + + +@pytest.mark.asyncio +@pytest.mark.parametrize("batching", [False, True]) +async def test_waited_writer_preserves_row_and_omits_process_clock(monkeypatch, writer, batching): + monkeypatch.setattr( + ch_writes, + "settings", + SimpleNamespace( + ch_batched_inserts=batching, + ch_batched_insert_wait_min_ms=3, + ch_batched_insert_wait_max_ms=11, + ch_batched_insert_background_wait_max_ms=17, + ), + ) + event = captured_event() + expected = event.to_row() + del expected["ts"] + expected["args"] = {} + expected["memory_key"] = "" + original = copy.deepcopy(event) + before = writer.emitter.stats() + with private_work(): + await events.write_marked_request_event(event) + assert event == original + assert len(writer.rows) == 1 + table, rows, settings = writer.rows[0] + assert table == "loom.agent_events_private" and rows == [expected] + assert "ts" not in rows[0] and rows[0]["mirror_marked"] == 1 + assert settings["wait_for_async_insert"] == 1 + assert settings["async_insert"] == int(batching) + if batching: + assert settings["async_insert_use_adaptive_busy_timeout"] == 1 + assert settings["async_insert_busy_timeout_min_ms"] == 3 + assert settings["async_insert_busy_timeout_max_ms"] == 11 + else: + assert settings == {"async_insert": 0, "wait_for_async_insert": 1} + assert writer.emitter.stats() == before + assert writer.emitter.queue.empty() + + +@pytest.mark.asyncio +async def test_writer_drops_untrusted_projections_even_without_the_transport(writer): + event = captured_event( + memory_key="private-key-canary", + args={ + "out_ch_statements": "3", + "out_ch_read_rows": "private-row-canary", + "out_ch_read_bytes": "-1", + "out_injected_facts": "1.5", + "out_injected_chunks": "2", + "out_ch_elapsed_ms": "inf", + "out_tags": "private-tag-canary", + "error": "private-error-canary", + }, + ) + with private_work(): + await events.write_marked_request_event(event) + row = writer.rows[0][1][0] + assert row["args"] == {"out_ch_statements": "3"} + assert row["memory_key"] == "" + assert "private-" not in str(row) + assert event.memory_key == "private-key-canary" + + +@pytest.mark.asyncio +@pytest.mark.parametrize( + "kind,marker,private", + [ + ("worker", True, True), + ("request", False, True), + ("request", 1, True), + ("request", True, False), + ], +) +async def test_invalid_capture_refuses_before_client_access(monkeypatch, kind, marker, private): + access = Mock(side_effect=AssertionError("invalid capture must not touch the client")) + monkeypatch.setattr(events, "get_client", access) + event = captured_event(kind=kind, mirror_marked=marker) + if private: + with private_work(), pytest.raises(ValueError, match="server classification"): + await events.write_marked_request_event(event) + else: + with pytest.raises(ValueError, match="server classification"): + await events.write_marked_request_event(event) + access.assert_not_called() + + +@pytest.mark.asyncio +async def test_insert_failure_is_owned_and_never_queued(writer): + original = RuntimeError("private backend canary") + writer.client.insert.side_effect = original + before = writer.emitter.stats() + with private_work(), pytest.raises(RuntimeError) as caught: + await events.write_marked_request_event(captured_event()) + assert caught.value is original + assert writer.emitter.stats() == before + assert writer.emitter.queue.empty() + + +@pytest.mark.asyncio +async def test_cancelled_insert_leaves_no_background_writer(writer): + entered, release = asyncio.Event(), asyncio.Event() + + async def suspended(*args, **kwargs): + entered.set() + await release.wait() + + writer.client.insert.side_effect = suspended + before = writer.emitter.stats() + + async def deliver(): + with private_work(): + await events.write_marked_request_event(captured_event()) + + task = asyncio.create_task(deliver()) + try: + await entered.wait() + task.cancel() + with pytest.raises(asyncio.CancelledError): + await task + assert task.done() and task.cancelled() + assert writer.emitter.stats() == before + assert writer.emitter.queue.empty() + writer.client.insert.assert_awaited_once() + finally: + release.set() + if not task.done(): + task.cancel() + await asyncio.gather(task, return_exceptions=True) + + +@pytest.mark.asyncio +async def test_worker_writer_still_refuses_an_ordinary_namespace(writer): + with private_work(), pytest.raises(ValueError, match="require a mirror"): + await events.write_private_event(captured_event(kind="worker")) + writer.client.insert.assert_not_awaited() + + +@pytest.mark.asyncio +async def test_mirror_worker_uses_private_storage_even_without_request_marker(writer): + event = captured_event(kind="worker", namespace="acl-" + "a" * 24, mirror_marked=False) + expected = event.to_row() + with private_work(): + await events.write_private_event(event) + table, rows, _ = writer.rows[0] + assert table == "loom.agent_events_private" + assert rows == [expected] and rows[0]["mirror_marked"] == 0 + assert writer.emitter.queue.empty() diff --git a/tests/unit/test_marked_transport_exit.py b/tests/unit/test_marked_transport_exit.py new file mode 100644 index 0000000000..9fd7161bae --- /dev/null +++ b/tests/unit/test_marked_transport_exit.py @@ -0,0 +1,205 @@ +"""Cancelled marked operations retain one mandatory numeric accounting row.""" + +from __future__ import annotations + +import asyncio +import logging + +import pytest + +from server.core import diagnostics, request_tail +from server.observability import ledger +from tests.unit._marked_transport_exit import Stopped, assert_row, prepare + + +@pytest.fixture(autouse=True) +def diagnostic_handlers(): + token = diagnostics._codes_only.set(False) + handlers = [*logging.getLogger().handlers, logging.lastResort] + saved = [(handler, handler.filters[:]) for handler in handlers if handler] + try: + yield + finally: + diagnostics._codes_only.reset(token) + for handler, filters in saved: + handler.filters[:] = filters + + +@pytest.mark.parametrize("transport", ["http", "mcp"]) +@pytest.mark.parametrize("private", [False, True]) +@pytest.mark.parametrize("stage", ["handler", "post_rows"]) +async def test_cancelled_marked_call_commits_once_without_losing_admitted_identity( + monkeypatch, transport, private, stage +): + world = prepare(monkeypatch, transport) + world.private, world.stage = private, stage + tail = request_tail._Tail() + token = request_tail._tail.set(tail) + task = asyncio.create_task(world.invoke()) + try: + await asyncio.wait_for(world.ready.wait(), 1) + task.cancel("private cancellation nonce") + with pytest.raises(asyncio.CancelledError) as cancelled: + await task + assert cancelled.value is world.primary + assert tail.has_required, "marked cancellation lost required accounting" + assert world.rows == [] + await request_tail.settle(tail) + await request_tail.settle(tail) + assert_row(world, transport, success=stage == "post_rows") + finally: + world.release.set() + world.insert_release.set() + if not task.done(): + task.cancel() + await asyncio.gather(task, return_exceptions=True) + request_tail._tail.reset(token) + + +@pytest.mark.parametrize("transport", ["http", "mcp"]) +async def test_unmarked_cancellation_creates_no_marked_fallback(monkeypatch, transport): + world = prepare(monkeypatch, transport) + world.marked = False + tail = request_tail._Tail() + token = request_tail._tail.set(tail) + task = asyncio.create_task(world.invoke()) + try: + await asyncio.wait_for(world.ready.wait(), 1) + task.cancel() + with pytest.raises(asyncio.CancelledError): + await task + await request_tail.settle(tail) + assert not tail.has_required + assert world.rows == world.queued == world.held == [] + finally: + world.release.set() + if not task.done(): + task.cancel() + await asyncio.gather(task, return_exceptions=True) + request_tail._tail.reset(token) + + +@pytest.mark.parametrize("transport", ["http", "mcp"]) +async def test_primary_base_exception_identity_survives_capture(monkeypatch, transport): + world = prepare(monkeypatch, transport) + primary = world.control = Stopped("private control nonce") + tail = request_tail._Tail() + token = request_tail._tail.set(tail) + try: + with pytest.raises(Stopped) as stopped: + await world.invoke() + assert stopped.value is primary + assert tail.has_required, "escaping control lost required accounting" + await request_tail.settle(tail) + assert_row(world, transport) + finally: + request_tail._tail.reset(token) + + +@pytest.mark.parametrize("transport", ["http", "mcp"]) +async def test_capture_waits_for_handler_owned_child_final_charge(monkeypatch, transport): + world = prepare(monkeypatch, transport) + world.join_child = True + tail = request_tail._Tail() + token = request_tail._tail.set(tail) + task = asyncio.create_task(world.invoke()) + try: + await asyncio.wait_for(world.ready.wait(), 1) + task.cancel() + with pytest.raises(asyncio.CancelledError): + await task + assert world.child is not None and world.child.done() + assert tail.has_required, "joined cleanup spend has no required accounting" + await request_tail.settle(tail) + assert_row(world, transport, joined=True) + finally: + world.release.set() + if not task.done(): + task.cancel() + await asyncio.gather(task, return_exceptions=True) + if world.child is not None: + if not world.child.done(): + world.child.cancel() + await asyncio.gather(world.child, return_exceptions=True) + request_tail._tail.reset(token) + + +@pytest.mark.parametrize("transport", ["http", "mcp"]) +@pytest.mark.parametrize("fault", ["construction", "registration"]) +async def test_capture_failure_preserves_primary_control_and_latches_required_failure( + monkeypatch, transport, fault +): + world = prepare(monkeypatch, transport) + primary = world.control = Stopped("private primary nonce") + + def fail(*args, **kwargs): + raise RuntimeError("private accounting failure nonce") + + if fault == "construction": + monkeypatch.setattr(ledger, "AgentEvent", fail) + else: + monkeypatch.setattr(request_tail, "defer_required", fail) + tail = request_tail._Tail() + token = request_tail._tail.set(tail) + task = asyncio.create_task(world.invoke()) + try: + with pytest.raises(Stopped) as stopped: + await task + assert stopped.value is primary + assert tail.has_required and tail.required_failed + with pytest.raises(request_tail.RequiredTailError) as failed: + await request_tail.settle(tail) + assert str(failed.value) == "Required request work was not confirmed" + assert world.client.insert.await_count == 0 + assert world.rows == world.queued == world.held == [] + finally: + if not task.done(): + task.cancel() + await asyncio.gather(task, return_exceptions=True) + request_tail._tail.reset(token) + + +@pytest.mark.parametrize("transport", ["http", "mcp"]) +async def test_outer_tail_joins_one_commit_before_repeated_request_cancellation_escapes( + monkeypatch, transport +): + world = prepare(monkeypatch, transport) + world.pause_insert = True + + async def app(scope, receive, send): + await world.invoke() + await send({"type": "http.response.start", "status": 200, "headers": []}) + await send({"type": "http.response.body", "body": b"success"}) + + async def receive(): + return {"type": "http.disconnect"} + + async def send(message): + world.messages.append(message) + + task = asyncio.create_task( + request_tail.RequestTailMiddleware(app)({"type": "http"}, receive, send) + ) + try: + await asyncio.wait_for(world.ready.wait(), 1) + task.cancel("private cancellation nonce") + await asyncio.wait_for(world.insert_started.wait(), 1) + assert world.tail.has_required, "outer cleanup has no required cancellation row" + assert not task.done() and world.rows == [] + task.cancel() + await asyncio.sleep(0) + assert not task.done() and world.messages == [] + world.insert_release.set() + with pytest.raises(asyncio.CancelledError) as cancelled: + await task + assert cancelled.value is world.primary + assert world.messages == [] + assert_row(world, transport) + await request_tail.settle(world.tail) + assert world.client.insert.await_count == 1 + finally: + world.release.set() + world.insert_release.set() + if not task.done(): + task.cancel() + await asyncio.gather(task, return_exceptions=True) diff --git a/tests/unit/test_mcp_assistant_toolset.py b/tests/unit/test_mcp_assistant_toolset.py index 3ccf9a1dcb..05006fe6e1 100644 --- a/tests/unit/test_mcp_assistant_toolset.py +++ b/tests/unit/test_mcp_assistant_toolset.py @@ -378,7 +378,7 @@ class _Local: async def query_all(self, sql: str, params: dict[str, Any] | None = None) -> Any: if "FROM loom.agent_events" not in sql: return [] - return run([ddl("agent_events"), *rows], sql, params) + return run([ddl("agent_events"), ddl("agent_events_private"), *rows], sql, params) async def query_one(self, sql: str, params: dict[str, Any] | None = None) -> Any: found = await self.query_all(sql, params) diff --git a/tests/unit/test_mcp_client_provenance.py b/tests/unit/test_mcp_client_provenance.py index 5a255d587b..038cd7fe0e 100644 --- a/tests/unit/test_mcp_client_provenance.py +++ b/tests/unit/test_mcp_client_provenance.py @@ -216,6 +216,14 @@ async def query_all( monkeypatch.setattr("server.auth.context.resolve_my_namespaces", _resolve_my_namespaces) monkeypatch.setattr("server.auth.authz.check_authorized", _check_authorized) monkeypatch.setattr("server.core.ch.get_client", lambda: _CH()) + from unittest.mock import AsyncMock + + from server.knowledge.app import source_access as access_app + from server.knowledge.store import source_access + + mirror_auth = AsyncMock(return_value=None) + monkeypatch.setattr(access_app, "check_authorized", mirror_auth) + monkeypatch.setattr(source_access, "active_sources", AsyncMock(return_value=[])) monkeypatch.setattr("server.memory.app.search.handle_memory_search", _memory_search) monkeypatch.setattr( "server.knowledge.app.knowledge_search.handle_knowledge_search", _knowledge_search @@ -244,6 +252,10 @@ async def query_all( assert resp["result"]["isError"] is False assert captured["authz"] == (Role.VIEWER, "test", "team-grant") + assert {call.args[3] for call in mirror_auth.await_args_list} == { + "team-grant", + "personal-token", + } assert captured["memory_input"].namespace == "team-grant" assert captured["memory_input"].namespace_scope == "all_mine" assert captured["profile_params"]["ns"] == ["team-grant", "personal-token"] diff --git a/tests/unit/test_mcp_coding_toolset.py b/tests/unit/test_mcp_coding_toolset.py index 272ec9b61c..8d0a9a5da8 100644 --- a/tests/unit/test_mcp_coding_toolset.py +++ b/tests/unit/test_mcp_coding_toolset.py @@ -245,7 +245,10 @@ def test_activation_triggers_are_one_list_on_both_tiers(): core_s = next(d for d in synthetic_descriptors("core") if d["name"] == "loom_search") coding_s = next(d for d in synthetic_descriptors("coding") if d["name"] == "loom_search") assert coding_s["description"] == coding_search_description(core_s["description"]) - assert "profile, knowledge and past conversations" in coding_s["description"] + assert ( + "profile, knowledge, past conversations and readable issues and pull requests" + in coding_s["description"] + ) assert "(uploaded documents)" in core_s["description"] for must in ( "One call per question", diff --git a/tests/unit/test_mcp_listing_budget.py b/tests/unit/test_mcp_listing_budget.py index f246b6a921..c40f7ee7e6 100644 --- a/tests/unit/test_mcp_listing_budget.py +++ b/tests/unit/test_mcp_listing_budget.py @@ -559,3 +559,12 @@ def test_marked_fields_are_unlisted_but_still_accepted(): # memory.pin forces pinned on; memory.set (same model) still lists it assert "pinned" not in listed["loom_memory_pin"]["inputSchema"]["properties"] assert "pinned" in listed["loom_memory_set"]["inputSchema"]["properties"] + + +@pytest.mark.parametrize("toolset", ["core", "coding", "atomic"]) +def test_memory_set_explains_repository_tags_without_tagging_unrelated_facts(toolset): + tools = {t["name"]: t for t in _listing(toolset, False)} + description = tools["loom_memory_set"]["description"] + assert "For a fact about the primer's repository" in description + assert "`repo:` tag" in description + assert "omit that tag for unrelated facts" in description diff --git a/tests/unit/test_memory_ask.py b/tests/unit/test_memory_ask.py index 9032eb89e6..bf1056e3f9 100644 --- a/tests/unit/test_memory_ask.py +++ b/tests/unit/test_memory_ask.py @@ -15,8 +15,11 @@ import pytest +from server.knowledge.api.models_knowledge import KnowledgeSearchOutput from server.memory.api.models_ask import MemoryAskInput from server.memory.api.models_search import MemorySearchOutput, _MemorySearchHit +from tests.unit.ch_fake import RecordingCH +from tests.unit.checked_pack_fakes import install_pack_knowledge class _FakeLLM: @@ -65,17 +68,26 @@ def ask_env(monkeypatch: pytest.MonkeyPatch) -> SimpleNamespace: env.search_inputs = [] env.over_cap = False env.llm = _FakeLLM("Your favorite color is blue [m1].") + env.ch = RecordingCH(strict=False).install(monkeypatch, "server.memory.app.working_memory") async def fake_search(search_input: Any) -> MemorySearchOutput: env.search_inputs.append(search_input) return env.search_output - async def fake_over_cap(org: str, ns: str) -> bool: + async def fake_over_cap(org: str, ns: str, *, user_id: str = "") -> bool: return env.over_cap + async def fake_knowledge(_input: Any) -> KnowledgeSearchOutput: + return KnowledgeSearchOutput(results=[], embedding_model="fake-embed") + + async def no_pending(*args: Any, **kwargs: Any) -> int: + return 0 + monkeypatch.setattr(hsearch, "handle_memory_search", fake_search) monkeypatch.setattr(budget, "namespace_over_cap", fake_over_cap) monkeypatch.setattr(llm_client, "get_llm_client", lambda: env.llm) + install_pack_knowledge(monkeypatch, fake_knowledge) + monkeypatch.setattr("server.memory.app.pending_disclosure.pending_extraction", no_pending) return env @@ -364,7 +376,7 @@ def cascade_env(ask_env, monkeypatch: pytest.MonkeyPatch) -> SimpleNamespace: def for_model(model: str | None) -> Any: return {"strong-model": ask_env.strong, "cheap-model": ask_env.cheap}[model] - async def fake_ratio(org: str, ns: str) -> float: + async def fake_ratio(org: str, ns: str, *, user_id: str = "") -> float: return ask_env.budget_ratio monkeypatch.setattr(llm_client, "get_llm_client_for_model", for_model) @@ -750,11 +762,13 @@ async def test_knowledge_lookup_overlaps_retrieval(ask_env, monkeypatch) -> None order: list[str] = [] inner_search = hsearch.handle_memory_search - async def slow_knowledge(search_input, question, *, enabled=None): + async def slow_knowledge(search_input, question, *, enabled=None, prepared=None): + from server.memory.app.ask.context_blocks import AskKnowledge + order.append("knowledge_start") await asyncio.sleep(0.05) order.append("knowledge_end") - return "", 0 + return AskKnowledge() async def observed_search(search_input): order.append("search_start") diff --git a/tests/unit/test_memory_ask_deep_evidence.py b/tests/unit/test_memory_ask_deep_evidence.py index bfadf48a43..c1fd6df1e6 100644 --- a/tests/unit/test_memory_ask_deep_evidence.py +++ b/tests/unit/test_memory_ask_deep_evidence.py @@ -92,7 +92,7 @@ def env(monkeypatch: pytest.MonkeyPatch) -> SimpleNamespace: async def fake_search(search_input: Any) -> MemorySearchOutput: return e.search_output - async def fake_over_cap(org: str, ns: str) -> bool: + async def fake_over_cap(org: str, ns: str, *, user_id: str = "") -> bool: return False async def fake_fetch(**kw: Any) -> list[EvidenceTurn]: diff --git a/tests/unit/test_memory_ask_deep_first.py b/tests/unit/test_memory_ask_deep_first.py index 1f6029f610..6cf74f4b9b 100644 --- a/tests/unit/test_memory_ask_deep_first.py +++ b/tests/unit/test_memory_ask_deep_first.py @@ -74,7 +74,7 @@ async def fake_search(search_input: Any) -> MemorySearchOutput: embedding_model="fake-embed", ) - async def fake_over_cap(org: str, ns: str) -> bool: + async def fake_over_cap(org: str, ns: str, *, user_id: str = "") -> bool: return False async def fake_fetch(**kw: Any) -> list[Any]: @@ -175,7 +175,7 @@ async def test_selector_runs_on_the_cheap_client_when_configured(env, monkeypatc def for_model(model: str | None) -> Any: return {"strong-model": strong, "cheap-model": cheap}[model] - async def ratio(org: str, ns: str) -> float: + async def ratio(org: str, ns: str, *, user_id: str = "") -> float: return 0.1 monkeypatch.setattr(llm_client, "get_llm_client_for_model", for_model) diff --git a/tests/unit/test_memory_ask_precedents.py b/tests/unit/test_memory_ask_precedents.py index 4439ec0b21..eb5e4f705e 100644 --- a/tests/unit/test_memory_ask_precedents.py +++ b/tests/unit/test_memory_ask_precedents.py @@ -204,7 +204,7 @@ def prec_env(monkeypatch: pytest.MonkeyPatch) -> SimpleNamespace: async def fake_search(search_input: Any): return _search_output(list(env.hits)) - async def fake_over_cap(org: str, ns: str) -> bool: + async def fake_over_cap(org: str, ns: str, *, user_id: str = "") -> bool: return False class _CH: diff --git a/tests/unit/test_memory_ask_token_budget.py b/tests/unit/test_memory_ask_token_budget.py index da026dc7ad..8a8e5c8a03 100644 --- a/tests/unit/test_memory_ask_token_budget.py +++ b/tests/unit/test_memory_ask_token_budget.py @@ -93,7 +93,7 @@ def env(monkeypatch: pytest.MonkeyPatch) -> SimpleNamespace: async def fake_search(search_input: Any) -> MemorySearchOutput: return e.search_output - async def fake_over_cap(org: str, ns: str) -> bool: + async def fake_over_cap(org: str, ns: str, *, user_id: str = "") -> bool: return False monkeypatch.setattr(hsearch, "handle_memory_search", fake_search) diff --git a/tests/unit/test_memory_entity_capacity.py b/tests/unit/test_memory_entity_capacity.py new file mode 100644 index 0000000000..2008b93fa6 --- /dev/null +++ b/tests/unit/test_memory_entity_capacity.py @@ -0,0 +1,189 @@ +from __future__ import annotations + +import asyncio + +import pytest +from pydantic import ValidationError as PydanticValidationError + +from server.core.errors import LoomServerError +from server.memory.api.models_search import MemorySearchInput, MemorySearchTraceInput +from server.memory.app.entity_resolution import lookup_canonical_entities +from tests.unit.ch_fake import RecordingCH + + +@pytest.mark.parametrize( + "model", [MemorySearchInput, MemorySearchTraceInput], ids=["search", "trace"] +) +@pytest.mark.parametrize("count", [0, 1, 64], ids=["empty", "one", "raw64"]) +def test_supported_entity_filter_keeps_input_order( + model: type[MemorySearchInput], count: int +) -> None: + entities = [f"entity{i:03d}" for i in reversed(range(count))] + + request = model(org="o", namespace="n", query="q", entity_filter=entities) + + assert request.entity_filter == entities + assert request.model_dump()["entity_filter"] == entities + + +@pytest.mark.parametrize( + "model", [MemorySearchInput, MemorySearchTraceInput], ids=["search", "trace"] +) +@pytest.mark.parametrize("repeated", [False, True], ids=["distinct", "repeated"]) +def test_entity_filter_refuses_raw65_before_deduplication( + model: type[MemorySearchInput], repeated: bool +) -> None: + entities = ["same"] * 65 if repeated else [f"entity{i:03d}" for i in range(65)] + + with pytest.raises(PydanticValidationError) as raised: + model(org="o", namespace="n", query="q", entity_filter=entities) + + errors = raised.value.errors(include_url=False) + assert len(errors) == 1 + assert errors[0]["loc"] == ("entity_filter",) + assert errors[0]["type"] == "too_long" + assert errors[0]["ctx"]["max_length"] == 64 + assert errors[0]["ctx"]["actual_length"] == 65 + + +async def test_empty_entity_lookup_does_not_read() -> None: + ch = RecordingCH() + + async with asyncio.timeout(5): + result = await lookup_canonical_entities(ch, org="o", namespaces=["n"], entity_texts=[]) + + assert result == [] + assert ch.calls == [] + + +async def test_alias_lookup_keeps_cited_order_scope_and_sorted_new_aliases() -> None: + ch = RecordingCH().on( + "FROM loom.entity_canonical_map", + [ + {"canonical_text": "zoey"}, + {"canonical_text": "aaron"}, + {"canonical_text": "zoey"}, + {"canonical_text": "noah"}, + ], + ) + + async with asyncio.timeout(5): + result = await lookup_canonical_entities( + ch, + org="o", + namespaces=["z", "a", "z"], + entity_texts=["noah", "aurora", "bart", "noah"], + ) + + assert result == ["noah", "aurora", "bart", "aaron", "zoey"] + assert len(ch.calls) == 1 + call = ch.calls[0] + assert call.kind == "query_all" + assert call.params == { + "org": "o", + "namespaces": ["a", "z"], + "mentions": ["aurora", "bart", "noah"], + } + assert "org = {org:String}" in call.sql + assert "namespace IN {namespaces:Array(String)}" in call.sql + assert "tombstoned_at IS NULL" in call.sql + + +async def test_alias_union_accepts_exactly256_and_preserves_order() -> None: + aliases = [f"commit:alias{i:03d}" for i in range(255)] + ch = RecordingCH().on( + "FROM loom.entity_canonical_map", + [{"canonical_text": value} for value in reversed(aliases)], + ) + + async with asyncio.timeout(5): + result = await lookup_canonical_entities( + ch, org="o", namespaces=["n"], entity_texts=["noah"] + ) + + assert result == ["noah", *aliases] + assert len(result) == 256 + assert len(ch.calls) == 1 + + +async def test_alias_rows256_are_allowed_when_union_stays256() -> None: + aliases = [f"commit:alias{i:03d}" for i in range(255)] + ch = RecordingCH().on( + "FROM loom.entity_canonical_map", + [{"canonical_text": value} for value in ["noah", *aliases]], + ) + + async with asyncio.timeout(5): + result = await lookup_canonical_entities( + ch, org="o", namespaces=["n"], entity_texts=["noah"] + ) + + assert result == ["noah", *aliases] + assert len(result) == 256 + assert len(ch.calls) == 1 + + +async def test_alias_union257_refuses_instead_of_truncating_or_returning_raw() -> None: + aliases = [f"commit:alias{i:03d}" for i in range(256)] + ch = RecordingCH().on( + "FROM loom.entity_canonical_map", + [{"canonical_text": value} for value in aliases], + ) + + with pytest.raises(LoomServerError) as raised: + async with asyncio.timeout(5): + await lookup_canonical_entities(ch, org="o", namespaces=["n"], entity_texts=["noah"]) + + assert raised.value.code == "VECTOR_INPUT_TOO_LARGE" + assert len(ch.calls) == 1 + assert all(call.kind == "query_all" for call in ch.calls) + + +async def test_alias_rows257_refuse_even_if_normalization_would_fit() -> None: + # Distinct database strings can normalize to the same entity. A full sentinel + # page cannot prove that omitted aliases would fit the effective bound. + aliases = ["same", " Same ", "SAME", *[f"commit:alias{i:03d}" for i in range(254)]] + ch = RecordingCH().on( + "FROM loom.entity_canonical_map", + [{"canonical_text": value} for value in aliases], + ) + + with pytest.raises(LoomServerError) as raised: + async with asyncio.timeout(5): + await lookup_canonical_entities(ch, org="o", namespaces=["n"], entity_texts=["noah"]) + + assert raised.value.code == "VECTOR_INPUT_TOO_LARGE" + assert len(aliases) == 257 + assert len(set(aliases)) == 257 + assert len(ch.calls) == 1 + + +async def test_alias_read_requests_distinct_rows_and_the257_sentinel() -> None: + ch = RecordingCH().on("FROM loom.entity_canonical_map", []) + + async with asyncio.timeout(5): + result = await lookup_canonical_entities( + ch, org="o", namespaces=["n"], entity_texts=["noah"] + ) + + assert result == ["noah"] + assert len(ch.calls) == 1 + call = ch.calls[0] + sql = " ".join(call.sql.split()) + assert "SELECT DISTINCT canonical_text" in sql + assert "LIMIT 257" in sql + + +async def test_ordinary_alias_backend_failure_retains_existing_raw_order() -> None: + def unavailable(sql: str, params: dict) -> list[dict]: + raise RuntimeError("alias reader unavailable") + + ch = RecordingCH().on("FROM loom.entity_canonical_map", unavailable) + + async with asyncio.timeout(5): + result = await lookup_canonical_entities( + ch, org="o", namespaces=["n"], entity_texts=["noah", "aurora", "noah"] + ) + + assert result == ["noah", "aurora"] + assert len(ch.calls) == 1 diff --git a/tests/unit/test_memory_entity_capacity_errors.py b/tests/unit/test_memory_entity_capacity_errors.py new file mode 100644 index 0000000000..b97dff5935 --- /dev/null +++ b/tests/unit/test_memory_entity_capacity_errors.py @@ -0,0 +1,128 @@ +"""Entity expansion refuses oversized internal inputs without changing the filter.""" + +from __future__ import annotations + +import asyncio +from types import SimpleNamespace + +import pytest +from loom.errors import ValidationError as SDKValidationError +from loom.errors import from_response + +from server.core.errors import VectorInputTooLargeError, classified +from server.memory.api.models_search import MemorySearchInput, MemorySearchTraceInput +from server.memory.app import entity_resolution +from server.memory.app.search import computed, scope, trace +from tests.unit.ch_fake import RecordingCH + + +@pytest.mark.parametrize("entry", ["scope", "lookup", "trace"]) +@pytest.mark.parametrize("repeated", [False, True], ids=["distinct", "repeated"]) +async def test_internal_raw_filter_refuses_before_normalization_or_io( + entry: str, repeated: bool, monkeypatch: pytest.MonkeyPatch +) -> None: + entities = ["same"] * 65 if repeated else [f"entity{i:03d}" for i in range(65)] + request = MemorySearchInput(org="o", namespace="n", query="q").model_copy( + update={"entity_filter": entities} + ) + ch = RecordingCH() + + def no_embedder(): + raise AssertionError("oversized input must not reach the embedder") + + monkeypatch.setattr(trace, "get_embedder", no_embedder) + with pytest.raises(VectorInputTooLargeError): + if entry == "scope": + scope._entity_filter(request, []) + elif entry == "lookup": + await entity_resolution.lookup_canonical_entities( + ch, org="o", namespaces=["n"], entity_texts=entities + ) + else: + traced = MemorySearchTraceInput(org="o", namespace="n", query="q").model_copy( + update={"entity_filter": entities} + ) + await trace.handle_memory_search_trace(traced) + assert ch.calls == [] + + +def test_parser_entities_obey_the_same_bound() -> None: + request = MemorySearchInput(org="o", namespace="n", query="q") + with pytest.raises(VectorInputTooLargeError): + scope._entity_filter(request, ["same"] * 65) + + +@pytest.mark.parametrize("prelaunched", [False, True], ids=["serial", "prelaunched"]) +async def test_search_scope_does_not_replace_refused_aliases_with_the_raw_filter( + prelaunched: bool, monkeypatch: pytest.MonkeyPatch +) -> None: + request = MemorySearchInput(org="o", namespace="n", query="q", entity_filter=["noah"]) + ch = RecordingCH().on( + "FROM loom.entity_canonical_map", + [{"canonical_text": f"commit:alias{i:03d}"} for i in range(257)], + ) + calibration = asyncio.create_task(asyncio.sleep(0)) + await calibration + run = scope._SearchRun("", None, calibration, None) + monkeypatch.setattr(scope, "get_client", lambda: ch) + if prelaunched: + run.canonical_prelaunched = True + run.effective_entity_filter = ["noah"] + run.canonical_task = asyncio.create_task( + entity_resolution.lookup_canonical_entities( + ch, org="o", namespaces=["n"], entity_texts=["noah"] + ) + ) + try: + with pytest.raises(VectorInputTooLargeError): + await scope._resolve_entity_scope(request, run, [], {}) + assert len(ch.calls) == 1 + finally: + await run.close() + + +async def test_alias_backend_cannot_hide_a_typed_input_refusal() -> None: + refusal = VectorInputTooLargeError("entity expansion is too large") + + def refuse(_sql: str, _params: dict) -> list[dict]: + raise refusal + + ch = RecordingCH().on("FROM loom.entity_canonical_map", refuse) + with pytest.raises(VectorInputTooLargeError) as raised: + await entity_resolution.lookup_canonical_entities( + ch, org="o", namespaces=["n"], entity_texts=["noah"] + ) + assert raised.value is refusal + + +async def test_derived_canonical_refusal_is_not_an_empty_aggregate( + monkeypatch: pytest.MonkeyPatch, +) -> None: + ch = RecordingCH().on( + "FROM loom.entity_canonical_map", + [{"canonical_text": f"commit:alias{i:03d}"} for i in range(257)], + ) + monkeypatch.setattr(computed, "get_client", lambda: ch) + ctx = SimpleNamespace( + input=MemorySearchInput(org="o", namespace="n", query="q"), + derived_aggregate_cache={}, + query_shape="aggregational", + stated_value_update=False, + parser_derived_intent={"op": "count", "subject": "noah"}, + llm_free=True, + ) + with pytest.raises(VectorInputTooLargeError): + await computed._maybe_derived_aggregate(ctx) + assert ctx.derived_aggregate_cache == {} + assert len(ch.calls) == 1 + + +def test_input_refusal_keeps_its_code_and_nonretryable_sdk_class() -> None: + refusal = VectorInputTooLargeError("entity alias expansion exceeds 256 names") + detail = classified(refusal.to_detail(), refusal.status_code) + assert refusal.status_code == 422 + assert detail["code"] == "VECTOR_INPUT_TOO_LARGE" + assert detail["category"] == "input" and detail["retryable"] is False + error = from_response({"detail": detail}, refusal.status_code) + assert isinstance(error, SDKValidationError) + assert error.code == refusal.code and error.retryable is False diff --git a/tests/unit/test_memory_search_handler_gates.py b/tests/unit/test_memory_search_handler_gates.py index b29bf89ecf..1884a8abc0 100644 --- a/tests/unit/test_memory_search_handler_gates.py +++ b/tests/unit/test_memory_search_handler_gates.py @@ -565,7 +565,7 @@ async def _h(*a: Any, **k: Any) -> Any: return _h for mod, name in ( - (knowledge_mod, "handle_knowledge_search"), + (knowledge_mod, "run_checked_search"), (conversations_mod, "handle_conversation_search"), ): monkeypatch.setattr(mod, name, recorded(name, getattr(mod, name))) @@ -587,7 +587,7 @@ async def _h(*a: Any, **k: Any) -> Any: assert llm_attempts == [] assert "memories" in out.sections # answered from the vector query alone # The opt-in sections ran (an empty one that raised would pass the check above). - assert {"handle_knowledge_search", "handle_conversation_search"} <= set(ran) + assert {"run_checked_search", "handle_conversation_search"} <= set(ran) assert searched # the memories search, and the procedures section's for search_out in searched: _assert_plans_no_llm(search_out) diff --git a/tests/unit/test_memory_search_task_cleanup.py b/tests/unit/test_memory_search_task_cleanup.py index f7f46f3ddb..d4872c8db6 100644 --- a/tests/unit/test_memory_search_task_cleanup.py +++ b/tests/unit/test_memory_search_task_cleanup.py @@ -105,3 +105,162 @@ async def _value() -> int: await asyncio.sleep(0) assert done.result() == 1 assert pending.cancelled() + + +async def test_refusal_joins_scope_reads_before_escaping( + launched: list[scope._SearchRun], monkeypatch: pytest.MonkeyPatch +) -> None: + from server.core.errors import VectorInputTooLargeError + + started, finished = asyncio.Event(), asyncio.Event() + refusal = VectorInputTooLargeError("summary input exceeds 256 names") + + async def calibration(*_args: Any, **_kwargs: Any) -> Any: + started.set() + try: + await asyncio.Event().wait() + finally: + await asyncio.sleep(0) + finished.set() + + async def fail(*_args: Any, **_kwargs: Any) -> Any: + await started.wait() + raise refusal + + monkeypatch.setattr("server.memory.app.embedder_calibration.resolve_calibration", calibration) + monkeypatch.setattr(search_handler, "_resolve_query_enrichment", fail) + try: + with pytest.raises(VectorInputTooLargeError) as raised: + await search_handler.handle_memory_search(_input()) + assert raised.value is refusal + assert finished.is_set() + assert all(t.done() for t in _tasks(launched[0])) + finally: + for run in launched: + await asyncio.gather(*_tasks(run), return_exceptions=True) + + +async def test_repeated_cancel_during_cleanup_preserves_the_first_typed_refusal( + launched: list[scope._SearchRun], monkeypatch: pytest.MonkeyPatch +) -> None: + from server.core.errors import VectorInputTooLargeError + + started, cleaning, release, finished = (asyncio.Event() for _ in range(4)) + refusal = VectorInputTooLargeError("summary input exceeds 256 names") + + async def calibration(*_args: Any, **_kwargs: Any) -> Any: + started.set() + try: + await asyncio.Event().wait() + finally: + cleaning.set() + await release.wait() + finished.set() + + async def fail(*_args: Any, **_kwargs: Any) -> Any: + await started.wait() + raise refusal + + monkeypatch.setattr("server.memory.app.embedder_calibration.resolve_calibration", calibration) + monkeypatch.setattr(search_handler, "_resolve_query_enrichment", fail) + request = asyncio.create_task(search_handler.handle_memory_search(_input())) + try: + async with asyncio.timeout(2): + await cleaning.wait() + assert request.cancel() + await asyncio.sleep(0) + assert request.cancel() + release.set() + with pytest.raises(VectorInputTooLargeError) as raised: + await request + assert raised.value is refusal + assert finished.is_set() and all(t.done() for t in _tasks(launched[0])) + finally: + release.set() + await asyncio.gather( + request, *(_tasks(launched[0]) if launched else []), return_exceptions=True + ) + + +async def test_successful_search_inside_except_propagates_cleanup_cancellation( + monkeypatch: pytest.MonkeyPatch, +) -> None: + from server.memory.domain.search_types import SearchHit + from tests.unit.memory_search_fakes import install_search_fakes + + state = install_search_fakes(monkeypatch) + state.hits_by_ns["n"] = [ + SearchHit( + memory_key="color", + memory_type="semantic", + content_excerpt="favorite color is blue", + distance=0.1, + rank_score=0.9, + ) + ] + started, cleaning, release, finished = (asyncio.Event() for _ in range(4)) + runs: list[scope._SearchRun] = [] + children: list[asyncio.Task[Any]] = [] + completed: list[Any] = [] + launch = search_handler._launch_scope_reads + finish = search_handler._finish_search_output + + async def owned() -> None: + started.set() + try: + await asyncio.Event().wait() + finally: + cleaning.set() + await release.wait() + finished.set() + + def record_run(inp: MemorySearchInput) -> scope._SearchRun: + run = launch(inp) + runs.append(run) + return run + + async def finish_with_owned_child(ctx: Any, output: Any, hits: Any) -> None: + await finish(ctx, output, hits) + completed.append(output) + child = asyncio.create_task(owned()) + children.append(child) + runs[-1].side_tasks.append(child) + await started.wait() + + async def request_from_except() -> Any: + try: + raise LookupError("unrelated caller exception") + except LookupError: + return await search_handler.handle_memory_search( + MemorySearchInput( + org="o", + namespace="n", + agent="a", + query="favorite color", + recipe="fast", + auto_touch=False, + ) + ) + + monkeypatch.setattr(search_handler, "_launch_scope_reads", record_run) + monkeypatch.setattr(search_handler, "_finish_search_output", finish_with_owned_child) + request = asyncio.create_task(request_from_except()) + try: + async with asyncio.timeout(2): + await cleaning.wait() + assert completed and children and not children[0].done() + assert request.cancel() + await asyncio.sleep(0) + release.set() + with pytest.raises(asyncio.CancelledError): + await request + assert finished.is_set() and all(t.done() for t in children) + assert all(t.done() for run in runs for t in _tasks(run)) + finally: + release.set() + if not request.done(): + request.cancel() + for child in children: + if not child.done(): + child.cancel() + await asyncio.gather(request, *children, return_exceptions=True) diff --git a/tests/unit/test_memory_sensitivity.py b/tests/unit/test_memory_sensitivity.py index b559b6badd..4c800f9e67 100644 --- a/tests/unit/test_memory_sensitivity.py +++ b/tests/unit/test_memory_sensitivity.py @@ -207,8 +207,7 @@ def test_recent_recall_admits_medium_only_on_contact_intent() -> None: @pytest.mark.asyncio async def test_memory_stack_recent_recall_sql_carries_the_medium_guard(monkeypatch) -> None: - from types import SimpleNamespace - + from server.memory.api.models_lifecycle import MemoryStackInput from server.memory.app import handlers as mem from server.memory.app import restore as _restore_mod from server.memory.app import stack as _stack_mod @@ -236,7 +235,7 @@ async def _no_profile(*a, **kw): monkeypatch.setattr( "server.memory.app.profile.handle_profile_render", _no_profile, raising=False ) - inp = SimpleNamespace( + inp = MemoryStackInput( org="o", namespace="n", agent="a", @@ -250,13 +249,8 @@ async def _no_profile(*a, **kw): knowledge_top_k=0, seed_query="who reviewed the rota?", procedure_limit=0, - include_procedures=False, - sections=None, ) - try: - await stack_mod.handle_memory_stack(inp) - except Exception: # noqa: BLE001 — must not raise: later sections may need unstubbed fields - pass # sections after recent_recall may need fields this stub lacks + await stack_mod.handle_memory_stack(inp) recent = [(sql, p) for sql, p in seen if "recall_count > 0" in sql] assert recent, "recent_recall query not issued" sql, params = recent[0] diff --git a/tests/unit/test_mirror_checked_inspect.py b/tests/unit/test_mirror_checked_inspect.py new file mode 100644 index 0000000000..d1bc900f29 --- /dev/null +++ b/tests/unit/test_mirror_checked_inspect.py @@ -0,0 +1,148 @@ +"""Inspection adds checked titles after ordinary diagnostics have finished.""" + +from __future__ import annotations + +import asyncio +from datetime import UTC, datetime, timedelta +from types import SimpleNamespace +from unittest.mock import AsyncMock + +import pytest + +from server.identity.api.models_findings import ReportCoverage +from server.knowledge.api.models_inspect import ( + ChunkTotals, + DecisionTotals, + DocumentTotals, + ExtractionTotals, + IngestionTotals, + InspectDocument, + KnowledgeInspectInput, + KnowledgeInspectOutput, +) +from server.knowledge.app import inspect as app +from server.knowledge.app import source_access, source_titles + +NOW = datetime(2025, 1, 1, tzinfo=UTC) + + +def title(uri="gdrive:file#native", when=NOW): + proof = SimpleNamespace(mirrored=True, check=AsyncMock(), fresh=lambda: True) + return source_titles.Title(uri, "Mirror title", "markdown", "gdrive", "r1", 17, 0, when, proof) + + +def ordinary(uri="https://example.com/ordinary", when=NOW): + return InspectDocument( + source_uri=uri, + title="Ordinary title", + format="html", + source_scheme="https", + version=19, + revision=1, + ingested_at=when, + retired_versions=3, + ) + + +@pytest.fixture +def world(monkeypatch): + events = [] + plan = SimpleNamespace(marked=True, failed=False, unread=False) + report = KnowledgeInspectOutput( + org="acme", + namespace="team", + computed_at=NOW, + documents=DocumentTotals(live=1, retired_versions=3), + chunks=ChunkTotals(), + decisions=DecisionTotals(definition="Ordinary decisions"), + coverage=ReportCoverage(complete=True), + ingestions=IngestionTotals(worker_enabled=False), + extraction=ExtractionTotals(documents=0), + listed=[ordinary()], + listed_complete=True, + skipped=["ordinary section unavailable"], + ) + + async def prepare(org, namespaces): + assert (org, namespaces) == ("acme", ["team"]) + events.append("prepare") + return plan + + async def inspect(_input): + events.append("ordinary") + return report + + async def collect(checked, namespace, *, limit): + assert checked is plan and namespace == "team" and limit > 0 + events.append("titles") + return [title()] + + monkeypatch.setattr(source_access, "prepare", AsyncMock(side_effect=prepare)) + monkeypatch.setattr(app, "_ordinary_inspect", AsyncMock(side_effect=inspect)) + monkeypatch.setattr(source_titles, "collect", AsyncMock(side_effect=collect)) + return plan, report, events + + +async def inspect(limit=20): + return await app.handle_knowledge_inspect( + KnowledgeInspectInput(org="acme", namespace="team", sample_limit=limit) + ) + + +async def test_checked_titles_are_last_and_do_not_change_ordinary_diagnostics(world): + _plan, report, events = world + before = report.model_dump(exclude={"listed", "listed_complete"}) + output = await inspect() + assert events == ["prepare", "ordinary", "titles"] + assert output.model_dump(exclude={"listed", "listed_complete"}) == before + assert not output.listed_complete + checked = next(doc for doc in output.listed if doc.title == "Mirror title") + assert checked.source_uri == "gdrive:file#native" + assert (checked.version, checked.revision) == (17, 0) + assert checked.ingestion_id == "" + for field in ("retired_versions", "chunks", "decisions", "extraction", "jobs"): + assert getattr(checked, field) is None + + +async def test_public_sample_uses_utc_timestamp_then_uri_before_limit(world): + world[1].listed = [ordinary("https://example.com/z", NOW.replace(tzinfo=None))] + source_titles.collect.side_effect = None + source_titles.collect.return_value = [ + title("gdrive:b", NOW + timedelta(seconds=1)), + title("gdrive:z", NOW + timedelta(seconds=1)), + ] + output = await inspect(2) + assert [doc.source_uri for doc in output.listed] == ["gdrive:z", "gdrive:b"] + + +async def test_unmarked_inspection_keeps_the_entire_ordinary_result(world): + world[0].marked = False + before = world[1].model_dump() + output = await inspect() + assert output.model_dump() == before + source_titles.collect.assert_not_awaited() + assert world[2] == ["prepare", "ordinary"] + + +async def test_denied_mirror_titles_disclose_no_new_counts_or_skip_reason(world): + world[0].failed = True + source_titles.collect.side_effect = None + source_titles.collect.return_value = [] + before = world[1].model_dump(exclude={"listed_complete"}) + output = await inspect() + assert output.model_dump(exclude={"listed_complete"}) == before + assert not output.listed_complete + + +async def test_zero_sample_still_prepares_but_never_reads_mirror_titles(world): + world[1].listed = [] + output = await inspect(0) + assert output.listed == [] and not output.listed_complete + assert world[2] == ["prepare", "ordinary"] + source_titles.collect.assert_not_awaited() + + +async def test_title_cancellation_propagates(world): + source_titles.collect.side_effect = asyncio.CancelledError() + with pytest.raises(asyncio.CancelledError): + await inspect() diff --git a/tests/unit/test_mirror_checked_source_inspect.py b/tests/unit/test_mirror_checked_source_inspect.py new file mode 100644 index 0000000000..544fbfa1df --- /dev/null +++ b/tests/unit/test_mirror_checked_source_inspect.py @@ -0,0 +1,136 @@ +"""Source inspection reads only the requested source's checked title sample.""" + +from __future__ import annotations + +import asyncio +from datetime import UTC, datetime +from types import SimpleNamespace +from unittest.mock import AsyncMock + +import pytest + +from server.knowledge.api.models_sources import KnowledgeSourceInspectInput +from server.knowledge.app import source_access, source_titles +from server.knowledge.app import sources as app +from server.knowledge.domain.sources import KnowledgeSource + +SID = "11111111-1111-4111-8111-111111111111" +NOW = datetime(2025, 1, 1, tzinfo=UTC) + + +@pytest.fixture +def world(monkeypatch): + events = [] + plan = SimpleNamespace(marked=True, failed=False, unread=False) + src = KnowledgeSource( + "acme", + "team", + "notes", + "gdrive", + SID, + access="mirrored", + created_by="owner", + created_at=NOW, + ) + + async def prepare(org, namespaces): + assert (org, namespaces) == ("acme", ["team"]) + events.append("prepare") + return plan + + async def registry(*args): + assert args == ("acme", "team", "notes") + events.append("registry") + return src + + async def states(*args): + assert args == ("acme", "team", ["notes"]) + events.append("states") + return {} + + async def titles(checked, namespace, *, limit, source_id): + assert checked is plan and namespace == "team" and limit == 200 and source_id == SID + events.append("titles") + return [ + source_titles.Title( + "gdrive:file#native", + "Notes", + "html", + "gdrive", + "r1", + 7, + 0, + NOW, + SimpleNamespace(mirrored=True, check=AsyncMock(), fresh=lambda: True), + ) + ] + + monkeypatch.setattr(source_access, "prepare", AsyncMock(side_effect=prepare)) + monkeypatch.setattr(app, "_source_or_404", AsyncMock(side_effect=registry)) + monkeypatch.setattr(app.store, "read_states", AsyncMock(side_effect=states)) + monkeypatch.setattr( + app.store, + "source_documents", + AsyncMock( + return_value=[ + { + "source_uri": "https://example.com/ordinary", + "title": "Ordinary", + "ingested_at": NOW, + }, + ] + ), + ) + monkeypatch.setattr(source_titles, "collect", AsyncMock(side_effect=titles)) + return plan, src, events + + +async def inspect(): + return await app.handle_knowledge_source_inspect( + KnowledgeSourceInspectInput(org="acme", namespace="team", name="notes") + ) + + +async def test_mirror_source_inspection_checks_own_titles_after_public_registry_state(world): + output = await inspect() + assert world[2] == ["prepare", "registry", "states", "titles"] + assert output.name == "notes" and output.created_by == "owner" + assert output.config == {} + assert [doc.model_dump() for doc in output.documents] == [ + { + "source_uri": "gdrive:file#native", + "title": "Notes", + "source_revision": "r1", + "ingested_at": NOW.isoformat(), + } + ] + app.store.source_documents.assert_not_awaited() + + +async def test_ordinary_source_inspection_keeps_its_existing_document_lookup(world, monkeypatch): + from dataclasses import replace + + monkeypatch.setattr( + app, "_source_or_404", AsyncMock(return_value=replace(world[1], access="namespace")) + ) + output = await inspect() + assert [doc.source_uri for doc in output.documents] == ["https://example.com/ordinary"] + app.store.source_documents.assert_awaited_once_with("acme", "team", "source:notes") + source_titles.collect.assert_not_awaited() + assert world[2] == ["prepare", "states"] + + +async def test_denied_titles_do_not_expose_document_count_or_status(world): + world[0].failed = True + source_titles.collect.side_effect = None + source_titles.collect.return_value = [] + output = await inspect() + assert output.documents == [] + assert output.sync.status == "" + app.store.source_documents.assert_not_awaited() + + +async def test_source_title_cancellation_propagates(world): + source_titles.collect.side_effect = asyncio.CancelledError() + with pytest.raises(asyncio.CancelledError): + await inspect() diff --git a/tests/unit/test_mirror_checked_synthesize.py b/tests/unit/test_mirror_checked_synthesize.py new file mode 100644 index 0000000000..c0a7a4ac8e --- /dev/null +++ b/tests/unit/test_mirror_checked_synthesize.py @@ -0,0 +1,206 @@ +"""Synthesis discards every generated field after losing a retained mirror proof.""" + +from __future__ import annotations + +import asyncio +from datetime import UTC, datetime +from types import SimpleNamespace +from unittest.mock import AsyncMock + +import pytest + +from server.knowledge.api.models_knowledge import KnowledgeSynthesizeInput +from server.knowledge.app import source_access, source_corpus +from server.knowledge.app import synthesize as app +from server.knowledge.app.source_access import Admitted +from server.memory.domain import corpus_synthesis as cs + +URI = "gdrive:private#native" + + +@pytest.fixture +def world(monkeypatch): + import server.llm.client as clients + from server.settings import settings + + events = [] + item = Admitted( + "team", + {"namespace": "acl-" + "1" * 24, "source_uri": "stored"}, + { + "namespace": "acl-" + "1" * 24, + "source_uri": "stored", + "tags": [], + "version": 1, + "revision": 1, + "ingested_at": datetime(2025, 1, 1, tzinfo=UTC), + }, + ) + plan = SimpleNamespace( + org="acme", marked=True, failed=False, unread=False, current=lambda _: True + ) + plan.check = AsyncMock(return_value=[item]) + proofs = source_corpus.Proofs(plan, (item,)) + corpus = source_corpus.Corpus( + [cs.CorpusChunk(URI, 0, "Private content", ("Notes",), 3, {"page": 2})], 1, proofs + ) + + async def prepare(org, namespaces): + events.append("prepare") + assert org == "acme" and namespaces == ["team"] + return plan + + async def budget(org: str, ns: str, *, user_id: str = ""): + events.append("budget") + return False + + class Model: + model = "fixture" + + def __init__(self): + self.calls = [] + + async def complete(self, system, user, **kwargs): + self.calls.append((system, user)) + events.append("provider") + return SimpleNamespace(text=f"Private prose [{URI}#0]") + + model = Model() + loader = AsyncMock(return_value=corpus) + monkeypatch.setattr(source_access, "prepare", prepare) + monkeypatch.setattr(source_corpus, "load", loader) + monkeypatch.setattr("server.observability.budget.namespace_over_cap", budget) + monkeypatch.setattr(clients, "get_llm_client", lambda: model) + monkeypatch.setattr(settings, "memory_ask_synth_model", "") + monkeypatch.setattr( + "server.embedding.get_embedder", + lambda: SimpleNamespace(model_name="fixture"), + ) + return SimpleNamespace( + plan=plan, proofs=proofs, corpus=corpus, model=model, loader=loader, events=events + ) + + +async def synthesize(**kwargs): + return await app.handle_knowledge_synthesize( + KnowledgeSynthesizeInput( + org="acme", namespace="team", source_uris=[URI], task="Read this", **kwargs + ) + ) + + +async def test_preparation_precedes_budget_and_checked_loader_supplies_counts(world): + result = await synthesize() + assert world.events[:2] == ["prepare", "budget"] + world.loader.assert_awaited_once() + assert world.loader.call_args.args[:3] == (world.plan, "team", [URI]) + assert result.documents == result.windows == result.chunks_read == 1 + assert result.answer == f"Private prose [{URI}#0]" + assert result.cited_chunks[0].source_uri == URI + assert result.cited_chunks[0].revision == 3 and result.cited_chunks[0].locator == {"page": 2} + assert len(world.model.calls) == 2 + assert world.plan.check.await_count == 5 + + +async def test_preparation_also_precedes_a_budget_abstention(world, monkeypatch): + budget = AsyncMock(return_value=True) + monkeypatch.setattr("server.observability.budget.namespace_over_cap", budget) + result = await synthesize() + assert world.events == ["prepare"] and result == app._abstain("budget_capped") + world.loader.assert_not_awaited() + assert not world.model.calls + + +async def test_marked_provider_work_suppresses_public_diagnostics(world): + from server.core.diagnostics import codes_only + from server.observability.genai import current_stage + + async def complete(*_args, **_kwargs): + assert codes_only() + assert current_stage() in {"knowledge_synthesize_map", "knowledge_synthesize_reduce"} + return SimpleNamespace(text="Private uncited prose") + + world.model.complete = complete + assert not (await synthesize()).abstain + + +@pytest.mark.parametrize("boundary", [1, 2, 3, 4, 5]) +async def test_proof_loss_before_or_after_each_provider_and_at_final_output_abstains( + world, boundary +): + admitted = world.plan.check.return_value + world.plan.check.side_effect = [admitted] * (boundary - 1) + [[]] + result = await synthesize() + assert result == app._abstain("no_chunks") + assert len(world.model.calls) == (boundary // 2) + assert world.proofs.invalid + + +async def test_marked_ordinary_only_corpus_keeps_ordinary_fallback(world): + world.loader.return_value = source_corpus.Corpus( + [cs.CorpusChunk("ordinary", 0, "Ordinary")], 1, source_corpus.Proofs(world.plan, ()) + ) + world.plan.failed = True + result = await synthesize() + assert not result.abstain and result.documents == 1 + world.plan.check.assert_not_awaited() + + +async def test_unmarked_corpus_uses_unchanged_ordinary_loader(world, monkeypatch): + world.plan.marked = False + ordinary = AsyncMock(return_value=([cs.CorpusChunk("ordinary", 0, "Ordinary")], 1)) + monkeypatch.setattr(app, "_corpus_chunks", ordinary) + result = await synthesize() + ordinary.assert_awaited_once() + world.loader.assert_not_awaited() + assert not result.abstain and result.documents == 1 + world.plan.check.assert_not_awaited() + + +@pytest.mark.parametrize("failure", ["revoked", "provider", "cancelled"]) +async def test_map_failure_cancels_and_drains_every_owned_sibling(world, failure): + sibling_started, sibling_cancelled = asyncio.Event(), asyncio.Event() + calls = 0 + world.corpus.chunks[:] = [cs.CorpusChunk(URI, idx, "Private" * 300) for idx in range(2)] + + async def complete(system, user, **kwargs): + nonlocal calls + calls += 1 + if calls == 1: + await sibling_started.wait() + if failure == "provider": + raise RuntimeError("provider failed") + if failure == "cancelled": + raise asyncio.CancelledError + world.plan.check.return_value = [] + return SimpleNamespace(text="Private uncited prose") + sibling_started.set() + try: + await asyncio.Event().wait() + finally: + sibling_cancelled.set() + + world.model.complete = complete + if failure == "revoked": + result = await asyncio.wait_for(synthesize(window_chars=2000), timeout=5) + assert result == app._abstain("no_chunks") + else: + error = RuntimeError if failure == "provider" else asyncio.CancelledError + with pytest.raises(error): + await asyncio.wait_for(synthesize(window_chars=2000), timeout=5) + assert sibling_cancelled.is_set() and calls == 2 + + +async def test_reduce_hierarchy_checks_every_provider_await(world): + world.corpus.chunks[:] = [cs.CorpusChunk(URI, i, "x" * 1900) for i in range(3)] + provider_calls = 0 + + async def complete(system, user, **kwargs): + nonlocal provider_calls + provider_calls += 1 + return SimpleNamespace(text="Long note " * 230 if provider_calls <= 3 else "Answer") + + world.model.complete = complete + result = await synthesize(window_chars=2000) + assert not result.abstain and result.reduce_rounds > 1 + assert provider_calls > 4 and world.plan.check.await_count == provider_calls * 2 + 1 diff --git a/tests/unit/test_mirror_escaping_errors.py b/tests/unit/test_mirror_escaping_errors.py new file mode 100644 index 0000000000..d7c417871d --- /dev/null +++ b/tests/unit/test_mirror_escaping_errors.py @@ -0,0 +1,412 @@ +"""Private escapes preserve control flow and are dropped before log formatting.""" + +from __future__ import annotations + +import asyncio +import io +import logging + +import pytest +from anyio import BrokenResourceError, ClosedResourceError, EndOfStream +from fastapi import FastAPI +from starlette.requests import ClientDisconnect + +from server.core import diagnostics, logging_config, request_work +from server.core.request_errors import MarkedRequestError, mark_preserved_error, marked_error +from server.transport.request_scope import HTTPApplication + + +@pytest.fixture(autouse=True) +def isolated_request_state(): + local = request_work._current.set(None) + owner = request_work._http_owner.set(None) + private = diagnostics._codes_only.set(False) + try: + yield + finally: + diagnostics._codes_only.reset(private) + request_work._http_owner.reset(owner) + request_work._current.reset(local) + + +@pytest.mark.asyncio +@pytest.mark.parametrize("marked", [False, True]) +@pytest.mark.parametrize("headers_sent", [False, True]) +async def test_application_error_boundary(monkeypatch, marked, headers_sent): + original = ValueError("private application error canary") + sent = [] + + async def send(message): + sent.append(message) + + async def invoke(self, scope, receive, send): + request_work.begin() + if marked: + assert request_work.mark_mirrored() + if headers_sent: + await send({"type": "http.response.start", "status": 200, "headers": []}) + raise original + + monkeypatch.setattr(FastAPI, "__call__", invoke) + with pytest.raises(MarkedRequestError if marked else ValueError) as caught: + await HTTPApplication()({"type": "http"}, None, send) + assert len(sent) == int(headers_sent) + assert not request_work.http_mirror_marked() + assert request_work.current() is None + if marked: + assert caught.value.args == ("Private request failed",) + assert caught.value.__context__ is original + assert caught.value.__suppress_context__ is True + assert marked_error(caught.value) + else: + assert caught.value is original + assert not marked_error(original) + + +def control_errors(): + return [ + asyncio.CancelledError("private cancellation canary"), + ClientDisconnect("private disconnect canary"), + OSError("private OS canary"), + EndOfStream("private end canary"), + BrokenResourceError("private broken resource canary"), + ClosedResourceError("private closed resource canary"), + ExceptionGroup("private group canary", [ValueError("private leaf canary")]), + BaseExceptionGroup( + "private control group canary", [asyncio.CancelledError("private child canary")] + ), + KeyboardInterrupt("private process canary"), + SystemExit("private exit canary"), + ] + + +@pytest.mark.asyncio +@pytest.mark.parametrize("marked", [False, True]) +@pytest.mark.parametrize("position", range(10)) +async def test_control_and_group_identity(monkeypatch, marked, position): + original = control_errors()[position] + children = original.exceptions if isinstance(original, BaseExceptionGroup) else None + + async def invoke(self, scope, receive, send): + request_work.begin() + if marked: + assert request_work.mark_mirrored() + raise original + + monkeypatch.setattr(FastAPI, "__call__", invoke) + with pytest.raises(type(original)) as caught: + await HTTPApplication()({"type": "http"}, None, None) + assert caught.value is original + if children is not None: + assert caught.value.exceptions is children + assert all(a is b for a, b in zip(caught.value.exceptions, children, strict=True)) + assert marked_error(caught.value) is marked + assert not request_work.http_mirror_marked() + assert request_work.current() is None + assert not marked_error(ValueError("separate ordinary error")) + + +def test_control_marker_bypasses_exception_attribute_overrides(): + class Controlled(OSError): + def __getattribute__(self, name): + if name.startswith("_loom_"): + raise AssertionError("subclass getter must not run") + return super().__getattribute__(name) + + def __setattr__(self, name, value): + raise AssertionError("subclass setter must not run") + + original = Controlled("private control canary") + mark_preserved_error(original) + mark_preserved_error(original) + assert marked_error(original) + + +class CountingFormatter(logging.Formatter): + def __init__(self): + super().__init__("%(message)s") + self.calls = 0 + + def format(self, record): + self.calls += 1 + return super().format(record) + + +@pytest.fixture +def serving_logs(monkeypatch): + names = ("uvicorn", "uvicorn.error", "uvicorn.access", "uvicorn.asgi") + loggers = [logging.getLogger(name) for name in names] + snapshots = [ + ( + logger, + logger.level, + logger.handlers[:], + logger.filters[:], + logger.propagate, + logger.disabled, + ) + for logger in loggers + ] + root_handlers = [*logging.getLogger().handlers, logging.lastResort] + handler_filters = [(handler, handler.filters[:]) for handler in root_handlers if handler] + outputs = {} + try: + for logger in loggers: + stream, formatter = io.StringIO(), CountingFormatter() + handler = logging.StreamHandler(stream) + handler.setFormatter(formatter) + logger.handlers, logger.filters = [handler], [] + logger.propagate, logger.disabled = False, False + logger.setLevel(logging.INFO) + outputs[logger.name] = (logger, stream, formatter) + monkeypatch.setattr(logging_config, "_configured", True) + logging_config.configure_logging() + logging_config.configure_logging() + yield outputs + finally: + for logger, level, handlers, filters, propagate, disabled in snapshots: + for handler in logger.handlers: + if handler not in handlers: + handler.close() + logger.setLevel(level) + logger.handlers, logger.filters = handlers, filters + logger.propagate, logger.disabled = propagate, disabled + for handler, filters in handler_filters: + handler.filters[:] = filters + + +def test_protocol_error_and_access_after_owner_reset(serving_logs): + error, error_stream, error_formatter = serving_logs["uvicorn.error"] + access, access_stream, access_formatter = serving_logs["uvicorn.access"] + original = OSError("private fallback canary") + mark_preserved_error(original) + assert not request_work.http_mirror_marked() + try: + raise original + except OSError: + error.error("protocol error canary", exc_info=True) + access.info("fallback500 access canary") + assert error_stream.getvalue() == access_stream.getvalue() == "" + assert error_formatter.calls == access_formatter.calls == 0 + error.info("ordinary transport control") + access.info("ordinary access control") + assert error_stream.getvalue() == "ordinary transport control\n" + assert access_stream.getvalue() == "ordinary access control\n" + assert error_formatter.calls == access_formatter.calls == 1 + assert error.filters.count(diagnostics.public_log) == 1 + assert access.filters.count(diagnostics.public_log) == 1 + + +def test_exception_record_is_private_outside_caught_exception(serving_logs): + logger, stream, formatter = serving_logs["uvicorn.error"] + original = MarkedRequestError() + original.__cause__ = ValueError("private cause canary") + original.add_note("private note canary") + logger.error("private outcome canary", exc_info=(type(original), original, None)) + assert stream.getvalue() == "" + assert formatter.calls == 0 + + +def test_verbose_asgi_source_is_suppressed_for_ordinary_requests(serving_logs): + logger, stream, formatter = serving_logs["uvicorn.asgi"] + assert not request_work.http_mirror_marked() + for phase in ("Started", "Receive", "Send", "Completed", "Raised exception"): + logger.info("%s private message canary", phase) + assert stream.getvalue() == "" + assert formatter.calls == 0 + assert len(logger.filters) == 1 + + +def test_verbose_filter_preserves_shared_handler_ordinary_logs(serving_logs): + verbose, verbose_stream, verbose_formatter = serving_logs["uvicorn.asgi"] + error, error_stream, error_formatter = serving_logs["uvicorn.error"] + error.addHandler(verbose.handlers[0]) + logging_config.configure_logging() + verbose.info("verbose request message canary") + assert verbose_stream.getvalue() == error_stream.getvalue() == "" + assert verbose_formatter.calls == error_formatter.calls == 0 + error.info("ordinary shared-handler control") + assert ( + verbose_stream.getvalue() == error_stream.getvalue() == "ordinary shared-handler control\n" + ) + assert verbose_formatter.calls == error_formatter.calls == 1 + + +def test_classification_failure_drops_before_formatter(monkeypatch, serving_logs): + from server.core import request_errors + + def unavailable(error): + raise RuntimeError("private classifier failure canary") + + logger, stream, formatter = serving_logs["uvicorn.error"] + monkeypatch.setattr(request_errors, "marked_error", unavailable) + logger.error("private diagnostic canary") + assert stream.getvalue() == "" + assert formatter.calls == 0 + + +class BufferedTransport: + def __init__(self): + self.writes = [] + self.closed = False + + def write(self, data): + self.writes.append(data) + + def close(self): + self.closed = True + + def is_closing(self): + return self.closed + + def pause_reading(self): + pass + + def resume_reading(self): + pass + + +def protocol_cycle(protocol, logs): + import h11 + from uvicorn.protocols.http import h11_impl, httptools_impl + from uvicorn.protocols.http.flow_control import FlowControl + + transport = BufferedTransport() + scope = { + "type": "http", + "asgi": {"version": "3.0", "spec_version": "2.3"}, + "http_version": "1.1", + "method": "GET", + "scheme": "http", + "path": "/canary", + "raw_path": b"/canary", + "root_path": "", + "query_string": b"", + "headers": [(b"host", b"unit.test")], + "client": ("127.0.0.1", 1234), + "server": ("127.0.0.1", 80), + } + arguments = dict( + scope=scope, + transport=transport, + flow=FlowControl(transport), + logger=logs["uvicorn.error"][0], + access_logger=logs["uvicorn.access"][0], + access_log=True, + default_headers=[], + message_event=asyncio.Event(), + on_response=lambda: None, + ) + if protocol == "h11": + connection = h11.Connection(h11.SERVER) + connection.receive_data(b"GET /canary HTTP/1.1\r\nHost: unit.test\r\n\r\n") + assert isinstance(connection.next_event(), h11.Request) + assert isinstance(connection.next_event(), h11.EndOfMessage) + cycle = h11_impl.RequestResponseCycle(conn=connection, **arguments) + else: + cycle = httptools_impl.RequestResponseCycle( + expect_100_continue=False, keep_alive=True, **arguments + ) + return cycle, transport + + +@pytest.mark.asyncio +@pytest.mark.parametrize("protocol", ["h11", "httptools"]) +@pytest.mark.parametrize("marked", [False, True]) +@pytest.mark.parametrize("headers_sent", [False, True]) +@pytest.mark.parametrize( + "error_kind", ["application", "disconnect", "cancel", "group", "controlgroup"] +) +async def test_real_protocol_error_paths( + monkeypatch, serving_logs, protocol, marked, headers_sent, error_kind +): + from uvicorn.logging import TRACE_LOG_LEVEL + from uvicorn.middleware.message_logger import MessageLoggerMiddleware + + errors = { + "application": ValueError("private cycle canary"), + "disconnect": ClientDisconnect("private cycle canary"), + "cancel": asyncio.CancelledError("private cycle canary"), + "group": ExceptionGroup("private cycle canary", [ValueError("private cycle leaf")]), + "controlgroup": BaseExceptionGroup( + "private cycle canary", [asyncio.CancelledError("private cycle leaf")] + ), + } + original = errors[error_kind] + cycle, transport = protocol_cycle(protocol, serving_logs) + error, error_stream, error_formatter = serving_logs["uvicorn.error"] + _access, access_stream, access_formatter = serving_logs["uvicorn.access"] + verbose, verbose_stream, verbose_formatter = serving_logs["uvicorn.asgi"] + observed = [] + emit = error.error + + def observe(message, *args, **kwargs): + observed.append(kwargs["exc_info"]) + emit(message, *args, **kwargs) + + async def invoke(self, scope, receive, send): + request_work.begin() + if marked: + assert request_work.mark_mirrored() + if headers_sent: + await send({"type": "http.response.start", "status": 200, "headers": []}) + raise original + + monkeypatch.setattr(error, "error", observe) + monkeypatch.setattr(FastAPI, "__call__", invoke) + monkeypatch.setattr(verbose, "trace", getattr(verbose, "trace", None), raising=False) + verbose.setLevel(TRACE_LOG_LEVEL) + await cycle.run_asgi(MessageLoggerMiddleware(HTTPApplication())) + assert len(observed) == 1 + if marked and error_kind == "application": + assert isinstance(observed[0], MarkedRequestError) + assert observed[0].__context__ is original + else: + assert observed[0] is original + assert not request_work.http_mirror_marked() + assert request_work.current() is None + wire = b"".join(transport.writes) + assert wire.startswith(b"HTTP/1.1 200" if headers_sent else b"HTTP/1.1 500") + assert b"private cycle" not in wire + assert transport.closed + if marked: + assert error_stream.getvalue() == access_stream.getvalue() == "" + assert error_formatter.calls == access_formatter.calls == 0 + else: + assert "private cycle canary" in error_stream.getvalue() + assert error_formatter.calls == access_formatter.calls == 1 + assert verbose_stream.getvalue() == "" + assert verbose_formatter.calls == 0 + + +@pytest.mark.asyncio +@pytest.mark.parametrize("protocol", ["h11", "httptools"]) +@pytest.mark.parametrize("marked", [False, True]) +async def test_real_protocol_success_suppresses_completed_trace( + monkeypatch, serving_logs, protocol, marked +): + from uvicorn.logging import TRACE_LOG_LEVEL + from uvicorn.middleware.message_logger import MessageLoggerMiddleware + + cycle, transport = protocol_cycle(protocol, serving_logs) + verbose, verbose_stream, verbose_formatter = serving_logs["uvicorn.asgi"] + + async def invoke(self, scope, receive, send): + request_work.begin() + if marked: + assert request_work.mark_mirrored() + await send({"type": "http.response.start", "status": 200, "headers": []}) + await send({"type": "http.response.body", "body": b"constant", "more_body": False}) + + monkeypatch.setattr(FastAPI, "__call__", invoke) + monkeypatch.setattr(verbose, "trace", getattr(verbose, "trace", None), raising=False) + verbose.setLevel(TRACE_LOG_LEVEL) + await cycle.run_asgi(MessageLoggerMiddleware(HTTPApplication())) + assert cycle.response_complete + assert b"constant" in b"".join(transport.writes) + assert not request_work.http_mirror_marked() + assert verbose_stream.getvalue() == "" + assert verbose_formatter.calls == 0 + _access, stream, formatter = serving_logs["uvicorn.access"] + assert formatter.calls == int(not marked) + assert bool(stream.getvalue()) is not marked diff --git a/tests/unit/test_mirror_event_marker.py b/tests/unit/test_mirror_event_marker.py new file mode 100644 index 0000000000..b699548bc9 --- /dev/null +++ b/tests/unit/test_mirror_event_marker.py @@ -0,0 +1,137 @@ +"""The ledger captures the logical mark before a writer consumes the row.""" + +from __future__ import annotations + +from contextlib import nullcontext +from types import SimpleNamespace + +import pytest + +from server.auth import tenancy +from server.core import request_tail, request_work +from server.core.diagnostics import private_work +from server.identity.app import policy_witness +from server.identity.domain.policy_rules import PolicyRule +from server.observability import cost_accumulator, events, ledger + + +@pytest.mark.asyncio +@pytest.mark.parametrize("marked", [False, True]) +@pytest.mark.parametrize("held", [False, True]) +@pytest.mark.parametrize("private", [False, True]) +async def test_logical_mark_reaches_normal_and_waited_event_rows( + monkeypatch, marked, held, private +): + rows = [] + queued = [] + rules = [ + PolicyRule.model_validate( + { + "policy_id": "prior-call", + "effect": "require", + "actions": ["memory.set"], + "condition": { + "op": "formerly", + "operation": ["knowledge.get"], + "within": "1h", + }, + } + ) + ] + + async def load_rules(org, namespace): + assert (org, namespace) == ("org-a", "team") + return rules + + async def write(table, row): + assert table == "loom.agent_events" + rows.append(row) + + async def insert(table, data, *, settings, required_columns): + assert table == "loom.agent_events_private" + assert required_columns == frozenset({"mirror_marked"}) + assert settings["async_insert"] == settings["wait_for_async_insert"] == 1 + rows.extend(data) + + def queue(event): + queued.append(event) + rows.append(event.to_row()) + + monkeypatch.setattr(tenancy, "attributable", lambda org: True) + monkeypatch.setattr(events, "get_client", lambda: SimpleNamespace(insert=insert)) + monkeypatch.setattr(events, "stamp_row", lambda row: row) + monkeypatch.setattr(events, "for_this_cell", lambda event: event) + monkeypatch.setattr(policy_witness, "_policies_on", lambda: True) + monkeypatch.setattr(policy_witness, "_rules", load_rules) + monkeypatch.setattr(policy_witness, "_write", write) + monkeypatch.setattr(ledger, "get_emitter", lambda: SimpleNamespace(emit=queue)) + monkeypatch.setattr(ledger, "_event_hold", policy_witness.hold_event if held else None) + monkeypatch.setattr( + cost_accumulator, + "current", + lambda: SimpleNamespace( + cost_usd=0.125, + embed_tokens=13, + llm_input_tokens=17, + llm_output_tokens=19, + llm_calls=2, + dominant_model=lambda: "test-model", + ), + ) + local_token = request_work._current.set(None) + tail = request_tail._Tail() + tail_token = request_tail._tail.set(tail) + try: + request_work.begin() + if marked: + assert request_work.mark_mirrored() + with private_work() if private else nullcontext(): + ledger.emit_agent_event( + op_name="knowledge.get", + identity={ + "org": "org-a", + "namespace": "team", + "agent": "reader", + "user_id": "user-a", + "session_id": "session-a", + }, + request_id="request-a", + latency_ms=23, + success=True, + error_code="", + # A caller cannot classify its own row, in either direction. + raw_args={"mirror_marked": not marked}, + subject="subject-a", + consumer="test-client", + traffic_class="interactive", + ) + if held or marked: + assert rows == [] + request_work.begin() + assert not request_work.mirror_marked() + await request_tail.settle(tail) + assert len(rows) == 1 + assert len(queued) == (0 if held or marked else 1) + row = rows[0] + assert row.get("mirror_marked", 0) == int(marked) + assert type(row.get("mirror_marked", 0)) is int + assert row["org"] == "org-a" + assert row["namespace"] == "team" + assert row["agent"] == "reader" + assert row["user_id"] == "user-a" + assert row["session_id"] == "session-a" + assert row["subject"] == "subject-a" + assert row["request_id"] == "request-a" + assert row["operation"] == "knowledge.get" + assert row["latency_ms"] == 23 + assert row["success"] is True + assert row["upstream_cost_usd"] == 0.125 + assert row["embedding_tokens"] == 13 + assert row["input_tokens"] == 17 + assert row["output_tokens"] == 19 + assert row["model"] == "test-model" + assert row["llm_calls"] == 2 + assert "mirror_marked" not in row["args"] + finally: + request_tail._tail.reset(tail_token) + request_work._current.reset(local_token) diff --git a/tests/unit/test_mirror_latch.py b/tests/unit/test_mirror_latch.py new file mode 100644 index 0000000000..b417172856 --- /dev/null +++ b/tests/unit/test_mirror_latch.py @@ -0,0 +1,153 @@ +"""A negative deployment decision needs fresh, same-backend ordered evidence.""" + +from __future__ import annotations + +import asyncio + +import pytest + +from server.core import request_work +from server.core.ch import current_query_tag, query_tag, statement_settings +from server.knowledge.store import mirror_latch as store +from tests.unit.mirror_latch_fake import A, B, KeeperWorld + + +async def test_an_absent_latch_is_never_a_cached_negative_decision(): + world = KeeperWorld() + assert not await store.enabled(ch=world) + assert not world.leases and world.counts["barrier"] == 1 + # Another process enables after the first decision; this follower has not seen it. + world.enabled = True + assert await store.enabled(ch=world) + assert not world.leases and world.counts["barrier"] == 2 + + +async def test_known_positive_latch_needs_no_barrier_or_cleanup(): + world = KeeperWorld(enabled=True, visible=True) + assert await store.enabled(ch=world) + assert world.calls == ["engines", "latch"] and not world.leases + + +@pytest.mark.parametrize( + "stage, occurrence", [("latch", 1), ("latch", 2), ("keeper", 2), ("nonce", 1), ("nonce", 2)] +) +async def test_every_read_attests_its_backend_even_when_the_latch_or_nonce_is_empty( + stage, occurrence +): + world = KeeperWorld() + world.routes[stage, occurrence] = B + with pytest.raises( + store.LatchUnavailable, match="^Session protection state could not be confirmed$" + ): + await store.enabled(ch=world) + assert not world.leases + + +async def test_write_on_another_bootstrap_backend_cannot_pass_an_a_b_a_read_sequence(): + world = KeeperWorld(enabled=True) + world.routes["barrier", 1] = B + with pytest.raises(store.LatchUnavailable): + await store.enabled(ch=world) + assert not world.visible[A] and world.visible[B] + assert world.counts["nonce"] == 1 and not world.leases + + +@pytest.mark.parametrize( + "fault", + [ + "wrong_engine", + "wrong_ensemble", + "wrong_primary_key", + "missing_keeper", + "expired_keeper", + "keeper_replaced", + "expired_nonce", + "latch_backend_error", + "ambiguous_write", + ], +) +async def test_uncertain_or_changed_evidence_never_authorizes_an_absence(fault): + world = KeeperWorld() + world.fault = fault + with pytest.raises( + store.LatchUnavailable, match="^Session protection state could not be confirmed$" + ): + await store.enabled(ch=world) + assert not world.leases + + +async def test_a_duplicate_barrier_is_not_accepted_and_foreign_ownership_is_preserved(): + world = KeeperWorld() + world.fault = "foreign_duplicate" + with pytest.raises(store.LatchUnavailable): + await store.enabled(ch=world) + assert len(world.leases) == 1 + assert next(iter(world.leases.values()))[0] == "foreign-holder" + assert world.counts["nonce"] == 0 + + +async def test_cleanup_failure_cannot_turn_an_unlatched_read_into_admission(): + world = KeeperWorld() + world.fault = "cleanup_error" + with pytest.raises(store.LatchUnavailable): + await store.enabled(ch=world) + assert len(world.leases) == 1 and world.counts["release"] == 2 + + +async def test_cancellation_after_commit_cleans_only_the_own_key_and_stays_cancellation(): + world = KeeperWorld() + world.fault = "cancelled_write" + with pytest.raises(asyncio.CancelledError): + await store.enabled(ch=world) + assert not world.leases and world.counts["release"] == 1 + + +@pytest.mark.parametrize("racing", [False, True]) +async def test_positive_enablement_is_confirmed_without_a_negative_barrier(racing): + world = KeeperWorld() + world.fault = "racing_set" if racing else "" + await store.ensure(ch=world) + assert world.enabled and world.visible[A] + assert world.counts["set"] == 1 and not world.counts["barrier"] + await store.ensure(ch=world) + assert world.counts["set"] == 2 + + +async def test_enablement_after_an_erasure_does_not_trust_a_followers_stale_positive(): + world = KeeperWorld(enabled=False, visible=True) + await store.ensure(ch=world) + assert world.enabled and world.counts["set"] == 1 + + +@pytest.mark.parametrize("operation", [store.enabled, store.ensure]) +@pytest.mark.parametrize("outcome", ["success", "refusal", "cancelled"]) +async def test_admission_restores_the_callers_query_tag_after_every_exit(operation, outcome): + class CancelledWorld(KeeperWorld): + async def query_one(self, sql, params=None): + raise asyncio.CancelledError() + + world = CancelledWorld() if outcome == "cancelled" else KeeperWorld() + if outcome == "refusal": + world.fault = "wrong_engine" + with request_work.http_owner({}), query_tag("memory.search caller-request-id"): + request_work.begin() + if outcome == "success": + await operation(ch=world) + else: + error = asyncio.CancelledError if outcome == "cancelled" else store.LatchUnavailable + with pytest.raises(error): + await operation(ch=world) + assert current_query_tag() == "memory.search caller-request-id" + following = statement_settings("SELECT 42") + assert following["log_comment"] == "memory.search caller-request-id" + assert following["query_id"].startswith("caller-request-id:") + + +async def test_positive_repair_refuses_a_write_routed_away_from_the_validated_store(): + world = KeeperWorld(enabled=False, visible=True) + # Both metadata reads and the stale positive stay on A; only SET reaches drifted B. + world.routes["set", 1] = B + world.detached_stores.add(B) + with pytest.raises(store.LatchUnavailable): + await store.ensure(ch=world) + assert not world.enabled diff --git a/tests/unit/test_mirror_mentor_advice.py b/tests/unit/test_mirror_mentor_advice.py new file mode 100644 index 0000000000..fa5e06b62a --- /dev/null +++ b/tests/unit/test_mirror_mentor_advice.py @@ -0,0 +1,101 @@ +"""Private calls leave mentor advice and its deferred profile work untouched.""" + +from __future__ import annotations + +import contextvars +from contextlib import contextmanager +from types import SimpleNamespace + +import pytest + +from server.core import diagnostics, request_work +from server.insights.app import mentor +from server.settings import settings + + +@pytest.fixture +def world(monkeypatch): + inspected, warmed, evaluated = [], [], [] + + class Result: + def model_dump(self): + inspected.append("result") + return {"content": "PRIVATE-CONTENT"} + + def rule(op, arguments, result, facts, state): + evaluated.append((op, arguments, result)) + return "test-advice", "Use the ordinary advice" + + monkeypatch.setattr(settings, "mentor_ttl_seconds", 3600) + monkeypatch.setattr(settings, "mentor_max_hints_per_session", 10) + monkeypatch.setattr(mentor, "_cache", {}) + monkeypatch.setattr(mentor, "_sessions", {}) + monkeypatch.setattr(mentor, "_profile_shown", {}) + monkeypatch.setattr(mentor, "CALL_RULES", (rule,)) + monkeypatch.setattr(mentor, "warm_profile", lambda *identity: warmed.append(identity)) + + def call(): + return mentor.call_hint( + "knowledge.get", + {"document_id": "PRIVATE-ID"}, + Result(), + session_key="session-a", + org="org-a", + namespace="team-a", + agent="reader", + clock=lambda: 100.0, + ) + + return SimpleNamespace(call=call, inspected=inspected, warmed=warmed, evaluated=evaluated) + + +@contextmanager +def privacy(kind): + if kind == "private": + with diagnostics.private_work(): + yield + elif kind == "http_owner": + with request_work.http_owner({"type": "http"}): + request_work.begin() + assert request_work.mark_mirrored() + request_work.begin() + assert not request_work.mirror_marked() and request_work.http_mirror_marked() + yield + else: + yield + + +@pytest.mark.parametrize("kind", ["ordinary", "private", "http_owner"]) +@pytest.mark.parametrize("cached", [False, True]) +def test_mentor_never_inspects_or_warms_private_request_advice(world, kind, cached): + if cached: + profile = SimpleNamespace(facts={}, hints=(), hint=lambda code: None) + mentor._cache[("org-a", "team-a", "reader")] = (1000.0, profile) + original_cache = dict(mentor._cache) + + def exercise(): + with privacy(kind): + result = world.call() + if kind == "ordinary": + assert result == ("test-advice", "Use the ordinary advice") + assert world.inspected == ["result"] and len(world.evaluated) == 1 + assert world.warmed == ([] if cached else [("org-a", "team-a", "reader")]) + assert mentor._sessions["session-a"]["shown"] == {"test-advice"} + assert mentor._sessions["session-a"]["count"] == 1 + else: + assert result is None + assert world.inspected == world.evaluated == world.warmed == [] + assert mentor._sessions == mentor._profile_shown == {} + assert mentor._cache == original_cache + + contextvars.copy_context().run(exercise) + + +def test_unavailable_privacy_decision_drops_advice_before_any_state_change(monkeypatch, world): + def unavailable(): + raise RuntimeError("private classification unavailable") + + monkeypatch.setattr(request_work, "http_mirror_marked", unavailable) + assert world.call() is None + assert world.inspected == world.evaluated == world.warmed == [] + assert mentor._cache == mentor._sessions == mentor._profile_shown == {} diff --git a/tests/unit/test_mirror_names_refused.py b/tests/unit/test_mirror_names_refused.py index 3629425316..f672c718ed 100644 --- a/tests/unit/test_mirror_names_refused.py +++ b/tests/unit/test_mirror_names_refused.py @@ -353,7 +353,8 @@ async def test_the_admin_ledger_reads_leave_out_a_mirror_s_rows() -> None: stmt for ns in ("team", MIRROR) for stmt in ( - "INSERT INTO loom.agent_events (ts, org, namespace, operation, kind)" + f"INSERT INTO loom.{'agent_events_private' if ns == MIRROR else 'agent_events'} " + "(ts, org, namespace, operation, kind)" f" VALUES (now64(3), 'o', '{ns}', 'memory.get', 'request')", "INSERT INTO loom.audit_log (ts, org, namespace, event_type)" f" VALUES (now64(3), 'o', '{ns}', 'e')", @@ -366,7 +367,7 @@ async def test_the_admin_ledger_reads_leave_out_a_mirror_s_rows() -> None: f" VALUES (now(), 'o', '{ns}', 'agent', 'opened_file')" for ns in ("team", MIRROR) ] - tables = ("agent_events", "audit_log", "events", "code_search_outcome") + tables = ("agent_events", "agent_events_private", "audit_log", "events", "code_search_outcome") ch = LocalCH(*(local_ddl(t) for t in tables), *rows) tail = await admin_store.events_tail(3600, 10, ch=ch) assert {r["namespace"] for r in tail} == {"team"} diff --git a/tests/unit/test_mirror_policy_enforcement.py b/tests/unit/test_mirror_policy_enforcement.py new file mode 100644 index 0000000000..a7674b17ed --- /dev/null +++ b/tests/unit/test_mirror_policy_enforcement.py @@ -0,0 +1,203 @@ +"""Protected UNKNOWN fails closed without changing ordinary backend-error reads.""" + +from __future__ import annotations + +from types import SimpleNamespace + +import pytest + +from server.auth import context as auth_context +from server.core import ch as ch_core +from server.identity.api.models_policy import PolicyCheckInput +from server.identity.app import history_policy, history_policy_ops, policy_gate +from server.identity.domain import policy_rules as rules +from server.observability import events +from server.operations.registry import ALL_OPERATIONS +from server.settings import settings + +_REASON = "protected history unavailable" +_IDENTITY = dict(org="acme", namespace="docs", agent="reader", user_id="person", session_id="run") +_MODES = [ + ("enforce", "inherit", True), + ("enforce", "shadow", False), + ("off", "enforce", False), + ("shadow", "enforce", True), +] + + +def rule(mode="inherit", *, breadth=False, unresolved=False): + leaf = dict(op="count_within", within="1h", operation=["knowledge.search"], cmp="lt", value=2) + if breadth: + leaf = dict(op="breadth_within", within="1h", key="actor", cmp="lt", value=2) + if unresolved: + leaf["args_equal"] = {"source_uri": "$args.source_uri"} + return rules.PolicyRule( + policy_id="guard", + effect="require", + actions=["memory.get", "memory.set"], + condition=leaf, + mode=mode, + ) + + +class History: + def __init__(self, *, marked=False, rows=None, error=False): + self.rows = [dict(protected_history=int(marked), n=1, total=2)] if rows is None else rows + self.error = error + self.calls = [] + + async def query_all(self, sql, params): + self.calls.append((sql, dict(params))) + if self.error: + raise ValueError("history backend unavailable") + return self.rows + + +def call_context(): + return rules.CallContext(**_IDENTITY, operation="memory.get") + + +@pytest.mark.parametrize( + "rows", + [ + [], + [{}], + [None], + [dict(n=1)], + [dict(protected_history=None, n=1)], + [dict(protected_history="0", n=1)], + [dict(protected_history=0.0, n=1)], + [dict(protected_history=2, n=1)], + [dict(protected_history=0, n=1), dict(protected_history=0, n=1)], + ], +) +async def test_unverifiable_participation_is_unknown_before_reading_any_outcome(rows): + ch = History(rows=rows) + result = await history_policy.evaluate_rule(rule(), call_context(), ch) + assert result.holds is None and result.denies is False + assert result.errors == [_REASON] + assert result.leaves[0].value is None and result.leaves[0].error == _REASON + assert len(ch.calls) == 1 + + +@pytest.mark.parametrize("marked", [False, True]) +@pytest.mark.parametrize("negate", [False, True]) +async def test_missing_argument_still_checks_coarse_participation_before_ordinary_false( + marked, negate +): + candidate = rule(unresolved=True) + if negate: + candidate = candidate.model_copy( + update={"condition": rules.Not(op="not", of=candidate.condition)} + ) + ch = History(marked=marked) + result = await history_policy.evaluate_rule(candidate, call_context(), ch) + assert len(ch.calls) == 1 + if marked: + assert result.holds is None and result.denies is False + assert result.errors == [_REASON] and result.leaves[0].value is None + else: + assert result.holds is negate and result.denies is (not negate) + assert result.errors == [] + assert result.leaves[0].skipped == "args reference unresolved" + assert result.leaves[0].value is None + + +@pytest.fixture +def gate_world(monkeypatch): + records = [] + state = SimpleNamespace(candidate=rule(), mode="enforce", records=records) + + async def rules_for(*_args, **_kwargs): + return [state.candidate] + + monkeypatch.setattr(policy_gate, "_mode", lambda: state.mode) + monkeypatch.setattr(history_policy, "rules_for", rules_for) + monkeypatch.setattr(policy_gate, "_record", lambda **kwargs: records.append(kwargs)) + return state + + +@pytest.mark.parametrize("operation", ["memory.get", "memory.set"]) +@pytest.mark.parametrize("deployment,mode,blocks", _MODES) +async def test_protected_unknown_blocks_every_enforcing_operation_only( + gate_world, operation, deployment, mode, blocks +): + gate_world.candidate = rule(mode) + gate_world.mode = deployment + op = next(op for op in ALL_OPERATIONS if op.name == operation) + ch = History(marked=True) + if deployment == "off": + assert await policy_gate.gate(op, _IDENTITY, None, ch=ch) is None + assert ch.calls == [] and gate_world.records == [] + return + if blocks: + with pytest.raises(policy_gate.PolicyForbiddenError, match=_REASON): + await policy_gate.gate(op, _IDENTITY, None, ch=ch) + else: + decision = await policy_gate.gate(op, _IDENTITY, None, ch=ch) + assert decision.errors == [_REASON] + assert len(ch.calls) == 1 and len(gate_world.records) == 1 + assert gate_world.records[0]["enforced"] is blocks + assert gate_world.records[0]["decision"].errors == [_REASON] + + +@pytest.mark.parametrize("operation", ["memory.get", "memory.set"]) +@pytest.mark.parametrize("deployment,mode,_blocks", _MODES) +async def test_unmarked_history_keeps_normal_gate_behavior( + gate_world, operation, deployment, mode, _blocks +): + gate_world.candidate = rule(mode) + gate_world.mode = deployment + op = next(op for op in ALL_OPERATIONS if op.name == operation) + ch = History() + if deployment == "off": + assert await policy_gate.gate(op, _IDENTITY, None, ch=ch) is None + assert ch.calls == [] and gate_world.records == [] + return + decision = await policy_gate.gate(op, _IDENTITY, None, ch=ch) + assert decision.errors == [] and decision.decision == "allow" + assert len(ch.calls) == 1 and gate_world.records[0]["enforced"] is False + + +@pytest.mark.parametrize("operation,blocks", [("memory.get", False), ("memory.set", True)]) +async def test_ordinary_backend_error_keeps_existing_read_and_write_posture( + gate_world, operation, blocks +): + op = next(op for op in ALL_OPERATIONS if op.name == operation) + ch = History(error=True) + if blocks: + with pytest.raises(policy_gate.PolicyForbiddenError): + await policy_gate.gate(op, _IDENTITY, None, ch=ch) + else: + decision = await policy_gate.gate(op, _IDENTITY, None, ch=ch) + assert decision.errors and _REASON not in decision.errors + assert len(ch.calls) == 1 and gate_world.records[0]["enforced"] is blocks + + +@pytest.mark.parametrize("operation", ["memory.get", "memory.set"]) +@pytest.mark.parametrize("mode", ["enforce", "shadow"]) +@pytest.mark.parametrize("marked", [False, True]) +async def test_policy_check_pins_breadth_to_verified_subject_and_matches_protected_enforcement( + monkeypatch, operation, mode, marked +): + ch = History(marked=marked) + flushed = [] + + async def flush_now(): + flushed.append(True) + + monkeypatch.setattr(ch_core, "get_client", lambda: ch) + monkeypatch.setattr(events, "get_emitter", lambda: SimpleNamespace(flush_now=flush_now)) + monkeypatch.setattr(auth_context, "current_auth", lambda: SimpleNamespace(subject="verified")) + monkeypatch.setattr(settings, "policy_mode", "enforce") + output = await history_policy_ops.handle_policy_check( + PolicyCheckInput( + **_IDENTITY, operation=operation, rules=[rule(mode, breadth=True).model_dump()] + ) + ) + expected = marked and mode == "enforce" + assert output.would_enforce is expected + assert output.decision == ("deny" if expected else "allow") + assert output.errors == ([_REASON] if marked else []) + assert len(ch.calls) == 1 and ch.calls[0][1]["p_actor"] == "verified" + assert flushed == [True] diff --git a/tests/unit/test_mirror_policy_unknown.py b/tests/unit/test_mirror_policy_unknown.py new file mode 100644 index 0000000000..3114e634a6 --- /dev/null +++ b/tests/unit/test_mirror_policy_unknown.py @@ -0,0 +1,100 @@ +"""Protected history is UNKNOWN before outcomes or negation are evaluated.""" + +from __future__ import annotations + +from datetime import datetime + +import pytest + +from server.identity.app import history_policy +from server.identity.domain import policy_rules as rules + +_REASON = "protected history unavailable" +_NOW = datetime(2030, 1, 1, 12) + + +def context(): + return rules.CallContext( + org="acme", + namespace="docs", + agent="reader", + user_id="person", + session_id="session", + operation="memory.get", + actor="subject", + now=_NOW, + ) + + +def condition(kind, negate): + if kind == "breadth_within": + leaf = dict(op=kind, within="1h", key="actor", cmp="lt", value=2) + else: + leaf = dict( + op=kind, + within="1h", + operation=["knowledge.search"], + key="user", + success=True, + args_equal={"source_uri": "requested-document"}, + ) + if kind == "count_within": + leaf.update(cmp="lt", value=2) + elif kind == "not_since": + leaf["anchor"] = ["memory.set"] + return dict(op="not", of=leaf) if negate else leaf + + +class HistoryRows: + def __init__(self, protected, *, alternative=False): + self.protected = protected + self.alternative = alternative + self.calls = [] + + async def query_all(self, sql, params): + self.calls.append((sql, dict(params))) + return [ + dict( + protected_history=self.protected, + n=999 if self.alternative else 1, + total=1000 if self.alternative else 2, + anchor_ts=None if self.alternative else _NOW, + left_ts=_NOW if self.alternative else None, + ) + ] + + +@pytest.mark.parametrize("kind", ["formerly", "count_within", "not_since", "breadth_within"]) +@pytest.mark.parametrize("effect", ["require", "forbid"]) +@pytest.mark.parametrize("negate", [False, True]) +async def test_protected_history_never_exposes_a_value_or_becomes_true_under_negation( + kind, effect, negate +): + rule = rules.PolicyRule( + policy_id="guard", effect=effect, actions=["memory.get"], condition=condition(kind, negate) + ) + for alternative in (False, True): + ch = HistoryRows(True, alternative=alternative) + result = await history_policy.evaluate_rule(rule, context(), ch) + assert result.holds is None + assert result.denies is False + assert result.errors == [_REASON] + assert len(result.leaves) == 1 + assert result.leaves[0].value is None and result.leaves[0].error == _REASON + assert len(ch.calls) == 1 + + +@pytest.mark.parametrize("kind", ["formerly", "count_within", "not_since", "breadth_within"]) +@pytest.mark.parametrize("effect", ["require", "forbid"]) +@pytest.mark.parametrize("negate", [False, True]) +async def test_unmarked_history_retains_ordinary_predicates(kind, effect, negate): + rule = rules.PolicyRule( + policy_id="guard", effect=effect, actions=["memory.get"], condition=condition(kind, negate) + ) + ch = HistoryRows(False) + result = await history_policy.evaluate_rule(rule, context(), ch) + assert result.holds is (not negate) + assert result.denies is ((not negate) if effect == "forbid" else negate) + assert result.errors == [] and result.leaves[0].error == "" + assert result.leaves[0].value is not None + assert len(ch.calls) == 1 diff --git a/tests/unit/test_mirror_publication_batch.py b/tests/unit/test_mirror_publication_batch.py new file mode 100644 index 0000000000..b616222d72 --- /dev/null +++ b/tests/unit/test_mirror_publication_batch.py @@ -0,0 +1,357 @@ +"""A buffered batch never publishes a checked reply after a later entry waits.""" + +from __future__ import annotations + +import asyncio +import json +from types import SimpleNamespace + +import pytest + +from server.core import request_tail, request_work +from server.transport import mcp + + +def request(index, method="tools/call"): + return {"jsonrpc": "2.0", "id": index, "method": method} + + +def frame(index, body): + return { + "jsonrpc": "2.0", + "id": index, + "result": { + "content": [{"type": "text", "text": json.dumps(body)}], + "structuredContent": body, + "isError": False, + }, + } + + +@pytest.fixture +def bag(): + tail = request_tail._Tail() + token = request_tail._tail.set(tail) + try: + with request_work.http_owner({"type": "http"}): + request_work.begin() + yield SimpleNamespace(tail=tail) + finally: + request_tail._tail.reset(token) + + +@pytest.mark.parametrize("position", [0, 1, 2]) +async def test_every_marked_batch_position_has_one_constant_refusal(bag, position): + replies = [] + for body in ( + {"title": "CHECKED-TITLE", "content": "CHECKED-CONTENT", "cursor": "CHECKED-CURSOR"}, + {"results": [], "stale_dropped": 0}, + {"found": False}, + ): + + async def dispatch(entry, selected=body): + index = entry["id"] + request_work.begin() + if index == position: + assert request_work.mark_mirrored() + return frame(index, selected) + # In a real batch this could be a second provider or a write. It + # runs after the earlier tool's last access check and before send. + await asyncio.sleep(0) + return frame(index, {"ordinary": index}) + + output = await mcp._dispatch_batch([request(i) for i in range(3)], dispatch) + assert [entry["id"] for entry in output] == [0, 1, 2] + marked = output[position] + assert "error" in marked or marked.get("result", {}).get("isError") is True + assert "CHECKED-" not in json.dumps(marked) + for i in range(3): + if i != position: + assert output[i] == frame(i, {"ordinary": i}) + replies.append(marked) + assert replies[0] == replies[1] == replies[2] + + +async def test_one_entry_array_keeps_the_checked_answer(bag): + expected = frame(1, {"content": "CHECKED-CONTENT"}) + + async def dispatch(_entry): + request_work.begin() + assert request_work.mark_mirrored() + return expected + + assert await mcp._dispatch_batch([request(1)], dispatch) == [expected] + + +async def test_a_later_early_return_does_not_inherit_the_previous_entry_mark(bag): + seen = [] + + async def dispatch(entry): + if entry["method"] == "tools/call": + request_work.begin() + assert request_work.mark_mirrored() + return frame(1, {"content": "CHECKED-CONTENT"}) + # A ping/invalid shape can return before the tool's begin_call runs. + seen.append(request_work.mirror_marked()) + return {"jsonrpc": "2.0", "id": 2, "result": {}} + + output = await mcp._dispatch_batch([request(1), request(2, "ping")], dispatch) + assert seen == [False] + assert output[1] == {"jsonrpc": "2.0", "id": 2, "result": {}} + assert not request_work.mirror_marked() + assert request_work.http_mirror_marked(), "the HTTP owner retains the batch mark" + + +async def test_a_later_ordinary_tool_cannot_clear_the_outer_batch_mark(bag): + async def dispatch(entry): + request_work.begin() + if entry["id"] == 1: + assert request_work.mark_mirrored() + return frame(entry["id"], {"ordinary": entry["id"]}) + + await mcp._dispatch_batch([request(1), request(2)], dispatch) + assert not request_work.mirror_marked() + assert request_work.http_mirror_marked() + + +async def test_zero_mirror_batch_keeps_frames_notifications_and_body_fields(bag): + ordinary = frame(1, {"mirrored": True, "content": "a caller-controlled ordinary field"}) + refusal = {"jsonrpc": "2.0", "id": 3, "error": {"code": -32600, "message": "invalid"}} + + async def dispatch(entry): + if "id" not in entry: + return None + return ordinary if entry["id"] == 1 else refusal + + output = await mcp._dispatch_batch( + [request(1), {"jsonrpc": "2.0", "method": "notifications/initialized"}, request(3)], + dispatch, + ) + assert output == [ordinary, refusal] + assert not request_work.mirror_marked() + + +async def test_marked_refusal_is_identical_across_batch_positions(bag): + replies = [] + for position in range(3): + + async def dispatch(entry, selected=position): + request_work.begin() + if entry["id"] == selected: + assert request_work.mark_mirrored() + return frame(entry["id"], {"content": "CHECKED-CONTENT"}) + + output = await mcp._dispatch_batch([request(i) for i in range(3)], dispatch) + marked = {**output[position], "id": "same-id"} + assert "error" in marked or marked.get("result", {}).get("isError") is True + assert "CHECKED-CONTENT" not in json.dumps(marked) + replies.append(marked) + assert replies[0] == replies[1] == replies[2] + + +@pytest.mark.parametrize("notification", [False, True]) +async def test_required_entry_commit_precedes_the_next_call_without_ordinary_cleanup( + bag, notification +): + committed, ordinary = [], [] + + async def commit(index): + committed.append(index) + + async def later(): + ordinary.append("ordinary") + + async def dispatch(entry): + index = entry.get("id", 1) + if index == 2: + assert committed == [1] + assert ordinary == [] and request_tail.required_active() + assert not request_work.mirror_marked() + assert request_work.mark_mirrored() + assert request_tail.defer_required(lambda: commit(index)) + if index == 1: + assert request_tail.defer(later) + return frame(index, {"content": "CHECKED-CONTENT"}) if "id" in entry else None + + first = request(1) + if notification: + first.pop("id") + result = await mcp._dispatch_batch([first, request(2)], dispatch) + assert committed == [1, 2] and ordinary == [] + assert request_tail.required_active() and not bag.tail.closed + assert len(result) == (1 if notification else 2) + assert all("CHECKED-CONTENT" not in json.dumps(reply) for reply in result) + await request_tail.settle(bag.tail) + await request_tail.settle(bag.tail) + assert committed == [1, 2] and ordinary == ["ordinary"] + + +async def test_required_entry_failure_prevents_the_next_dispatch_and_stays_fatal(bag): + visited, attempts, ordinary = [], [], [] + + async def broken(): + attempts.append("required") + raise RuntimeError("private insert detail") + + async def cleanup(): + ordinary.append("ordinary") + + async def dispatch(entry): + visited.append(entry["id"]) + if entry["id"] == 1: + assert request_work.mark_mirrored() + assert request_tail.defer_required(broken) + assert request_tail.defer(cleanup) + return frame(entry["id"], {"content": "CHECKED-CONTENT"}) + + with pytest.raises(request_tail.RequiredTailError) as failed: + await mcp._dispatch_batch([request(1), request(2)], dispatch) + assert "private insert detail" not in str(failed.value) + assert visited == [1] and attempts == ["required"] and ordinary == [] + assert bag.tail.required_failed and not request_tail.required_active() + with pytest.raises(request_tail.RequiredTailError): + await request_tail.settle(bag.tail) + assert attempts == ["required"] and ordinary == ["ordinary"] + + +async def test_ordinary_entries_keep_deferred_work_until_final_settlement(bag): + ordinary = [] + + async def cleanup(): + ordinary.append("ordinary") + + async def dispatch(entry): + assert ordinary == [] and not request_work.mirror_marked() + if entry["id"] == 1: + assert request_tail.defer(cleanup) + return frame(entry["id"], {"ordinary": entry["id"]}) + + expected = [frame(index, {"ordinary": index}) for index in (1, 2)] + assert await mcp._dispatch_batch([request(1), request(2)], dispatch) == expected + assert ordinary == [] + await request_tail.settle(bag.tail) + assert ordinary == ["ordinary"] + + +async def test_cancelled_entry_drain_joins_its_commit_before_propagating(bag): + entered, release = asyncio.Event(), asyncio.Event() + committed, later_entries = [], [] + + async def commit(): + entered.set() + await release.wait() + committed.append("required") + + async def dispatch(entry): + if entry["id"] == 1: + assert request_work.mark_mirrored() + assert request_tail.defer_required(commit) + else: + later_entries.append(entry["id"]) + return frame(entry["id"], {"content": "CHECKED-CONTENT"}) + + pending = asyncio.create_task(mcp._dispatch_batch([request(1), request(2)], dispatch)) + try: + await asyncio.sleep(0) + assert not pending.done(), "the entry must wait for its required commit" + await asyncio.wait_for(entered.wait(), 1) + pending.cancel() + await asyncio.sleep(0) + pending.cancel() + release.set() + with pytest.raises(asyncio.CancelledError): + await pending + assert committed == ["required"] and later_entries == [] + assert request_work.http_mirror_marked() + finally: + release.set() + if not pending.done(): + pending.cancel() + await asyncio.gather(pending, return_exceptions=True) + await request_tail.settle(bag.tail) + + +@pytest.mark.parametrize("shape", ["one", "multi", "notification"]) +async def test_only_a_retained_single_frame_renews_its_publication_dependencies(bag, shape): + checks, commits = [], [] + + async def check(): + checks.append("private") + + async def commit(): + commits.append("event") + + async def dispatch(entry): + if entry.get("id") == 2: + return frame(2, {"ordinary": True}) + assert request_work.mark_mirrored() + assert request_tail.defer_required(commit) + request_tail.retain_publication(object(), check, lambda: True) + return None if "id" not in entry else frame(1, {"private": True}) + + entries = [request(1)] + if shape == "multi": + entries.append(request(2)) + elif shape == "notification": + entries[0].pop("id") + result = await mcp._dispatch_batch(entries, dispatch) + assert commits == ["event"] + await request_tail.settle(bag.tail) + await request_tail._publication_barrier(bag.tail) + assert checks == (["private"] if shape == "one" else []) + assert ("private" in json.dumps(result)) is (shape == "one") + + +@pytest.mark.parametrize("notification", [False, True]) +async def test_single_endpoint_keeps_response_proofs_and_discards_notification_proofs( + monkeypatch, notification +): + from fastapi import Request, Response + + routers = [] + mcp.attach(SimpleNamespace(include_router=routers.append)) + endpoint = next(route.endpoint for route in routers[0].routes if route.path == "/mcp") + live, captured, sent = [True], [], [] + + async def check(): + if not live[0]: + raise ValueError("private-access-changed") + + async def commit(): + captured.append("event") + live[0] = False + + async def dispatch(req, *_args, **_kwargs): + request_work.begin() + assert request_work.mark_mirrored() + request_tail.retain_publication(object(), check, lambda: live[0]) + assert request_tail.defer_required(commit) + return None if "id" not in req else frame(1, {"private": True}) + + monkeypatch.setattr(mcp, "_effective_auth_mode", lambda: "open") + monkeypatch.setattr(mcp, "_verify_bearer", lambda _request: None) + monkeypatch.setattr(mcp, "_handle_request", dispatch) + payload = request(1, "ping") + if notification: + payload.pop("id") + + async def receive(): + return {"type": "http.request", "body": json.dumps(payload).encode()} + + async def app(scope, _receive, send): + await endpoint(Request(scope, receive), Response()) + await send({"type": "http.response.start", "status": 200, "headers": []}) + await send({"type": "http.response.body", "body": b"constant"}) + + async def send(message): + sent.append(message) + + scope = {"type": "http", "method": "POST", "path": "/mcp", "headers": [], "query_string": b""} + if notification: + await request_tail.RequestTailMiddleware(app)(scope, None, send) + assert len(sent) == 2 + else: + with pytest.raises(request_tail.RequiredTailError): + await request_tail.RequestTailMiddleware(app)(scope, None, send) + assert sent == [] + assert captured == ["event"] diff --git a/tests/unit/test_mirror_reader_evidence.py b/tests/unit/test_mirror_reader_evidence.py new file mode 100644 index 0000000000..151870fa00 --- /dev/null +++ b/tests/unit/test_mirror_reader_evidence.py @@ -0,0 +1,258 @@ +"""Mirrored readers use directory evidence rather than subject-shaped addresses.""" + +from contextlib import asynccontextmanager +from types import SimpleNamespace +from unittest.mock import AsyncMock + +import pytest + +from server.auth import reader_identity, sso_links + + +def account(**changes): + return { + "namespace": "home", + "owner_email": "lee", + "contact_email": "lee@example.com", + "password_hash": "", + "hosted_domain": "example.com", + "issuer": "https://idp.example", + **changes, + } + + +@pytest.fixture +def directory(monkeypatch): + ch = SimpleNamespace(query_all=AsyncMock(return_value=[account()])) + monkeypatch.setattr(reader_identity.settings, "oidc_issuer", "https://idp.example/") + monkeypatch.setattr(reader_identity.settings, "oauth_login_provider", "oidc") + return ch + + +@pytest.mark.asyncio +async def test_verified_rows_prove_email_and_signed_domain(directory): + actual = await reader_identity.resolve_reader("acme", "lee", ch=directory) + assert actual == reader_identity.ReaderIdentity( + "lee", frozenset({"lee@example.com"}), frozenset({"example.com"}) + ) + sql = directory.query_all.call_args.args[0] + assert "loom.namespaces FINAL" in sql and "loom.sso_links FINAL" in sql + assert "{org:String}" in sql and "contact_email != ''" in sql + assert "password_hash = '' OR" in sql + assert directory.query_all.call_args.kwargs["params"] == { + "org": "acme", + "sub": "lee", + "owner": "lee", + } + + +@pytest.mark.asyncio +async def test_bare_email_subject_is_not_evidence(directory): + directory.query_all.return_value = [] + actual = await reader_identity.resolve_reader("acme", "victim@example.com", ch=directory) + assert actual == reader_identity.ReaderIdentity("victim@example.com", frozenset(), frozenset()) + + +@pytest.mark.asyncio +@pytest.mark.parametrize( + "changes", + [ + {"password_hash": "hash"}, + {"hosted_domain": ""}, + {"hosted_domain": "*.example.com"}, + {"issuer": "https://other.example"}, + {"issuer": ""}, + ], +) +async def test_email_proof_does_not_infer_domain(directory, changes): + directory.query_all.return_value = [account(**changes)] + actual = await reader_identity.resolve_reader("acme", "lee", ch=directory) + assert actual.emails == frozenset({"lee@example.com"}) + assert actual.domains == frozenset() + + +@pytest.mark.asyncio +async def test_multiple_owners_and_excess_rows_fail_closed(directory): + directory.query_all.return_value = [account(), account(owner_email="other")] + assert await reader_identity.resolve_reader("acme", "lee@example.com", ch=directory) is None + directory.query_all.return_value = [account()] * 129 + assert await reader_identity.resolve_reader("acme", "lee", ch=directory) is None + + +@pytest.mark.parametrize( + "claim", [None, "", "*.example.com", "a@b.com", "example.com.", "a..b", "-a.com", 1, []] +) +def test_bad_hosted_domain_is_empty(claim): + assert sso_links.hosted_domain(claim) == "" + + +def test_signed_hosted_domain_normalization(): + assert sso_links.hosted_domain("Example.COM") == "example.com" + + +@pytest.mark.asyncio +async def test_attestation_rereads_under_account_lock(monkeypatch): + locked = set() + calls = [] + + @asynccontextmanager + async def account_change(org, ns): + locked.add((org, ns)) + try: + yield + finally: + locked.remove((org, ns)) + + async def query_all(sql, params): + calls.append(sql) + assert "LIMIT" not in sql # missing claims must clear every account + if len(calls) == 1: + assert not locked + else: + assert locked == {("acme", "home")} + assert "owner_email = {owner:String}" in sql + assert "password_hash = ''" in sql and "active = 1" in sql + return [{"namespace": "home"}] + + ch = SimpleNamespace(query_all=query_all) + write = AsyncMock() + monkeypatch.setattr(sso_links, "get_client", lambda: ch) + monkeypatch.setattr(sso_links, "_write", write) + monkeypatch.setattr("server.auth.grant_claims.account_change", account_change) + await sso_links.attest_domain( + "lee@example.com", "acme", "lee", {"iss": "https://idp.example", "hd": "Example.COM"} + ) + write.assert_awaited_once_with( + "lee@example.com", + [("acme", "home")], + "lee", + linked=1, + hosted_domain="example.com", + issuer="https://idp.example", + ch=ch, + ) + assert not locked + + +@pytest.mark.asyncio +async def test_release_between_discovery_and_lock_writes_nothing(monkeypatch): + @asynccontextmanager + async def account_change(*args): + yield + + ch = SimpleNamespace(query_all=AsyncMock(side_effect=[[{"namespace": "home"}], []])) + write = AsyncMock() + monkeypatch.setattr(sso_links, "get_client", lambda: ch) + monkeypatch.setattr(sso_links, "_write", write) + monkeypatch.setattr("server.auth.grant_claims.account_change", account_change) + await sso_links.attest_domain( + "lee@example.com", "acme", "lee", {"iss": "https://idp.example", "hd": "example.com"} + ) + write.assert_not_awaited() + + +@pytest.mark.asyncio +async def test_password_owner_keeps_identity_without_verified_contact(directory): + directory.query_all.return_value = [] + assert await reader_identity.resolve_reader( + "acme", "lee", ch=directory + ) == reader_identity.ReaderIdentity("lee", frozenset(), frozenset()) + + +@pytest.mark.asyncio +async def test_email_subject_collects_canonical_owners_other_verified_contacts(directory): + directory.query_all.side_effect = [ + [{"owner_email": "lee", "contact_email": "lee@example.com"}], + [account(), account(namespace="other", contact_email="other@example.com")], + ] + actual = await reader_identity.resolve_reader("acme", "lee@example.com", ch=directory) + assert actual.emails == frozenset({"lee@example.com", "other@example.com"}) + assert directory.query_all.call_args.kwargs["params"]["owner"] == "lee" + + +@pytest.mark.asyncio +@pytest.mark.parametrize("deactivated", [False, True]) +async def test_callback_evidence_failure_revokes_and_never_starts_session( + monkeypatch, auth_attempts, deactivated +): + import time + + from starlette.responses import Response + + from server.auth import oauth, oidc + from tests.unit.oauth_store_fake import MemoryOAuthStore + + pending = { + "kind": "dashboard", + "nonce": "n", + "code_verifier": "v", + "state": "s", + "exp": time.time() + 600, + } + + class Request: + client = None + query_params = {"code": "c", "state": "s"} + cookies = {oauth._state_cookie("s"): oauth.seal_pending(pending)} + + evidence = AsyncMock(side_effect=RuntimeError("private backend exception")) + session = AsyncMock(return_value=Response(status_code=302)) + revoke = AsyncMock() + monkeypatch.setattr(oauth, "store", MemoryOAuthStore()) + monkeypatch.setattr( + oauth, + "_exchange_at_idp", + AsyncMock( + return_value=( + {"refresh_token": "upstream"}, + { + "email": "lee@example.com", + "email_verified": True, + "iss": "https://idp.example", + "hd": "example.com", + }, + ) + ), + ) + monkeypatch.setattr( + oauth, "_account_for", AsyncMock(return_value=("lee", "acme", ["home"], ["writer"])) + ) + monkeypatch.setattr( + oauth, + "_refused_if_deactivated", + AsyncMock(return_value=Response(status_code=403) if deactivated else None), + ) + monkeypatch.setattr(oauth, "_dashboard_signed_in", session) + monkeypatch.setattr(sso_links, "attest_domain", evidence) + monkeypatch.setattr(oidc, "revoke", revoke) + response = await oauth.oidc_callback(Request()) + session.assert_not_awaited() + if deactivated: + assert response.status_code == 403 + evidence.assert_not_awaited() + else: + assert response.status_code == 503 + assert b"private backend exception" not in response.body + assert b"again" in response.body.lower() + revoke.assert_awaited_once_with("upstream") + + +@pytest.mark.asyncio +async def test_cancelled_attestation_does_not_become_restart_response(monkeypatch): + import asyncio + + from server.auth import oauth, oidc + + monkeypatch.setattr(oauth, "_refused_if_deactivated", AsyncMock(return_value=None)) + monkeypatch.setattr(sso_links, "attest_domain", AsyncMock(side_effect=asyncio.CancelledError)) + revoke = AsyncMock() + monkeypatch.setattr(oidc, "revoke", revoke) + with pytest.raises(asyncio.CancelledError): + await oauth._signed_in_as( + {"kind": "dashboard"}, + ("lee", "acme", ["home"], ["writer"]), + "upstream", + "lee@example.com", + verified_claims={"iss": "https://idp.example"}, + ) + revoke.assert_not_awaited() diff --git a/tests/unit/test_mirror_reader_identity.py b/tests/unit/test_mirror_reader_identity.py new file mode 100644 index 0000000000..c65d57114c --- /dev/null +++ b/tests/unit/test_mirror_reader_identity.py @@ -0,0 +1,257 @@ +"""Only a sign-in or an explicitly minted personal token names a mirror reader.""" + +from __future__ import annotations + +from types import SimpleNamespace +from typing import Any + +import jwt +import pytest +from fastapi import HTTPException + +from server.auth import delegation +from server.auth import jwt as tokens +from server.identity.app import me_service_accounts as me +from server.settings import settings +from tests.unit.test_token_mint import _caller, saved +from tests.unit.test_token_mint import grants as grants + + +@pytest.fixture(autouse=True) +def auth_on(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setattr(type(settings), "auth_actually_required", lambda self: True) + + +@pytest.mark.parametrize( + ("claims", "subject"), + [ + ({"session_id": "sid"}, "alice"), + ({"session_id": "sid", "first_party": True}, "alice"), + ({}, ""), + ({"is_service_account": True}, ""), + ({"creator": "alice"}, ""), + ({"creator": "alice", "session_id": "sid"}, ""), + ({"is_service_account": True, "session_id": "sid"}, ""), + ({"creator": "alice", "reads_as_creator": True, "is_service_account": True}, "alice"), + ({"reads_as_creator": True}, ""), + ({"session_id": "sid", "impersonated_by": "bob"}, ""), + ({"creator": "alice", "reads_as_creator": True, "impersonated_by": "bob"}, ""), + ({"session_id": "sid", "agent_principal": "agent:bot"}, ""), + ({"session_id": "sid", "read_user_id": "end-user"}, ""), + ], +) +def test_reader_subject_matrix(claims: dict[str, Any], subject: str) -> None: + from server.auth.reader_identity import reader_subject + + assert reader_subject(_caller(**claims)) == subject + assert reader_subject(None) == "" + + +def test_auth_off_has_no_reader_even_with_a_primary_session( + monkeypatch: pytest.MonkeyPatch, +) -> None: + from server.auth.reader_identity import reader_subject + + monkeypatch.setattr(type(settings), "auth_actually_required", lambda self: False) + assert reader_subject(_caller(session_id="sid")) == "" + + +@pytest.mark.parametrize("personal", [False, True]) +def test_signed_reader_claim_roundtrip(personal: bool) -> None: + token = tokens.mint_token( + "sa:personal", "o", ["a"], ["viewer"], creator="alice", reads_as_creator=personal + ) + assert tokens.verify_token(token).reads_as_creator is personal + decoded = jwt.decode(token, options={"verify_signature": False}) + assert ("reads_as_creator" in decoded) is personal + + +@pytest.mark.parametrize("value", ["true", "false", 0, 1, None, [], {}]) +def test_malformed_reader_claim_is_refused(value: Any) -> None: + token = tokens.mint_token("alice", "o", ["a"], ["viewer"]) + decoded = jwt.decode(token, options={"verify_signature": False}) + decoded["reads_as_creator"] = value + from server.auth import keyring + + key = keyring.signing_key() + forged = jwt.encode(decoded, key.secret, algorithm=key.algorithm, headers={"kid": key.kid}) + with pytest.raises(tokens.TokenError, match="reads_as_creator"): + tokens.verify_token(forged) + + +async def _mint( + monkeypatch: pytest.MonkeyPatch, caller: tokens.AuthInfo, *, personal: bool, **payload: Any +) -> dict[str, Any]: + monkeypatch.setattr("server.auth.bearer.verify_bearer", lambda token: caller) + request: Any = SimpleNamespace(headers={"Authorization": "Bearer t"}, state=SimpleNamespace()) + route = me.me_personal_tokens_create if personal else me.me_service_accounts_create + return await route(request, {"name": "personal-agent", "namespaces": ["a"], **payload}) + + +async def test_personal_mint_is_listed_and_never_wider_than_its_session( + monkeypatch: pytest.MonkeyPatch, grants: Any +) -> None: + parent = _caller(session_id="sid", first_party=True, roles=(), ns_roles=(("a", "viewer"),)) + response = await _mint(monkeypatch, parent, personal=True, creator="bob", org="elsewhere") + token = tokens.verify_token(response["token"]) + assert token.reads_as_creator and token.creator == "alice" and token.org == "o" + assert token.ns_roles == (("a", "viewer"),) + assert saved[0]["kind"] == "personal_agent" and saved[0]["created_by"] == "alice" + assert saved[0]["sa_subject"] == token.subject + assert saved[0]["inherit_creator_grants"] + + +async def test_service_account_mint_never_takes_a_reader_claim_from_the_body( + monkeypatch: pytest.MonkeyPatch, grants: Any +) -> None: + response = await _mint( + monkeypatch, + _caller(session_id="sid", first_party=True), + personal=False, + reads_as_creator=True, + ) + token = tokens.verify_token(response["token"]) + assert not token.reads_as_creator + assert saved[0]["kind"] == "service_account" + + +@pytest.mark.parametrize( + "claims", + [ + {}, + {"session_id": "sid", "first_party": False}, + {"session_id": "sid", "first_party": True, "is_service_account": True}, + {"session_id": "sid", "first_party": True, "creator": "alice"}, + {"session_id": "sid", "first_party": True, "impersonated_by": "bob"}, + {"session_id": "sid", "first_party": True, "agent_principal": "agent:bot"}, + {"session_id": "sid", "first_party": True, "read_user_id": "end-user"}, + ], +) +async def test_personal_mint_refuses_nonprimary_sessions_before_writing( + monkeypatch: pytest.MonkeyPatch, grants: Any, claims: dict[str, Any] +) -> None: + with pytest.raises(HTTPException) as failure: + await _mint(monkeypatch, _caller(**claims), personal=True) + assert failure.value.status_code == 403 + assert saved == [] + + +async def test_personal_mint_refuses_auth_off(monkeypatch: pytest.MonkeyPatch, grants: Any) -> None: + monkeypatch.setattr(type(settings), "auth_actually_required", lambda self: False) + with pytest.raises(HTTPException) as failure: + await _mint(monkeypatch, _caller(session_id="sid", first_party=True), personal=True) + assert failure.value.status_code == 403 and saved == [] + + +async def test_personal_mint_refuses_on_behalf_header( + monkeypatch: pytest.MonkeyPatch, grants: Any +) -> None: + caller = _caller(session_id="sid", first_party=True) + monkeypatch.setattr("server.auth.bearer.verify_bearer", lambda token: caller) + request: Any = SimpleNamespace( + headers={"Authorization": "Bearer t", "X-Loom-On-Behalf-Of": "bob"}, state=SimpleNamespace() + ) + with pytest.raises(HTTPException) as failure: + await me.me_personal_tokens_create(request, {"namespaces": ["a"]}) + assert failure.value.status_code == 403 and saved == [] + + +async def test_delegation_never_copies_a_personal_reader_claim( + monkeypatch: pytest.MonkeyPatch, grants: Any +) -> None: + response = await _mint(monkeypatch, _caller(session_id="sid", first_party=True), personal=True) + parent = tokens.verify_token(response["token"]) + assert parent.reads_as_creator + child = await delegation.delegate( + parent, + org="o", + requested={"a": "viewer"}, + scoped=True, + ttl_seconds=60, + is_service_account=True, + ) + assert not child.as_auth("sa:child").reads_as_creator + assert not tokens.verify_token(child.mint("sa:child")).reads_as_creator + + +@pytest.mark.parametrize( + ("claims", "reader"), + [ + ({"session_id": "sid", "first_party": True}, "alice"), + ({"subject": "sa:personal", "creator": "alice", "reads_as_creator": True}, "alice"), + ({"subject": "sa:ci", "creator": "alice", "is_service_account": True}, ""), + ({"session_id": "sid", "impersonated_by": "bob"}, ""), + ({}, ""), + ], +) +async def test_answer_token_explicitly_reads_as_the_callers_person_and_its_child_does_not( + monkeypatch: pytest.MonkeyPatch, grants: Any, claims: dict[str, Any], reader: str +) -> None: + from server.assistant.app import bridge + from server.auth.reader_identity import reader_subject + + token = tokens.verify_token( + await bridge.answer_token(_caller(namespaces=("a",), **claims), "o", "a") + ) + assert token.reads_as_creator is bool(reader) + assert reader_subject(token) == reader + child = await delegation.delegate( + token, + org="o", + requested={"a": "viewer"}, + scoped=True, + ttl_seconds=30, + is_service_account=True, + ) + child_auth = tokens.verify_token(child.mint("sa:answer-child")) + assert not child_auth.reads_as_creator and not reader_subject(child_auth) + from server.core.errors import AssistantSelfCallError + + with pytest.raises(AssistantSelfCallError): + bridge.refuse_self_call(child_auth) + + +async def test_personal_kind_survives_listing_and_revocation( + monkeypatch: pytest.MonkeyPatch, grants: Any +) -> None: + from server.auth.service_accounts import revoked_row + from server.core.datetimes import naive_utc_now_seconds + + parent = _caller(session_id="sid", first_party=True) + await _mint(monkeypatch, parent, personal=True) + [stored] = saved + revoked = revoked_row(stored, revoked_at=naive_utc_now_seconds(), revoked_by=parent.subject) + assert revoked == { + **stored, + "revoked_at": revoked["revoked_at"], + "revoked_by": "alice", + "version": revoked["version"], + } + assert revoked["kind"] == "personal_agent" and revoked["version"] > stored["version"] + + class Client: + async def query_all(self, *args: Any, **kwargs: Any) -> list[dict[str, Any]]: + return [stored] + + monkeypatch.setattr("server.core.ch.get_client", lambda: Client()) + request: Any = SimpleNamespace(headers={"Authorization": "Bearer t"}, state=SimpleNamespace()) + listed = await me.me_service_accounts_list(request) + assert listed["rows"][0]["kind"] == "personal_agent" + assert listed["rows"][0]["sa_subject"] == stored["sa_subject"] + + +async def test_personal_mint_binds_the_once_verified_primary_session( + monkeypatch: pytest.MonkeyPatch, grants: Any +) -> None: + parent = _caller(session_id="sid", first_party=True) + checked: list[str] = [] + + def verify(token: str) -> tokens.AuthInfo: + checked.append(token) + return parent + + monkeypatch.setattr("server.auth.bearer.verify_bearer", verify) + request: Any = SimpleNamespace(headers={"Authorization": "Bearer t"}, state=SimpleNamespace()) + result = await me.me_personal_tokens_create(request, {"namespaces": ["a"]}) + assert tokens.verify_token(result["token"]).creator == parent.subject + assert checked == ["t"] diff --git a/tests/unit/test_mirror_recall_credit_cache.py b/tests/unit/test_mirror_recall_credit_cache.py new file mode 100644 index 0000000000..8dda04ad58 --- /dev/null +++ b/tests/unit/test_mirror_recall_credit_cache.py @@ -0,0 +1,52 @@ +"""A private closer cannot publish positive evidence through a later recall-credit cache hit.""" + +from __future__ import annotations + +import contextvars +from contextlib import contextmanager + +import pytest + +from server.core import diagnostics, request_work +from server.memory.app import recall_credit + + +@contextmanager +def privacy(kind: str): + if kind == "private": + with diagnostics.private_work(): + yield + elif kind == "http_owner": + with request_work.http_owner({"type": "http"}): + request_work.begin() + assert request_work.mark_mirrored() + request_work.begin() + assert not request_work.mirror_marked() and request_work.http_mirror_marked() + yield + else: + yield + + +@pytest.mark.parametrize("kind", ["ordinary", "private", "http_owner", "unavailable"]) +@pytest.mark.parametrize("cached", [False, True]) +def test_only_ordinary_closers_change_cached_recall_evidence(monkeypatch, kind, cached) -> None: + key = ("org", "client") + before = {key: (False, float("inf"))} if cached else {} + monkeypatch.setattr(recall_credit, "_CLOSER_CACHE", dict(before)) + + if kind == "unavailable": + + def unavailable(): + raise RuntimeError("classification unavailable") + + monkeypatch.setattr(request_work, "http_mirror_marked", unavailable) + + def exercise(): + with privacy(kind): + recall_credit.note_closer(*key) + if kind == "ordinary": + assert recall_credit._CLOSER_CACHE[key][0] is True + else: + assert recall_credit._CLOSER_CACHE == before + + contextvars.copy_context().run(exercise) diff --git a/tests/unit/test_mirror_request_owner.py b/tests/unit/test_mirror_request_owner.py new file mode 100644 index 0000000000..0a9c5faca8 --- /dev/null +++ b/tests/unit/test_mirror_request_owner.py @@ -0,0 +1,362 @@ +"""HTTP ownership survives logical-bag replacement and middleware task boundaries.""" + +from __future__ import annotations + +import asyncio +from types import SimpleNamespace + +import httpx +import pytest +from starlette.background import BackgroundTask +from starlette.middleware.base import BaseHTTPMiddleware +from starlette.responses import PlainTextResponse + +from server.core import request_work +from server.core.diagnostics import private_work +from server.core.request_tail import RequestTailMiddleware +from server.transport.request_scope import HTTPApplication + +_OWNER_KEY = "loom.request_work_owner" + + +@pytest.fixture(autouse=True) +def instrumentor_background_state(): + # Uninstrumenting a local app also removes the process-wide background hook. + missing = object() + original_call = BackgroundTask.__call__ + original_hook = vars(BackgroundTask).get("_otel_original_call", missing) + try: + yield + finally: + BackgroundTask.__call__ = original_call + if original_hook is missing: + if "_otel_original_call" in vars(BackgroundTask): + delattr(BackgroundTask, "_otel_original_call") + else: + BackgroundTask._otel_original_call = original_hook + + +def flags(scope): + owner = scope.get(_OWNER_KEY) + return bool(owner and owner.mirror_marked), bool(owner and owner.mirror_unread) + + +@pytest.fixture +def world(): + token = request_work._current.set(None) + state = SimpleNamespace(seen=[], scopes=[]) + yield state + request_work._current.reset(token) + + +def owner_application(endpoint): + app = HTTPApplication() + app.mount("/", RequestTailMiddleware(endpoint)) + return app + + +def application(state, endpoint): + async def observe(request, call_next): + try: + return await call_next(request) + finally: + state.seen.append((request.url.path, flags(request.scope))) + + inner = BaseHTTPMiddleware(endpoint, dispatch=observe) + outer = BaseHTTPMiddleware(inner, dispatch=observe) + return owner_application(outer) + + +@pytest.mark.parametrize("unread", [False, True]) +@pytest.mark.parametrize("replace_child_bag", [False, True]) +async def test_http_owner_survives_private_child_and_bag_replacement( + world, unread, replace_child_bag +): + async def endpoint(scope, receive, send): + world.scopes.append(scope) + parent = request_work.begin() + + async def child(): + if replace_child_bag: + request_work.begin() + with private_work(): + assert request_work.current() is None + assert request_work.mark_mirrored(unread=unread) + + task = asyncio.create_task(child()) + try: + await task + finally: + if not task.done(): + task.cancel() + await asyncio.gather(task, return_exceptions=True) + assert parent.mirror_marked is (not replace_child_bag) + assert flags(scope) == (True, unread) + # A later logical operation has independent counters and local flags. + next_bag = request_work.begin() + assert next_bag is not parent and not request_work.mirror_marked() + assert next_bag.ch_statements == 0 + assert flags(scope) == (True, unread) + await PlainTextResponse("ready")(scope, receive, send) + + async with httpx.AsyncClient( + transport=httpx.ASGITransport(app=application(world, endpoint)), base_url="http://test" + ) as client: + response = await client.get("/marked") + assert response.status_code == 200 and response.text == "ready" + assert world.seen == [("/marked", (True, unread)), ("/marked", (True, unread))] + assert flags(world.scopes[0]) == (True, unread) + assert request_work._current.get() is None + + +async def test_sequential_http_requests_keep_owner_and_accounting_separate(world): + async def endpoint(scope, receive, send): + world.scopes.append(scope) + assert flags(scope) == (False, False) + assert request_work._current.get() is None + bag = request_work.begin() + if scope["path"] == "/marked": + assert request_work.mark_mirrored(unread=True) + bag.ch_statements = 11 + else: + assert not request_work.mirror_marked() and bag.ch_statements == 0 + await PlainTextResponse("ready")(scope, receive, send) + + async with httpx.AsyncClient( + transport=httpx.ASGITransport(app=application(world, endpoint)), base_url="http://test" + ) as client: + assert (await client.get("/marked")).status_code == 200 + assert (await client.get("/ordinary")).status_code == 200 + assert world.scopes[0].get(_OWNER_KEY) is not world.scopes[1].get(_OWNER_KEY) + assert world.seen == [ + ("/marked", (True, True)), + ("/marked", (True, True)), + ("/ordinary", (False, False)), + ("/ordinary", (False, False)), + ] + assert request_work._current.get() is None + + +async def test_overlapping_http_requests_have_distinct_owners(world): + marked = asyncio.Event() + ordinary = asyncio.Event() + + async def endpoint(scope, receive, send): + world.scopes.append(scope) + request_work.begin() + if scope["path"] == "/marked": + assert request_work.mark_mirrored() + marked.set() + await asyncio.wait_for(ordinary.wait(), timeout=5) + assert flags(scope) == (True, False) + else: + await asyncio.wait_for(marked.wait(), timeout=5) + assert not request_work.mirror_marked() and flags(scope) == (False, False) + ordinary.set() + await PlainTextResponse("ready")(scope, receive, send) + + async with httpx.AsyncClient( + transport=httpx.ASGITransport(app=application(world, endpoint)), base_url="http://test" + ) as client: + tasks = [asyncio.create_task(client.get(path)) for path in ("/marked", "/ordinary")] + try: + responses = await asyncio.wait_for(asyncio.gather(*tasks), timeout=10) + assert [response.status_code for response in responses] == [200, 200] + finally: + for task in tasks: + if not task.done(): + task.cancel() + await asyncio.gather(*tasks, return_exceptions=True) + by_path = {scope["path"]: scope for scope in world.scopes} + assert by_path["/marked"].get(_OWNER_KEY) is not by_path["/ordinary"].get(_OWNER_KEY) + assert sorted(world.seen) == [ + ("/marked", (True, False)), + ("/marked", (True, False)), + ("/ordinary", (False, False)), + ("/ordinary", (False, False)), + ] + assert request_work._current.get() is None + + +@pytest.mark.parametrize("cancel", [False, True]) +async def test_http_owner_restores_context_after_endpoint_failure(world, cancel): + from server.core.request_errors import MarkedRequestError + + class EndpointFailure(Exception): + pass + + failure = asyncio.CancelledError() if cancel else EndpointFailure() + prior = request_work.begin() + + async def endpoint(scope, receive, send): + world.scopes.append(scope) + assert request_work._current.get() is None + request_work.begin() + assert request_work.mark_mirrored(unread=False) + raise failure + + async with httpx.AsyncClient( + transport=httpx.ASGITransport(app=owner_application(endpoint)), base_url="http://test" + ) as client: + with pytest.raises(asyncio.CancelledError if cancel else MarkedRequestError) as caught: + await client.get("/failed") + if cancel: + assert caught.value is failure + else: + assert type(caught.value) is MarkedRequestError + assert caught.value.__context__ is failure + assert caught.value.__suppress_context__ + assert str(caught.value) == "Private request failed" + assert flags(world.scopes[0]) == (True, False) + assert request_work._current.get() is prior and not prior.mirror_marked + + request_work.begin() + assert request_work.mark_mirrored(unread=True) + assert flags(world.scopes[0]) == (True, False) + + +def test_worker_bag_without_http_owner_remains_fresh(world): + first = request_work.begin() + assert request_work.mark_mirrored(unread=True) + second = request_work.begin() + assert first is not second and first.mirror_marked and first.mirror_unread + assert not request_work.mirror_marked() and not second.mirror_unread + + +async def test_http_owner_unread_is_monotonic_across_distinct_logical_bags(world): + async def endpoint(scope, receive, send): + world.scopes.append(scope) + request_work.begin() + assert request_work.mark_mirrored(unread=True) + assert flags(scope) == (True, True) + next_bag = request_work.begin() + assert request_work.mark_mirrored(unread=False) + assert next_bag.mirror_marked and not next_bag.mirror_unread + assert flags(scope) == (True, True) + await PlainTextResponse("ready")(scope, receive, send) + + async with httpx.AsyncClient( + transport=httpx.ASGITransport(app=application(world, endpoint)), base_url="http://test" + ) as client: + assert (await client.get("/marked")).status_code == 200 + assert world.seen == [("/marked", (True, True)), ("/marked", (True, True))] + + +async def test_outside_request_mark_cannot_mutate_a_completed_http_owner(world): + async def endpoint(scope, receive, send): + world.scopes.append(scope) + request_work.begin() + await PlainTextResponse("ready")(scope, receive, send) + + async with httpx.AsyncClient( + transport=httpx.ASGITransport(app=owner_application(endpoint)), base_url="http://test" + ) as client: + assert (await client.get("/ordinary")).status_code == 200 + completed = world.scopes[0] + assert flags(completed) == (False, False) + request_work.begin() + assert request_work.mark_mirrored(unread=True) + assert flags(completed) == (False, False) + + +async def test_owner_survives_installed_instrumentor_finalizers(world): + from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor + from opentelemetry.sdk.resources import Resource + from opentelemetry.sdk.trace import SpanProcessor, TracerProvider + from opentelemetry.sdk.trace.sampling import ALWAYS_ON + from opentelemetry.trace import SpanKind + + ended = [] + histograms = [] + active = [] + + class Observer(SpanProcessor): + def on_end(self, span): + ended.append((span.kind, request_work.http_mirror_marked())) + + class Histogram: + def __init__(self, name): + self.name = name + + def record(self, value, attributes=None, context=None): + histograms.append((self.name, value, request_work.http_mirror_marked())) + + class Counter: + def add(self, value, attributes=None, context=None): + active.append((value, request_work.http_mirror_marked())) + + class Meter: + def create_histogram(self, name, *args, **kwargs): + return Histogram(name) + + def create_up_down_counter(self, name, *args, **kwargs): + return Counter() + + class Meters: + def get_meter(self, *args, **kwargs): + return Meter() + + async def endpoint(scope, receive, send): + world.scopes.append(scope) + request_work.begin() + assert request_work.mark_mirrored() + await PlainTextResponse("ready")(scope, receive, send) + + app = owner_application(endpoint) + provider = TracerProvider(sampler=ALWAYS_ON, resource=Resource({}), shutdown_on_exit=False) + provider.add_span_processor(Observer()) + try: + FastAPIInstrumentor.instrument_app( + app, tracer_provider=provider, meter_provider=Meters(), excluded_urls="" + ) + async with httpx.AsyncClient( + transport=httpx.ASGITransport(app=app), base_url="http://test" + ) as client: + response = await client.get("/marked") + assert response.status_code == 200 and response.text == "ready" + assert [marked for kind, marked in ended if kind is SpanKind.SERVER] == [True] + assert histograms and all(marked for _name, _value, marked in histograms) + assert active and sum(value for value, _marked in active) == 0 + assert any(value > 0 and not marked for value, marked in active) + assert any(value < 0 and marked for value, marked in active) + assert not request_work.http_mirror_marked() + assert request_work._current.get() is None + finally: + try: + FastAPIInstrumentor.uninstrument_app(app) + finally: + provider.shutdown() + + +async def test_lifespan_delegates_without_an_http_owner(world): + app = HTTPApplication() + prior = request_work.begin() + received = iter(({"type": "lifespan.startup"}, {"type": "lifespan.shutdown"})) + sent = [] + scope = {"type": "lifespan", "asgi": {"version": "3.0"}, "state": {}} + + async def receive(): + return next(received) + + async def send(message): + sent.append(message) + + await app(scope, receive, send) + assert sent == [{"type": "lifespan.startup.complete"}, {"type": "lifespan.shutdown.complete"}] + assert _OWNER_KEY not in scope and not request_work.http_mirror_marked() + assert request_work._current.get() is prior + + +def test_application_keeps_fastapi_routing_and_schema(world): + from fastapi import FastAPI + + app = HTTPApplication(title="Example") + + @app.get("/ping") + async def ping(): + return {"ready": True} + + assert isinstance(app, FastAPI) + schema = app.openapi() + assert schema["info"]["title"] == "Example" + assert schema["paths"]["/ping"]["get"]["responses"]["200"]["description"] diff --git a/tests/unit/test_mirror_telemetry_sinks.py b/tests/unit/test_mirror_telemetry_sinks.py new file mode 100644 index 0000000000..70214b35bd --- /dev/null +++ b/tests/unit/test_mirror_telemetry_sinks.py @@ -0,0 +1,298 @@ +"""Private request outcomes never enter public telemetry queues or histograms.""" + +from __future__ import annotations + +import logging +from types import SimpleNamespace +from unittest.mock import Mock + +import httpx +import pytest +from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor +from opentelemetry.sdk.resources import Resource +from opentelemetry.sdk.trace import TracerProvider +from opentelemetry.sdk.trace.export import BatchSpanProcessor +from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter +from opentelemetry.sdk.trace.sampling import ALWAYS_ON +from starlette.background import BackgroundTask +from starlette.responses import PlainTextResponse + +from server.core import diagnostics, request_work +from server.observability import otel, otel_langfuse +from server.observability.otel_privacy import asgi_meter_provider, public_span_processor +from server.transport.request_scope import HTTPApplication + + +@pytest.fixture(autouse=True) +def isolated_work(): + token = request_work._current.set(None) + try: + yield + finally: + request_work._current.reset(token) + + +@pytest.fixture(autouse=True) +def instrumentor_background_state(): + # Uninstrumenting a local app also removes the process-wide background hook. + missing = object() + original_call = BackgroundTask.__call__ + original_hook = vars(BackgroundTask).get("_otel_original_call", missing) + try: + yield + finally: + BackgroundTask.__call__ = original_call + if original_hook is missing: + if "_otel_original_call" in vars(BackgroundTask): + delattr(BackgroundTask, "_otel_original_call") + else: + BackgroundTask._otel_original_call = original_hook + + +@pytest.fixture +def local_traces(): + provider = TracerProvider(sampler=ALWAYS_ON, resource=Resource({}), shutdown_on_exit=False) + try: + exporter = InMemorySpanExporter() + batch = BatchSpanProcessor(exporter) + try: + provider.add_span_processor(public_span_processor(batch)) + except BaseException: + batch.shutdown() + raise + yield provider, exporter + finally: + provider.shutdown() + + +def mark(): + request_work.begin() + assert request_work.mark_mirrored() + + +def test_owner_survives_private_scope_without_hiding_accounting(): + assert diagnostics.public_diagnostics() + with request_work.http_owner({}): + bag = request_work.begin() + with diagnostics.private_work(): + assert request_work.mark_mirrored() + assert not diagnostics.public_diagnostics() + assert request_work.current() is None + assert not diagnostics.codes_only() + assert not diagnostics.public_diagnostics() + assert request_work.current() is bag + request_work.begin() + assert not request_work.mirror_marked() + assert not diagnostics.public_diagnostics() + assert diagnostics.public_diagnostics() + + +def test_unavailable_owner_decision_drops_public_sinks(monkeypatch): + def unavailable(): + raise RuntimeError("private decision unavailable") + + monkeypatch.setattr(request_work, "http_mirror_marked", unavailable) + emit = Mock() + diagnostics.public_only(emit)("hidden") + record = logging.LogRecord("example", logging.ERROR, "", 0, "hidden", (), None) + assert not diagnostics.public_diagnostics() + assert not diagnostics.public_log(record) + emit.assert_not_called() + + +@pytest.mark.parametrize("transport", ["http", "mcp"]) +@pytest.mark.parametrize("success", [True, False]) +def test_operation_metrics_keep_ordinary_values_and_drop_marked(monkeypatch, transport, success): + counter, duration = Mock(), Mock() + monkeypatch.setattr(otel, "_request_counter", counter) + monkeypatch.setattr(otel, "_request_duration", duration) + values = dict( + namespace="example", + success=success, + duration_ms=17.5, + transport=transport, + error_code="" if success else "UNAVAILABLE", + ) + with request_work.http_owner({}): + mark() + otel.record_op("memory.search", **values) + counter.add.assert_not_called() + duration.record.assert_not_called() + otel.record_op("memory.search", **values) + attrs = { + "loom.operation": "memory.search", + "loom.namespace": "example", + "loom.transport": transport, + "success": "true" if success else "false", + } + counter.add.assert_called_once_with( + 1, attributes={**attrs, "loom.error_code": values["error_code"]} + ) + duration.record.assert_called_once_with(17.5, attributes=attrs) + + +def test_batch_export_after_owner_reset_contains_only_ordinary_spans(local_traces): + provider, exporter = local_traces + tracer = provider.get_tracer("example") + with request_work.http_owner({}): + span = tracer.start_span("private-canary", start_time=1) + mark() + span.end(end_time=2) + ordinary = tracer.start_span("ordinary", start_time=3) + ordinary.set_attribute("example.value", "retained") + ordinary.end(end_time=4) + assert provider.force_flush() + spans = exporter.get_finished_spans() + assert [span.name for span in spans] == ["ordinary"] + assert spans[0].attributes["example.value"] == "retained" + assert (spans[0].start_time, spans[0].end_time) == (3, 4) + + +def test_span_processor_preserves_public_lifecycle(): + inner = Mock() + inner.force_flush.return_value = True + processor = public_span_processor(inner) + span, parent = object(), object() + processor.on_start(span, parent) + processor.on_end(span) + assert processor.force_flush(123) + processor.shutdown() + inner.on_start.assert_called_once_with(span, parent) + inner.on_end.assert_called_once_with(span) + inner.force_flush.assert_called_once_with(123) + inner.shutdown.assert_called_once_with() + + +def test_langfuse_does_not_inspect_count_or_export_marked_spans(monkeypatch): + inner, span_filter = Mock(), Mock() + span_filter.keep.return_value = True + monkeypatch.setattr(otel_langfuse.genai, "stamp_identity", Mock()) + processor = otel_langfuse._langfuse_processor_class()(inner, span_filter) + span = object() + with request_work.http_owner({}): + mark() + processor.on_start(span) + processor._on_ending(span) + processor.on_end(span) + assert (processor.forwarded, processor.dropped, processor.errors) == (0, 0, 0) + assert inner.mock_calls == [] + span_filter.keep.assert_not_called() + otel_langfuse.genai.stamp_identity.assert_not_called() + processor.on_start(span) + processor.on_end(span) + assert (processor.forwarded, processor.dropped, processor.errors) == (1, 0, 0) + inner.on_start.assert_called_once_with(span, None) + inner.on_end.assert_called_once_with(span) + span_filter.keep.assert_called_once_with(span) + + +def test_meter_preserves_identity_histogram_arguments_and_records(): + inner = Mock() + wrapper = asgi_meter_provider(inner) + attrs = {"example.scope": "value"} + meter = wrapper.get_meter("example", "1", "https://example.com/schema", attrs) + inner.get_meter.assert_called_once_with("example", "1", "https://example.com/schema", attrs) + histogram = meter.create_histogram( + "duration", + unit="s", + description="Elapsed time", + explicit_bucket_boundaries_advisory=(0.1, 1.0), + ) + raw = inner.get_meter.return_value.create_histogram.return_value + inner.get_meter.return_value.create_histogram.assert_called_once_with( + "duration", + unit="s", + description="Elapsed time", + explicit_bucket_boundaries_advisory=(0.1, 1.0), + ) + context = object() + with request_work.http_owner({}): + mark() + histogram.record(9, attrs, context) + raw.record.assert_not_called() + histogram.record(1.5, attrs, context) + raw.record.assert_called_once_with(1.5, attrs, context) + + +@pytest.mark.parametrize( + "method", + [ + "create_counter", + "create_up_down_counter", + "create_observable_counter", + "create_observable_up_down_counter", + "create_gauge", + "create_observable_gauge", + ], +) +def test_other_meter_instruments_delegate_without_changing_participation(method): + inner = Mock() + meter = asgi_meter_provider(inner).get_meter("example") + create = getattr(inner.get_meter.return_value, method) + with request_work.http_owner({}): + mark() + instrument = getattr(meter, method)("active", unit="1", description="Active") + assert instrument is create.return_value + create.assert_called_once_with("active", unit="1", description="Active") + + +@pytest.mark.parametrize("raises", [False, True]) +async def test_real_instrumentor_finalizers_drop_marked_and_keep_ordinary(raises, local_traces): + histograms, active = [], [] + + class Histogram: + def __init__(self, name): + self.name = name + + def record(self, amount, attributes=None, context=None): + histograms.append((self.name, amount, attributes)) + + class Counter: + def add(self, amount, *args, **kwargs): + active.append(amount) + + class Meter: + def create_histogram(self, name, *args, **kwargs): + return Histogram(name) + + def create_up_down_counter(self, name, *args, **kwargs): + return Counter() + + provider, exporter = local_traces + app = HTTPApplication() + + async def endpoint(scope, receive, send): + if scope["path"] == "/marked": + mark() + if raises: + raise RuntimeError("private-exception-canary") + await PlainTextResponse("ready")(scope, receive, send) + + app.mount("/", endpoint) + try: + FastAPIInstrumentor.instrument_app( + app, + tracer_provider=provider, + meter_provider=asgi_meter_provider(SimpleNamespace(get_meter=lambda *args: Meter())), + excluded_urls="", + ) + async with httpx.AsyncClient( + transport=httpx.ASGITransport(app=app, raise_app_exceptions=False), + base_url="http://test", + ) as client: + response = await client.get("/marked") + assert response.status_code == (500 if raises else 200) + assert not request_work.http_mirror_marked() + assert provider.force_flush() + assert exporter.get_finished_spans() == () + assert histograms == [] + assert active and sum(active) == 0 + ordinary = await client.get("/ordinary") + assert ordinary.status_code == 200 and ordinary.text == "ready" + assert provider.force_flush() + spans = exporter.get_finished_spans() + assert spans and histograms and sum(active) == 0 + assert all("private-exception-canary" not in str(span.events) for span in spans) + assert all("/marked" not in str(dict(span.attributes)) for span in spans) + finally: + FastAPIInstrumentor.uninstrument_app(app) diff --git a/tests/unit/test_model_calls_held_mid_pass.py b/tests/unit/test_model_calls_held_mid_pass.py index c90b76fe18..72cc979ea2 100644 --- a/tests/unit/test_model_calls_held_mid_pass.py +++ b/tests/unit/test_model_calls_held_mid_pass.py @@ -150,7 +150,7 @@ async def nothing(*a: Any, **k: Any) -> Any: async def in_order(repo: Any, org: str, ns: str, *a: Any) -> list[str]: return list(paths) - async def under_cap(org: str, ns: str) -> bool: + async def under_cap(org: str, ns: str, *, user_id: str = "") -> bool: return False from server.code.store import index as code_index diff --git a/tests/unit/test_namespace_audit.py b/tests/unit/test_namespace_audit.py index 22727386c7..596bbcc745 100644 --- a/tests/unit/test_namespace_audit.py +++ b/tests/unit/test_namespace_audit.py @@ -1286,7 +1286,13 @@ class _Local: async def query_all(self, sql: str, params: dict[str, Any] | None = None) -> Any: # The ledger summary also reads which keys are procedures (loom.memory). return run( - ["SET enable_quantized_codec = 1", ddl("memory"), ddl("agent_events"), *rows], + [ + "SET enable_quantized_codec = 1", + ddl("memory"), + ddl("agent_events"), + ddl("agent_events_private"), + *rows, + ], sql, params, ) @@ -1447,7 +1453,7 @@ async def test_an_audit_run_twice_still_sees_writes_the_ledger_never_recorded() # A worker's own row (an extractor's spend on the rows) says nothing about callers. _ledger_row("worker.entity_extractor", kind="worker"), ] - ch = _LocalCH(["memory", "agent_events"], rows) + ch = _LocalCH(["memory", "agent_events", "agent_events_private"], rows) audit = na.new_audit(_inp(window_seconds=3600), ch=ch) await na.run_checks(audit, ["telemetry_unavailable"]) gap = _finding(audit, "telemetry_unavailable") @@ -1460,7 +1466,7 @@ async def test_an_audit_run_twice_still_sees_writes_the_ledger_never_recorded() _ledger_row("namespace.register", consumer="loom-ui"), ) for closer in closers: - closed = _LocalCH(["memory", "agent_events"], [*rows, closer]) + closed = _LocalCH(["memory", "agent_events", "agent_events_private"], [*rows, closer]) audit = na.new_audit(_inp(window_seconds=3600), ch=closed) await na.run_checks(audit, ["telemetry_unavailable"]) assert _finding(audit, "telemetry_unavailable").count == 0, closer @@ -1471,7 +1477,10 @@ async def test_an_audit_run_twice_still_sees_writes_the_ledger_never_recorded() async def test_a_workers_revision_of_an_old_row_is_not_an_unrecorded_write() -> None: # Created two days ago, relabelled by a sweep ten minutes ago, with no call in the window. old = _memory_row("team/fact", minutes_ago=10, created_minutes_ago=2 * 24 * 60) - audit = na.new_audit(_inp(window_seconds=3600), ch=_LocalCH(["memory", "agent_events"], [old])) + audit = na.new_audit( + _inp(window_seconds=3600), + ch=_LocalCH(["memory", "agent_events", "agent_events_private"], [old]), + ) await na.run_checks(audit, ["telemetry_unavailable"]) assert _finding(audit, "telemetry_unavailable").severity == "info" @@ -1535,7 +1544,7 @@ async def test_a_hot_short_procedure_is_not_coordination_state() -> None: _memory_row("lease/y", minutes_ago=10, value="taken"), *reads, ] - ch = _LocalCH(["memory", "agent_events"], rows) + ch = _LocalCH(["memory", "agent_events", "agent_events_private"], rows) audit = na.new_audit(_inp(window_seconds=3600), ch=ch) await audit.coordination_as_memory() f = _finding(audit, "coordination_as_memory") @@ -1630,7 +1639,8 @@ async def test_a_copied_row_is_not_an_unrecorded_write() -> None: "now() - INTERVAL 10 MINUTE, now() - INTERVAL 10 MINUTE, 'source')" ) audit = na.new_audit( - _inp(window_seconds=3600), ch=_LocalCH(["memory", "agent_events"], [copied]) + _inp(window_seconds=3600), + ch=_LocalCH(["memory", "agent_events", "agent_events_private"], [copied]), ) await na.run_checks(audit, ["telemetry_unavailable"]) assert _finding(audit, "telemetry_unavailable").severity == "info" @@ -1646,7 +1656,10 @@ async def test_a_procedure_read_over_mcp_is_left_out_of_the_object_store_gauge() *(_ledger_row("memory.get", arg_key="runbook/restart") for _ in range(25)), *(_ledger_row("memory.get", arg_key="team/fact") for _ in range(21)), ] - audit = na.new_audit(_inp(window_seconds=3600), ch=_LocalCH(["memory", "agent_events"], rows)) + audit = na.new_audit( + _inp(window_seconds=3600), + ch=_LocalCH(["memory", "agent_events", "agent_events_private"], rows), + ) await audit.summary_ledger() await audit.exact_key_store() s = audit.summary diff --git a/tests/unit/test_namespace_get_classification.py b/tests/unit/test_namespace_get_classification.py index 5d0e3c0027..8e731c6cf5 100644 --- a/tests/unit/test_namespace_get_classification.py +++ b/tests/unit/test_namespace_get_classification.py @@ -56,7 +56,13 @@ def __init__(self, row: dict[str, Any] | None) -> None: async def query_one(self, sql: str, params: dict[str, Any]) -> dict[str, Any] | None: self.sql = sql - return self.row + if self.row is None: + return None + return { + k: v + for k, v in self.row.items() + if k not in {"daily_user_cost_cap_usd", "budget_alert_inbox"} or k in sql + } async def _get(monkeypatch: pytest.MonkeyPatch, row: dict[str, Any] | None) -> Any: @@ -95,3 +101,11 @@ async def test_a_missing_namespace_says_nothing_about_classification( assert out.found is False assert out.classification is None assert out.model_dump(exclude_none=True) == {"found": False, "namespace": "n"} + + +async def test_budget_policy_round_trips_in_namespace_get(monkeypatch: pytest.MonkeyPatch) -> None: + row = _row("standard") + row.update(daily_user_cost_cap_usd=2.5, budget_alert_inbox="warnings") + out = await _get(monkeypatch, row) + assert out.daily_user_cost_cap_usd == 2.5 + assert out.budget_alert_inbox == "warnings" diff --git a/tests/unit/test_namespace_register_preserve.py b/tests/unit/test_namespace_register_preserve.py index 070e241719..1494c4a14c 100644 --- a/tests/unit/test_namespace_register_preserve.py +++ b/tests/unit/test_namespace_register_preserve.py @@ -21,6 +21,8 @@ "visibility": "public", "consolidation_enabled": True, "daily_cost_cap_usd": 5.0, + "daily_user_cost_cap_usd": 2.0, + "budget_alert_inbox": "warnings", "requires_approval": True, "retention_days": 30, "warm_days": 7, @@ -37,6 +39,8 @@ "visibility": "private", "consolidation_enabled": False, "daily_cost_cap_usd": 0.0, + "daily_user_cost_cap_usd": 0.0, + "budget_alert_inbox": "", "requires_approval": False, "retention_days": 0, "warm_days": 0, @@ -207,3 +211,21 @@ async def insert(self, table: str, rows: list[Any], **_k: Any) -> None: with pytest.raises(PreconditionFailedError, match="owned by 'bob': send that owner_email"): asyncio.run(h.handle_namespace_register(inp)) assert written == [] + + +def test_registration_cannot_turn_typed_contact_into_verified_email() -> None: + inp = NamespaceRegisterInput.model_validate( + { + "org": "o", + "namespace": "n", + "owner_email": "caller", + "contact_email": "victim@example.com", + "password_hash": "", + } + ) + row = h.registry_row(inp, None, NOW) + assert row["contact_email"] == row["password_hash"] == "" + stored = _existing(contact_email="unverified@example.com", password_hash="hash") + carried = h.registry_row(inp, stored, NOW) + assert carried["contact_email"] == stored["contact_email"] + assert carried["password_hash"] == "hash" diff --git a/tests/unit/test_observation_policy.py b/tests/unit/test_observation_policy.py new file mode 100644 index 0000000000..e3a1bd7d23 --- /dev/null +++ b/tests/unit/test_observation_policy.py @@ -0,0 +1,103 @@ +"""Native access-store definitions must prove visibility, including implicit deny.""" + +from __future__ import annotations + +import pytest + +from server.insights.domain.observation_policy import observer_policies_allow + +_SCOPE = ( + "CREATE ROW POLICY loom_analyst_scope ON loom.agent_events " + "AS PERMISSIVE FOR SELECT USING mirror_marked = 0 TO loom_analyst" +) +_OTHERS = ( + "CREATE ROW POLICY loom_analyst_others ON loom.agent_events " + "AS PERMISSIVE FOR SELECT USING 1 TO ALL EXCEPT loom_analyst" +) + + +@pytest.mark.parametrize("clause", ["AS PERMISSIVE ", ""]) +def test_generated_event_pair_proves_observer_visibility(clause): + scope = _SCOPE.replace("AS PERMISSIVE ", clause) + others = _OTHERS.replace("AS PERMISSIVE ", clause) + assert observer_policies_allow((scope, others), "loom") + assert observer_policies_allow((others,), "loom") + assert observer_policies_allow((), "loom") + + +def test_analyst_only_policy_implicitly_denies_the_observer_without_its_companion(): + assert not observer_policies_allow((_SCOPE,), "loom") + other_table = _OTHERS.replace("loom.agent_events", "loom.agent_events_private") + assert not observer_policies_allow((_SCOPE, other_table), "loom") + + +@pytest.mark.parametrize( + "table", ["processes", "row_policies", "clusters", "tables", "constraints", "*"] +) +def test_system_policies_cannot_hide_process_or_metadata_populations(table): + hidden = _SCOPE.replace("loom.agent_events", "system." + table) + assert not observer_policies_allow((hidden, _OTHERS), "loom") + + +@pytest.mark.parametrize( + "replacement", + [ + "USING mirror_marked = 0 TO ALL EXCEPT loom_analyst", + "USING 1 TO loom_analyst", + "USING 1 TO ALL EXCEPT another_role", + "USING 1 TO ALL EXCEPT loom_analyst, service", + "USING 1 TO ALL EXCEPT `loom_analyst TO service`", + ], +) +def test_a_familiar_policy_name_cannot_replace_its_actual_visibility_definition(replacement): + defective = _OTHERS.replace("USING 1 TO ALL EXCEPT loom_analyst", replacement) + assert not observer_policies_allow((_SCOPE, defective), "loom") + + +@pytest.mark.parametrize("target", ["loom.*", "*.*", "system.*"]) +def test_database_wildcard_policies_are_included_in_the_inventory(target): + assert not observer_policies_allow( + (_SCOPE.replace("loom.agent_events", target), _OTHERS), "loom" + ) + + +def test_unrelated_policy_does_not_block_an_event_proof(): + assert observer_policies_allow( + (_SCOPE.replace("loom.agent_events", "other.agent_events"),), "loom" + ) + + +def test_quoted_role_text_and_policy_expressions_cannot_fake_an_unrestricted_companion(): + fake = _OTHERS.replace("USING 1", "USING '1 TO ALL EXCEPT loom_analyst' = 'no'") + assert not observer_policies_allow((_SCOPE, fake), "loom") + assert not observer_policies_allow((_SCOPE, _OTHERS, _OTHERS), "loom") + + +@pytest.mark.parametrize("index", [0, 1]) +def test_a_restrictive_generated_policy_cannot_prove_visibility(index): + policies = [_SCOPE, _OTHERS] + policies[index] = policies[index].replace("AS PERMISSIVE", "AS RESTRICTIVE") + assert not observer_policies_allow(tuple(policies), "loom") + + +def test_native_quoted_names_and_to_inside_a_literal_preserve_the_actual_recipient(): + scope = _SCOPE.replace("loom.agent_events", "`loom`.`agent_events`").replace( + "mirror_marked = 0", "position('it\\'s TO service ([)]', 'TO') > 0" + ) + others = _OTHERS.replace("loom.agent_events", '"loom"."agent_events"') + assert observer_policies_allow((scope, others), "loom") + + +@pytest.mark.parametrize( + "expression", + ["1 /* hidden */", "1 -- hidden\n", "1 # hidden\n", "'unclosed", "([)]", "$tag$TO$tag$"], +) +def test_unknown_or_commented_native_policy_syntax_cannot_prove_visibility(expression): + assert not observer_policies_allow( + (_SCOPE.replace("mirror_marked = 0", expression), _OTHERS), "loom" + ) + + +def test_unsupported_quoted_target_escapes_refuse_instead_of_looking_unrelated(): + escaped = _SCOPE.replace("loom.agent_events", r"`lo\om`.agent_events") + assert not observer_policies_allow((escaped, _OTHERS), "loom") diff --git a/tests/unit/test_oidc.py b/tests/unit/test_oidc.py index dc44f3481e..942302ce95 100644 --- a/tests/unit/test_oidc.py +++ b/tests/unit/test_oidc.py @@ -672,5 +672,15 @@ class _Req: monkeypatch.setattr(jit, "_accounts_naming", accounts) monkeypatch.setattr(jit, "_ever_granted", ever_granted) monkeypatch.setattr(self_signup, "insert_owner_grant", grant) + from unittest.mock import AsyncMock + + attested = AsyncMock() + monkeypatch.setattr(oauth.sso_links, "attest_domain", attested) assert (await oauth.oidc_callback(_Req())).status_code == 302 # type: ignore[arg-type] assert granted == ([] if granted_before else [("u-bob", "u-bob")]) + attested.assert_awaited_once_with( + "bob@acme.com", + settings.oidc_jit_org, + "someone", # the identity resolver's owner, not the JIT account name + {"email": "bob@acme.com", "email_verified": True}, + ) diff --git a/tests/unit/test_oidc_fixture_ports.py b/tests/unit/test_oidc_fixture_ports.py new file mode 100644 index 0000000000..4062ffc8f2 --- /dev/null +++ b/tests/unit/test_oidc_fixture_ports.py @@ -0,0 +1,52 @@ +"""OIDC fixture port allocation excludes the already listening IdP.""" + +from contextlib import contextmanager +from types import SimpleNamespace + +import pytest + +from tests.integration import test_oidc_flow as flow + + +@pytest.mark.parametrize("loom_port", [None, 41003]) +def test_oidc_stack_excludes_idp_port(monkeypatch, loom_port): + bound = set() + + def free_port(): + return next(port for port in (41001, 41002) if port not in bound) + + class FakeIdP: + def __init__(self, email): + self.port = free_port() + self.url = f"http://127.0.0.1:{self.port}" + + @contextmanager + def running(self): + bound.add(self.port) + try: + yield self + finally: + bound.remove(self.port) + + @contextmanager + def loom_server(label, env, *, port): + assert port not in bound + assert bound == {41001} + assert port == (loom_port or 41002) + assert env["LOOM_OIDC_ISSUER"] == "http://127.0.0.1:41001" + assert env["LOOM_OAUTH_ISSUER"] == f"http://127.0.0.1:{port}" + assert env["LOOM_OIDC_JIT_PROVISION"] == "true" + yield env["LOOM_OAUTH_ISSUER"] + + monkeypatch.delenv("LOOM_CH_SECURE", raising=False) + monkeypatch.setattr(flow, "free_port", free_port) + monkeypatch.setattr(flow, "FakeIdP", FakeIdP) + monkeypatch.setattr(flow, "loom_server", loom_server) + request = SimpleNamespace(param={"seed": False, "jit": True, "loom_port": loom_port}) + stack = flow.oidc_stack.__wrapped__(None, request) + _, namespace, base = next(stack) + assert namespace is None + assert base == f"http://127.0.0.1:{loom_port or 41002}" + with pytest.raises(StopIteration): + next(stack) + assert not bound diff --git a/tests/unit/test_op_scope_fields.py b/tests/unit/test_op_scope_fields.py index a96c17ecd1..338487d2c9 100644 --- a/tests/unit/test_op_scope_fields.py +++ b/tests/unit/test_op_scope_fields.py @@ -39,6 +39,9 @@ # (op, field) -> the function that authorizes the field's value. AUTHORIZED: dict[tuple[str, str], str] = { + ("namespace.register", "budget_alert_inbox"): ( + "server.tasks.app.budget_notifications.inbox_owned_by" + ), ("code.search", "namespaces"): _FANOUT, ("code.symbol", "namespaces"): _FANOUT, ("code.grep", "namespaces"): _FANOUT, diff --git a/tests/unit/test_otel_health_spans_excluded.py b/tests/unit/test_otel_health_spans_excluded.py index 26e8cae81d..f3baa1eaad 100644 --- a/tests/unit/test_otel_health_spans_excluded.py +++ b/tests/unit/test_otel_health_spans_excluded.py @@ -44,7 +44,11 @@ def test_instrument_app_receives_the_excluded_urls(monkeypatch: pytest.MonkeyPat ) app = object() otel._instrument_fastapi(app) - assert calls == [{"app": app, "excluded_urls": "/v1/health,/oauth/"}] + assert len(calls) == 1 + assert calls[0]["app"] is app + assert calls[0]["excluded_urls"] == "/v1/health,/oauth/" + assert set(calls[0]) == {"app", "excluded_urls", "meter_provider"} + assert callable(calls[0]["meter_provider"].get_meter) def test_a_blank_setting_instruments_every_path_but_sign_in( diff --git a/tests/unit/test_pg_authority.py b/tests/unit/test_pg_authority.py index 4e19faee4a..a970ad7ee5 100644 --- a/tests/unit/test_pg_authority.py +++ b/tests/unit/test_pg_authority.py @@ -1422,7 +1422,12 @@ def test_the_authoritys_erasure_step_leads_the_erasing_steps_and_runs_only_under assert authority_steps(USER_STEPS)[0][0] == "pg_memory.delete" # A namespace's sources stop first, so no sync turn writes into what the steps erase. names = [name for name, _ in authority_steps(NAMESPACE_STEPS)] - assert names[:2] == ["knowledge_sources.retire", "pg_memory.delete"] + assert names[:4] == [ + "knowledge_sources.retire", + "knowledge_source_push.delete", + "pg_memory.delete", + "pg_knowledge.delete", + ] assert set(PG_CENSUS) <= set(census_tables("user_id")) monkeypatch.setattr(settings, "storage_authority", "clickhouse") for steps in (USER_STEPS, NAMESPACE_STEPS): diff --git a/tests/unit/test_policy.py b/tests/unit/test_policy.py index f7b09f6992..babc4e7960 100644 --- a/tests/unit/test_policy.py +++ b/tests/unit/test_policy.py @@ -182,7 +182,8 @@ def test_formerly_compiles_to_one_pinned_point_query(): assert "args[{p_ak0:String}] = {p_av0:String}" in sql assert c.params["p_ak0"] == "memory_key" and c.params["p_av0"] == "prefs" assert c.params["p_ops"] == ["memory.get"] - assert "session_id" not in sql and "user_id" not in sql + assert "session_id =" not in sql and "user_id =" not in sql + assert not any(k.startswith(("p_session", "p_user")) for k in c.params) # no literal from the call is ever spliced into the SQL text assert "acme" not in sql and "prefs" not in sql @@ -197,11 +198,15 @@ def test_session_and_user_keys_narrow_the_pin(): assert c2 is not None and "user_id = {p_user:String}" in c2.sql and c2.params["p_user"] == "u1" -def test_unresolved_args_reference_skips_the_leaf(): +def test_unresolved_args_reference_keeps_the_coarse_participation_query(): leaf = R.Formerly( op="formerly", within="1h", operation="x", args_equal={"memory_key": "$args.memory_id"} ) - assert R.compile_leaf(leaf, ctx()) is None + unresolved = R.compile_leaf(leaf, ctx()) + assert unresolved is not None and unresolved.unresolved + assert "max(mirror_marked) AS protected_history" in unresolved.sql + assert "countIf(mirror_marked = 0 AND 0) AS n" in unresolved.sql + assert "p_av0" not in unresolved.params # a literal template is not a reference and always compiles leaf2 = R.Formerly( op="formerly", within="1h", operation="x", args_equal={"memory_type": "fact"} @@ -216,8 +221,15 @@ def test_not_since_compiles_to_two_maxima(): ) c = R.compile_leaf(leaf, ctx()) assert c is not None and c.kind == "not_since" - assert "maxOrNullIf(ts, operation IN {p_anchor:Array(String)}) AS anchor_ts" in c.sql - assert "maxOrNullIf(ts, operation IN {p_left:Array(String)}) AS left_ts" in c.sql + assert "max(mirror_marked) AS protected_history" in c.sql + assert ( + "maxOrNullIf(ts, (mirror_marked = 0) AND operation IN {p_anchor:Array(String)}) AS anchor_ts" + in c.sql + ) + assert ( + "maxOrNullIf(ts, (mirror_marked = 0) AND operation IN {p_left:Array(String)}) AS left_ts" + in c.sql + ) assert c.params["p_anchor"] == ["memory.set"] and c.params["p_left"] == ["memory.delete"] @@ -235,10 +247,10 @@ def _rule( @pytest.mark.asyncio async def test_require_formerly_denies_without_witness_and_allows_with_one(): rule = _rule("require", {"op": "formerly", "within": "1h", "operation": "memory.get"}) - d = await P.evaluate([rule], ctx(), FakeCH([[{"n": 0}]])) + d = await P.evaluate([rule], ctx(), FakeCH([[{"protected_history": 0, "n": 0}]])) assert d.decision == "deny" and d.determining_rules == ["r1"] and d.errors == [] assert d.verdicts[0].leaves[0].value == 0 and d.verdicts[0].holds is False - d2 = await P.evaluate([rule], ctx(), FakeCH([[{"n": 3}]])) + d2 = await P.evaluate([rule], ctx(), FakeCH([[{"protected_history": 0, "n": 3}]])) assert d2.decision == "allow" and d2.determining_rules == [] assert d2.verdicts[0].leaves[0].value == 3 @@ -255,8 +267,12 @@ async def test_forbid_count_within_is_a_durable_rate_limit(): "value": 200, }, ) - assert (await P.evaluate([rule], ctx(), FakeCH([[{"n": 199}]]))).decision == "allow" - assert (await P.evaluate([rule], ctx(), FakeCH([[{"n": 200}]]))).decision == "deny" + assert ( + await P.evaluate([rule], ctx(), FakeCH([[{"protected_history": 0, "n": 199}]])) + ).decision == "allow" + assert ( + await P.evaluate([rule], ctx(), FakeCH([[{"protected_history": 0, "n": 200}]])) + ).decision == "deny" @pytest.mark.asyncio @@ -267,15 +283,21 @@ async def test_not_since_open_session_idiom(): ) t0 = NOW - timedelta(hours=2) # anchor present, nothing forbidden since → holds - d = await P.evaluate([rule], ctx(), FakeCH([[{"anchor_ts": t0, "left_ts": None}]])) + d = await P.evaluate( + [rule], ctx(), FakeCH([[{"protected_history": 0, "anchor_ts": t0, "left_ts": None}]]) + ) assert d.decision == "allow" # forbidden event after the anchor → does not hold d = await P.evaluate( - [rule], ctx(), FakeCH([[{"anchor_ts": t0, "left_ts": t0 + timedelta(minutes=5)}]]) + [rule], + ctx(), + FakeCH([[{"protected_history": 0, "anchor_ts": t0, "left_ts": t0 + timedelta(minutes=5)}]]), ) assert d.decision == "deny" # no anchor in the window → since has nothing to anchor on → does not hold - d = await P.evaluate([rule], ctx(), FakeCH([[{"anchor_ts": None, "left_ts": None}]])) + d = await P.evaluate( + [rule], ctx(), FakeCH([[{"protected_history": 0, "anchor_ts": None, "left_ts": None}]]) + ) assert d.decision == "deny" @@ -283,13 +305,17 @@ async def test_not_since_open_session_idiom(): async def test_all_any_not_combine_and_short_circuit(): f = {"op": "formerly", "within": "1h", "operation": "a"} g = {"op": "formerly", "within": "1h", "operation": "b"} - ch = FakeCH([[{"n": 0}]]) # `all` stops after the first false leaf + ch = FakeCH([[{"protected_history": 0, "n": 0}]]) # `all` stops after the first false leaf d = await P.evaluate([_rule("require", {"op": "all", "of": [f, g]})], ctx(), ch) assert d.decision == "deny" and len(ch.calls) == 1 - ch = FakeCH([[{"n": 1}]]) # `any` stops after the first true leaf + ch = FakeCH([[{"protected_history": 0, "n": 1}]]) # `any` stops after the first true leaf d = await P.evaluate([_rule("require", {"op": "any", "of": [f, g]})], ctx(), ch) assert d.decision == "allow" and len(ch.calls) == 1 - d = await P.evaluate([_rule("forbid", {"op": "not", "of": f})], ctx(), FakeCH([[{"n": 0}]])) + d = await P.evaluate( + [_rule("forbid", {"op": "not", "of": f})], + ctx(), + FakeCH([[{"protected_history": 0, "n": 0}]]), + ) assert d.decision == "deny" # forbid(not formerly) denies when nothing happened @@ -323,7 +349,11 @@ async def test_deny_overrides_across_rules_and_detail_explains(): {"op": "count_within", "within": "1h", "operation": "b", "cmp": "gt", "value": 0}, pid="rate", ) - d = await P.evaluate([allow_rule, deny_rule], ctx(), FakeCH([[{"n": 1}], [{"n": 5}]])) + d = await P.evaluate( + [allow_rule, deny_rule], + ctx(), + FakeCH([[{"protected_history": 0, "n": 1}], [{"protected_history": 0, "n": 5}]]), + ) assert d.decision == "deny" and d.determining_rules == ["rate"] detail = d.to_detail() assert [r["policy_id"] for r in detail["rules"]] == ["ok", "rate"] diff --git a/tests/unit/test_policy_breadth.py b/tests/unit/test_policy_breadth.py index e0a15135b5..b8f9bc7399 100644 --- a/tests/unit/test_policy_breadth.py +++ b/tests/unit/test_policy_breadth.py @@ -95,7 +95,7 @@ def test_actor_pin_without_a_token_cannot_hold(): def test_evaluates_count_and_fraction_forms(): - ch = _CH([{"n": 120, "total": 1500}]) + ch = _CH([{"protected_history": 0, "n": 120, "total": 1500}]) out: list = [] leaf = rules.BreadthWithin(op="breadth_within", within="1h", cmp="gt", value=100) assert asyncio.run(pol._eval_leaf(leaf, _ctx(), ch, out)) is True @@ -106,7 +106,7 @@ def test_evaluates_count_and_fraction_forms(): leaf_f2 = rules.BreadthWithin(op="breadth_within", within="1h", cmp="gt", fraction=0.10) assert asyncio.run(pol._eval_leaf(leaf_f2, _ctx(), ch, out)) is False # Empty namespace: fraction is 0, never holds on gt. - ch0 = _CH([{"n": 0, "total": 0}]) + ch0 = _CH([{"protected_history": 0, "n": 0, "total": 0}]) assert asyncio.run(pol._eval_leaf(leaf_f, _ctx(), ch0, out)) is False @@ -119,9 +119,13 @@ def test_forbid_rule_denies_when_breadth_exceeds_the_budget(): "condition": {"op": "breadth_within", "within": "1h", "cmp": "gt", "fraction": 0.05}, } ) - verdict = asyncio.run(pol.evaluate_rule(rule, _ctx(), _CH([{"n": 90, "total": 1000}]))) + verdict = asyncio.run( + pol.evaluate_rule(rule, _ctx(), _CH([{"protected_history": 0, "n": 90, "total": 1000}])) + ) assert verdict.denies is True - verdict2 = asyncio.run(pol.evaluate_rule(rule, _ctx(), _CH([{"n": 40, "total": 1000}]))) + verdict2 = asyncio.run( + pol.evaluate_rule(rule, _ctx(), _CH([{"protected_history": 0, "n": 40, "total": 1000}])) + ) assert verdict2.denies is False diff --git a/tests/unit/test_policy_gate.py b/tests/unit/test_policy_gate.py index 0d980e3b54..cd3f1dff36 100644 --- a/tests/unit/test_policy_gate.py +++ b/tests/unit/test_policy_gate.py @@ -1,5 +1,5 @@ -"""The policy gate: off / shadow / enforce, fail-closed for -writes, fail-open for reads, exemptions, the ledger row, the 403 shape.""" +"""Ordinary history policies: modes, backend-error read/write posture, +exemptions, the ledger row and the 403 shape.""" from __future__ import annotations @@ -59,7 +59,7 @@ async def query_all(self, sql: str, params: dict[str, Any] | None = None): self.calls += 1 if self.fail: raise RuntimeError("clickhouse unreachable") - return [{"n": self.n}] + return [{"protected_history": 0, "n": self.n}] @pytest.fixture @@ -153,7 +153,7 @@ async def test_enforce_fails_closed_for_writes_when_history_cannot_be_read(monke @pytest.mark.asyncio -async def test_a_gate_that_cannot_read_its_rules_names_the_error_kind_only(monkeypatch): +async def test_a_gate_that_cannot_read_its_rules_names_the_error_kind_only(monkeypatch, rules): async def broken(*_a: Any, **_k: Any) -> Any: raise RuntimeError("SELECT * FROM loom.policies WHERE secret = 1") @@ -164,6 +164,7 @@ async def broken(*_a: Any, **_k: Any) -> Any: with pytest.raises(G.PolicyForbiddenError) as ei: await G.gate(WRITE_OP, IDENTITY, {}, ch=FakeCH(n=2)) finally: + await G.drain() P.invalidate() detail = ei.value.to_detail() assert detail["errors"] == ["policy gate: RuntimeError"] diff --git a/tests/unit/test_policy_graduated.py b/tests/unit/test_policy_graduated.py index 72157367a8..72601fa4af 100644 --- a/tests/unit/test_policy_graduated.py +++ b/tests/unit/test_policy_graduated.py @@ -54,7 +54,7 @@ def __init__(self, n=0, fail=False): async def query_all(self, sql, params=None): if self.fail: raise RuntimeError("clickhouse unreachable") - return [{"n": self.n}] + return [{"protected_history": 0, "n": self.n}] def ctx(op="memory.set"): diff --git a/tests/unit/test_private_diagnostics.py b/tests/unit/test_private_diagnostics.py index 994784b99c..3dd494db1a 100644 --- a/tests/unit/test_private_diagnostics.py +++ b/tests/unit/test_private_diagnostics.py @@ -149,7 +149,8 @@ async def test_private_spend_is_written_under_mirror_without_shared_accounting( async def insert(table: str, batch: list[dict[str, Any]], **kwargs: Any) -> None: assert diagnostics.codes_only() - assert table == "loom.agent_events" + assert table == "loom.agent_events_private" + assert kwargs["required_columns"] == frozenset({"mirror_marked"}) rows.extend(batch) monkeypatch.setattr(events, "get_client", lambda: SimpleNamespace(insert=insert)) diff --git a/tests/unit/test_private_event_cutover.py b/tests/unit/test_private_event_cutover.py new file mode 100644 index 0000000000..f41c3f8890 --- /dev/null +++ b/tests/unit/test_private_event_cutover.py @@ -0,0 +1,258 @@ +"""Analyst grants follow a complete writer fence, never a partial or stale census.""" + +from __future__ import annotations + +import asyncio +import copy +from contextlib import asynccontextmanager +from types import SimpleNamespace +from uuid import UUID + +import pytest + +from server.insights.domain.analysis import SettingNames +from server.insights.store import analysis, event_cutover + + +class WriterWorld: + def __init__(self) -> None: + self.servers = [str(UUID(int=1)), str(UUID(int=2))] + self.topology = [ + dict( + shard_num=1, + replica_num=i, + host_name=f"writer-{i}", + host_address=f"192.0.2.{i}", + port=9000, + user="service", + default_database="loom", + ) + for i in (1, 2) + ] + self.metadata = [ + dict( + server_uuid=uid, + named=1, + correct=1, + tables=[ + ("agent_events", str(UUID(int=10 + i)), "MergeTree"), + ("agent_events_private", str(UUID(int=20 + i)), "MergeTree"), + ], + ) + for i, uid in enumerate(self.servers) + ] + self.process_reads = 0 + self.census_reads = 0 + self.private_after_drain = False + self.pending_forever = False + self.change = "" + self.sent = [] + self.catalog = [(), ()] + self.observation_cache = {} + self.observer_servers = list(self.servers) + + @asynccontextmanager + async def policy_observers(self): + world = self + + class Observer: + def __init__(self, index): + self.index = index + self.server_uuid = world.observer_servers[index] + + user = "service" + roles = () + + async def policies(self): + return list(world.catalog[self.index]) + + async def query_all(self, sql, params=None): + if "AS topology" in sql: + return [ + { + "server_uuid": self.server_uuid, + "topology": [tuple(row.values()) for row in world.topology], + } + ] + if self.index == 0: + world.observation_cache[sql] = await world.query_all(sql, params) + return copy.deepcopy( + [ + row + for row in world.observation_cache[sql] + if row["server_uuid"] == self.server_uuid + ] + ) + + yield tuple(Observer(index) for index in range(len(self.observer_servers))) + + async def query_all(self, sql, params=None): + if "FROM system.clusters" in sql: + return copy.deepcopy(self.topology) + if sql.startswith("SELECT toString(serverUUID()) AS server_uuid SETTINGS"): + return [{"server_uuid": self.servers[0]}] + if "FROM system.tables" in sql: + return copy.deepcopy(self.metadata) + if "FROM system.processes" in sql: + self.process_reads += 1 + if self.process_reads > 1: + if self.change == "missing_writer": + return [{"server_uuid": self.servers[0], "inserts": []}] + if self.change == "topology": + self.topology.pop() + if self.change == "uuid": + self.metadata[0]["tables"][0] = ("agent_events", str(UUID(int=99)), "MergeTree") + if self.change == "cluster_missing": + raise RuntimeError("Code: 701. CLUSTER_DOESNT_EXIST") + old = ( + [("service", "old-insert")] + if self.process_reads == 1 or self.pending_forever + else [] + ) + return [ + {"server_uuid": self.servers[0], "inserts": old}, + # New inserts continue; their identities never join the frozen set. + { + "server_uuid": self.servers[1], + "inserts": [("service", "new-insert")] if self.process_reads > 1 else [], + }, + ] + if "AS private" in sql: + self.census_reads += 1 + assert self.process_reads >= 2 + return [ + {"server_uuid": uid, "private": int(self.private_after_drain)} + for uid in self.servers + ] + raise AssertionError(sql) + + async def execute(self, sql, **kwargs): + self.sent.append(sql) + + +@pytest.fixture +def world(monkeypatch): + monkeypatch.setattr(event_cutover, "settings", SimpleNamespace(ch_cluster="writers")) + return WriterWorld() + + +async def test_the_fence_drains_only_the_frozen_insert_set_before_counting(world): + await event_cutover.confirm_ordinary_events(ch=world) + assert world.process_reads == 2 and world.census_reads == 1 + assert world.sent == [] + + +async def test_private_rows_committed_by_an_old_insert_preserve_data_and_refuse_grants(world): + world.private_after_drain = True + statements = ["CREATE USER loom_analyst", "GRANT SELECT ON loom.agent_events TO loom_analyst"] + with pytest.raises(event_cutover.EventCutoverUnavailable): + await analysis.write_entities(statements, names=SettingNames("SQL_"), ch=world) + assert world.census_reads == 1 and world.sent == [] and world.private_after_drain + + +@pytest.mark.parametrize("change", ["missing_writer", "topology", "uuid", "cluster_missing"]) +async def test_writer_or_table_drift_never_counts_as_old_insert_completion(world, change): + world.change = change + with pytest.raises(event_cutover.EventCutoverUnavailable): + await event_cutover.confirm_ordinary_events(ch=world) + assert world.census_reads == 0 + + +@pytest.mark.parametrize( + "defect", ["hidden_table", "missing_check", "wrong_check", "duplicate_writer"] +) +async def test_incomplete_initial_attestation_cannot_start_a_census(world, defect): + if defect == "hidden_table": + world.metadata[0]["tables"].pop() + elif defect == "missing_check": + world.metadata[0]["named"] = world.metadata[0]["correct"] = 0 + elif defect == "wrong_check": + world.metadata[0]["correct"] = 0 + else: + world.metadata[1]["server_uuid"] = world.metadata[0]["server_uuid"] + with pytest.raises(event_cutover.EventCutoverUnavailable): + await event_cutover.confirm_ordinary_events(ch=world) + assert world.process_reads == world.census_reads == 0 + + +async def test_cutover_cancellation_is_not_a_success_or_a_retry(world, monkeypatch): + original = world.query_all + + async def query(sql, params=None): + if "FROM system.processes" in sql: + raise asyncio.CancelledError + return await original(sql, params) + + monkeypatch.setattr(world, "query_all", query) + with pytest.raises(asyncio.CancelledError): + await event_cutover.confirm_ordinary_events(ch=world) + assert world.census_reads == 0 and world.sent == [] + + +async def test_grants_follow_the_completed_census(world): + statements = ["GRANT SELECT ON loom.agent_events TO loom_analyst"] + await analysis.write_entities(statements, names=SettingNames("SQL_"), ch=world) + assert world.census_reads == 1 and world.sent == statements + + +async def test_a_surviving_old_insert_exhausts_the_budget_without_grants(world, monkeypatch): + world.pending_forever = True + monkeypatch.setattr(event_cutover, "_BUDGET_S", 0.02) + with pytest.raises(event_cutover.EventCutoverUnavailable): + await event_cutover.confirm_ordinary_events(ch=world) + assert world.process_reads > 0 and world.census_reads == 0 and world.sent == [] + + +@pytest.mark.parametrize( + "target", ["loom.agent_events", "system.processes", "system.row_policies", "loom.*"] +) +async def test_filtered_empty_results_with_valid_writer_uuids_cannot_authorize_grants( + world, target +): + # The normal SELECT interface can report clean aggregate UUID rows. The native + # access catalog still reveals the policy that made its population invisible. + world.catalog[1] = ( + f"CREATE ROW POLICY hidden_rows ON {target} AS RESTRICTIVE FOR SELECT USING 0 TO ALL", + ) + with pytest.raises(event_cutover.EventCutoverUnavailable): + await analysis.write_entities( + ["GRANT SELECT ON loom.agent_events TO loom_analyst"], + names=SettingNames("SQL_"), + ch=world, + ) + assert world.process_reads == world.census_reads == 0 + assert not world.sent + + +@pytest.mark.parametrize("defect", ["missing", "duplicate", "extra", "unexpected"]) +async def test_direct_observer_routes_must_cover_each_actual_writer_exactly_once(world, defect): + if defect == "missing": + world.observer_servers.pop() + elif defect == "duplicate": + world.observer_servers[1] = world.observer_servers[0] + elif defect == "extra": + world.observer_servers.append(str(UUID(int=3))) + else: + world.observer_servers[1] = str(UUID(int=3)) + with pytest.raises(event_cutover.EventCutoverUnavailable): + await event_cutover.confirm_ordinary_events(ch=world) + assert world.process_reads == world.census_reads == 0 and not world.sent + + +async def test_policy_drift_during_the_old_insert_drain_cannot_reuse_clean_visibility( + world, monkeypatch +): + original = world.query_all + + async def change_catalog(sql, params=None): + rows = await original(sql, params) + if "FROM system.processes" in sql: + world.catalog[1] = ( + "CREATE ROW POLICY hidden ON system.processes AS RESTRICTIVE FOR SELECT USING 0 TO ALL", + ) + return rows + + monkeypatch.setattr(world, "query_all", change_catalog) + with pytest.raises(event_cutover.EventCutoverUnavailable): + await event_cutover.confirm_ordinary_events(ch=world) + assert world.census_reads == 0 and not world.sent diff --git a/tests/unit/test_private_source_sync.py b/tests/unit/test_private_source_sync.py index b423f33c77..aeb7f8df1c 100644 --- a/tests/unit/test_private_source_sync.py +++ b/tests/unit/test_private_source_sync.py @@ -80,7 +80,7 @@ async def upsert(*args: Any, **kwargs: Any) -> Any: async def insert(table: str, batch: list[dict[str, Any]], **kwargs: Any) -> None: assert diagnostics.codes_only() - assert table == "loom.agent_events" + assert table == "loom.agent_events_private" rows.extend(batch) monkeypatch.setattr(writes, "handle_knowledge_upsert", upsert) diff --git a/tests/unit/test_promote_definition.py b/tests/unit/test_promote_definition.py index 000e002b3a..79a1dea125 100644 --- a/tests/unit/test_promote_definition.py +++ b/tests/unit/test_promote_definition.py @@ -193,6 +193,17 @@ async def test_an_empty_approver_sent_is_named_ignored(store: dict[str, Any]) -> assert out.ignored_args == ["approver"] +async def test_review_provenance_comes_only_from_the_internal_call(store: dict[str, Any]) -> None: + cid = "00000000-0000-0000-0000-000000000001" + out = await promote.handle_memory_promote( + _input(promoted_from_candidate_id="untrusted"), reviewed_candidate_id=cid + ) + (row,) = store["written"] + assert row["promoted_from_candidate_id"] == cid + assert row["promoted_by"] == "user:admin" + assert out.ignored_args == ["promoted_from_candidate_id"] + + async def test_a_definition_promotion_needs_its_approved_hash(store: dict[str, Any]) -> None: assert await _refusal(store, approved_sha256=None) == "VALIDATION_FAILED" with pytest.raises(PreconditionFailedError) as e: diff --git a/tests/unit/test_query_history_registry_erasure.py b/tests/unit/test_query_history_registry_erasure.py new file mode 100644 index 0000000000..61efe684ad --- /dev/null +++ b/tests/unit/test_query_history_registry_erasure.py @@ -0,0 +1,335 @@ +"""Registry sends and namespace erasure cannot cross an unacknowledged write.""" + +from __future__ import annotations + +import asyncio +from contextlib import asynccontextmanager +from datetime import datetime +from types import SimpleNamespace +from typing import Any +from unittest.mock import AsyncMock + +import pytest + +from server.core import leases +from server.core.errors import BackendUnavailableError, ValidationError +from server.erasure.store import steps_ledgers +from server.knowledge.api.models_query_history import ( + QueryHistoryAddInput, + QueryHistoryListInput, + QueryHistoryRemoveInput, +) +from server.knowledge.app import query_history_sources as sources +from tests.unit.definition_queue_fake import install + + +@pytest.fixture +def registry(monkeypatch: pytest.MonkeyPatch) -> Any: + state = SimpleNamespace( + rows=[], pending=None, fence=install(monkeypatch), failure=None, version=0, clock=1000 + ) + + async def find(*args: Any) -> Any: + return dict(state.rows[-1]) if state.rows else None + + async def insert(row: Any) -> None: + state.pending = dict(row) + if state.failure: + raise state.failure + state.rows.append(dict(row)) + + async def version(*args: Any) -> int: + state.version += 1 + return state.version + + async def delete(*args: Any, **kw: Any) -> int: + assert args[0] == "loom.query_history_sources" + count = len(state.rows) + state.rows.clear() + return count + + async def probe(*args: Any) -> None: + assert state.fence.holders == {} # remote I/O does not hold the org writer fence + + @asynccontextmanager + async def claim(*args: Any, **kw: Any) -> Any: + yield True + + monkeypatch.setattr(leases, "holding", claim) + monkeypatch.setattr(sources.settings, "knowledge_query_history_enabled", True) + monkeypatch.setattr(sources, "require_draft_fleet", AsyncMock()) + monkeypatch.setattr(sources, "probe", probe) + monkeypatch.setattr(sources, "seal", lambda *args: "sealed-password") + monkeypatch.setattr(sources, "writer_actor", lambda *args: "user:admin") + monkeypatch.setattr(sources.time, "time", lambda: state.clock) + monkeypatch.setattr(sources.repo, "find", find) + monkeypatch.setattr(sources.repo, "list_sources", AsyncMock(return_value=[])) + monkeypatch.setattr(sources.repo, "next_source_version", version) + monkeypatch.setattr(sources.repo, "insert", insert) + monkeypatch.setattr(steps_ledgers, "delete_scoped", delete) + return state + + +def registration() -> QueryHistoryAddInput: + return QueryHistoryAddInput( + org="o", + namespace="n", + name="sales", + host="db.example", + user="reader", + password="secret", + databases=["sales"], + ) + + +async def change(registry: Any, kind: str) -> Any: + if kind == "add": + return await sources.handle_add(registration()) + if not registry.rows: + registry.rows.append( + { + **registration().model_dump(exclude={"password"}), + "source_id": "source", + "created_at": datetime(2026, 1, 1), + "password_enc": "sealed-password", + "tombstoned_at": None, + "version": 1, + } + ) + return await sources.handle_remove( + QueryHistoryRemoveInput(org="o", namespace="n", name="sales") + ) + + +async def erase(registry: Any) -> int: + registry.fence.erasures = [{"scope_type": "namespace_list", "scope_value": '["n", "other"]'}] + return await steps_ledgers.delete_query_history_by_namespace("o", ["n", "other"]) + + +@pytest.mark.parametrize("kind", ["add", "remove"]) +@pytest.mark.parametrize("failure", [TimeoutError, asyncio.CancelledError]) +async def test_uncertain_registry_send_excludes_namespace_list_erasure( + registry: Any, kind: str, failure: type[BaseException] +) -> None: + registry.failure = failure() + with pytest.raises(failure): + await change(registry, kind) + with pytest.raises(BackendUnavailableError): + await erase(registry) + registry.rows.append(registry.pending) # the server admits the already-sent row + registry.fence.holders.clear() # its server deadline has elapsed before takeover + await erase(registry) + assert registry.rows == [] + + +@pytest.mark.parametrize("kind", ["add", "remove"]) +async def test_registry_read_before_completed_erasure_cannot_restore_metadata( + registry: Any, monkeypatch: pytest.MonkeyPatch, kind: str +) -> None: + version = sources.repo.next_source_version + erased = False + + async def stale(*args: Any) -> int: + nonlocal erased + result = await version(*args) + if not erased: + erased = True + await erase(registry) + return result + + monkeypatch.setattr(sources.repo, "next_source_version", stale) + with pytest.raises(ValidationError, match="eras"): + await change(registry, kind) + assert registry.rows == [] + + +async def test_registration_start_precedes_its_first_await( + registry: Any, monkeypatch: pytest.MonkeyPatch +) -> None: + async def fleet() -> None: + registry.clock = 1200 # erasure at 1100 completes during the first fleet read + + async def erased(org: str, namespace: str, started: int, askers: Any) -> bool: + return started <= 1100 + + monkeypatch.setattr(sources, "require_draft_fleet", fleet) + monkeypatch.setattr(sources, "erasure_since", erased) + with pytest.raises(ValidationError, match="eras"): + await change(registry, "add") + assert registry.rows == [] + + +async def test_registry_roundtrip_preserves_sealing_and_clears_credential_on_remove( + registry: Any, +) -> None: + added = await change(registry, "add") + assert "password" not in added.model_dump() and "password_enc" not in added.model_dump() + assert registry.rows[0]["password_enc"] == "sealed-password" + assert registry.rows[0]["actor"] == "user:admin" + result = await change(registry, "remove") + assert result.removed and registry.rows[-1]["password_enc"] == "" + assert registry.rows[-1]["tombstoned_at"] is not None + assert registry.rows[-1]["version"] > registry.rows[0]["version"] + + +@pytest.mark.parametrize("kind", ["add", "remove"]) +async def test_registry_eraser_cannot_finish_during_an_admitted_insert( + registry: Any, monkeypatch: pytest.MonkeyPatch, kind: str +) -> None: + entered, resume = asyncio.Event(), asyncio.Event() + insert = sources.repo.insert + + async def paused(row: Any) -> None: + entered.set() + await resume.wait() + await insert(row) + + monkeypatch.setattr(sources.repo, "insert", paused) + writer = asyncio.create_task(change(registry, kind)) + try: + await asyncio.wait_for(entered.wait(), 1) + with pytest.raises(BackendUnavailableError): + await erase(registry) + finally: + resume.set() + await writer + await erase(registry) + assert registry.rows == [] + + +async def test_registry_ledger_failure_refuses_without_sending_or_retaining_a_write( + registry: Any, +) -> None: + registry.fence.failure = RuntimeError("ledger unavailable") + with pytest.raises(ValidationError, match="eras"): + await change(registry, "add") + assert registry.pending is None and registry.rows == [] and registry.fence.holders == {} + + +async def test_remove_missing_source_stays_a_noop(registry: Any) -> None: + result = await sources.handle_remove( + QueryHistoryRemoveInput(org="o", namespace="n", name="absent") + ) + assert not result.removed and registry.pending is None and registry.fence.reads == [] + + +async def test_registered_source_still_requires_explicit_removal(registry: Any) -> None: + await change(registry, "add") + original = [dict(row) for row in registry.rows] + with pytest.raises(ValidationError, match="already|registered"): + await change(registry, "add") + assert registry.rows == original + + +async def test_removal_start_precedes_its_first_claim_await( + registry: Any, monkeypatch: pytest.MonkeyPatch +) -> None: + @asynccontextmanager + async def claim(*args: Any, **kw: Any) -> Any: + registry.clock = 1200 + yield True + + async def erased(org: str, namespace: str, started: int, askers: Any) -> bool: + return started <= 1100 + + monkeypatch.setattr(leases, "holding", claim) + monkeypatch.setattr(sources, "erasure_since", erased) + with pytest.raises(ValidationError, match="eras"): + await change(registry, "remove") + assert registry.pending is None + + +async def test_source_projection_preserves_identity_and_refuses_credentials( + registry: Any, monkeypatch: pytest.MonkeyPatch +) -> None: + await change(registry, "add") + monkeypatch.setattr(sources.repo, "list_sources", AsyncMock(return_value=registry.rows)) + whole = await sources.handle_list(QueryHistoryListInput(org="o", namespace="n")) + assert whole.model_dump()["sources"][0]["host"] == "db.example" + selected = await sources.handle_list( + QueryHistoryListInput(org="o", namespace="n", fields=["host"]) + ) + assert selected.model_dump()["sources"] == [ + {"name": "sales", "source_id": registry.rows[0]["source_id"], "host": "db.example"} + ] + with pytest.raises(ValidationError, match="unknown output field"): + await sources.handle_list( + QueryHistoryListInput(org="o", namespace="n", fields=["password_enc"]) + ) + + +async def test_recent_source_keeps_its_open_circuit_when_cache_evicts_an_older_source( + monkeypatch: pytest.MonkeyPatch, +) -> None: + from collections import OrderedDict + + from server.knowledge.store import query_history_remote as remote + + @asynccontextmanager + async def connection(source: Any) -> Any: + yield object() + + monkeypatch.setattr(remote, "_BREAKERS", OrderedDict()) + monkeypatch.setattr(remote, "connection", connection) + query = AsyncMock(return_value=[]) + monkeypatch.setattr(remote, "query", query) + monkeypatch.setattr(remote.settings, "knowledge_query_history_max_breakers", 2) + monkeypatch.setattr(remote.settings, "tracker_circuit_failure_threshold", 1) + rows = {name: {"source_id": name, "cluster": "", "databases": ["sales"]} for name in "abc"} + await remote.read_groups(rows["a"]) + query.side_effect = ValidationError("refused source") + with pytest.raises(ValidationError): + await remote.read_groups(rows["b"]) + query.side_effect = None + await remote.read_groups(rows["c"]) + before = query.await_count + assert await remote.read_groups(rows["b"]) == [] + assert query.await_count == before + await remote.read_groups(rows["a"]) + assert query.await_count == before + 1 + + +async def test_remote_group_read_applies_the_history_window_and_group_bound( + monkeypatch: pytest.MonkeyPatch, +) -> None: + from collections import OrderedDict + + from server.knowledge.store import query_history_remote as remote + + @asynccontextmanager + async def connection(source: Any) -> Any: + yield object() + + monkeypatch.setattr(remote, "_BREAKERS", OrderedDict()) + monkeypatch.setattr(remote, "connection", connection) + read = AsyncMock(return_value=[{"query_hash": 1}]) + monkeypatch.setattr(remote, "query", read) + monkeypatch.setattr(remote.settings, "knowledge_query_history_max_groups", 1) + monkeypatch.setattr(remote.settings, "knowledge_query_history_window_days", 2) + assert await remote.read_groups( + {"source_id": "source", "cluster": "", "databases": ["sales"]} + ) == [{"query_hash": 1}] + assert read.await_args.args[2] == { + "cluster": "", + "databases": ["sales"], + "days": 2, + "k": 3, + "lim": 1, + } + + +async def test_remote_query_cancels_at_the_configured_read_deadline( + monkeypatch: pytest.MonkeyPatch, +) -> None: + from server.knowledge.store import query_history_remote as remote + + waiting = asyncio.Event() + + async def blocked(*args: Any, **kw: Any) -> Any: + await waiting.wait() + + client = SimpleNamespace(query=AsyncMock(side_effect=blocked)) + monkeypatch.setattr(remote.settings, "knowledge_query_history_read_timeout_s", 0.001) + with pytest.raises(TimeoutError): + await remote.query(client, "SELECT 1") + client.query.assert_awaited_once() diff --git a/tests/unit/test_query_history_worker.py b/tests/unit/test_query_history_worker.py new file mode 100644 index 0000000000..36c45442e0 --- /dev/null +++ b/tests/unit/test_query_history_worker.py @@ -0,0 +1,174 @@ +"""Source rotation and live privacy policy remain valid across awaited work.""" + +import time +import uuid +from contextlib import nullcontext +from types import SimpleNamespace +from typing import Any +from unittest.mock import AsyncMock + +import pytest + +from server.knowledge.workers import query_history as worker +from server.workers import pass_context + + +@pytest.fixture +def source(monkeypatch: pytest.MonkeyPatch) -> Any: + row = { + "org": "o", + "namespace": "n", + "name": "🙂" * 100, + "source_id": str(uuid.uuid4()), + "tombstoned_at": None, + } + monkeypatch.setattr(worker.settings, "knowledge_query_history_enabled", True) + monkeypatch.setattr(worker.settings, "knowledge_query_history_min_users", 3) + monkeypatch.setattr(worker, "require_draft_fleet", AsyncMock()) + monkeypatch.setattr(worker, "namespace_over_cap", AsyncMock(return_value=False)) + monkeypatch.setattr(worker, "erasure_since", AsyncMock(return_value=False)) + monkeypatch.setattr(worker.repo, "find", AsyncMock(return_value=row)) + monkeypatch.setattr(worker, "already_claimed", AsyncMock(return_value=False)) + monkeypatch.setattr(worker, "emit_worker_cost_event_for", lambda **kw: None) + pass_context.begin("query_history") + yield row + pass_context.clear() + + +@pytest.mark.asyncio +async def test_unicode_source_name_cannot_truncate_rotation( + source: Any, + monkeypatch: pytest.MonkeyPatch, +) -> None: + monkeypatch.setattr(worker.repo, "active_after", AsyncMock(return_value=[source])) + monkeypatch.setattr(worker, "_source", AsyncMock(return_value=0)) + monkeypatch.setattr(worker, "record_pass", lambda name: nullcontext(SimpleNamespace())) + await worker.run_pass() + saved = pass_context.current().cursor + assert saved == source["source_id"] + pass_context.begin("query_history", resume_cursor=saved) + assert worker._cursor() == source["source_id"] + await worker.run_pass() + assert worker.repo.active_after.await_args.args[0] == source["source_id"] + + +@pytest.mark.asyncio +async def test_exhausted_rotation_persists_a_nonempty_start_cursor( + source: Any, + monkeypatch: pytest.MonkeyPatch, +) -> None: + pass_context.begin("query_history", resume_cursor=source["source_id"]) + monkeypatch.setattr(worker.repo, "active_after", AsyncMock(return_value=[])) + monkeypatch.setattr(worker, "record_pass", lambda name: nullcontext(SimpleNamespace())) + await worker.run_pass() + saved = pass_context.current().cursor + assert saved == str(uuid.UUID(int=0)) + pass_context.begin("query_history", resume_cursor=saved) + assert worker._cursor() == saved + + +@pytest.mark.asyncio +@pytest.mark.parametrize("during_model", [False, True]) +async def test_live_threshold_increase_invalidates_inflight_group( + source: Any, + monkeypatch: pytest.MonkeyPatch, + during_model: bool, +) -> None: + group = {"query_hash": 1, "template_hash": 2, "users": 3, "sql": "SELECT sum(x) FROM t"} + + async def read(row: Any) -> Any: + if not during_model: + monkeypatch.setattr(worker.settings, "knowledge_query_history_min_users", 4) + return [group] + + async def draft(*args: Any, **kwargs: Any) -> str: + assert await kwargs["still_valid"]() + monkeypatch.setattr(worker.settings, "knowledge_query_history_min_users", 4) + assert not await kwargs["still_valid"]() + return "candidate" + + model = AsyncMock(side_effect=draft) + monkeypatch.setattr(worker, "read_groups", read) + monkeypatch.setattr(worker, "draft", model) + await worker._source(source, time.monotonic() + 60) + assert model.await_count == int(during_model) + + +@pytest.mark.asyncio +async def test_gap_draft_invalidates_evidence_when_live_threshold_increases( + monkeypatch: pytest.MonkeyPatch, +) -> None: + from server.knowledge.api.models_gaps import KnowledgeGapsDraftInput + from server.knowledge.app import gap_drafts + + monkeypatch.setattr(gap_drafts.settings, "knowledge_gaps_enabled", True) + monkeypatch.setattr(gap_drafts.settings, "knowledge_gaps_min_askers", 3) + monkeypatch.setattr( + gap_drafts.capture_consent, "level_uncached", AsyncMock(return_value="full") + ) + monkeypatch.setattr(gap_drafts.gaps, "erasure_since", AsyncMock(return_value=False)) + monkeypatch.setattr( + gap_drafts.repo, "gap_for_draft", AsyncMock(return_value={"head": "revenue", "samples": []}) + ) + monkeypatch.setattr(gap_drafts.repo, "draft_queries", AsyncMock(return_value=["revenue"])) + + async def draft(*args: Any, **kwargs: Any) -> str: + assert await kwargs["still_valid"]() + monkeypatch.setattr(gap_drafts.settings, "knowledge_gaps_min_askers", 4) + assert not await kwargs["still_valid"]() + return "candidate" + + monkeypatch.setattr(gap_drafts, "draft", draft) + result = await gap_drafts.handle_gap_draft( + KnowledgeGapsDraftInput(org="o", namespace="n", gap_id="g") + ) + assert result.candidate_id == "candidate" + + +async def test_source_stops_at_the_configured_draft_limit( + source: Any, monkeypatch: pytest.MonkeyPatch +) -> None: + monkeypatch.setattr(worker.settings, "knowledge_query_history_max_drafts", 1) + groups = [ + {"query_hash": i, "template_hash": i, "users": 3, "sql": "SELECT x FROM t"} for i in [1, 2] + ] + monkeypatch.setattr(worker, "read_groups", AsyncMock(return_value=groups)) + model = AsyncMock(return_value="candidate") + monkeypatch.setattr(worker, "draft", model) + assert await worker._source(source, time.monotonic() + 30) == 1 + assert model.await_count == 1 + + +async def test_pass_bounds_source_selection_and_starts_no_work_after_its_deadline( + source: Any, monkeypatch: pytest.MonkeyPatch +) -> None: + clock = {"now": 100.0} + monkeypatch.setattr(worker, "time", SimpleNamespace(monotonic=lambda: clock["now"])) + monkeypatch.setattr(worker.settings, "knowledge_query_history_max_sources", 2) + monkeypatch.setattr(worker.settings, "knowledge_query_history_max_pass_seconds", 6.0) + + async def loaded(*args: Any) -> Any: + clock["now"] = 104.0 + return [source] + + monkeypatch.setattr(worker.repo, "active_after", AsyncMock(side_effect=loaded)) + turn = AsyncMock(return_value=0) + monkeypatch.setattr(worker, "_source", turn) + monkeypatch.setattr(worker, "record_pass", lambda name: nullcontext(SimpleNamespace())) + assert await worker.run_pass() == {"sources": 0, "attempted": 0} + assert worker.repo.active_after.await_args.args[1] == 2 + turn.assert_not_awaited() + + +def test_query_history_registry_uses_the_configured_cadence_and_deadline( + monkeypatch: pytest.MonkeyPatch, +) -> None: + from server.workers.registry import enabled_workers + + monkeypatch.setattr(worker.settings, "knowledge_query_history_enabled", True) + monkeypatch.setattr(worker.settings, "knowledge_query_history_interval_seconds", 1234) + monkeypatch.setattr(worker.settings, "knowledge_query_history_max_pass_seconds", 90.0) + spec = next(s for s in enabled_workers() if s.name == "query_history") + assert spec.interval_seconds == 1234 + assert spec.max_pass_seconds == 90.0 + assert spec.pass_callable is worker.run_pass diff --git a/tests/unit/test_raw_routes_restricted_audit.py b/tests/unit/test_raw_routes_restricted_audit.py index 53c5385b14..ef0ae55984 100644 --- a/tests/unit/test_raw_routes_restricted_audit.py +++ b/tests/unit/test_raw_routes_restricted_audit.py @@ -385,7 +385,8 @@ class _Delegated: def writes(self, namespace: str) -> bool: return False # a viewer token: it saves nowhere - def mint(self, subject: str) -> str: + def mint(self, subject: str, *, reads_as_creator: bool = False) -> str: + assert reads_as_creator is False # Ordinary service accounts do not identify a reader. return "jwt" def expires_at(self, now: Any) -> None: diff --git a/tests/unit/test_read_scope_admission.py b/tests/unit/test_read_scope_admission.py index 540a0c4f59..57700553ea 100644 --- a/tests/unit/test_read_scope_admission.py +++ b/tests/unit/test_read_scope_admission.py @@ -264,6 +264,8 @@ def test_a_write_under_an_unresolved_scope_is_refused() -> None: "knowledge.add", "knowledge.bulk_add", "knowledge.ingest", + "knowledge.source.push_configure", + "knowledge.synthesize", "knowledge.upsert", "memory.bulk_set", "memory.delete", diff --git a/tests/unit/test_relevance_gate.py b/tests/unit/test_relevance_gate.py index 72f534228d..55dbe93c43 100644 --- a/tests/unit/test_relevance_gate.py +++ b/tests/unit/test_relevance_gate.py @@ -64,7 +64,7 @@ def ask_env(monkeypatch: pytest.MonkeyPatch) -> SimpleNamespace: async def fake_search(search_input: Any) -> MemorySearchOutput: return MemorySearchOutput(results=env.hits, embedding_model="fake-embed") - async def fake_over_cap(org: str, ns: str) -> bool: + async def fake_over_cap(org: str, ns: str, *, user_id: str = "") -> bool: return False monkeypatch.setattr(hsearch, "handle_memory_search", fake_search) diff --git a/tests/unit/test_reliance_split.py b/tests/unit/test_reliance_split.py index 1ff38fec1e..5c426c6d32 100644 --- a/tests/unit/test_reliance_split.py +++ b/tests/unit/test_reliance_split.py @@ -498,13 +498,13 @@ def test_admin_consumers_window_carries_the_tagging_rows(monkeypatch: pytest.Mon app.include_router(admin_router) client = TestClient(app) - async def _consumers(since, limit, *, org=None, ch=None): + async def _consumers(since, limit, *, org=None, operator=False, ch=None): return [] async def _outcomes(since, limit, *, org=None, ch=None): return [] - async def _tagging(since, limit, *, org=None, ch=None): + async def _tagging(since, limit, *, org=None, operator=False, ch=None): return [ { "org": "clickhouse", diff --git a/tests/unit/test_repo_docs.py b/tests/unit/test_repo_docs.py index b335de8d5b..d693476b0c 100644 --- a/tests/unit/test_repo_docs.py +++ b/tests/unit/test_repo_docs.py @@ -53,6 +53,25 @@ def _hit(uri: str, score: float, ns: str = "", chunk: int = 0) -> _SearchHit: ) +@pytest.fixture(autouse=True) +def _resolved_searches(monkeypatch): + from server.knowledge.app import knowledge_search, source_access + + async def resolve(inp): + return knowledge_search.SearchRequest(inp.model_copy(deep=True), (inp.namespace,), ()) + + async def prepare(org, namespaces): + return source_access.ReadPlan(org) + + async def run(request, plan): + out = await knowledge_search.handle_knowledge_search(request.input) + return knowledge_search.CheckedSearch(out, None, SimpleNamespace(marked=False), [], 0) + + monkeypatch.setattr(knowledge_search, "resolve_search", resolve) + monkeypatch.setattr(knowledge_search, "run_checked_search", run) + monkeypatch.setattr(source_access, "prepare", prepare) + + @pytest.fixture(autouse=True) def _repos(monkeypatch): monkeypatch.setattr(repos, "configured_repos", lambda: list(ENTRIES)) @@ -198,7 +217,9 @@ async def test_a_slow_repository_search_answers_nothing(monkeypatch) -> None: "server.knowledge.app.knowledge_search.handle_knowledge_search", _search(base_only, delay=0.05), ) - assert await rd.search_repo_docs(ORG, "code-kj", "q", 3, timeout_s=0.01) == [] + monkeypatch.setattr(rd.settings, "knowledge_repo_docs_timeout_s", 0.01) + out = await rd.knowledge_with_repo_docs(BASE, repo_namespace="code-kj") + assert out.results == [] def test_a_hit_both_legs_return_is_listed_once() -> None: @@ -233,20 +254,36 @@ def test_the_pack_section_names_each_doc_within_its_budget() -> None: @pytest.mark.asyncio async def test_the_orientation_pack_appends_the_docs_and_caches_the_listing(monkeypatch) -> None: from server.code.app import context as cc + from server.knowledge.app import document_reads, source_access listed: list[str] = [] - async def handle_knowledge_list(inp): - listed.append(inp.namespace) + async def resolve(inp): + return document_reads.ListRequest(inp, (inp.namespace,), None) + + async def prepare(org, namespaces): + assert namespaces == ["code-kj"] + return source_access.ReadPlan(org) + + async def run(request, plan): + listed.append(request.input.namespace) + assert plan.org == ORG and not plan.marked return SimpleNamespace( - rows=[ - SimpleNamespace(source_uri="doc://runbook", title="On-call runbook", description="") - ] + output=SimpleNamespace( + rows=[ + SimpleNamespace( + source_uri="doc://runbook", title="On-call runbook", description="" + ) + ] + ), + marked=False, + lost=False, + proofs=None, ) - monkeypatch.setattr( - "server.knowledge.app.document_reads.handle_knowledge_list", handle_knowledge_list - ) + monkeypatch.setattr(document_reads, "resolve_list", resolve) + monkeypatch.setattr(source_access, "prepare", prepare) + monkeypatch.setattr(document_reads, "run_checked_list", run) monkeypatch.setattr("server.code.app.repo_scope.row_in_scope", _gate({"code-kj"})) out = await cc._with_repo_docs(ORG, "code-kj-26-7", "# map", 2500) assert out.startswith("# map\n\n## Repository docs (code-kj)") diff --git a/tests/unit/test_repository_column_sets_match_schema.py b/tests/unit/test_repository_column_sets_match_schema.py index 100b75ed3c..b1a5bc7f2d 100644 --- a/tests/unit/test_repository_column_sets_match_schema.py +++ b/tests/unit/test_repository_column_sets_match_schema.py @@ -10,14 +10,17 @@ from __future__ import annotations import importlib +from dataclasses import asdict from typing import Any import pytest -from tests.unit.schema_ddl import column_names +from tests.unit.ch_fake import RecordingCH +from tests.unit.schema_ddl import column_names, columns # (repository module, constant, table, columns the DDL fills and no writer sends) CASES: list[tuple[str, str, str, frozenset[str]]] = [ + ("server.knowledge.store.query_history", "_COLUMNS", "loom.query_history_sources", frozenset()), ( "server.tracker.store.daily", "TRACKER_TEST_DAILY_COLS", @@ -102,3 +105,33 @@ def test_the_column_set_is_the_tables( assert len(cols) == len(set(cols)), f"{const} repeats a column" schema = set(column_names(table.removeprefix("loom."), materialized=False)) assert set(cols) == schema - ddl_only, set(cols) ^ (schema - ddl_only) + + +async def test_source_push_put_carries_every_persisted_registration_column() -> None: + from server.knowledge.domain.source_push import PushRegistration + from server.knowledge.store import source_push + + registration = PushRegistration( + org="o", + namespace="n", + name="notes", + source_id="source-id", + provider="notion", + generation="generation", + fingerprint="fingerprint", + provider_id="workspace", + status="active", + secret_enc="sealed", + agent="agent", + user_id="user", + session_id="session", + actor="process:writer", + ) + ch = RecordingCH() + await source_push.put(registration, ch=ch) # type: ignore[arg-type] + [row] = ch.inserted("knowledge_source_push") + assert row == {**asdict(registration), "source_class": "derived"} + schema = columns("knowledge_source_push", materialized=False) + assert set(row) == set(schema) - {"updated_at", "version"} + assert schema["updated_at"] == "DateTime64(3) DEFAULT now64(3)" + assert schema["version"] == "UInt64 DEFAULT toUInt64(toUnixTimestamp64Nano(now64(9)))" diff --git a/tests/unit/test_required_insert_columns.py b/tests/unit/test_required_insert_columns.py new file mode 100644 index 0000000000..236d350388 --- /dev/null +++ b/tests/unit/test_required_insert_columns.py @@ -0,0 +1,184 @@ +"""Required ledger classification survives schema projection and retries.""" + +from __future__ import annotations + +import copy +from types import SimpleNamespace + +import pytest + +from server.core import ch as ch_mod + +TABLE = "loom.agent_events" +REQUIRED = frozenset({"mirror_marked"}) + + +class Driver: + def __init__(self, live): + self.live = dict(live) + self.attempts = [] + self.committed = [] + self.describes = 0 + self.describe_error = False + self.remove_marker_on_first_send = False + self.remove_input_marker_on_first_send = None + + async def query(self, sql, parameters=None, settings=None): + assert sql.startswith("DESCRIBE TABLE ") + self.describes += 1 + if self.describe_error: + raise RuntimeError("Code: 16. DB::Exception: metadata unavailable") + return SimpleNamespace(column_names=["name", "type"], result_rows=list(self.live.items())) + + async def insert(self, table, data, *, column_names, column_type_names, settings): + attempt = dict( + table=table, + columns=list(column_names), + data=copy.deepcopy(data), + types=copy.deepcopy(column_type_names), + settings=dict(settings), + ) + self.attempts.append(attempt) + if self.remove_marker_on_first_send and len(self.attempts) == 1: + del self.live["mirror_marked"] + if self.remove_input_marker_on_first_send is not None and len(self.attempts) == 1: + self.remove_input_marker_on_first_send[0].pop("mirror_marked") + unknown = set(column_names) - self.live.keys() + if unknown: + raise RuntimeError(f"Code: 16. DB::Exception: No such column {sorted(unknown)[0]}") + self.committed.extend(dict(zip(column_names, row, strict=True)) for row in data) + + +@pytest.fixture +def world(monkeypatch): + driver = Driver({"id": "UInt64", "mirror_marked": "UInt8"}) + monkeypatch.setattr(ch_mod, "_COLUMN_TYPES", {}) + monkeypatch.setattr(ch_mod, "_PROJECTION_WARNED", set()) + monkeypatch.setattr(ch_mod, "_INSERT_OBSERVERS", []) + monkeypatch.setattr(ch_mod.CHClient, "client", property(lambda self: driver)) + + async def table_present(*args, **kwargs): + pass + + monkeypatch.setattr(ch_mod, "guard_pending_schema", table_present) + return SimpleNamespace(driver=driver, client=ch_mod.CHClient()) + + +@pytest.mark.parametrize("cached_marker", [False, True]) +@pytest.mark.parametrize("live_marker", [False, True]) +async def test_required_marker_cannot_be_projected_away_by_cached_or_live_schema( + world, cached_marker, live_marker +): + cached = {"id": "UInt64"} + if cached_marker: + cached["mirror_marked"] = "UInt8" + ch_mod._COLUMN_TYPES[TABLE] = cached + if not live_marker: + del world.driver.live["mirror_marked"] + rows = [{"id": 7, "mirror_marked": 1, "optional_future": "unused"}] + if live_marker: + await world.client.insert(TABLE, rows, required_columns=REQUIRED) + assert world.driver.committed == [{"id": 7, "mirror_marked": 1}] + if not cached_marker: + assert world.driver.attempts[0]["types"] is None + else: + with pytest.raises(RuntimeError, match="No such column mirror_marked"): + await world.client.insert(TABLE, rows, required_columns=REQUIRED) + assert world.driver.committed == [] + assert world.driver.attempts + assert all("mirror_marked" in attempt["columns"] for attempt in world.driver.attempts) + assert all("optional_future" not in attempt["columns"] for attempt in world.driver.attempts) + assert (TABLE, "mirror_marked") not in ch_mod._PROJECTION_WARNED + + +@pytest.mark.parametrize("live_marker", [False, True]) +async def test_unreadable_metadata_delegates_required_column_validation_to_driver( + world, live_marker +): + world.driver.describe_error = True + if not live_marker: + del world.driver.live["mirror_marked"] + rows = [{"id": 7, "mirror_marked": 1}] + if live_marker: + await world.client.insert(TABLE, rows, required_columns=REQUIRED) + assert world.driver.committed == rows + else: + with pytest.raises(RuntimeError, match="No such column mirror_marked"): + await world.client.insert(TABLE, rows, required_columns=REQUIRED) + assert world.driver.committed == [] + assert all(attempt["columns"] == ["id", "mirror_marked"] for attempt in world.driver.attempts) + assert all(attempt["types"] is None for attempt in world.driver.attempts) + + +async def test_retry_after_schema_change_never_downgrades_marker_or_changes_batch_token(world): + world.driver.remove_marker_on_first_send = True + with pytest.raises(RuntimeError, match="No such column mirror_marked"): + await world.client.insert(TABLE, [{"id": 7, "mirror_marked": 1}], required_columns=REQUIRED) + assert world.driver.committed == [] + assert len(world.driver.attempts) == 2 + assert all(a["columns"] == ["id", "mirror_marked"] for a in world.driver.attempts) + assert all(a["data"] == [[7, 1]] for a in world.driver.attempts) + tokens = {a["settings"]["insert_deduplication_token"] for a in world.driver.attempts} + assert len(tokens) == 1 + + +async def test_row_mutation_during_failed_send_cannot_create_a_marker_free_retry(world): + rows = [{"id": 7, "mirror_marked": 1}] + world.driver.remove_marker_on_first_send = True + world.driver.remove_input_marker_on_first_send = rows + with pytest.raises(ValueError, match="lacks required columns"): + await world.client.insert(TABLE, rows, required_columns=REQUIRED) + assert world.driver.committed == [] + assert len(world.driver.attempts) == 1 + assert world.driver.attempts[0]["columns"] == ["id", "mirror_marked"] + + +@pytest.mark.parametrize("bad_index", [0, 1]) +async def test_missing_required_value_in_any_input_row_refuses_before_metadata_or_send( + world, bad_index +): + rows = [{"id": 7, "mirror_marked": 1}, {"id": 8, "mirror_marked": 1}] + del rows[bad_index]["mirror_marked"] + with pytest.raises(ValueError, match="lacks required columns"): + await world.client.insert(TABLE, rows, required_columns=REQUIRED) + assert world.driver.describes == 0 + assert world.driver.attempts == world.driver.committed == [] + + +async def test_ordinary_projection_still_preserves_batch_without_new_required_fields(world): + del world.driver.live["mirror_marked"] + await world.client.insert(TABLE, [{"id": 7, "optional_future": "unused"}]) + assert world.driver.committed == [{"id": 7}] + assert world.driver.attempts[0]["columns"] == ["id"] + assert (TABLE, "optional_future") in ch_mod._PROJECTION_WARNED + + +async def test_ordinary_retry_may_still_drop_an_optional_column(world): + world.driver.remove_marker_on_first_send = True + await world.client.insert(TABLE, [{"id": 7, "mirror_marked": 1}]) + assert world.driver.committed == [{"id": 7}] + assert [a["columns"] for a in world.driver.attempts] == [["id", "mirror_marked"], ["id"]] + + +async def test_nonprojected_insert_also_validates_required_input_before_send(world, monkeypatch): + from server.core import rmt_carry + + monkeypatch.setattr(rmt_carry, "carries", lambda table: False) + with pytest.raises(ValueError, match="lacks required columns"): + await world.client.insert("loom.required_unit", [{"id": 7}], required_columns=REQUIRED) + assert world.driver.describes == 0 and not world.driver.attempts + + +async def test_required_set_is_frozen_before_the_first_await(world, monkeypatch): + required = {"mirror_marked"} + + async def mutate_caller_set(*args, **kwargs): + required.clear() + + monkeypatch.setattr(ch_mod, "guard_pending_schema", mutate_caller_set) + del world.driver.live["mirror_marked"] + with pytest.raises(RuntimeError, match="No such column mirror_marked"): + await world.client.insert(TABLE, [{"id": 7, "mirror_marked": 1}], required_columns=required) + assert not required + assert not world.driver.committed + assert all("mirror_marked" in a["columns"] for a in world.driver.attempts) diff --git a/tests/unit/test_required_request_tail.py b/tests/unit/test_required_request_tail.py new file mode 100644 index 0000000000..88b04dc3e7 --- /dev/null +++ b/tests/unit/test_required_request_tail.py @@ -0,0 +1,664 @@ +"""Required work stays owned across entry drains, failure and cancellation.""" + +from __future__ import annotations + +import asyncio +from contextvars import ContextVar +from types import SimpleNamespace + +import anyio +import pytest +from starlette.requests import ClientDisconnect + +from server.core import ch, request_tail + + +@pytest.fixture +def world(): + tail = request_tail._Tail() + token = request_tail._tail.set(tail) + state = SimpleNamespace(tail=tail, events=[]) + try: + yield state + finally: + request_tail._tail.reset(token) + + +def record(world, name): + async def step(): + world.events.append(name) + + return step + + +async def test_required_registration_refuses_outside_a_live_tail(world): + token = request_tail._tail.set(None) + try: + assert not request_tail.active() and not request_tail.required_active() + assert not request_tail.defer_required(record(world, "unowned")) + await request_tail.drain_required() + await request_tail.settle_current() + finally: + request_tail._tail.reset(token) + await request_tail.settle_current() + assert not request_tail.defer_required(record(world, "closed")) + assert world.events == [] + + +async def test_ordinary_order_keyed_registration_and_best_effort_remain(world, caplog): + async def broken(): + world.events.append("broken") + raise ValueError("ordinary cleanup detail") + + assert request_tail.defer_once("claim", record(world, "claim")) + assert request_tail.defer_once("claim", record(world, "duplicate")) + assert request_tail.deferred("claim") + assert request_tail.defer(broken) + assert request_tail.defer(record(world, "last")) + await request_tail.settle_current() + await request_tail.settle_current() + assert world.events == ["claim", "broken", "last"] + assert "ordinary cleanup detail" in caplog.text + assert not request_tail.active() + + +async def test_unmarked_cancelled_tail_does_not_resume_cleanup_before_headers(world): + control = asyncio.CancelledError("ordinary cancellation") + state = SimpleNamespace(tail=None) + sent = [] + + async def ordinary(): + world.events.append("ordinary") + raise control + + async def app(scope, receive, send): + state.tail = request_tail._tail.get() + request_tail.defer(ordinary) + request_tail.defer(record(world, "later")) + await send({"type": "http.response.start", "status": 200, "headers": []}) + await send({"type": "http.response.body", "body": b""}) + + async def send(message): + sent.append(message) + + with pytest.raises(type(control)) as caught: + await request_tail.RequestTailMiddleware(app)({"type": "http"}, None, send) + assert caught.value is control + await request_tail.settle(state.tail) + assert world.events == ["ordinary"] and sent == [] + assert request_tail._tail.get() is world.tail + + +async def test_unmarked_cleanup_disconnect_keeps_best_effort_response(world, caplog): + sent = [] + + async def ordinary(): + world.events.append("ordinary") + raise ClientDisconnect("ordinary cleanup disconnect") + + async def app(scope, receive, send): + request_tail.defer(ordinary) + request_tail.defer(record(world, "later")) + await send({"type": "http.response.start", "status": 200, "headers": []}) + await send({"type": "http.response.body", "body": b""}) + + async def send(message): + sent.append(message["type"]) + + await request_tail.RequestTailMiddleware(app)({"type": "http"}, None, send) + assert world.events == ["ordinary", "later"] + assert sent == ["http.response.start", "http.response.body"] + assert "ordinary cleanup disconnect" in caplog.text + assert request_tail._tail.get() is world.tail + + +async def test_required_entry_drains_preserve_ordinary_timing_keys_and_later_registration(world): + required = record(world, "marked") + assert request_tail.defer_once("claim", record(world, "claim")) + assert request_tail.defer_required(required) + assert request_tail.defer(record(world, "ordinary")) + await request_tail.drain_required() + assert world.events == ["marked"] + assert request_tail.active() and request_tail.required_active() + assert request_tail.deferred("claim") + assert request_tail.defer_required(required) + await request_tail.drain_required() + assert world.events == ["marked", "marked"] + await request_tail.settle_current() + await request_tail.drain_required() + assert world.events == ["marked", "marked", "claim", "ordinary"] + + +async def test_required_failure_drains_cleanup_and_stays_failed_without_backend_details( + world, caplog +): + async def broken(): + world.events.append("required") + raise RuntimeError("private backend canary") + + request_tail.defer(record(world, "before")) + request_tail.defer_required(broken) + request_tail.defer(record(world, "after")) + for settle in ( + request_tail.settle_current, + request_tail.settle_current, + request_tail.drain_required, + ): + with pytest.raises(request_tail.RequiredTailError) as caught: + await settle() + assert str(caught.value) == "Required request work was not confirmed" + assert caught.value.__cause__ is None + assert world.events == ["before", "required", "after"] + assert "private backend canary" not in caplog.text + assert not request_tail.required_active() + assert not request_tail.defer_required(record(world, "later")) + + +async def test_failed_entry_drain_never_runs_ordinary_work_early(world): + async def broken(): + world.events.append("required") + raise ValueError("private backend detail") + + request_tail.defer(record(world, "ordinary")) + request_tail.defer_required(broken) + with pytest.raises(request_tail.RequiredTailError): + await request_tail.drain_required() + assert world.events == ["required"] + assert request_tail.active() and not request_tail.required_active() + with pytest.raises(request_tail.RequiredTailError): + await request_tail.settle_current() + assert world.events == ["required", "ordinary"] + + +async def test_cooperative_timeout_finishes_owned_callback_and_remaining_cleanup( + world, monkeypatch +): + monkeypatch.setattr(request_tail, "REQUIRED_STEP_TIMEOUT_S", 0) + release = asyncio.Event() + + async def blocked(): + world.events.append("started") + try: + await release.wait() + finally: + world.events.append("ended") + + request_tail.defer_required(blocked) + request_tail.defer(record(world, "cleanup")) + with pytest.raises(request_tail.RequiredTailError): + await request_tail.settle_current() + assert world.events == ["started", "ended", "cleanup"] + assert not any(task.get_name() == "request.required-tail" for task in asyncio.all_tasks()) + + +@pytest.mark.parametrize("fails", [False, True]) +async def test_concurrent_entry_and_final_drains_wait_for_one_required_attempt(world, fails): + entered, release = asyncio.Event(), asyncio.Event() + + async def blocked(): + world.events.append("required") + entered.set() + await release.wait() + if fails: + raise ValueError("private failure") + + request_tail.defer(record(world, "ordinary")) + request_tail.defer_required(blocked) + first = asyncio.create_task(request_tail.drain_required()) + others = [] + try: + await asyncio.wait_for(entered.wait(), timeout=5) + others = [ + asyncio.create_task(request_tail.drain_required()), + asyncio.create_task(request_tail.settle_current()), + ] + await asyncio.sleep(0) + assert not first.done() and not any(task.done() for task in others) + assert not request_tail.defer_required(record(world, "too late")) + release.set() + results = await asyncio.gather(first, *others, return_exceptions=True) + assert ( + all(isinstance(result, request_tail.RequiredTailError) for result in results) + if fails + else results == [None] * 3 + ) + assert world.events == ["required", "ordinary"] + finally: + release.set() + for task in [first, *others]: + if not task.done(): + task.cancel() + await asyncio.gather(first, *others, return_exceptions=True) + + +@pytest.mark.parametrize("fails", [False, True]) +async def test_repeated_caller_cancellation_waits_and_preserves_primary_without_raw_cause( + world, fails +): + entered, release = asyncio.Event(), asyncio.Event() + + async def blocked(): + world.events.append("required") + entered.set() + await release.wait() + if fails: + raise ValueError("private backend canary") + + request_tail.defer_required(blocked) + task = asyncio.create_task(request_tail.drain_required()) + try: + await asyncio.wait_for(entered.wait(), timeout=5) + task.cancel("first caller cancellation") + await asyncio.sleep(0) + task.cancel("later caller cancellation") + await asyncio.sleep(0) + assert not task.done() + release.set() + with pytest.raises(asyncio.CancelledError) as caught: + await task + assert caught.value.args == ("first caller cancellation",) + assert caught.value.__cause__ is None + assert world.events == ["required"] + if fails: + with pytest.raises(request_tail.RequiredTailError): + await request_tail.settle_current() + else: + await request_tail.settle_current() + finally: + release.set() + if not task.done(): + task.cancel() + await asyncio.gather(task, return_exceptions=True) + + +async def test_callback_self_cancellation_is_failed_delivery_not_caller_cancellation(world): + async def cancelled(): + world.events.append("required") + raise asyncio.CancelledError("private callback canary") + + request_tail.defer_required(cancelled) + request_tail.defer(record(world, "cleanup")) + with pytest.raises(request_tail.RequiredTailError): + await request_tail.settle_current() + assert world.events == ["required", "cleanup"] + + +async def test_owned_wrapper_starts_in_its_own_context_before_factory_returns(world, monkeypatch): + factory = asyncio.eager_task_factory + loop = asyncio.get_running_loop() + previous_factory = loop.get_task_factory() + caller = asyncio.current_task() + value = ContextVar("required-tail-test-value", default="ordinary") + state = SimpleNamespace(started=False, callback_task=None, factory_task=None) + + async def required(): + state.started = True + state.callback_task = asyncio.current_task() + value.set("private") + world.events.append("required") + + def observed_factory(loop, coroutine, **kwargs): + task = factory(loop, coroutine, **kwargs) + assert state.started + state.factory_task = task + assert asyncio.current_task() is caller + return task + + request_tail.defer_required(required) + monkeypatch.setattr(request_tail.asyncio, "eager_task_factory", observed_factory) + await request_tail.settle_current() + assert state.callback_task is state.factory_task and state.callback_task is not caller + assert state.factory_task.done() and world.events == ["required"] + assert value.get() == "ordinary" + assert loop.get_task_factory() is previous_factory + + +@pytest.mark.parametrize("disconnect", [False, True]) +async def test_cancellation_after_owned_start_in_sole_final_settle_finishes_cleanup( + world, monkeypatch, disconnect +): + factory, shield = asyncio.eager_task_factory, asyncio.shield + shield_calls = 0 + primary = ClientDisconnect() + tasks = [] + + def cancel_after_start(loop, coroutine, **kwargs): + task = factory(loop, coroutine, **kwargs) + assert world.events == ["required"] + task.cancel("private callback cancellation") + tasks.append(task) + return task + + def bounded_shield(awaitable): + nonlocal shield_calls + shield_calls += 1 + if shield_calls > 4: + raise AssertionError("terminal-task join did not finish") + return shield(awaitable) + + async def app(scope, receive, send): + async def required(): + world.events.append("required") + try: + await asyncio.Event().wait() + finally: + world.events.append("ended") + + request_tail.defer_required(required) + request_tail.defer(record(world, "claim")) + request_tail.defer(record(world, "cleanup")) + if disconnect: + raise primary + + with monkeypatch.context() as patch: + patch.setattr(request_tail.asyncio, "eager_task_factory", cancel_after_start) + patch.setattr(request_tail.asyncio, "shield", bounded_shield) + with pytest.raises( + ClientDisconnect if disconnect else request_tail.RequiredTailError + ) as caught: + await request_tail.RequestTailMiddleware(app)({"type": "http"}, None, None) + if disconnect: + assert caught.value is primary + assert world.events == ["required", "ended", "claim", "cleanup"] + assert request_tail._tail.get() is world.tail + assert all(task.done() for task in tasks) + + +@pytest.mark.parametrize("outcome", ["return", "suspend", "raise"]) +async def test_actual_callback_self_cancellation_is_constant_and_does_not_cancel_waiter( + world, outcome +): + caller = asyncio.current_task() + before = caller.cancelling() + + async def required(): + world.events.append("required") + assert asyncio.current_task() is not caller + asyncio.current_task().cancel("private callback canary") + if outcome == "suspend": + await asyncio.sleep(0) + if outcome == "raise": + raise ValueError("private callback failure") + + request_tail.defer_required(required) + request_tail.defer(record(world, "cleanup")) + for _ in range(2): + with pytest.raises(request_tail.RequiredTailError) as caught: + await request_tail.settle_current() + assert str(caught.value) == "Required request work was not confirmed" + assert caught.value.__cause__ is None + assert "private" not in str(caught.value) + assert world.events == ["required", "cleanup"] + assert caller.cancelling() == before + + +@pytest.mark.parametrize("cancel_waiter", [False, True]) +async def test_cancelled_owned_lock_wait_finishes_cleanup_before_sole_final_owner_exits( + world, monkeypatch, cancel_waiter +): + factory = asyncio.eager_task_factory + entered, release, waiting = asyncio.Event(), asyncio.Event(), asyncio.Event() + state = SimpleNamespace(first=None, jobs=[]) + + def observed_factory(loop, coroutine, **kwargs): + task = factory(loop, coroutine, **kwargs) + state.jobs.append(task) + if len(state.jobs) == 2: + waiting.set() + return task + + async def required(): + world.events.append("required") + entered.set() + await release.wait() + + async def app(scope, receive, send): + request_tail.defer_required(required) + request_tail.defer(record(world, "claim")) + request_tail.defer(record(world, "cleanup")) + state.first = asyncio.create_task(request_tail.drain_required()) + await entered.wait() + + monkeypatch.setattr(request_tail.asyncio, "eager_task_factory", observed_factory) + task = asyncio.create_task( + request_tail.RequestTailMiddleware(app)({"type": "http"}, None, None) + ) + try: + await asyncio.wait_for(waiting.wait(), timeout=5) + state.jobs[1].cancel("private lock cancellation") + if cancel_waiter: + task.cancel("real caller cancellation") + await asyncio.sleep(0) + assert not task.done() + release.set() + with pytest.raises( + asyncio.CancelledError if cancel_waiter else request_tail.RequiredTailError + ) as caught: + await task + if cancel_waiter: + assert caught.value.args == ("real caller cancellation",) + else: + assert str(caught.value) == "Required request work was not confirmed" + assert caught.value.__cause__ is None + assert world.events == ["required", "claim", "cleanup"] + assert state.first.done() and all(job.done() for job in state.jobs) + assert request_tail._tail.get() is world.tail + finally: + release.set() + for owned in [task, state.first]: + if owned is not None and not owned.done(): + owned.cancel() + await asyncio.gather( + *(owned for owned in [task, state.first] if owned is not None), return_exceptions=True + ) + + +@pytest.mark.parametrize("disconnect", [False, True]) +@pytest.mark.parametrize("outcome", ["bare_cancel", "return", "suspend", "raise_error"]) +async def test_sole_final_settle_drains_required_work_after_ordinary_control_outcome( + world, disconnect, outcome +): + cancelled = asyncio.CancelledError("ordinary callback cancellation") + primary = ClientDisconnect() + caller = asyncio.current_task() + before = caller.cancelling() + state = SimpleNamespace(tail=None) + + async def ordinary(): + world.events.append("ordinary") + assert asyncio.current_task() is not caller + if outcome == "bare_cancel": + raise cancelled + asyncio.current_task().cancel("ordinary callback cancellation") + if outcome == "suspend": + await asyncio.sleep(0) + if outcome == "raise_error": + raise ValueError("ordinary callback failure") + + async def app(scope, receive, send): + state.tail = request_tail._tail.get() + request_tail.defer(ordinary) + request_tail.defer_required(record(world, "required")) + request_tail.defer(record(world, "cleanup")) + if disconnect: + raise primary + + with pytest.raises(ClientDisconnect if disconnect else asyncio.CancelledError) as caught: + await request_tail.RequestTailMiddleware(app)({"type": "http"}, None, None) + if disconnect: + assert caught.value is primary + else: + assert caught.value.args == cancelled.args + if outcome == "bare_cancel": + assert caught.value is cancelled + assert caller.cancelling() == before + assert caught.value.__cause__ is None + await request_tail.settle(state.tail) + assert world.events == ["ordinary", "required", "cleanup"] + assert request_tail._tail.get() is world.tail + + +async def test_required_callback_group_is_sanitized_and_finishes_remaining_cleanup(world, caplog): + group = BaseExceptionGroup( + "private group canary", + [asyncio.CancelledError("private callback canary"), RuntimeError("private backend canary")], + ) + + async def grouped(): + world.events.append("required") + raise group + + request_tail.defer_required(grouped) + request_tail.defer(record(world, "cleanup")) + with pytest.raises(request_tail.RequiredTailError) as caught: + await request_tail.settle_current() + assert str(caught.value) == "Required request work was not confirmed" + assert caught.value.__cause__ is None + assert world.events == ["required", "cleanup"] + assert "canary" not in caplog.text + with pytest.raises(request_tail.RequiredTailError): + await request_tail.settle_current() + + +async def test_anyio_level_cancellation_is_observed_after_owned_join(world): + entered, release = asyncio.Event(), asyncio.Event() + state = SimpleNamespace(scope=None, cancelled=False) + + async def blocked(): + entered.set() + await release.wait() + world.events.append("committed") + + async def caller(): + with anyio.CancelScope() as scope: + state.scope = scope + try: + await request_tail.drain_required() + world.events.append("unexpected continuation") + except asyncio.CancelledError: + state.cancelled = True + raise + + request_tail.defer_required(blocked) + task = asyncio.create_task(caller()) + try: + await asyncio.wait_for(entered.wait(), timeout=5) + state.scope.cancel() + await asyncio.sleep(0) + assert not task.done() + release.set() + await task + assert state.cancelled and world.events == ["committed"] + await request_tail.settle_current() + finally: + release.set() + if not task.done(): + task.cancel() + await asyncio.gather(task, return_exceptions=True) + + +async def test_completed_write_racing_with_caller_cancellation_keeps_cancellation(world): + entered, release = asyncio.Event(), asyncio.Event() + + async def blocked(): + entered.set() + await release.wait() + world.events.append("committed") + + request_tail.defer_required(blocked) + task = asyncio.create_task(request_tail.drain_required()) + try: + await asyncio.wait_for(entered.wait(), timeout=5) + release.set() + task.cancel("caller") + with pytest.raises(asyncio.CancelledError): + await task + assert world.events == ["committed"] + await request_tail.settle_current() + finally: + release.set() + if not task.done(): + task.cancel() + await asyncio.gather(task, return_exceptions=True) + + +@pytest.mark.parametrize("existing", [0, 0.25]) +async def test_required_statement_cap_is_finite_and_never_widens_an_existing_limit( + world, monkeypatch, existing +): + monkeypatch.setattr(request_tail, "class_timeout_s", lambda kind: existing) + values = [] + + async def inspect_cap(): + values.append((ch.class_timeout_s("read"), ch.class_timeout_s("write"))) + + request_tail.defer_required(inspect_cap) + await request_tail.settle_current() + expected = existing or request_tail.REQUIRED_STEP_TIMEOUT_S + assert values == [(expected, expected)] + + +async def test_ordinary_and_required_steps_keep_their_captured_query_tags(world): + values = [] + + async def inspect_tag(): + values.append(ch.current_query_tag()) + + with ch.query_tag("ordinary-tag"): + request_tail.defer(inspect_tag) + with ch.query_tag("required-tag"): + request_tail.defer_required(inspect_tag) + with ch.query_tag("later-tag"): + await request_tail.settle_current() + assert ch.current_query_tag() == "later-tag" + assert values == ["ordinary-tag", "required-tag"] + + +@pytest.mark.parametrize( + "mode", + ["success", "app_error", "send_error", "cancel", "required_error", "disconnect", "no_response"], +) +async def test_middleware_restores_outer_context_and_preserves_primary_while_draining(world, mode): + original = ( + asyncio.CancelledError("caller") + if mode == "cancel" + else ClientDisconnect() + if mode == "disconnect" + else ValueError("ordinary app error") + ) + sent = [] + + async def required(): + world.events.append("required") + if mode in ("app_error", "cancel", "disconnect", "required_error"): + raise ValueError("private backend canary") + + async def app(scope, receive, send): + assert request_tail._tail.get() is not world.tail + request_tail.defer_required(required) + request_tail.defer(record(world, "cleanup")) + if mode in ("app_error", "cancel", "disconnect"): + raise original + if mode != "no_response": + await send({"type": "http.response.start", "status": 200, "headers": []}) + await send({"type": "http.response.body", "body": b"answer"}) + + async def send(message): + assert world.events == ["required", "cleanup"] + if mode == "send_error": + raise original + sent.append(message) + + middleware = request_tail.RequestTailMiddleware(app) + if mode in ("success", "no_response"): + await middleware({"type": "http"}, None, send) + else: + expected = request_tail.RequiredTailError if mode == "required_error" else type(original) + with pytest.raises(expected) as caught: + await middleware({"type": "http"}, None, send) + if mode != "required_error": + assert caught.value is original + assert sent == [] + assert request_tail._tail.get() is world.tail and request_tail.active() + assert world.events == ["required", "cleanup"] + assert not any(task.get_name() == "request.required-tail" for task in asyncio.all_tasks()) diff --git a/tests/unit/test_retention_overrides.py b/tests/unit/test_retention_overrides.py index c175eabc7c..1e255c7182 100644 --- a/tests/unit/test_retention_overrides.py +++ b/tests/unit/test_retention_overrides.py @@ -111,7 +111,7 @@ def test_compute_alters_per_namespace_override_uses_multiif() -> None: ], ) # Override applies to every managed table — one ALTER per table. - assert len(out) == 7 + assert len(out) == 8 audit_alter = next(s for t, s, _ in out if t.table == "loom.audit_log") assert "multiIf" in audit_alter assert "org = 'clickhouse'" in audit_alter @@ -220,6 +220,7 @@ def test_compute_alters_per_namespace_applies_to_all_tables() -> None: tables = sorted(t.table for t, _, _ in out) assert tables == [ "loom.agent_events", + "loom.agent_events_private", "loom.audit_log", "loom.chunks", "loom.conversations", @@ -251,7 +252,7 @@ async def test_apply_uses_provided_overrides_without_ch_query() -> None: @pytest.mark.asyncio async def test_apply_per_namespace_emits_alters_for_all_tables() -> None: - """One namespace override → one ALTER per managed table (7).""" + """One namespace override → one ALTER per managed table (8).""" ch = _DiffCH({}) n = await retention_overrides.apply( _FakeSettings(), @@ -261,7 +262,7 @@ async def test_apply_per_namespace_emits_alters_for_all_tables() -> None: ], leader=True, ) - assert n == 7 + assert n == 8 @pytest.mark.asyncio @@ -588,17 +589,23 @@ async def query_one(self, sql: str, params: Any = None) -> dict[str, Any] | None def test_every_managed_table_reads_its_own_retention_and_tiering_settings() -> None: - """Each target's accessors read the settings named after its table: set - one table's pair alone and the plan alters that table only.""" + """Each setting pair reaches exactly its managed physical tables; both event + streams share the agent-events retention and tiering settings.""" from server.settings import Settings assert retention_overrides.compute_alters(Settings()) == [] for target in retention_overrides.TARGETS: leaf = target.table.removeprefix("loom.") - fake = _FakeSettings(**{f"retention_{leaf}_days": 30, f"tiering_{leaf}_warm_days": 7}) + source = "agent_events" if leaf == "agent_events_private" else leaf + fake = _FakeSettings(**{f"retention_{source}_days": 30, f"tiering_{source}_warm_days": 7}) plan = retention_overrides.compute_alters(fake) - assert [t.table for t, _, _ in plan] == [target.table] - assert plan[0][2]["retention_global"] == 30 and plan[0][2]["tiering_global"] == 7 + expected = ( + ["loom.agent_events", "loom.agent_events_private"] + if source == "agent_events" + else [target.table] + ) + assert [t.table for t, _, _ in plan] == expected + assert all(p["retention_global"] == 30 and p["tiering_global"] == 7 for _, _, p in plan) def test_no_ttl_deletes_memory_or_its_vectors_under_the_postgres_authority( diff --git a/tests/unit/test_rmt_carry.py b/tests/unit/test_rmt_carry.py index 0ade4bd393..da7ac22d5f 100644 --- a/tests/unit/test_rmt_carry.py +++ b/tests/unit/test_rmt_carry.py @@ -572,6 +572,56 @@ def test_a_guarded_batch_that_landed_nothing_after_an_alter_is_refused( assert not rmt_carry._pinned and not rmt_carry._inflight +@pytest.mark.parametrize(("request_s", "response_s"), [(28.0, 0.0), (0.0, 28.0), (14.0, 14.0)]) +async def test_a_sampled_clock_bounds_leased_sends_and_uncertain_pins( + monkeypatch: pytest.MonkeyPatch, request_s: float, response_s: float +) -> None: + from server.core import lease_writes, leases + from tests.unit.clock_fake import ManualClock + + clock = ManualClock(t=1000.0) + monkeypatch.setattr(rmt_carry, "time", clock) + started, server_start = clock.monotonic(), 10_000.0 + + async def query_one(sql: str) -> dict[str, int]: + assert sql == "SELECT toUnixTimestamp64Milli(now64(3)) AS ms" + clock.advance(request_s) + sampled = server_start + clock.monotonic() - started + clock.advance(response_s) + return {"ms": round(sampled * 1000)} + + await rmt_carry.measure_server_clock(SimpleNamespace(query_one=query_one)) + ttl = lease_writes.lease_ttl_s(rmt_carry.send_bound_s()) + work_s = ttl * leases._WORK_SHARE + takeover = server_start + ttl + # Both a last admitted send and one delayed past the work window keep its bound. + for send_at in (56.5, work_s + 0.25): + clock.t = started + send_at + with rmt_carry.under_lease(started + work_s): + deadline = rmt_carry.send_deadline() + actual_deadline = server_start + min(send_at, work_s) + rmt_carry._TRANSIT_S + assert deadline + ch_mod.write_limit_s() + rmt_carry._RELEASE_MARGIN_S < takeover, ( + request_s, + response_s, + send_at, + deadline, + takeover, + ) + assert deadline <= actual_deadline, (deadline, actual_deadline) + + rmt_carry._gen, rmt_carry._prints[1] = 1, {TABLE: "old"} + await _cut_off_write(deadline=deadline) + [pin] = rmt_carry._pinned + ch = _ProcessesCH(running=None) + # An unreadable process list proves no end; only the receiving clock can release it. + clock.t = started + pin.release_at - server_start - 0.1 + await rmt_carry._settle(ch) + assert rmt_carry._pinned and rmt_carry._inflight + clock.advance(request_s + response_s + 0.2) + await rmt_carry._settle(ch) + assert not rmt_carry._pinned and not rmt_carry._inflight + + def test_a_host_clock_step_does_not_move_the_servers_clock( monkeypatch: pytest.MonkeyPatch, ) -> None: diff --git a/tests/unit/test_rmt_write_paths.py b/tests/unit/test_rmt_write_paths.py index 9a6ee58143..5c33d3c35b 100644 --- a/tests/unit/test_rmt_write_paths.py +++ b/tests/unit/test_rmt_write_paths.py @@ -38,8 +38,14 @@ "delete_version_checks": ("builder", "test_delete_version_sql.py"), "memory_webhooks": ("builder", "test_memory_webhooks.py"), "knowledge_sources": ("builder", "test_knowledge_sources.py"), + "knowledge_source_push": ("builder", "test_repository_column_sets_match_schema.py"), + "query_history_sources": ("builder", "test_repository_column_sets_match_schema.py"), "knowledge_mirrors": ("builder", "test_knowledge_mirrors.py"), "knowledge_source_listings": ("builder", "test_knowledge_mirrors.py"), + "knowledge_group_members": ( + "insert_once", + "read-side schema only; no production writer inserts or rewrites membership evidence", + ), "machine_identities": ("builder", "test_machines.py"), "org_model_calls": ("builder", "test_model_calls_switch.py"), "extraction_policies": ("builder", "test_extraction_policy.py"), diff --git a/tests/unit/test_schema_baseline.py b/tests/unit/test_schema_baseline.py index e17fcffa3d..1a0b8bf3bf 100644 --- a/tests/unit/test_schema_baseline.py +++ b/tests/unit/test_schema_baseline.py @@ -157,6 +157,15 @@ def test_the_journal_files() -> None: "099_document_access_lists.sql", "100_knowledge_source_listings.sql", "101_erasure_mirror_mark.sql", + "102_query_history_sources.sql", + "103_sso_domain_evidence.sql", + "104_knowledge_group_members.sql", + "105_mirror_access_candidates.sql", + "106_marked_request_measures.sql", + "107_user_cost_budgets.sql", + "108_knowledge_mirror_latch.sql", + "109_knowledge_source_push.sql", + "110_private_event_storage.sql", ] diff --git a/tests/unit/test_sdk_agent_call.py b/tests/unit/test_sdk_agent_call.py index 381ba7bc77..876b1e7b40 100644 --- a/tests/unit/test_sdk_agent_call.py +++ b/tests/unit/test_sdk_agent_call.py @@ -138,6 +138,12 @@ async def test_knowledge_synthesize_sends_datasets_with_or_without_documents() - assert t.calls[2][1]["source_uris"] == ["doc://a"] and "datasets" not in t.calls[2][1] +async def test_knowledge_synthesis_names_the_user_whose_budget_it_uses() -> None: + a, t = _agent() + await a.knowledge.synthesize(["doc://a"], "Summarize", user_id="alice") + assert t.calls[0][1]["user_id"] == "alice" + + def test_identity_helper() -> None: a, _ = _agent() assert a.identity() == { diff --git a/tests/unit/test_sdk_errors_from_response.py b/tests/unit/test_sdk_errors_from_response.py index 5e6976697a..615825e10f 100644 --- a/tests/unit/test_sdk_errors_from_response.py +++ b/tests/unit/test_sdk_errors_from_response.py @@ -119,6 +119,7 @@ def test_a_5xx_is_backend_unavailable_and_a_429_rate_limited_whatever_the_code() # Every server error code and the SDK class a caller catches it as (docs/reference/python-sdk.md). _SERVER_CODE_CLASSES: dict[str, type[LoomError]] = { "VALIDATION_FAILED": ValidationError, + "VECTOR_INPUT_TOO_LARGE": ValidationError, "BAD_CONFIG": ValidationError, # a 422 a document source's config or item is refused with "AUTH_INSUFFICIENT": AuthInsufficient, "IDENTITY_INCOMPLETE": ValidationError, @@ -126,6 +127,7 @@ def test_a_5xx_is_backend_unavailable_and_a_429_rate_limited_whatever_the_code() "PRECONDITION_FAILED": PreconditionFailed, "GRANT_WOULD_DOWNGRADE": PreconditionFailed, "READS_LLM_FREE": PreconditionFailed, + "SESSION_PROTECTION_REQUIRED": PreconditionFailed, "OVERLOADED": Overloaded, "RATE_LIMITED": RateLimited, "BACKEND_UNAVAILABLE": BackendUnavailable, diff --git a/tests/unit/test_sdk_write_kwargs.py b/tests/unit/test_sdk_write_kwargs.py index a08e9b56db..498a0bf3c1 100644 --- a/tests/unit/test_sdk_write_kwargs.py +++ b/tests/unit/test_sdk_write_kwargs.py @@ -55,17 +55,20 @@ async def test_a_coalesced_set_keeps_its_source_class(agent: Agent) -> None: assert entries and all(e["source_class"] == "imported" for e in entries) -async def test_pin_sends_what_set_sends(agent: Agent) -> None: +@pytest.mark.parametrize( + "precondition", [{"if_match_sha256": "abc"}, {"if_match_sha256": "absent"}] +) +async def test_pin_sends_what_set_sends(agent: Agent, precondition: dict[str, Any]) -> None: t: Any = agent.transport kw: dict[str, Any] = dict( tags=["ops"], entities=["E1"], - if_match_sha256="abc", valid_at=datetime(2026, 1, 2, tzinfo=UTC), source_resource_id="doc-1", source_class="derived", agent_id="other", ) + kw.update(precondition) await agent.memory.pin("k", "v", **kw) await agent.memory.set("k", "v", **kw) # a lone set takes the point path assert t.last("/v1/memory.pin") == t.last("/v1/memory.set") @@ -120,6 +123,17 @@ async def test_a_set_with_relations_is_never_coalesced(agent: Agent) -> None: assert len([o for o, _ in t.calls if o == "/v1/memory.set"]) == 4 +async def test_create_only_sets_keep_their_precondition_on_the_point_path(agent: Agent) -> None: + t: Any = agent.transport + await asyncio.gather(*[agent.memory.set(k, "v", if_match_sha256="absent") for k in "abcd"]) + assert len(t.calls) == 4 + assert all( + op == "/v1/memory.set" and body["if_match_sha256"] == "absent" for op, body in t.calls + ) + await agent.memory.set("ordinary", "v") + assert "if_match_sha256" not in t.last("/v1/memory.set") + + async def test_set_from_messages_sends_defer_only_when_given(agent: Agent) -> None: """Unset leaves the operator's extraction_defer_agents in charge; an explicit False must reach the server, which honours a sent field over the allowlist.""" diff --git a/tests/unit/test_secrets_at_rest.py b/tests/unit/test_secrets_at_rest.py index bf639f5151..253f64da5e 100644 --- a/tests/unit/test_secrets_at_rest.py +++ b/tests/unit/test_secrets_at_rest.py @@ -168,6 +168,112 @@ async def query_one(self, sql: str) -> dict | None: assert unseal("qa_sources.password", rows[0]["password_enc"]) == "pw" +@pytest.mark.asyncio +@pytest.mark.parametrize("dry_run", [True, False]) +async def test_reseal_push_registry_uses_the_supplied_client( + monkeypatch: pytest.MonkeyPatch, dry_run: bool +) -> None: + from contextlib import asynccontextmanager + from dataclasses import asdict + + from server.cli import secrets as cli + from server.core import ch as ch_module + from server.knowledge.app import source_push as push + from server.knowledge.domain.source_push import PushRegistration, writer_lease_name + + monkeypatch.setattr(settings, "jwt_secret", "old-root-secret") + stale = seal(push.domain.SECRET_PURPOSE, "push-verification-secret") + monkeypatch.setattr(settings, "jwt_secret", "new-root-secret") + monkeypatch.setattr(settings, "jwt_secret_previous", "old-root-secret") + row = asdict( + PushRegistration( + org="o", + namespace="docs", + name="source", + source_id="source-id", + provider="notion", + generation="generation", + fingerprint="fingerprint", + secret_enc=stale, + ) + ) + calls: list[str] = [] + inserted: list[tuple[str, list[dict]]] = [] + uncertainties: list[bool] = [] + + class Ch: + async def query_all(self, sql: str, params: dict | None = None) -> list[dict]: + if "loom.knowledge_source_push" in sql: + calls.append("scan") + assert params is not None + return [dict(row)] if params["after"] == ("", "", "") else [] + if "loom.erasure_requests" in sql: + calls.append("erasure") + if "loom.instances" in sql: + calls.append("fleet") + return [{"schema_version": push.PUSH_MIGRATION}] + return [] + + async def query_one(self, sql: str, params: dict | None = None) -> dict | None: + if "loom.knowledge_source_push" in sql: + calls.append("reread") + assert params == {"org": "o", "ns": "docs", "source": "source-id"} + return dict(row) + if "loom.knowledge_sources" in sql: + calls.append("source") + return {**row, "kind": "notion", "active": 1} + return None + + async def insert(self, table: str, rows: list[dict], settings: dict | None = None) -> None: + inserted.append((table, rows)) + + ch = Ch() + + def no_global_client(): + pytest.fail("reseal must use the supplied ClickHouse client") + + @asynccontextmanager + async def source_lease(name: str, *, ttl_s: float, wait_s: float, ch=None): + assert ch is client and name == "knowledge-source:o:docs" + assert ttl_s == 60.0 and wait_s == 5.0 + calls.append("lease") + yield True + + @asynccontextmanager + async def writer_fence(name: str, *, ch=None): + assert ch is client and name == writer_lease_name("o", "docs") + calls.append("fence") + yield uncertainties.append + + client = ch + monkeypatch.setattr(ch_module, "get_client", no_global_client) + monkeypatch.setattr(push, "get_client", no_global_client) + monkeypatch.setattr(push.leases, "holding", source_lease) + monkeypatch.setattr(push, "fenced", writer_fence) + counts, lost, _ = await cli.reseal_all(client, dry_run=dry_run) + assert counts["loom.knowledge_source_push.secret_enc"] == 1 and lost == {} + assert calls == ["scan", "lease", "erasure", "reread", "source"] + ( + [] if dry_run else ["fence", "fleet"] + ) + ["scan"] + if dry_run: + assert inserted == [] and uncertainties == [] + else: + [(table, [rewritten])] = inserted + assert table == "loom.knowledge_source_push" + assert rewritten == { + **row, + "secret_enc": rewritten["secret_enc"], + "actor": "process:source-push", + "source_class": "derived", + } + assert uncertainties == [True, False] + monkeypatch.setattr(settings, "jwt_secret_previous", "") + assert ( + unseal(push.domain.SECRET_PURPOSE, rewritten["secret_enc"]) + == "push-verification-secret" + ) + + @pytest.mark.asyncio async def test_reseal_reaches_a_rebuild_recipe_and_waits_out_a_running_rebuild( monkeypatch: pytest.MonkeyPatch, diff --git a/tests/unit/test_section_value.py b/tests/unit/test_section_value.py index 41228f2f1a..28bbae1602 100644 --- a/tests/unit/test_section_value.py +++ b/tests/unit/test_section_value.py @@ -21,6 +21,7 @@ from server.knowledge.domain.section_value import is_noise from server.knowledge.store.chunks import build_chunk_rows from server.settings import settings +from tests.unit.checked_pack_fakes import install_pack_knowledge, install_pack_target FIXTURE = Path(__file__).resolve().parent / "fixtures" / "section_values.json" @@ -698,8 +699,10 @@ def test_the_repository_docs_merge_keeps_noise_after_the_close_hits() -> None: def test_a_reranked_page_keeps_noise_below_an_admitted_repository_hit( monkeypatch: pytest.MonkeyPatch, ) -> None: + from types import SimpleNamespace + from server.knowledge.api.models_knowledge import KnowledgeSearchInput, KnowledgeSearchOutput - from server.knowledge.app import repo_docs + from server.knowledge.app import knowledge_search, repo_docs, source_access async def _search(inp: KnowledgeSearchInput) -> KnowledgeSearchOutput: if inp.namespace == "code-kj": @@ -707,7 +710,20 @@ async def _search(inp: KnowledgeSearchInput) -> KnowledgeSearchOutput: hits = [_hit("kb://sync", 0.95, noise=True), _hit("kb://design", 0.6)] return KnowledgeSearchOutput(results=hits, embedding_model="m", reranked_by="builtin:x") - monkeypatch.setattr("server.knowledge.app.knowledge_search.handle_knowledge_search", _search) + async def resolve(inp): + return knowledge_search.SearchRequest(inp, (inp.namespace,), ()) + + async def run(request, plan): + return knowledge_search.CheckedSearch( + await _search(request.input), None, SimpleNamespace(marked=False), [], 0 + ) + + async def prepare(org, namespaces): + return source_access.ReadPlan(org) + + monkeypatch.setattr(knowledge_search, "resolve_search", resolve) + monkeypatch.setattr(knowledge_search, "run_checked_search", run) + monkeypatch.setattr(source_access, "prepare", prepare) page = KnowledgeSearchInput(org="o", namespace="ns", query="the cache", top_k=3) out = asyncio.run(repo_docs.knowledge_with_repo_docs(page, repo_namespace="code-kj")) assert [h.source_uri for h in out.results] == ["kb://design", "doc://adr", "kb://sync"] @@ -755,7 +771,7 @@ async def _dead(*a: Any, **k: Any) -> Any: "server.memory.app.procedure.handle_procedure_match", "server.knowledge.app.conversations.handle_conversation_search", ): - monkeypatch.setattr(target, _dead) + install_pack_target(monkeypatch, target, _dead) @pytest.mark.usefixtures("_only_knowledge") @@ -771,7 +787,7 @@ def test_a_context_pack_leaves_noise_out_with_the_filter_on( async def _knowledge(*a: Any, **k: Any) -> Any: return SimpleNamespace(results=[_hit("kb://design", 0.9), _hit("kb://sync", 0.8, True)]) - monkeypatch.setattr("server.knowledge.app.knowledge_search.handle_knowledge_search", _knowledge) + install_pack_knowledge(monkeypatch, _knowledge) monkeypatch.setattr(settings, "knowledge_noise_filter", filter_on) out = asyncio.run( handle_context_pack( @@ -797,7 +813,7 @@ async def _knowledge(inp: Any) -> Any: return SimpleNamespace(results=hits[: inp.top_k]) - monkeypatch.setattr("server.knowledge.app.knowledge_search.handle_knowledge_search", _knowledge) + install_pack_knowledge(monkeypatch, _knowledge) out = asyncio.run( handle_context_pack( ContextPackInput( @@ -821,7 +837,7 @@ async def _knowledge(inp: Any) -> Any: raise RuntimeError("the wider read failed") return SimpleNamespace(results=[_hit("kb://sync", 0.9, True), _hit("kb://a", 0.8)]) - monkeypatch.setattr("server.knowledge.app.knowledge_search.handle_knowledge_search", _knowledge) + install_pack_knowledge(monkeypatch, _knowledge) out = asyncio.run( handle_context_pack( ContextPackInput( @@ -839,8 +855,9 @@ def test_a_memory_stack_leaves_noise_out_with_the_filter_on( # The stack reads chunks itself (and context.pack serves its knowledge entries). from server.knowledge.app import search as knowledge_store from server.knowledge.app.search import ChunkHit + from server.knowledge.app.source_access import ReadPlan from server.memory.api.models_lifecycle import MemoryStackInput - from server.memory.app import stack + from server.memory.app import stack, stack_knowledge class _Embedder: model_name = "m" @@ -860,15 +877,20 @@ async def _search(q: Any) -> list[ChunkHit]: monkeypatch.setattr(knowledge_store, "hybrid_search", _search) monkeypatch.setattr(settings, "knowledge_noise_filter", filter_on) fill = stack._StackFill(budget=10_000) - asyncio.run( - stack._stack_knowledge( - MemoryStackInput( - org="o", namespace="ns", agent="a", include_knowledge=True, knowledge_top_k=2 - ), - fill, + knowledge_input = MemoryStackInput( + org="o", namespace="ns", agent="a", include_knowledge=True, knowledge_top_k=2 + ) + knowledge = asyncio.run( + stack_knowledge.collect( + knowledge_input.org, + knowledge_input.namespace, + knowledge_input.agent, "the cache", + int(knowledge_input.knowledge_top_k), + ReadPlan(knowledge_input.org), ) ) + fill = stack._render(fill, knowledge.hits) served = [e.memory_key for e in fill.entries] assert served == (["kb://a", "kb://b"] if filter_on else ["kb://sync", "kb://a"]) diff --git a/tests/unit/test_session_content_senders.py b/tests/unit/test_session_content_senders.py new file mode 100644 index 0000000000..88408e3b44 --- /dev/null +++ b/tests/unit/test_session_content_senders.py @@ -0,0 +1,172 @@ +"""Pin automatic sender provenance to the operation admission class.""" + +from __future__ import annotations + +import hashlib +import json +from pathlib import Path + +import pytest + +from server.operations.registry import OPERATIONS_BY_NAME +from tests.unit.session_content_senders import collect, javascript_sites, python_sites + +ROOT = Path(__file__).resolve().parents[2] +FLOOR = frozenset( + { + "conversation.append", + "conversation.save_message", + "conversation.create", + "conversation.update", + "memory.set_from_messages", + "session.brief_save", + "observe.record", + "observe.crystallize", + "working_memory.set", + "working_memory.append", + "run.begin", + "run.complete", + "code.outcome", + "cost.record_turns", + "ui.vitals", + "context.pack", + "code.search", + "code.impact", + "memory.for_file", + "namespace.validate", + "code.test_gate", + "code.symbol", + "code.enclosing", + "tracker.duplicate_check", + "memory.search", + "memory.set", + "memory.bulk_set", + "knowledge.search", + } +) + + +def _unclassified(sites, classified, exceptions): + return {site.key for site in sites if site.op not in classified} - set(exceptions) + + +def _changed_sources(root, pins): + return { + path + for path, digest in pins.items() + if hashlib.sha256((root / path).read_bytes()).hexdigest() != digest + } + + +def test_shipped_automatic_senders_have_an_admission_class_or_reviewed_exception(): + classified = {name for name, op in OPERATIONS_BY_NAME.items() if op.session_content} + assert FLOOR <= classified + sites = collect(ROOT) + reviewed = json.loads(Path(__file__).with_name("session_content_senders.json").read_text()) + exceptions = reviewed["sites"] + assert not _unclassified(sites, classified, exceptions), "Review new sender content provenance" + assert set(exceptions) == {site.key for site in sites if site.op not in classified} + assert not _changed_sources(ROOT, reviewed["reviewed_source_sha256"]), ( + "Review changed sender and body-builder provenance before renewing an exception" + ) + assert {site.path for site in sites if site.key in exceptions} <= set( + reviewed["reviewed_source_sha256"] + ) + assert all( + entry["reason"] + and entry["category"] in {"scope", "reference", "explicit", "delivery", "bootstrap"} + for entry in exceptions.values() + ) + + +def test_independent_delivery_roots_are_present_in_the_actual_census(): + paths = {site.path for site in collect(ROOT)} + assert { + "frontend/src/lib/vitals.ts", + "integrations/grep-shim/lib/shim.mjs", + "integrations/cursor/cursor-session-hook.sh", + "integrations/generic/ingest.sh", + "server/cli/shell.py", + "sdk/python/loom/memory.py", + } <= paths + for plugin in ("claude-code-plugin", "codex-plugin"): + assert f"integrations/{plugin}/hooks/loom-capture.mjs" in paths + assert f"integrations/{plugin}/lib/flush-job.mjs" in paths + + +@pytest.mark.parametrize( + ("source", "expected"), + [ + ( + '// post("manual.example", payload)\nconst example = \'post("manual.example", x)\';', + set(), + ), + ('/* ignored\ncomment */\npostBounded("observe.record", body);', {"observe.record"}), + ('const OP = "observe.record"; postBounded(OP, body);', {"observe.record"}), + ('enqueue({op: "session.brief_save", body});', {"session.brief_save"}), + ("fetch(`${base}/v1/ui.vitals`, {body: JSON.stringify(vitals)});", {"ui.vitals"}), + ("function post(op, body) {}\npost(name, body);", {""}), + ( + 'fetch(key: string): Promise { return client.call("context.fetch", {key}); }', + {"context.fetch"}, + ), + ], +) +def test_javascript_sender_shapes(source, expected): + assert {site.op for site in javascript_sites(source, "lib/only.mjs")} == expected + + +def test_new_library_send_and_changed_scope_payload_require_review(): + original = javascript_sites('post("code.repos", {repo});', "lib/scope.mjs") + reviewed = {site.key: "scope" for site in original} + assert not _unclassified(original, set(), reviewed) + changed = javascript_sites('post("code.repos", {repo, prompt});', "lib/scope.mjs") + assert _unclassified(changed, set(), reviewed) + added = javascript_sites('post("new.capture", {prompt});', "lib/added.mjs") + assert _unclassified(original | added, set(), reviewed) + + +def test_duplicate_calls_cannot_reuse_one_reviewed_exception(): + first = javascript_sites('post("knowledge.search", {query});', "lib/query.mjs") + doubled = javascript_sites( + 'post("knowledge.search", {query}); post("knowledge.search", {query});', "lib/query.mjs" + ) + assert len(doubled) == 2 + assert _unclassified(doubled, set(), {site.key: "explicit" for site in first}) + + +def test_python_bound_methods_and_lexical_scope_are_part_of_the_census(): + classes = {"Memory": {"search": {"memory.search"}}} + attrs = {"memory": "Memory"} + source = """ +async def explicit(self, query): + return await runner(self.agent.memory.search, query) +async def automatic(self, messages): + query = messages[-1].content + return await runner(self.agent.memory.search, query) +""" + sites = python_sites(source, "adapter.py", classes, attrs) + assert len(sites) == 2 + assert {site.op for site in sites} == {"memory.search"} + assert len({site.key for site in sites}) == 2 + + +def test_cli_urllib_request_collects_the_formatted_url_operation(): + source = """ +def _cmd_ingest_transcript(args): + req = urllib.request.Request(f"{base}/v1/conversation.append", data=encoded) + return urllib.request.urlopen(req) +""" + sites = python_sites(source, "server/cli/shell.py", {}, {}) + assert {site.op for site in sites} == {"conversation.append"} + + +def test_unchanged_call_with_changed_argument_provenance_invalidates_source_review(tmp_path): + path = tmp_path / "adapter.py" + path.write_text('query = request.query\nclient.call("knowledge.search", {"query": query})\n') + pins = {path.name: hashlib.sha256(path.read_bytes()).hexdigest()} + assert not _changed_sources(tmp_path, pins) + path.write_text( + 'query = messages[-1].content\nclient.call("knowledge.search", {"query": query})\n' + ) + assert _changed_sources(tmp_path, pins) == {path.name} diff --git a/tests/unit/test_session_protection_admission.py b/tests/unit/test_session_protection_admission.py new file mode 100644 index 0000000000..bdb0a77486 --- /dev/null +++ b/tests/unit/test_session_protection_admission.py @@ -0,0 +1,279 @@ +"""Session-content admission uses global durable state before reading payloads.""" + +from __future__ import annotations + +import asyncio +from unittest.mock import AsyncMock + +import pytest + +from server.auth.session_protection import request_declaration +from server.core.errors import SessionProtectionRequiredError, classified +from server.knowledge.store import mirror_latch +from server.operations.registry import OPERATIONS_BY_NAME +from server.transport import gates + + +@pytest.mark.parametrize( + "operation", + [op for op in OPERATIONS_BY_NAME.values() if op.session_content], + ids=lambda op: op.name, +) +@pytest.mark.parametrize("local_on", [False, True]) +async def test_every_classified_operation_refuses_undeclared_clients( + monkeypatch, operation, local_on +): + from server.settings import settings + + monkeypatch.setattr(settings, "knowledge_mirrored_sources_enabled", local_on) + monkeypatch.setattr(mirror_latch, "enabled", AsyncMock(return_value=True)) + ensure = AsyncMock() + monkeypatch.setattr(mirror_latch, "ensure", ensure) + with request_declaration({"headers": []}): + with pytest.raises(SessionProtectionRequiredError): + await gates.session_content(operation, None) + assert ensure.await_count == int(local_on) + + +@pytest.mark.parametrize("declared", [False, True]) +@pytest.mark.parametrize( + ("switch", "latched", "unavailable", "allowed"), + [ + (False, False, False, True), + (False, True, False, False), + (False, False, True, False), + (True, False, False, False), + (True, True, False, False), + (True, False, True, False), + ], +) +async def test_durable_state_and_local_switch_have_one_constant_refusal( + monkeypatch, declared, switch, latched, unavailable, allowed +): + from server.settings import settings + + monkeypatch.setattr(settings, "knowledge_mirrored_sources_enabled", switch) + enabled = AsyncMock(return_value=latched) + ensure = AsyncMock() + if unavailable: + enabled.side_effect = mirror_latch.LatchUnavailable() + ensure.side_effect = mirror_latch.LatchUnavailable() + monkeypatch.setattr(mirror_latch, "enabled", enabled) + monkeypatch.setattr(mirror_latch, "ensure", ensure) + headers = [(b"x-loom-session-protection", b"v1")] if declared else [] + with request_declaration({"headers": headers}): + may_admit = (declared and not (switch and unavailable)) or allowed + if may_admit: + await gates.session_content(OPERATIONS_BY_NAME["conversation.create"], None) + else: + with pytest.raises(SessionProtectionRequiredError) as caught: + await gates.session_content(OPERATIONS_BY_NAME["conversation.create"], None) + assert classified(caught.value.to_detail(), caught.value.status_code) == { + "code": "SESSION_PROTECTION_REQUIRED", + "message": "This operation requires a client that protects session content", + "category": "configuration", + "retryable": False, + } + assert ensure.await_count == int(switch) + assert enabled.await_count == int(not switch and not declared) + + +async def test_an_ordinary_op_never_reads_or_repairs_privacy_state(monkeypatch): + from server.settings import settings + + monkeypatch.setattr(settings, "knowledge_mirrored_sources_enabled", True) + enabled, ensure = AsyncMock(), AsyncMock() + monkeypatch.setattr(mirror_latch, "enabled", enabled) + monkeypatch.setattr(mirror_latch, "ensure", ensure) + await gates.session_content(OPERATIONS_BY_NAME["memory.get"], None) + enabled.assert_not_awaited() + ensure.assert_not_awaited() + + +async def test_an_offline_unknown_client_cannot_reuse_an_absent_decision(monkeypatch): + enabled = AsyncMock(side_effect=[False, True]) + monkeypatch.setattr(mirror_latch, "enabled", enabled) + with request_declaration({"headers": []}): + await gates.session_content(OPERATIONS_BY_NAME["conversation.create"], None) + with pytest.raises(SessionProtectionRequiredError): + await gates.session_content(OPERATIONS_BY_NAME["conversation.create"], None) + assert enabled.await_count == 2 + + +async def test_cancellation_during_durable_repair_is_not_an_admission(monkeypatch): + from server.settings import settings + + monkeypatch.setattr(settings, "knowledge_mirrored_sources_enabled", True) + ensure = AsyncMock(side_effect=asyncio.CancelledError()) + monkeypatch.setattr(mirror_latch, "ensure", ensure) + with request_declaration({"headers": [(b"x-loom-session-protection", b"v1")]}): + with pytest.raises(asyncio.CancelledError): + await gates.session_content(OPERATIONS_BY_NAME["conversation.create"], None) + + +@pytest.mark.parametrize("declared", [False, True]) +async def test_http_protection_runs_after_authentication_before_body_or_validation( + monkeypatch, declared +): + from fastapi import Request, Response + + from server.transport import http + + class ReachedBody(Exception): + pass + + phases = [] + + def authenticate(request): + phases.append("authenticated") + return None + + async def body(*args): + phases.append("body") + raise ReachedBody() + + monkeypatch.setattr(http, "_extract_auth", authenticate) + monkeypatch.setattr(http, "_read_body", body) + monkeypatch.setattr(mirror_latch, "enabled", AsyncMock(return_value=True)) + scope = {"type": "http", "headers": []} + endpoint = http._make_endpoint(OPERATIONS_BY_NAME["conversation.create"]) + headers = [(b"x-loom-session-protection", b"v1")] if declared else [] + with request_declaration({"headers": headers}): + with pytest.raises(ReachedBody if declared else SessionProtectionRequiredError): + await endpoint(Request(scope), Response()) + assert phases == (["authenticated", "body"] if declared else ["authenticated"]) + + +async def test_http_authentication_refusal_precedes_the_deployment_read(monkeypatch): + from fastapi import HTTPException, Request, Response + + from server.transport import http + + def authenticate(request): + raise HTTPException(401, "credential refused") + + monkeypatch.setattr(http, "_extract_auth", authenticate) + enabled = AsyncMock(return_value=True) + monkeypatch.setattr(mirror_latch, "enabled", enabled) + endpoint = http._make_endpoint(OPERATIONS_BY_NAME["conversation.create"]) + with pytest.raises(HTTPException) as caught: + await endpoint(Request({"type": "http", "headers": []}), Response()) + assert caught.value.status_code == 401 + enabled.assert_not_awaited() + + +@pytest.mark.parametrize("declared", [False, True]) +async def test_mcp_protection_precedes_identity_validation_replay_and_implicit_runs( + monkeypatch, declared +): + from server.transport import mcp_call + + class ReachedIdentity(Exception): + pass + + op = OPERATIONS_BY_NAME["conversation.create"] + monkeypatch.setattr(mcp_call, "_resolve_connection_tool", AsyncMock(return_value=op)) + identity = AsyncMock(side_effect=ReachedIdentity()) + monkeypatch.setattr(mcp_call, "_another_cells_org", identity) + monkeypatch.setattr(mirror_latch, "enabled", AsyncMock(return_value=True)) + headers = [(b"x-loom-session-protection", b"v1")] if declared else [] + params = {"name": op.mcp_tool_name, "arguments": {"malformed": "private-canary"}} + with request_declaration({"headers": headers}): + if declared: + with pytest.raises(ReachedIdentity): + await mcp_call._call_tool(7, params) + else: + result = await mcp_call._call_tool(7, params) + assert result["id"] == 7 and result["result"]["isError"] + assert result["result"]["structuredContent"] == { + "code": "SESSION_PROTECTION_REQUIRED", + "message": "This operation requires a client that protects session content", + "status": 409, + } + assert "private-canary" not in str(result) + assert identity.await_count == int(declared) + + +async def test_unit_store_seam_runs_real_absence_proofs_and_observes_later_enablement( + mirror_latch_world, +): + world = mirror_latch_world + with request_declaration({"headers": []}): + await gates.session_content(OPERATIONS_BY_NAME["conversation.create"], None) + await gates.session_content(OPERATIONS_BY_NAME["run.begin"], None) + assert world.counts["barrier"] == 2 and not world.leases + world.enabled = True # The existing backend view still reports absence. + with pytest.raises(SessionProtectionRequiredError): + await gates.session_content(OPERATIONS_BY_NAME["conversation.create"], None) + assert world.counts["barrier"] == 3 and not world.leases + + +async def test_unit_store_unreadability_refuses_before_http_body(monkeypatch, mirror_latch_world): + from fastapi import Request, Response + + from server.transport import http + + world = mirror_latch_world + world.fault = "wrong_engine" + monkeypatch.setattr(http, "_extract_auth", lambda request: None) + body = AsyncMock(side_effect=AssertionError("private body must not be read")) + monkeypatch.setattr(http, "_read_body", body) + endpoint = http._make_endpoint(OPERATIONS_BY_NAME["conversation.create"]) + with request_declaration({"headers": []}): + with pytest.raises(SessionProtectionRequiredError): + await endpoint(Request({"type": "http", "headers": []}), Response()) + body.assert_not_awaited() + assert world.calls == ["engines"] + + +async def test_declared_switch_on_client_reasserts_the_real_latch_before_admission( + monkeypatch, mirror_latch_world +): + from server.settings import settings + + monkeypatch.setattr(settings, "knowledge_mirrored_sources_enabled", True) + with request_declaration({"headers": [(b"x-loom-session-protection", b"v1")]}): + await gates.session_content(OPERATIONS_BY_NAME["conversation.create"], None) + assert mirror_latch_world.enabled and mirror_latch_world.counts["set"] == 1 + + +async def test_first_on_startup_and_existing_beat_reassert_durable_state( + monkeypatch, mirror_latch_world +): + from server import boot + from server.settings import settings + from server.workers import leader + + world = mirror_latch_world + monkeypatch.setattr(settings, "knowledge_mirrored_sources_enabled", True) + + async def after_repair(ch): + assert ch is world and world.enabled and world.counts["set"] == 2 + + read_holder = AsyncMock(side_effect=after_repair) + monkeypatch.setattr(leader, "read_holder", read_holder) + await boot.require_session_protection(world) + assert world.enabled and world.counts["set"] == 1 + # A lost row while the process is on must not look like a never-enabled boot. + world.enabled = False + await boot.refresh_instance_state(world) + assert world.enabled and world.counts["set"] == 2 + read_holder.assert_awaited_once_with(world) + + +async def test_first_on_startup_failure_cannot_advance_to_the_instance_read( + monkeypatch, mirror_latch_world +): + from server import boot + from server.settings import settings + from server.workers import leader + + monkeypatch.setattr(settings, "knowledge_mirrored_sources_enabled", True) + mirror_latch_world.fault = "wrong_engine" + read_holder = AsyncMock() + monkeypatch.setattr(leader, "read_holder", read_holder) + with pytest.raises(mirror_latch.LatchUnavailable): + await boot.require_session_protection(mirror_latch_world) + with pytest.raises(mirror_latch.LatchUnavailable): + await boot.refresh_instance_state(mirror_latch_world) + read_holder.assert_not_awaited() diff --git a/tests/unit/test_session_protection_declaration.py b/tests/unit/test_session_protection_declaration.py new file mode 100644 index 0000000000..d4c4cae7d0 --- /dev/null +++ b/tests/unit/test_session_protection_declaration.py @@ -0,0 +1,203 @@ +"""Transport promises stay request-local and cannot upgrade an assistant caller.""" + +from __future__ import annotations + +import asyncio +from dataclasses import replace +from typing import Any + +import jwt +import pytest +from fastapi import Request +from fastapi.testclient import TestClient +from starlette.responses import StreamingResponse + +from server.assistant.app import bridge +from server.auth.answer_tokens import ANSWER_JTI_PREFIX +from server.auth.delegation import Delegated +from server.auth.jwt import AuthInfo, TokenError, mint_token, verify_token +from server.auth.session_protection import protected_for, request_declaration +from server.operations.base import Role +from server.transport.request_scope import HTTPApplication + +_SECRET = "session-protection-unit-signing-key-unchanged" +_HEADER = (b"x-loom-session-protection", b"v1") + + +def _auth(**kwargs: Any) -> AuthInfo: + return AuthInfo( + **{ + "subject": "reader", + "org": "example", + "namespaces": ("notes",), + "roles": (Role.VIEWER,), + "is_service_account": False, + "token_id": "caller", + **kwargs, + } + ) + + +@pytest.mark.parametrize( + ("headers", "expected"), + [ + ([], False), + ([_HEADER], True), + ([(b"X-Loom-Session-Protection", b"v1")], True), + ([(b"x-loom-session-protection", b"true")], False), + ([(b"x-loom-session-protection", b"v2")], False), + ([(b"x-loom-session-protection", b"v1, v1")], False), + ([_HEADER, _HEADER], False), + ([_HEADER, (b"x-loom-session-protection", b"false")], False), + ([(b"user-agent", b"loom-protected-v1")], False), + ], +) +def test_only_one_versioned_transport_promise_is_accepted( + headers: list[tuple[bytes, bytes]], expected: bool +) -> None: + assert not protected_for(None) + with request_declaration({"headers": headers}): + assert protected_for(_auth()) is expected + assert not protected_for(None) + + +@pytest.mark.parametrize( + "identity", + [ + {"consumer": "loom-assistant"}, + {"token_id": f"{ANSWER_JTI_PREFIX}bounded"}, + {"parents": ("root", f"{ANSWER_JTI_PREFIX}bounded")}, + ], +) +@pytest.mark.parametrize("caller_protected", [False, True]) +def test_an_answer_and_its_descendants_use_only_the_fixed_claim( + identity: dict[str, Any], caller_protected: bool +) -> None: + auth = _auth(**identity, session_protection=caller_protected) + for headers in ([], [_HEADER]): + with request_declaration({"headers": headers}): + assert protected_for(auth) is caller_protected + + +@pytest.mark.asyncio +async def test_concurrent_requests_and_child_tasks_keep_their_own_promise() -> None: + arrived = asyncio.Event() + release = asyncio.Event() + + async def declared() -> bool: + with request_declaration({"headers": [_HEADER]}): + arrived.set() + await release.wait() + return await asyncio.create_task(_read()) + + async def _read() -> bool: + await asyncio.sleep(0) + return protected_for(None) + + task = asyncio.create_task(declared()) + await arrived.wait() + with request_declaration({"headers": []}): + assert not await asyncio.create_task(_read()) + release.set() + assert await task + assert not protected_for(None) + assert not protected_for(None) + + +def test_nested_or_failed_requests_restore_the_previous_promise() -> None: + with request_declaration({"headers": [_HEADER]}): + with pytest.raises(RuntimeError), request_declaration({"headers": []}): + assert not protected_for(None) + raise RuntimeError("interrupted") + assert protected_for(None) + assert not protected_for(None) + + +def test_the_http_owner_keeps_the_promise_through_middleware_and_streaming() -> None: + app = HTTPApplication() + + @app.middleware("http") + async def middleware(request: Request, call_next: Any) -> Any: + return await call_next(request) + + @app.get("/promise") + async def promise() -> StreamingResponse: + async def chunks() -> Any: + await asyncio.sleep(0) + yield b"protected" if protected_for(None) else b"unknown" + + return StreamingResponse(chunks()) + + with TestClient(app) as client: + assert ( + client.get("/promise", headers={"X-Loom-Session-Protection": "v1"}).text == "protected" + ) + assert client.get("/promise").text == "unknown" + assert not protected_for(None) + + +@pytest.mark.parametrize("declared", [False, True]) +def test_the_signed_promise_survives_token_verification(declared: bool) -> None: + token = mint_token( + "reader", + "example", + ["notes"], + ["viewer"], + secret=_SECRET, + session_protection=declared, + ) + assert verify_token(token, secret=_SECRET).session_protection is declared + + +@pytest.mark.parametrize("claim", ["false", "true", 0, 1, None, [], {}]) +def test_a_signed_non_boolean_promise_is_refused(claim: Any) -> None: + with pytest.raises(TokenError, match="must be a boolean"): + mint_token( + "reader", "example", ["notes"], ["viewer"], secret=_SECRET, session_protection=claim + ) + token = mint_token("reader", "example", ["notes"], ["viewer"], secret=_SECRET) + payload = jwt.decode(token, options={"verify_signature": False}) + payload["session_protection"] = claim + invalid = jwt.encode(payload, _SECRET, algorithm="HS256", headers={"kid": "override"}) + with pytest.raises(TokenError, match="must be a boolean"): + verify_token(invalid, secret=_SECRET) + + +@pytest.mark.parametrize("caller_protected", [False, True]) +@pytest.mark.asyncio +async def test_the_bridge_fixes_the_callers_declaration_in_the_answer( + monkeypatch: pytest.MonkeyPatch, caller_protected: bool +) -> None: + parent = _auth() + + async def delegate(auth: AuthInfo, **kwargs: Any) -> Delegated: + return Delegated( + org="example", + namespaces=["notes"], + roles=["viewer"], + ns_roles=None, + write_namespaces=None, + read_scope="", + read_user_id="", + ttl_seconds=60, + parents=[*auth.parents, auth.token_id], + parent_subjects=[*auth.parent_subjects, auth.subject], + parent_iats=[*auth.parent_iats, auth.issued_at or 0], + creator="reader", + is_service_account=False, + ) + + monkeypatch.setattr(bridge, "delegate", delegate) + with request_declaration({"headers": [_HEADER] if caller_protected else []}): + token = await bridge.answer_token(parent, "example", "notes") + answer = verify_token(token) + assert answer.session_protection is caller_protected + with request_declaration({"headers": [] if caller_protected else [_HEADER]}): + assert protected_for(answer) is caller_protected + child = verify_token((await delegate(answer)).mint("sa:child")) + assert not child.session_protection + assert not protected_for(child) + # A forged local field is not inherited by ordinary delegation either. + assert not verify_token( + (await delegate(replace(answer, session_protection=True))).mint("sa:other-child") + ).session_protection diff --git a/tests/unit/test_source_access.py b/tests/unit/test_source_access.py new file mode 100644 index 0000000000..29194acdfb --- /dev/null +++ b/tests/unit/test_source_access.py @@ -0,0 +1,200 @@ +"""A permission list admits one verified reader, independently of its candidates.""" + +from __future__ import annotations + +import pytest + +from server.knowledge.domain.access_list import UNREAD, AccessList, allows, from_json + + +@pytest.mark.parametrize( + "access,subject,emails,domains,groups,owner,expected", + [ + (AccessList(anyone=True), "", (), (), (), "", True), + ( + UNREAD, + "lee", + ("lee@example.com",), + ("example.com",), + ("team@example.com",), + "lee", + False, + ), + ( + AccessList(), + "lee", + ("lee@example.com",), + ("example.com",), + ("team@example.com",), + "", + False, + ), + (AccessList(owner="alias@example.com"), "lee", (), (), (), "lee", True), + (AccessList(owner="alias@example.com"), "other", (), (), (), "lee", False), + (AccessList(owner="lee"), "", (), (), (), "lee", False), + (AccessList(emails=("lee@example.com",)), "lee", ("lee@example.com",), (), (), "", True), + (AccessList(emails=("lee@example.com",)), "lee@example.com", (), (), (), "", False), + (AccessList(emails=("lee@example.com",)), "", ("lee@example.com",), (), (), "", False), + (AccessList(domains=("example.com",)), "lee", ("lee@example.com",), (), (), "", False), + (AccessList(domains=("example.com",)), "lee", (), ("example.com",), (), "", True), + (AccessList(domains=("example.com",)), "lee", (), ("sub.example.com",), (), "", False), + ( + AccessList(groups=("team@example.com",)), + "lee", + ("lee@example.com",), + (), + ("team@example.com",), + "", + True, + ), + ( + AccessList(groups=("team@example.com",)), + "lee", + ("lee@example.com",), + (), + ("other@example.com",), + "", + False, + ), + (AccessList(groups=("team@example.com",)), "", (), (), ("team@example.com",), "", False), + ], +) +def test_one_verified_person_or_discoverable_anyone( + access, subject, emails, domains, groups, owner, expected +): + assert ( + allows( + access, + subject=subject, + emails=frozenset(emails), + domains=frozenset(domains), + groups=frozenset(groups), + canonical_owner=owner, + ) + is expected + ) + + +@pytest.mark.parametrize( + "text", + [ + "", + "{", + "null", + "[]", + '{"anyone":true}', + '{"unread":false,"anyone":"true"}', + '{"unread":false,"anyone":1}', + '{"unread":false,"anyone":true,"future_restriction":true}', + '{"unread":false,"emails":[true],"anyone":true}', + '{"unread":false,"groups":"team@example.com","anyone":true}', + '{"unread":false,"owner":[],"anyone":true}', + ], +) +def test_malformed_permission_never_reaches_anyone_or_identity_arms(text): + assert not allows( + from_json(text), + subject="lee", + emails=frozenset({"lee@example.com"}), + domains=frozenset({"example.com"}), + groups=frozenset({"team@example.com"}), + canonical_owner="lee", + ) + + +@pytest.mark.parametrize( + "tags,uri,expected", + [ + ( + ["source-id:11111111-1111-4111-8111-111111111111"], + "gdrive:file#11111111-1111-4111-8111-111111111111", + "11111111-1111-4111-8111-111111111111", + ), + (["source:name"], "gdrive:file#11111111-1111-4111-8111-111111111111", ""), + ( + ["source-id:11111111-1111-4111-8111-111111111111"], + "gdrive:file#22222222-2222-4222-8222-222222222222", + "", + ), + ( + [ + "source-id:11111111-1111-4111-8111-111111111111", + "source-id:22222222-2222-4222-8222-222222222222", + ], + "gdrive:file#11111111-1111-4111-8111-111111111111", + "", + ), + (["source-id:bad"], "gdrive:file#bad", ""), + ( + ["source-id:11111111-1111-4111-8111-111111111111"], + "#11111111-1111-4111-8111-111111111111", + "", + ), + ], +) +def test_source_identity_requires_one_id_and_its_address_suffix(tags, uri, expected): + from server.knowledge.domain.document_access import source_id + + assert source_id(uri, tags) == expected + + +@pytest.mark.parametrize( + "age,expected", [(0, True), (3599, True), (3600, True), (3601, False), (-1, False)] +) +def test_listing_and_group_age_must_be_known_and_within_bound(age, expected): + from datetime import UTC, datetime, timedelta + + from server.knowledge.domain.document_access import fresh + + now = datetime(2026, 1, 1, tzinfo=UTC) + assert fresh(now - timedelta(seconds=age), now, 3600) is expected + assert not fresh(None, now, 3600) + + +@pytest.mark.asyncio +async def test_child_leg_mark_is_monotonic_and_visible_after_private_scope(): + import asyncio + + from server.core import request_work + from server.core.diagnostics import private_work + + bag = request_work.begin() + + async def child(): + with private_work(): + request_work.mark_mirrored(unread=True) + request_work.mark_mirrored() + + await asyncio.gather(child(), child()) + assert request_work.mirror_marked() and bag.mirror_unread + + +@pytest.mark.asyncio +async def test_next_request_has_no_preceding_mirror_mark(): + from server.core import request_work + + first = request_work.begin() + request_work.mark_mirrored(unread=True) + second = request_work.begin() + assert first.mirror_marked and first.mirror_unread + assert not request_work.mirror_marked() and not second.mirror_unread + + +def test_candidate_keys_are_coarse_and_keep_unknown_readers_to_anyone(): + from server.knowledge.domain.access_list import candidate_keys + + assert candidate_keys(subject="", emails=frozenset(), domains=frozenset()) == ["anyone"] + keys = candidate_keys( + subject="reader", + emails=frozenset({"lee@example.com"}), + domains=frozenset({"example.com"}), + ) + assert set(keys) == { + "anyone", + "owner", + "group", + "email_unicode", + "domain_unicode", + "e:lee@example.com", + "d:example.com", + } diff --git a/tests/unit/test_source_access_plan.py b/tests/unit/test_source_access_plan.py new file mode 100644 index 0000000000..a85e57e2b4 --- /dev/null +++ b/tests/unit/test_source_access_plan.py @@ -0,0 +1,546 @@ +"""Every mirror leg shares source freshness, strict permissions and failure policy.""" + +from __future__ import annotations + +import asyncio +from datetime import UTC, datetime, timedelta +from unittest.mock import AsyncMock + +import pytest + +from server.auth.jwt import AuthInfo +from server.auth.reader_identity import ReaderIdentity +from server.core import request_work +from server.knowledge.app import source_access as app +from server.knowledge.domain.access_list import AccessList, to_json +from server.knowledge.domain.serving import Serving +from server.operations.base import Role + +SID = "11111111-1111-4111-8111-111111111111" +MIRROR = "acl-" + "1" * 24 +URI = "gdrive:file#" + SID +NOW = datetime(2026, 1, 1, tzinfo=UTC) + + +@pytest.fixture +def world(monkeypatch): + token = request_work._current.set(None) + bag = request_work.begin() + auth = AuthInfo( + subject="lee", + org="acme", + namespaces=("docs",), + roles=(Role.VIEWER,), + session_id="sid", + is_service_account=False, + ) + doc = { + "org": "acme", + "namespace": MIRROR, + "source_uri": URI, + "tags": ["source-id:" + SID], + "version": 10, + "revision": 0, + "title": "checked title", + "superseded_at": None, + "access_json": to_json(AccessList(emails=("lee@example.com",))), + } + mocks = { + "sources": AsyncMock(return_value=[{"namespace": "docs", "source_id": SID}]), + "mirrors": AsyncMock(return_value={MIRROR: "docs"}), + "listings": AsyncMock( + return_value=[{"namespace": MIRROR, "source_id": SID, "started_at": NOW}] + ), + "metadata": AsyncMock(side_effect=lambda *_a, **_k: [dict(doc)]), + "groups": AsyncMock(return_value=[]), + "heads": AsyncMock(return_value={}), + "reader": AsyncMock( + return_value=ReaderIdentity("lee", frozenset({"lee@example.com"}), frozenset()) + ), + "owner": AsyncMock(return_value="lee"), + "gate": AsyncMock(), + "bag": bag, + "doc": doc, + } + monkeypatch.setattr(app, "current_auth", lambda: auth) + monkeypatch.setattr(app.settings, "auth_required", True) + monkeypatch.setattr(app.settings, "knowledge_source_acl_stale_seconds", 3600) + monkeypatch.setattr(app, "now", lambda: NOW) + monkeypatch.setattr(app, "check_authorized", mocks["gate"]) + monkeypatch.setattr(app, "resolve_reader", mocks["reader"]) + monkeypatch.setattr(app, "canonical_subject", mocks["owner"]) + monkeypatch.setattr(app.pg, "enabled", lambda: False) + monkeypatch.setattr(app.store, "active_sources", mocks["sources"]) + monkeypatch.setattr(app.mirrors_repo, "mirrors_of", mocks["mirrors"]) + monkeypatch.setattr(app.store, "listings", mocks["listings"]) + monkeypatch.setattr(app.store, "metadata", mocks["metadata"]) + monkeypatch.setattr(app.store, "group_members", mocks["groups"]) + monkeypatch.setattr(app.store, "heads", mocks["heads"]) + yield mocks + request_work._current.reset(token) + + +def candidate(**changes): + return {"namespace": MIRROR, "source_uri": URI, "doc_version": 10, "revision": 0, **changes} + + +async def test_owner_resolution_is_shared_within_one_batch_and_fresh_in_the_next(world): + world["doc"]["access_json"] = to_json(AccessList(owner="owner@example.com")) + plan = await app.prepare("acme", ["docs"]) + rows = [candidate(chunk_idx=i) for i in range(64)] + assert len(await plan.check(rows, chunks=True)) == 64 + assert world["owner"].await_count == 1 + world["owner"].return_value = "somebody-else" + assert await plan.check(rows, chunks=True) == [] + assert world["owner"].await_count == 2 + + +async def test_active_source_marks_even_without_admitted_documents(world): + plan = await app.prepare("acme", ["docs"]) + world["doc"]["access_json"] = to_json(AccessList(emails=("other@example.com",))) + assert await plan.check([candidate()], chunks=True) == [] + assert plan.marked and not plan.unread and world["bag"].mirror_marked + world["gate"].assert_awaited_once() + + +async def test_checked_document_retains_its_scope_and_metadata(world): + plan = await app.prepare("acme", ["docs"]) + [admitted] = await plan.check([candidate()], chunks=True) + assert admitted.namespace == "docs" and admitted.candidate == candidate() + assert admitted.document == world["doc"] + + +@pytest.mark.parametrize("stage", ["sources", "mirrors", "listings", "reader"]) +async def test_unconditional_read_failure_has_one_public_marker(world, stage): + world[stage].side_effect = RuntimeError("private row or backend cause") + plan = await app.prepare("acme", ["docs"]) + assert await plan.check([candidate()], chunks=True) == [] + assert plan.marked and plan.unread and world["bag"].mirror_unread + + +async def test_no_active_mirrored_source_runs_no_leg(world): + world["sources"].return_value = [] + plan = await app.prepare("acme", ["docs"]) + assert not plan.marked and not world["bag"].mirror_marked + world["mirrors"].assert_not_awaited() + world["reader"].assert_not_awaited() + + +@pytest.mark.parametrize( + "change", ["auth_off", "missing_binding", "stale_listing", "future_listing", "wrong_source"] +) +async def test_missing_scope_or_freshness_admits_nothing(world, monkeypatch, change): + if change == "auth_off": + monkeypatch.setattr(app.settings, "auth_required", False) + elif change == "missing_binding": + world["mirrors"].return_value = {} + elif change in {"stale_listing", "future_listing"}: + world["listings"].return_value[0]["started_at"] = NOW + timedelta( + seconds=-3601 if change == "stale_listing" else 1 + ) + else: + world["doc"]["tags"] = ["source-id:22222222-2222-4222-8222-222222222222"] + plan = await app.prepare("acme", ["docs"]) + assert await plan.check([candidate()], chunks=True) == [] + assert not plan.unread + + +async def test_unbound_direct_helper_serves_no_mirror(world): + request_work._current.set(None) + plan = await app.prepare("acme", ["docs"]) + assert await plan.check([candidate()], chunks=True) == [] + world["metadata"].assert_not_awaited() + + +@pytest.mark.parametrize("stage", ["metadata", "heads", "groups", "owner"]) +async def test_candidate_failure_discards_prior_results_without_read_marker( + world, monkeypatch, stage +): + plan = await app.prepare("acme", ["docs"]) + assert await plan.check([candidate()], chunks=True) + if stage == "heads": + monkeypatch.setattr(app.pg, "enabled", lambda: True) + if stage == "groups": + world["doc"]["access_json"] = to_json(AccessList(groups=("team@example.com",))) + if stage == "owner": + world["doc"]["access_json"] = to_json(AccessList(owner="alias@example.com")) + world[stage].side_effect = RuntimeError("private candidate error") + assert await plan.check([candidate()], chunks=True) == [] + assert plan.failed and not plan.unread and not world["bag"].mirror_unread + assert await plan.check([candidate()], chunks=True) == [] + + +@pytest.mark.parametrize( + "state", ["missing", "deleted", "wrong_revision", "missing_chunk_state", "old_chunk_version"] +) +async def test_pg_requires_current_live_head_and_recorded_chunk_pair(world, monkeypatch, state): + monkeypatch.setattr(app.pg, "enabled", lambda: True) + head = app.store.ReadHead(dict(world["doc"]), Serving(False, 0, 0, 10)) + if state == "deleted": + head = head._replace(serving=Serving(True, 0, 0, 10)) + elif state == "wrong_revision": + head = head._replace(serving=Serving(False, 1, 1, 10)) + elif state == "missing_chunk_state": + head = head._replace(serving=Serving(False, 0, None, None)) + elif state == "old_chunk_version": + head = head._replace(serving=Serving(False, 0, 0, 11)) + world["heads"].return_value = {} if state == "missing" else {(MIRROR, URI): head} + plan = await app.prepare("acme", ["docs"]) + assert await plan.check([candidate()], chunks=True) == [] + assert not plan.unread + + +async def test_pg_metadata_only_acl_uses_recorded_chunks_and_current_permission(world, monkeypatch): + monkeypatch.setattr(app.pg, "enabled", lambda: True) + world["doc"]["access_json"] = "" # publication has not carried a widening yet + head = { + **world["doc"], + "version": 11, + "access_json": to_json(AccessList(emails=("lee@example.com",))), + } + world["heads"].return_value = { + (MIRROR, URI): app.store.ReadHead(head, Serving(False, 0, 0, 10)) + } + plan = await app.prepare("acme", ["docs"]) + assert len(await plan.check([candidate()], chunks=True)) == 1 + head["access_json"] = to_json(AccessList(emails=("other@example.com",))) + assert await plan.check([candidate()], chunks=True) == [] + + +async def test_pg_document_admission_retains_serving_state_for_checked_counts(world, monkeypatch): + monkeypatch.setattr(app.pg, "enabled", lambda: True) + serving = Serving(False, 0, 0, 9) + world["heads"].return_value = {(MIRROR, URI): app.store.ReadHead(dict(world["doc"]), serving)} + plan = await app.prepare("acme", ["docs"]) + [admitted] = await plan.check([candidate()]) + assert admitted.serving == serving + + +async def test_group_membership_is_current_and_bound_to_owning_source(world): + world["doc"]["access_json"] = to_json(AccessList(groups=("team@example.com",))) + row = { + "namespace": MIRROR, + "source_id": SID, + "group": "team@example.com", + "members": ["lee@example.com"], + "read_at": NOW, + "deleted": False, + } + world["groups"].return_value = [row] + plan = await app.prepare("acme", ["docs"]) + assert len(await plan.check([candidate()], chunks=True)) == 1 + for changed in ( + {"source_id": "other"}, + {"namespace": "acl-" + "2" * 24}, + {"read_at": NOW - timedelta(seconds=3601)}, + {"deleted": True}, + ): + world["groups"].return_value = [{**row, **changed}] + assert await plan.check([candidate()], chunks=True) == [] + + +async def test_registry_read_is_sequential_before_listing_evidence(world, monkeypatch): + from contextlib import contextmanager + + held = [] + + @contextmanager + def sequential(): + held.append(True) + try: + yield + finally: + held.pop() + + async def sources(*_args, **_kwargs): + assert held + return [{"namespace": "docs", "source_id": SID}] + + monkeypatch.setattr(app, "sequential_reads", sequential) + world["sources"].side_effect = sources + plan = await app.prepare("acme", ["docs"]) + assert not plan.unread and plan.sources == {(MIRROR, SID): "docs"} + + +@pytest.mark.parametrize("authority", ["clickhouse", "postgres"]) +async def test_wrong_tenant_document_metadata_cannot_authorize(world, monkeypatch, authority): + world["doc"]["org"] = "another-org" + if authority == "postgres": + monkeypatch.setattr(app.pg, "enabled", lambda: True) + world["heads"].return_value = { + (MIRROR, URI): app.store.ReadHead(dict(world["doc"]), Serving(False, 0, 0, 10)) + } + plan = await app.prepare("acme", ["docs"]) + assert await plan.check([candidate()], chunks=True) == [] + + +@pytest.mark.parametrize("chunks", [False, True]) +async def test_pg_head_metadata_must_match_requested_pair_and_serving_revision( + world, monkeypatch, chunks +): + monkeypatch.setattr(app.pg, "enabled", lambda: True) + for change in ({"namespace": "other"}, {"source_uri": "other"}, {"revision": 1}): + world["heads"].return_value = { + (MIRROR, URI): app.store.ReadHead({**world["doc"], **change}, Serving(False, 0, 0, 10)) + } + plan = await app.prepare("acme", ["docs"]) + assert await plan.check([candidate()], chunks=chunks) == [] + + +async def test_listing_freshness_is_checked_when_each_batch_is_admitted(world, monkeypatch): + plan = await app.prepare("acme", ["docs"]) + assert await plan.check([candidate()], chunks=True) + monkeypatch.setattr(app, "now", lambda: NOW + timedelta(seconds=3601)) + assert await plan.check([candidate()], chunks=True) == [] + assert not plan.unread + + +async def test_ch_content_revision_must_match_current_metadata_without_requiring_metadata_version( + world, +): + world["doc"]["revision"] = 1 + plan = await app.prepare("acme", ["docs"]) + assert await plan.check([candidate(revision=0)], chunks=True) == [] + assert await plan.check([candidate(revision=2)], chunks=True) == [] + world["doc"]["version"] = 11 + assert len(await plan.check([candidate(revision=1, doc_version=10)], chunks=True)) == 1 + + +@pytest.mark.parametrize("count", [65, 129]) +@pytest.mark.parametrize("independent", ["none", "email", "owner", "domain", "anyone"]) +async def test_final_pool_rechecks_group_expiry_without_removing_independent_grants( + world, monkeypatch, count, independent +): + from server.knowledge.app import source_search + + access = {"groups": ("team@example.com",)} + if independent == "email": + access["emails"] = ("lee@example.com",) + elif independent == "owner": + access["owner"] = "owner-alias" + elif independent == "domain": + access["domains"] = ("example.com",) + elif independent == "anyone": + access["anyone"] = True + world["doc"]["access_json"] = to_json(AccessList(**access)) + world["reader"].return_value = ReaderIdentity( + "lee", frozenset({"lee@example.com"}), frozenset({"example.com"}) + ) + calls = 0 + + async def metadata(_org, pairs): + nonlocal calls + calls += 1 + if calls > 1: + monkeypatch.setattr(app, "now", lambda: NOW + timedelta(seconds=10)) + return [{**world["doc"], "source_uri": uri} for _namespace, uri in pairs] + + world["metadata"].side_effect = metadata + world["groups"].return_value = [ + { + "namespace": MIRROR, + "source_id": SID, + "group": "team@example.com", + "members": ["lee@example.com"], + "read_at": NOW - timedelta(seconds=3599), + "deleted": False, + } + ] + plan = await app.prepare("acme", ["docs"]) + retained = [ + app.Admitted("docs", candidate(source_uri=f"gdrive:file-{i}#" + SID, chunk_idx=0), {}) + for i in range(count) + ] + out = await source_search.recheck(plan, {"semantic": retained}) + assert len(out["semantic"]) == (0 if independent == "none" else count) + assert not plan.failed and not plan.unread + + +@pytest.mark.parametrize("change", ["permission", "revision", "listing", "group"]) +async def test_content_is_discarded_if_access_changes_during_hydration(world, monkeypatch, change): + from server.knowledge.app import source_search + + if change == "group": + world["doc"]["access_json"] = to_json(AccessList(groups=("team@example.com",))) + world["groups"].return_value = [ + { + "namespace": MIRROR, + "source_id": SID, + "group": "team@example.com", + "members": ["lee@example.com"], + "read_at": NOW - timedelta(seconds=3599), + "deleted": False, + } + ] + plan = await app.prepare("acme", ["docs"]) + [retained] = await plan.check([candidate(chunk_idx=0)], chunks=True) + + async def chunks(_org, _model, _keys, *, embedded_only=True): + assert embedded_only + if change == "permission": + world["doc"]["access_json"] = to_json(AccessList()) + elif change == "revision": + world["doc"]["revision"] = 1 + else: + age = 3601 if change == "listing" else 10 + monkeypatch.setattr(app, "now", lambda: NOW + timedelta(seconds=age)) + return [{**retained.candidate, "content": "never returned"}] + + monkeypatch.setattr(source_search.store, "chunks", chunks) + assert await source_search.hydrate(plan, {"semantic": [retained]}, model="fake") == { + "semantic": [] + } + assert not plan.failed and not plan.unread and not world["bag"].mirror_unread + + +@pytest.mark.parametrize( + "change", ["inactive", "missing_binding", "ambiguous_binding", "listing", "reader"] +) +async def test_each_batch_refreshes_current_source_and_reader_evidence(world, change): + plan = await app.prepare("acme", ["docs"]) + assert await plan.check([candidate()], chunks=True) + if change == "inactive": + world["sources"].return_value = [] + elif change == "missing_binding": + world["mirrors"].return_value = {} + elif change == "ambiguous_binding": + world["mirrors"].return_value = {MIRROR: "docs", "acl-" + "2" * 24: "docs"} + elif change == "listing": + world["listings"].return_value = [] + else: + world["reader"].return_value = ReaderIdentity("lee", frozenset(), frozenset()) + assert await plan.check([candidate()], chunks=True) == [] + assert not plan.failed and not plan.unread and not world["bag"].mirror_unread + + +@pytest.mark.parametrize("stage", ["sources", "mirrors", "listings", "reader"]) +async def test_scope_refresh_failures_are_conditional_without_unread(world, stage): + plan = await app.prepare("acme", ["docs"]) + assert await plan.check([candidate()], chunks=True) + world[stage].side_effect = RuntimeError("private refresh failure") + assert await plan.check([candidate()], chunks=True) == [] + assert plan.failed and not plan.unread and not world["bag"].mirror_unread + + +async def test_refresh_never_adds_new_source_legs_or_rebinds_initial_sources(world): + plan = await app.prepare("acme", ["docs"]) + second = "22222222-2222-4222-8222-222222222222" + world["sources"].return_value.append({"namespace": "docs", "source_id": second}) + world["listings"].return_value.append( + {"namespace": MIRROR, "source_id": second, "started_at": NOW} + ) + assert await plan.check([candidate()], chunks=True) + assert plan.sources == {(MIRROR, SID): "docs"} + replacement = "acl-" + "2" * 24 + world["mirrors"].return_value = {replacement: "docs"} + world["listings"].return_value = [ + {"namespace": replacement, "source_id": SID, "started_at": NOW} + ] + assert await plan.check([candidate()], chunks=True) == [] + assert not plan.sources and not plan.unread + + +@pytest.mark.parametrize("independent", ["owner", "anyone"]) +async def test_reader_contact_loss_keeps_independent_permission_arms(world, independent): + world["doc"]["access_json"] = to_json( + AccessList( + **{ + "emails": ("lee@example.com",), + independent: "owner-alias" if independent == "owner" else True, + } + ) + ) + plan = await app.prepare("acme", ["docs"]) + assert await plan.check([candidate()], chunks=True) + world["reader"].return_value = ReaderIdentity("lee", frozenset(), frozenset()) + assert await plan.check([candidate()], chunks=True) + assert plan.reader.emails == frozenset() + assert not plan.failed and not plan.unread + + +@pytest.mark.parametrize("independent", [False, True]) +async def test_old_group_proof_cannot_follow_a_changed_verified_email_set(world, independent): + world["doc"]["access_json"] = to_json( + AccessList(groups=("group@example.com",), anyone=independent) + ) + world["groups"].return_value = [ + { + "namespace": MIRROR, + "source_id": SID, + "group": "group@example.com", + "members": ["lee@example.com"], + "read_at": NOW, + "deleted": False, + } + ] + plan = await app.prepare("acme", ["docs"]) + [earlier] = await plan.check([candidate()], chunks=True) + world["reader"].return_value = ReaderIdentity( + "lee", frozenset({"other@example.com"}), frozenset() + ) + later = await plan.check([candidate()], chunks=True) + assert bool(later) is independent + assert plan.current(earlier) is independent + assert not plan.failed and not plan.unread + + +async def test_overlapping_checks_cannot_restore_a_source_after_observing_its_removal(world): + plan = await app.prepare("acme", ["docs"]) + started, release = asyncio.Event(), asyncio.Event() + calls = 0 + + async def active_sources(*_args): + nonlocal calls + calls += 1 + if calls == 1: + snapshot = list(world["sources"].return_value) + started.set() + await release.wait() + return snapshot + return [] + + world["sources"].side_effect = active_sources + earlier = asyncio.create_task(plan.check([candidate()], chunks=True)) + await started.wait() + later = asyncio.create_task(plan.check([candidate()], chunks=True)) + try: + await asyncio.sleep(0) + assert not later.done() + finally: + release.set() + first, last = await asyncio.gather(earlier, later) + assert first and not last and calls == 2 + assert not plan.current(first[0]) and not plan.sources + assert not plan.failed and not plan.unread + + +async def test_a_queued_check_observes_an_earlier_checks_failure(world): + plan = await app.prepare("acme", ["docs"]) + started, release = asyncio.Event(), asyncio.Event() + + async def failed_metadata(*_args): + started.set() + await release.wait() + raise RuntimeError("private failed evidence") + + world["metadata"].side_effect = failed_metadata + earlier = asyncio.create_task(plan.check([candidate()], chunks=True)) + await started.wait() + later = asyncio.create_task(plan.check([candidate()], chunks=True)) + release.set() + assert await asyncio.gather(earlier, later) == [[], []] + assert world["metadata"].await_count == 1 + assert plan.failed and not plan.unread + + +async def test_conditional_refresh_preserves_discovery_sources_and_reader(world): + plan = await app.prepare("acme", ["docs"]) + initial_reader = plan.discovery_reader + world["sources"].return_value = [] + world["reader"].return_value = ReaderIdentity("lee", frozenset(), frozenset()) + assert await plan.check([candidate()], chunks=True) == [] + assert plan.discovery_sources == {(MIRROR, SID): "docs"} + assert plan.discovery_reader is initial_reader + assert initial_reader.emails == frozenset({"lee@example.com"}) + plan.discovery_sources.clear() + assert plan.discovery_sources == {(MIRROR, SID): "docs"} diff --git a/tests/unit/test_source_ask_generation.py b/tests/unit/test_source_ask_generation.py new file mode 100644 index 0000000000..4bf635fdc9 --- /dev/null +++ b/tests/unit/test_source_ask_generation.py @@ -0,0 +1,372 @@ +"""A lost document proof discards a complete generated answer and its derived state.""" + +from __future__ import annotations + +import asyncio +import copy +import dataclasses +import json +from types import SimpleNamespace + +import pytest + +from server.core import request_work +from server.knowledge.api.models_knowledge import KnowledgeSearchOutput, _SearchHit +from server.knowledge.app import knowledge_search, source_access +from server.knowledge.app.knowledge_search import CheckedSearch, SearchRequest +from server.knowledge.app.source_access import ReadPlan +from server.knowledge.app.source_corpus import LostCorpus +from server.memory.app.ask import cascade, handler, pipeline +from server.observability import cost_accumulator +from server.observability.genai import current_stage +from tests.unit.test_ask_synth_accounting import _ask, make_env + + +def _passage(name): + return _SearchHit( + namespace="ns", + source_uri=name, + chunk_idx=0, + content=name, + tags=[], + distance=0.2, + similarity=0.8, + ) + + +def _plain(value): + if hasattr(value, "model_dump"): + return value.model_dump() + if dataclasses.is_dataclass(value): + return dataclasses.asdict(value) + return vars(value) if hasattr(value, "__dict__") else value + + +def _snapshot(run): + return copy.deepcopy( + { + "rows": { + name: [_plain(row) for row in getattr(run, name)] + for name in ("ranked", "memories", "results", "synth_pool") + }, + "intent": _plain(run.intent), + "search": _plain(run.search_input), + } + ) + + +class _Proof: + mirrored = True + + def __init__(self, world): + self.world = world + self.invalid = False + + def fresh(self): + return not self.invalid and self.world.allowed + + async def check(self): + if not self.fresh(): + self.invalid = True + raise LostCorpus() + + +class _Renderer: + marked = True + + def __init__(self, world): + self.world = world + + async def render(self, _rows, _dropped): + self.world.renders += 1 + await asyncio.sleep(0) + return KnowledgeSearchOutput( + results=[_passage("ordinary:document")], embedding_model="fake-embed" + ) + + +class _World: + provider = "fake" + model = "gpt-4o-mini" + + def __init__(self): + self.allowed = True + self.phase = None + self.fired = False + self.calls = [] + self.pending_reads = [] + self.searches = [] + self.resolutions = 0 + self.renders = 0 + self.runs = [] + self.deferred = [] + self.live = set() + self.entered = asyncio.Event() + self.cleanup_entered = asyncio.Event() + self.release_cleanup = asyncio.Event() + + async def resolve(self, input): + self.resolutions += 1 + return SearchRequest(input.model_copy(deep=True), (input.namespace,), ()) + + async def prepare(self, org, namespaces): + assert namespaces == ["ns"] + assert request_work.mark_mirrored() + return ReadPlan(org, marked=True) + + async def search(self, request, plan): + self.searches.append(request) + proof = _Proof(self) if self.allowed else None + values = [_passage("PRIVATE-CANARY")] if proof else [_passage("ordinary:document")] + return CheckedSearch( + KnowledgeSearchOutput(results=values, embedding_model="fake-embed"), + proof, + _Renderer(self), + [], + 0, + ) + + async def complete(self, system, user, **kwargs): + stage = str(current_stage() or "") + selector = "worth opening at full detail" in system + self.calls.append((stage, system, user)) + self.live.add(asyncio.current_task()) + cost_accumulator.report_llm(self.model, 101, 11, cache_read=17) + try: + self.entered.set() + if self.phase == "cancel": + try: + await asyncio.Event().wait() + finally: + self.cleanup_entered.set() + await self.release_cleanup.wait() + ordinary = not self.allowed + if ordinary and self.phase == "retry-error": + raise RuntimeError("ordinary retry refused") + synthesis_n = sum( + "worth opening at full detail" not in row[1] and row[0] != "ask_consistency" + for row in self.calls + ) + revoke = ( + (self.phase == "excerpt" and not selector) + or (self.phase == "selector" and selector) + or (self.phase == "deep" and not selector and synthesis_n == 2) + or (self.phase == "inline" and stage == "ask_consistency") + or (self.phase == "mid" and stage == "ask_synthesize_mid") + or ( + self.phase in {"cheap-escalation", "mid-verify"} + and stage == "ask_synthesize_strong" + ) + or (self.phase == "reread" and not selector and synthesis_n == 2) + or (self.phase == "retry-error" and not selector and not ordinary) + ) + if revoke and not self.fired: + self.allowed, self.fired = False, True + await asyncio.sleep(0) + if selector: + return SimpleNamespace(text=json.dumps({"picks": [0]}), model=self.model) + if stage == "ask_consistency": + return SimpleNamespace(text='{"entailment":1,"neutral":0,"contradiction":0}') + if "PRIVATE-CANARY" in user and ( + (self.phase in {"reread", "reread-io"} and synthesis_n == 1) + or (self.phase == "cheap-escalation" and stage == "ask_synthesize_cheap") + or (self.phase == "mid-verify" and stage != "ask_synthesize_strong") + ): + return SimpleNamespace(text="The memories do not record this.", model=self.model) + answer = "PRIVATE-CANARY" if "PRIVATE-CANARY" in user else "Ordinary answer" + return SimpleNamespace(text=answer + " [m1].", model=self.model) + finally: + self.live.discard(asyncio.current_task()) + + +@pytest.fixture +def world(monkeypatch): + env = make_env(monkeypatch) + state = _World() + env.llm = state + monkeypatch.setattr(env.settings, "memory_ask_knowledge_top_k", 2) + monkeypatch.setattr(env.settings, "memory_ask_premise_check", False) + token = request_work._current.set(None) + request_work.begin() + monkeypatch.setattr(knowledge_search, "resolve_search", state.resolve) + monkeypatch.setattr(source_access, "prepare", state.prepare) + monkeypatch.setattr(knowledge_search, "run_checked_search", state.search) + settle = pipeline._settle_window + audit = cascade._audit_answer + + async def settle_window(run, **kwargs): + result = await settle(run, **kwargs) + state.runs.append((run, _snapshot(run))) + return result + + async def audit_answer(*args, **kwargs): + result = await audit(*args, **kwargs) + state.deferred.append(result[3]) + if state.phase == "tail" and state.allowed: + state.allowed, state.fired = False, True + return result + + def forbidden(*args, **kwargs): + pytest.fail("marked generated work reached a deferred or precedent sink") + + async def dated_turns(**kwargs): + from server.memory.app.ask_when_evidence import DatedTurn + + if state.phase == "reread-io" and state.allowed: + state.allowed, state.fired = False, True + return [DatedTurn(day="2023-05-21", role="user", content="Ordinary dated fact")] + + async def pending_extraction(*args, **kwargs): + state.pending_reads.append(len(state.calls)) + return 0 + + monkeypatch.setattr(pipeline, "_settle_window", settle_window) + monkeypatch.setattr(pipeline, "_audit_answer", audit_answer) + monkeypatch.setattr("server.memory.app.ask_when_evidence.fetch_dated_turns", dated_turns) + monkeypatch.setattr( + "server.memory.app.pending_disclosure.pending_extraction", pending_extraction + ) + for name in ("_schedule_cited_used", "_record_contradiction", "_schedule_deferred_consistency"): + monkeypatch.setattr(handler, name, forbidden) + yield state, env.settings + request_work._current.reset(token) + + +@pytest.mark.parametrize( + "phase", + [ + "excerpt", + "selector", + "deep", + "inline", + "tail", + "reread", + "reread-io", + "mid", + "cheap-escalation", + "mid-verify", + ], +) +async def test_public_ask_rebuilds_the_whole_ordinary_answer_after_loss(world, phase, monkeypatch): + state, settings = world + state.phase = phase + deep = phase in {"selector", "deep", "mid-verify"} + monkeypatch.setattr(settings, "memory_ask_consistency_check", phase == "inline") + if phase in {"mid", "mid-verify", "cheap-escalation"}: + import server.memory.app.search as search + + retrieve = search.handle_memory_search + + async def routed_search(input): + output = await retrieve(input) + for index, row in enumerate(output.results): + row.similarity = ( + (0.9 if index == 0 else 0.5) + if phase == "cheap-escalation" + else (0.6 if index == 0 else 0.5) + ) + output.retrieval_confidence = 0.95 if phase == "cheap-escalation" else 0.7 + output.retrieval_risk = "low" if phase == "cheap-escalation" else "medium" + output.route_agreement = 0.95 + return output + + async def ratio(org: str, ns: str, *, user_id: str = ""): + return 0.0 + + monkeypatch.setattr(search, "handle_memory_search", routed_search) + monkeypatch.setattr("server.llm.client.get_llm_client_for_model", lambda _model: state) + monkeypatch.setattr("server.observability.budget.namespace_budget_ratio", ratio) + if phase == "cheap-escalation": + monkeypatch.setattr(settings, "memory_ask_synth_model_cheap", state.model) + else: + monkeypatch.setattr(settings, "memory_ask_mid_model", state.model) + monkeypatch.setattr(settings, "memory_ask_synth_mid_routes", "uncertain") + options = dict( + depth="raw" if deep else "excerpt", + consistency="inline", + knowledge=True, + deep_first=phase == "mid-verify", + ) + acc = cost_accumulator.begin_op() + late = await _ask(**options) + assert state.fired and not state.live + assert acc.by_model[state.model][0] == len(state.calls) + assert all(_snapshot(run) == frozen for run, frozen in state.runs) + assert state.resolutions == 1 and [r.input.top_k for r in state.searches] == [2, 8] + assert all(r.input.rerank == "none" and r.namespaces == ("ns",) for r in state.searches) + assert "PRIVATE-CANARY" not in late.model_dump_json() + assert late.synth_cost_usd == late.synth_input_tokens == 0 + assert late.synth_cached_input_tokens == late.synth_cache_write_tokens == 0 + charged = len(state.calls) + state.phase, state.calls = None, [] + initial = await _ask(**options) + assert late.model_dump() == initial.model_dump() + assert charged > len(state.calls) + assert not state.live and all(_snapshot(run) == frozen for run, frozen in state.runs) + assert state.pending_reads and all(count == 0 for count in state.pending_reads) + + +async def test_no_admitted_mirrors_uses_one_generation_without_a_retry(world): + state, _settings = world + state.allowed = False + output = await _ask(depth="excerpt", knowledge=True) + assert output.source == "synthesized" and output.knowledge_hits == 1 + assert len(state.calls) == 1 and not state.live and state.resolutions == 1 + + +async def test_marked_ask_bypasses_response_cache_precedents_and_deferred_judge(world, monkeypatch): + from server.llm.cache import CachedLLMClient + + state, settings = world + monkeypatch.setattr(settings, "memory_ask_consistency_check", True) + monkeypatch.setattr(settings, "memory_ask_precedents", True) + + def forbidden(*args, **kwargs): + pytest.fail("private work reached a cache or precedent") + + async def require_customer(): + return None + + monkeypatch.setattr("server.llm.customer.require", require_customer) + for name in ("_get", "_put"): + monkeypatch.setattr(CachedLLMClient, name, forbidden) + for name in ("fast_reuse", "reuse", "schedule_store"): + monkeypatch.setattr("server.memory.app.precedents." + name, forbidden) + output = await _ask( + depth="excerpt", knowledge=True, llm_cache=True, precedents=True, consistency="deferred" + ) + assert output.source == "synthesized" and output.llm_cache_hits == 0 + assert len(state.calls) == 1 and state.deferred == [None] + + +async def test_ordinary_retry_failure_never_returns_the_private_answer_or_retries_again(world): + state, _settings = world + state.phase = "retry-error" + with pytest.raises(RuntimeError, match="ordinary retry refused"): + await _ask(depth="excerpt", knowledge=True) + assert len(state.calls) == 2 and not state.live + assert state.resolutions == 1 and len(state.searches) == 2 + + +async def test_repeated_request_cancellation_joins_the_provider_cleanup(world): + state, _settings = world + state.phase = "cancel" + request = asyncio.create_task(_ask(depth="excerpt", knowledge=True)) + try: + await asyncio.wait_for(state.entered.wait(), 1) + request.cancel() + await asyncio.wait_for(state.cleanup_entered.wait(), 1) + request.cancel() + await asyncio.sleep(0) + assert not request.done() and state.live + state.release_cleanup.set() + with pytest.raises(asyncio.CancelledError): + await request + assert not state.live + finally: + state.release_cleanup.set() + owned = {request, *state.live} + for task in owned: + if not task.done(): + task.cancel() + await asyncio.gather(*owned, return_exceptions=True) diff --git a/tests/unit/test_source_ask_preparation.py b/tests/unit/test_source_ask_preparation.py new file mode 100644 index 0000000000..00c252fb4f --- /dev/null +++ b/tests/unit/test_source_ask_preparation.py @@ -0,0 +1,143 @@ +"""An ask prepares source scope before route, client and generation-prefix work.""" + +from __future__ import annotations + +from types import SimpleNamespace + +import pytest + +from server.core import request_work +from server.core.diagnostics import codes_only +from server.knowledge.app import knowledge_search, source_access +from server.memory.api.models_ask import MemoryAskInput, MemoryAskOutput +from server.memory.app import ask as ask_package +from server.memory.app.ask import handler +from server.memory.app.ask.result import MemoryAskResult +from server.settings import settings + + +@pytest.fixture +def world(monkeypatch): + token = request_work._current.set(None) + request_work.begin() + state = SimpleNamespace(marked=True, routed=False, cancel_prepare=False) + events = [] + + def event(name): + events.append((name, codes_only(), request_work.mirror_marked())) + + async def resolve(input): + return knowledge_search.SearchRequest(input.model_copy(deep=True), ("docs",), ()) + + async def prepare(org, namespaces): + import asyncio + + assert org == "acme" and namespaces == ["docs"] + events.append(("prepare", tuple(namespaces))) + if state.cancel_prepare: + raise asyncio.CancelledError() + if state.marked: + assert request_work.mark_mirrored() + return source_access.ReadPlan(org, marked=state.marked) + + async def route(input, *_prepared, **_kwargs): + event("route") + if state.routed: + return MemoryAskOutput( + answer="route answer", source="synthesized", route_reason="corpus" + ) + return None + + async def clients(*_args): + event("clients") + return None, None, None, None, False, 0.0 + + def precedent(*_args): + event("precedent") + return "", "" + + async def scratchpad(*_args): + event("scratchpad") + return "ordinary run notes" + + async def pipeline(*_args, **_kwargs): + event("pipeline") + return MemoryAskResult(source="retrieval_only") + + async def pending(*_args): + event("pending") + return 7 + + monkeypatch.setattr(settings, "memory_ask_knowledge_top_k", 2) + monkeypatch.setattr(knowledge_search, "resolve_search", resolve) + monkeypatch.setattr(source_access, "prepare", prepare) + monkeypatch.setattr(handler, "refuse_synthesis", lambda *_args: None) + monkeypatch.setattr(handler, "_maybe_route_to_synthesize", route) + monkeypatch.setattr(handler, "_ask_clients", clients) + monkeypatch.setattr(handler, "_ask_precedent", precedent) + monkeypatch.setattr("server.memory.app.working_memory.render_run_blocks", scratchpad) + monkeypatch.setattr(ask_package, "ask", pipeline) + monkeypatch.setattr(handler, "_pending_extraction", pending) + monkeypatch.setattr(handler, "_schedule_cited_used", lambda *_args: None) + monkeypatch.setattr(handler, "_record_contradiction", lambda *_args: None) + monkeypatch.setattr(handler, "_schedule_deferred_consistency", lambda *_args: None) + yield SimpleNamespace(state=state, events=events) + request_work._current.reset(token) + + +def request(**changes): + return MemoryAskInput( + org="acme", + namespace="docs", + agent="reader", + query="question", + run_id="run-one", + knowledge=True, + allow_synthesis=False, + ).model_copy(update=changes) + + +async def test_marked_ask_prepares_before_clients_prefix_and_all_pipeline_work(world): + output = await handler.handle_memory_ask(request()) + assert world.events[0] == ("prepare", ("docs",)) + names = [row[0] for row in world.events] + assert names.count("prepare") == 1 + for name in ("clients", "precedent", "scratchpad", "pipeline", "pending"): + assert (name, True, True) in world.events + assert names.index("pending") < names.index("pipeline") + assert output.source == "retrieval_only" and output.pending_extraction == 7 + + +async def test_corpus_route_is_prepared_even_when_normal_passages_are_disabled(world): + world.state.routed = True + output = await handler.handle_memory_ask( + request(allow_synthesis=True, knowledge=False, query="summarize all documents") + ) + assert world.events == [("prepare", ("docs",)), ("route", True, True)] + assert output.answer == "route answer" and output.route_reason == "corpus" + + +async def test_ordinary_plan_still_prepares_but_keeps_ordinary_tail_timing(world): + world.state.marked = False + output = await handler.handle_memory_ask(request()) + assert world.events[0] == ("prepare", ("docs",)) + names = [row[0] for row in world.events] + assert names.index("pending") > names.index("pipeline") + assert all(row[1:] == (False, False) for row in world.events if row[0] != "prepare") + assert not request_work.mirror_marked() and output.pending_extraction == 7 + + +async def test_no_possible_document_read_does_not_discover_or_mark(world): + output = await handler.handle_memory_ask(request(knowledge=False)) + assert all(row[0] != "prepare" for row in world.events) + assert all(row[1:] == (False, False) for row in world.events) + assert output.source == "retrieval_only" and not request_work.mirror_marked() + + +async def test_source_preparation_cancellation_starts_no_other_work(world): + import asyncio + + world.state.cancel_prepare = True + with pytest.raises(asyncio.CancelledError): + await handler.handle_memory_ask(request()) + assert world.events == [("prepare", ("docs",))] diff --git a/tests/unit/test_source_candidate_stream.py b/tests/unit/test_source_candidate_stream.py new file mode 100644 index 0000000000..aa6944b426 --- /dev/null +++ b/tests/unit/test_source_candidate_stream.py @@ -0,0 +1,91 @@ +"""Ranked discovery streams carry metadata and close before text hydration.""" + +from __future__ import annotations + +import json +from contextlib import asynccontextmanager + +import pytest + +from server.knowledge.store import source_candidates as store + + +@pytest.mark.parametrize("leg", ["semantic", "lexical", "keys"]) +@pytest.mark.parametrize("authority", ["clickhouse", "postgres"]) +def test_metadata_stream_has_no_page_cap_or_hidden_corpus_statistics(leg, authority): + sql, params = store.statement( + ["org = {org:String}", "namespace IN {nss:Array(String)}"], + { + "org": "acme", + "nss": ["acl-" + "1" * 24], + "q": [1.0], + "toks": ["token"], + "keys": ["object"], + "idfs": [1000.0], + "avgdl": 100000.0, + }, + leg=leg, + access_keys=["anyone"] if authority == "clickhouse" else None, + ) + select = sql.split("SELECT", 1)[1].split("FROM loom.chunks", 1)[0] + assert "source_uri" in select and "AS revision" in select + assert "content," not in select and "context," not in select and "tags," not in select + assert "LIMIT" not in sql and "OFFSET" not in sql + assert "vector_search" not in sql and "chunk_term_freq" not in sql + assert ("hasAny(access_keys" in sql) == (authority == "clickhouse") + assert "FORMAT JSONEachRow" in sql + if leg == "lexical": + assert params["idfs"] == [1.0] and params["avgdl"] == 256.0 + assert "query_plan_direct_read_from_text_index = 0" in sql + elif leg == "keys": + assert "hasAny(keys" in sql and "arrayIntersect(keys" in sql + + +async def test_stream_decodes_split_unicode_and_closes_on_early_stop(): + class Client: + closed = False + + @asynccontextmanager + async def raw_stream(self, sql, params): + assert "FORMAT JSONEachRow" in sql and params["org"] == "acme" + + async def body(): + raw = json.dumps({"source_uri": "drive:K"}, ensure_ascii=False).encode() + b"\n" + for byte in raw: + yield bytes([byte]) + yield b'{"source_uri":"unused"}\n' + + try: + yield body() + finally: + self.closed = True + + client = Client() + async with store.candidates("SELECT 1 FORMAT JSONEachRow", {"org": "acme"}, ch=client) as rows: + async for row in rows: + assert row == {"source_uri": "drive:K"} + break + assert not client.closed + assert client.closed + + +@pytest.mark.parametrize("raw", [b'{"x":1}\n{bad}\n', b"[]\n", b'{"x":1}\n{bad}']) +async def test_malformed_stream_never_becomes_a_partial_success(raw): + class Client: + closed = False + + @asynccontextmanager + async def raw_stream(self, *_args): + async def body(): + yield raw + + try: + yield body() + finally: + self.closed = True + + client = Client() + with pytest.raises(ValueError): + async with store.candidates("SELECT 1", {}, ch=client) as rows: + _ = [row async for row in rows] + assert client.closed diff --git a/tests/unit/test_source_checked_pack.py b/tests/unit/test_source_checked_pack.py new file mode 100644 index 0000000000..5b11af35da --- /dev/null +++ b/tests/unit/test_source_checked_pack.py @@ -0,0 +1,335 @@ +"""A composed pack renews both document pools and rebuilds its entire ordinary wire.""" + +from __future__ import annotations + +from dataclasses import replace +from datetime import UTC, datetime, timedelta +from types import SimpleNamespace + +import pytest + +from server.auth.reader_identity import ReaderIdentity +from server.core import request_tail +from server.knowledge.api.models_knowledge import KnowledgeSearchOutput, _SearchHit +from server.knowledge.app import source_access, source_publication +from server.knowledge.app.knowledge_search import CheckedSearch +from server.knowledge.app.search import ChunkHit +from server.knowledge.app.source_passages import CheckedPassages +from server.knowledge.app.source_search_proofs import SearchProofs +from server.knowledge.domain.access_list import AccessList +from server.knowledge.store import source_candidates +from server.memory.api.models_context import ContextPackInput +from server.memory.api.models_lifecycle import _StackEntry +from server.memory.app import context_pack, stack, stack_knowledge +from server.memory.domain.context_layout import _DEFAULT_SECTION_TOKENS +from server.settings import settings + + +@pytest.fixture +def world(monkeypatch): + clock = SimpleNamespace(at=datetime(2025, 1, 1, tzinfo=UTC)) + monkeypatch.setattr(source_access, "now", lambda: clock.at) + monkeypatch.setattr(settings, "knowledge_source_acl_stale_seconds", 5) + state = SimpleNamespace(revoked=set(), renders=[], checks=[], expire_on_stack=False) + items = {} + for index, name in enumerate(("direct", "stack"), 1): + ns = "acl-" + str(index) * 24 + sid = ( + str(index) * 8 + + "-" + + str(index) * 4 + + "-" + + str(index) * 4 + + "-" + + str(index) * 4 + + "-" + + str(index) * 12 + ) + uri = "gdrive:file#" + sid + items[name] = source_access.Admitted( + "docs", + {"namespace": ns, "source_uri": uri, "chunk_idx": 0, "doc_version": 10, "revision": 0}, + { + "namespace": ns, + "source_uri": uri, + "version": 10, + "revision": 0, + "ingested_at": clock.at, + "tags": ["source-id:" + sid], + }, + AccessList(emails=("lee@example.com",)), + reader_emails=frozenset({"lee@example.com"}), + ) + plan = source_access.ReadPlan( + "acme", + sources={ + ( + item.candidate["namespace"], + item.document["tags"][0].removeprefix("source-id:"), + ): "docs" + for item in items.values() + }, + reader=ReaderIdentity("lee", frozenset({"lee@example.com"}), frozenset()), + marked=True, + ) + plan.listing_starts = {key: clock.at for key in plan.sources} + + async def check(candidates, **_kwargs): + found = [] + for candidate in candidates: + name = next( + name + for name, item in items.items() + if item.candidate["source_uri"] == candidate["source_uri"] + ) + state.checks.append(name) + if name == "stack" and state.expire_on_stack: + clock.at += timedelta(seconds=6) + stack_item = items["stack"] + stack_key = ( + stack_item.candidate["namespace"], + stack_item.document["tags"][0].removeprefix("source-id:"), + ) + plan.listing_starts[stack_key] = clock.at + state.expire_on_stack = False + if name not in state.revoked: + found.append(items[name]) + return found + + async def keys(org, model, wanted, *, embedded_only=True): + assert org == "acme" and model == "fake" + return wanted + + monkeypatch.setattr(plan, "check", check) + monkeypatch.setattr(source_candidates, "chunk_keys", keys) + + def passage(name): + return _SearchHit( + namespace="docs", + source_uri=name, + chunk_idx=0, + content=name, + tags=[], + distance=0.1, + similarity=0.9, + ) + + class Renderer: + def __init__(self, marked): + self.marked = marked + + async def render(self, rows, dropped): + state.renders.append("ordinary-direct") + return KnowledgeSearchOutput( + results=[passage("ordinary-direct")], embedding_model="fake" + ) + + def build(*, private=True, large=False): + input = ContextPackInput( + org="acme", + namespace="docs", + agent="reader", + query="question", + include_knowledge=True, + section_token_budgets={"memory_stack": 80}, + token_budget=2000, + only_sections=["profile", "knowledge", "memory_stack"], + ) + prefix = context_pack._PackState(input, dict(_DEFAULT_SECTION_TOKENS[input.mode])) + prefix.put( + "profile", + "ordinary profile", + citations=["profile:one"], + source_count=1, + extra_meta={"nested": {"rows": ["stable"]}}, + ) + direct_hit = passage("private-direct" if private else "ordinary-direct") + if large and private: + direct_hit.content = "private-direct" * 20 + first = CheckedSearch( + KnowledgeSearchOutput(results=[direct_hit], embedding_model="fake"), + SearchProofs(plan, "fake", (items["direct"],)) if private else None, + Renderer(private), + [], + 0, + ) + direct = CheckedPassages(first, None, "reader", 2, None, [direct_hit]) + fill = stack._StackFill(budget=200) + fill.add( + _StackEntry( + section="pinned", + memory_key="kept-row", + memory_type="fact", + value="ordinary pinned", + tokens=4, + namespace="docs", + ) + ) + mixed = ChunkHit( + "docs", + "private-stack" if private else "ordinary-stack", + 0, + "private-stack" * (50 if large and private else 1) if private else "ordinary-stack", + [], + 0.1, + ) + ordinary = ChunkHit("docs", "ordinary-stack", 0, "ordinary-stack", [], 0.2) + knowledge = stack_knowledge.StackKnowledge( + [mixed], [ordinary], SearchProofs(plan, "fake", (items["stack"],)) if private else None + ) + checked_stack = stack.CheckedStack(fill, knowledge, private) + return context_pack.CheckedPack(prefix, checked_stack, direct, private) + + return SimpleNamespace(state=state, clock=clock, plan=plan, build=build) + + +@pytest.mark.parametrize("pool", ["direct", "stack"]) +async def test_loss_of_either_pool_rebuilds_the_entire_ordinary_pack(world, pool): + checked = world.build() + mixed = await checked.current() + assert "private-direct" in mixed.rendered and "private-stack" in mixed.rendered + world.state.revoked.add(pool) + actual = await checked.current() + expected = await world.build(private=False).current() + assert actual.model_dump() == expected.model_dump() + assert actual._served_rows == expected._served_rows + assert checked.lost and checked.fresh() + assert world.state.renders == ["ordinary-direct"] + assert (await checked.current()).model_dump() == expected.model_dump() + assert (await checked.ordinary())._served_rows == expected._served_rows + assert world.state.renders == ["ordinary-direct"] + + +async def test_private_truncation_and_counts_do_not_survive_ordinary_rebuild(world): + checked = world.build(large=True) + mixed = await checked.current() + assert mixed.truncated + world.state.revoked.add("direct") + actual = await checked.current() + expected = await world.build(private=False).current() + assert not actual.truncated + assert actual.model_dump() == expected.model_dump() + assert actual._served_rows == expected._served_rows + assert actual.section_meta["memory_stack"]["source_count"] == 2 + + +async def test_last_child_wait_cannot_leave_an_earlier_pool_expired(world): + checked = world.build() + world.state.expire_on_stack = True + actual = await checked.current() + expected = await world.build(private=False).current() + assert "direct" in world.state.checks and "stack" in world.state.checks + assert actual.model_dump() == expected.model_dump() + assert actual._served_rows == expected._served_rows and checked.lost + + +async def test_cpu_render_deadline_crossing_discards_the_whole_mixed_pack(world, monkeypatch): + render = context_pack._render_checked_pack + calls = [] + + def expire(prefix, stack_output, hits, **kwargs): + output = render(prefix, stack_output, hits, **kwargs) + calls.append(output.rendered) + if len(calls) == 1: + world.clock.at += timedelta(seconds=6) + return output + + monkeypatch.setattr(context_pack, "_render_checked_pack", expire) + actual = await world.build().current() + expected = await world.build(private=False).current() + assert len(calls) == 3 and "private-direct" in calls[0] + assert actual.model_dump() == expected.model_dump() + assert actual._served_rows == expected._served_rows + + +async def test_repeated_outputs_and_nested_metadata_never_mutate_the_prefix(world): + checked = world.build() + first = await checked.current() + first.section_meta["profile"]["nested"]["rows"].append("caller mutation") + first.section_meta["profile"]["citations"].append("caller mutation") + first.sections["profile"] = "caller mutation" + second = await checked.current() + assert second.section_meta["profile"]["nested"]["rows"] == ["stable"] + assert second.section_meta["profile"]["citations"] == ["profile:one"] + assert "caller mutation" not in second.rendered + ordinary = await checked.ordinary() + ordinary.section_meta["profile"]["nested"]["rows"].append("other mutation") + assert (await checked.current()).section_meta["profile"]["nested"]["rows"] == ["stable"] + + +@pytest.mark.parametrize("section", ["memory_stack", "knowledge"]) +async def test_optional_renderer_failure_discards_its_partial_mutation(world, monkeypatch, section): + def broken(st, output): + st.put(section, "partial private section", source_count=77) + raise ValueError("render failed") + + monkeypatch.setattr(context_pack, "_put_" + section, broken) + checked = world.build() + actual = await checked.current() + assert section not in actual.sections and "partial private section" not in actual.rendered + assert actual.sections["profile"] == "ordinary profile" + assert actual.section_meta["profile"]["source_count"] == 1 + assert actual.section_count == 2 + + async def app(scope, receive, send): + for proof in checked.publication_proofs(): + source_publication.retain(proof) + world.state.revoked.add("stack" if section == "memory_stack" else "direct") + await send({"type": "http.response.start", "status": 200, "headers": []}) + await send({"type": "http.response.body", "body": actual.model_dump_json().encode()}) + + sent = [] + + async def send(message): + sent.append(message) + + await request_tail.RequestTailMiddleware(app)({"type": "http"}, None, send) + assert "partial private section" not in sent[-1]["body"].decode() + + +@pytest.mark.parametrize("pool", ["direct", "stack"]) +@pytest.mark.parametrize("change", ["access", "version", "chunk"]) +async def test_accounting_wait_cannot_publish_a_mixed_pack_after_either_pool_changes( + world, monkeypatch, pool, change +): + sent = [] + namespace = "acl-" + ("1" if pool == "direct" else "2") * 24 + + async def revoke(): + if change == "access": + world.state.revoked.add(pool) + elif change == "version": + original = world.plan.check + + async def updated(candidates, **kwargs): + return [ + replace(item, document={**item.document, "version": 11}) + if item.candidate["namespace"] == namespace + else item + for item in await original(candidates, **kwargs) + ] + + monkeypatch.setattr(world.plan, "check", updated) + else: + + async def gone(org, model, wanted, *, embedded_only=True): + return [key for key in wanted if key[0] != namespace] + + monkeypatch.setattr(source_candidates, "chunk_keys", gone) + + async def app(scope, receive, send): + checked = world.build() + output = await checked.current() + assert "private-direct" in output.rendered and "private-stack" in output.rendered + for proof in checked.publication_proofs(): + source_publication.retain(proof) + assert request_tail.defer_required(revoke) + await send({"type": "http.response.start", "status": 200, "headers": []}) + await send({"type": "http.response.body", "body": output.model_dump_json().encode()}) + + async def send(message): + sent.append(message) + + with pytest.raises(request_tail.RequiredTailError): + await request_tail.RequestTailMiddleware(app)({"type": "http"}, None, send) + assert sent == [] and world.state.renders == [] diff --git a/tests/unit/test_source_checked_stack.py b/tests/unit/test_source_checked_stack.py new file mode 100644 index 0000000000..830364956a --- /dev/null +++ b/tests/unit/test_source_checked_stack.py @@ -0,0 +1,312 @@ +"""Checked stack fallback rebuilds every knowledge-derived field from ordinary rows.""" + +from __future__ import annotations + +import asyncio +from dataclasses import replace +from datetime import UTC, datetime, timedelta +from types import SimpleNamespace +from unittest.mock import AsyncMock + +import pytest + +from server.auth.reader_identity import ReaderIdentity +from server.core import pg, request_work +from server.knowledge.app import pg_serving, search, source_access, source_search_passes +from server.knowledge.app.search import ChunkHit +from server.knowledge.app.source_search import Hydrated +from server.knowledge.domain.access_list import AccessList +from server.knowledge.store import source_candidates +from server.memory.api.models_lifecycle import MemoryStackInput, _StackEntry +from server.memory.app import stack +from server.settings import settings + +NS = "acl-" + "1" * 24 +SID = "11111111-1111-4111-8111-111111111111" +URI = "gdrive:file#" + SID + + +def hit(name, *, tags=(), content=None, distance=0.5): + return ChunkHit("docs", name, 0, content or name, list(tags), distance, score=1 - distance) + + +@pytest.fixture +def world(monkeypatch): + token = request_work._current.set(None) + request_work.begin() + assert request_work.mark_mirrored() + clock = SimpleNamespace(at=datetime(2025, 1, 1, tzinfo=UTC)) + monkeypatch.setattr(source_access, "now", lambda: clock.at) + monkeypatch.setattr(settings, "knowledge_source_acl_stale_seconds", 5) + reader = ReaderIdentity("lee", frozenset({"lee@example.com"}), frozenset()) + plan = source_access.ReadPlan( + "acme", + sources={(NS, SID): "docs"}, + listing_starts={(NS, SID): clock.at}, + reader=reader, + marked=True, + _bindings=((NS, SID, "docs"),), + ) + item = source_access.Admitted( + "docs", + { + "namespace": NS, + "source_uri": URI, + "chunk_idx": 0, + "doc_version": 10, + "revision": 0, + "distance": 0.05, + "lexical": 0.0, + "matched": [], + }, + { + "namespace": NS, + "source_uri": URI, + "version": 10, + "revision": 0, + "ingested_at": clock.at, + "tags": ["source-id:" + SID], + }, + AccessList(emails=("lee@example.com",)), + reader_emails=reader.emails, + ) + state = SimpleNamespace( + admit=True, + revoked=False, + chunk_gone=False, + first=[hit("first-a"), hit("first-b")], + wide=[hit("wide-a"), hit("wide-b")], + queries=[], + embeddings=[], + prefix_calls=0, + first_error=None, + wide_error=None, + content="private", + ) + + async def check(candidates, **_kwargs): + return [item] if candidates and state.admit and not state.revoked else [] + + async def prepare(org, namespaces): + assert org == "acme" and namespaces == ["docs"] + assert request_work.mark_mirrored() + return plan + + async def discover(_plan, query, **_kwargs): + assert _plan is plan and query.namespaces == ("docs",) + return {"semantic": [item]} if state.admit and not state.revoked else {} + + async def hydrate(_plan, pools, **_kwargs): + return { + leg: [Hydrated(entry, {"content": state.content}) for entry in entries] + for leg, entries in pools.items() + } + + async def keys(org, model, keys, *, embedded_only=True): + assert org == "acme" and model == "fake" + return [] if state.chunk_gone else keys + + async def profile(_input, fill): + state.prefix_calls += 1 + fill.add( + _StackEntry( + section="profile", + memory_key="profile.render", + memory_type="profile", + value="prefix", + tokens=1, + ) + ) + + class Embedder: + model_name = "fake" + + async def embed(self, text): + state.embeddings.append(text) + return [1.0] + + async def ranked(query): + assert query.keys == query.tokens == [] + assert query.namespaces == ("docs",) + state.queries.append(query.top_k) + error = state.first_error if query.top_k == 2 else state.wide_error + if error is not None: + raise error + return state.first if query.top_k == 2 else state.wide + + monkeypatch.setattr(plan, "check", check) + monkeypatch.setattr(source_access, "prepare", prepare) + monkeypatch.setattr(source_search_passes, "discover", discover) + monkeypatch.setattr(source_search_passes, "hydrate", hydrate) + monkeypatch.setattr(source_candidates, "chunk_keys", keys) + monkeypatch.setattr(stack, "get_client", lambda: SimpleNamespace()) + monkeypatch.setattr(stack, "_stack_profile", profile) + monkeypatch.setattr(stack, "_stack_pinned", AsyncMock()) + monkeypatch.setattr(stack, "_stack_recent", AsyncMock(return_value="")) + monkeypatch.setattr("server.embedding.get_embedder", Embedder) + monkeypatch.setattr(search, "hybrid_search", ranked) + monkeypatch.setattr(pg, "enabled", lambda: False) + yield SimpleNamespace(state=state, plan=plan, clock=clock) + request_work._current.reset(token) + + +def request(**changes): + return MemoryStackInput( + org="acme", + namespace="docs", + agent="reader", + seed_query="question", + procedure_limit=0, + include_knowledge=True, + knowledge_top_k=2, + **changes, + ) + + +@pytest.mark.parametrize("admit", [False, True]) +async def test_marked_stack_uses_exact_separate_widths_and_one_seed_embedding(world, admit): + world.state.admit = admit + output = await stack.handle_memory_stack(request()) + assert world.state.queries == [2, 8] and world.state.embeddings == ["question"] + values = [entry.value for entry in output.entries if entry.section == "knowledge"] + assert values == (["private", "first-a"] if admit else ["first-a", "first-b"]) + assert world.state.prefix_calls == 1 + + +@pytest.mark.parametrize("loss", ["revoked", "chunk_gone", "failed", "unread"]) +async def test_later_loss_rebuilds_the_whole_stack_without_retrieval_or_prefix_replay(world, loss): + checked = await stack.run_checked_stack(request(), world.plan) + assert checked.output.entries[-2].value == "private" + if loss in {"failed", "unread"}: + setattr(world.plan, loss, True) + else: + setattr(world.state, loss, True) + actual = await checked.current() + assert [entry.value for entry in actual.entries] == ["prefix", "first-a", "first-b"] + assert checked.lost and checked.fresh() + assert await checked.current() == actual and await checked.ordinary() == actual + assert world.state.queries == [2, 8] and world.state.prefix_calls == 1 + assert world.state.embeddings == ["question"] + + +async def test_private_token_overflow_cannot_leave_the_ordinary_stack_truncated(world): + world.state.content = "private" * 200 + checked = await stack.run_checked_stack(request(token_budget=200), world.plan) + assert checked.output.truncated and len(checked.output.entries) == 1 + world.state.revoked = True + actual = await checked.current() + assert not actual.truncated and actual.section_counts["knowledge"] == 2 + world.state.admit = False + baseline = await stack.run_checked_stack(request(token_budget=200), world.plan) + assert actual.model_dump() == (await baseline.current()).model_dump() + + +async def test_suppressed_mixed_widening_uses_saved_complete_ordinary_wider_pass(world): + world.state.first = [ + hit("rule", tags=("source-kind:assistant_turn", "agent:other")), + hit("first-b"), + ] + checked = await stack.run_checked_stack(request(), world.plan) + assert [entry.value for entry in checked.output.entries] == ["prefix", "private", "first-b"] + world.state.revoked = True + output = await checked.current() + assert [entry.value for entry in output.entries] == ["prefix", "wide-a", "wide-b"] + assert world.state.queries == [2, 8] + + +async def test_optional_wider_failure_keeps_the_first_ordinary_pass_without_retry(world, caplog): + world.state.first = [ + hit("rule", tags=("source-kind:assistant_turn", "agent:other")), + hit("first-b"), + ] + world.state.wide_error = RuntimeError("private backend marker") + checked = await stack.run_checked_stack(request(), world.plan) + world.state.revoked = True + output = await checked.current() + assert [entry.value for entry in output.entries] == ["prefix", "first-b"] + assert world.state.queries == [2, 8] + assert "private backend marker" not in caplog.text + + +async def test_first_failure_is_not_rescued_by_wide_success(world): + world.state.first_error = RuntimeError("private first failure") + output = await stack.handle_memory_stack(request()) + assert [entry.value for entry in output.entries] == ["prefix"] + assert world.state.queries == [2] + + +async def test_pure_outer_freshness_detects_expiry_after_another_pool_waits(world): + checked = await stack.run_checked_stack(request(), world.plan) + assert checked.fresh() + world.clock.at += timedelta(seconds=6) + assert not checked.fresh() + output = await checked.current() + assert [entry.value for entry in output.entries] == ["prefix", "first-a", "first-b"] + + +async def test_wider_cancellation_propagates(world): + world.state.wide_error = asyncio.CancelledError() + with pytest.raises(asyncio.CancelledError): + await stack.handle_memory_stack(request()) + + +async def test_wrong_org_plan_refuses_before_the_first_provider(world): + with pytest.raises(ValueError, match="document read scope changed"): + await stack.run_checked_stack(request(), replace(world.plan, org="other")) + assert world.state.prefix_calls == 0 and not world.state.queries and not world.state.embeddings + + +async def test_retired_ordinary_fallback_and_shadow_disappear_from_the_same_snapshot( + world, monkeypatch +): + world.state.first = [hit("gdrive:file")] + calls = 0 + + async def keep(_org, hits): + nonlocal calls + calls += 1 + kept = hits if calls == 1 else [h for h in hits if h.source_uri != "gdrive:file"] + return kept, len(hits) - len(kept) + + monkeypatch.setattr(pg, "enabled", lambda: True) + monkeypatch.setattr(pg_serving, "keep_served", keep) + checked = await stack.run_checked_stack(request(), world.plan) + assert [entry.value for entry in checked.output.entries] == ["prefix", "private"] + world.state.revoked = True + assert [entry.value for entry in (await checked.current()).entries] == ["prefix"] + assert world.state.queries == [2, 8] + + +async def test_fresh_serving_uses_physical_rows_and_the_actual_refill_query(world, monkeypatch): + old = replace(hit("gdrive:file", content="old"), doc_version=10, revision=0) + new = replace(old, content="current", doc_version=11, revision=1) + queries, candidates = [], [] + calls = 0 + + async def ranked(query): + queries.append(query.top_k) + return [old, new] + + async def keep(_org, hits): + nonlocal calls + calls += 1 + # A headless first read admits both versions; publication races its refill. + kept = hits if calls <= 2 else [h for h in hits if h.doc_version == 11] + return kept, len(hits) - len(kept) + + original = source_search_passes.discover + + async def discover(plan, query, **kwargs): + candidates.append(query.top_k) + return await original(plan, query, **kwargs) + + monkeypatch.setattr(search, "hybrid_search", ranked) + monkeypatch.setattr(pg, "enabled", lambda: True) + monkeypatch.setattr(pg_serving, "keep_served", keep) + monkeypatch.setattr(source_search_passes, "discover", discover) + checked = await stack.run_checked_stack(request(), world.plan) + assert queries == [2, 4, 8] + assert candidates == [4, 8] + # The live new raw row still shadows the source family, while the old physical + # fallback is gone. Logical-key membership must not retain the old object. + assert [entry.value for entry in checked.output.entries] == ["prefix"] diff --git a/tests/unit/test_source_corpus_loader.py b/tests/unit/test_source_corpus_loader.py new file mode 100644 index 0000000000..b226673e8f --- /dev/null +++ b/tests/unit/test_source_corpus_loader.py @@ -0,0 +1,205 @@ +"""Synthesis alone assembles checked chunks; ordinary and mining helpers stay scoped.""" + +from __future__ import annotations + +from datetime import UTC, datetime +from types import SimpleNamespace +from unittest.mock import AsyncMock + +import pytest + +from server.knowledge.app import source_corpus as app +from server.knowledge.app import source_documents +from server.knowledge.app.source_access import Admitted +from server.knowledge.app.source_search import Hydrated +from server.knowledge.domain.serving import Serving +from server.knowledge.store import documents +from server.memory.domain.corpus_synthesis import CorpusChunk + +NS = "acl-" + "1" * 24 +URI = "gdrive:file#native" + + +@pytest.fixture +def world(monkeypatch): + metadata = { + "tags": [], + "version": 11, + "revision": 0, + "ingested_at": datetime(2025, 1, 1, tzinfo=UTC), + } + candidate = {"namespace": NS, "source_uri": URI + "#source"} + admitted = Admitted( + "team", candidate, {**candidate, **metadata}, serving=Serving(False, 0, 0, 10) + ) + checked = source_documents.CheckedDocument( + admitted, + SimpleNamespace( + org="acme", + **candidate, + **metadata, + content="Full body not retained as proof", + ), + ) + hydrated = Hydrated( + admitted, + { + **candidate, + "chunk_idx": 3, + "content": "Checked chunk", + "doc_version": 10, + "chunk_metadata": '{"revision":0,"section_path":["Notes"],"locator":{"page":2}}', + }, + ) + plan = SimpleNamespace( + org="acme", + failed=False, + unread=False, + current=lambda _item: True, + check=AsyncMock(return_value=[admitted]), + ) + ordinary = AsyncMock(return_value=[]) + monkeypatch.setattr(documents, "get_one", AsyncMock(return_value=None)) + monkeypatch.setattr(source_documents, "get", AsyncMock(return_value=checked)) + monkeypatch.setattr(source_documents, "chunks", AsyncMock(return_value=[hydrated])) + return plan, ordinary, checked, hydrated + + +async def load(world, uris=None): + plan, ordinary, _checked, _hydrated = world + return await app.load(plan, "team", uris or [URI], ordinary_chunks=ordinary, model="fixture") + + +async def test_admitted_chunks_keep_public_uri_structure_and_recorded_serving_pair(world): + result = await load(world) + assert result.documents == 1 and result.proofs.mirrored + assert result.chunks == [CorpusChunk(URI, 3, "Checked chunk", ("Notes",), 0, {"page": 2})] + source_documents.chunks.assert_awaited_once_with(world[0], world[2], model="fixture") + + +async def test_existing_ordinary_chunks_win_even_without_document_head(world): + _plan, ordinary, _checked, _hydrated = world + ordinary.return_value = [CorpusChunk(URI, 1, "Ordinary legacy chunk")] + result = await load(world) + assert result.chunks == ordinary.return_value and result.documents == 1 + assert not result.proofs.mirrored + documents.get_one.assert_not_awaited() + source_documents.get.assert_not_awaited() + + +async def test_live_ordinary_document_with_zero_usable_chunks_still_shadows_mirror(world): + documents.get_one.return_value = object() + result = await load(world) + assert result.chunks == [] and result.documents == 0 and not result.proofs.mirrored + source_documents.get.assert_not_awaited() + + +async def test_ordinary_presence_failure_is_not_mirror_fallback(world): + documents.get_one.side_effect = RuntimeError("ordinary authority unavailable") + with pytest.raises(RuntimeError, match="ordinary authority"): + await load(world) + source_documents.get.assert_not_awaited() + + +async def test_denied_copy_contributes_no_chunks_document_or_proof(world): + source_documents.get.return_value = None + result = await load(world) + assert result.chunks == [] and result.documents == 0 and not result.proofs.mirrored + source_documents.chunks.assert_not_awaited() + + +@pytest.mark.parametrize("chunks", [None, []]) +async def test_empty_or_failed_checked_chunk_read_contributes_nothing(world, chunks): + source_documents.chunks.return_value = chunks + result = await load(world) + assert result.chunks == [] and result.documents == 0 and not result.proofs.mirrored + + +async def test_later_mirror_failure_discards_every_mirror_but_preserves_ordinary_corpus(world): + plan, ordinary, _checked, _hydrated = world + ordinary.side_effect = [[], [], [CorpusChunk("ordinary", 0, "Ordinary")]] + + async def get(_plan, _namespace, uri): + if uri != URI: + plan.failed = True + return None + return world[2] + + source_documents.get.side_effect = get + result = await load(world, [URI, "other", "ordinary"]) + assert result.chunks == [CorpusChunk("ordinary", 0, "Ordinary")] + assert result.documents == 1 and not result.proofs.mirrored and not plan.unread + assert source_documents.get.await_count == 2 + + +async def test_final_permission_loss_discards_mirror_corpus_before_any_model_use(world): + plan, _ordinary, _checked, _hydrated = world + plan.check.return_value = [] + result = await load(world) + assert result.chunks == [] and result.documents == 0 and not result.proofs.mirrored + assert not plan.unread + + +@pytest.mark.parametrize("later_chunks", [None, []]) +async def test_later_chunk_failure_discards_earlier_mirrors_but_empty_copy_does_not( + world, later_chunks +): + source_documents.chunks.side_effect = [[world[3]], later_chunks] + result = await load(world, [URI, "other"]) + assert result.documents == (0 if later_chunks is None else 1) + assert result.proofs.mirrored == (later_chunks is not None) + assert world[0].failed == (later_chunks is None) + + +async def test_cancellation_propagates_without_returning_a_partial_corpus(world): + import asyncio + + source_documents.chunks.side_effect = asyncio.CancelledError + with pytest.raises(asyncio.CancelledError): + await load(world) + assert not world[0].failed + + +async def test_repeated_public_uri_reuses_one_whole_copy_if_another_source_changes(world): + from dataclasses import replace + + plan, _ordinary, checked, hydrated = world + newer = replace( + checked.admitted, + candidate={**checked.admitted.candidate, "source_uri": "another-copy"}, + ) + other = source_documents.CheckedDocument( + newer, SimpleNamespace(**{**vars(checked.row), "source_uri": "another-copy"}) + ) + source_documents.get.side_effect = [checked, other] + source_documents.chunks.side_effect = [ + [hydrated], + [replace(hydrated, admitted=newer, row={**hydrated.row, "content": "Another copy"})], + ] + by_uri = {item.candidate["source_uri"]: item for item in (checked.admitted, newer)} + + async def current(candidates): + return [by_uri[row["source_uri"]] for row in candidates] + + plan.check.side_effect = current + result = await load(world, [URI, URI]) + assert [chunk.text for chunk in result.chunks] == ["Checked chunk", "Checked chunk"] + assert result.documents == 2 + source_documents.get.assert_awaited_once() + + +@pytest.mark.parametrize("field", ["namespace", "source_uri", "version", "revision", "serving"]) +async def test_chunks_must_belong_to_the_same_complete_admitted_copy(world, field): + from dataclasses import replace + + _plan, _ordinary, _checked, hydrated = world + item = hydrated.admitted + if field in {"namespace", "source_uri"}: + item = replace(item, candidate={**item.candidate, field: "other"}) + elif field == "serving": + item = replace(item, serving=Serving(False, 0, 0, 9)) + else: + item = replace(item, document={**item.document, field: item.document[field] + 1}) + source_documents.chunks.return_value = [replace(hydrated, admitted=item)] + result = await load(world) + assert result.chunks == [] and result.documents == 0 and not result.proofs.mirrored diff --git a/tests/unit/test_source_corpus_proofs.py b/tests/unit/test_source_corpus_proofs.py new file mode 100644 index 0000000000..e4f0448449 --- /dev/null +++ b/tests/unit/test_source_corpus_proofs.py @@ -0,0 +1,190 @@ +"""Synthesis retains immutable copy identities and a monotonic invalidation latch.""" + +from __future__ import annotations + +import asyncio +from dataclasses import replace +from datetime import UTC, datetime +from types import SimpleNamespace +from unittest.mock import AsyncMock + +import pytest + +from server.knowledge.app.source_access import Admitted +from server.knowledge.domain.serving import Serving + + +@pytest.fixture +def world(): + item = Admitted( + "team", + {"namespace": "acl-" + "1" * 24, "source_uri": "gdrive:file#source"}, + { + "namespace": "acl-" + "1" * 24, + "source_uri": "gdrive:file#source", + "tags": [], + "version": 10, + "revision": 0, + "ingested_at": datetime(2025, 1, 1, tzinfo=UTC), + }, + serving=Serving(False, 0, 0, 9), + ) + fresh = replace(item, candidate=dict(item.candidate), document=dict(item.document)) + plan = SimpleNamespace( + failed=False, + unread=False, + current=lambda _item: True, + check=AsyncMock(return_value=[fresh]), + ) + return plan, item, fresh + + +def bundle(world, items=None): + from server.knowledge.app import source_corpus + + plan, item, _fresh = world + return source_corpus.Proofs(plan, tuple(items if items is not None else [item])) + + +async def test_current_copy_and_recorded_serving_pair_validate_without_text(world): + plan, item, _fresh = world + proof = bundle(world) + await proof.check() + assert not proof.invalid + plan.check.assert_awaited_once_with([item.candidate]) + + +@pytest.mark.parametrize( + "change", + [ + "namespace", + "source_uri", + "public_namespace", + "version", + "revision", + "ingested_at", + "serving", + "denied", + "duplicate", + "expired", + "failed", + "unread", + ], +) +async def test_lost_proof_invalidates_monotonically_and_cannot_be_readmitted(world, change): + from server.knowledge.app import source_corpus + + plan, _item, fresh = world + proof = bundle(world) + if change in {"namespace", "source_uri"}: + fresh.candidate[change] = "other" + elif change == "public_namespace": + plan.check.return_value = [replace(fresh, namespace="other")] + elif change in {"version", "revision"}: + fresh.document[change] += 1 + elif change == "ingested_at": + fresh.document[change] = datetime(2025, 1, 2, tzinfo=UTC) + elif change == "serving": + plan.check.return_value = [replace(fresh, serving=Serving(False, 0, 0, 10))] + elif change == "denied": + plan.check.return_value = [] + elif change == "duplicate": + plan.check.return_value = [fresh, fresh] + elif change == "expired": + plan.current = lambda _item: False + else: + setattr(plan, change, True) + with pytest.raises(source_corpus.LostCorpus): + await proof.check() + assert proof.invalid + calls = plan.check.await_count + plan.check.return_value = [fresh] + plan.failed = plan.unread = False + plan.current = lambda _item: True + with pytest.raises(source_corpus.LostCorpus): + await proof.check() + assert plan.check.await_count == calls + + +async def test_expected_identity_is_snapshotted_instead_of_aliasing_mutable_metadata(world): + from server.knowledge.app import source_corpus + + _plan, item, fresh = world + proof = bundle(world) + item.document["version"] = fresh.document["version"] = 11 + with pytest.raises(source_corpus.LostCorpus): + await proof.check() + + +async def test_empty_mirror_bundle_keeps_ordinary_work_despite_unread_mirror_plan(world): + plan, _item, _fresh = world + plan.failed = plan.unread = True + proof = bundle(world, []) + await proof.check() + assert not proof.invalid + plan.check.assert_not_awaited() + + +async def test_conditional_backend_error_is_sanitized_and_does_not_mark_unread(world): + from server.knowledge.app import source_corpus + + plan, _item, _fresh = world + plan.check.side_effect = RuntimeError("private backend detail") + with pytest.raises(source_corpus.LostCorpus) as caught: + await bundle(world).check() + assert "private" not in str(caught.value) and caught.value.__suppress_context__ + assert plan.failed and not plan.unread + + +async def test_cancellation_propagates(world): + plan, _item, _fresh = world + plan.check.side_effect = asyncio.CancelledError + with pytest.raises(asyncio.CancelledError): + await bundle(world).check() + assert not plan.unread + + +async def test_last_await_expiry_invalidates_earlier_batches_too(world): + from server.knowledge.app import source_corpus + + plan, item, _fresh = world + items = [ + replace(item, candidate={**item.candidate, "source_uri": f"gdrive:{i}#source"}) + for i in range(129) + ] + calls = 0 + + async def check(candidates): + nonlocal calls + calls += 1 + assert len(candidates) <= 64 + if calls == 3: + plan.current = lambda selected: selected.candidate["source_uri"] != "gdrive:0#source" + return [replace(item, candidate=candidate) for candidate in candidates] + + plan.check.side_effect = check + with pytest.raises(source_corpus.LostCorpus): + await bundle(world, items).check() + assert calls == 3 and not plan.unread + + +async def test_waiting_validation_cannot_restore_a_corpus_after_observed_revocation(world): + from server.knowledge.app import source_corpus + + plan, _item, _fresh = world + started, finish = asyncio.Event(), asyncio.Event() + proof = bundle(world) + + async def revoked(_candidates): + started.set() + await finish.wait() + return [] + + plan.check.side_effect = revoked + first = asyncio.create_task(proof.check()) + await started.wait() + second = asyncio.create_task(proof.check()) + finish.set() + results = await asyncio.gather(first, second, return_exceptions=True) + assert all(isinstance(result, source_corpus.LostCorpus) for result in results) + assert proof.invalid and plan.check.await_count == 1 diff --git a/tests/unit/test_source_document_chunks.py b/tests/unit/test_source_document_chunks.py new file mode 100644 index 0000000000..0af740505c --- /dev/null +++ b/tests/unit/test_source_document_chunks.py @@ -0,0 +1,132 @@ +"""Document chunks retain embedding stubs and invalidate a failed or expired outline.""" + +from __future__ import annotations + +from contextlib import asynccontextmanager +from types import SimpleNamespace +from unittest.mock import AsyncMock + +import pytest + +from server.knowledge.app import source_documents as app +from server.knowledge.app import source_search +from server.knowledge.app.source_access import Admitted + +NS = "acl-" + "1" * 24 +URI = "gdrive:file#11111111-1111-4111-8111-111111111111" + + +@pytest.fixture +def world(monkeypatch): + state = {"size": 2, "stream_error": False, "expired": False} + rows = [ + {"namespace": NS, "source_uri": URI, "chunk_idx": i, "doc_version": 10, "revision": 0} + for i in range(129) + ] + row = SimpleNamespace(org="acme", namespace=NS, source_uri=URI, version=10, revision=0) + doc = Admitted("team", {"namespace": NS, "source_uri": URI}, {"version": 10, "revision": 0}) + checked = app.CheckedDocument(doc, row) + plan = SimpleNamespace( + org="acme", failed=False, unread=False, current=lambda _item: not state["expired"] + ) + + async def check(candidates, *, chunks=False): + return [Admitted("team", c, {"version": 10, "revision": 0}) for c in candidates] + + @asynccontextmanager + async def candidates(org, namespace, uri, model): + assert (org, namespace, uri, model) == ("acme", NS, URI, "fixture") + + async def stream(): + for selected in rows[: state["size"]]: + yield selected + if state["stream_error"]: + raise RuntimeError("private stream failure") + + yield stream() + + async def chunks(org, model, keys, *, embedded_only=True): + assert not embedded_only, "Outline text includes chunks awaiting an embedding" + return [ + { + "namespace": ns, + "source_uri": uri, + "chunk_idx": idx, + "doc_version": version, + "revision": revision, + "content": "stub" if idx == 1 else "embedded", + "chunk_metadata": "{}", + } + for ns, uri, idx, version, revision in keys + ] + + plan.check = AsyncMock(side_effect=check) + monkeypatch.setattr(app.store, "chunk_candidates", candidates, raising=False) + monkeypatch.setattr(source_search.store, "chunks", AsyncMock(side_effect=chunks)) + return plan, checked, rows, state + + +async def test_outline_hydrates_embedded_and_stub_sections_in_document_order(world): + plan, checked, _rows, _state = world + result = await app.chunks(plan, checked, model="fixture") + assert [r.row["content"] for r in result] == ["embedded", "stub"] + assert [r.admitted.candidate["chunk_idx"] for r in result] == [0, 1] + assert not plan.failed and not plan.unread + + +async def test_empty_document_has_a_valid_empty_outline(world): + plan, checked, _rows, state = world + state["size"] = 0 + assert await app.chunks(plan, checked, model="fixture") == [] + source_search.store.chunks.assert_not_awaited() + + +async def test_late_stream_error_discards_already_hydrated_chunks_without_unread(world): + plan, checked, _rows, state = world + state.update(size=65, stream_error=True) + assert await app.chunks(plan, checked, model="fixture") is None + assert source_search.store.chunks.await_count >= 1 + assert plan.failed and not plan.unread + + +@pytest.mark.parametrize("change", ["denied", "version", "revision", "expired"]) +async def test_final_document_permission_and_identity_are_required(world, change): + plan, checked, _rows, state = world + original = plan.check.side_effect + + async def final(candidates, *, chunks=False): + out = await original(candidates, chunks=chunks) + if not chunks: + if change == "denied": + return [] + if change == "expired": + state["expired"] = True + else: + out[0].document[change] += 1 + return out + + plan.check.side_effect = final + assert await app.chunks(plan, checked, model="fixture") is None + assert not plan.unread + + +async def test_final_expiry_drops_early_batches_too(world): + plan, checked, _rows, state = world + state["size"] = 129 + original = plan.check.side_effect + + async def final(candidates, *, chunks=False): + out = await original(candidates, chunks=chunks) + if not chunks: + state["expired"] = True + return out + + plan.check.side_effect = final + assert await app.chunks(plan, checked, model="fixture") is None + + +async def test_unexpected_chunk_source_invalidates_the_whole_copy(world): + plan, checked, rows, _state = world + rows[1]["source_uri"] = "different-source" + assert await app.chunks(plan, checked, model="fixture") is None + assert plan.failed and not plan.unread diff --git a/tests/unit/test_source_document_handler.py b/tests/unit/test_source_document_handler.py new file mode 100644 index 0000000000..e0f824caa9 --- /dev/null +++ b/tests/unit/test_source_document_handler.py @@ -0,0 +1,123 @@ +"""Public document reads project checked copies while mining stays ordinary-only.""" + +from __future__ import annotations + +from types import SimpleNamespace +from unittest.mock import AsyncMock + +import pytest + +from server.knowledge.api.models_knowledge import KnowledgeGetInput +from server.knowledge.app import document_reads as app +from server.knowledge.app import source_access, source_documents +from server.knowledge.app.source_access import Admitted +from server.knowledge.store import documents + +SID = "11111111-1111-4111-8111-111111111111" + + +@pytest.fixture +def world(monkeypatch): + from datetime import UTC, datetime + + phases = [] + plan = SimpleNamespace(marked=True) + input = KnowledgeGetInput(org="acme", namespace="team", source_uri="gdrive:file#native") + row = documents.DocumentRow( + org="acme", + namespace="acl-" + "1" * 24, + source_uri=input.source_uri + "#" + SID, + doc_id="22222222-2222-4222-8222-222222222222", + content="admitted content", + title="Checked", + tags=["source-id:" + SID, "kind:notes"], + version=10, + revision=0, + ingested_at=datetime(2025, 1, 1, tzinfo=UTC), + access_json="private ACL", + ) + checked = source_documents.CheckedDocument(Admitted("team", {}, {}), row) + + async def prepare(*args): + phases.append(("prepare", args)) + return plan + + async def ordinary(*args, **kwargs): + phases.append(("ordinary", args, kwargs)) + return None + + async def mirrored(*args): + phases.append(("mirrored", args)) + return checked + + monkeypatch.setattr(source_access, "prepare", AsyncMock(side_effect=prepare)) + monkeypatch.setattr(documents, "get_one", AsyncMock(side_effect=ordinary)) + monkeypatch.setattr(source_documents, "get", AsyncMock(side_effect=mirrored)) + return input, row, plan, phases + + +async def test_get_prepares_before_any_content_and_projects_only_checked_copy(world): + input, row, plan, phases = world + result = await app.handle_knowledge_get(input) + assert result.found and result.content == row.content and result.title == row.title + assert result.source_uri == input.source_uri and result.tags == ["kind:notes"] + assert "access_json" not in result.model_dump() + assert phases == [ + ("prepare", ("acme", ["team"])), + ("ordinary", ("acme", "team", input.source_uri), {"include_superseded": False}), + ("mirrored", (plan, "team", input.source_uri)), + ] + + +async def test_existing_ordinary_copy_wins_with_all_its_fields_unchanged(world): + input, row, _plan, _phases = world + ordinary = row.model_copy( + update={ + "namespace": "team", + "source_uri": input.source_uri, + "content": "ordinary text", + "tags": ["ordinary"], + } + ) + documents.get_one.side_effect = None + documents.get_one.return_value = ordinary + result = await app.handle_knowledge_get(input) + assert result.found and result.content == "ordinary text" and result.tags == ["ordinary"] + source_documents.get.assert_not_awaited() + + +@pytest.mark.parametrize("include_superseded", [False, True]) +async def test_missing_and_denied_mirror_have_the_complete_missing_reply(world, include_superseded): + input, _row, plan, _phases = world + input = input.model_copy(update={"include_superseded": include_superseded}) + source_documents.get.side_effect = None + source_documents.get.return_value = None + hidden = await app.handle_knowledge_get(input) + plan.marked = False + missing = await app.handle_knowledge_get(input) + assert hidden.model_dump(mode="json") == missing.model_dump(mode="json") + assert not hidden.found and hidden.source_uri == input.source_uri + + +async def test_ordinary_helper_cannot_prepare_or_read_mirrors(world): + input, _row, _plan, phases = world + result = await app.ordinary_get(input) + assert not result.found + source_access.prepare.assert_not_awaited() + source_documents.get.assert_not_awaited() + assert len(phases) == 1 and phases[0][0] == "ordinary" + + +async def test_decision_citation_probe_uses_only_ordinary_document_reads(monkeypatch): + from server.memory.app.decision_extract import cites_document, source_resource_id + + ordinary = AsyncMock(return_value=SimpleNamespace(found=False)) + monkeypatch.setattr(app, "ordinary_get", ordinary, raising=False) + mirrored = AsyncMock(side_effect=AssertionError("mining cannot read mirrored documents")) + monkeypatch.setattr(app, "handle_knowledge_get", mirrored) + uri = "gdrive:file" + assert await cites_document( + "acme", source_resource_id("team", uri, "part#heading"), "team", uri + ) + ordinary.assert_awaited_once() + mirrored.assert_not_awaited() diff --git a/tests/unit/test_source_document_refresh.py b/tests/unit/test_source_document_refresh.py new file mode 100644 index 0000000000..8f7ec852de --- /dev/null +++ b/tests/unit/test_source_document_refresh.py @@ -0,0 +1,77 @@ +"""An open document retains only its exact, currently admitted identity.""" + +from __future__ import annotations + +import asyncio +from types import SimpleNamespace +from unittest.mock import AsyncMock + +import pytest + +from server.knowledge.app import source_documents as app +from server.knowledge.app.source_access import Admitted + + +@pytest.fixture +def world(monkeypatch): + candidate = {"namespace": "acl-" + "1" * 24, "source_uri": "file#source"} + admitted = Admitted("team", candidate, {"version": 10, "revision": 0}) + row = SimpleNamespace(org="acme", **candidate, version=10, revision=0) + checked = app.CheckedDocument(admitted, row) + plan = SimpleNamespace(org="acme", failed=False, unread=False, current=lambda _item: True) + refreshed = Admitted("team", dict(candidate), {"version": 10, "revision": 0}) + plan.check = AsyncMock(return_value=[refreshed]) + monkeypatch.setattr( + app.store, "contents", AsyncMock(side_effect=AssertionError("No new text read")) + ) + return plan, checked, refreshed + + +async def test_refresh_uses_current_proof_without_reading_text_again(world): + plan, checked, refreshed = world + result = await app.refresh(plan, checked) + assert result.row is checked.row and result.admitted is refreshed + plan.check.assert_awaited_once_with([checked.admitted.candidate]) + app.store.contents.assert_not_awaited() + + +@pytest.mark.parametrize("state", ["failed", "unread"]) +async def test_unavailable_plan_never_revalidates_or_reads_content(world, state): + plan, checked, _refreshed = world + setattr(plan, state, True) + assert await app.refresh(plan, checked) is None + plan.check.assert_not_awaited() + app.store.contents.assert_not_awaited() + + +@pytest.mark.parametrize( + "change", ["namespace", "source_uri", "version", "revision", "denied", "expired", "duplicate"] +) +async def test_changed_or_missing_proof_cannot_authorize_the_open_copy(world, change): + plan, checked, refreshed = world + if change in {"namespace", "source_uri"}: + refreshed.candidate[change] = "other" + elif change in {"version", "revision"}: + refreshed.document[change] += 1 + elif change == "expired": + plan.current = lambda _item: False + else: + plan.check.return_value = [] if change == "denied" else [refreshed, refreshed] + assert await app.refresh(plan, checked) is None + assert not plan.unread + app.store.contents.assert_not_awaited() + + +async def test_conditional_refresh_exception_is_failed_without_unread(world): + plan, checked, _refreshed = world + plan.check.side_effect = RuntimeError("private backend detail") + assert await app.refresh(plan, checked) is None + assert plan.failed and not plan.unread + + +async def test_refresh_cancellation_propagates(world): + plan, checked, _refreshed = world + plan.check.side_effect = asyncio.CancelledError + with pytest.raises(asyncio.CancelledError): + await app.refresh(plan, checked) + assert not plan.failed and not plan.unread diff --git a/tests/unit/test_source_documents.py b/tests/unit/test_source_documents.py new file mode 100644 index 0000000000..c64797906f --- /dev/null +++ b/tests/unit/test_source_documents.py @@ -0,0 +1,282 @@ +"""Exact document reads distinguish discovery errors from conditional admission failures.""" + +from __future__ import annotations + +from datetime import UTC, datetime, timedelta +from types import SimpleNamespace +from unittest.mock import AsyncMock + +import pytest + +from server.knowledge.app.source_access import Admitted + +MIRROR = "acl-" + "1" * 24 + + +@pytest.fixture +def world(monkeypatch): + from server.knowledge.app import source_documents as app + + phases = [] + source = "11111111-1111-4111-8111-111111111111" + row = SimpleNamespace( + org="acme", + namespace=MIRROR, + source_uri="gdrive:file#native#" + source, + version=10, + revision=0, + ) + plan = SimpleNamespace( + org="acme", + discovery_sources={(MIRROR, source): "team"}, + failed=False, + unread=False, + current=lambda _item: True, + ) + + async def discover(org, pairs): + phases.append(("discover", org, pairs)) + return [{"namespace": ns, "source_uri": uri} for ns, uri in pairs] + + async def check(candidates, *, chunks=False): + phases.append("check") + assert not chunks + return [ + Admitted( + "team", + c, + {"version": 10, "revision": 0, "ingested_at": datetime(2025, 1, 1, tzinfo=UTC)}, + ) + for c in candidates + ] + + async def contents(*args): + phases.append(("contents", args)) + return row + + plan.check = AsyncMock(side_effect=check) + monkeypatch.setattr(app.pg, "enabled", lambda: False) + monkeypatch.setattr(app.evidence, "metadata", AsyncMock(side_effect=discover)) + monkeypatch.setattr(app.store, "contents", AsyncMock(side_effect=contents)) + return app, plan, row, phases + + +async def test_document_text_is_read_only_at_admitted_metadata_identity(world): + app, plan, row, phases = world + result = await app.get(plan, "team", "gdrive:file#native") + assert result.row is row and result.admitted.namespace == "team" + assert phases == [ + ("discover", "acme", [(MIRROR, row.source_uri)]), + "check", + ("contents", ("acme", MIRROR, row.source_uri, 10, 0)), + "check", + ] + + +@pytest.mark.parametrize("state", ["failed", "unread", "other_namespace"]) +async def test_failed_plan_keeps_selected_discovery_but_never_reads_content(world, state): + app, plan, _row, phases = world + if state == "other_namespace": + plan.discovery_sources = {key: "other" for key in plan.discovery_sources} + else: + setattr(plan, state, True) + assert await app.get(plan, "team", "gdrive:file#native") is None + assert phases == ( + [] if state == "other_namespace" else [("discover", "acme", [(MIRROR, _row.source_uri)])] + ) + plan.check.assert_not_awaited() + app.store.contents.assert_not_awaited() + + +async def test_missing_or_denied_document_never_reads_text(world): + app, plan, _row, _phases = world + app.evidence.metadata.return_value = [] + app.evidence.metadata.side_effect = None + assert await app.get(plan, "team", "gdrive:file#native") is None + app.store.contents.assert_not_awaited() + app.evidence.metadata.side_effect = lambda _org, pairs: [ + {"namespace": ns, "source_uri": uri} for ns, uri in pairs + ] + plan.check.side_effect = None + plan.check.return_value = [] + assert await app.get(plan, "team", "gdrive:file#native") is None + app.store.contents.assert_not_awaited() + + +@pytest.mark.parametrize( + "field,value", + [ + ("org", "other"), + ("namespace", "other"), + ("source_uri", "other"), + ("version", 11), + ("revision", 1), + ], +) +async def test_unexpected_content_invalidates_every_mirror(world, field, value): + app, plan, row, _phases = world + setattr(row, field, value) + assert await app.get(plan, "team", "gdrive:file#native") is None + assert plan.failed and not plan.unread + + +@pytest.mark.parametrize("change", ["denied", "metadata_version", "revision", "expired"]) +async def test_postfetch_permission_or_identity_loss_drops_fetched_text(world, change): + app, plan, _row, _phases = world + check = plan.check.side_effect + count = 0 + + async def changed(candidates, *, chunks=False): + nonlocal count + count += 1 + out = await check(candidates, chunks=chunks) + if count == 2: + if change == "denied": + return [] + if change == "expired": + plan.current = lambda _item: False + else: + out[0].document["version" if change == "metadata_version" else "revision"] += 1 + return out + + plan.check.side_effect = changed + assert await app.get(plan, "team", "gdrive:file#native") is None + assert not plan.unread + + +async def test_all_bounded_discovery_queries_run_after_an_earlier_failure(world): + app, plan, _row, phases = world + plan.discovery_sources = { + (MIRROR, f"{i:08x}-1111-4111-8111-111111111111"): "team" for i in range(65) + } + calls = [] + + async def broken(_org, pairs): + calls.append(pairs) + if len(calls) == 1: + raise RuntimeError("private database detail") + return [] + + app.evidence.metadata.side_effect = broken + assert await app.get(plan, "team", "gdrive:file#native") is None + assert [len(batch) for batch in calls] == [64, 1] + assert plan.failed and plan.unread + assert phases == [] + plan.check.assert_not_awaited() + app.store.contents.assert_not_awaited() + + +@pytest.mark.parametrize("stage", ["check", "contents"]) +async def test_conditional_failure_is_atomic_without_unread(world, stage): + app, plan, _row, _phases = world + target = plan.check if stage == "check" else app.store.contents + target.side_effect = RuntimeError("private failure") + assert await app.get(plan, "team", "gdrive:file#native") is None + assert plan.failed and not plan.unread + + +async def test_cancellation_propagates(world): + import asyncio + + app, plan, _row, _phases = world + app.store.contents.side_effect = asyncio.CancelledError + with pytest.raises(asyncio.CancelledError): + await app.get(plan, "team", "gdrive:file#native") + assert not plan.failed and not plan.unread + + +@pytest.mark.parametrize("first", ["missing", "denied", "changed"]) +async def test_another_admitted_source_survives_a_missing_or_revoked_copy(world, first): + app, plan, row, _phases = world + from copy import copy + + second = "22222222-2222-4222-8222-222222222222" + plan.discovery_sources[(MIRROR, second)] = "team" + second_row = copy(row) + second_row.source_uri = "gdrive:file#native#" + second + app.store.contents.side_effect = [None if first == "missing" else row, second_row] + original_check = plan.check.side_effect + calls = 0 + + async def check(candidates, *, chunks=False): + nonlocal calls + calls += 1 + out = await original_check(candidates, chunks=chunks) + for item in out: + if item.candidate["source_uri"] == row.source_uri: + item.document["ingested_at"] += timedelta(seconds=1) + if calls == 2 and first == "denied": + return [] + if calls == 2 and first == "changed": + out[0].document["version"] += 1 + return out + + plan.check.side_effect = check + result = await app.get(plan, "team", "gdrive:file#native") + assert result.row is second_row + assert not plan.failed and not plan.unread + + +async def test_pg_discovery_uses_current_heads_without_ch_metadata_fallback(world, monkeypatch): + app, plan, row, _phases = world + monkeypatch.setattr(app.pg, "enabled", lambda: True) + head = SimpleNamespace(row={"namespace": MIRROR, "source_uri": row.source_uri}) + monkeypatch.setattr( + app.evidence, "heads", AsyncMock(return_value={(MIRROR, row.source_uri): head}) + ) + result = await app.get(plan, "team", "gdrive:file#native") + assert result.row is row + app.evidence.metadata.assert_not_awaited() + + +async def test_prior_conditional_failure_cannot_hide_a_selected_discovery_failure(world): + app, plan, _row, _phases = world + plan.failed = True + app.evidence.metadata.side_effect = RuntimeError("unconditional metadata failure") + assert await app.get(plan, "team", "gdrive:file#native") is None + app.evidence.metadata.assert_awaited_once() + plan.check.assert_not_awaited() + app.store.contents.assert_not_awaited() + assert plan.failed and plan.unread + + +@pytest.mark.parametrize("newer", ["first", "second"]) +async def test_newest_admitted_copy_wins_independently_of_storage_address(world, newer): + from copy import copy + + app, plan, row, _phases = world + second_source = "22222222-2222-4222-8222-222222222222" + plan.discovery_sources[(MIRROR, second_source)] = "team" + second = copy(row) + second.source_uri = "gdrive:file#native#" + second_source + original_check = plan.check.side_effect + + async def dated(candidates, *, chunks=False): + out = await original_check(candidates, chunks=chunks) + for item in out: + is_first = item.candidate["source_uri"] == row.source_uri + if is_first == (newer == "first"): + item.document["ingested_at"] += timedelta(seconds=1) + return out + + plan.check.side_effect = dated + app.store.contents.side_effect = lambda _org, _ns, uri, *_args: ( + row if uri == row.source_uri else second + ) + result = await app.get(plan, "team", "gdrive:file#native") + assert result.row is (row if newer == "first" else second) + assert app.store.contents.await_count == 1 + + +async def test_equal_age_copy_tie_is_stable_and_matches_checked_listing(world): + from copy import copy + + app, plan, row, _phases = world + second_source = "22222222-2222-4222-8222-222222222222" + plan.discovery_sources[(MIRROR, second_source)] = "team" + second = copy(row) + second.source_uri = "gdrive:file#native#" + second_source + app.store.contents.return_value = second + app.store.contents.side_effect = None + assert (await app.get(plan, "team", "gdrive:file#native")).row is second + assert app.store.contents.await_count == 1 diff --git a/tests/unit/test_source_downloads.py b/tests/unit/test_source_downloads.py new file mode 100644 index 0000000000..a27c93358b --- /dev/null +++ b/tests/unit/test_source_downloads.py @@ -0,0 +1,274 @@ +"""Checked downloads revalidate before headers and every emitted chunk.""" + +from __future__ import annotations + +import asyncio +import traceback +from contextlib import asynccontextmanager +from dataclasses import replace +from datetime import UTC, datetime +from types import SimpleNamespace +from unittest.mock import AsyncMock + +import pytest +from fastapi import Request +from fastapi.testclient import TestClient +from starlette.requests import ClientDisconnect + +from server.knowledge.app import download_routes as app +from server.knowledge.app import source_access, source_documents +from server.knowledge.app.source_access import Admitted +from server.knowledge.store import blobs, documents +from server.knowledge.store.documents import DocumentRow + +SID = "11111111-1111-4111-8111-111111111111" +PUBLIC_URI = "gdrive:file#native" +MIRROR = "acl-" + "1" * 24 +URL = "/v1/knowledge.download" + + +@pytest.fixture +def world(monkeypatch): + state = { + "allowed": True, + "opened": 0, + "closed": 0, + "during_read": "", + "data": b"First private section. Second private section. Last section.", + } + plan = SimpleNamespace( + org="acme", marked=True, failed=False, unread=False, current=lambda _item: state["allowed"] + ) + row = DocumentRow( + org="acme", + doc_id=SID, + namespace=MIRROR, + source_uri=PUBLIC_URI + "#" + SID, + title="", + content="Private text.", + version=10, + revision=0, + ingested_at=datetime(2026, 1, 1, tzinfo=UTC), + ) + checked = source_documents.CheckedDocument( + Admitted("team", {"namespace": MIRROR, "source_uri": row.source_uri}, {}), row + ) + state["checked"] = checked + phases = [] + + async def prepare(*_args): + phases.append("prepare") + return plan + + async def ordinary(*_args, **_kwargs): + phases.append("ordinary") + return None + + async def refresh(*_args): + return state["checked"] if state["allowed"] else None + + @asynccontextmanager + async def stream(org, namespace, sha, **_kwargs): + assert (org, namespace, sha) == ("acme", MIRROR, "a" * 64) + state["opened"] += 1 + + async def chunks(): + if state["during_read"] == "cancel": + raise asyncio.CancelledError + if state["during_read"] == "error": + raise RuntimeError("private backend secret") + if state["during_read"] == "revoke": + state["allowed"] = False + for start in range(0, len(state["data"]), 16): + if start and state["during_read"] == "late_io": + raise OSError("private storage secret") + yield state["data"][start : start + 16] + + try: + yield chunks() + finally: + state["closed"] += 1 + if state.get("close_error"): + raise RuntimeError("private close secret") + + monkeypatch.setattr(app.settings, "auth_required", False) + monkeypatch.setattr(app, "check_acted_for", AsyncMock()) + monkeypatch.setattr(app, "check_authorized", AsyncMock()) + monkeypatch.setattr(app, "note_restricted_access", AsyncMock()) + monkeypatch.setattr(source_access, "prepare", AsyncMock(side_effect=prepare)) + monkeypatch.setattr(documents, "get_one", AsyncMock(side_effect=ordinary)) + monkeypatch.setattr(source_documents, "get", AsyncMock(return_value=checked)) + monkeypatch.setattr(source_documents, "refresh", AsyncMock(side_effect=refresh)) + monkeypatch.setattr( + blobs, "locate", AsyncMock(side_effect=lambda *_args: blobs.Stored(len(state["data"]), "")) + ) + monkeypatch.setattr( + blobs, "read", AsyncMock(side_effect=AssertionError("Mirror blobs must stream")) + ) + monkeypatch.setattr(blobs, "stream", stream) + return state, plan, checked, phases + + +def _blob(world): + state, _plan, checked, _phases = world + selected = replace(checked, row=checked.row.model_copy(update={"blob_path": "a" * 64})) + state["checked"] = selected + source_documents.get.return_value = selected + + +@pytest.fixture +def client(world): + from server.main import app as application + + return TestClient(application, base_url="http://localhost") + + +def params(): + return {"org": "acme", "namespace": "team", "source_uri": PUBLIC_URI} + + +async def response(spec="2.4"): + scope = { + "type": "http", + "method": "GET", + "path": URL, + "headers": [], + "asgi": {"spec_version": spec}, + } + return scope, await app.knowledge_download(Request(scope), **params()) + + +async def receive(): + await asyncio.Event().wait() + return {"type": "http.disconnect"} + + +def test_checked_text_download_prepares_before_content_and_projects_filename(world, client): + _state, _plan, checked, phases = world + result = client.get(URL, params=params()) + assert result.status_code == 200 and result.text == checked.row.content + assert result.headers["x-loom-download-source"] == "text" + assert SID not in result.headers["content-disposition"] + assert phases[:2] == ["prepare", "ordinary"] + source_documents.refresh.assert_awaited() + + +def test_ordinary_document_remains_the_complete_download_copy(world, client): + _state, _plan, checked, phases = world + documents.get_one.side_effect = None + documents.get_one.return_value = checked.row.model_copy( + update={"namespace": "team", "source_uri": PUBLIC_URI, "content": "Ordinary text."} + ) + result = client.get(URL, params=params()) + assert result.status_code == 200 and result.text == "Ordinary text." + assert phases == ["prepare"] + source_documents.get.assert_not_awaited() + source_documents.refresh.assert_not_awaited() + + +def test_checked_blob_uses_admitted_namespace_and_closes(world, client): + state, _plan, checked, _phases = world + _blob(world) + result = client.get(URL, params=params(), headers={"Accept-Encoding": "identity"}) + assert result.status_code == 200 and result.content == state["data"] + assert state["opened"] == state["closed"] == 1 + assert result.headers["content-length"] == str(len(state["data"])) + assert SID not in result.headers["content-disposition"] + blobs.locate.assert_awaited_once_with("acme", MIRROR, "a" * 64) + blobs.read.assert_not_awaited() + + +@pytest.mark.parametrize("change", ["locate", "revoke", "error"]) +def test_preheader_blob_loss_has_the_complete_missing_reply_and_closes(world, client, change): + state, _plan, checked, _phases = world + source_documents.get.return_value = None + missing = client.get(URL, params=params()) + source_documents.get.return_value = checked + _blob(world) + if change == "locate": + + async def locate(*_args): + state["allowed"] = False + return blobs.Stored(len(state["data"]), "") + + blobs.locate.side_effect = locate + else: + state["during_read"] = change + result = client.get(URL, params=params()) + assert result.status_code == missing.status_code == 404 + assert result.json() == missing.json() + assert "private backend" not in result.text + blobs.locate.assert_awaited_once() + assert state["opened"] == state["closed"] == (0 if change == "locate" else 1) + + +@pytest.mark.parametrize("spec", ["2.3", "2.4"]) +@pytest.mark.parametrize("when", ["headers", "first_chunk"]) +async def test_revocation_during_send_prevents_the_next_body_chunk(world, when, spec): + state, _plan, checked, _phases = world + _blob(world) + scope, answer = await response(spec) + sent = [] + + async def send(message): + sent.append(message) + if message["type"] == "http.response.start" and when == "headers": + state["allowed"] = False + elif ( + message["type"] == "http.response.body" + and message.get("body") + and when == "first_chunk" + ): + state["allowed"] = False + + with pytest.raises(RuntimeError, match="document read unavailable"): + await answer(scope, receive, send) + payload = b"".join(message.get("body", b"") for message in sent) + assert payload == (b"" if when == "headers" else state["data"][:16]) + assert state["opened"] == state["closed"] == 1 + + +async def test_cancellation_during_prefetch_closes_the_open_stream(world): + state, plan, checked, _phases = world + _blob(world) + state["during_read"] = "cancel" + scope, answer = await response() + send = AsyncMock() + with pytest.raises(asyncio.CancelledError): + await answer(scope, receive, send) + assert state["opened"] == state["closed"] == 1 + assert not plan.failed + send.assert_not_awaited() + + +async def test_failed_header_send_closes_a_prefetched_but_unstarted_body(world): + state, _plan, checked, _phases = world + _blob(world) + scope, answer = await response() + with pytest.raises(ClientDisconnect): + await answer(scope, receive, AsyncMock(side_effect=OSError("client gone"))) + assert state["opened"] == state["closed"] == 1 + + +def test_preheader_cleanup_failure_does_not_escape_private_details(world, client): + state, _plan, _checked, _phases = world + source_documents.get.return_value = None + missing = client.get(URL, params=params()) + _blob(world) + state.update(during_read="revoke", close_error=True) + result = client.get(URL, params=params()) + assert result.status_code == 404 and result.json() == missing.json() + assert state["opened"] == state["closed"] == 1 + + +@pytest.mark.parametrize("spec", ["2.3", "2.4"]) +async def test_body_io_failure_does_not_escape_private_traceback_context(world, spec): + state, _plan, _checked, _phases = world + _blob(world) + state["during_read"] = "late_io" + scope, answer = await response(spec) + with pytest.raises((ClientDisconnect, RuntimeError)) as error: + await answer(scope, receive, AsyncMock()) + rendered = "".join(traceback.format_exception(error.value)) + assert "private storage secret" not in rendered + assert state["opened"] == state["closed"] == 1 diff --git a/tests/unit/test_source_fanout_renewal.py b/tests/unit/test_source_fanout_renewal.py new file mode 100644 index 0000000000..3327f9b323 --- /dev/null +++ b/tests/unit/test_source_fanout_renewal.py @@ -0,0 +1,243 @@ +"""Wider knowledge failures remain additive during permission renewal.""" + +from __future__ import annotations + +import asyncio +from types import SimpleNamespace +from unittest.mock import AsyncMock + +import pytest + +from server.core import request_tail +from server.core.diagnostics import private_work +from server.knowledge.api.models_conversations import ConversationSearchOutput +from server.knowledge.api.models_knowledge import ( + KnowledgeSearchInput, + KnowledgeSearchOutput, + _SearchHit, +) +from server.knowledge.app import repo_docs, source_publication +from server.knowledge.app.knowledge_search import CheckedSearch, SearchRequest +from server.knowledge.app.source_access import ReadPlan +from server.knowledge.app.source_corpus import LostCorpus +from server.memory.api.models_search import MemorySearchOutput +from server.memory.app.loom_search import fanout +from server.memory.domain.assistant_rules import hits_to_ask + + +def hit(uri, *, other=False): + return _SearchHit( + source_uri=uri, + content=uri, + chunk_idx=0, + distance=0.2, + similarity=0.8, + score=0.8, + namespace="home", + tags=["source-kind:assistant_turn", "agent:other-bot"] if other else [], + ) + + +def result(name, *, lost=False, fail_render=False, needs_widen=False, ordinary_full=False): + inp = KnowledgeSearchInput(org="acme", namespace="home", query="cache", top_k=2) + request = repo_docs.RepoSearchRequest( + SearchRequest(inp, ("home",), ()), None, "", asyncio.get_running_loop().time() + 100 + ) + mixed = KnowledgeSearchOutput( + results=[hit("private-other", other=True), hit("private-a")] + if needs_widen + else [hit("private-" + name)], + embedding_model="private-model", + reranked_by="private-rank", + ) + ordinary = KnowledgeSearchOutput( + results=[hit("ordinary-a"), hit("ordinary-b")] + if ordinary_full + else [hit("ordinary-other", other=True), hit("ordinary-a")], + embedding_model="ordinary-model", + stale_dropped=7, + ) + + async def render(*_args): + await asyncio.sleep(0) + if fail_render: + raise RuntimeError("PRIVATE-WIDER-ERROR") + return ordinary + + proof = SimpleNamespace( + mirrored=True, + check=AsyncMock(side_effect=LostCorpus() if lost else None), + fresh=lambda: not lost, + ) + renderer = SimpleNamespace(marked=True, render=AsyncMock(side_effect=render)) + checked = CheckedSearch(mixed, proof, renderer, [], 7) + return repo_docs.RepoSearch(request, checked, None), renderer + + +async def test_failed_wider_ordinary_render_does_not_cancel_first_fallback(caplog): + first, first_renderer = result("first") + wider, wider_renderer = result("wider", fail_render=True) + with private_work(): + know = await fanout._ordinary_knowledge(first, wider, "reader") + assert [h["source_uri"] for h in know["results"]] == ["ordinary-a"] + assert (know["embedding_model"], know["reranked_by"], know["stale_dropped"]) == ( + "ordinary-model", + "", + 7, + ) + first_renderer.render.assert_awaited_once() + wider_renderer.render.assert_awaited_once() + assert "PRIVATE-WIDER-ERROR" not in caplog.text + + +async def test_late_wider_renewal_failure_keeps_ordinary_first_and_never_retries_wide(monkeypatch): + first, first_renderer = result("first", needs_widen=True) + wider, wider_renderer = result("wider", lost=True, fail_render=True) + run = AsyncMock(return_value=wider) + monkeypatch.setattr(repo_docs, "run_repo_search", run) + with private_work(): + know = await fanout._knowledge_section(first, ReadPlan("acme", marked=True), "reader") + assert [h["source_uri"] for h in know["results"]] == ["ordinary-a"] + assert know["reranked_by"] == "" and know["stale_dropped"] == 7 + first_renderer.render.assert_awaited_once() + wider_renderer.render.assert_awaited_once() + run.assert_awaited_once() + request, _plan = run.call_args.args + assert request.base.input.top_k == hits_to_ask(2) and request.base.namespaces == ("home",) + + +async def test_independently_cancelled_knowledge_child_is_propagated(monkeypatch): + first, _ = result("first") + + async def prepare(*_args): + return first.request, ReadPlan("acme") + + async def cancelled(*_args): + raise asyncio.CancelledError() + + async def memory(*_args, **_kwargs): + return MemorySearchOutput(results=[], embedding_model="fake") + + async def empty(*_args, **_kwargs): + return [] + + async def conversations(*_args, **_kwargs): + return ConversationSearchOutput(hits=[]) + + async def namespaces(org, namespace, *_args, **_kwargs): + return [namespace], [] + + monkeypatch.setattr(fanout, "_prepare_knowledge", prepare) + monkeypatch.setattr(fanout, "_run_knowledge", cancelled) + monkeypatch.setattr(fanout, "memory_with_repo_decisions", memory) + monkeypatch.setattr(fanout, "search_profile", empty) + monkeypatch.setattr(fanout, "tracker_leg", empty) + monkeypatch.setattr(fanout, "_conversation_leg", conversations) + monkeypatch.setattr("server.auth.fanout.namespaces_to_search", namespaces) + with pytest.raises(asyncio.CancelledError): + await fanout.search_sections( + org="acme", + namespace="home", + agent="reader", + query="cache", + top_k=2, + tags=[], + namespace_scope="this", + recipe="", + bodies="excerpt", + page="", + explain=False, + repo_namespace="", + tracker_plan=None, + ) + + +@pytest.mark.parametrize("reranked", [False, True]) +@pytest.mark.parametrize("count_changed", [False, True]) +@pytest.mark.parametrize("rerank_possible", [False, True]) +async def test_displaced_base_keeps_only_surviving_private_metadata_dependencies( + reranked, count_changed, rerank_possible +): + first, _renderer = result("base") + first.base.ordinary_rerank_possible = rerank_possible + first.base.output.reranked_by = "private-ranker" if reranked else "" + first.base._ordinary_dropped = 7 if count_changed else first.base.output.stale_dropped + private = first.base.proofs + extra = KnowledgeSearchOutput( + results=[hit("ordinary-a"), hit("ordinary-b")], embedding_model="fake" + ) + for item in extra.results: + item.score = 1 + first.extra = CheckedSearch(extra, None, first.base._renderer, [], 0) + sent = [] + + async def app(scope, receive, send): + output = await first.current() + assert [item.source_uri for item in output.results] == ["ordinary-a", "ordinary-b"] + for proof in first.publication_proofs: + source_publication.retain(proof) + private.check.side_effect = LostCorpus() + await send({"type": "http.response.start", "status": 200, "headers": []}) + await send({"type": "http.response.body", "body": output.model_dump_json().encode()}) + + async def send(message): + sent.append(message) + + if reranked or count_changed or rerank_possible: + with pytest.raises(request_tail.RequiredTailError): + await request_tail.RequestTailMiddleware(app)({"type": "http"}, None, send) + assert sent == [] + else: + await request_tail.RequestTailMiddleware(app)({"type": "http"}, None, send) + assert b"ordinary-a" in sent[-1]["body"] + + +async def test_lost_first_with_full_ordinary_page_never_renews_unused_wider(monkeypatch): + first, first_renderer = result("first", needs_widen=True, ordinary_full=True) + first.base.proofs.check.side_effect = [None, LostCorpus()] + wider, wider_renderer = result("wider", lost=True, fail_render=True) + run = AsyncMock(return_value=wider) + monkeypatch.setattr(repo_docs, "run_repo_search", run) + with private_work(): + know = await fanout._knowledge_section(first, ReadPlan("acme", marked=True), "reader") + assert [h["source_uri"] for h in know["results"]] == ["ordinary-a", "ordinary-b"] + assert first.lost and not wider.lost + first_renderer.render.assert_awaited_once() + wider.base.proofs.check.assert_not_awaited() + wider_renderer.render.assert_not_awaited() + run.assert_awaited_once() + + +async def test_expired_extra_can_remove_widen_need_without_losing_the_first_base(monkeypatch): + from dataclasses import replace + + first, first_renderer = result("first") + first.base.output.results = [hit("private-a"), hit("private-b")] + extra, _extra_renderer = result("extra") + other = hit("extra-other", other=True) + other.namespace, other.score = "repo", 0.99 + extra.base.output.results = [other] + first.extra = extra.base + extra_request = SearchRequest( + first.request.base.input.model_copy( + update={"namespace": "repo", "namespace_scope": "this", "rerank": "none"} + ), + ("repo",), + (), + ) + first.request = replace(first.request, extra=extra_request, repo_namespace="repo") + wider, wider_renderer = result("wider", lost=True, fail_render=True) + + async def run(request, plan): + wider.request = request + first.request = replace(first.request, extra_deadline=asyncio.get_running_loop().time() - 1) + return wider + + monkeypatch.setattr(repo_docs, "run_repo_search", run) + with private_work(): + know = await fanout._knowledge_section(first, ReadPlan("acme", marked=True), "reader") + assert [h["source_uri"] for h in know["results"]] == ["private-a", "private-b"] + assert first.extra is None and not first.lost + wider.base.proofs.check.assert_not_awaited() + wider_renderer.render.assert_not_awaited() + first_renderer.render.assert_not_awaited() diff --git a/tests/unit/test_source_hydration.py b/tests/unit/test_source_hydration.py new file mode 100644 index 0000000000..a7100cd795 --- /dev/null +++ b/tests/unit/test_source_hydration.py @@ -0,0 +1,143 @@ +"""Only exact admitted chunk keys reach text reads or survive their final check.""" + +from __future__ import annotations + +from types import SimpleNamespace +from unittest.mock import AsyncMock + +import pytest + +from server.knowledge.app import source_search as app +from server.knowledge.app.source_access import Admitted + +MIRROR = "acl-" + "1" * 24 +SID = "11111111-1111-4111-8111-111111111111" + + +def item(i): + row = { + "namespace": MIRROR, + "source_uri": f"gdrive:{i}#" + SID, + "chunk_idx": 0, + "doc_version": 10, + "revision": 0, + "distance": 0.2, + "lexical": 3.0, + "matched": ["object"], + } + return Admitted("docs", row, {"version": 10}) + + +@pytest.fixture +def world(monkeypatch): + plan = SimpleNamespace(org="acme", failed=False, unread=False) + pools = {"semantic": [item(0)], "lexical": [item(0)]} + calls = [] + + async def recheck(_plan, retained): + calls.append("check") + return retained + + async def chunks(org, model, keys, *, embedded_only=True): + calls.append((org, model, keys)) + return [ + { + "namespace": ns, + "source_uri": uri, + "chunk_idx": idx, + "doc_version": version, + "revision": revision, + "content": "checked content", + } + for ns, uri, idx, version, revision in keys + ] + + monkeypatch.setattr(app, "recheck", AsyncMock(side_effect=recheck)) + monkeypatch.setattr(app.store, "chunks", AsyncMock(side_effect=chunks), raising=False) + return plan, pools, calls + + +async def test_hydration_checks_before_and_after_one_shared_exact_read(world): + plan, pools, calls = world + pools["lexical"][0].candidate["lexical"] = 7.0 + out = await app.hydrate(plan, pools, model="test-model") + assert calls == [ + "check", + ("acme", "test-model", [(MIRROR, "gdrive:0#" + SID, 0, 10, 0)]), + "check", + ] + assert out["semantic"][0].row["content"] == "checked content" + assert out["semantic"][0].admitted.candidate is pools["semantic"][0].candidate + assert out["lexical"][0].admitted.candidate["lexical"] == 7.0 + assert not plan.failed and not plan.unread + + +async def test_hydration_does_not_read_text_when_recheck_denies_every_candidate(world, monkeypatch): + plan, pools, _calls = world + monkeypatch.setattr(app, "recheck", AsyncMock(return_value={"semantic": []})) + assert await app.hydrate(plan, pools, model="test-model") == {"semantic": []} + app.store.chunks.assert_not_awaited() + + +async def test_hydration_drops_newly_denied_content_and_uses_final_document_metadata( + world, monkeypatch +): + plan, pools, _calls = world + final = Admitted("docs", pools["semantic"][0].candidate, {"version": 11}) + monkeypatch.setattr(app, "recheck", AsyncMock(side_effect=[pools, {"semantic": [final]}])) + out = await app.hydrate(plan, pools, model="test-model") + assert list(out) == ["semantic"] + assert out["semantic"][0].admitted.document == {"version": 11} + + +@pytest.mark.parametrize( + "failure", ["read", "duplicate", "unexpected", "newer_revision", "late_read"] +) +async def test_candidate_hydration_failure_discards_all_pools_without_unread( + world, monkeypatch, failure +): + plan, pools, _calls = world + if failure == "late_read": + pools = {"semantic": [item(i) for i in range(65)]} + original = app.store.chunks.side_effect + count = 0 + + async def broken(org, model, keys, *, embedded_only=True): + nonlocal count + count += 1 + if failure == "read" or (failure == "late_read" and count == 2): + raise RuntimeError("private title") + rows = await original(org, model, keys, embedded_only=embedded_only) + if failure == "duplicate": + rows.append(dict(rows[0])) + elif failure == "unexpected": + rows[0]["source_uri"] = "unrequested" + elif failure == "newer_revision": + rows[0]["revision"] = 1 + return rows + + monkeypatch.setattr(app.store, "chunks", AsyncMock(side_effect=broken)) + assert await app.hydrate(plan, pools, model="test-model") == {} + assert plan.failed and not plan.unread + + +async def test_document_hydration_requests_chunks_without_embedding_eligibility(world): + plan, pools, _calls = world + out = await app.hydrate(plan, pools, model="test-model", embedded_only=False) + assert out["semantic"][0].row["content"] == "checked content" + assert app.store.chunks.call_args.kwargs == {"embedded_only": False} + + +async def test_missing_exact_chunk_is_omitted_without_fetching_its_replacement(world, monkeypatch): + plan, pools, _calls = world + monkeypatch.setattr(app.store, "chunks", AsyncMock(return_value=[])) + assert await app.hydrate(plan, pools, model="test-model") == {"semantic": [], "lexical": []} + assert app.store.chunks.await_count == 1 + assert not plan.failed and not plan.unread + + +async def test_hydration_reads_at_most_64_unique_admitted_keys_per_batch(world): + plan, _pools, calls = world + out = await app.hydrate(plan, {"semantic": [item(i) for i in range(130)]}, model="test-model") + assert len(out["semantic"]) == 130 + assert [len(c[2]) for c in calls if isinstance(c, tuple)] == [64, 64, 2] diff --git a/tests/unit/test_source_list_counts.py b/tests/unit/test_source_list_counts.py new file mode 100644 index 0000000000..3a401dc19b --- /dev/null +++ b/tests/unit/test_source_list_counts.py @@ -0,0 +1,58 @@ +"""A checked list counts only its copy's served logical chunks, including stubs.""" + +from __future__ import annotations + +import pytest + +from server.knowledge.domain.serving import Serving +from server.knowledge.store import source_documents as store +from tests.unit.ch_fake import RecordingCH + +NS = "acl-" + "1" * 24 +URI = "gdrive:file#11111111-1111-4111-8111-111111111111" + + +@pytest.fixture +def world(monkeypatch): + monkeypatch.setattr(store.pg, "enabled", lambda: False) + ch = RecordingCH().on("FROM loom.chunks", [{"chunk_count": 2}]) + ch.install(monkeypatch, "server.knowledge.store.source_documents") + return ch + + +async def test_count_deduplicates_logical_sections_and_includes_embedding_stubs(world): + assert await store.list_chunk_count("acme", NS, URI, 0, None) == 2 + statement = world.calls[-1] + assert statement.params == {"org": "acme", "ns": NS, "uri": URI, "revision": 0} + assert "uniqExact(embedding_model, chunk_idx)" in statement.sql + assert "embedding_dim" not in statement.sql + assert "doc_superseded_at IS NULL" in statement.sql and "chunk_supersessions" in statement.sql + assert "JSONExtractUInt(chunk_metadata, 'revision') = {revision:UInt64}" in statement.sql + assert "doc_version =" not in statement.sql + + +async def test_pg_counts_exact_recorded_chunk_version_not_metadata_only_row_version( + world, monkeypatch +): + monkeypatch.setattr(store.pg, "enabled", lambda: True) + assert await store.list_chunk_count("acme", NS, URI, 2, Serving(False, 2, 2, 10)) == 2 + statement = world.calls[-1] + assert statement.params == {"org": "acme", "ns": NS, "uri": URI, "revision": 2, "version": 10} + assert "doc_version = {version:UInt64}" in statement.sql + + +@pytest.mark.parametrize("head", [Serving(False, 2, None, None), Serving(False, 2, 1, 10)]) +async def test_pg_unpublished_current_revision_has_zero_chunks_without_ch_query( + world, monkeypatch, head +): + monkeypatch.setattr(store.pg, "enabled", lambda: True) + assert await store.list_chunk_count("acme", NS, URI, 2, head) == 0 + assert not world.calls + + +@pytest.mark.parametrize("head", [None, Serving(True, 2, 2, 10), Serving(False, 3, 3, 10)]) +async def test_missing_or_mismatched_pg_count_proof_is_refused(world, monkeypatch, head): + monkeypatch.setattr(store.pg, "enabled", lambda: True) + with pytest.raises(ValueError): + await store.list_chunk_count("acme", NS, URI, 2, head) + assert not world.calls diff --git a/tests/unit/test_source_list_discovery.py b/tests/unit/test_source_list_discovery.py new file mode 100644 index 0000000000..0fbb1cb110 --- /dev/null +++ b/tests/unit/test_source_list_discovery.py @@ -0,0 +1,181 @@ +"""List metadata groups complete families before any cursor or public limit.""" + +from __future__ import annotations + +from unittest.mock import AsyncMock + +import pytest + +from server.knowledge.store import source_documents as store +from tests.unit.ch_fake import RecordingCH + +NS = "acl-" + "1" * 24 +SID = "11111111-1111-4111-8111-111111111111" +SOURCES = {(NS, SID): "team"} + + +async def test_ch_metadata_stream_groups_families_without_filtering_or_page_cap(monkeypatch): + monkeypatch.setattr(store.pg, "enabled", lambda: False) + row = { + "namespace": NS, + "source_uri": "gdrive:file#" + SID, + "public_namespace": "team", + "public_uri": "gdrive:file", + } + ch = RecordingCH().on("FROM loom.documents FINAL", [row]) + ch.install( + monkeypatch, + "server.knowledge.store.source_documents", + "server.knowledge.store.source_candidates", + ) + async with store.list_candidates("acme", SOURCES, ["anyone"]) as stream: + assert [r async for r in stream] == [row] + statement = ch.calls[-1] + assert statement.params["org"] == "acme" and statement.params["nss"] == [NS] + assert statement.params["bindings"] == [(NS, SID)] + assert statement.params["originals"] == ["team"] + assert "LIMIT" not in statement.sql and "OFFSET" not in statement.sql + assert "ORDER BY public_namespace, public_uri, namespace, source_uri" in statement.sql + assert "hasAny(access_keys" in statement.sql and "superseded_at IS NULL" in statement.sql + assert "content" not in statement.sql and "title" not in statement.sql + assert "FORMAT JSONEachRow" in statement.sql + + +async def test_pg_metadata_releases_bounded_page_before_admission_and_never_ch_coarse_acl( + monkeypatch, +): + monkeypatch.setattr(store.pg, "enabled", lambda: True) + row = { + "namespace": NS, + "source_uri": "gdrive:file#" + SID, + "public_namespace": "team", + "public_uri": "gdrive:file", + } + events = [] + + async def fetch(sql, *args): + assert args[:4] == ("acme", [NS], [SID], ["team"]) + assert args[4:] == ("", "", "", "") + assert "LIMIT 64" in sql and "NOT h.deleted" in sql + assert 'COLLATE "C"' in sql and "access_keys" not in sql + assert "h.row FROM" not in sql and "content" not in sql + events.extend(["open", "released"]) + return [row] + + monkeypatch.setattr(store.pg, "fetch", AsyncMock(side_effect=fetch)) + monkeypatch.setattr(store, "get_client", lambda: pytest.fail("No ClickHouse fallback")) + async with store.list_candidates("acme", SOURCES, ["untrusted-coarse-veto"]) as stream: + async for result in stream: + assert result == row + break + assert events == ["open", "released"] + assert events == ["open", "released"] + + +async def test_pg_discovery_reads_every_keyset_page_without_candidate_cutoff(monkeypatch): + monkeypatch.setattr(store.pg, "enabled", lambda: True) + rows = [ + { + "namespace": NS, + "source_uri": f"gdrive:{i:04d}#" + SID, + "public_namespace": "team", + "public_uri": f"gdrive:{i:04d}", + } + for i in range(130) + ] + fetch = AsyncMock(side_effect=[rows[:64], rows[64:128], rows[128:]]) + monkeypatch.setattr(store.pg, "fetch", fetch) + async with store.list_candidates("acme", SOURCES, None) as stream: + assert [r async for r in stream] == rows + assert fetch.await_count == 3 + for call, last in zip(fetch.await_args_list[1:], [rows[63], rows[127]], strict=True): + assert call.args[-4:] == tuple( + last[k] for k in ("public_namespace", "public_uri", "namespace", "source_uri") + ) + + +async def test_pg_discovery_rejects_nonadvancing_page_instead_of_looping(monkeypatch): + monkeypatch.setattr(store.pg, "enabled", lambda: True) + row = { + "namespace": NS, + "source_uri": "gdrive:file#" + SID, + "public_namespace": "team", + "public_uri": "gdrive:file", + } + monkeypatch.setattr(store.pg, "fetch", AsyncMock(return_value=[row, row])) + with pytest.raises(ValueError): + async with store.list_candidates("acme", SOURCES, None) as stream: + _ = [r async for r in stream] + + +@pytest.mark.parametrize("authority", ["clickhouse", "postgres"]) +async def test_ordinary_shadow_lookup_is_metadata_only_and_independent_of_cursor( + monkeypatch, authority +): + monkeypatch.setattr(store.pg, "enabled", lambda: authority == "postgres") + pairs = [("team", "gdrive:file"), ("other", "gdrive:second")] + rows = [{"namespace": "team", "source_uri": "gdrive:file"}] + ch = RecordingCH().on("FROM loom.documents FINAL", rows) + ch.install(monkeypatch, "server.knowledge.store.source_documents") + fetch = AsyncMock(return_value=rows) + monkeypatch.setattr(store.pg, "fetch", fetch) + assert await store.ordinary_families("acme", pairs) == {("team", "gdrive:file")} + sql = fetch.await_args.args[0] if authority == "postgres" else ch.calls[-1].sql + selected = sql.split("FROM", 1)[0] + assert "content" not in selected and "tags" not in selected and "title" not in selected + assert "ingested_at <" not in sql and "cursor" not in sql + assert "superseded_at" in sql + assert len(ch.calls) == 1 + + +async def test_ordinary_shadow_lookup_enforces_bounded_batch_before_any_io(monkeypatch): + monkeypatch.setattr(store, "get_client", lambda: pytest.fail("No oversized query")) + monkeypatch.setattr( + store.pg, "fetch", AsyncMock(side_effect=AssertionError("No oversized query")) + ) + with pytest.raises(ValueError): + await store.ordinary_families("acme", [("team", str(i)) for i in range(65)]) + + +@pytest.mark.parametrize("authority", ["clickhouse", "postgres"]) +async def test_unexpected_shadow_identity_is_refused(monkeypatch, authority): + monkeypatch.setattr(store.pg, "enabled", lambda: authority == "postgres") + rows = [{"namespace": "foreign", "source_uri": "gdrive:file"}] + ch = RecordingCH().on("FROM loom.documents FINAL", rows) + ch.install(monkeypatch, "server.knowledge.store.source_documents") + monkeypatch.setattr(store.pg, "fetch", AsyncMock(return_value=rows)) + with pytest.raises(ValueError): + await store.ordinary_families("acme", [("team", "gdrive:file")]) + + +async def test_pg_shadow_union_keeps_unheaded_published_and_unpublished_ordinary_copies( + monkeypatch, +): + monkeypatch.setattr(store.pg, "enabled", lambda: True) + ch = RecordingCH().on( + "FROM loom.documents FINAL", [{"namespace": "team", "source_uri": "published"}] + ) + ch.install(monkeypatch, "server.knowledge.store.source_documents") + monkeypatch.setattr( + store.pg, + "fetch", + AsyncMock(return_value=[{"namespace": "team", "source_uri": "head-only"}]), + ) + assert await store.ordinary_families( + "acme", [("team", "published"), ("team", "head-only")] + ) == {("team", "published"), ("team", "head-only")} + + +@pytest.mark.parametrize("include", [False, True]) +async def test_ordinary_tombstones_shadow_only_when_requested(monkeypatch, include): + monkeypatch.setattr(store.pg, "enabled", lambda: True) + ch = RecordingCH().on("FROM loom.documents FINAL", []) + ch.install(monkeypatch, "server.knowledge.store.source_documents") + fetch = AsyncMock(return_value=[]) + monkeypatch.setattr(store.pg, "fetch", fetch) + assert ( + await store.ordinary_families("acme", [("team", "file")], include_superseded=include) + == set() + ) + assert ("superseded_at IS NULL" in ch.calls[-1].sql) is not include + assert ("NOT h.deleted" in fetch.await_args.args[0]) is not include diff --git a/tests/unit/test_source_list_handler.py b/tests/unit/test_source_list_handler.py new file mode 100644 index 0000000000..24461850a0 --- /dev/null +++ b/tests/unit/test_source_list_handler.py @@ -0,0 +1,109 @@ +"""Public listing prepares access before I/O and merges complete public families.""" + +from __future__ import annotations + +from datetime import UTC, datetime, timedelta +from types import SimpleNamespace +from unittest.mock import AsyncMock + +import pytest + +from server.knowledge.api.models_knowledge import KnowledgeListInput +from server.knowledge.app import document_reads as app +from server.knowledge.app import source_access, source_listing +from server.knowledge.app.source_list_proofs import ListProofs +from server.knowledge.store import documents + + +@pytest.fixture +def world(monkeypatch): + calls = [] + state = SimpleNamespace(ordinary=[], mirrored=[], marked=True) + + def row(uri, stamp, *, namespace="team", title="Title"): + return { + "namespace": namespace, + "source_uri": uri, + "title": title, + "description": "Description", + "tags": ["wanted"], + "ingested_at": datetime(2025, 1, 1, tzinfo=UTC) + timedelta(seconds=stamp), + "superseded_at": None, + "chunk_count": stamp, + "content_preview": "Preview", + "blob_path": "", + "blob_size": 0, + "blob_content_type": "", + "original_filename": "", + } + + async def prepare(org, names): + calls.append("prepare") + assert (org, names) == ("acme", ["team"]) + return SimpleNamespace(org=org, marked=state.marked) + + async def ordinary(*args, **kwargs): + calls.append("ordinary") + return state.ordinary + + async def mirrored(*args, **kwargs): + calls.append("mirror") + assert kwargs["namespaces"] == ["team"] + return source_listing.Listing( + state.mirrored, ListProofs(source_access.ReadPlan("acme"), False, ()) + ) + + monkeypatch.setattr(app, "readable_namespaces", AsyncMock(return_value=["team"])) + monkeypatch.setattr(source_access, "prepare", AsyncMock(side_effect=prepare)) + monkeypatch.setattr(documents, "list_with_chunk_counts", AsyncMock(side_effect=ordinary)) + monkeypatch.setattr(source_listing, "collect", AsyncMock(side_effect=mirrored)) + return state, calls, row + + +async def test_prepare_precedes_ordinary_listing_then_checked_families_are_merged(world): + state, calls, row = world + state.ordinary = [row("ordinary", 80)] + state.mirrored = [row("mirror", 100)] + result = await app.handle_knowledge_list(KnowledgeListInput(org="acme", namespace="team")) + assert calls == ["prepare", "ordinary", "mirror"] + assert [(r.source_uri, r.chunk_count) for r in result.rows] == [ + ("mirror", 100), + ("ordinary", 80), + ] + + +async def test_ordinary_copy_wins_whole_family_before_limit_and_cursor(world): + state, _calls, row = world + state.ordinary = [row("same", 80, title="Ordinary")] + state.mirrored = [row("same", 100, title="Mirror"), row("other", 70)] + result = await app.handle_knowledge_list( + KnowledgeListInput(org="acme", namespace="team", limit=1) + ) + assert [(r.source_uri, r.title, r.chunk_count) for r in result.rows] == [ + ("same", "Ordinary", 80) + ] + assert result.next_cursor is not None + at, ns, uri = app._list_position(result.next_cursor, "acme", ["team"]) + assert (at.replace(tzinfo=UTC), ns, uri) == (state.ordinary[0]["ingested_at"], "team", "same") + + +async def test_public_field_projection_applies_after_merge_and_retains_cursor(world): + state, _calls, row = world + state.mirrored = [row("mirror", 100), row("next", 80)] + result = await app.handle_knowledge_list( + KnowledgeListInput(org="acme", namespace="team", limit=1, fields=["title"]) + ) + assert result.model_dump()["rows"] == [ + {"namespace": "team", "source_uri": "mirror", "title": "Title"} + ] + assert result.next_cursor is not None + + +async def test_unmarked_plan_preserves_ordinary_listing_and_skips_checked_leg(world): + state, calls, row = world + state.marked = False + state.ordinary = [row("ordinary", 80)] + result = await app.handle_knowledge_list(KnowledgeListInput(org="acme", namespace="team")) + assert [r.source_uri for r in result.rows] == ["ordinary"] + assert calls == ["prepare", "ordinary"] + source_listing.collect.assert_not_awaited() diff --git a/tests/unit/test_source_list_projection.py b/tests/unit/test_source_list_projection.py new file mode 100644 index 0000000000..6b7b45f48c --- /dev/null +++ b/tests/unit/test_source_list_projection.py @@ -0,0 +1,96 @@ +"""A list projection reads bounded fields from exactly one admitted live version.""" + +from __future__ import annotations + +import base64 +from datetime import UTC, datetime +from unittest.mock import AsyncMock + +import pytest + +from server.knowledge.store import source_documents as store +from tests.unit.ch_fake import RecordingCH + + +@pytest.fixture +def world(monkeypatch): + row = { + "org": "acme", + "namespace": "acl-" + "1" * 24, + "source_uri": "gdrive:file#11111111-1111-4111-8111-111111111111", + "version": 11, + "revision": 0, + "title": "Title", + "description": "Description", + "tags": ["kind:notes"], + "ingested_at": datetime(2025, 1, 1, tzinfo=UTC), + "superseded_at": None, + "blob_path": "", + "blob_size": 0, + "blob_content_type": "", + "original_filename": "", + "content_preview": "Preview", + } + monkeypatch.setattr(store.pg, "enabled", lambda: False) + ch = RecordingCH().on("FROM loom.documents FINAL", [row]) + ch.install(monkeypatch, "server.knowledge.store.source_documents") + return row, ch + + +async def test_clickhouse_projection_uses_materialized_preview_at_exact_identity(world): + row, ch = world + result = await store.list_projection("acme", row["namespace"], row["source_uri"], 11, 0) + assert result == row + statement = ch.calls[-1] + assert statement.params == { + "org": "acme", + "ns": row["namespace"], + "uri": row["source_uri"], + "version": 11, + "revision": 0, + } + assert "version = {version:UInt64}" in statement.sql + assert "revision = {revision:UInt64}" in statement.sql + assert "superseded_at IS NULL LIMIT 1" in statement.sql + selected = statement.sql.split(" FROM ")[0] + assert "content_preview" in selected + assert "substring(content" not in selected and ", content," not in selected + + +async def test_missing_clickhouse_projection_never_fetches_full_content(world, monkeypatch): + row, _ch = world + ch = RecordingCH().on("FROM loom.documents FINAL", []) + ch.install(monkeypatch, "server.knowledge.store.source_documents") + assert await store.list_projection("acme", row["namespace"], row["source_uri"], 11, 0) is None + assert len(ch.calls) == 1 + + +@pytest.mark.parametrize("preview", [b"Preview", "é".encode() * 109 + b"a\xc3", b"a\x00b"]) +async def test_postgres_projects_only_bounded_preview_and_preserves_other_fields( + world, monkeypatch, preview +): + row, ch = world + monkeypatch.setattr(store.pg, "enabled", lambda: True) + saved = {k: v for k, v in row.items() if k != "content_preview"} + saved["ingested_at"] = row["ingested_at"].isoformat() + saved["title"] = {"$loom_base64": base64.b64encode(b"a\x00b").decode()} + fetch = AsyncMock(return_value={"row": saved, "preview": base64.b64encode(preview).decode()}) + monkeypatch.setattr(store.pg, "fetchrow", fetch) + result = await store.list_projection("acme", row["namespace"], row["source_uri"], 11, 0) + assert result["content_preview"] == preview.decode("utf-8", "replace") + assert result["title"] == "a\x00b" and result["ingested_at"] == row["ingested_at"] + sql, *args = fetch.await_args.args + assert args == ["acme", row["namespace"], row["source_uri"], "11", 0, "0"] + assert "NOT h.deleted" in sql and "h.row ->> 'version' = $4" in sql + assert "h.revision = $5" in sql and "h.row ->> 'revision' = $6" in sql + assert "h.row FROM" not in sql and "SELECT h.row," not in sql + assert "for 220" in sql and "$loom_base64" in sql + assert not ch.calls + + +async def test_missing_postgres_head_never_falls_back_to_clickhouse(world, monkeypatch): + row, ch = world + monkeypatch.setattr(store.pg, "enabled", lambda: True) + monkeypatch.setattr(store.pg, "fetchrow", AsyncMock(return_value=None)) + assert await store.list_projection("acme", row["namespace"], row["source_uri"], 11, 0) is None + assert not ch.calls diff --git a/tests/unit/test_source_list_proofs.py b/tests/unit/test_source_list_proofs.py new file mode 100644 index 0000000000..3a9c45436b --- /dev/null +++ b/tests/unit/test_source_list_proofs.py @@ -0,0 +1,175 @@ +"""List proofs retain lookahead families and renew shadows before the final barrier.""" + +from __future__ import annotations + +import asyncio +from dataclasses import replace +from datetime import UTC, datetime +from types import SimpleNamespace +from unittest.mock import AsyncMock + +import pytest + +from server.knowledge.app.source_access import Admitted +from server.knowledge.app.source_corpus import LostCorpus +from server.knowledge.store import source_documents as store + +NS = "acl-" + "1" * 24 +SID = "11111111-1111-4111-8111-111111111111" + + +@pytest.fixture +def world(monkeypatch): + item = Admitted( + "team", + {"namespace": NS, "source_uri": "gdrive:file#" + SID}, + { + "namespace": NS, + "source_uri": "gdrive:file#" + SID, + "tags": ["source-id:" + SID], + "version": 10, + "revision": 0, + "ingested_at": datetime(2025, 1, 1, tzinfo=UTC), + }, + ) + events = [] + + async def documents(candidates): + events.append(("documents", len(candidates))) + return [ + replace(item, candidate=dict(candidate), document={**item.document, **candidate}) + for candidate in candidates + ] + + async def shadows(org, pairs, *, include_superseded): + assert org == "acme" and include_superseded + assert all(ns == "team" and "#" not in uri for ns, uri in pairs) + events.append(("shadows", len(pairs))) + return set() + + plan = SimpleNamespace( + org="acme", + failed=False, + unread=False, + current=lambda _: True, + current_evidence=lambda _: True, + check=AsyncMock(side_effect=documents), + ) + monkeypatch.setattr(store, "ordinary_families", AsyncMock(side_effect=shadows)) + return plan, item, events + + +def bundle(world, items=None): + from server.knowledge.app.source_list_proofs import ListProofs + + plan, item, _events = world + return ListProofs(plan, True, tuple([item] if items is None else items)) + + +async def test_shadow_barrier_uses_public_families_between_two_document_renewals(world): + proof = bundle(world) + await proof.check() + assert world[2] == [("documents", 1), ("shadows", 1), ("documents", 1)] + assert proof.fresh() and not proof.invalid + store.ordinary_families.assert_awaited_once_with( + "acme", [("team", "gdrive:file")], include_superseded=True + ) + + +async def test_all_selected_families_include_lookahead_and_use_bounded_shadow_batches(world): + _plan, item, events = world + items = [ + replace( + item, + candidate={**item.candidate, "source_uri": f"gdrive:{i}#" + SID}, + document={**item.document, "source_uri": f"gdrive:{i}#" + SID}, + ) + for i in range(129) + ] + proof = bundle(world, items) + await proof.check() + assert events == [ + (kind, size) for kind in ("documents", "shadows", "documents") for size in (64, 64, 1) + ] + assert proof.fresh() + + +@pytest.mark.parametrize("change", ["shadow", "backend", "denied", "expired"]) +async def test_any_lost_selected_family_invalidates_the_whole_list_monotonically(world, change): + plan, _item, _events = world + proof = bundle(world) + + async def changed(*_args, **_kwargs): + if change == "backend": + raise RuntimeError("private shadow backend") + if change == "denied": + plan.check.side_effect = None + plan.check.return_value = [] + if change == "expired": + plan.current = lambda _: False + return {("team", "gdrive:file")} if change == "shadow" else set() + + store.ordinary_families.side_effect = changed + with pytest.raises(LostCorpus, match="^document access changed$") as caught: + await proof.check() + assert proof.invalid and not proof.fresh() and not plan.unread + assert plan.failed == (change == "backend") + assert "private" not in str(caught.value) + calls = plan.check.await_count + with pytest.raises(LostCorpus): + await proof.check() + assert plan.check.await_count == calls + + +@pytest.mark.parametrize("phase", ["first_documents", "shadows", "last_documents"]) +async def test_unchecked_freshness_loss_prevents_an_inflight_initial_check_return(world, phase): + plan, _item, _events = world + proof = bundle(world) + entered, release = asyncio.Event(), asyncio.Event() + documents = plan.check.side_effect + calls = 0 + + async def pause(candidates): + nonlocal calls + calls += 1 + if phase == "first_documents" or (phase == "last_documents" and calls == 2): + entered.set() + await release.wait() + return await documents(candidates) + + async def shadow(*_args, **_kwargs): + if phase == "shadows": + entered.set() + await release.wait() + return set() + + plan.check.side_effect = pause + store.ordinary_families.side_effect = shadow + task = asyncio.create_task(proof.check()) + await entered.wait() + try: + assert not proof.fresh() + finally: + release.set() + results = await asyncio.gather(task, return_exceptions=True) + assert len(results) == 1 and isinstance(results[0], LostCorpus) + assert proof.invalid + + +async def test_cancelled_shadow_probe_propagates_and_cannot_certify_a_first_check(world): + proof = bundle(world) + store.ordinary_families.side_effect = asyncio.CancelledError + with pytest.raises(asyncio.CancelledError): + await proof.check() + assert not proof.fresh() + assert not world[0].failed and not world[0].unread + + +async def test_empty_ordinary_proof_needs_no_conditional_state_or_queries(world): + plan, _item, events = world + plan.failed = plan.unread = True + proof = bundle(world, []) + assert proof.fresh() + await proof.check() + assert proof.fresh() and events == [] + store.ordinary_families.assert_not_awaited() diff --git a/tests/unit/test_source_list_result.py b/tests/unit/test_source_list_result.py new file mode 100644 index 0000000000..14f2ecea9d --- /dev/null +++ b/tests/unit/test_source_list_result.py @@ -0,0 +1,230 @@ +"""Outer list renewal rebuilds a complete ordinary page and its cursor once.""" + +from __future__ import annotations + +import asyncio +from datetime import UTC, datetime, timedelta +from types import SimpleNamespace +from unittest.mock import AsyncMock, Mock + +import pytest + +from server.knowledge.api.models_knowledge import KnowledgeListInput +from server.knowledge.app import document_reads as app +from server.knowledge.app import source_access, source_listing +from server.knowledge.app.source_access import Admitted, ReadPlan +from server.knowledge.app.source_corpus import LostCorpus +from server.knowledge.app.source_list_proofs import ListProofs +from server.knowledge.domain.access_list import AccessList +from server.knowledge.store import documents, source_documents + +NS = "acl-" + "1" * 24 +SID = "11111111-1111-4111-8111-111111111111" + + +@pytest.fixture +def world(monkeypatch): + now = datetime(2025, 1, 1, tzinfo=UTC) + state = SimpleNamespace(allowed=True, marked=True, denied=set()) + plan = ReadPlan( + "acme", marked=True, sources={(NS, SID): "team"}, listing_starts={(NS, SID): now} + ) + monkeypatch.setattr(source_access, "now", lambda: now) + + def row(uri, stamp): + return { + "namespace": "team", + "source_uri": uri, + "title": uri, + "description": uri + " description", + "tags": [], + "ingested_at": now + timedelta(seconds=stamp), + "superseded_at": None, + "chunk_count": stamp, + "content_preview": uri + " preview", + } + + ordinary = [row(f"ordinary:{i}", 80 - i) for i in range(3)] + mirrored = [row(f"gdrive:{i}", 100 - i) for i in range(2)] + items = { + r["source_uri"] + "#" + SID: Admitted( + "team", + {"namespace": NS, "source_uri": r["source_uri"] + "#" + SID}, + { + **r, + "namespace": NS, + "source_uri": r["source_uri"] + "#" + SID, + "tags": ["source-id:" + SID], + "version": 10, + "revision": 0, + }, + AccessList(anyone=True), + ) + for r in mirrored + } + + async def check(candidates): + return ( + [ + items[r["source_uri"]] + for r in candidates + if r["source_uri"].split("#", 1)[0] not in state.denied + ] + if state.allowed + else [] + ) + + async def prepare(org, namespaces): + assert org == "acme" and namespaces == ["team"] + plan.marked = state.marked + return plan + + async def collect(actual, input, *, namespaces, cursor): + assert actual is plan and namespaces == ["team"] and cursor is None + if not state.allowed: + return source_listing.Listing([], ListProofs(plan, input.include_superseded, ())) + proofs = ListProofs(plan, input.include_superseded, tuple(items.values())) + await proofs.check() + return source_listing.Listing(mirrored, proofs) + + monkeypatch.setattr(plan, "check", AsyncMock(side_effect=check)) + monkeypatch.setattr(source_access, "prepare", AsyncMock(side_effect=prepare)) + monkeypatch.setattr(app, "readable_namespaces", AsyncMock(return_value=["team"])) + monkeypatch.setattr(documents, "list_with_chunk_counts", AsyncMock(return_value=ordinary)) + monkeypatch.setattr(source_documents, "ordinary_families", AsyncMock(return_value=set())) + monkeypatch.setattr(source_listing, "collect", AsyncMock(side_effect=collect)) + return state, plan, ordinary + + +def request(**kwargs): + return KnowledgeListInput(org="acme", namespace="team", limit=2, **kwargs) + + +@pytest.mark.parametrize("fields", [None, ["title"]]) +async def test_late_loss_restores_the_whole_ordinary_page_projection_and_cursor(world, fields): + state, _plan, ordinary = world + options = {"fields": fields} if fields is not None else {} + checked = await app.checked_knowledge_list(request(**options)) + assert [r.source_uri for r in checked.output.rows] == ["gdrive:0", "gdrive:1"] + mixed_cursor = checked.output.next_cursor + checked.output.rows[0].title = "Changed provisional title" + calls = documents.list_with_chunk_counts.await_count + state.allowed = False + first, second = await asyncio.gather(checked.current(), checked.current()) + assert first is second is await checked.current() is await checked.ordinary() + assert checked.lost and checked.proofs is None + assert documents.list_with_chunk_counts.await_count == calls + baseline = await app.handle_knowledge_list(request(**options)) + assert first.model_dump() == baseline.model_dump() + assert [r.source_uri for r in first.rows] == [r["source_uri"] for r in ordinary[:2]] + assert first.next_cursor is not None and first.next_cursor != mixed_cursor + + +async def test_forced_ordinary_reply_is_cached_and_never_readmits_still_valid_mirrors(world): + _state, plan, _ordinary = world + checked = await app.checked_knowledge_list(request()) + calls = plan.check.await_count + reply = await checked.ordinary() + assert checked.lost and checked.proofs is None + assert reply is await checked.current() is await checked.ordinary() + assert plan.check.await_count == calls + assert all(r.source_uri.startswith("ordinary:") for r in reply.rows) + + +async def test_an_initially_ordinary_result_needs_no_render_or_proof_retry(world, monkeypatch): + state, plan, _ordinary = world + state.allowed = False + checked = await app.checked_knowledge_list(request()) + render = Mock(side_effect=AssertionError("ordinary result already rendered")) + monkeypatch.setattr(app._ListRenderer, "render", render) + assert await checked.ordinary() is await checked.current() is checked.output + assert not checked.lost + plan.check.assert_not_awaited() + render.assert_not_called() + + +async def test_failed_fallback_cannot_return_the_old_private_page_or_retry(world, monkeypatch): + state, _plan, _ordinary = world + checked = await app.checked_knowledge_list(request()) + state.allowed = False + render = Mock(side_effect=RuntimeError("ordinary renderer failed")) + monkeypatch.setattr(app._ListRenderer, "render", render) + with pytest.raises(RuntimeError, match="ordinary renderer failed"): + await checked.current() + for method in (checked.current, checked.ordinary): + with pytest.raises(LostCorpus): + await method() + render.assert_called_once() + + +async def test_cancelled_renewal_propagates_without_returning_a_page(world): + _state, plan, _ordinary = world + checked = await app.checked_knowledge_list(request()) + plan.check.side_effect = asyncio.CancelledError + with pytest.raises(asyncio.CancelledError): + await checked.current() + assert not checked.lost and not plan.failed and not plan.unread + + +async def test_recipe_snapshots_inputs_and_executes_its_resolved_scope_without_resolving_again( + world, +): + _state, plan, _ordinary = world + original = request(fields=["title"], namespaces=["team"]) + recipe = await app.resolve_list(original) + original.namespaces.append("another-team") + original.fields.append("content_preview") + app.readable_namespaces.side_effect = AssertionError("scope already resolved") + result = await app.run_checked_list(recipe, plan) + assert recipe.namespaces == ("team",) and recipe.input.fields == ["title"] + assert set(result.output.model_dump()["rows"][0]) == {"namespace", "source_uri", "title"} + source_access.prepare.assert_not_awaited() + + +async def test_execution_refuses_another_orgs_plan_before_any_document_read(world): + recipe = await app.resolve_list(request()) + with pytest.raises(ValueError, match="document read scope changed"): + await app.run_checked_list(recipe, ReadPlan("another-org")) + documents.list_with_chunk_counts.assert_not_awaited() + source_listing.collect.assert_not_awaited() + + +async def test_unused_mirror_beyond_merged_page_and_lookahead_cannot_invalidate_page(world): + state, _plan, ordinary = world + ordinary[0]["ingested_at"] += timedelta(seconds=19, milliseconds=500) + checked = await app.checked_knowledge_list( + KnowledgeListInput(org="acme", namespace="team", limit=1) + ) + assert checked.output.rows[0].source_uri == "gdrive:0" and checked.output.next_cursor + state.denied.add("gdrive:1") + assert await checked.current() is checked.output + assert checked.output.rows[0].source_uri == "gdrive:0" and not checked.lost + + +async def test_private_cursor_lookahead_is_still_a_dependency(world): + state, _plan, _ordinary = world + checked = await app.checked_knowledge_list( + KnowledgeListInput(org="acme", namespace="team", limit=1) + ) + assert checked.output.rows[0].source_uri == "gdrive:0" and checked.output.next_cursor + state.denied.add("gdrive:1") + output = await checked.current() + assert checked.lost and output.rows[0].source_uri == "ordinary:0" + + +@pytest.mark.parametrize("shadow", [False, True]) +async def test_wholly_ordinary_page_and_cursor_retain_no_displaced_mirror(world, shadow): + state, plan, ordinary = world + if shadow: + ordinary[0]["source_uri"] = "gdrive:0" + for row in ordinary: + row["ingested_at"] += timedelta(seconds=100) + checked = await app.checked_knowledge_list(request()) + assert checked.proofs is None + assert [row.source_uri for row in checked.output.rows] == [ + row["source_uri"] for row in ordinary[:2] + ] + state.allowed = False + count = plan.check.await_count + assert await checked.current() is checked.output and not checked.lost + assert plan.check.await_count == count diff --git a/tests/unit/test_source_listing.py b/tests/unit/test_source_listing.py new file mode 100644 index 0000000000..f9cf17cab7 --- /dev/null +++ b/tests/unit/test_source_listing.py @@ -0,0 +1,447 @@ +"""Checked listing chooses complete families before filtering and pagination.""" + +from __future__ import annotations + +import asyncio +from contextlib import asynccontextmanager +from datetime import UTC, datetime, timedelta +from types import SimpleNamespace +from unittest.mock import AsyncMock + +import pytest + +from server.knowledge.api.models_knowledge import KnowledgeListInput +from server.knowledge.app import source_documents +from server.knowledge.app.source_access import Admitted +from server.knowledge.domain.serving import Serving + +NOW = datetime(2025, 1, 1, tzinfo=UTC) +NS = "acl-" + "1" * 24 +SID = "11111111-1111-4111-8111-111111111111" +OTHER_SID = "22222222-2222-4222-8222-222222222222" + + +@pytest.fixture +def world(monkeypatch): + state = SimpleNamespace( + docs={}, + allowed={}, + counts={}, + shadows=set(), + expired=False, + stream_error=None, + discovered=0, + conditional_error=False, + ) + sources = {(NS, SID): "team", (NS, OTHER_SID): "team"} + plan = SimpleNamespace( + org="acme", + marked=True, + failed=False, + unread=False, + discovery_sources=sources, + discovery_reader=None, + current=lambda _item: not state.expired, + ) + + def add(uri, stamp, *, source=SID, allowed=True, tags=("wanted",), title=None): + namespace, sid = NS, source + stored = uri + "#" + sid + row = { + "org": "acme", + "namespace": namespace, + "source_uri": stored, + "version": 10, + "revision": 0, + "title": title or stored, + "description": "Description", + "tags": ["source-id:" + sid, *tags], + "ingested_at": NOW + timedelta(seconds=stamp), + "superseded_at": None, + "blob_path": "", + "blob_size": 0, + "blob_content_type": "", + "original_filename": "", + "content_preview": "Preview", + } + key = (namespace, stored) + state.docs[key], state.allowed[key], state.counts[key] = row, allowed, stamp + return key + + async def check(candidates, *, chunks=False): + assert len(candidates) <= 64 and not chunks + if state.conditional_error: + raise RuntimeError("private permission backend") + return [ + Admitted( + sources[(key[0], key[1].rsplit("#", 1)[1])], + candidate, + dict(state.docs[key]), + serving=Serving(False, 0, 0, 9), + ) + for candidate in candidates + if (key := (candidate["namespace"], candidate["source_uri"])) in state.docs + and state.allowed[key] + ] + + @asynccontextmanager + async def discovery(org, selected, coarse): + assert org == "acme" and selected and selected.items() <= sources.items() + + async def rows(): + for ns, stored in sorted(state.docs, key=lambda key: (key[1].rsplit("#", 1)[0], *key)): + if (ns, stored.rsplit("#", 1)[1]) not in selected: + continue + state.discovered += 1 + yield { + "namespace": ns, + "source_uri": stored, + "public_namespace": sources[(ns, stored.rsplit("#", 1)[1])], + "public_uri": stored.rsplit("#", 1)[0], + } + if state.stream_error: + raise state.stream_error + + yield rows() + + async def projection(org, namespace, uri, version, revision): + key = (namespace, uri) + assert state.allowed[key], "No denied title or preview read" + row = state.docs[key] + assert (org, version, revision) == (row["org"], row["version"], row["revision"]) + return dict(row) + + async def count(org, namespace, uri, revision, serving): + assert org == "acme" and revision == 0 and serving == Serving(False, 0, 0, 9) + return state.counts[(namespace, uri)] + + async def shadows(org, pairs, *, include_superseded=False): + assert org == "acme" and len(pairs) <= 64 + return set(pairs) & state.shadows + + plan.check = AsyncMock(side_effect=check) + monkeypatch.setattr(source_documents.store.pg, "enabled", lambda: False) + monkeypatch.setattr(source_documents.store, "list_candidates", discovery) + monkeypatch.setattr( + source_documents.store, "list_projection", AsyncMock(side_effect=projection) + ) + monkeypatch.setattr(source_documents.store, "list_chunk_count", AsyncMock(side_effect=count)) + monkeypatch.setattr(source_documents.store, "ordinary_families", AsyncMock(side_effect=shadows)) + return state, plan, add + + +async def collect(world, *, cursor=None, **fields): + from server.knowledge.app import source_listing + + _state, plan, _add = world + return ( + await source_listing.collect( + plan, + KnowledgeListInput(org="acme", namespace="team", **fields), + namespaces=["team"], + cursor=cursor, + ) + ).rows + + +async def test_selection_reads_no_preview_or_chunk_count_before_title_projection(world): + from server.knowledge.app import source_listing + + _state, plan, add = world + add("gdrive:a", 10) + selected = await source_listing.select( + plan, KnowledgeListInput(org="acme", namespace="team", limit=1), None, namespaces=["team"] + ) + assert [item.candidate["source_uri"] for item in selected] == ["gdrive:a#" + SID] + source_documents.store.list_projection.assert_not_awaited() + source_documents.store.list_chunk_count.assert_not_awaited() + + +@pytest.mark.parametrize("source_id", [None, OTHER_SID]) +async def test_shared_plan_discovery_keeps_each_childs_resolved_namespace_scope(world, source_id): + from server.knowledge.app import source_listing + + state, plan, add = world + plan.discovery_sources[(NS, OTHER_SID)] = "another-team" + add("gdrive:ours", 10) + add("gdrive:other", 20, source=OTHER_SID) + selected = await source_listing.select( + plan, + KnowledgeListInput(org="acme", namespace="team", limit=2), + None, + namespaces=["team"], + source_id=source_id, + ) + assert [item.namespace for item in selected] == ([] if source_id else ["team"]) + assert state.discovered == (0 if source_id else 1) + + +async def test_source_selection_keeps_its_own_copy_despite_other_source_and_ordinary_copy(world): + from server.knowledge.app import source_listing + + state, plan, add = world + add("gdrive:a", 10, title="Requested source") + add("gdrive:a", 20, source=OTHER_SID, title="Another source") + state.shadows.add(("team", "gdrive:a")) + selected = await source_listing.select( + plan, + KnowledgeListInput(org="acme", namespace="team", limit=1), + None, + namespaces=["team"], + source_id=SID, + ) + assert [item.document["title"] for item in selected] == ["Requested source"] + assert len(plan.discovery_sources) == 2 and state.discovered == 1 + source_documents.store.ordinary_families.assert_not_awaited() + + +async def test_unknown_source_selection_opens_no_conditional_discovery(world): + from server.knowledge.app import source_listing + + state, plan, add = world + add("gdrive:a", 10) + assert ( + await source_listing.select( + plan, + KnowledgeListInput(org="acme", namespace="team"), + None, + namespaces=["team"], + source_id="unregistered", + ) + == [] + ) + assert state.discovered == 0 + plan.check.assert_not_awaited() + + +@pytest.mark.parametrize("source_id", [None, SID]) +async def test_final_selection_barrier_only_catalogs_apply_ordinary_shadows(world, source_id): + from server.knowledge.app import source_listing + + state, plan, add = world + add("gdrive:a", 10) + input = KnowledgeListInput(org="acme", namespace="team") + selected = await source_listing.select( + plan, input, None, namespaces=["team"], source_id=source_id + ) + state.shadows.add(("team", "gdrive:a")) + final = await source_listing.finish(plan, input, selected, source_id=source_id) + assert (final is not None) == (source_id is not None) + assert not plan.unread + + +async def test_family_winner_is_chosen_before_cursor_so_older_copy_never_reappears(world): + _state, _plan, add = world + add("gdrive:a", 100) + add("gdrive:a", 80, source=OTHER_SID) + add("gdrive:b", 90) + add("gdrive:c", 70) + first = await collect(world, limit=1) + assert [(r["source_uri"], r["chunk_count"]) for r in first] == [ + ("gdrive:a", 100), + ("gdrive:b", 90), + ] + second = await collect(world, limit=1, cursor=(NOW + timedelta(seconds=90), "team", "gdrive:b")) + assert [(r["source_uri"], r["chunk_count"]) for r in second] == [("gdrive:c", 70)] + + +async def test_family_winner_is_chosen_before_tags_without_mixing_copy_fields(world): + _state, _plan, add = world + add("gdrive:a", 100, tags=("other",), title="new copy") + add("gdrive:a", 80, source=OTHER_SID, tags=("wanted",), title="old copy") + assert await collect(world, tags=["wanted"]) == [] + [row] = await collect(world) + assert row["title"] == "new copy" and row["tags"] == ["other"] and row["chunk_count"] == 100 + + +async def test_denied_newest_copy_has_no_effect_on_admitted_copy_or_position(world): + _state, _plan, add = world + add("gdrive:a", 100, allowed=False) + add("gdrive:a", 80, source=OTHER_SID) + [row] = await collect(world, cursor=(NOW + timedelta(seconds=90), "team", "gdrive:z")) + assert row["chunk_count"] == 80 and row["source_uri"] == "gdrive:a" + + +async def test_more_than_six_thousand_denied_families_cannot_consume_page_or_lookahead(world): + state, _plan, add = world + for index in range(6000): + add(f"gdrive:{index:04d}", 100, allowed=False) + add("gdrive:z1", 90) + add("gdrive:z2", 80) + result = await collect(world, limit=1) + assert [row["source_uri"] for row in result] == ["gdrive:z1", "gdrive:z2"] + assert state.discovered == 6002 + assert source_documents.store.list_projection.await_count == 2 + + +async def test_ordinary_family_shadows_every_copy_before_page_filters(world): + state, _plan, add = world + add("gdrive:a", 100) + add("gdrive:a", 80, source=OTHER_SID) + add("gdrive:b", 70) + state.shadows.add(("team", "gdrive:a")) + [row] = await collect(world, limit=1, tags=["wanted"], include_superseded=True) + assert row["source_uri"] == "gdrive:b" + assert all( + call.kwargs["include_superseded"] + for call in source_documents.store.ordinary_families.await_args_list + ) + + +@pytest.mark.parametrize("change", ["permission", "version", "serving", "expired", "shadow"]) +async def test_late_change_to_returned_item_or_lookahead_invalidates_whole_mirror_leg( + world, change +): + state, plan, add = world + first = add("gdrive:a", 100) + add("gdrive:b", 80) + original = source_documents.store.list_chunk_count.side_effect + + async def count(*args): + result = await original(*args) + if source_documents.store.list_chunk_count.await_count == 2: + if change == "permission": + state.allowed[first] = False + elif change == "version": + state.docs[first]["version"] += 1 + elif change == "expired": + state.expired = True + elif change == "shadow": + state.shadows.add(("team", "gdrive:a")) + else: + check = plan.check.side_effect + + async def changed(*a, **k): + from dataclasses import replace + + return [ + replace(item, serving=Serving(False, 0, 0, 10)) + for item in await check(*a, **k) + ] + + plan.check.side_effect = changed + return result + + source_documents.store.list_chunk_count.side_effect = count + assert await collect(world, limit=1) == [] + assert not plan.unread + + +async def test_discovery_failure_marks_unread_and_never_reads_selected_fields(world, monkeypatch): + from server.core import request_work + + state, plan, add = world + add("gdrive:a", 100) + state.stream_error = RuntimeError("private candidate failure") + mark = [] + monkeypatch.setattr(request_work, "mark_mirrored", lambda **kwargs: mark.append(kwargs)) + assert await collect(world) == [] + assert plan.failed and plan.unread and mark == [{"unread": True}] + source_documents.store.list_projection.assert_not_awaited() + + +async def test_conditional_failure_keeps_all_fixed_discovery_but_does_not_mark_unread(world): + state, plan, add = world + for index in range(130): + add(f"gdrive:{index:04d}", 100) + state.conditional_error = True + assert await collect(world) == [] + assert state.discovered == 130 and plan.failed and not plan.unread + source_documents.store.list_projection.assert_not_awaited() + + +async def test_no_admitted_copy_has_exact_empty_leg_without_projection_or_count(world): + _state, _plan, add = world + add("gdrive:a", 100, allowed=False) + assert await collect(world) == [] + source_documents.store.list_projection.assert_not_awaited() + source_documents.store.list_chunk_count.assert_not_awaited() + + +async def test_cancellation_propagates_without_unread(world): + state, plan, add = world + add("gdrive:a", 100) + state.stream_error = asyncio.CancelledError() + with pytest.raises(asyncio.CancelledError): + await collect(world) + assert not plan.unread + + +async def test_native_fragment_uri_and_public_tags_are_projected_only_from_admitted_copy(world): + _state, _plan, add = world + add("gdrive:a#native", 100, tags=("wanted", "second")) + [row] = await collect( + world, uri_prefix=["gdrive:a#"], tags=["WANTED", "SECOND"], tags_every=True + ) + assert row["namespace"] == "team" and row["source_uri"] == "gdrive:a#native" + assert row["tags"] == ["wanted", "second"] + + +async def test_empty_uri_prefix_does_not_override_a_nonempty_filter(world): + _state, _plan, add = world + add("gdrive:wanted", 100) + add("gdrive:unrelated", 80) + assert [ + row["source_uri"] for row in await collect(world, uri_prefix=["", "gdrive:wanted"]) + ] == ["gdrive:wanted"] + assert {row["source_uri"] for row in await collect(world, uri_prefix=[""])} == { + "gdrive:wanted", + "gdrive:unrelated", + } + + +@pytest.mark.parametrize( + "field", + ["org", "namespace", "source_uri", "version", "revision", "ingested_at", "superseded_at"], +) +async def test_wrong_projection_identity_invalidates_whole_mirror_leg(world, field): + _state, plan, add = world + add("gdrive:a", 100) + original = source_documents.store.list_projection.side_effect + + async def changed(*args): + row = await original(*args) + row[field] = "other" + return row + + source_documents.store.list_projection.side_effect = changed + assert await collect(world) == [] and not plan.unread + + +@pytest.mark.parametrize("failure", ["projection", "count", "shadow"]) +async def test_conditional_io_failure_has_no_unread_or_partial_page(world, failure): + state, plan, add = world + for i in range(130): + add(f"gdrive:{i:04d}", 100) + target = { + "projection": "list_projection", + "count": "list_chunk_count", + "shadow": "ordinary_families", + }[failure] + getattr(source_documents.store, target).side_effect = RuntimeError("private backend detail") + assert await collect(world) == [] and plan.failed and not plan.unread + assert state.discovered == 130 + + +async def test_already_failed_conditional_plan_keeps_fixed_discovery(world): + state, plan, add = world + add("gdrive:a", 100) + plan.failed = True + assert await collect(world) == [] and state.discovered == 1 + plan.check.assert_not_awaited() + + +async def test_invalid_admitted_metadata_is_conditional_without_unread(world): + state, plan, add = world + key = add("gdrive:a", 100) + state.docs[key]["tags"] = None + assert await collect(world) == [] and plan.failed and not plan.unread + + +async def test_selected_field_cancellation_propagates_without_unread(world): + _state, plan, add = world + add("gdrive:a", 100) + source_documents.store.list_projection.side_effect = asyncio.CancelledError() + with pytest.raises(asyncio.CancelledError): + await collect(world) + assert not plan.failed and not plan.unread diff --git a/tests/unit/test_source_outline_handler.py b/tests/unit/test_source_outline_handler.py new file mode 100644 index 0000000000..d84a83a049 --- /dev/null +++ b/tests/unit/test_source_outline_handler.py @@ -0,0 +1,117 @@ +"""Outlines project one checked copy and preserve ordinary mining reads.""" + +from __future__ import annotations + +import json +from datetime import UTC, datetime +from types import SimpleNamespace +from unittest.mock import AsyncMock + +import pytest + +from server.knowledge.api.models_knowledge import KnowledgeOutlineInput +from server.knowledge.app import document_reads as app +from server.knowledge.app import source_access, source_documents +from server.knowledge.app.source_access import Admitted +from server.knowledge.app.source_search import Hydrated +from server.knowledge.store import chunks as chunk_store +from server.knowledge.store import documents + + +@pytest.fixture +def world(monkeypatch): + phases = [] + plan = SimpleNamespace(marked=True) + input = KnowledgeOutlineInput( + org="acme", namespace="team", source_uri="gdrive:file#native", section_path=["Pending"] + ) + metadata = { + "namespace": "acl-" + "a" * 24, + "source_uri": input.source_uri, + "version": 1, + "revision": 0, + "ingested_at": datetime.now(UTC), + } + checked = source_documents.CheckedDocument( + Admitted("team", dict(metadata), dict(metadata)), SimpleNamespace(title="Checked title") + ) + chunk = Hydrated( + Admitted("team", {**metadata, "chunk_idx": 1, "doc_version": 1}, dict(metadata)), + { + "content": "Unembedded section.", + "chunk_metadata": json.dumps( + { + "section_path": ["Pending"], + "section_depth": 1, + "section_idx": 0, + "revision": 0, + } + ), + }, + ) + + async def prepare(*args): + phases.append("prepare") + return plan + + async def ordinary(*args): + phases.append("ordinary") + return None + + async def get(*args): + phases.append("checked_document") + return checked + + async def chunks(*args, **kwargs): + phases.append("checked_chunks") + return [chunk] + + monkeypatch.setattr(source_access, "prepare", AsyncMock(side_effect=prepare)) + monkeypatch.setattr(documents, "get_one", AsyncMock(side_effect=ordinary)) + monkeypatch.setattr(source_documents, "get", AsyncMock(side_effect=get)) + monkeypatch.setattr(source_documents, "chunks", AsyncMock(side_effect=chunks)) + monkeypatch.setattr(app, "get_embedder", lambda: SimpleNamespace(model_name="fixture")) + return input, plan, phases + + +async def test_outline_prepares_before_content_and_uses_checked_unembedded_sections(world): + input, _plan, phases = world + result = await app.handle_knowledge_outline(input) + assert result.found and result.title == "Checked title" and result.structured + assert result.chunk_count == 1 and result.section_content == "Unembedded section." + assert result.section_chunk_idxs == [1] and result.source_uri == input.source_uri + assert result.sections[0].path == ["Pending"] + assert phases == ["prepare", "ordinary", "checked_document", "checked_chunks"] + + +async def test_failed_checked_chunks_have_the_complete_missing_outline_reply(world): + input, plan, _phases = world + source_documents.chunks.side_effect = None + source_documents.chunks.return_value = None + failed = await app.handle_knowledge_outline(input) + plan.marked = False + absent = await app.handle_knowledge_outline(input) + assert failed.model_dump(mode="json") == absent.model_dump(mode="json") + assert not failed.found + + +async def test_valid_empty_checked_document_is_found(world): + input, _plan, _phases = world + source_documents.chunks.side_effect = None + source_documents.chunks.return_value = [] + result = await app.handle_knowledge_outline(input) + assert result.found and not result.structured and result.chunk_count == 0 + + +async def test_ordinary_outline_wins_as_a_complete_copy(world, monkeypatch): + input, _plan, phases = world + documents.get_one.side_effect = None + documents.get_one.return_value = SimpleNamespace(title="Ordinary title") + row = SimpleNamespace(chunk_idx=0, content="Ordinary section.", chunk_metadata="{}") + monkeypatch.setattr(chunk_store, "list_for_doc", AsyncMock(return_value=[row])) + monkeypatch.setattr(app.pg_serving, "keep_served", AsyncMock(return_value=([row], 0))) + result = await app.handle_knowledge_outline(input) + assert result.found and result.title == "Ordinary title" and result.chunk_count == 1 + source_documents.get.assert_not_awaited() + source_documents.chunks.assert_not_awaited() + assert phases == ["prepare"] diff --git a/tests/unit/test_source_pack_lifecycle.py b/tests/unit/test_source_pack_lifecycle.py new file mode 100644 index 0000000000..71c61956fc --- /dev/null +++ b/tests/unit/test_source_pack_lifecycle.py @@ -0,0 +1,152 @@ +"""A pack owns producer cancellation and freezes input before scope discovery.""" + +from __future__ import annotations + +import asyncio +from types import SimpleNamespace + +import pytest + +from server.core import request_work +from server.core.diagnostics import codes_only +from server.knowledge.app import knowledge_search, source_access +from server.memory.api.models_context import ContextPackInput +from server.memory.app import context_pack + + +@pytest.fixture +def world(monkeypatch): + token = request_work._current.set(None) + request_work.begin() + events = [] + state = SimpleNamespace(resolve_gate=None, resolve_entered=asyncio.Event(), marked=True) + + async def resolve(input): + state.resolve_entered.set() + events.append(("resolve", input.query)) + if state.resolve_gate is not None: + await state.resolve_gate.wait() + return knowledge_search.SearchRequest(input, (input.namespace, "other"), ()) + + async def prepare(org, namespaces): + events.append(("prepare", tuple(namespaces))) + if state.marked: + assert request_work.mark_mirrored() + return source_access.ReadPlan(org, marked=state.marked) + + def producer(name): + async def run(*args): + events.append((name, codes_only())) + return None + + return run + + monkeypatch.setattr(knowledge_search, "resolve_search", resolve) + monkeypatch.setattr(source_access, "prepare", prepare) + for name in ( + "_pack_working_memory", + "_pack_profile", + "_advisory_health", + "_pack_namespace_guide", + "_advisory_mentor", + "_pack_memory_stack", + "_pack_memories", + "_pack_procedures", + "_pack_knowledge", + "_pack_conversations", + "_pack_runs", + ): + monkeypatch.setattr(context_pack, name, producer(name)) + yield SimpleNamespace(events=events, state=state) + request_work._current.reset(token) + + +def request(): + return ContextPackInput( + org="acme", + namespace="docs", + agent="reader", + query="original", + situation="stack seed", + include_knowledge=True, + ) + + +async def test_input_is_frozen_before_the_scope_await(world, monkeypatch): + world.state.resolve_gate = asyncio.Event() + original = request() + observed = [] + + async def direct(st, resolved, plan): + observed.append( + ( + st.input.query, + st.input.situation, + st.input.agent, + resolved.input.query, + resolved.namespaces, + plan.marked, + ) + ) + return None + + monkeypatch.setattr(context_pack, "_pack_knowledge", direct) + task = asyncio.create_task(context_pack.handle_context_pack(original)) + try: + await asyncio.wait_for(world.state.resolve_entered.wait(), timeout=5) + original.query, original.situation, original.agent = "changed", "changed", "changed" + world.state.resolve_gate.set() + await asyncio.wait_for(task, timeout=5) + assert observed == [ + ("original", "stack seed", "reader", "original", ("docs", "other"), True) + ] + assert world.events[:2] == [("resolve", "original"), ("prepare", ("docs", "other"))] + finally: + task.cancel() + await asyncio.gather(task, return_exceptions=True) + + +async def test_every_sibling_starts_after_the_common_marked_preparation(world): + output = await context_pack.handle_context_pack(request()) + assert world.events[:2] == [("resolve", "original"), ("prepare", ("docs", "other"))] + providers = world.events[2:] + assert len(providers) == 11 and all(private is True for name, private in providers) + assert request_work.mirror_marked() and output.section_count == 0 + + +async def test_independently_canceled_producer_drains_siblings_before_escape(world, monkeypatch): + started, drained = asyncio.Event(), asyncio.Event() + owned_waiters = [] + + async def waiting(st): + owned_waiters.append(asyncio.current_task()) + started.set() + try: + await asyncio.Event().wait() + finally: + drained.set() + + async def canceled(st): + await asyncio.wait_for(started.wait(), timeout=5) + raise asyncio.CancelledError() + + monkeypatch.setattr(context_pack, "_pack_working_memory", waiting) + monkeypatch.setattr(context_pack, "_pack_profile", canceled) + try: + with pytest.raises(asyncio.CancelledError): + await asyncio.wait_for(context_pack.handle_context_pack(request()), timeout=5) + assert drained.is_set() + finally: + for task in owned_waiters: + task.cancel() + await asyncio.gather(*owned_waiters, return_exceptions=True) + + +async def test_scope_cancellation_never_starts_preparation_or_producers(world, monkeypatch): + async def canceled(input): + raise asyncio.CancelledError() + + monkeypatch.setattr(knowledge_search, "resolve_search", canceled) + with pytest.raises(asyncio.CancelledError): + await context_pack.handle_context_pack(request()) + assert world.events == [] diff --git a/tests/unit/test_source_pack_preparation.py b/tests/unit/test_source_pack_preparation.py new file mode 100644 index 0000000000..14f762e313 --- /dev/null +++ b/tests/unit/test_source_pack_preparation.py @@ -0,0 +1,126 @@ +"""A pack prepares every possible knowledge scope before sibling providers.""" + +from __future__ import annotations + +from types import SimpleNamespace + +import pytest + +from server.core import request_work +from server.core.diagnostics import codes_only +from server.knowledge.app import knowledge_search, source_access +from server.memory.api.models_context import ContextPackInput +from server.memory.app import context_pack + + +@pytest.fixture +def world(monkeypatch): + token = request_work._current.set(None) + request_work.begin() + events = [] + state = {"resolution_error": False, "marked": True} + + async def resolve(input): + events.append(("resolve", input.model_copy(deep=True), codes_only())) + if state["resolution_error"]: + raise ValueError("private resolution failure") + return knowledge_search.SearchRequest(input.model_copy(deep=True), ("docs", "other"), ()) + + async def prepare(org, namespaces): + assert org == "acme" + events.append(("prepare", tuple(namespaces), codes_only())) + if state["marked"]: + assert request_work.mark_mirrored() + return source_access.ReadPlan(org, marked=state["marked"]) + + async def gather(_state, *_prepared): + events.append(("providers", None, codes_only())) + return None, None + + monkeypatch.setattr(knowledge_search, "resolve_search", resolve) + monkeypatch.setattr(source_access, "prepare", prepare) + monkeypatch.setattr(context_pack, "_gather_sections", gather) + yield SimpleNamespace(state=state, events=events) + request_work._current.reset(token) + + +def request(sections, **changes): + return ContextPackInput( + org="acme", + namespace="docs", + agent="reader", + include_knowledge=True, + only_sections=sections, + **changes, + ) + + +@pytest.mark.parametrize( + "sections,query,situation,expected,resolve", + [ + (["knowledge"], "question", "different stack seed", ("docs", "other"), True), + (["memory_stack"], "", "different stack seed", ("docs",), False), + (["memory_stack"], "", "", ("docs",), False), + ( + ["knowledge", "memory_stack"], + "question", + "different stack seed", + ("docs", "other"), + True, + ), + ], +) +async def test_parent_prepares_fixed_union_before_any_sibling_provider( + world, sections, query, situation, expected, resolve +): + output = await context_pack.handle_context_pack( + request(sections, query=query, situation=situation) + ) + assert [event[0] for event in world.events] == ( + ["resolve", "prepare", "providers"] if resolve else ["prepare", "providers"] + ) + prepared = [event for event in world.events if event[0] == "prepare"] + assert len(prepared) == 1 and prepared[0][1] == expected + assert world.events[-1] == ("providers", None, True) + assert request_work.mirror_marked() + assert output.section_count == 0 and not output.rendered and not output.truncated + if resolve: + source = world.events[0][1] + assert source.query == query and source.namespace_scope == "all_mine" + assert source.rerank == "none" and source.namespaces == [] + + +@pytest.mark.parametrize( + "changes", + [ + {"include_knowledge": False}, + {"only_sections": ["profile"]}, + {"only_sections": ["knowledge"], "query": ""}, + ], +) +async def test_no_possible_knowledge_read_keeps_the_parent_unmarked(world, changes): + input = request(["knowledge", "memory_stack"], query="question").model_copy(update=changes) + output = await context_pack.handle_context_pack(input) + assert world.events == [("providers", None, False)] + assert not request_work.mirror_marked() + assert output.section_count == 0 and not output.rendered + + +async def test_direct_scope_failure_keeps_prepared_stack_and_unrelated_sections(world, caplog): + world.state["resolution_error"] = True + output = await context_pack.handle_context_pack( + request(["knowledge", "memory_stack"], query="question") + ) + assert [event[0] for event in world.events] == ["resolve", "prepare", "providers"] + assert world.events[1][1] == ("docs",) + assert world.events[-1] == ("providers", None, True) + assert output.section_count == 0 and "private resolution failure" not in caplog.text + + +async def test_ordinary_plan_keeps_provider_work_and_empty_output_unmarked(world): + world.state["marked"] = False + output = await context_pack.handle_context_pack(request(["knowledge"], query="question")) + assert [event[0] for event in world.events] == ["resolve", "prepare", "providers"] + assert world.events[-1] == ("providers", None, False) + assert not request_work.mirror_marked() + assert output.section_count == 0 and not output.rendered diff --git a/tests/unit/test_source_passages.py b/tests/unit/test_source_passages.py new file mode 100644 index 0000000000..867b76ec29 --- /dev/null +++ b/tests/unit/test_source_passages.py @@ -0,0 +1,261 @@ +"""Passage composition retains complete ordinary widths and terminal fallbacks.""" + +from __future__ import annotations + +import asyncio +from types import SimpleNamespace + +import pytest + +from server.knowledge.api.models_knowledge import ( + KnowledgeSearchInput, + KnowledgeSearchOutput, + _SearchHit, +) +from server.knowledge.app import knowledge_search, source_passages +from server.knowledge.app.knowledge_search import CheckedSearch, SearchRequest +from server.knowledge.app.source_access import ReadPlan +from server.knowledge.app.source_corpus import LostCorpus + + +def hit(name, *, noise=False): + return _SearchHit( + namespace="docs", + source_uri=name, + chunk_idx=0, + content=name, + tags=[], + distance=0.2, + similarity=0.8, + noise=noise, + ) + + +def names(hits): + return [h.source_uri for h in hits] + + +@pytest.fixture +def world(monkeypatch): + state = SimpleNamespace( + queries=[], + first=[hit("private")], + wide=[hit("private-wide")], + first_ordinary=[hit("ordinary-first")], + wide_ordinary=[hit("ordinary-wide")], + children={}, + proofs={}, + render_calls=[], + render_gate=None, + render_entered=asyncio.Event(), + first_error=None, + wide_error=None, + wide_render_error=None, + revoke=False, + ) + + class Proof: + invalid = False + + async def check(self): + if state.revoke: + self.invalid = True + raise LostCorpus() + + def fresh(self): + return not self.invalid and not state.revoke + + class Renderer: + marked = True + + def __init__(self, width): + self.width = width + + async def render(self, rows, dropped): + state.render_calls.append(self.width) + state.render_entered.set() + if state.render_gate is not None: + await state.render_gate.wait() + if self.width > 2 and state.wide_render_error: + raise state.wide_render_error + values = state.first_ordinary if self.width == 2 else state.wide_ordinary + return KnowledgeSearchOutput(results=values, embedding_model="fake") + + async def run(request, plan): + state.queries.append(request) + width = request.input.top_k + error = state.first_error if width == 2 else state.wide_error + if error is not None: + raise error + values = state.first if width == 2 else state.wide + renderer = Renderer(width) + renderer.marked = plan.marked + proof = Proof() if plan.marked else None + checked = CheckedSearch( + KnowledgeSearchOutput(results=values, embedding_model="fake"), proof, renderer, [], 0 + ) + state.children[width], state.proofs[width] = checked, proof + return checked + + monkeypatch.setattr(knowledge_search, "run_checked_search", run) + return state + + +def request(): + return SearchRequest( + KnowledgeSearchInput( + org="acme", + namespace="docs", + query="question", + top_k=2, + namespace_scope="all_mine", + rerank="none", + tags=["hard"], + ), + ("docs", "other"), + ("unread",), + ) + + +async def collect(world, *, marked=True): + return await source_passages.collect( + request(), ReadPlan("acme", marked=marked), "reader", keep=lambda h: not h.noise + ) + + +@pytest.mark.parametrize("values", [[], [hit("private")], [hit("private", noise=True)]]) +async def test_marked_work_keeps_true_k_and_wide_queries_even_without_a_drop(world, values): + world.first = values + checked = await collect(world) + assert [q.input.top_k for q in world.queries] == [2, 8] + assert all( + q.namespaces == ("docs", "other") + and q.skipped == ("unread",) + and q.input.tags == ["hard"] + and q.input.rerank == "none" + for q in world.queries + ) + assert names(await checked.current()) == ( + ["private-wide"] if values and values[0].noise else names(values) + ) + assert checked.marked and not checked.lost + + +@pytest.mark.parametrize("dropped,expected", [(False, [2]), (True, [2, 8])]) +async def test_unmarked_widening_stays_lazy(world, dropped, expected): + world.first = [hit("first", noise=dropped)] + checked = await collect(world, marked=False) + assert [q.input.top_k for q in world.queries] == expected + assert names(await checked.current()) == (["private-wide"] if dropped else ["first"]) + assert [q.input.top_k for q in world.queries] == expected + assert not checked.marked + + +async def test_loss_reselects_both_complete_saved_ordinary_widths(world): + world.first = [hit("private")] + world.first_ordinary = [hit("ordinary-noise", noise=True), hit("ordinary-k")] + world.wide_ordinary = [hit("ordinary-w1"), hit("ordinary-w2")] + checked = await collect(world) + assert names(checked.hits) == ["private"] + world.revoke = True + assert names(await checked.current()) == ["ordinary-w1", "ordinary-w2"] + assert checked.lost and checked.fresh() + assert world.render_calls == [2, 8] + assert names(await checked.current()) == ["ordinary-w1", "ordinary-w2"] + assert names(await checked.ordinary()) == ["ordinary-w1", "ordinary-w2"] + assert world.render_calls == [2, 8] + assert [q.input.top_k for q in world.queries] == [2, 8] + + +async def test_unused_wide_proof_loss_still_forces_the_complete_ordinary_pair(world): + checked = await collect(world) + world.proofs[8].invalid = True + assert names(await checked.current()) == ["ordinary-first"] + assert checked.lost and world.render_calls == [2, 8] + + +async def test_first_failure_is_not_rescued_by_a_wide_pass(world): + world.first_error = ValueError("first failed") + with pytest.raises(ValueError, match="first failed"): + await collect(world) + assert [q.input.top_k for q in world.queries] == [2] + + +async def test_optional_wide_failure_does_not_retry_or_replace_first(world): + world.first = [hit("keep"), hit("noise", noise=True)] + world.wide_error = ValueError("wide failed") + checked = await collect(world) + assert names(await checked.current()) == ["keep"] + assert names(await checked.current()) == ["keep"] + assert [q.input.top_k for q in world.queries] == [2, 8] + + +async def test_optional_wide_ordinary_render_failure_keeps_first_and_is_not_retried(world): + world.first_ordinary = [hit("keep"), hit("noise", noise=True)] + checked = await collect(world) + world.revoke, world.wide_render_error = True, ValueError("wide render failed") + assert names(await checked.current()) == ["keep"] + assert names(await checked.ordinary()) == ["keep"] + assert world.render_calls == [2, 8] and checked.lost + + +async def test_pending_ordinary_fallback_is_never_fresh(world): + checked = await collect(world) + world.render_gate = asyncio.Event() + task = asyncio.create_task(checked.ordinary()) + try: + await asyncio.wait_for(world.render_entered.wait(), timeout=5) + assert not checked.fresh() + assert names(checked.hits) == ["private"] + world.render_gate.set() + assert names(await task) == ["ordinary-first"] + assert checked.fresh() and checked.lost + finally: + task.cancel() + await asyncio.gather(task, return_exceptions=True) + + +async def test_canceled_fallback_is_terminal_and_never_reuses_private_hits(world): + checked = await collect(world) + world.render_gate = asyncio.Event() + task = asyncio.create_task(checked.ordinary()) + try: + await asyncio.wait_for(world.render_entered.wait(), timeout=5) + task.cancel() + with pytest.raises(asyncio.CancelledError): + await task + assert not checked.fresh() + with pytest.raises(LostCorpus): + await checked.current() + with pytest.raises(LostCorpus): + await checked.ordinary() + assert world.render_calls == [2] + finally: + task.cancel() + await asyncio.gather(task, return_exceptions=True) + + +async def test_wide_collection_cancellation_propagates(world): + world.wide_error = asyncio.CancelledError() + with pytest.raises(asyncio.CancelledError): + await collect(world) + assert [q.input.top_k for q in world.queries] == [2, 8] + + +async def test_wrong_org_is_refused_before_any_child_work(world): + with pytest.raises(ValueError, match="scope changed"): + await source_passages.collect(request(), ReadPlan("other", marked=True), "reader") + assert world.queries == [] + + +async def test_failed_wide_collection_is_not_retried_when_access_is_later_lost(world): + world.first = [hit("keep"), hit("noise", noise=True)] + world.first_ordinary = [hit("ordinary-keep"), hit("ordinary-noise", noise=True)] + world.wide_error = ValueError("wide failed") + checked = await collect(world) + assert names(checked.hits) == ["keep"] + world.revoke = True + assert names(await checked.current()) == ["ordinary-keep"] + assert names(await checked.ordinary()) == ["ordinary-keep"] + assert [q.input.top_k for q in world.queries] == [2, 8] + assert world.render_calls == [2] and checked.lost and checked.fresh() diff --git a/tests/unit/test_source_proof_freshness.py b/tests/unit/test_source_proof_freshness.py new file mode 100644 index 0000000000..135a79cbe5 --- /dev/null +++ b/tests/unit/test_source_proof_freshness.py @@ -0,0 +1,254 @@ +"""Composed reads recheck every permission deadline after their last await.""" + +from __future__ import annotations + +import asyncio +from dataclasses import fields, replace +from datetime import UTC, datetime, timedelta +from types import SimpleNamespace +from unittest.mock import AsyncMock + +import pytest + +from server.auth.reader_identity import ReaderIdentity +from server.knowledge.app import source_access +from server.knowledge.app.source_corpus import LostCorpus, Proofs +from server.knowledge.app.source_search_proofs import SearchProofs +from server.knowledge.domain.access_list import AccessList +from server.knowledge.store import source_candidates +from server.settings import settings + +NS = "acl-" + "1" * 24 +SID = "11111111-1111-4111-8111-111111111111" +URI = "gdrive:file#" + SID + + +@pytest.fixture +def world(monkeypatch): + clock = SimpleNamespace(at=datetime(2025, 1, 1, tzinfo=UTC)) + monkeypatch.setattr(source_access, "now", lambda: clock.at) + monkeypatch.setattr(settings, "knowledge_source_acl_stale_seconds", 5) + reader = ReaderIdentity("lee", frozenset({"lee@example.com"}), frozenset({"example.com"})) + plan = source_access.ReadPlan( + "acme", + sources={(NS, SID): "team"}, + listing_starts={(NS, SID): clock.at}, + reader=reader, + marked=True, + _bindings=((NS, SID, "team"),), + ) + item = source_access.Admitted( + "team", + {"namespace": NS, "source_uri": URI, "chunk_idx": 0, "doc_version": 10, "revision": 0}, + { + "namespace": NS, + "source_uri": URI, + "tags": ["source-id:" + SID], + "version": 10, + "revision": 0, + "ingested_at": clock.at, + "content": "private body must not survive in permission evidence", + }, + AccessList(groups=("group@example.com",)), + groups=(("group@example.com", clock.at),), + reader_emails=reader.emails, + ) + monkeypatch.setattr(plan, "check", AsyncMock(return_value=[item])) + return clock, plan, item + + +async def test_first_bundle_expiry_while_another_checks_is_detected_without_another_await(world): + clock, plan, item = world + earlier, later = Proofs(plan, (item,)), Proofs(plan, (item,)) + await earlier.check() + clock.at += timedelta(seconds=4) + renewed = replace(item, groups=(("group@example.com", clock.at),)) + + async def check(_candidates): + clock.at += timedelta(seconds=2) + plan.listing_starts[(NS, SID)] = clock.at + return [renewed] + + plan.check.side_effect = check + await later.check() + assert later.fresh() + assert not earlier.fresh() + assert earlier.invalid and not later.invalid + calls = plan.check.await_count + clock.at -= timedelta(seconds=6) + assert not earlier.fresh() + with pytest.raises(LostCorpus): + await earlier.check() + assert plan.check.await_count == calls + + +@pytest.mark.parametrize("state", ["unchecked", "failed", "unread", "listing", "group", "email"]) +async def test_nonempty_freshness_refuses_unchecked_or_lost_evidence_monotonically(world, state): + clock, plan, item = world + proof = Proofs(plan, (item,)) + if state != "unchecked": + await proof.check() + if state in {"failed", "unread"}: + setattr(plan, state, True) + elif state == "listing": + plan.listing_starts.clear() + elif state == "group": + clock.at += timedelta(seconds=6) + plan.listing_starts[(NS, SID)] = clock.at + elif state == "email": + plan.reader = ReaderIdentity("lee", frozenset({"other@example.com"}), frozenset()) + assert not proof.fresh() + assert proof.invalid + plan.failed = plan.unread = False + plan.reader = ReaderIdentity("lee", item.reader_emails, frozenset()) + plan.listing_starts[(NS, SID)] = clock.at + assert not proof.fresh() + + +@pytest.mark.parametrize("arm", ["owner", "anyone", "emails", "domains"]) +async def test_group_expiry_keeps_each_independent_permission_arm(world, arm): + clock, plan, item = world + value = { + "owner": "owner-alias", + "anyone": True, + "emails": ("lee@example.com",), + "domains": ("example.com",), + }[arm] + item = replace( + item, + access=AccessList(groups=("group@example.com",), **{arm: value}), + canonical_owner="lee", + ) + plan.check.return_value = [item] + proof = Proofs(plan, (item,)) + await proof.check() + clock.at += timedelta(seconds=6) + plan.listing_starts[(NS, SID)] = clock.at + assert proof.fresh() and not proof.invalid + assert plan.current(item) + + +async def test_successful_renewal_replaces_the_immutable_permission_snapshot(world): + clock, plan, item = world + proof = Proofs(plan, (item,)) + await proof.check() + clock.at += timedelta(seconds=4) + plan.listing_starts[(NS, SID)] = clock.at + plan.check.return_value = [replace(item, groups=(("group@example.com", clock.at),))] + await proof.check() + clock.at += timedelta(seconds=2) + assert proof.fresh() + assert not plan.current(item) + + +async def test_permission_snapshot_does_not_retain_document_or_candidate_dictionaries(world): + _clock, plan, item = world + proof = Proofs(plan, (item,)) + await proof.check() + assert proof.fresh() + [evidence] = proof._evidence + assert {f.name for f in fields(evidence)} == { + "namespace", + "source_id", + "access", + "canonical_owner", + "groups", + "reader_emails", + } + item.document.clear() + item.candidate.clear() + assert proof.fresh() + + +async def test_empty_ordinary_proof_has_no_mirror_deadline_or_conditional_reads(world): + _clock, plan, _item = world + plan.failed = plan.unread = True + proof = Proofs(plan, ()) + assert proof.fresh() + await proof.check() + assert proof.fresh() and not proof.invalid + plan.check.assert_not_awaited() + + +async def test_search_freshness_uses_document_evidence_without_repeating_key_probes( + world, monkeypatch +): + clock, plan, item = world + key = (NS, URI, 0, 10, 0) + query = AsyncMock(return_value=[key]) + monkeypatch.setattr(source_candidates, "chunk_keys", query) + proof = SearchProofs(plan, "fake-model", (item,)) + await proof.check() + assert proof.fresh() + query.assert_awaited_once_with("acme", "fake-model", [key], embedded_only=True) + clock.at += timedelta(seconds=6) + assert not proof.fresh() and proof.invalid + query.assert_awaited_once() + + +def test_empty_search_freshness_remains_ordinary_only_with_a_failed_plan(world): + _clock, plan, _item = world + plan.failed = plan.unread = True + assert SearchProofs(plan, "", ()).fresh() + + +@pytest.mark.parametrize("search", [False, True]) +async def test_inflight_renewal_cannot_return_success_after_freshness_observes_loss( + world, monkeypatch, search +): + _clock, plan, item = world + entered, release = asyncio.Event(), asyncio.Event() + + async def wait(_candidates): + entered.set() + await release.wait() + return [item] + + plan.check.side_effect = wait + monkeypatch.setattr( + source_candidates, "chunk_keys", AsyncMock(return_value=[(NS, URI, 0, 10, 0)]) + ) + proof = SearchProofs(plan, "fake-model", (item,)) if search else Proofs(plan, (item,)) + task = asyncio.create_task(proof.check()) + await entered.wait() + assert not proof.fresh() + release.set() + with pytest.raises(LostCorpus): + await task + assert proof.invalid + + +@pytest.mark.parametrize("phase", ["keys", "final_documents"]) +async def test_search_is_unchecked_until_the_entire_initial_key_sequence_completes( + world, monkeypatch, phase +): + _clock, plan, item = world + entered, release = asyncio.Event(), asyncio.Event() + calls = 0 + + async def documents(_candidates): + nonlocal calls + calls += 1 + if phase == "final_documents" and calls == 2: + entered.set() + await release.wait() + return [item] + + async def keys(*_args, embedded_only=True): + if phase == "keys": + entered.set() + await release.wait() + return [(NS, URI, 0, 10, 0)] + + plan.check.side_effect = documents + monkeypatch.setattr(source_candidates, "chunk_keys", keys) + proof = SearchProofs(plan, "fake-model", (item,)) + task = asyncio.create_task(proof.check()) + await entered.wait() + try: + assert not proof.fresh() + finally: + release.set() + results = await asyncio.gather(task, return_exceptions=True) + assert len(results) == 1 and isinstance(results[0], LostCorpus) + assert proof.invalid diff --git a/tests/unit/test_source_publication_tail.py b/tests/unit/test_source_publication_tail.py new file mode 100644 index 0000000000..b574223323 --- /dev/null +++ b/tests/unit/test_source_publication_tail.py @@ -0,0 +1,316 @@ +"""Selected private answers renew after required writes and awaited headers.""" + +from __future__ import annotations + +import asyncio +from datetime import UTC, datetime +from types import SimpleNamespace +from unittest.mock import AsyncMock + +import pytest + +from server.auth.context import current_auth_var +from server.core import request_tail, request_work +from server.core.diagnostics import private_work +from server.knowledge.api.models_knowledge import ( + KnowledgeSearchInput, + KnowledgeSearchOutput, + _SearchHit, +) +from server.knowledge.app import knowledge_search, source_downloads +from server.knowledge.app.source_corpus import LostCorpus +from server.observability import events + + +@pytest.mark.parametrize("loss_at", ["write", "headers", "never"]) +async def test_search_publication_never_outlives_selected_access(monkeypatch, loss_at): + access = SimpleNamespace(live=True, checks=0, writes=0) + caller = object() + sent = [] + + async def check(): + assert current_auth_var.get() is caller + access.checks += 1 + if not access.live: + raise LostCorpus() + + proofs = SimpleNamespace(check=check, fresh=lambda: access.live, mirrored=True) + output = KnowledgeSearchOutput( + embedding_model="fake", + results=[ + _SearchHit( + source_uri="drive:private", + chunk_idx=0, + content="private-canary", + tags=[], + distance=0, + similarity=1, + ) + ], + ) + checked = knowledge_search.CheckedSearch(output, proofs, SimpleNamespace(marked=True), [], 0) + monkeypatch.setattr( + knowledge_search, "checked_knowledge_search", AsyncMock(return_value=checked) + ) + + async def insert(table, rows, *, settings, required_columns): + assert table == "loom.agent_events_private" and required_columns == frozenset( + {"mirror_marked"} + ) + await asyncio.sleep(0) + access.writes += 1 + if loss_at == "write": + access.live = False + + monkeypatch.setattr(events, "get_client", lambda: SimpleNamespace(insert=insert)) + monkeypatch.setattr(events, "stamp_row", lambda row: row) + monkeypatch.setattr(events, "for_this_cell", lambda event: event) + event = events.AgentEvent( + ts=datetime.fromtimestamp(0, UTC), + org="org", + namespace="team", + agent="reader", + user_id="user", + session_id="session", + operation="knowledge.search", + request_id="request", + latency_ms=1, + success=True, + kind="request", + mirror_marked=True, + ) + + async def write(): + with private_work(): + await events.write_marked_request_event(event) + + async def app(scope, receive, send): + token = request_work._current.set(None) + auth = current_auth_var.set(caller) + try: + request_work.begin() + assert request_work.mark_mirrored() + result = await knowledge_search.handle_knowledge_search( + KnowledgeSearchInput(org="org", namespace="team", query="document") + ) + assert request_tail.defer_required(write) + finally: + current_auth_var.reset(auth) + request_work._current.reset(token) + # Endpoint/dependency auth has unwound before the response is serialized. + assert current_auth_var.get() is not caller + await send({"type": "http.response.start", "status": 200, "headers": []}) + await send({"type": "http.response.body", "body": result.model_dump_json().encode()}) + + async def send(message): + sent.append(message) + await asyncio.sleep(0) + if message["type"] == "http.response.start" and loss_at == "headers": + access.live = False + + if loss_at == "never": + await request_tail.RequestTailMiddleware(app)({"type": "http"}, None, send) + assert b"private-canary" in sent[-1]["body"] + else: + with pytest.raises(request_tail.RequiredTailError): + await request_tail.RequestTailMiddleware(app)({"type": "http"}, None, send) + assert not any(b"private-canary" in message.get("body", b"") for message in sent) + assert len(sent) == (1 if loss_at == "headers" else 0) + assert access.writes == 1 + + +async def test_later_renewal_cannot_publish_after_an_earlier_proof_expires(): + live = [True] + sent = [] + + async def first(): + assert live[0] + + async def second(): + await asyncio.sleep(0) + live[0] = False + + async def app(scope, receive, send): + request_tail.retain_publication(object(), first, lambda: live[0]) + request_tail.retain_publication(object(), second, lambda: True) + await send({"type": "http.response.start", "status": 200, "headers": []}) + + with pytest.raises(request_tail.RequiredTailError): + await request_tail.RequestTailMiddleware(app)({"type": "http"}, None, sent.append) + assert sent == [] + + +@pytest.mark.parametrize("commit", [False, True]) +async def test_abandoned_nested_branch_does_not_keep_its_private_dependencies(commit): + checks = [] + + async def check(): + checks.append("selected") + + async def discarded(): + raise LostCorpus() + + async def app(scope, receive, send): + with request_tail.publication_group() as outer: + request_tail.retain_publication(object(), check, lambda: True) + with request_tail.publication_group(): + request_tail.retain_publication(object(), discarded, lambda: False) + if commit: + outer.commit() + await send({"type": "http.response.start", "status": 200, "headers": []}) + + async def send(_message): + pass + + await request_tail.RequestTailMiddleware(app)({"type": "http"}, None, send) + assert checks == (["selected"] if commit else []) + + +@pytest.mark.parametrize("failure", ["self_cancel", "timeout"]) +async def test_proof_failure_is_a_constant_refusal_and_joins_its_task(monkeypatch, failure): + ended = asyncio.Event() + + async def check(): + try: + if failure == "self_cancel": + raise asyncio.CancelledError() + await asyncio.Future() + finally: + ended.set() + + async def app(scope, receive, send): + request_tail.retain_publication(object(), check, lambda: True) + await send({"type": "http.response.start", "status": 200, "headers": []}) + + monkeypatch.setattr(request_tail, "REQUIRED_STEP_TIMEOUT_S", 0.01) + with pytest.raises( + request_tail.RequiredTailError, match="Required request work was not confirmed" + ): + await request_tail.RequestTailMiddleware(app)({"type": "http"}, None, None) + assert ended.is_set() + + +async def test_caller_cancellation_during_renewal_propagates_and_joins_proof(): + entered, ended = asyncio.Event(), asyncio.Event() + + async def check(): + try: + entered.set() + await asyncio.Future() + finally: + ended.set() + + async def app(scope, receive, send): + request_tail.retain_publication(object(), check, lambda: True) + await send({"type": "http.response.start", "status": 200, "headers": []}) + + pending = asyncio.create_task( + request_tail.RequestTailMiddleware(app)({"type": "http"}, None, None) + ) + await entered.wait() + pending.cancel() + with pytest.raises(asyncio.CancelledError): + await pending + assert ended.is_set() + + +@pytest.mark.parametrize("outcome", ["success", "failure", "cancel"]) +async def test_raw_download_marks_have_one_required_event_on_every_exit(monkeypatch, outcome): + captured, sent = [], [] + + async def write(event): + await asyncio.sleep(0) + captured.append(event) + + monkeypatch.setattr(events, "write_marked_request_event", write) + + async def app(scope, receive, send): + auth = current_auth_var.set(None) + try: + try: + with source_downloads.download_request("org", "team"): + assert request_work.mark_mirrored() + if outcome == "failure": + raise ValueError("private-backend-detail") + if outcome == "cancel": + raise asyncio.CancelledError() + except ValueError: + pass + await send({"type": "http.response.start", "status": 200, "headers": []}) + await send({"type": "http.response.body", "body": b"constant"}) + finally: + current_auth_var.reset(auth) + + async def send(message): + assert len(captured) == 1 + sent.append(message) + + if outcome == "cancel": + with pytest.raises(asyncio.CancelledError): + await request_tail.RequestTailMiddleware(app)({"type": "http"}, None, send) + assert not sent + else: + await request_tail.RequestTailMiddleware(app)({"type": "http"}, None, send) + assert len(captured) == 1 + event = captured[0] + assert (event.operation, event.org, event.namespace, event.transport) == ( + "knowledge.download", + "org", + "team", + "http", + ) + assert event.mirror_marked and event.success is (outcome == "success") + assert event.error_code == ("" if outcome == "success" else "REQUEST_INTERRUPTED") + assert "private-backend-detail" not in repr(event.args) + + +@pytest.mark.parametrize("later_chunk", [b"", b"still-private"]) +async def test_stream_completion_after_delivered_payload_keeps_next_request_usable(later_chunk): + from starlette.responses import Response, StreamingResponse + + live = True + checks = [] + sent = [] + + async def check(): + checks.append(live) + if not live: + raise LostCorpus() + + async def chunks(): + yield b"private-payload" + if later_chunk: + yield later_chunk + + async def app(scope, receive, send): + if scope["path"] == "/private": + request_tail.retain_publication(object(), check, lambda: live) + response = StreamingResponse( + chunks(), + headers={"content-length": str(len(b"private-payload") + len(later_chunk))}, + ) + else: + response = Response(b"ordinary") + await response(scope, receive, send) + + async def send(message): + nonlocal live + sent.append(message) + # A Content-Length client can start its next request after these bytes. + if message.get("body") == b"private-payload": + live = False + await asyncio.sleep(0) + + middleware = request_tail.RequestTailMiddleware(app) + scope = {"type": "http", "path": "/private", "asgi": {"spec_version": "2.4"}} + if later_chunk: + with pytest.raises(request_tail.RequiredTailError): + await middleware(scope, None, send) + assert not any(message.get("body") == later_chunk for message in sent) + assert checks == [True, True, False] + else: + await middleware(scope, None, send) + assert sent[-1] == {"type": "http.response.body", "body": b"", "more_body": False} + assert checks == [True, True] + await middleware({**scope, "path": "/ordinary"}, None, send) + assert sent[-1]["body"] == b"ordinary" diff --git a/tests/unit/test_source_push.py b/tests/unit/test_source_push.py new file mode 100644 index 0000000000..d58b3a9b0d --- /dev/null +++ b/tests/unit/test_source_push.py @@ -0,0 +1,610 @@ +"""Setup activation and sync hints stay bound across source lifecycle changes.""" + +from __future__ import annotations + +import dataclasses +import hashlib +import hmac +import json +import time +from contextlib import asynccontextmanager +from types import SimpleNamespace +from unittest.mock import AsyncMock + +import pytest + +from server.knowledge.api.models_source_push import ( + PushConfigureInput, + PushConfirmInput, + PushStatusInput, +) +from server.knowledge.app import source_push as app +from server.knowledge.domain.source_push import DeliveryRefused, PushRegistration +from server.knowledge.domain.sources import KnowledgeSource + + +@pytest.fixture +def env(monkeypatch: pytest.MonkeyPatch) -> SimpleNamespace: + state = SimpleNamespace( + src=KnowledgeSource( + org="org", namespace="docs", name="source", kind="notion", source_id="source-id" + ), + reg=None, + sync={}, + writes=[], + requests=[], + ready=True, + ) + monkeypatch.setattr(app.settings, "public_base_url", "https://loom.example") + monkeypatch.setattr(app.settings, "knowledge_source_push_enabled", True) + monkeypatch.setattr(app.settings, "jwt_secret", "source-push-test-root-" * 4) + monkeypatch.setattr(app.sources, "credential_of", lambda src: "credential") + + @asynccontextmanager + async def lease(*args: object, **kwargs: object): + yield + + @asynccontextmanager + async def renewal_lease(*args: object, **kwargs: object): + yield True + + @asynccontextmanager + async def fence(*args: object, **kwargs: object): + yield lambda uncertain: None + + async def get_source(*args: object, **kwargs: object): + return state.src + + async def get_reg(org: str, namespace: str, source_id: str, *, ch=None): + if ( + state.reg + and state.reg.org == org + and state.reg.namespace == namespace + and state.reg.source_id == source_id + ): + return state.reg + return None + + async def put(reg: PushRegistration, *, ch=None): + state.reg = reg + state.writes.append(reg) + + async def read_state(src: KnowledgeSource): + return state.sync + + async def update_state( + src: KnowledgeSource, previous: dict[str, str], changes: dict[str, object] + ): + state.requests.append((src, changes)) + detail = json.loads(state.sync.get("detail") or "{}") + state.sync = {"detail": json.dumps({**detail, **changes})} + + monkeypatch.setattr(app.sources, "sources_lease", lease) + monkeypatch.setattr(app.leases, "holding", renewal_lease) + monkeypatch.setattr(app, "fenced", fence) + monkeypatch.setattr(app.sources, "_source_or_404", get_source) + monkeypatch.setattr(app.source_store, "get_source", get_source) + monkeypatch.setattr(app.sources, "_require_served", lambda src: None) + monkeypatch.setattr(app.sources, "_require_source_namespace", AsyncMock()) + monkeypatch.setattr(app.sources, "_require_no_erasure", AsyncMock()) + monkeypatch.setattr(app.sources, "_read_state", read_state) + monkeypatch.setattr(app.sources, "_update_state", update_state) + monkeypatch.setattr(app.store, "get", get_reg) + monkeypatch.setattr(app.store, "put", put) + monkeypatch.setattr(app.machines, "fleet_at", AsyncMock(side_effect=lambda *args: state.ready)) + monkeypatch.setattr(app.notion, "workspace_id", AsyncMock(return_value="workspace")) + monkeypatch.setattr(app.linear, "organization_id", AsyncMock(return_value="organization")) + return state + + +async def setup_notion(env: SimpleNamespace) -> None: + await app.handle_configure(PushConfigureInput(org="org", namespace="docs", name="source")) + + +async def capture(env: SimpleNamespace, token: str = "verification-challenge") -> None: + await app.receive( + "org", + "docs", + "source-id", + env.reg.generation, + json.dumps({"verification_token": token}).encode(), + {}, + ) + + +async def activate(env: SimpleNamespace) -> None: + await capture(env) + await app.handle_confirm( + PushConfirmInput( + org="org", + namespace="docs", + name="source", + generation=env.reg.generation, + challenge_fingerprint=app.domain.challenge_fingerprint("verification-challenge"), + ) + ) + + +@pytest.mark.asyncio +async def test_notion_challenge_does_not_sync_or_activate_and_only_explicitly_reveals( + env: SimpleNamespace, +) -> None: + await setup_notion(env) + await capture(env) + normal = await app.handle_status(PushStatusInput(org="org", namespace="docs", name="source")) + assert normal.status == "pending" and normal.verification_token == "" + reveal = await app.handle_status( + PushStatusInput(org="org", namespace="docs", name="source", reveal_challenge=True) + ) + assert reveal.verification_token == "verification-challenge" + assert env.requests == [] + assert "verification-challenge" not in env.reg.secret_enc + with pytest.raises(DeliveryRefused, match="already captured"): + await capture(env, "attacker-replacement") + await activate(env) + assert env.reg.status == "active" + assert ( + await app.handle_status( + PushStatusInput(org="org", namespace="docs", name="source", reveal_challenge=True) + ) + ).verification_token == "" + + +@pytest.mark.asyncio +async def test_confirmation_requires_exact_generation_and_fingerprint(env: SimpleNamespace) -> None: + await setup_notion(env) + await capture(env) + for generation, fingerprint in ( + ("old", app.domain.challenge_fingerprint("verification-challenge")), + (env.reg.generation, "wrong"), + ): + with pytest.raises(app.ValidationError): + await app.handle_confirm( + PushConfirmInput( + org="org", + namespace="docs", + name="source", + generation=generation, + challenge_fingerprint=fingerprint, + ) + ) + assert env.reg.status == "pending" and not env.requests + + +@pytest.mark.asyncio +async def test_active_notion_only_records_one_hint_and_preserves_full_request( + env: SimpleNamespace, +) -> None: + await setup_notion(env) + await activate(env) + raw = json.dumps({"workspace_id": "workspace", "type": "page.content_updated"}).encode() + signature = "sha256=" + hmac.new(b"verification-challenge", raw, hashlib.sha256).hexdigest() + for _ in range(2): + await app.receive( + "org", "docs", "source-id", env.reg.generation, raw, {"x-notion-signature": signature} + ) + assert len(env.requests) == 1 + env.sync = {"detail": json.dumps({"requested_at": "earlier", "full": True, "cursor": "keep"})} + await app.receive( + "org", "docs", "source-id", env.reg.generation, raw, {"x-notion-signature": signature} + ) + assert json.loads(env.sync["detail"]) == { + "requested_at": "earlier", + "full": True, + "cursor": "keep", + } + with pytest.raises(DeliveryRefused): + await app.receive("org", "docs", "source-id", env.reg.generation, raw, {}) + + +@pytest.mark.asyncio +@pytest.mark.parametrize( + "change", ["removed", "replaced", "items", "retired", "other-org", "other-namespace"] +) +async def test_late_delivery_cannot_reach_changed_registration( + env: SimpleNamespace, change: str +) -> None: + await setup_notion(env) + generation = env.reg.generation + if change == "removed": + env.src = None + elif change == "replaced": + env.src = dataclasses.replace(env.src, source_id="replacement") + elif change == "items": + env.src = dataclasses.replace(env.src, items=[{"type": "page", "id": "new"}]) + elif change == "retired": + await app.retire(env.src) + before = len(env.writes) + with pytest.raises(DeliveryRefused): + await app.receive( + "other-org" if change == "other-org" else "org", + "other-docs" if change == "other-namespace" else "docs", + "source-id", + generation, + b'{"verification_token":"verification-challenge"}', + {}, + ) + assert not env.requests and len(env.writes) == before + + +@pytest.mark.asyncio +async def test_fleet_downgrade_refuses_unsigned_challenge_write(env: SimpleNamespace) -> None: + await setup_notion(env) + env.ready = False + with pytest.raises(app.BadConfigError): + await capture(env) + assert "challenge" not in app._secrets(env.reg) + + +@pytest.mark.asyncio +async def test_setup_requires_explicit_https_origin( + env: SimpleNamespace, monkeypatch: pytest.MonkeyPatch +) -> None: + for url in ( + "", + "http://loom.example", + "https://user:secret@loom.example", + "https://loom.example/path", + "https://[broken", + ): + monkeypatch.setattr(app.settings, "public_base_url", url) + with pytest.raises(app.BadConfigError): + await setup_notion(env) + assert not env.writes + + +@pytest.mark.asyncio +async def test_removal_during_drive_watch_cannot_reactivate( + env: SimpleNamespace, monkeypatch: pytest.MonkeyPatch +) -> None: + env.src = dataclasses.replace(env.src, kind="gdrive") + monkeypatch.setattr(app.gdrive, "parse_service_account", lambda key: object()) + monkeypatch.setattr(app.gdrive, "access_token", AsyncMock(return_value="token")) + monkeypatch.setattr(app.gdrive_push, "member_drives", AsyncMock(return_value=set())) + stopped = AsyncMock() + monkeypatch.setattr(app.gdrive_push, "stop", stopped) + + async def watch(*args: object, **kwargs: object): + await app.retire(env.src) + env.src = None + return { + "id": kwargs["channel_id"], + "token": kwargs["channel_token"], + "resource_id": "resource", + "expiration": time.time() + 3600, + "drive_id": "", + } + + monkeypatch.setattr(app.gdrive_push, "watch", watch) + with pytest.raises(DeliveryRefused): + await app.handle_configure(PushConfigureInput(org="org", namespace="docs", name="source")) + assert env.reg.status == "retired" and env.reg.secret_enc == "" + stopped.assert_awaited_once() + + +def test_pending_secret_read_cannot_enter_idempotency_replay_storage() -> None: + from server.knowledge.api.ops_source_push import OPERATIONS + + status = next(op for op in OPERATIONS if op.name.endswith(".push_status")) + assert not status.idempotent + + +def test_setup_audit_accepts_response_and_omits_secrets() -> None: + body = PushConfirmInput( + org="org", namespace="docs", name="source", generation="generation", signing_secret="secret" + ) + assert app.audit_subject(body, {"verification_token": "secret"}) == { + "org": "org", + "namespace": "docs", + "name": "source", + } + + +@pytest.mark.asyncio +async def test_reseal_rechecks_row_after_scanning_before_erasure( + env: SimpleNamespace, monkeypatch: pytest.MonkeyPatch +) -> None: + await setup_notion(env) + scanned = env.reg + pages = AsyncMock(side_effect=[[scanned], []]) + monkeypatch.setattr(app.store, "sealed_page", pages) + + @asynccontextmanager + async def erase_before_claim(*args: object, **kwargs: object): + env.reg = None + yield + + monkeypatch.setattr(app.sources, "sources_lease", erase_before_claim) + before = len(env.writes) + assert await app.reseal_registry(dry_run=False) == (0, []) + assert env.reg is None and len(env.writes) == before + + +@pytest.mark.asyncio +async def test_reseal_uses_current_generation_and_fleet_gate( + env: SimpleNamespace, monkeypatch: pytest.MonkeyPatch +) -> None: + await setup_notion(env) + scanned = env.reg + await setup_notion(env) + generation = env.reg.generation + monkeypatch.setattr(app.store, "sealed_page", AsyncMock(side_effect=[[scanned], []])) + monkeypatch.setattr(app, "resealed", lambda purpose, value: value) + assert await app.reseal_registry(dry_run=False) == (1, []) + assert env.reg.generation == generation + env.ready = False + monkeypatch.setattr(app.store, "sealed_page", AsyncMock(side_effect=[[env.reg], []])) + with pytest.raises(app.BadConfigError): + await app.reseal_registry(dry_run=False) + + +@pytest.mark.asyncio +async def test_lost_publication_ack_does_not_stop_current_drive_channels( + env: SimpleNamespace, monkeypatch: pytest.MonkeyPatch +) -> None: + env.src = dataclasses.replace(env.src, kind="gdrive") + monkeypatch.setattr(app.gdrive, "parse_service_account", lambda key: object()) + monkeypatch.setattr(app.gdrive, "access_token", AsyncMock(return_value="token")) + monkeypatch.setattr(app.gdrive_push, "member_drives", AsyncMock(return_value=set())) + stopped = AsyncMock() + monkeypatch.setattr(app.gdrive_push, "stop", stopped) + original_put = app.store.put + + async def uncertain_put(reg: PushRegistration, *, ch=None): + await original_put(reg, ch=ch) + if reg.status == "active": + raise ConnectionError("ack lost after commit") + + async def watch(*args: object, **kwargs: object): + return { + "id": kwargs["channel_id"], + "token": kwargs["channel_token"], + "resource_id": "resource", + "expiration": time.time() + 3600, + "drive_id": "", + } + + monkeypatch.setattr(app.store, "put", uncertain_put) + monkeypatch.setattr(app.gdrive_push, "watch", watch) + with pytest.raises(ConnectionError, match="ack lost"): + await app.handle_configure(PushConfigureInput(org="org", namespace="docs", name="source")) + assert env.reg.status == "active" and app._secrets(env.reg)["channels"] + stopped.assert_not_awaited() + + +@pytest.mark.asyncio +async def test_linear_prepares_stable_address_then_requires_exact_confirmation( + env: SimpleNamespace, +) -> None: + env.src = dataclasses.replace(env.src, kind="linear") + pending = await app.handle_configure( + PushConfigureInput(org="org", namespace="docs", name="source") + ) + assert pending.status == "pending" + assert pending.callback_url == ( + f"https://loom.example/hooks/knowledge/docs/source-id/{pending.generation}?org=org" + ) + generation = pending.generation + raw = json.dumps( + {"organizationId": "organization", "webhookTimestamp": int(time.time() * 1000)} + ).encode() + signature = hmac.new(b"signing-secret", raw, hashlib.sha256).hexdigest() + with pytest.raises(DeliveryRefused): + await app.receive( + "org", "docs", "source-id", generation, raw, {"linear-signature": signature} + ) + with pytest.raises(app.ValidationError): + await app.handle_confirm( + PushConfirmInput( + org="org", + namespace="docs", + name="source", + generation="old", + signing_secret="signing-secret", + ) + ) + active = await app.handle_confirm( + PushConfirmInput( + org="org", + namespace="docs", + name="source", + generation=generation, + signing_secret="signing-secret", + ) + ) + assert active.status == "active" and active.callback_url == pending.callback_url + await app.receive("org", "docs", "source-id", generation, raw, {"linear-signature": signature}) + assert len(env.requests) == 1 + + +@pytest.mark.asyncio +async def test_deployment_opt_out_refuses_setup( + env: SimpleNamespace, monkeypatch: pytest.MonkeyPatch +) -> None: + monkeypatch.setattr(app.settings, "knowledge_source_push_enabled", False) + with pytest.raises(app.BadConfigError): + await setup_notion(env) + assert not env.writes + + +@pytest.mark.asyncio +async def test_deployment_opt_out_refuses_existing_delivery( + env: SimpleNamespace, monkeypatch: pytest.MonkeyPatch +) -> None: + await setup_notion(env) + await activate(env) + monkeypatch.setattr(app.settings, "knowledge_source_push_enabled", False) + raw = json.dumps({"workspace_id": "workspace"}).encode() + signature = "sha256=" + hmac.new(b"verification-challenge", raw, hashlib.sha256).hexdigest() + with pytest.raises(DeliveryRefused): + await app.receive( + "org", "docs", "source-id", env.reg.generation, raw, {"x-notion-signature": signature} + ) + assert not env.requests + + +@pytest.mark.asyncio +@pytest.mark.parametrize("origin", ["", "https://[broken"]) +async def test_paused_setup_can_be_inspected_and_disabled_without_public_origin( + env: SimpleNamespace, monkeypatch: pytest.MonkeyPatch, origin: str +) -> None: + await setup_notion(env) + monkeypatch.setattr(app.settings, "knowledge_source_push_enabled", False) + monkeypatch.setattr(app.settings, "public_base_url", origin) + status = await app.handle_status(PushStatusInput(org="org", namespace="docs", name="source")) + assert not status.enabled and status.callback_url == "" and status.status == "pending" + disabled = await app.handle_configure( + PushConfigureInput(org="org", namespace="docs", name="source", enabled=False) + ) + assert disabled.status == "disabled" and env.reg.secret_enc == "" + + +@pytest.mark.asyncio +async def test_provider_and_channel_cleanup_read_configured_timeouts( + env: SimpleNamespace, monkeypatch: pytest.MonkeyPatch +) -> None: + waits = [] + + @asynccontextmanager + async def timeout(seconds: float): + waits.append(seconds) + yield + + monkeypatch.setattr(app.asyncio, "timeout", timeout) + monkeypatch.setattr(app.settings, "knowledge_source_push_provider_timeout_s", 17.0) + monkeypatch.setattr(app.settings, "knowledge_source_push_stop_timeout_s", 1.25) + monkeypatch.setattr(app.settings, "knowledge_source_push_cleanup_timeout_s", 3.0) + await setup_notion(env) + assert waits == [17.0] + env.src = dataclasses.replace(env.src, kind="gdrive") + env.reg = dataclasses.replace(env.reg, provider="gdrive") + monkeypatch.setattr(app.gdrive, "parse_service_account", lambda key: object()) + monkeypatch.setattr(app.gdrive, "access_token", AsyncMock(return_value="token")) + monkeypatch.setattr(app.gdrive_push, "member_drives", AsyncMock(return_value=set())) + monkeypatch.setattr( + app.gdrive_push, + "watch", + AsyncMock( + return_value={ + "id": "created", + "token": "channel-token", + "resource_id": "resource", + "expiration": time.time() + 3600, + "drive_id": "", + } + ), + ) + stopped = AsyncMock() + monkeypatch.setattr(app.gdrive_push, "stop", stopped) + await app._renew_drive(env.reg, initial=True) + assert waits == [17.0, 17.0, 3.0] + await app._stop_channels("token", [{"id": "superseded"}]) + assert waits == [17.0, 17.0, 3.0, 1.25] + stopped.assert_awaited_once_with("token", {"id": "superseded"}) + + +@pytest.mark.parametrize( + "overrides,error", + [ + ({"knowledge_source_push_stop_timeout_s": 6.0}, "STOP_TIMEOUT_S"), + ({"knowledge_source_push_provider_timeout_s": 60.0}, "renewal work window"), + ({"knowledge_source_push_max_pass_seconds": 50.0}, "MAX_PASS_SECONDS"), + ], +) +def test_push_budgets_refuse_cleanup_or_attempt_outside_deadline( + overrides: dict[str, float], error: str +) -> None: + from pydantic import ValidationError + + from server.settings.catalog import KnowledgeSettings + + with pytest.raises(ValidationError, match=error): + KnowledgeSettings(**overrides) + + +def test_push_budgets_accept_configured_deadlines() -> None: + from server.settings.catalog import KnowledgeSettings + + configured = KnowledgeSettings( + knowledge_source_push_provider_timeout_s=36.0, + knowledge_source_push_stop_timeout_s=3.0, + knowledge_source_push_cleanup_timeout_s=6.0, + knowledge_source_push_max_pass_seconds=180.0, + ) + assert configured.knowledge_source_push_provider_timeout_s == 36.0 + assert configured.knowledge_source_push_stop_timeout_s == 3.0 + assert configured.knowledge_source_push_cleanup_timeout_s == 6.0 + assert configured.knowledge_source_push_max_pass_seconds == 180.0 + + +def test_push_budget_boundary_matches_the_actual_renewal_lease_window( + monkeypatch: pytest.MonkeyPatch, +) -> None: + from pydantic import ValidationError + + from server.settings.catalog import KnowledgeSettings + + monkeypatch.setattr(app.leases, "time", SimpleNamespace(monotonic=lambda: 100.0)) + lease = app.leases.Lease("push-budget", ttl_s=120, ch=object(), holder="budget-test") + lease._renewed = 100.0 + work_window = app.leases.work_left(lease, 120) + assert work_window == 48.0 + with pytest.raises(ValidationError, match="renewal work window"): + KnowledgeSettings( + knowledge_source_push_provider_timeout_s=40.0, + knowledge_source_push_cleanup_timeout_s=work_window - 40.0, + ) + configured = KnowledgeSettings( + knowledge_source_push_provider_timeout_s=40.0, + knowledge_source_push_cleanup_timeout_s=work_window - 41.0, + ) + assert configured.knowledge_source_push_cleanup_timeout_s == 7.0 + + +@pytest.mark.asyncio +@pytest.mark.parametrize("namespace", ["docs", "other-docs", "missing"]) +async def test_registry_lookup_requires_the_namespace_key(namespace: str) -> None: + from server.knowledge.store import source_push + + rows = [ + PushRegistration( + org="org", + namespace=ns, + name="source", + source_id="shared-id", + provider="notion", + generation=ns, + fingerprint="fp", + secret_enc=ns, + ) + for ns in ("docs", "other-docs") + ] + + class Ch: + async def query_one(self, sql: str, params: dict[str, str]): + assert "org = {org:String} AND namespace = {ns:String}" in sql + assert "source_id = {source:String}" in sql + assert params == {"org": "org", "ns": namespace, "source": "shared-id"} + return next( + (dataclasses.asdict(row) for row in rows if row.namespace == params["ns"]), None + ) + + result = await source_push.get("org", namespace, "shared-id", ch=Ch()) + assert result == next((row for row in rows if row.namespace == namespace), None) + + +@pytest.mark.asyncio +@pytest.mark.parametrize("scan", ["drive_page", "sealed_page"]) +async def test_registry_maintenance_cursor_follows_the_namespace_key(scan: str) -> None: + from server.knowledge.store import source_push + + after = ("org", "docs", "shared-id") + + class Ch: + async def query_all(self, sql: str, params: dict[str, tuple[str, str, str]]): + assert "(org, namespace, source_id) > {after:Tuple(String, String, String)}" in sql + assert "ORDER BY org, namespace, source_id LIMIT" in sql + assert params == {"after": after} + return [] + + assert await getattr(source_push, scan)(after, ch=Ch()) == [] diff --git a/tests/unit/test_source_push_proofs.py b/tests/unit/test_source_push_proofs.py new file mode 100644 index 0000000000..b03fce4772 --- /dev/null +++ b/tests/unit/test_source_push_proofs.py @@ -0,0 +1,73 @@ +"""Provider proof is checked over raw bytes and the signed provider scope.""" + +from __future__ import annotations + +import hashlib +import hmac +import json + +import pytest + +from server.knowledge.domain import source_push as push + + +def signed(body: dict[str, object], *, prefix: str = "") -> tuple[bytes, str]: + raw = json.dumps(body, indent=2).encode() + return raw, prefix + hmac.new(b"secret", raw, hashlib.sha256).hexdigest() + + +def test_linear_requires_signed_timestamp_and_organization() -> None: + raw, signature = signed({"organizationId": "org", "webhookTimestamp": 1_000_000}) + push.verify_linear(raw, signature, "secret", "org", now=1000) + for kwargs in ( + {"now": 1061, "organization_id": "org"}, + {"now": 1000, "organization_id": "other"}, + ): + with pytest.raises(push.DeliveryRefused): + push.verify_linear(raw, signature, "secret", **kwargs) + with pytest.raises(push.DeliveryRefused): + push.verify_linear(raw + b" ", signature, "secret", "org", now=1000) + + +@pytest.mark.parametrize("stamp", [True, "1000000", None, float("nan"), float("inf"), 10**1000]) +def test_linear_refuses_invalid_signed_clock(stamp: object) -> None: + raw, signature = signed({"organizationId": "org", "webhookTimestamp": stamp}) + with pytest.raises(push.DeliveryRefused): + push.verify_linear(raw, signature, "secret", "org", now=1000) + + +def test_notion_checks_raw_body_workspace_and_prefix() -> None: + raw, signature = signed({"workspace_id": "space"}, prefix="sha256=") + push.verify_notion(raw, signature, "secret", "space") + for body, proof, workspace in ( + (raw + b" ", signature, "space"), + (raw, signature[7:], "space"), + (raw, signature, "other"), + ): + with pytest.raises(push.DeliveryRefused): + push.verify_notion(body, proof, "secret", workspace) + + +def test_drive_requires_whole_active_channel_binding() -> None: + channel = {"id": "id", "token": "secret", "resource_id": "resource", "expiration": 1100} + headers = { + "x-goog-channel-id": "id", + "x-goog-channel-token": "secret", + "x-goog-resource-id": "resource", + "x-goog-resource-state": "change", + } + assert push.verify_drive(headers, [channel], now=1000) + assert not push.verify_drive({**headers, "x-goog-resource-state": "sync"}, [channel], now=1000) + for key in headers: + with pytest.raises(push.DeliveryRefused): + push.verify_drive({**headers, key: "wrong"}, [channel], now=1000) + with pytest.raises(push.DeliveryRefused): + push.verify_drive(headers, [channel], now=1100) + + +def test_fingerprint_ignores_mapping_order_but_binds_credentials_and_items() -> None: + kwargs = {"credential": "key", "items": [{"id": "one", "type": "file"}], "config": {}} + first = push.fingerprint(**kwargs) + assert first == push.fingerprint(**{**kwargs, "items": [{"type": "file", "id": "one"}]}) + assert first != push.fingerprint(**{**kwargs, "credential": "other"}) + assert first != push.fingerprint(**{**kwargs, "items": []}) diff --git a/tests/unit/test_source_push_routes.py b/tests/unit/test_source_push_routes.py new file mode 100644 index 0000000000..4d06a23600 --- /dev/null +++ b/tests/unit/test_source_push_routes.py @@ -0,0 +1,113 @@ +"""Provider ingress bounds its bytes and acknowledges with the required status.""" + +from __future__ import annotations + +from unittest.mock import AsyncMock +from urllib.parse import urlsplit, urlunsplit + +import pytest +from fastapi import FastAPI +from fastapi.testclient import TestClient + +from server.knowledge.app import source_push as push +from server.knowledge.app import source_push_routes as routes +from server.knowledge.domain.source_push import MAX_BODY_BYTES, DeliveryRefused, PushRegistration + +URL = "/hooks/knowledge/docs/12345678-1234-1234-1234-123456789abc/22345678-1234-1234-1234-123456789abc?org=org" + + +def client() -> TestClient: + app = FastAPI() + routes.attach(app) + return TestClient(app) + + +def test_verified_delivery_acknowledges_200_inside_provider_deadline( + monkeypatch: pytest.MonkeyPatch, +) -> None: + receive = AsyncMock() + monkeypatch.setattr(routes, "receive", receive) + assert client().post(URL, content=b"signal").status_code == 200 + assert routes.CALLBACK_TIMEOUT_S < 5 + assert receive.call_args.args[:5] == ( + "org", + "docs", + "12345678-1234-1234-1234-123456789abc", + "22345678-1234-1234-1234-123456789abc", + b"signal", + ) + + +def test_oversized_delivery_never_reaches_store(monkeypatch: pytest.MonkeyPatch) -> None: + receive = AsyncMock() + monkeypatch.setattr(routes, "receive", receive) + assert client().post(URL, content=b"x" * (MAX_BODY_BYTES + 1)).status_code == 413 + receive.assert_not_awaited() + + +def test_unverifiable_delivery_refuses(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setattr( + routes, "receive", AsyncMock(side_effect=DeliveryRefused("unverifiable delivery")) + ) + assert client().post(URL, content=b"signal").status_code == 403 + + +def test_callback_without_namespace_is_not_a_route(monkeypatch: pytest.MonkeyPatch) -> None: + receive = AsyncMock() + monkeypatch.setattr(routes, "receive", receive) + assert client().post(URL.replace("/docs/", "/"), content=b"signal").status_code == 404 + receive.assert_not_awaited() + + +@pytest.fixture +def callback_env(monkeypatch: pytest.MonkeyPatch) -> AsyncMock: + held = AsyncMock(return_value=True) + monkeypatch.setattr(routes.tenancy, "is_held", held) + monkeypatch.setattr(push.settings, "public_base_url", "https://loom.example") + return held + + +def registration(org: str) -> PushRegistration: + return PushRegistration( + org=org, + namespace="docs", + name="source", + source_id="12345678-1234-1234-1234-123456789abc", + generation="22345678-1234-1234-1234-123456789abc", + provider="notion", + fingerprint="fingerprint", + ) + + +@pytest.mark.parametrize( + "org", + ["org", "team/acme", "team?x=1&org=other#group", "team%2Facme+ ops", "研究/チーム &é"], +) +def test_generated_callback_round_trips_the_exact_organization_through_asgi( + monkeypatch: pytest.MonkeyPatch, callback_env: AsyncMock, org: str +) -> None: + receive = AsyncMock() + monkeypatch.setattr(routes, "receive", receive) + reg = registration(org) + response = client().post(push.callback_url(reg), content=b"signal") + assert response.status_code == 200 + callback_env.assert_awaited_once_with(org) + assert receive.await_args.args[:5] == ( + org, + reg.namespace, + reg.source_id, + reg.generation, + b"signal", + ) + + +def test_callback_requires_organization_before_tenancy_or_delivery( + monkeypatch: pytest.MonkeyPatch, callback_env: AsyncMock +) -> None: + receive = AsyncMock() + monkeypatch.setattr(routes, "receive", receive) + address = urlsplit(push.callback_url(registration("org"))) + missing_org = urlunsplit(address._replace(query="")) + assert client().post(missing_org, content=b"signal").status_code == 422 + callback_env.assert_not_awaited() + receive.assert_not_awaited() diff --git a/tests/unit/test_source_push_worker.py b/tests/unit/test_source_push_worker.py new file mode 100644 index 0000000000..5ed1439633 --- /dev/null +++ b/tests/unit/test_source_push_worker.py @@ -0,0 +1,100 @@ +"""Renewal pages advance past failed sources and reset exhausted scans durably.""" + +from __future__ import annotations + +import json +from types import SimpleNamespace +from unittest.mock import AsyncMock + +import pytest + +from server.knowledge.domain.source_push import PushRegistration +from server.knowledge.workers import source_push as worker +from server.workers import pass_context, registry + + +def registration(source_id: str) -> PushRegistration: + return PushRegistration( + org="org", + namespace="docs", + name="source", + source_id=source_id, + provider="gdrive", + generation="gen", + fingerprint="fp", + ) + + +@pytest.mark.asyncio +async def test_failed_source_does_not_starve_following_row(monkeypatch: pytest.MonkeyPatch) -> None: + context = pass_context.begin("knowledge_source_push", resume_cursor='["before", "docs", "id"]') + page = AsyncMock(return_value=[registration("one"), registration("two")]) + renew = AsyncMock(side_effect=[ConnectionError("temporary"), None]) + monkeypatch.setattr(worker, "require_ready", AsyncMock()) + monkeypatch.setattr(worker, "drive_page", page) + monkeypatch.setattr(worker, "renew_drive", renew) + result = await worker.run_pass() + page.assert_awaited_once_with(("before", "docs", "id")) + assert result == {"items_planned": 2, "items_done": 1, "failed": 1} + assert context.count == 1 and json.loads(context.cursor) == ["", "", ""] + + +@pytest.mark.asyncio +@pytest.mark.parametrize("max_pass,expected", [(120.0, 1), (180.0, 2)]) +async def test_page_cut_persists_last_attempted_row( + monkeypatch: pytest.MonkeyPatch, max_pass: float, expected: int +) -> None: + context = pass_context.begin("knowledge_source_push") + monkeypatch.setattr(worker, "require_ready", AsyncMock()) + monkeypatch.setattr( + worker, "drive_page", AsyncMock(return_value=[registration("one"), registration("two")]) + ) + renew = AsyncMock() + monkeypatch.setattr(worker, "renew_drive", renew) + monkeypatch.setattr(worker.settings, "knowledge_source_push_max_pass_seconds", max_pass) + clock = iter([0.0, 0.0, 80.0]) + monkeypatch.setattr(worker, "time", SimpleNamespace(monotonic=lambda: next(clock, 80.0))) + result = await worker.run_pass() + assert result["items_done"] == expected + assert json.loads(context.cursor) == (["org", "docs", "one"] if expected == 1 else ["", "", ""]) + assert renew.await_count == expected + + +def test_registry_reads_configured_push_cadence_and_deadline( + monkeypatch: pytest.MonkeyPatch, +) -> None: + monkeypatch.setattr(worker.settings, "knowledge_source_push_enabled", True) + monkeypatch.setattr(worker.settings, "knowledge_source_push_interval_seconds", 733) + monkeypatch.setattr(worker.settings, "knowledge_source_push_max_pass_seconds", 180.0) + spec = next(spec for spec in registry.enabled_workers() if spec.name == "knowledge_source_push") + assert spec.interval_seconds == 733 + assert spec.deadline_seconds() == 180.0 + + +@pytest.mark.asyncio +async def test_page_cursor_advances_between_namespaces(monkeypatch: pytest.MonkeyPatch) -> None: + import dataclasses + + context = pass_context.begin("knowledge_source_push", resume_cursor='["org", "docs", "before"]') + rows = [ + registration("same-id"), + dataclasses.replace(registration("same-id"), namespace="other-docs"), + ] + page = AsyncMock(return_value=rows) + renew = AsyncMock() + cursors: list[list[str]] = [] + set_cursor = pass_context.set_cursor + + def capture_cursor(cursor: str) -> None: + cursors.append(json.loads(cursor)) + set_cursor(cursor) + + monkeypatch.setattr(worker, "require_ready", AsyncMock()) + monkeypatch.setattr(worker, "drive_page", page) + monkeypatch.setattr(worker, "renew_drive", renew) + monkeypatch.setattr(pass_context, "set_cursor", capture_cursor) + assert await worker.run_pass() == {"items_planned": 2, "items_done": 2, "failed": 0} + page.assert_awaited_once_with(("org", "docs", "before")) + assert [call.args[0] for call in renew.await_args_list] == rows + assert cursors == [["org", "docs", "same-id"], ["org", "other-docs", "same-id"], ["", "", ""]] + assert json.loads(context.cursor) == ["", "", ""] diff --git a/tests/unit/test_source_ranking.py b/tests/unit/test_source_ranking.py new file mode 100644 index 0000000000..5c7830fa24 --- /dev/null +++ b/tests/unit/test_source_ranking.py @@ -0,0 +1,202 @@ +"""Source copies contribute complete hits and never borrow another copy's rank credit.""" + +from __future__ import annotations + +import json + +import pytest + +from server.knowledge.app import source_ranking as app +from server.knowledge.app.search import ChunkHit +from server.knowledge.app.source_access import Admitted +from server.knowledge.app.source_search import Hydrated + + +def copy(label, *, uri="drive:file", distance=0.1, lexical=0.0, matched=()): + sid = ("1" if label == "A" else "2") * 8 + "-1111-4111-8111-111111111111" + version, revision = (10, 0) if label == "A" else (20, 1) + candidate = { + "namespace": "acl-" + "1" * 24, + "source_uri": uri + "#" + sid, + "chunk_idx": 0, + "doc_version": version, + "revision": revision, + "distance": distance, + "lexical": lexical, + "matched": list(matched), + } + return Hydrated( + Admitted("docs", candidate, {"version": version, "title": label}), + {"content": label, "chunk_metadata": json.dumps({"revision": revision})}, + ) + + +def ordinary(uri="drive:ordinary", *, score=0.8): + return ChunkHit("docs", uri, 0, "ordinary content", ["ordinary"], 0.2, score=score) + + +def test_public_mirror_hits_omit_internal_ownership_tags(): + item = copy("A") + item.row["tags"] = ["source-id:private", "kind:notes"] + [result] = app.rank({}, {"semantic": [item]}, legs=("semantic",), fallback=[], top_k=1) + assert result.chunk.tags == ["kind:notes"] + + +def test_public_ordinary_hits_keep_their_existing_tags(): + hit = ordinary() + hit.tags[:] = ["source-id:ordinary", "kind:notes"] + [result] = app.rank({"semantic": [hit]}, {}, legs=("semantic",), fallback=[hit], top_k=1) + assert result.chunk is hit and result.chunk.tags == ["source-id:ordinary", "kind:notes"] + + +def test_different_semantic_and_lexical_copies_never_mix_text_distance_or_credit(): + a, b = copy("A"), copy("B", distance=0.5, lexical=4.0) + [result] = app.rank( + {}, + {"semantic": [a], "lexical": [b]}, + legs=("semantic", "lexical"), + fallback=[], + top_k=1, + ) + hit = result.chunk + assert (hit.content, hit.distance, hit.lexical_score, hit.revision, hit.doc_version) == ( + "A", + 0.1, + 0.0, + 0, + 10, + ) + assert hit.score == pytest.approx(1 / 61) + assert result.admitted is a.admitted and result.mirrored + assert hit.namespace == "docs" and hit.source_uri == "drive:file" + + +def test_lexical_and_key_credit_can_choose_one_copy_without_borrowing_semantic_distance(): + a, b = copy("A"), copy("B", distance=0.5, lexical=4.0, matched=("key",)) + [result] = app.rank( + {}, + {"semantic": [a], "lexical": [b], "keys": [b]}, + legs=("semantic", "lexical", "keys"), + fallback=[], + top_k=1, + ) + hit = result.chunk + assert (hit.content, hit.distance, hit.lexical_score, hit.revision, hit.doc_version) == ( + "B", + 0.5, + 4.0, + 1, + 20, + ) + assert hit.score == pytest.approx(2 / 61) + assert result.admitted is b.admitted and hit.keys_matched == ("key",) + + +def test_same_storage_copy_combines_its_own_leg_credit(): + a = copy("A", lexical=4.0) + [result] = app.rank( + {}, + {"semantic": [a], "lexical": [a]}, + legs=("semantic", "lexical"), + fallback=[], + top_k=1, + ) + assert result.chunk.content == "A" and result.chunk.score == pytest.approx(2 / 61) + + +def test_different_versions_at_one_storage_address_keep_separate_payload_and_credit(): + a, b = copy("A"), copy("A", distance=0.5, lexical=4) + b.admitted.candidate["doc_version"] = 20 + b.row["content"] = "different version" + [result] = app.rank( + {}, + {"semantic": [a], "lexical": [b]}, + legs=("semantic", "lexical"), + fallback=[], + top_k=1, + ) + assert result.chunk.content == "A" and result.chunk.doc_version == 10 + assert result.chunk.distance == 0.1 and result.chunk.lexical_score == 0 + assert result.chunk.score == pytest.approx(1 / 61) + + +def test_copy_collapse_happens_before_final_page_limit(): + out = app.rank( + {}, + { + "semantic": [copy("A"), copy("A", uri="drive:second", distance=0.8)], + "lexical": [ + copy("B", distance=0.5, lexical=4), + copy("B", uri="drive:third", lexical=1), + ], + }, + legs=("semantic", "lexical"), + fallback=[], + top_k=2, + ) + assert len(out) == 2 + assert out[0].chunk.source_uri == "drive:file" + assert out[1].chunk.source_uri in {"drive:second", "drive:third"} + assert out[1].chunk.score == pytest.approx(1 / 62) + + +def test_serving_ordinary_family_wins_across_legs_without_changing_its_fields(): + hit = ordinary(uri="drive:file") + [result] = app.rank( + {"semantic": [hit]}, + {"lexical": [copy("A", lexical=99)]}, + legs=("semantic", "lexical"), + fallback=[hit], + top_k=1, + ) + assert result.chunk is hit and result.admitted is None and not result.mirrored + + +def test_ordinary_pool_from_an_unselected_leg_cannot_shadow_a_mirror(): + hit = ordinary(uri="drive:file") + [result] = app.rank( + {"keys": [hit]}, + {"lexical": [copy("A", lexical=3)]}, + legs=("lexical",), + fallback=[], + top_k=1, + ) + assert result.mirrored and result.chunk.lexical_score == result.chunk.score == 3 + + +def test_no_admitted_mirrors_preserves_fallback_order_identity_and_scores(): + a, b = ordinary("drive:z", score=0.7), ordinary("drive:a", score=0.7) + out = app.rank( + {"semantic": [a, b]}, + {}, + legs=("semantic",), + fallback=[a, b], + top_k=2, + ) + assert [r.chunk for r in out] == [a, b] + assert out[0].chunk is a and out[1].chunk is b + assert all(not r.mirrored for r in out) + + +def test_semantic_scores_and_native_uri_fragments_survive_projection(): + [result] = app.rank( + {}, + {"semantic": [copy("A", uri="drive:file#native", distance=0.25)]}, + legs=("semantic",), + fallback=[], + top_k=1, + ) + assert result.chunk.source_uri == "drive:file#native" and result.chunk.score == 0.75 + + +def test_ordinary_semantic_hit_keeps_its_payload_and_similarity_when_mirrors_match(): + hit = ordinary() + out = app.rank( + {"semantic": [hit]}, + {"semantic": [copy("A")]}, + legs=("semantic",), + fallback=[hit], + top_k=2, + ) + assert out[1].chunk is hit and out[1].chunk.score == hit.score + assert not out[1].mirrored diff --git a/tests/unit/test_source_read_results.py b/tests/unit/test_source_read_results.py new file mode 100644 index 0000000000..32f7581c7f --- /dev/null +++ b/tests/unit/test_source_read_results.py @@ -0,0 +1,175 @@ +"""Composed reads publish no mixed result after any child's proof is lost.""" + +from __future__ import annotations + +import asyncio +from types import SimpleNamespace +from unittest.mock import AsyncMock, Mock + +import pytest + +from server.core.diagnostics import codes_only +from server.knowledge.app.source_corpus import LostCorpus +from server.knowledge.app.source_read_results import settle + + +def child(name, events, *, marked=True, mirrored=True, lost=False): + async def check(): + assert not marked or codes_only() + events.append(name + ":check") + + def fresh(): + events.append(name + ":fresh") + return True + + result = SimpleNamespace( + marked=marked, + lost=lost, + output=name + ":mixed", + proofs=SimpleNamespace(check=AsyncMock(side_effect=check), fresh=Mock(side_effect=fresh)) + if mirrored + else None, + ) + + async def ordinary(): + assert not marked or codes_only() + events.append(name + ":ordinary") + result.output = name + ":ordinary" + result.proofs, result.lost = None, True + return result.output + + result.ordinary = AsyncMock(side_effect=ordinary) + return result + + +async def test_every_proof_is_checked_before_all_pure_freshness_checks_and_publication(): + events = [] + first, second = child("first", events), child("second", events) + await settle([first, second]) + assert events == ["first:check", "second:check", "first:fresh", "second:fresh"] + assert (first.output, second.output) == ("first:mixed", "second:mixed") + first.ordinary.assert_not_awaited() + second.ordinary.assert_not_awaited() + assert not codes_only() + + +@pytest.mark.parametrize("when", ["prior_loss", "check_loss", "last_check_loss", "expired"]) +async def test_any_child_loss_rebuilds_all_children_before_returning(when): + events = [] + first, second = child("first", events), child("second", events) + if when == "prior_loss": + first.lost = True + elif when == "check_loss": + first.proofs.check.side_effect = LostCorpus + elif when == "last_check_loss": + + async def loss(): + first.lost = True + + second.proofs.check.side_effect = loss + else: + first.proofs.fresh.side_effect = lambda: False + await settle([first, second]) + assert (first.output, second.output) == ("first:ordinary", "second:ordinary") + first.ordinary.assert_awaited_once() + second.ordinary.assert_awaited_once() + if when == "prior_loss": + assert events == ["first:ordinary", "second:ordinary"] + + +async def test_empty_or_ordinary_only_composition_needs_no_fallback_or_conditional_io(): + events = [] + ordinary = child("ordinary", events, marked=False, mirrored=False) + await settle([]) + await settle([ordinary]) + assert events == [] and not codes_only() + ordinary.ordinary.assert_not_awaited() + + +async def test_marked_composition_keeps_ordinary_sibling_fallback_private(): + events = [] + first = child("first", events, lost=True) + second = child("ordinary", events, marked=False, mirrored=False) + + async def ordinary(): + assert codes_only() + second.output = "ordinary:reply" + + second.ordinary.side_effect = ordinary + await settle([first, second]) + assert second.output == "ordinary:reply" and not codes_only() + + +async def test_child_collection_is_snapshotted_before_any_check_awaits(): + events = [] + first, second = child("first", events), child("second", events) + children = [first, second] + + async def remove(): + children.clear() + raise LostCorpus() + + first.proofs.check.side_effect = remove + await settle(children) + assert first.output == "first:ordinary" and second.output == "second:ordinary" + assert not children + + +async def test_unrelated_proof_error_propagates_without_returning_or_rebuilding_partial_results(): + events = [] + first, second = child("first", events), child("second", events) + first.proofs.check.side_effect = RuntimeError("ordinary backend unavailable") + with pytest.raises(RuntimeError, match="ordinary backend unavailable"): + await settle([first, second]) + first.ordinary.assert_not_awaited() + second.ordinary.assert_not_awaited() + + +async def test_failed_fallback_cancels_and_drains_its_owned_sibling_before_propagating(): + events = [] + first, second = child("first", events, lost=True), child("second", events) + entered, stopped = asyncio.Event(), asyncio.Event() + + async def fail(): + await entered.wait() + raise RuntimeError("ordinary provider failed") + + async def sibling(): + entered.set() + try: + await asyncio.Future() + finally: + stopped.set() + + first.ordinary.side_effect, second.ordinary.side_effect = fail, sibling + with pytest.raises(RuntimeError, match="ordinary provider failed"): + await settle([first, second]) + assert stopped.is_set() + + +async def test_outer_cancellation_drains_all_owned_fallback_tasks(): + events = [] + first, second = child("first", events, lost=True), child("second", events) + entered, stopped = [asyncio.Event(), asyncio.Event()], [asyncio.Event(), asyncio.Event()] + + async def wait(index): + entered[index].set() + try: + await asyncio.Future() + finally: + stopped[index].set() + + async def first_wait(): + await wait(0) + + async def second_wait(): + await wait(1) + + first.ordinary.side_effect = first_wait + second.ordinary.side_effect = second_wait + task = asyncio.create_task(settle([first, second])) + await asyncio.gather(*(event.wait() for event in entered)) + task.cancel() + with pytest.raises(asyncio.CancelledError): + await task + assert all(event.is_set() for event in stopped) diff --git a/tests/unit/test_source_repo_docs_cache.py b/tests/unit/test_source_repo_docs_cache.py new file mode 100644 index 0000000000..3fdfa8d743 --- /dev/null +++ b/tests/unit/test_source_repo_docs_cache.py @@ -0,0 +1,204 @@ +"""Mirrored repository listings bypass namespace caches before either cache access.""" + +from __future__ import annotations + +import asyncio +from contextlib import asynccontextmanager +from datetime import UTC, datetime, timedelta +from types import SimpleNamespace +from unittest.mock import AsyncMock + +import pytest + +from server.knowledge.app import document_reads, repo_docs, source_access +from server.knowledge.app.source_list_proofs import ListProofs +from server.knowledge.domain.access_list import AccessList +from server.knowledge.store import source_documents +from server.settings import settings + + +@pytest.fixture +def world(monkeypatch): + state = SimpleNamespace(allowed=True, marked=True, unread=False, phases=[]) + + async def resolve(input): + state.phases.append("resolve") + return document_reads.ListRequest(input.model_copy(deep=True), ("code-kj",), None) + + async def prepare(org, namespaces): + state.phases.append("prepare") + assert (org, namespaces) == ("acme", ["code-kj"]) + return source_access.ReadPlan(org, marked=state.marked, unread=state.unread) + + async def run(request, plan): + state.phases.append("list") + assert request.namespaces == ("code-kj",) and plan.org == "acme" + title = "Ordinary title" if not state.marked else "Current private title" + rows = ( + [SimpleNamespace(source_uri="gdrive:file", title=title, description="Description")] + if not state.marked or (state.allowed and not state.unread) + else [] + ) + return SimpleNamespace( + output=SimpleNamespace(rows=rows), marked=state.marked, lost=False, proofs=None + ) + + repo_docs.reset_cache_for_tests() + monkeypatch.setattr( + "server.code.app.repo_scope.readable_repo_namespace", AsyncMock(return_value="code-kj") + ) + monkeypatch.setattr(document_reads, "resolve_list", AsyncMock(side_effect=resolve)) + monkeypatch.setattr(source_access, "prepare", AsyncMock(side_effect=prepare)) + monkeypatch.setattr(document_reads, "run_checked_list", AsyncMock(side_effect=run)) + yield state + repo_docs.reset_cache_for_tests() + + +async def test_private_titles_are_never_shared_with_a_second_reader_by_the_namespace_cache(world): + first = (await repo_docs.list_repo_docs("acme", "code-kj")).docs + assert first[0]["title"] == "Current private title" + world.allowed = False + second = (await repo_docs.list_repo_docs("acme", "code-kj")).docs + assert second == [] + assert repo_docs._LIST_CACHE == {} + assert world.phases == ["resolve", "prepare", "list"] * 2 + + +@pytest.mark.parametrize( + "cached", [[], [{"source_uri": "old", "title": "Old private title", "description": ""}]] +) +async def test_marked_listing_reads_neither_a_positive_nor_a_negative_cached_page(world, cached): + key = ("acme", "code-kj", repo_docs.DOCS_SECTION_MAX_DOCS) + repo_docs._LIST_CACHE[key] = (float("inf"), cached) + docs = (await repo_docs.list_repo_docs("acme", "code-kj")).docs + assert docs == [ + { + "source_uri": "gdrive:file", + "title": "Current private title", + "description": "Description", + } + ] + assert repo_docs._LIST_CACHE[key][1] == cached + assert world.phases == ["resolve", "prepare", "list"] + + +async def test_unread_mirror_preparation_never_falls_back_to_cached_private_titles(world): + key = ("acme", "code-kj", repo_docs.DOCS_SECTION_MAX_DOCS) + repo_docs._LIST_CACHE[key] = ( + float("inf"), + [{"source_uri": "old", "title": "Old private title", "description": ""}], + ) + world.unread = True + assert await repo_docs.list_repo_docs("acme", "code-kj") == repo_docs.RepoListing("code-kj", []) + assert world.phases == ["resolve", "prepare", "list"] + + +async def test_ordinary_cache_still_prepares_the_current_caller_before_each_cache_lookup(world): + world.marked = False + first = await repo_docs.list_repo_docs("acme", "code-kj") + assert first == await repo_docs.list_repo_docs("acme", "code-kj") + assert first.docs[0]["title"] == "Ordinary title" + assert world.phases == ["resolve", "prepare", "list", "resolve", "prepare"] + + +async def test_preparation_is_inside_the_additive_listing_timeout(world, monkeypatch): + async def wait(*_args): + await asyncio.Future() + + monkeypatch.setattr(source_access, "prepare", AsyncMock(side_effect=wait)) + assert await repo_docs.list_repo_docs( + "acme", "code-kj", timeout_s=0.01 + ) == repo_docs.RepoListing("code-kj", []) + assert repo_docs._LIST_CACHE == {} + + +async def test_private_failure_details_do_not_escape_the_additive_logger( + world, monkeypatch, caplog +): + monkeypatch.setattr( + document_reads, + "run_checked_list", + AsyncMock(side_effect=ValueError("PRIVATE-SOURCE-CONTENT")), + ) + with caplog.at_level("INFO", logger="loom.repo_docs"): + assert await repo_docs.list_repo_docs("acme", "code-kj") == repo_docs.RepoListing( + "code-kj", [] + ) + assert "PRIVATE-SOURCE-CONTENT" not in caplog.text + assert repo_docs._LIST_CACHE == {} + + +async def test_permission_expiry_during_timeout_cleanup_returns_the_complete_ordinary_list( + world, monkeypatch +): + clock = SimpleNamespace(at=datetime(2025, 1, 1, tzinfo=UTC)) + mirror, sid = "acl-" + "1" * 24, "11111111-1111-4111-8111-111111111111" + plan = source_access.ReadPlan("acme", marked=True, listing_starts={(mirror, sid): clock.at}) + ordinary = { + "namespace": "code-kj", + "source_uri": "ordinary:page", + "title": "Ordinary title", + "description": "Ordinary description", + "tags": [], + "ingested_at": clock.at, + "superseded_at": None, + "chunk_count": 1, + } + private = { + **ordinary, + "source_uri": "gdrive:file", + "title": "Private title", + "ingested_at": clock.at + timedelta(seconds=1), + } + stored = "gdrive:file#" + sid + item = source_access.Admitted( + "code-kj", + {"namespace": mirror, "source_uri": stored}, + { + **private, + "namespace": mirror, + "source_uri": stored, + "tags": ["source-id:" + sid], + "version": 10, + "revision": 0, + }, + AccessList(anyone=True), + ) + plan.check = AsyncMock(return_value=[item]) + proof = ListProofs(plan, False, (item,)) + results = [] + + async def run(request, actual_plan): + assert actual_plan is plan + await proof.check() + renderer = document_reads._ListRenderer(request) + checked = document_reads.CheckedList( + renderer.render([ordinary], [private]), proof, True, renderer, [ordinary] + ) + assert [r.source_uri for r in checked.output.rows] == ["gdrive:file"] + results.append(checked) + return checked + + @asynccontextmanager + async def timeout(_seconds): + yield + clock.at += timedelta(seconds=6) + + monkeypatch.setattr(source_access, "now", lambda: clock.at) + monkeypatch.setattr(settings, "knowledge_source_acl_stale_seconds", 5) + monkeypatch.setattr(source_access, "prepare", AsyncMock(return_value=plan)) + monkeypatch.setattr(document_reads, "run_checked_list", run) + monkeypatch.setattr(source_documents, "ordinary_families", AsyncMock(return_value=set())) + monkeypatch.setattr(repo_docs.asyncio, "timeout", timeout) + assert await repo_docs.list_repo_docs("acme", "code-kj", limit=1) == repo_docs.RepoListing( + "code-kj", + [ + { + "source_uri": "ordinary:page", + "title": "Ordinary title", + "description": "Ordinary description", + } + ], + ) + assert results[0].lost and results[0].proofs is None and proof.invalid + assert repo_docs._LIST_CACHE == {} diff --git a/tests/unit/test_source_repo_search.py b/tests/unit/test_source_repo_search.py new file mode 100644 index 0000000000..3e7b061896 --- /dev/null +++ b/tests/unit/test_source_repo_search.py @@ -0,0 +1,399 @@ +"""Repository composition retains source proofs across both search legs.""" + +from __future__ import annotations + +import asyncio +from types import SimpleNamespace + +import pytest + +from server.core.diagnostics import codes_only +from server.knowledge.api.models_knowledge import ( + KnowledgeSearchInput, + KnowledgeSearchOutput, + _SearchHit, +) +from server.knowledge.app import knowledge_search as search +from server.knowledge.app import repo_docs, source_access +from server.knowledge.app.source_corpus import LostCorpus + + +def hit(uri, score, namespace): + return _SearchHit( + source_uri=uri, + content=uri, + chunk_idx=0, + tags=[], + distance=1 - score, + similarity=score, + score=score, + namespace=namespace, + ) + + +def install(monkeypatch, *, revoke=False, extra_error=False, base_error=False): + events = [] + children = {} + expired = False + base_ready = asyncio.Event() + + async def resolve(inp): + events.append("resolve:" + inp.namespace) + return search.SearchRequest(inp.model_copy(deep=True), (inp.namespace,), ()) + + async def prepare(org, namespaces): + events.append(("prepare", tuple(namespaces))) + return source_access.ReadPlan(org, marked=True) + + async def run(request, plan): + nonlocal expired + ns = request.input.namespace + events.append(("run", ns, codes_only())) + if ns == "home": + if base_error: + base_ready.set() + raise RuntimeError("base failed") + base_ready.set() + else: + await base_ready.wait() + expired = revoke + if extra_error: + raise RuntimeError("PRIVATE-SOURCE-CONTENT") + mixed = KnowledgeSearchOutput( + results=[hit("private:" + ns, 0.9, ns)], + embedding_model="fake", + reranked_by="private-rank", + ) + ordinary = KnowledgeSearchOutput( + results=[hit("ordinary:" + ns, 0.4, ns)], embedding_model="fake", stale_dropped=2 + ) + + async def check(): + events.append("check:" + ns) + if expired: + raise LostCorpus() + + async def render(*_args): + events.append("ordinary:" + ns) + return ordinary + + result = search.CheckedSearch( + mixed, + SimpleNamespace(check=check, fresh=lambda: not expired, mirrored=True), + SimpleNamespace(marked=True, render=render), + [], + 2, + ) + children[ns] = result + return result + + async def public(inp): + return (await run(await resolve(inp), source_access.ReadPlan(inp.org, marked=True))).output + + monkeypatch.setattr(search, "resolve_search", resolve) + monkeypatch.setattr(search, "run_checked_search", run) + monkeypatch.setattr(search, "handle_knowledge_search", public) + monkeypatch.setattr(source_access, "prepare", prepare) + return events, children + + +INPUT = KnowledgeSearchInput(org="acme", namespace="home", query="cache", top_k=3) + + +async def test_sibling_revocation_rebuilds_both_complete_ordinary_searches(monkeypatch): + events, children = install(monkeypatch, revoke=True) + out = await repo_docs.knowledge_with_repo_docs(INPUT, repo_namespace="repo") + assert [h.source_uri for h in out.results] == ["ordinary:home", "ordinary:repo"] + assert out.reranked_by == "" and out.stale_dropped == 2 + assert events.count("ordinary:home") == events.count("ordinary:repo") == 1 + assert all(child.lost for child in children.values()) + + +async def test_union_is_prepared_before_either_provider_and_both_legs_are_private(monkeypatch): + events, _ = install(monkeypatch) + out = await repo_docs.knowledge_with_repo_docs(INPUT, repo_namespace="repo") + assert ("prepare", ("home", "repo")) in events + prep = events.index(("prepare", ("home", "repo"))) + assert all( + prep < i and private + for i, event in enumerate(events) + if isinstance(event, tuple) and event[0] == "run" + for private in [event[2]] + ) + assert [h.source_uri for h in out.results] == ["private:home", "private:repo"] + assert not codes_only() + + +async def test_additive_exception_is_generic_and_base_keeps_its_proof(monkeypatch, caplog): + install(monkeypatch, extra_error=True) + with caplog.at_level("INFO", logger="loom.repo_docs"): + out = await repo_docs.knowledge_with_repo_docs(INPUT, repo_namespace="repo") + assert [h.source_uri for h in out.results] == ["private:home"] + assert "PRIVATE-SOURCE-CONTENT" not in caplog.text + + +async def test_base_error_still_propagates(monkeypatch): + install(monkeypatch, base_error=True) + with pytest.raises(RuntimeError, match="base failed"): + await repo_docs.knowledge_with_repo_docs(INPUT, repo_namespace="repo") + + +@pytest.mark.parametrize("failure", ["error", "timeout"]) +async def test_additive_scope_failure_keeps_the_base_and_drops_its_discovery_scope( + monkeypatch, failure +): + events, _ = install(monkeypatch) + original = search.resolve_search + cleanup = [] + + async def resolve(inp): + if inp.namespace == "repo": + if failure == "error": + raise RuntimeError("PRIVATE-SCOPE-DETAIL") + try: + await asyncio.Event().wait() + finally: + cleanup.append("drained") + return await original(inp) + + monkeypatch.setattr(search, "resolve_search", resolve) + monkeypatch.setattr(repo_docs.settings, "knowledge_repo_docs_timeout_s", 0.001) + out = await repo_docs.knowledge_with_repo_docs(INPUT, repo_namespace="repo") + assert [h.source_uri for h in out.results] == ["private:home"] + assert ("prepare", ("home",)) in events + assert not any(isinstance(e, tuple) and e[:2] == ("run", "repo") for e in events) + assert cleanup == (["drained"] if failure == "timeout" else []) + + +async def test_base_scope_failure_never_starts_discovery_or_providers(monkeypatch): + events, _ = install(monkeypatch) + + async def fail(inp): + raise RuntimeError("base scope refused") + + monkeypatch.setattr(search, "resolve_search", fail) + with pytest.raises(RuntimeError, match="base scope refused"): + await repo_docs.knowledge_with_repo_docs(INPUT, repo_namespace="repo") + assert events == [] + + +@pytest.mark.parametrize("failure", ["cancel", "base_error"]) +async def test_parent_failure_cancels_and_drains_owned_siblings(monkeypatch, failure): + install(monkeypatch) + entered, release = asyncio.Event(), asyncio.Event() + active, drained = set(), set() + + async def run(request, plan): + ns = request.input.namespace + active.add(ns) + if len(active) == 2: + entered.set() + try: + if ns == "home" and failure == "base_error": + await entered.wait() + raise RuntimeError("base failed") + await release.wait() + finally: + drained.add(ns) + + monkeypatch.setattr(search, "run_checked_search", run) + task = asyncio.create_task(repo_docs.knowledge_with_repo_docs(INPUT, repo_namespace="repo")) + await entered.wait() + if failure == "cancel": + task.cancel() + with pytest.raises(asyncio.CancelledError if failure == "cancel" else RuntimeError): + await task + assert active == drained == {"home", "repo"} + + +async def test_expired_additive_budget_never_starts_its_provider(monkeypatch): + events, _ = install(monkeypatch) + request = await repo_docs.resolve_repo_search(INPUT, repo_namespace="repo") + from dataclasses import replace + + request = replace(request, extra_deadline=asyncio.get_running_loop().time() - 1) + result = await repo_docs.run_repo_search(request, source_access.ReadPlan("acme", marked=True)) + assert [h.source_uri for h in result.output.results] == ["private:home"] + assert not any(isinstance(e, tuple) and e[:2] == ("run", "repo") for e in events) + assert result.children == (result.base,) and result.extra is None + + +@pytest.mark.parametrize("child", ["base", "extra"]) +async def test_every_child_org_is_checked_before_any_provider(monkeypatch, child): + from dataclasses import replace + + events, _ = install(monkeypatch) + request = await repo_docs.resolve_repo_search(INPUT, repo_namespace="repo") + changed = getattr(request, child) + changed = replace(changed, input=changed.input.model_copy(update={"org": "other"})) + request = replace(request, **{child: changed}) + with pytest.raises(ValueError, match="document read scope changed"): + await repo_docs.run_repo_search(request, source_access.ReadPlan("acme", marked=True)) + assert not any(isinstance(e, tuple) and e[0] == "run" for e in events) + + +async def test_actual_checked_children_publish_only_their_cached_ordinary_rerenders(monkeypatch): + from unittest.mock import AsyncMock + + install(monkeypatch) + request = await repo_docs.resolve_repo_search(INPUT, repo_namespace="repo") + renderers = [] + children = [] + for ns in ["home", "repo"]: + renderer = SimpleNamespace( + marked=True, + render=AsyncMock( + return_value=KnowledgeSearchOutput( + results=[hit("ordinary:" + ns, 0.4, ns)], + embedding_model="ordinary-model", + stale_dropped=7, + ) + ), + ) + proof = SimpleNamespace(check=AsyncMock(side_effect=LostCorpus()), fresh=lambda: False) + children.append( + search.CheckedSearch( + KnowledgeSearchOutput( + results=[hit("private:" + ns, 0.9, ns)], + embedding_model="private-model", + reranked_by="private-rank", + ), + proof, + renderer, + [], + 7, + ) + ) + renderers.append(renderer) + result = repo_docs.RepoSearch(request, *children) + assert result.output.reranked_by == "private-rank" + await result.current() + out = result.output + assert [h.source_uri for h in out.results] == ["ordinary:home", "ordinary:repo"] + assert (out.embedding_model, out.reranked_by, out.stale_dropped) == ("ordinary-model", "", 7) + await result.current() + for renderer in renderers: + renderer.render.assert_awaited_once_with([], 7) + + +async def test_additive_final_permission_renewal_is_bounded_without_failing_the_base(monkeypatch): + events, children = install(monkeypatch) + original = search.run_checked_search + cleaned = [] + + async def run(request, plan): + result = await original(request, plan) + if request.input.namespace == "repo": + + async def wait_forever(): + try: + await asyncio.Event().wait() + finally: + cleaned.append("extra proof drained") + + result.proofs.check = wait_forever + return result + + monkeypatch.setattr(search, "run_checked_search", run) + monkeypatch.setattr(repo_docs.settings, "knowledge_repo_docs_timeout_s", 0.005) + out = await asyncio.wait_for( + repo_docs.knowledge_with_repo_docs(INPUT, repo_namespace="repo"), timeout=0.1 + ) + assert [h.source_uri for h in out.results] == ["private:home"] + assert cleaned == ["extra proof drained"] + assert not children["home"].lost and "check:home" in events + + +async def test_timed_out_extra_fallback_keeps_loss_sticky_and_preserves_base_rebuild(monkeypatch): + from unittest.mock import AsyncMock + + events, children = install(monkeypatch) + original = search.run_checked_search + canceled = [] + + async def run(request, plan): + result = await original(request, plan) + if request.input.namespace == "repo": + + async def block(*_args): + try: + await asyncio.Event().wait() + finally: + canceled.append("drained") + + result.proofs.check = AsyncMock(side_effect=LostCorpus()) + result._renderer.render = block + return result + + monkeypatch.setattr(search, "run_checked_search", run) + monkeypatch.setattr(repo_docs.settings, "knowledge_repo_docs_timeout_s", 0.01) + request = await repo_docs.resolve_repo_search(INPUT, repo_namespace="repo") + result = await repo_docs.run_repo_search(request, source_access.ReadPlan("acme", marked=True)) + out = await asyncio.wait_for(result.current(), timeout=0.2) + assert [h.source_uri for h in out.results] == ["ordinary:home"] + assert result.lost and result.extra is None and canceled == ["drained"] + assert children["repo"]._failed + assert await result.current() is children["home"].output + assert events.count("ordinary:home") == 1 + + +async def test_concurrent_composed_renewals_share_one_cached_fallback(monkeypatch): + events, _ = install(monkeypatch, revoke=True) + request = await repo_docs.resolve_repo_search(INPUT, repo_namespace="repo") + result = await repo_docs.run_repo_search(request, source_access.ReadPlan("acme", marked=True)) + outputs = await asyncio.gather(*(result.current() for _ in range(8))) + assert all( + [h.source_uri for h in out.results] == ["ordinary:home", "ordinary:repo"] for out in outputs + ) + assert events.count("ordinary:home") == events.count("ordinary:repo") == 1 + + +async def test_additive_recipe_keeps_resolved_scope_filters_and_cap(monkeypatch): + install(monkeypatch) + inp = INPUT.model_copy(update={"top_k": 200, "tags": ["narrow"], "uri_prefix": ["notes:"]}) + request = await repo_docs.resolve_repo_search(inp, repo_namespace="repo") + inp.tags.append("later") + inp.uri_prefix.append("later:") + assert request.base.input.tags == ["narrow"] and request.base.input.uri_prefix == ["notes:"] + assert request.extra.input.top_k == 20 and request.extra.input.rerank == "none" + assert request.extra.input.tags == [] and request.extra.input.namespace_scope == "this" + assert request.namespaces == ["home", "repo"] + + +async def test_base_wait_can_expire_the_additive_result_without_reusing_its_wire(monkeypatch): + from dataclasses import replace + + events, children = install(monkeypatch) + request = await repo_docs.resolve_repo_search(INPUT, repo_namespace="repo") + result = await repo_docs.run_repo_search(request, source_access.ReadPlan("acme", marked=True)) + result.request = replace(request, extra_deadline=asyncio.get_running_loop().time() + 0.005) + original = children["home"].proofs.check + + async def check(): + await original() + await asyncio.sleep(0.01) + + children["home"].proofs.check = check + out = await result.current() + assert [h.source_uri for h in out.results] == ["private:home"] + assert result.extra is None and not children["home"].lost + assert "ordinary:home" not in events + + +@pytest.mark.parametrize("force_ordinary", [False, True]) +@pytest.mark.parametrize("prior_loss", [False, True]) +async def test_completed_ordinary_extra_survives_base_work_after_its_deadline( + monkeypatch, force_ordinary, prior_loss +): + from dataclasses import replace + + _, children = install(monkeypatch) + request = await repo_docs.resolve_repo_search(INPUT, repo_namespace="repo") + result = await repo_docs.run_repo_search(request, source_access.ReadPlan("acme", marked=True)) + await children["repo"].ordinary() + children["repo"].lost = prior_loss + result.request = replace(request, extra_deadline=asyncio.get_running_loop().time() - 1) + out = await (result.ordinary() if force_ordinary else result.current()) + home = "ordinary:home" if force_ordinary or prior_loss else "private:home" + assert [h.source_uri for h in out.results] == [home, "ordinary:repo"] + assert result.extra is children["repo"] diff --git a/tests/unit/test_source_repo_search_recipe.py b/tests/unit/test_source_repo_search_recipe.py new file mode 100644 index 0000000000..aad371dae7 --- /dev/null +++ b/tests/unit/test_source_repo_search_recipe.py @@ -0,0 +1,122 @@ +"""Composed repository searches widen fixed scopes and retain final deadlines.""" + +from __future__ import annotations + +import asyncio +from dataclasses import replace +from types import SimpleNamespace +from unittest.mock import Mock + +import pytest + +from server.knowledge.api.models_knowledge import KnowledgeSearchInput, KnowledgeSearchOutput +from server.knowledge.app.knowledge_search import CheckedSearch, SearchRequest +from server.knowledge.app.repo_docs import RepoSearch, RepoSearchRequest +from server.settings import settings + + +def request(*, extra=True): + base = SearchRequest( + KnowledgeSearchInput( + org="acme", + namespace="home", + query="cache", + top_k=2, + tags=["bounded"], + uri_prefix=["notes:"], + ), + ("home", "team"), + ("private",), + ) + additive = ( + SearchRequest( + KnowledgeSearchInput( + org="acme", + namespace="repo", + query="cache", + top_k=2, + rerank="none", + namespace_scope="this", + ), + ("repo",), + (), + ) + if extra + else None + ) + return RepoSearchRequest(base, additive, "repo", asyncio.get_running_loop().time() + 100) + + +def child(*, mirrored=True, lost=False, fresh=True): + proof = SimpleNamespace(fresh=Mock(return_value=fresh)) if mirrored else None + return CheckedSearch( + KnowledgeSearchOutput(results=[], embedding_model="fake"), + proof, + SimpleNamespace(marked=True), + [], + 0, + lost=lost, + ) + + +async def test_wider_recipe_keeps_authorized_scope_filters_and_caps_additive_leg(): + initial = request() + began = asyncio.get_running_loop().time() + widened = initial.wider(50) + ended = asyncio.get_running_loop().time() + assert initial.base.input.top_k == initial.extra.input.top_k == 2 + assert widened.base.input.top_k == 50 and widened.extra.input.top_k == 20 + assert widened.base.namespaces == ("home", "team") and widened.base.skipped == ("private",) + assert widened.extra.namespaces == ("repo",) and widened.extra.input.rerank == "none" + assert widened.extra.input.namespace_scope == "this" + assert widened.base.input.tags == ["bounded"] and widened.base.input.uri_prefix == ["notes:"] + initial.base.input.tags.append("later") + initial.base.input.uri_prefix.append("later:") + assert widened.base.input.tags == ["bounded"] and widened.base.input.uri_prefix == ["notes:"] + assert ( + began + settings.knowledge_repo_docs_timeout_s + <= widened.extra_deadline + <= ended + settings.knowledge_repo_docs_timeout_s + ) + + +async def test_failed_initial_additive_resolution_is_never_rediscovered_by_widening(): + initial = request(extra=False) + widened = initial.wider(10) + assert widened.extra is None and widened.repo_namespace == initial.repo_namespace + assert widened.namespaces == ["home", "team"] + + +@pytest.mark.parametrize("which", ["base", "extra"]) +@pytest.mark.parametrize("state", ["lost", "stale"]) +async def test_final_pure_sweep_rejects_any_retained_child_loss(which, state): + result = RepoSearch(request(), child(), child()) + target = getattr(result, which) + if state == "lost": + target.lost = True + else: + target.proofs.fresh.return_value = False + assert not result.fresh() + + +async def test_expired_additive_budget_rejects_mixed_proof_even_if_acl_is_fresh(): + result = RepoSearch(request(), child(), child()) + assert result.fresh() + result.request = replace(result.request, extra_deadline=asyncio.get_running_loop().time() - 1) + assert not result.fresh() + assert result.extra is not None + + +@pytest.mark.parametrize("extra", [False, True]) +async def test_complete_ordinary_results_need_no_conditional_read_or_extra_deadline(extra): + result = RepoSearch( + request(extra=extra), child(mirrored=False), child(mirrored=False) if extra else None + ) + result.request = replace(result.request, extra_deadline=asyncio.get_running_loop().time() - 1) + assert result.fresh() + + +async def test_composition_loss_stays_stale_after_failed_extra_is_dropped(): + result = RepoSearch(request(), child(mirrored=False), None) + result._lost = True + assert not result.fresh() diff --git a/tests/unit/test_source_search_chunk_keys.py b/tests/unit/test_source_search_chunk_keys.py new file mode 100644 index 0000000000..8a95fcdd80 --- /dev/null +++ b/tests/unit/test_source_search_chunk_keys.py @@ -0,0 +1,62 @@ +"""Search proof probes return exact live keys without fetching text.""" + +from __future__ import annotations + +import pytest + +from server.knowledge.store import source_candidates as store +from tests.unit.ch_fake import RecordingCH + +KEY = ("acl-" + "1" * 24, "gdrive:file#source", 3, 9, 0) + + +def row(key=KEY): + return dict( + zip(("namespace", "source_uri", "chunk_idx", "doc_version", "revision"), key, strict=True) + ) + + +@pytest.mark.parametrize("embedded_only", [False, True]) +async def test_key_probe_scopes_exact_live_model_keys_and_never_fetches_text( + monkeypatch, embedded_only +): + ch = RecordingCH().on("FROM loom.chunks", [row()]) + ch.install(monkeypatch, "server.knowledge.store.source_candidates") + assert await store.chunk_keys("acme", "fake-model", [KEY], embedded_only=embedded_only) == [KEY] + call = ch.calls[-1] + assert call.params == { + "org": "acme", + "nss": [KEY[0]], + "model": "fake-model", + "keys": [KEY], + "limit": 2, + } + selected = call.sql.split(" FROM ", 1)[0] + assert "content" not in selected and "context" not in selected and "tags" not in selected + assert "embedding_model = {model:String}" in call.sql + assert ("embedding_dim > 0" in call.sql) is embedded_only + assert "doc_version" in selected and "AS revision" in selected + assert "org = {org:String}" in call.sql and "LIMIT {limit:UInt32}" in call.sql + + +async def test_duplicate_physical_keys_are_preserved_for_proof_ambiguity_detection(monkeypatch): + ch = RecordingCH().on("FROM loom.chunks", [row(), row()]) + ch.install(monkeypatch, "server.knowledge.store.source_candidates") + assert await store.chunk_keys("acme", "fake-model", [KEY]) == [KEY, KEY] + + +async def test_empty_key_probe_has_no_database_io(monkeypatch): + ch = RecordingCH() + ch.install(monkeypatch, "server.knowledge.store.source_candidates") + assert await store.chunk_keys("acme", "fake-model", []) == [] + assert ch.calls == [] + + +async def test_key_probe_rejects_more_than_one_bounded_batch(monkeypatch): + ch = RecordingCH() + ch.install(monkeypatch, "server.knowledge.store.source_candidates") + with pytest.raises(ValueError): + await store.chunk_keys( + "acme", "fake-model", [(*KEY[:2], index, *KEY[3:]) for index in range(65)] + ) + assert ch.calls == [] diff --git a/tests/unit/test_source_search_fanout.py b/tests/unit/test_source_search_fanout.py new file mode 100644 index 0000000000..95a67d1bd6 --- /dev/null +++ b/tests/unit/test_source_search_fanout.py @@ -0,0 +1,198 @@ +"""Unified search retains checked knowledge after sibling work completes.""" + +from __future__ import annotations + +import asyncio +from types import SimpleNamespace + +from server.core.diagnostics import codes_only +from server.knowledge.api.models_conversations import ConversationSearchOutput +from server.knowledge.api.models_knowledge import KnowledgeSearchOutput, _SearchHit +from server.knowledge.app import knowledge_search, repo_docs, source_access +from server.knowledge.app.source_corpus import LostCorpus +from server.memory.api.models_search import MemorySearchOutput +from server.memory.app.loom_search import fanout + + +def hit(uri, score): + return _SearchHit( + source_uri=uri, + content=uri, + chunk_idx=0, + tags=[], + distance=1 - score, + similarity=score, + score=score, + namespace="home", + ) + + +def install(monkeypatch, *, ordinary_needs_widen=False, fail_ordinary_wider=False): + events = [] + calls = [] + ready = asyncio.Event() + state = {"revoked": False} + + async def resolve(inp): + return knowledge_search.SearchRequest(inp.model_copy(deep=True), (inp.namespace,), ()) + + async def prepare(org, namespaces): + events.append("prepare") + return source_access.ReadPlan(org, marked=True) + + async def leaf(request, plan): + events.append(("knowledge", codes_only())) + calls.append((request.input.top_k, plan.marked, request.namespaces)) + if fail_ordinary_wider and request.input.top_k > 2 and not plan.marked: + raise RuntimeError("PRIVATE-WIDER-FAILURE") + mixed = KnowledgeSearchOutput( + results=[hit("private", 0.9)], embedding_model="fake", reranked_by="private-rank" + ) + ordinary_rows = [hit("ordinary-a", 0.5), hit("ordinary-b", 0.4)] + if ordinary_needs_widen: + other_rule = hit("other-agent-rule", 0.8) + other_rule.tags = ["source-kind:assistant_turn", "agent:another-bot"] + ordinary_rows.insert(0, other_rule) + ordinary = KnowledgeSearchOutput( + results=ordinary_rows[: request.input.top_k], + embedding_model="fake", + stale_dropped=4, + ) + + async def check(): + if state["revoked"]: + raise LostCorpus() + + async def render(*_args): + events.append("ordinary") + return ordinary + + return knowledge_search.CheckedSearch( + mixed if plan.marked else ordinary, + SimpleNamespace(check=check, fresh=lambda: not state["revoked"]) + if plan.marked + else None, + SimpleNamespace(marked=plan.marked, render=render), + [], + 4, + ) + + original = repo_docs.run_repo_search + + async def repository(request, plan): + result = await original(request, plan) + ready.set() + return result + + async def memory(*_args, **_kwargs): + events.append(("memory", codes_only())) + await ready.wait() + state["revoked"] = True + return MemorySearchOutput(results=[], embedding_model="fake") + + async def namespaces(org, namespace, *_args, **_kwargs): + return [namespace], [] + + async def profile(*_args, **_kwargs): + events.append(("profile", codes_only())) + return [] + + async def conversations(*_args, **_kwargs): + return ConversationSearchOutput(hits=[]) + + async def tracker(*_args, **_kwargs): + return {} + + monkeypatch.setattr(knowledge_search, "resolve_search", resolve) + monkeypatch.setattr(knowledge_search, "run_checked_search", leaf) + monkeypatch.setattr(source_access, "prepare", prepare) + monkeypatch.setattr(fanout, "prepare", prepare) + monkeypatch.setattr(repo_docs, "run_repo_search", repository) + monkeypatch.setattr("server.auth.fanout.namespaces_to_search", namespaces) + monkeypatch.setattr(fanout, "memory_with_repo_decisions", memory) + monkeypatch.setattr(fanout, "search_profile", profile) + monkeypatch.setattr(fanout, "_conversation_leg", conversations) + monkeypatch.setattr(fanout, "tracker_leg", tracker) + monkeypatch.setattr(fanout, "request_scope", lambda: SimpleNamespace(narrowed=False)) + monkeypatch.setattr(fanout, "answer_first", lambda payload, *_args, **_kwargs: payload) + return SimpleNamespace(events=events, calls=calls, state=state) + + +async def run(): + return await fanout.search_sections( + org="acme", + namespace="home", + agent="reader", + query="cache", + top_k=2, + tags=[], + namespace_scope="this", + recipe="", + bodies="excerpt", + page="", + explain=False, + repo_namespace="", + tracker_plan=None, + ) + + +async def test_sibling_revocation_restores_rows_and_metadata_before_final_assembly(monkeypatch): + env = install(monkeypatch) + payload = await run() + know = payload["knowledge"] + assert [h["source_uri"] for h in know["results"]] == ["ordinary-a", "ordinary-b"] + assert know["reranked_by"] == "" and know["stale_dropped"] == 4 + assert env.events.count("ordinary") == 1 + + +async def test_parent_prepares_before_all_sibling_providers(monkeypatch): + env = install(monkeypatch) + await run() + prepared = env.events.index("prepare") + assert all(prepared < i and e[1] for i, e in enumerate(env.events) if isinstance(e, tuple)) + assert not codes_only() + + +async def test_revoked_first_pass_refills_from_one_ordinary_only_wider_query(monkeypatch): + from server.memory.domain.assistant_rules import hits_to_ask + + env = install(monkeypatch, ordinary_needs_widen=True) + payload = await run() + know = payload["knowledge"] + assert [h["source_uri"] for h in know["results"]] == ["ordinary-a", "ordinary-b"] + assert know["reranked_by"] == "" and know["stale_dropped"] == 4 + assert env.calls == [(2, True, ("home",)), (hits_to_ask(2), False, ("home",))] + assert env.events.count("prepare") == 1 + + +async def test_failed_ordinary_widen_keeps_ordinary_first_rows_and_metadata(monkeypatch, caplog): + env = install(monkeypatch, ordinary_needs_widen=True, fail_ordinary_wider=True) + payload = await run() + know = payload["knowledge"] + assert [h["source_uri"] for h in know["results"]] == ["ordinary-a"] + assert know["reranked_by"] == "" and know["stale_dropped"] == 4 + assert len(env.calls) == 2 and not env.calls[-1][1] + assert "PRIVATE-WIDER-FAILURE" not in caplog.text + + +async def test_base_scope_failure_leaves_other_search_sections_available(monkeypatch): + install(monkeypatch) + + async def fail(inp): + raise ValueError("knowledge scope refused") + + async def memory(*_args, **_kwargs): + return MemorySearchOutput(results=[], embedding_model="fake") + + async def profile(*_args, **_kwargs): + return [{"key": "ordinary-profile", "content": "still available"}] + + monkeypatch.setattr(knowledge_search, "resolve_search", fail) + monkeypatch.setattr(fanout, "memory_with_repo_decisions", memory) + monkeypatch.setattr(fanout, "search_profile", profile) + payload = await run() + assert payload["knowledge"]["error"] and payload["knowledge"]["results"] == [] + assert payload["memory"]["results"] == [] + assert payload["profile"]["results"] == [ + {"key": "ordinary-profile", "content": "still available"} + ] diff --git a/tests/unit/test_source_search_handler.py b/tests/unit/test_source_search_handler.py new file mode 100644 index 0000000000..4eacb5ead5 --- /dev/null +++ b/tests/unit/test_source_search_handler.py @@ -0,0 +1,256 @@ +"""Public search prepares identity before providers and routes only final checked pools.""" + +from __future__ import annotations + +from dataclasses import replace +from types import SimpleNamespace +from unittest.mock import AsyncMock + +import pytest + +from server.knowledge.api.models_knowledge import KnowledgeSearchInput +from server.knowledge.app import knowledge_search as app +from server.knowledge.app import source_access, source_search_passes +from server.knowledge.app.search import ChunkHit +from server.knowledge.app.source_access import Admitted +from server.knowledge.app.source_ranking import RankedHit + + +def hit(namespace, *, mirrored=False): + chunk = ChunkHit( + namespace, + "drive:allowed" if mirrored else "ordinary:" + namespace, + 0, + "allowed text" if mirrored else namespace, + [], + 0.05 if mirrored else 0.9 if namespace == "private" else 0.2, + score=0.95 if mirrored else 0.1 if namespace == "private" else 0.8, + ) + return RankedHit(chunk, Admitted(namespace, {}, {}) if mirrored else None) + + +@pytest.fixture +def world(monkeypatch): + phases, collected, counts = [], [], [] + pending = {"strong": False} + final = [[hit("private")], [hit("public")]] + plan = SimpleNamespace(org="acme", marked=True) + + class Embedder: + model_name = "fake" + + async def embed(self, _text): + phases.append("embed") + return [1.0] + + async def namespaces(*_args): + phases.append("namespaces") + return ["private", "public"] + + async def prepare(_org, selected): + assert selected == ["private", "public"] + phases.append("prepare") + return plan + + async def finish(): + phases.append("finish") + return final + + session = SimpleNamespace( + finish=finish, + proofs=SimpleNamespace(check=AsyncMock(), fresh=lambda: True, mirrored=True), + restrict_proofs=lambda selected: collected.append(selected), + ordinary=lambda: [[hit("private")], [hit("public")]], + ) + + def factory(_input, _embedder, _vector, _pool, dropped, **kwargs): + collected.append(kwargs.get("checked")) + + async def search(selected): + phases.append("search:" + ",".join(selected)) + counts.append(list(selected)) + dropped.count += 2 if selected == ["private"] else 7 + return [ + (ns, [hit(ns, mirrored=(ns == "private" and pending["strong"])).chunk]) + for ns in selected + ] + + return search + + async def rerank(_endpoint, _query, hits, _pool): + phases.append("rerank") + return hits, False + + monkeypatch.setattr(app, "get_embedder", Embedder) + monkeypatch.setattr(app, "readable_namespaces", namespaces) + monkeypatch.setattr(source_access, "prepare", prepare) + monkeypatch.setattr( + source_search_passes, "SearchPasses", lambda actual: session if actual is plan else None + ) + monkeypatch.setattr(app, "_namespaces_search", factory) + monkeypatch.setattr( + app.namespace_visibility, + "visibility_map", + AsyncMock(return_value={"private": "private", "public": "public"}), + ) + monkeypatch.setattr(app, "_rerank_endpoint", lambda _input: "synthetic-reranker") + monkeypatch.setattr(app, "_rerank", rerank) + monkeypatch.setattr(app.gaps_app, "record_miss", lambda **_kwargs: None) + request = KnowledgeSearchInput( + org="acme", + namespace="private", + namespaces=["private", "public"], + namespace_scope="all_mine", + query="document", + top_k=5, + collapse_sections=False, + ) + return phases, counts, collected, final, session, request, pending + + +async def test_source_participation_is_prepared_before_query_embedding_and_provider_use(world): + phases, counts, collected, _final, session, request, _pending = world + out = await app.handle_knowledge_search(request) + assert phases.index("namespaces") < phases.index("prepare") < phases.index("embed") + assert phases.index("finish") < phases.index("rerank") + assert counts == [["private"], ["public"]] and collected == [session, _final] + assert {item.content for item in out.results} == {"private", "public"} + assert out.stale_dropped == 9 + + +async def test_surviving_strong_private_mirror_emits_first_only_after_gathering_both_passes(world): + phases, counts, _collected, final, _session, request, pending = world + final[0] = [hit("private", mirrored=True)] + out = await app.handle_knowledge_search(request) + assert counts == [["private"], ["public"]] + assert [item.content for item in out.results] == ["allowed text"] + assert out.stale_dropped == 2 + assert phases[-1] == "finish" # one final hit needs no reranker + + +async def test_final_denial_and_initial_denial_have_identical_complete_public_replies(world): + phases, counts, _collected, final, _session, request, pending = world + pending["strong"] = True + late = await app.handle_knowledge_search(request) + phases.clear() + counts.clear() + pending["strong"] = False + # The controller barrier has removed a lost or failed provisional mirror; + # public conversion must use these same final pools for an initial denial. + final[:] = [[hit("private")], [hit("public")]] + initial = await app.handle_knowledge_search(request) + assert late.model_dump() == initial.model_dump() + assert counts == [["private"], ["public"]] + + +async def test_ordinary_stale_copy_is_removed_before_it_can_shadow_a_mirror(monkeypatch): + from server.core import pg + from server.knowledge.app import pg_serving, search_legs + from server.knowledge.app.search import HybridSearchQuery + + stale, live = hit("docs").chunk, hit("other").chunk + query = HybridSearchQuery("acme", ("docs", "other"), "fake", [1.0], 2) + pools = search_legs.LegPools(query, {"semantic": [stale, live]}, 2, 1.0) + monkeypatch.setattr(search_legs, "collect", AsyncMock(return_value=pools)) + monkeypatch.setattr(pg, "enabled", lambda: True) + + async def keep(_org, hits): + return [item for item in hits if item is not stale], int(stale in hits) + + monkeypatch.setattr(pg_serving, "keep_served", keep) + checked = SimpleNamespace(collect=AsyncMock()) + search = app._namespaces_search( + KnowledgeSearchInput( + org="acme", namespace="docs", query="document", search_mode="semantic" + ), + SimpleNamespace(model_name="fake"), + [1.0], + 0, + app._Dropped(), + checked=checked, + ) + await search(["docs", "other"]) + ordinary = checked.collect.await_args.args[1] + assert ordinary == {"semantic": [live]} + assert checked.collect.await_args.kwargs["fallback"] == [live] + + +async def test_ordinary_head_retired_after_legacy_search_is_removed_from_fallback(monkeypatch): + from server.core import pg + from server.knowledge.app import pg_serving, search_legs + from server.knowledge.app.search import HybridSearchQuery + + retired = hit("docs").chunk + pools = search_legs.LegPools( + HybridSearchQuery("acme", ("docs",), "fake", [1.0], 2), + {"semantic": [retired]}, + 2, + 1.0, + ) + monkeypatch.setattr(search_legs, "collect", AsyncMock(return_value=pools)) + monkeypatch.setattr(pg, "enabled", lambda: True) + calls = 0 + + async def keep(_org, hits): + nonlocal calls + calls += 1 + return (list(hits), 0) if calls == 1 else ([], len(hits)) + + monkeypatch.setattr(pg_serving, "keep_served", keep) + checked = SimpleNamespace(collect=AsyncMock()) + dropped = app._Dropped() + search = app._namespaces_search( + KnowledgeSearchInput( + org="acme", namespace="docs", query="document", search_mode="semantic" + ), + SimpleNamespace(model_name="fake"), + [1.0], + 0, + dropped, + checked=checked, + ) + await search(["docs"]) + assert calls == 2 + assert checked.collect.await_args.args[1] == {"semantic": []} + assert checked.collect.await_args.kwargs["fallback"] == [] + assert dropped.count == 1 + + +async def test_new_serving_version_cannot_keep_the_retired_fallback_version(monkeypatch): + from server.core import pg + from server.knowledge.app import pg_serving, search_legs + from server.knowledge.app.search import HybridSearchQuery + + old = replace(hit("docs").chunk, doc_version=10, revision=1) + new = replace(old, doc_version=20, revision=2, content="new version") + pools = search_legs.LegPools( + HybridSearchQuery("acme", ("docs",), "fake", [1.0], 2), + {"semantic": [old, new]}, + 2, + 1.0, + ) + monkeypatch.setattr(search_legs, "collect", AsyncMock(return_value=pools)) + monkeypatch.setattr(pg, "enabled", lambda: True) + calls = 0 + + async def keep(_org, hits): + nonlocal calls + calls += 1 + return (list(hits), 0) if calls == 1 else ([item for item in hits if item is new], 1) + + monkeypatch.setattr(pg_serving, "keep_served", keep) + checked = SimpleNamespace(collect=AsyncMock()) + search = app._namespaces_search( + KnowledgeSearchInput( + org="acme", namespace="docs", query="document", search_mode="semantic" + ), + SimpleNamespace(model_name="fake"), + [1.0], + 0, + app._Dropped(), + checked=checked, + ) + await search(["docs"]) + assert calls == 2 + assert checked.collect.await_args.args[1] == {"semantic": [new]} + assert checked.collect.await_args.kwargs["fallback"] == [] diff --git a/tests/unit/test_source_search_passes.py b/tests/unit/test_source_search_passes.py new file mode 100644 index 0000000000..6add7245dc --- /dev/null +++ b/tests/unit/test_source_search_passes.py @@ -0,0 +1,215 @@ +"""Late permission changes cannot leave provisional mirrors controlling a search route.""" + +from __future__ import annotations + +import asyncio +from dataclasses import asdict, replace +from datetime import UTC, datetime +from types import SimpleNamespace +from unittest.mock import AsyncMock + +import pytest + +from server.core.vectors.private_first import best_similarity +from server.knowledge.app import source_search_passes as app +from server.knowledge.app.search import ChunkHit, HybridSearchQuery +from server.knowledge.app.source_access import Admitted +from server.knowledge.app.source_search import Hydrated + + +def mirror(namespace): + candidate = { + "namespace": "acl-" + "1" * 24, + "source_uri": "drive:" + namespace + "#11111111-1111-4111-8111-111111111111", + "chunk_idx": 0, + "doc_version": 10, + "revision": 0, + "distance": 0.05, + "lexical": 0.0, + "matched": [], + } + return Hydrated( + Admitted( + namespace, + candidate, + {"version": 10, "revision": 0, "ingested_at": datetime(2025, 1, 1, tzinfo=UTC)}, + ), + {"content": "private text"}, + ) + + +def ordinary(namespace): + distance = 0.9 if namespace == "private" else 0.2 + return ChunkHit( + namespace, "ordinary:" + namespace, 0, namespace, [], distance, score=1 - distance + ) + + +def routed(passes): + first = [(r.chunk.namespace, [r.chunk]) for r in passes[0]] + selected = passes[:1] if best_similarity(first, lambda hit: not hit.noise) >= 0.8 else passes + return [dict(asdict(r.chunk), mirrored=r.mirrored) for pool in selected for r in pool] + + +@pytest.fixture +def world(monkeypatch): + plan = SimpleNamespace(org="acme", failed=False, unread=False) + source = {namespace: mirror(namespace) for namespace in ("private", "public")} + seen = [] + + async def discover(_plan, query, **_kwargs): + namespace = query.namespaces[0] + seen.append(namespace) + return {"semantic": [source[namespace].admitted]} if namespace in source else {} + + async def hydrate(_plan, pools, **_kwargs): + return {leg: [source[item.namespace] for item in pool] for leg, pool in pools.items()} + + async def recheck(_plan, pools): + return pools + + monkeypatch.setattr(app, "discover", AsyncMock(side_effect=discover)) + monkeypatch.setattr(app, "hydrate", AsyncMock(side_effect=hydrate)) + monkeypatch.setattr(app, "recheck", AsyncMock(side_effect=recheck)) + + async def collect(session, namespace): + hit = ordinary(namespace) + assert ( + await session.collect( + HybridSearchQuery("acme", (namespace,), "fake", [1.0], 2), + {"semantic": [hit]}, + legs=("semantic",), + fallback=[hit], + top_k=1, + ) + is None + ) + + return plan, source, seen, collect + + +async def test_all_possible_passes_are_collected_before_final_route_selection(world): + plan, source, seen, collect = world + del source["public"] + session = app.SearchPasses(plan) + await collect(session, "private") + await collect(session, "public") + final = await session.finish() + assert seen == ["private", "public"] + assert len(routed(final)) == 1 and routed(final)[0]["mirrored"] + assert final[1][0].chunk.content == "public" + + +@pytest.mark.parametrize("failure", ["denied", "expired", "candidate_failure"]) +async def test_discarded_private_mirror_has_same_complete_fallback_as_initially_denied( + world, monkeypatch, failure +): + plan, source, _seen, collect = world + del source["public"] + late = app.SearchPasses(plan) + await collect(late, "private") + await collect(late, "public") + + async def changed(_plan, pools): + if failure == "candidate_failure": + plan.failed = True + return {} + return { + leg: [item for item in pool if item.namespace != "private"] + for leg, pool in pools.items() + } + + monkeypatch.setattr(app, "recheck", AsyncMock(side_effect=changed)) + actual = routed(await late.finish()) + plan.failed = False + del source["private"] + initial = app.SearchPasses(plan) + await collect(initial, "private") + await collect(initial, "public") + expected = routed(await initial.finish()) + assert actual == expected + assert [row["content"] for row in actual] == ["private", "public"] + assert not plan.unread + + +@pytest.mark.parametrize("unread", [False, True]) +async def test_second_pass_failure_removes_first_pass_mirrors_too(world, monkeypatch, unread): + plan, _source, seen, collect = world + session = app.SearchPasses(plan) + await collect(session, "private") + original = app.discover.side_effect + + async def fail(*args, **kwargs): + await original(*args, **kwargs) + plan.failed, plan.unread = True, unread + return {} + + monkeypatch.setattr(app, "discover", AsyncMock(side_effect=fail)) + await collect(session, "public") + out = await session.finish() + assert seen == ["private", "public"] + assert all(not hit.mirrored for pool in out for hit in pool) + assert [pool[0].chunk.content for pool in out] == ["private", "public"] + + +async def test_prior_candidate_failure_does_not_skip_a_statically_selected_pass(world): + plan, _source, seen, collect = world + plan.failed = True + session = app.SearchPasses(plan) + await collect(session, "private") + await collect(session, "public") + assert seen == ["private", "public"] + assert all(not r.mirrored for pool in await session.finish() for r in pool) + + +async def test_final_proof_refresh_preserves_the_checked_candidates_own_scores(world, monkeypatch): + plan, _source, _seen, collect = world + session = app.SearchPasses(plan) + await collect(session, "private") + + async def latest(_plan, pools): + return { + leg: [ + replace( + item, + candidate={**item.candidate, "distance": 0.99}, + document={**item.document, "version": 11}, + ) + for item in pool + ] + for leg, pool in pools.items() + } + + monkeypatch.setattr(app, "recheck", AsyncMock(side_effect=latest)) + [[hit]] = await session.finish() + assert hit.chunk.distance == 0.05 + assert hit.admitted.document == {**_source["private"].admitted.document, "version": 11} + assert hit.admitted.candidate["distance"] == 0.05 + + +async def test_late_final_ranking_error_discards_all_mirrors(world, monkeypatch): + plan, _source, _seen, collect = world + session = app.SearchPasses(plan) + await collect(session, "private") + await collect(session, "public") + rank = app.rank + + def broken(ordinary, mirrored, **kwargs): + if any(item.admitted.namespace == "public" for pool in mirrored.values() for item in pool): + raise ValueError("private title") + return rank(ordinary, mirrored, **kwargs) + + monkeypatch.setattr(app, "rank", broken) + assert all(not r.mirrored for pool in await session.finish() for r in pool) + assert plan.failed and not plan.unread + + +async def test_collection_cancellation_propagates_without_becoming_a_private_failure( + world, monkeypatch +): + plan, _source, _seen, collect = world + session = app.SearchPasses(plan) + monkeypatch.setattr(app, "discover", AsyncMock(side_effect=asyncio.CancelledError)) + with pytest.raises(asyncio.CancelledError): + await collect(session, "private") + assert not plan.failed and not plan.unread diff --git a/tests/unit/test_source_search_pool.py b/tests/unit/test_source_search_pool.py new file mode 100644 index 0000000000..1aaa89f8b8 --- /dev/null +++ b/tests/unit/test_source_search_pool.py @@ -0,0 +1,287 @@ +"""Admission precedes mirror leg limits, duplicate removal and fusion ranks.""" + +from __future__ import annotations + +import asyncio +from contextlib import asynccontextmanager +from types import SimpleNamespace + +import pytest + +from server.knowledge.app import source_search as app +from server.knowledge.app.search import HybridSearchQuery +from server.knowledge.app.source_access import Admitted + +MIRROR = "acl-" + "1" * 24 +SID = "11111111-1111-4111-8111-111111111111" + + +def row(i, *, uri=None, admitted=True): + return { + "namespace": MIRROR, + "source_uri": (uri or f"gdrive:{i}") + "#" + SID, + "chunk_idx": 0, + "doc_version": 1, + "revision": 0, + "distance": i / 10000, + "lexical": 0.0, + "matched": [], + "admitted": admitted, + } + + +@pytest.fixture +def world(monkeypatch): + sizes, opened, closed = [], [], [] + plan = SimpleNamespace( + org="acme", + sources={(MIRROR, SID): "docs"}, + discovery_sources={(MIRROR, SID): "docs"}, + reader=None, + discovery_reader=None, + failed=False, + unread=False, + ) + plan.listing_current = lambda _namespace, _source: True + plan.current = lambda item: plan.listing_current(item.document["namespace"], SID) + + async def check(batch, *, chunks): + assert chunks + sizes.append(len(batch)) + return [ + Admitted( + "docs", + r, + {"namespace": MIRROR, "source_uri": r["source_uri"], "tags": ["source-id:" + SID]}, + ) + for r in batch + if r["admitted"] and not plan.failed + ] + + plan.check = check + monkeypatch.setattr(app.pg, "enabled", lambda: False) + q = HybridSearchQuery("acme", ("docs",), "fake", [1.0], 2, tokens=["token"], keys=["key"]) + + def install(factory): + @asynccontextmanager + async def candidates(sql, _params): + leg = ( + "lexical" + if "lexical DESC" in sql + else "keys" + if "length(matched)" in sql + else "semantic" + ) + opened.append(leg) + try: + yield factory(leg) + finally: + closed.append(leg) + + monkeypatch.setattr(app.store, "candidates", candidates) + + return plan, q, sizes, opened, closed, install + + +async def test_scan_passes_thousands_of_denied_candidates_in_bounded_batches(world): + plan, q, sizes, opened, closed, install = world + + async def rows(_leg): + for i in range(6010): + yield row(i, admitted=i >= 6000) + + install(rows) + out = await app.collect_leg(plan, q, "semantic", limit=2) + assert [r.candidate["source_uri"] for r in out] == ["gdrive:6000#" + SID, "gdrive:6001#" + SID] + assert max(sizes) <= 64 and len(sizes) > 90 + assert opened == closed == ["semantic"] + + +async def test_each_search_pass_discovers_only_its_requested_original_namespaces( + world, monkeypatch +): + plan, q, _sizes, _opened, _closed, _install = world + other = "acl-" + "2" * 24 + other_sid = "22222222-2222-4222-8222-222222222222" + plan.discovery_sources[(other, other_sid)] = "other-docs" + seen = [] + + @asynccontextmanager + async def candidates(_sql, params): + seen.append(params) + + async def rows(): + yield row(0) + + yield rows() + + monkeypatch.setattr(app.store, "candidates", candidates) + assert len(await app.collect_leg(plan, q, "semantic", limit=2)) == 1 + assert seen[0]["nss"] == [MIRROR] + assert seen[0]["source_tags"] == ["source-id:" + SID] + + +async def test_ordinary_families_and_duplicate_copies_do_not_consume_admitted_pool(world): + plan, q, _sizes, _opened, closed, install = world + + async def rows(_leg): + for i, uri in enumerate(("gdrive:a", "gdrive:a", "gdrive:b", "gdrive:c")): + yield row(i, uri=uri) + + install(rows) + out = await app.collect_leg(plan, q, "semantic", limit=2, ordinary={("docs", "gdrive:a")}) + assert [r.candidate["source_uri"] for r in out] == ["gdrive:b#" + SID, "gdrive:c#" + SID] + assert closed == ["semantic"] + + +async def test_late_candidate_failure_discards_earlier_batches_without_unread(world): + plan, q, _sizes, _opened, closed, install = world + check = plan.check + + async def fail(batch, *, chunks): + if batch[0]["distance"] >= 0.0064: + plan.failed = True + return [] + return await check(batch, chunks=chunks) + + plan.check = fail + + async def rows(_leg): + for i in range(70): + yield row(i) + + install(rows) + assert await app.collect_leg(plan, q, "semantic", limit=100) == [] + assert plan.failed and not plan.unread and closed == ["semantic"] + + +async def test_late_discovery_failure_discards_earlier_batches_and_marks_unread(world): + plan, q, _sizes, _opened, closed, install = world + + async def rows(_leg): + for i in range(64): + yield row(i) + raise RuntimeError("synthetic private backend error") + + install(rows) + assert await app.collect_leg(plan, q, "semantic", limit=100) == [] + assert plan.failed and plan.unread and closed == ["semantic"] + + +async def test_selected_discovery_streams_open_even_after_another_candidate_failure(world): + plan, q, _sizes, opened, closed, install = world + + async def fail(_batch, *, chunks): + plan.failed = True + return [] + + plan.check = fail + + async def rows(_leg): + yield row(0) + + install(rows) + assert await app.discover(plan, q, legs=("semantic", "lexical", "keys"), limit=2) == {} + assert sorted(opened) == sorted(closed) == ["keys", "lexical", "semantic"] + assert plan.failed and not plan.unread + + +async def test_cancellation_closes_stream_without_becoming_an_unread_failure(world): + plan, q, _sizes, _opened, closed, install = world + + async def rows(_leg): + yield row(0) + raise asyncio.CancelledError + + install(rows) + with pytest.raises(asyncio.CancelledError): + await app.collect_leg(plan, q, "semantic", limit=100) + assert closed == ["semantic"] and not plan.unread + + +async def test_final_recheck_drops_a_retained_pool_after_permissions_expire(world): + plan, q, sizes, _opened, _closed, install = world + check = plan.check + + async def checked(batch, *, chunks): + if sizes: + return [] + return await check(batch, chunks=chunks) + + plan.check = checked + + async def rows(_leg): + yield row(0) + + install(rows) + out = await app.discover(plan, q, legs=("semantic",), limit=1) + assert out == {"semantic": []} + assert not plan.unread + + +async def test_final_candidate_failure_discards_every_discovery_pool(world): + plan, q, sizes, _opened, _closed, install = world + check = plan.check + + async def checked(batch, *, chunks): + if len(sizes) >= 3: + plan.failed = True + return [] + return await check(batch, chunks=chunks) + + plan.check = checked + + async def rows(_leg): + yield row(0) + + install(rows) + out = await app.discover(plan, q, legs=("semantic", "lexical", "keys"), limit=1) + assert out == {} and plan.failed and not plan.unread + + +async def test_expiry_during_final_other_batch_also_evicts_earlier_rechecked_rows(world): + plan, q, sizes, _opened, _closed, install = world + check = plan.check + expired = False + + async def checked(batch, *, chunks): + nonlocal expired + found = await check(batch, chunks=chunks) + if len(sizes) == 4: + expired = True + return found + + plan.check = checked + plan.listing_current = lambda _namespace, _source: not expired + + async def rows(_leg): + for i in range(100): + yield row(i) + + install(rows) + out = await app.discover(plan, q, legs=("semantic",), limit=100) + assert expired and out == {"semantic": []} + assert not plan.unread + + +async def test_later_discovery_still_opens_after_conditional_source_removal(world): + plan, q, _sizes, opened, closed, install = world + + async def check(_batch, *, chunks): + plan.sources = {} + plan.reader = None + plan.failed = True + return [] + + plan.check = check + + async def rows(leg): + if leg == "lexical": + raise RuntimeError("unconditional backend failure") + yield row(0) + + install(rows) + assert await app.collect_leg(plan, q, "semantic", limit=2) == [] + assert await app.collect_leg(plan, q, "lexical", limit=2) == [] + assert opened == closed == ["semantic", "lexical"] + assert plan.failed and plan.unread diff --git a/tests/unit/test_source_search_proofs.py b/tests/unit/test_source_search_proofs.py new file mode 100644 index 0000000000..894b9d7f99 --- /dev/null +++ b/tests/unit/test_source_search_proofs.py @@ -0,0 +1,221 @@ +"""Search proofs retain no text and renew live chunks between document checks.""" + +from __future__ import annotations + +import asyncio +from dataclasses import replace +from datetime import UTC, datetime +from types import SimpleNamespace +from unittest.mock import AsyncMock + +import pytest + +from server.knowledge.app.source_access import Admitted +from server.knowledge.app.source_corpus import LostCorpus +from server.knowledge.domain.serving import Serving +from server.knowledge.store import source_candidates as store + +NS = "acl-" + "1" * 24 +URI = "gdrive:file#11111111-1111-4111-8111-111111111111" +MODEL = "fake-model" + + +def key(item): + row = item.candidate + return ( + row["namespace"], + row["source_uri"], + row["chunk_idx"], + row["doc_version"], + row["revision"], + ) + + +@pytest.fixture +def world(monkeypatch): + items = tuple( + Admitted( + "team", + { + "namespace": NS, + "source_uri": URI, + "chunk_idx": index, + "doc_version": 9, + "revision": 0, + }, + { + "namespace": NS, + "source_uri": URI, + "tags": [], + "version": 10, + "revision": 0, + "ingested_at": datetime(2025, 1, 1, tzinfo=UTC), + }, + serving=Serving(False, 0, 0, 9), + ) + for index in range(2) + ) + events = [] + + async def documents(candidates): + assert candidates == [{"namespace": NS, "source_uri": URI}] + events.append("documents") + return [items[0]] + + async def keys(org, model, selected, *, embedded_only=True): + assert (org, model) == ("acme", MODEL) + events.append("chunks") + return list(selected) + + plan = SimpleNamespace( + org="acme", + failed=False, + unread=False, + current=lambda _item: True, + check=AsyncMock(side_effect=documents), + ) + monkeypatch.setattr(store, "chunk_keys", AsyncMock(side_effect=keys)) + return plan, items, events + + +def proof(world, items=None): + from server.knowledge.app.source_search_proofs import SearchProofs + + plan, initial, _events = world + return SearchProofs(plan, MODEL, initial if items is None else tuple(items)) + + +async def test_search_proof_checks_document_then_live_model_keys_then_documents(world): + checked = proof(world) + await checked.check() + assert world[2] == ["documents", "chunks", "documents"] + store.chunk_keys.assert_awaited_once_with( + "acme", MODEL, [key(item) for item in world[1]], embedded_only=True + ) + assert not checked.invalid + + +@pytest.mark.parametrize("lost", ["missing", "duplicate", "unexpected", "backend"]) +async def test_bad_live_key_evidence_invalidates_the_whole_proof_monotonically(world, lost): + checked = proof(world) + selected = [key(item) for item in world[1]] + store.chunk_keys.side_effect = None + if lost == "backend": + store.chunk_keys.side_effect = RuntimeError("private backend information") + else: + store.chunk_keys.return_value = { + "missing": selected[:1], + "duplicate": [*selected, selected[0]], + "unexpected": [*selected[:1], (NS, URI, 99, 9, 0)], + }[lost] + with pytest.raises(LostCorpus, match="^document access changed$"): + await checked.check() + assert checked.invalid and not world[0].unread + calls = store.chunk_keys.await_count + store.chunk_keys.side_effect = None + store.chunk_keys.return_value = selected + with pytest.raises(LostCorpus): + await checked.check() + assert store.chunk_keys.await_count == calls + + +async def test_permission_loss_during_key_probe_is_detected_by_final_document_renewal(world): + checked = proof(world) + + async def revoke(_org, _model, selected, *, embedded_only=True): + world[0].check.side_effect = None + world[0].check.return_value = [] + return list(selected) + + store.chunk_keys.side_effect = revoke + with pytest.raises(LostCorpus): + await checked.check() + assert checked.invalid + + +async def test_expected_document_and_chunk_identities_do_not_alias_mutable_input(world): + checked = proof(world) + world[1][0].candidate["doc_version"] = 100 + world[1][0].document["version"] = 100 + with pytest.raises(LostCorpus): + await checked.check() + + +async def test_metadata_only_head_version_can_keep_older_serving_chunks(world): + checked = proof(world) + assert world[1][0].document["version"] > world[1][0].candidate["doc_version"] + await checked.check() + + +@pytest.mark.parametrize("change", ["revision", "chunks_version", "chunks_revision", "deleted"]) +async def test_constructor_requires_an_initially_served_chunk_relationship(world, change): + first = world[1][0] + if change == "revision": + bad = replace(first, candidate={**first.candidate, "revision": 99}) + else: + bad = replace( + first, serving=first.serving._replace(**{change: True if change == "deleted" else 99}) + ) + checked = proof(world, [bad]) + with pytest.raises(LostCorpus): + await checked.check() + assert checked.invalid + world[0].check.assert_not_awaited() + store.chunk_keys.assert_not_awaited() + + +async def test_inconsistent_document_evidence_never_chooses_the_last_identity(world): + first, second = world[1] + bad = replace(second, document={**second.document, "version": 99}) + checked = proof(world, [first, bad]) + with pytest.raises(LostCorpus): + await checked.check() + world[0].check.assert_not_awaited() + store.chunk_keys.assert_not_awaited() + + +async def test_key_batches_are_bounded_and_document_renewal_follows_all_batches(world): + first = world[1][0] + many = [ + replace(first, candidate={**first.candidate, "chunk_idx": index}) for index in range(65) + ] + checked = proof(world, many) + await checked.check() + assert [len(call.args[2]) for call in store.chunk_keys.await_args_list] == [64, 1] + assert world[2] == ["documents", "chunks", "chunks", "documents"] + + +async def test_empty_proof_does_no_conditional_io_even_after_plan_failure(world): + world[0].failed = world[0].unread = True + checked = proof(world, []) + await checked.check() + world[0].check.assert_not_awaited() + store.chunk_keys.assert_not_awaited() + + +async def test_key_probe_cancellation_propagates_without_a_second_document_read(world): + checked = proof(world) + store.chunk_keys.side_effect = asyncio.CancelledError() + with pytest.raises(asyncio.CancelledError): + await checked.check() + assert world[0].check.await_count == 1 + + +async def test_full_check_sequences_are_serialized(world): + checked = proof(world) + entered, release = asyncio.Event(), asyncio.Event() + + async def pause(_org, _model, selected, *, embedded_only=True): + entered.set() + await release.wait() + return list(selected) + + store.chunk_keys.side_effect = pause + first = asyncio.create_task(checked.check()) + await entered.wait() + second = asyncio.create_task(checked.check()) + await asyncio.sleep(0) + assert world[0].check.await_count == 1 + release.set() + await asyncio.gather(first, second) + assert world[0].check.await_count == 4 diff --git a/tests/unit/test_source_search_provider_boundaries.py b/tests/unit/test_source_search_provider_boundaries.py new file mode 100644 index 0000000000..f137b855e6 --- /dev/null +++ b/tests/unit/test_source_search_provider_boundaries.py @@ -0,0 +1,169 @@ +"""Permission loss while a provider waits cannot survive into public search output.""" + +from __future__ import annotations + +import asyncio +from datetime import UTC, datetime +from types import SimpleNamespace +from unittest.mock import AsyncMock + +import pytest + +from server.knowledge.api.models_knowledge import KnowledgeSearchInput +from server.knowledge.app import knowledge_search as app +from server.knowledge.app import source_access, source_search_passes +from server.knowledge.app.search import ChunkHit, HybridSearchQuery +from server.knowledge.app.source_access import Admitted +from server.knowledge.app.source_search import Hydrated +from server.knowledge.domain.serving import Serving +from tests.unit.ch_fake import RecordingCH + + +@pytest.mark.parametrize("provider", ["rerank", "spans"]) +@pytest.mark.parametrize("boundary", ["provider", "outer"]) +async def test_lost_provider_proof_rebuilds_the_whole_ordinary_search_reply( + monkeypatch, provider, boundary +): + state = {"allowed": True, "revoke": boundary == "provider"} + candidate = { + "namespace": "acl-" + "1" * 24, + "source_uri": "gdrive:private#11111111-1111-4111-8111-111111111111", + "chunk_idx": 0, + "doc_version": 9, + "revision": 0, + "distance": 0.05, + "lexical": 0.0, + "matched": [], + } + admitted = Admitted( + "team", + candidate, + { + "namespace": candidate["namespace"], + "source_uri": candidate["source_uri"], + "tags": [], + "version": 10, + "revision": 0, + "ingested_at": datetime(2025, 1, 1, tzinfo=UTC), + }, + serving=Serving(False, 0, 0, 9), + ) + hydrated = Hydrated(admitted, {"content": "Private provider text"}) + + async def check(_candidates, **_kwargs): + return [admitted] if state["allowed"] else [] + + plan = SimpleNamespace( + org="acme", + marked=True, + failed=False, + unread=False, + current=lambda _item: True, + check=AsyncMock(side_effect=check), + ) + + class Embedder: + model_name = "fake-model" + + async def embed(self, _query): + return [1.0] + + ordinary = [ + ChunkHit( + "team", + f"ordinary:{index}", + 0, + f"Ordinary {index}", + [], + 0.4 + index / 10, + score=0.6 - index / 10, + ) + for index in range(2) + ] + + async def recheck(_plan, pools): + return pools if state["allowed"] else {} + + def factory(_input, embedder, vector, _pool, _dropped, *, checked): + async def search(namespaces): + await checked.collect( + HybridSearchQuery("acme", tuple(namespaces), embedder.model_name, vector, 3), + {"semantic": ordinary}, + legs=("semantic",), + fallback=ordinary, + top_k=3, + ) + return [("team", ordinary)] + + return search + + async def rerank(_endpoint, _query, hits, _pool): + await asyncio.sleep(0) + mirrored = any(hit.content == hydrated.row["content"] for hit in hits) + if state["revoke"]: + state["allowed"] = False + return (list(reversed(hits)), True) if mirrored else (hits, False) + + async def spans(_embedder, _vector, hits, *, proofs=None): + await asyncio.sleep(0) + mirrored = any(hit.content == hydrated.row["content"] for hit in hits) + if state["revoke"]: + state["allowed"] = False + for hit in hits: + hit.span = "Mirror-influenced span" if mirrored else "Ordinary span" + + monkeypatch.setattr(app, "readable_namespaces", AsyncMock(return_value=["team"])) + monkeypatch.setattr(source_access, "prepare", AsyncMock(return_value=plan)) + monkeypatch.setattr(app, "get_embedder", Embedder) + monkeypatch.setattr(app, "_namespaces_search", factory) + monkeypatch.setattr( + app, "_rerank_endpoint", lambda _input: "synthetic" if provider == "rerank" else "" + ) + monkeypatch.setattr(app, "_rerank", rerank) + monkeypatch.setattr(app, "_narrow_spans", spans) + monkeypatch.setattr(app.gaps_app, "record_miss", lambda **_kwargs: None) + monkeypatch.setattr( + source_search_passes, "discover", AsyncMock(return_value={"semantic": [admitted]}) + ) + monkeypatch.setattr( + source_search_passes, "hydrate", AsyncMock(return_value={"semantic": [hydrated]}) + ) + monkeypatch.setattr(source_search_passes, "recheck", AsyncMock(side_effect=recheck)) + ch = RecordingCH().on( + "FROM loom.chunks", + [ + { + k: candidate[k] + for k in ( + "namespace", + "source_uri", + "chunk_idx", + "doc_version", + "revision", + ) + } + ], + ) + ch.install(monkeypatch, "server.knowledge.store.source_candidates") + request = KnowledgeSearchInput( + org="acme", + namespace="team", + namespaces=["team"], + namespace_scope="this", + query="document", + top_k=3, + collapse_sections=False, + narrow_spans=provider == "spans", + ) + if boundary == "provider": + late = await app.handle_knowledge_search(request) + else: + checked = await app.checked_knowledge_search(request) + state["allowed"] = False + late, concurrent = await asyncio.gather(checked.current(), checked.current()) + assert late is concurrent and await checked.current() is late + state["allowed"] = state["revoke"] = False + initial = await app.handle_knowledge_search(request) + assert late.model_dump() == initial.model_dump() + assert {hit.source_uri for hit in late.results} == {"ordinary:0", "ordinary:1"} + assert not late.reranked_by diff --git a/tests/unit/test_source_search_request.py b/tests/unit/test_source_search_request.py new file mode 100644 index 0000000000..a1ff5d5704 --- /dev/null +++ b/tests/unit/test_source_search_request.py @@ -0,0 +1,82 @@ +"""Search recipes snapshot authorized scopes before shared-plan provider work.""" + +from __future__ import annotations + +from types import SimpleNamespace +from unittest.mock import AsyncMock, Mock + +import pytest + +from server.core.diagnostics import codes_only +from server.knowledge.api.models_knowledge import KnowledgeSearchInput +from server.knowledge.app import knowledge_search as app +from server.knowledge.app import source_access +from server.knowledge.app.search import ChunkHit + + +@pytest.fixture +def world(monkeypatch): + import server.auth.gateway as gateway + + monkeypatch.setattr(gateway, "is_end_user", lambda _: False) + readable = AsyncMock(return_value=["team"]) + embedder = SimpleNamespace(model_name="fake", embed=AsyncMock(return_value=[1.0])) + ordinary = [("team", [ChunkHit("team", "ordinary:one", 0, "Ordinary", [], 0.1, score=0.9)])] + monkeypatch.setattr(app, "readable_namespaces", readable) + monkeypatch.setattr(app, "get_embedder", Mock(return_value=embedder)) + monkeypatch.setattr(app, "_search_private_first", AsyncMock(return_value=ordinary)) + monkeypatch.setattr(app, "_namespaces_search", Mock()) + monkeypatch.setattr(source_access, "prepare", AsyncMock()) + return readable, embedder + + +async def test_resolved_recipe_is_snapshotted_and_execution_never_resolves_scope_again(world): + readable, embedder = world + original = KnowledgeSearchInput( + org="acme", namespace="@me", namespaces=["team"], query="Question", rerank="none" + ) + recipe = await app.resolve_search(original) + original.namespaces.append("another-team") + original.query = "Changed" + readable.side_effect = AssertionError("authorized scope already resolved") + result = await app.run_checked_search(recipe, source_access.ReadPlan("acme")) + assert recipe.namespaces == ("team",) and recipe.input.namespaces == ["team"] + assert recipe.input.query == "Question" and not result.lost + assert result.output.results[0].source_uri == "ordinary:one" + embedder.embed.assert_awaited_once_with("Question") + source_access.prepare.assert_not_awaited() + assert await result.current() is await result.ordinary() is result.output + + +async def test_recipe_execution_refuses_another_org_before_providers_or_document_reads(world): + _readable, embedder = world + recipe = await app.resolve_search( + KnowledgeSearchInput(org="acme", namespace="team", namespaces=["team"], query="Question") + ) + with pytest.raises(ValueError, match="document read scope changed"): + await app.run_checked_search(recipe, source_access.ReadPlan("another-org")) + embedder.embed.assert_not_awaited() + app._search_private_first.assert_not_awaited() + + +@pytest.mark.parametrize("marked", [False, True]) +async def test_entire_recipe_execution_is_private_when_the_shared_plan_is_marked( + world, monkeypatch, marked +): + recipe = await app.resolve_search( + KnowledgeSearchInput(org="acme", namespace="team", namespaces=["team"], query="Question") + ) + expected = object() + + async def execute(actual, plan): + assert actual is recipe and plan.org == "acme" + assert codes_only() is marked + return expected + + monkeypatch.setattr(app, "_run_search", execute) + assert not codes_only() + assert ( + await app.run_checked_search(recipe, source_access.ReadPlan("acme", marked=marked)) + is expected + ) + assert not codes_only() diff --git a/tests/unit/test_source_search_result.py b/tests/unit/test_source_search_result.py new file mode 100644 index 0000000000..c15d00de43 --- /dev/null +++ b/tests/unit/test_source_search_result.py @@ -0,0 +1,126 @@ +"""Search renewal owns one fallback, and span helpers preserve proof loss.""" + +from __future__ import annotations + +import asyncio +from types import SimpleNamespace +from unittest.mock import AsyncMock + +import pytest + +from server.knowledge.api.models_knowledge import KnowledgeSearchOutput +from server.knowledge.app import knowledge_search as app +from server.knowledge.app.search import ChunkHit +from server.knowledge.app.source_corpus import LostCorpus + + +@pytest.mark.parametrize( + "failure", [RuntimeError("provider unavailable"), asyncio.CancelledError()] +) +async def test_failed_ordinary_fallback_is_never_retried_or_replaced_by_the_old_reply(failure): + initial = KnowledgeSearchOutput(results=[], embedding_model="fake-model") + renderer = SimpleNamespace(marked=True, render=AsyncMock(side_effect=failure)) + proofs = SimpleNamespace(check=AsyncMock(side_effect=LostCorpus())) + result = app.CheckedSearch(initial, proofs, renderer, [], 0) + with pytest.raises(type(failure)): + await result.current() + with pytest.raises(LostCorpus, match="^document access changed$"): + await result.current() + renderer.render.assert_awaited_once() + assert result.marked + + +async def test_concurrent_renewals_render_and_cache_one_complete_ordinary_fallback(): + initial = KnowledgeSearchOutput(results=[], embedding_model="fake-model") + fallback = KnowledgeSearchOutput(results=[], embedding_model="fake-model", stale_dropped=7) + entered, release = asyncio.Event(), asyncio.Event() + + async def render(*_args): + entered.set() + await release.wait() + return fallback + + renderer = SimpleNamespace(marked=True, render=AsyncMock(side_effect=render)) + proofs = SimpleNamespace(check=AsyncMock(side_effect=LostCorpus())) + result = app.CheckedSearch(initial, proofs, renderer, [], 7) + first = asyncio.create_task(result.current()) + await entered.wait() + second = asyncio.create_task(result.current()) + await asyncio.sleep(0) + renderer.render.assert_awaited_once_with([], 7) + release.set() + assert await first is await second is await result.current() is fallback + renderer.render.assert_awaited_once() + + +async def test_forced_ordinary_fallback_is_cached_without_readmitting_valid_mirrors(): + initial = KnowledgeSearchOutput(results=[], embedding_model="fake-model") + fallback = KnowledgeSearchOutput(results=[], embedding_model="fake-model", stale_dropped=7) + renderer = SimpleNamespace(marked=True, render=AsyncMock(return_value=fallback)) + proofs = SimpleNamespace(check=AsyncMock()) + result = app.CheckedSearch(initial, proofs, renderer, [], 7) + first, second = await asyncio.gather(result.ordinary(), result.current()) + assert first is second is await result.ordinary() is fallback + assert result.lost and result.proofs is None + proofs.check.assert_not_awaited() + renderer.render.assert_awaited_once_with([], 7) + + +async def test_initially_ordinary_reply_needs_no_additional_provider_or_query_work(): + initial = KnowledgeSearchOutput(results=[], embedding_model="fake-model") + renderer = SimpleNamespace( + marked=True, render=AsyncMock(side_effect=AssertionError("no retry")) + ) + result = app.CheckedSearch(initial, None, renderer, [], 0) + assert await result.ordinary() is await result.current() is initial + assert not result.lost + renderer.render.assert_not_awaited() + + +@pytest.mark.parametrize("many", [False, True]) +@pytest.mark.parametrize("lost", ["before", "during", "never"]) +async def test_each_span_embedding_is_guarded_and_proof_loss_is_not_swallowed( + monkeypatch, many, lost +): + from server.memory.app import spans + + state = {"lost": lost == "before", "calls": 0} + + async def check(): + if state["lost"]: + raise LostCorpus() + + async def embed(_text): + state["calls"] += 1 + if lost == "during": + state["lost"] = True + return [1.0] + + async def embed_many(_texts): + state["calls"] += 1 + if lost == "during": + state["lost"] = True + return [[1.0], [1.0]] + + async def best_spans(_query, _chunks, batch): + await batch(["window one", "window two"]) + return [SimpleNamespace(text="Nearest span", start=0, end=12, similarity=1.0)] + + monkeypatch.setattr(spans, "best_spans", best_spans) + embedder = SimpleNamespace(embed=embed) + if many: + embedder.embed_many = embed_many + proofs = SimpleNamespace(check=AsyncMock(side_effect=check)) + [hit] = app._as_search_hits( + [ + ("team", [ChunkHit("team", "gdrive:private", 0, "Private chunk", [], 0.2)]), + ] + ) + if lost == "never": + await app._narrow_spans(embedder, [1.0], [hit], proofs=proofs) + assert hit.span == "Nearest span" and state["calls"] == (1 if many else 2) + assert proofs.check.await_count == (2 if many else 4) + else: + with pytest.raises(LostCorpus): + await app._narrow_spans(embedder, [1.0], [hit], proofs=proofs) + assert not hit.span and state["calls"] == (0 if lost == "before" else 1) diff --git a/tests/unit/test_source_stack_preparation.py b/tests/unit/test_source_stack_preparation.py new file mode 100644 index 0000000000..e5834ac54d --- /dev/null +++ b/tests/unit/test_source_stack_preparation.py @@ -0,0 +1,127 @@ +"""A possible stack knowledge read marks its whole parent before provider work.""" + +from __future__ import annotations + +from types import SimpleNamespace + +import pytest + +from server.core import pg, request_work +from server.core.diagnostics import codes_only +from server.knowledge.app import search, source_access +from server.memory.api.models_lifecycle import MemoryStackInput +from server.memory.app import stack + + +@pytest.fixture +def world(monkeypatch): + token = request_work._current.set(None) + request_work.begin() + events = [] + state = {"marked": True, "recent": "", "queries": []} + + async def prepare(org, namespaces): + events.append(("prepare", list(namespaces))) + if state["marked"]: + assert request_work.mark_mirrored() + return source_access.ReadPlan(org, marked=state["marked"]) + + async def profile(_input, _fill): + events.append(("profile", codes_only())) + + async def pinned(_client, _input, _fill): + events.append(("pinned", codes_only())) + + async def recent(_client, _input, _fill): + events.append(("recent", codes_only())) + return state["recent"] + + class Embedder: + model_name = "fake" + + async def embed(self, seed): + events.append(("embed", codes_only())) + assert seed == "question" or seed == "recent seed" + return [1.0] + + async def ranked(query): + events.append(("query", codes_only())) + state["queries"].append(query) + return [] + + monkeypatch.setattr(source_access, "prepare", prepare) + monkeypatch.setattr(stack, "get_client", lambda: SimpleNamespace()) + monkeypatch.setattr(stack, "_stack_profile", profile) + monkeypatch.setattr(stack, "_stack_pinned", pinned) + monkeypatch.setattr(stack, "_stack_recent", recent) + monkeypatch.setattr("server.embedding.get_embedder", Embedder) + monkeypatch.setattr(search, "hybrid_search", ranked) + monkeypatch.setattr(pg, "enabled", lambda: False) + yield SimpleNamespace(events=events, state=state) + request_work._current.reset(token) + + +def request(**changes): + return MemoryStackInput( + org="acme", + namespace="docs", + agent="reader", + procedure_limit=0, + include_knowledge=True, + knowledge_top_k=2, + **changes, + ) + + +@pytest.mark.parametrize("seed,recent", [("question", ""), ("", "recent seed"), ("", "")]) +async def test_possible_knowledge_scope_is_prepared_before_the_first_stack_provider( + world, seed, recent +): + world.state["recent"] = recent + output = await stack.handle_memory_stack(request(seed_query=seed)) + assert world.events[0] == ("prepare", ["docs"]) + assert all(private for name, private in world.events if name != "prepare") + assert request_work.mirror_marked() + assert output.entries == [] and output.tokens_used == 0 + names = [name for name, _ in world.events] + assert names[:4] == ["prepare", "profile", "pinned", "recent"] + if seed or recent: + # This module fixes preparation order; the wider-read policy is separate. + assert names[4] == "embed" and names.count("embed") == 1 + assert all(name == "query" for name in names[5:]) + assert names.count("query") == len(world.state["queries"]) + assert [query.top_k for query in world.state["queries"]] in ([2], [2, 8]) + else: + assert names == ["prepare", "profile", "pinned", "recent"] + assert world.state["queries"] == [] + for query in world.state["queries"]: + assert query.namespaces == ("docs",) + assert query.keys == query.tokens == [] + + +async def test_unmarked_stack_keeps_the_semantic_query_and_ordinary_output(world): + world.state["marked"] = False + output = await stack.handle_memory_stack(request(seed_query="question")) + assert output.entries == [] and output.tokens_used == 0 + assert not request_work.mirror_marked() + assert all(not private for name, private in world.events if name != "prepare") + assert [name for name, _ in world.events] == [ + "prepare", + "profile", + "pinned", + "recent", + "embed", + "query", + ] + assert [query.top_k for query in world.state["queries"]] == [2] + query = world.state["queries"][0] + assert query.namespaces == ("docs",) and query.keys == query.tokens == [] + + +async def test_disabled_knowledge_does_no_source_or_embedding_work(world): + input = request(seed_query="question").model_copy(update={"include_knowledge": False}) + output = await stack.handle_memory_stack(input) + assert [name for name, _ in world.events] == ["profile", "pinned", "recent"] + assert all(not private for _, private in world.events) + assert not world.state["queries"] and not request_work.mirror_marked() + assert output.entries == [] and output.tokens_used == 0 diff --git a/tests/unit/test_source_title_projection.py b/tests/unit/test_source_title_projection.py new file mode 100644 index 0000000000..b6e67b608b --- /dev/null +++ b/tests/unit/test_source_title_projection.py @@ -0,0 +1,86 @@ +"""Inspection reads admitted title scalars without document bodies or diagnostics.""" + +from __future__ import annotations + +from datetime import UTC, datetime +from unittest.mock import AsyncMock + +import pytest + +from server.knowledge.store import source_documents as store +from tests.unit.ch_fake import RecordingCH + + +@pytest.fixture +def world(monkeypatch): + row = { + "org": "acme", + "namespace": "acl-" + "1" * 24, + "source_uri": "gdrive://file#11111111-1111-4111-8111-111111111111", + "version": 11, + "revision": 0, + "title": "Title", + "ingested_at": datetime(2025, 1, 1, tzinfo=UTC), + "superseded_at": None, + "doc_format": "markdown", + "source_scheme": "gdrive", + "source_revision": "r1", + } + monkeypatch.setattr(store.pg, "enabled", lambda: False) + ch = RecordingCH().on("FROM loom.documents FINAL", [row]) + ch.install(monkeypatch, "server.knowledge.store.source_documents") + return row, ch + + +async def test_clickhouse_title_projection_binds_one_admitted_live_identity(world): + row, ch = world + assert await store.title_projection("acme", row["namespace"], row["source_uri"], 11, 0) == row + statement = ch.calls[-1] + assert statement.params == { + "org": "acme", + "ns": row["namespace"], + "uri": row["source_uri"], + "version": 11, + "revision": 0, + } + assert "version = {version:UInt64}" in statement.sql + assert "revision = {revision:UInt64}" in statement.sql + assert "superseded_at IS NULL LIMIT 1" in statement.sql + selected = statement.sql.split(" FROM ")[0] + assert "AS doc_format" in selected and "AS source_revision" in selected + assert "content_preview" not in selected and ", content," not in selected + assert ", metadata," not in selected and "loom.chunks" not in statement.sql + + +async def test_missing_clickhouse_title_never_reads_body(world, monkeypatch): + row, _ch = world + ch = RecordingCH().on("FROM loom.documents FINAL", []) + ch.install(monkeypatch, "server.knowledge.store.source_documents") + assert await store.title_projection("acme", row["namespace"], row["source_uri"], 11, 0) is None + assert len(ch.calls) == 1 + + +async def test_postgres_title_projection_transfers_only_selected_scalars(world, monkeypatch): + row, ch = world + monkeypatch.setattr(store.pg, "enabled", lambda: True) + saved = {**row, "ingested_at": row["ingested_at"].isoformat()} + fetch = AsyncMock(return_value={"row": saved}) + monkeypatch.setattr(store.pg, "fetchrow", fetch) + assert await store.title_projection("acme", row["namespace"], row["source_uri"], 11, 0) == row + sql, *args = fetch.await_args.args + assert args == ["acme", row["namespace"], row["source_uri"], "11", 0, "0"] + assert "NOT h.deleted" in sql and "h.row ->> 'version' = $4" in sql + assert "h.revision = $5" in sql and "h.row ->> 'revision' = $6" in sql + assert "'content'" not in sql and "content_preview" not in sql and "chunks" not in sql + assert "jsonb_build_object" in sql and "AS row" in sql + projected = sql.rsplit("SELECT jsonb_build_object", 1)[1] + assert "'metadata'," not in projected and sql.endswith("AS row FROM formatted") + assert not ch.calls + + +async def test_missing_postgres_title_has_no_clickhouse_fallback(world, monkeypatch): + row, ch = world + monkeypatch.setattr(store.pg, "enabled", lambda: True) + monkeypatch.setattr(store.pg, "fetchrow", AsyncMock(return_value=None)) + assert await store.title_projection("acme", row["namespace"], row["source_uri"], 11, 0) is None + assert not ch.calls diff --git a/tests/unit/test_source_titles.py b/tests/unit/test_source_titles.py new file mode 100644 index 0000000000..ddf0e8a9c9 --- /dev/null +++ b/tests/unit/test_source_titles.py @@ -0,0 +1,138 @@ +"""Inspection titles retain private evidence without reading document diagnostics.""" + +from __future__ import annotations + +import asyncio +from datetime import UTC, datetime +from types import SimpleNamespace +from unittest.mock import AsyncMock + +import pytest + +from server.knowledge.app import source_listing +from server.knowledge.app.source_access import Admitted +from server.knowledge.store import source_documents as store + +SID = "11111111-1111-4111-8111-111111111111" +NS = "acl-" + "1" * 24 +NOW = datetime(2025, 1, 1, tzinfo=UTC) + + +@pytest.fixture +def world(monkeypatch): + items, rows = [], {} + for index in range(2): + uri = f"gdrive:file{index}#native#{SID}" + document = {"version": 11, "revision": 0, "ingested_at": NOW} + items.append(Admitted("team", {"namespace": NS, "source_uri": uri}, document)) + rows[uri] = { + "org": "acme", + "namespace": NS, + "source_uri": uri, + **document, + "superseded_at": None, + "title": f"Title {index}", + "doc_format": "markdown", + "source_scheme": "(none)", + "source_revision": "r1", + } + plan = SimpleNamespace(org="acme", failed=False, unread=False) + + async def renew(_plan, selected): + return selected + + async def finish(_plan, _input, selected, **_scope): + return selected + + async def project(_org, _ns, uri, _version, _revision): + return dict(rows[uri]) + + monkeypatch.setattr(source_listing, "select", AsyncMock(return_value=items)) + monkeypatch.setattr(source_listing, "renew", AsyncMock(side_effect=renew)) + monkeypatch.setattr(source_listing, "finish", AsyncMock(side_effect=finish)) + monkeypatch.setattr(store, "title_projection", AsyncMock(side_effect=project)) + monkeypatch.setattr(store, "list_projection", AsyncMock(side_effect=AssertionError("preview"))) + monkeypatch.setattr(store, "list_chunk_count", AsyncMock(side_effect=AssertionError("chunks"))) + return plan, items, rows + + +async def collect(world, **kwargs): + from server.knowledge.app import source_titles + + return await source_titles.collect(world[0], "team", limit=10, **kwargs) + + +async def test_title_leg_exposes_only_public_scalar_identity(world): + titles = await collect(world) + assert [title.source_uri for title in titles] == ["gdrive:file0#native", "gdrive:file1#native"] + assert titles[0].title == "Title 0" and titles[0].format == "markdown" + assert titles[0].source_scheme == "(none)" and titles[0].source_revision == "r1" + assert (titles[0].version, titles[0].revision, titles[0].ingested_at) == (11, 0, NOW) + assert titles[0].proof.plan is world[0] + assert set(vars(titles[0])) == { + "source_uri", + "title", + "format", + "source_scheme", + "source_revision", + "version", + "revision", + "ingested_at", + "proof", + } + store.list_projection.assert_not_awaited() + store.list_chunk_count.assert_not_awaited() + + +async def test_source_identity_reaches_both_selection_and_last_barrier(world): + await collect(world, source_id=SID) + assert source_listing.select.await_args.kwargs["source_id"] == SID + assert source_listing.finish.await_args.kwargs["source_id"] == SID + + +@pytest.mark.parametrize( + "field", ["org", "namespace", "source_uri", "version", "revision", "ingested_at"] +) +async def test_wrong_projected_copy_discards_every_title(world, field): + rows = world[2] + row = rows[next(reversed(rows))] + row[field] = "wrong" if field not in {"version", "revision"} else row[field] + 1 + assert await collect(world) == [] + assert not world[0].unread + + +async def test_missing_later_projection_discards_prior_title(world): + first = next(iter(world[2].values())) + store.title_projection.side_effect = [first, None] + assert await collect(world) == [] + assert not world[0].unread + + +async def test_final_access_or_shadow_loss_discards_every_title(world): + source_listing.finish.side_effect = None + source_listing.finish.return_value = None + assert await collect(world) == [] + assert store.title_projection.await_count == 2 + assert not world[0].unread + + +async def test_projection_failure_is_conditional_and_has_no_partial_result(world): + first = next(iter(world[2].values())) + store.title_projection.side_effect = [first, RuntimeError("private backend")] + assert await collect(world) == [] + assert world[0].failed and not world[0].unread + + +async def test_cancellation_propagates_without_a_partial_title_list(world): + store.title_projection.side_effect = asyncio.CancelledError + with pytest.raises(asyncio.CancelledError): + await collect(world) + assert not world[0].failed + + +async def test_zero_sample_reads_no_conditional_title_fields(world): + from server.knowledge.app import source_titles + + assert await source_titles.collect(world[0], "team", limit=0) == [] + source_listing.select.assert_not_awaited() + store.title_projection.assert_not_awaited() diff --git a/tests/unit/test_sql_surface.py b/tests/unit/test_sql_surface.py index d40f85e07a..983755358a 100644 --- a/tests/unit/test_sql_surface.py +++ b/tests/unit/test_sql_surface.py @@ -485,13 +485,17 @@ def test_the_ledger_views_read_their_window_and_no_other_view_has_one(view: str) bounds a ledger read must sit in the view's own WHERE, right after the admit clause.""" flat = " ".join(_views()[view].split()) - admit = _ADMIT.search(flat) - assert admit, view - after = flat[admit.end() :].lstrip() + admits = list(_ADMIT.finditer(flat)) + assert admits, view + after = flat[admits[-1].end() :].lstrip() if view in _LEDGER: - assert after.startswith(_WINDOW), (view, after[:80]) + assert len(admits) == 3, "both physical branches and the outer scope stay bounded" + assert all(flat[a.end() :].lstrip().startswith(_WINDOW) for a in admits), view rest = after[len(_WINDOW) :].strip() - assert rest == "" or rest.startswith("GROUP BY"), (view, rest[:80]) + if view == "sql_v1_usage_daily": + assert rest == ") GROUP BY day, org, namespace, agent, operation, kind", (view, rest) + else: + assert rest == "", (view, rest) else: assert "INTERVAL" not in flat, view diff --git a/tests/unit/test_summary_capacity_propagation.py b/tests/unit/test_summary_capacity_propagation.py new file mode 100644 index 0000000000..f438dc093a --- /dev/null +++ b/tests/unit/test_summary_capacity_propagation.py @@ -0,0 +1,277 @@ +"""Oversized summary inputs refuse the composed read instead of losing a leg.""" + +from __future__ import annotations + +import asyncio +from types import SimpleNamespace +from typing import Any + +import pytest + +from server.core.errors import VectorInputTooLargeError +from server.memory.api.models_search import MemorySearchInput, MemorySearchOutput, _MemorySearchHit +from server.memory.app.ask import pool, retrieval_legs +from server.memory.app.loom_search import fanout, repo_decisions +from server.memory.app.search import consistency, fallbacks + + +def _input(**changes: Any) -> MemorySearchInput: + return MemorySearchInput(org="org", namespace="home", query="question").model_copy( + update=changes + ) + + +@pytest.fixture(params=[VectorInputTooLargeError, RuntimeError], ids=["refusal", "ordinary"]) +def failure(request: pytest.FixtureRequest) -> Exception: + return request.param("summary seed input exceeds 256 names") + + +async def _nothing(*_args: Any, **_kwargs: Any) -> list[Any]: + return [] + + +async def test_decomposition_preserves_typed_refusal( + failure: Exception, monkeypatch: pytest.MonkeyPatch +) -> None: + async def parts(*_args: Any, **_kwargs: Any) -> list[str]: + return ["part one", "part two"] + + calls: list[str] = [] + + async def search(inp: MemorySearchInput) -> MemorySearchOutput: + calls.append(inp.query) + raise failure + + monkeypatch.setattr(retrieval_legs, "decompose_question", parts) + monkeypatch.setattr("server.memory.app.search.handle_memory_search", search) + stats = {"failed": 0} + if isinstance(failure, VectorInputTooLargeError): + with pytest.raises(VectorInputTooLargeError) as raised: + await retrieval_legs.decomposed_retrieval( + _input(), "question", [], llm=None, mode="always", stats=stats + ) + assert raised.value is failure + assert calls == ["part one"] and stats == {"failed": 0} + else: + parts_out, ranked = await retrieval_legs.decomposed_retrieval( + _input(), "question", [], llm=None, mode="always", stats=stats + ) + assert parts_out == ["part one", "part two"] and ranked == [] + assert calls == parts_out and stats == {"failed": 2} + + +@pytest.mark.parametrize("route", ["compound", "bridge"]) +async def test_question_widening_preserves_typed_refusal( + route: str, failure: Exception, monkeypatch: pytest.MonkeyPatch +) -> None: + calls: list[MemorySearchInput] = [] + + async def search(inp: MemorySearchInput) -> MemorySearchOutput: + calls.append(inp) + raise failure + + monkeypatch.setattr("server.memory.app.search.handle_memory_search", search) + monkeypatch.setattr( + pool, + "split_compound_question", + lambda _q: ["first", "second"] if route == "compound" else [], + ) + monkeypatch.setattr(pool, "is_chain_question", lambda _q: route == "bridge") + monkeypatch.setattr(pool, "bridge_entities", lambda *_a, **_k: ["bridge"]) + monkeypatch.setattr(pool, "bridge_rows_by_key", _nothing) + run = SimpleNamespace( + search_input=_input(), + question="question", + ranked=[], + settings=SimpleNamespace(memory_ask_entity_follow_max=2, memory_ask_entity_follow_top_k=6), + ) + if isinstance(failure, VectorInputTooLargeError): + with pytest.raises(VectorInputTooLargeError) as raised: + await pool._widen_by_question(run, llm=None, llm_cheap=None, decompose="off") + assert raised.value is failure + else: + await pool._widen_by_question(run, llm=None, llm_cheap=None, decompose="off") + assert run.ranked == [] + assert len(calls) == 1 + assert (calls[0].org, calls[0].namespace) == ("org", "home") + + +@pytest.mark.parametrize("route", ["fresh-hit", "empty"]) +async def test_consistency_reread_preserves_typed_refusal( + route: str, failure: Exception, monkeypatch: pytest.MonkeyPatch +) -> None: + async def search(inp: MemorySearchInput) -> MemorySearchOutput: + assert (inp.org, inp.namespace, inp._pass_depth) == ("org", "home", 1) + raise failure + + monkeypatch.setattr("server.memory.app.search.handle_memory_search", search) + monkeypatch.setattr( + consistency, "_fresh_hit_reread_wanted", lambda *_a, **_k: route == "fresh-hit" + ) + monkeypatch.setattr(consistency, "_sequential_retry_wanted", lambda **_k: route == "empty") + monkeypatch.setattr("server.memory.store.read_your_writes_enabled", lambda: True) + budget = SimpleNamespace(wall_left_s=lambda: 10.0, remaining_wall_s=lambda: 10.0) + ctx = SimpleNamespace(input=_input(), search_budget=budget, namespaces=["home"]) + hits = [ + _MemorySearchHit( + memory_key="existing", + memory_type="semantic", + content_excerpt="kept", + distance=0.5, + similarity=0.5, + ) + ] + if isinstance(failure, VectorInputTooLargeError): + with pytest.raises(VectorInputTooLargeError) as raised: + await consistency._consistency_reread(ctx, hits) + assert raised.value is failure + else: + assert await consistency._consistency_reread(ctx, hits) is None + assert hits[0].memory_key == "existing" + + +async def test_iterative_retry_preserves_typed_refusal( + failure: Exception, monkeypatch: pytest.MonkeyPatch +) -> None: + async def judge(*_args: Any) -> tuple[bool, str]: + return False, "rephrased question" + + async def search(inp: MemorySearchInput) -> MemorySearchOutput: + assert inp.query == "rephrased question" and inp._pass_depth == 1 + raise failure + + monkeypatch.setattr("server.memory.app.search_llm.judge_results_iteratively", judge) + monkeypatch.setattr("server.memory.app.search.handle_memory_search", search) + budget = SimpleNamespace( + fallback_affordable=lambda **_k: True, + try_spend_llm=lambda _n: True, + note_llm_call=lambda _n: None, + try_spend_fallback=lambda **_k: True, + remaining_wall_s=lambda: 10.0, + ) + hits = [ + _MemorySearchHit( + memory_key="existing", + memory_type="semantic", + content_excerpt="kept", + distance=0.5, + similarity=0.5, + ) + ] + ctx = SimpleNamespace( + input=_input(recipe="quality"), + final_hits=hits, + chronological_intent=False, + llm_free=False, + search_budget=budget, + namespaces=["home"], + actual_work={}, + ) + if isinstance(failure, VectorInputTooLargeError): + with pytest.raises(VectorInputTooLargeError) as raised: + await fallbacks._maybe_iterative_retry(ctx) + assert raised.value is failure + else: + await fallbacks._maybe_iterative_retry(ctx) + assert ctx.final_hits == hits + + +async def test_repository_search_preserves_typed_refusal( + failure: Exception, monkeypatch: pytest.MonkeyPatch +) -> None: + async def search(inp: MemorySearchInput) -> MemorySearchOutput: + assert (inp.org, inp.namespace) == ("org", "repository") + raise failure + + monkeypatch.setattr("server.memory.app.search.handle_memory_search", search) + if isinstance(failure, VectorInputTooLargeError): + with pytest.raises(VectorInputTooLargeError) as raised: + await repo_decisions.search_repo_decisions(_input(), "repository") + assert raised.value is failure + else: + assert await repo_decisions.search_repo_decisions(_input(), "repository") is None + + +async def test_section_gather_preserves_typed_refusal( + failure: Exception, monkeypatch: pytest.MonkeyPatch +) -> None: + async def namespaces(_org: str, ns: str, _scope: str) -> tuple[list[str], list[str]]: + return [ns], [] + + async def memory(inp: MemorySearchInput, **_kwargs: Any) -> MemorySearchOutput: + assert (inp.org, inp.namespace) == ("org", "home") + raise failure + + async def prepare(*_args: Any) -> Any: + return None, SimpleNamespace(marked=False) + + async def unavailable(*_args: Any) -> Any: + raise RuntimeError("ordinary unavailable section") + + monkeypatch.setattr("server.auth.fanout.namespaces_to_search", namespaces) + monkeypatch.setattr(fanout, "request_scope", lambda: None) + monkeypatch.setattr(fanout, "memory_with_repo_decisions", memory) + monkeypatch.setattr(fanout, "_prepare_knowledge", prepare) + monkeypatch.setattr(fanout, "_run_knowledge", unavailable) + monkeypatch.setattr(fanout, "search_profile", _nothing) + monkeypatch.setattr(fanout, "_conversation_leg", unavailable) + monkeypatch.setattr(fanout, "tracker_leg", _nothing) + monkeypatch.setattr(fanout, "answer_first", lambda payload, *_a, **_k: payload) + kwargs = dict( + org="org", + namespace="home", + agent="a", + query="question", + top_k=3, + tags=[], + namespace_scope="this", + recipe="", + bodies="excerpt", + page="", + explain=False, + repo_namespace="", + tracker_plan=None, + ) + if isinstance(failure, VectorInputTooLargeError): + with pytest.raises(VectorInputTooLargeError) as raised: + await fanout.search_sections(**kwargs) + assert raised.value is failure + else: + result = await fanout.search_sections(**kwargs) + assert result["memory"]["results"] == [] + assert result["memory"]["error"] == "RuntimeError" + assert result["knowledge"]["results"] == [] + + +async def test_repository_base_failure_joins_its_owned_sibling( + monkeypatch: pytest.MonkeyPatch, +) -> None: + started, finished = asyncio.Event(), asyncio.Event() + refusal = VectorInputTooLargeError("summary input exceeds 256 names") + child: asyncio.Task[Any] | None = None + + async def extra(*_args: Any) -> None: + nonlocal child + child = asyncio.current_task() + started.set() + try: + await asyncio.Event().wait() + finally: + await asyncio.sleep(0) + finished.set() + + async def search(_inp: MemorySearchInput) -> MemorySearchOutput: + await started.wait() + raise refusal + + monkeypatch.setattr(repo_decisions, "search_repo_decisions", extra) + monkeypatch.setattr("server.memory.app.search.handle_memory_search", search) + try: + with pytest.raises(VectorInputTooLargeError) as raised: + await repo_decisions.memory_with_repo_decisions(_input(), repo_namespace="repository") + assert raised.value is refusal + assert finished.is_set() and child is not None and child.done() + finally: + if child is not None: + child.cancel() + await asyncio.gather(child, return_exceptions=True) diff --git a/tests/unit/test_synthesize_datasets.py b/tests/unit/test_synthesize_datasets.py index b097ac6136..19908a5041 100644 --- a/tests/unit/test_synthesize_datasets.py +++ b/tests/unit/test_synthesize_datasets.py @@ -289,7 +289,7 @@ def __init__(self, monkeypatch: pytest.MonkeyPatch, llm: _LLM) -> None: self.queries: list[Any] = [] self.refuse: list[str] = [] - async def _over_cap(org: str, ns: str) -> bool: + async def _over_cap(org: str, ns: str, *, user_id: str = "") -> bool: return False async def _get(input: Any) -> KnowledgeDatasetGetOutput: diff --git a/tests/unit/test_task_cursor_server_clock.py b/tests/unit/test_task_cursor_server_clock.py index 75afc23978..8764305f59 100644 --- a/tests/unit/test_task_cursor_server_clock.py +++ b/tests/unit/test_task_cursor_server_clock.py @@ -10,6 +10,7 @@ import pytest +from server.identity.domain.read_scope import WHOLE_NAMESPACE from server.tasks.domain import cursors from server.tasks.store import repo from tests.unit.test_task_inbox import _post, _register, fake # noqa: F401 — fixture @@ -47,7 +48,14 @@ async def test_server_version_reads_the_server_clock_and_beats_the_row() -> None @pytest.mark.asyncio async def test_the_cursor_read_is_sequential_and_lags_the_server_clock() -> None: ch = _RecordingCH() - await repo.events_since("acme", since_seq=5, lag_s=cursors.LAG_SECONDS, inbox="bot", ch=ch) # type: ignore[arg-type] + await repo.events_since( + "acme", + since_seq=5, + lag_s=cursors.LAG_SECONDS, + warning_scope=WHOLE_NAMESPACE, + inbox="bot", + ch=ch, # type: ignore[arg-type] + ) sql, params = ch.sql[-1] assert "select_sequential_consistency = 1" in sql assert "ts <= now64(3) - toIntervalSecond({lag:Int32})" in sql diff --git a/tests/unit/test_task_inbox.py b/tests/unit/test_task_inbox.py index 02c3b9ba9b..efba029b87 100644 --- a/tests/unit/test_task_inbox.py +++ b/tests/unit/test_task_inbox.py @@ -286,7 +286,15 @@ async def task_history(self, org, task_id, *, limit=500, consistent=False): return [e for e in self.events if e["org"] == org and e["task_id"] == str(task_id)][:limit] async def events_since( - self, org, *, since_seq, lag_s, inbox=None, from_subject=None, limit=200 + self, + org, + *, + since_seq, + lag_s, + warning_scope=None, + inbox=None, + from_subject=None, + limit=200, ): rows = [e for e in self.events if e["org"] == org and e["seq"] > since_seq] if inbox: diff --git a/tests/unit/test_tracker_binding_discovery.py b/tests/unit/test_tracker_binding_discovery.py new file mode 100644 index 0000000000..0f498e0dd2 --- /dev/null +++ b/tests/unit/test_tracker_binding_discovery.py @@ -0,0 +1,125 @@ +"""General tracker discovery reads persisted repository links before authorizing.""" + +import asyncio +import json +from copy import deepcopy +from types import SimpleNamespace + +import pytest + +from server.identity.domain.read_scope import WHOLE_NAMESPACE +from server.memory.app.loom_search.tracker_leg import prepare_tracker_search +from server.settings import settings +from server.tracker.app import binding +from tests.unit.clock_fake import ManualClock + +ORG = "acme" +CODE = "code-project" +ROOT = "code-project-root" +PUBLIC = "tracker-project" +RESTRICTED = "tracker-restricted" + + +@pytest.fixture +def stored_links(monkeypatch): + clock = ManualClock(t=1000.0) + values = {binding.OVERRIDE_KEY: {}, binding.BRANCH_OF_KEY: {}} + + class Repository: + async def state_values_for_keys(self, keys): + assert keys == [binding.OVERRIDE_KEY, binding.BRANCH_OF_KEY] + return deepcopy(values) + + async def kinds(org): + assert org == ORG + return {CODE: "code"} + + async def readable(org, namespace, role=None, *, hides_answer=True): + return org == ORG and namespace == CODE + + targets = { + PUBLIC: SimpleNamespace(restricted=False), + RESTRICTED: SimpleNamespace(restricted=True), + } + monkeypatch.setattr(binding, "time", SimpleNamespace(monotonic=clock.monotonic)) + monkeypatch.setattr(binding, "_OVERRIDES", {}) + monkeypatch.setattr(binding, "_BRANCH_OF", {}) + monkeypatch.setattr(binding, "_OVERRIDES_AT", -float("inf")) + monkeypatch.setattr(binding, "_AFTER_WRITE", False) + monkeypatch.setattr(binding, "operator_repositories", lambda: frozenset({(ORG, ROOT)})) + monkeypatch.setattr(binding.repos, "registry_namespaces", lambda: {(ORG, CODE)}) + monkeypatch.setattr(settings, "code_repos_refresh_seconds", 1) + monkeypatch.setattr(settings, "tracker_code_namespace_bindings_json", "{}") + monkeypatch.setattr("server.code.app.reads.code_index", Repository) + monkeypatch.setattr("server.core.ch.get_client", lambda: SimpleNamespace(_client=object())) + monkeypatch.setattr("server.auth.authz.row_in_scope", readable) + monkeypatch.setattr("server.identity.app.namespace_kinds.kind_map", kinds) + monkeypatch.setattr("server.code.domain.scope.current_code_scope", lambda: None) + monkeypatch.setattr("server.identity.app.request_scope.request_scope", lambda: WHOLE_NAMESPACE) + monkeypatch.setattr( + "server.tracker.domain.namespaces.configured_namespaces", lambda: dict(targets) + ) + monkeypatch.setattr( + "server.tracker.domain.namespaces.tracker_namespace", + lambda org, namespace: targets.get(namespace) if org == ORG else None, + ) + return values, clock + + +@pytest.mark.parametrize("link_kind", ["override", "branch"]) +async def test_cold_persisted_links_open_only_the_standard_tracker( + stored_links, monkeypatch, link_kind +): + values, _ = stored_links + if link_kind == "override": + values[binding.OVERRIDE_KEY][ORG, CODE] = f"{PUBLIC},{RESTRICTED}" + else: + values[binding.BRANCH_OF_KEY][ORG, CODE] = ROOT + monkeypatch.setattr( + settings, + "tracker_code_namespace_bindings_json", + json.dumps({ROOT: [PUBLIC, RESTRICTED]}), + ) + + plan = await prepare_tracker_search("retention decision", org=ORG) + + assert plan is not None + assert plan.namespaces == (PUBLIC,) + + +async def test_cleared_persisted_link_closes_the_warm_discovery_cache(stored_links): + values, clock = stored_links + values[binding.OVERRIDE_KEY][ORG, CODE] = PUBLIC + await binding.refresh_overrides() + plan = await prepare_tracker_search("retention decision", org=ORG) + assert plan is not None and plan.namespaces == (PUBLIC,) + + values[binding.OVERRIDE_KEY][ORG, CODE] = "" + clock.advance(2) + + assert await prepare_tracker_search("retention decision", org=ORG) is None + + +async def test_another_orgs_persisted_link_opens_nothing(stored_links): + values, _ = stored_links + values[binding.OVERRIDE_KEY]["other-org", CODE] = PUBLIC + + assert await prepare_tracker_search("retention decision", org=ORG) is None + + +async def test_persisted_binding_read_obeys_the_discovery_deadline(stored_links, monkeypatch): + cancelled = asyncio.Event() + + async def blocked_read(keys): + try: + await asyncio.Event().wait() + finally: + cancelled.set() + + monkeypatch.setattr( + "server.code.app.reads.code_index", + lambda: SimpleNamespace(state_values_for_keys=blocked_read), + ) + + assert await prepare_tracker_search("retention decision", org=ORG, timeout_s=0.01) is None + assert cancelled.is_set() diff --git a/tests/unit/test_tracker_dupcheck_fanout.py b/tests/unit/test_tracker_dupcheck_fanout.py index a41011956a..9c55d6a30f 100644 --- a/tests/unit/test_tracker_dupcheck_fanout.py +++ b/tests/unit/test_tracker_dupcheck_fanout.py @@ -76,6 +76,14 @@ async def test_a_restricted_record_needs_its_own_grant(monkeypatch) -> None: assert await fo.readable_tracker_namespaces(ORG, "", [], 4) == [PUB] +@pytest.mark.asyncio +async def test_one_namespace_limit_without_a_bound_tracker_still_discovers_a_readable_record( + monkeypatch, +) -> None: + _wire_namespaces(monkeypatch, readable=set(), code_readable={"code-clickhouse"}) + assert await fo.readable_tracker_namespaces(ORG, "", [], 1) == [PUB] + + @pytest.mark.asyncio async def test_requested_namespaces_are_resolved_and_gated_in_order(monkeypatch) -> None: _wire_namespaces(monkeypatch, readable={PRIV, PUB}) @@ -463,3 +471,41 @@ async def _one(input, wall, **_kw): monkeypatch.setattr(repos, "_registry_loaded", True) await hd.handle_tracker_duplicate_check(ask) assert remembered == ["code-example-private"] + + +@pytest.mark.asyncio +async def test_prepared_duplicate_targets_do_not_discover_new_bindings(monkeypatch) -> None: + from unittest.mock import AsyncMock + + _wire_namespaces(monkeypatch, readable={PUB}) + monkeypatch.setattr(tcommon, "linked_trackers", AsyncMock(return_value=[PUB])) + monkeypatch.setattr( + tcommon, + "_bound_input", + AsyncMock(side_effect=lambda i: i.model_copy(update={"namespace": PUB})), + ) + plan = await hd.prepare_duplicate_check( + TrackerDuplicateCheckInput( + org=ORG, namespace="code-clickhouse", title="retention failure", related_prs=False + ) + ) + assert plan.targets == (PUB,) + monkeypatch.setattr( + tcommon, + "linked_trackers", + AsyncMock(side_effect=AssertionError("new binding after consent")), + ) + monkeypatch.setattr( + fo, + "readable_tracker_namespaces", + AsyncMock(side_effect=AssertionError("rediscovery after consent")), + ) + checked = AsyncMock(return_value=_out("none", [])) + monkeypatch.setattr(hd, "_checked", checked) + + async def links(out, *args, **kwargs): + return out + + monkeypatch.setattr(hd, "_with_links", links) + await hd.execute_duplicate_check(plan) + assert [i.namespace for i in checked.await_args.args[0]] == [PUB] diff --git a/tests/unit/test_tracker_ux.py b/tests/unit/test_tracker_ux.py index a1fa62d794..9a4c7780f0 100644 --- a/tests/unit/test_tracker_ux.py +++ b/tests/unit/test_tracker_ux.py @@ -128,7 +128,8 @@ async def test_reads_count_agent_opens_not_the_dashboards(monkeypatch) -> None: assert params["skip"] == ["loom-ui", "loom-assistant"] assert params == {**params, "org": "acme", "ns": "code-kj", "days": 7, "uris": []} # the ledger's sort key leads with (org, namespace): the read is a key range - assert sql.index("org = {org:String}") < sql.index("operation") + where = sql.rsplit("WHERE", 1)[1] + assert where.index("org = {org:String}") < where.index("operation") def test_the_reads_window_is_bounded() -> None: diff --git a/tests/unit/test_transport_security.py b/tests/unit/test_transport_security.py index 3c96a6c745..c3251cba45 100644 --- a/tests/unit/test_transport_security.py +++ b/tests/unit/test_transport_security.py @@ -89,7 +89,11 @@ def test_admin_route_allows_admin_bearer( from server.insights.store import admin as admin_repo async def fake( - since_seconds: int, limit: int, *, filters: dict[str, Any] | None = None + since_seconds: int, + limit: int, + *, + filters: dict[str, Any] | None = None, + operator: bool = False, ) -> list[dict[str, Any]]: return [] diff --git a/tests/unit/test_user_cost_budget.py b/tests/unit/test_user_cost_budget.py new file mode 100644 index 0000000000..0f2f3bf1f8 --- /dev/null +++ b/tests/unit/test_user_cost_budget.py @@ -0,0 +1,396 @@ +"""Named-user cost caps remain independent of the namespace ceiling.""" + +from __future__ import annotations + +from typing import Any + +import pytest + +from server.core.event_source import ALL_EVENTS +from server.insights.api.models_cost import BudgetStatusInput +from server.insights.app import cost +from server.observability import budget + + +class BudgetCH: + def __init__(self, *, namespace_cap: float = 0, user_cap: float = 2, spent: float = 3) -> None: + self.namespace_cap, self.user_cap, self.spent = namespace_cap, user_cap, spent + self.reads: list[dict[str, Any]] = [] + self.inbox = "" + self.marked_spent = 0.0 + + async def query_one(self, sql: str, params: dict[str, Any]) -> dict[str, Any]: + self.reads.append(params) + if "FROM loom.namespaces" in sql: + return { + "daily_cost_cap_usd": self.namespace_cap, + "daily_user_cost_cap_usd": self.user_cap, + "budget_alert_inbox": self.inbox, + } + assert f"FROM {ALL_EVENTS}" in sql + assert "WHERE" not in ALL_EVENTS.upper(), "the source must include every event" + assert "mirror_marked" not in sql.replace(ALL_EVENTS, "event_rows"), ( + "budget predicates and aggregates count marked spend too" + ) + return { + "spent": 10.0, + "own": 0.0, + "user_spent": self.spent + self.marked_spent if params.get("uid") == "alice" else 0.0, + "user_own": 0.0, + } + + +@pytest.fixture +def ch(monkeypatch: pytest.MonkeyPatch) -> BudgetCH: + from server.settings import settings + + client = BudgetCH() + monkeypatch.setattr("server.core.ch.get_client", lambda: client) + monkeypatch.setattr(cost, "get_client", lambda: client) + monkeypatch.setattr(settings, "default_daily_cost_cap_usd", 0) + monkeypatch.setattr("server.auth.context.current_auth", lambda: None) + return client + + +async def test_user_cap_applies_with_an_uncapped_namespace(ch: BudgetCH) -> None: + assert await budget.namespace_over_cap("o", "n", user_id="alice") is True + assert await budget.namespace_over_cap("o", "n", user_id="bob") is False + + +async def test_user_cap_controls_budget_pressure_routing(ch: BudgetCH) -> None: + assert await budget.namespace_budget_ratio("o", "n", user_id="alice") == 1.5 + assert await budget.namespace_budget_ratio("o", "n", user_id="bob") == 0.0 + + +async def test_namespace_cap_still_stops_a_user_under_their_own_cap(ch: BudgetCH) -> None: + ch.namespace_cap = 5 + assert await budget.namespace_over_cap("o", "n", user_id="bob") is True + assert await budget.namespace_budget_ratio("o", "n", user_id="bob") == 2.0 + + +async def test_an_unattributed_check_does_not_guess_a_user(ch: BudgetCH) -> None: + assert await budget.namespace_over_cap("o", "n") is False + assert await budget.namespace_budget_ratio("o", "n") == 0.0 + assert len(ch.reads) == 2, "uncapped anonymous checks need only their cap reads" + + +async def test_user_budget_status_uses_the_named_users_spend( + ch: BudgetCH, monkeypatch: pytest.MonkeyPatch +) -> None: + from server.auth.jwt import AuthInfo + from server.operations.base import Role + + auth = AuthInfo( + subject="operator", + org="o", + namespaces=("*",), + roles=(Role.PLATFORM_ADMIN,), + is_service_account=False, + ) + monkeypatch.setattr("server.auth.context.current_auth", lambda: auth) + out = await cost.handle_budget_status( + BudgetStatusInput(org="o", namespace="n", user_id="alice") + ) + assert out.user_id == "alice" + assert (out.cap_usd, out.spent_24h_usd, out.cap_source) == (2.0, 3.0, "namespace_user") + assert out.over_cap is True and out.pct_of_cap == 1.0 + + +@pytest.mark.parametrize( + "principal", ["none", "viewer", "org_admin", "narrow_operator", "operator"] +) +@pytest.mark.parametrize("marked_spent", [0.0, 2.0]) +async def test_user_spend_is_operator_only_even_when_every_event_is_ordinary( + ch: BudgetCH, monkeypatch: pytest.MonkeyPatch, principal: str, marked_spent: float +) -> None: + from server.auth.jwt import AuthInfo + from server.observability import budget_notifications + from server.operations.base import Role + from server.settings import settings + + role = {"viewer": Role.VIEWER, "org_admin": Role.ORG_ADMIN}.get(principal, Role.PLATFORM_ADMIN) + auth = ( + None + if principal == "none" + else AuthInfo( + subject="reader", + org="o", + namespaces=("n",), + roles=(role,), + is_service_account=False, + ns_roles=(("n", "admin"),) if principal == "narrow_operator" else (), + ) + ) + assert auth is None or not auth.read_user_id + monkeypatch.setattr("server.auth.context.current_auth", lambda: auth) + warnings: list[budget_notifications.BudgetWarning] = [] + monkeypatch.setattr(budget_notifications, "_observer", warnings.append) + monkeypatch.setattr(settings, "cost_budget_alert_share", 0.8) + ch.inbox = "warnings" + ch.spent, ch.marked_spent = 1.0, marked_spent + out = await cost.handle_budget_status( + BudgetStatusInput(org="o", namespace="n", user_id="alice") + ) + real_spent = 1.0 + marked_spent + assert out.spent_24h_usd == (real_spent if principal == "operator" else None) + assert out.pct_of_cap == (min(1.0, real_spent / 2) if principal == "operator" else None) + assert out.cap_usd == 2 and out.cap_source == "namespace_user" + assert out.over_cap is (real_spent >= 2) and out.namespace_over_cap is False + assert len(warnings) == (1 if marked_spent else 0) + if warnings: + assert warnings[0].user_id == "alice" and warnings[0].spent == real_spent + snapshot = await budget.budget_snapshot("o", "n", user_id="alice", read_uncapped=True, ch=ch) + assert snapshot.user_spent == real_spent + assert await budget.namespace_over_cap("o", "n", user_id="alice") is (real_spent >= 2) + assert await budget.namespace_budget_ratio("o", "n", user_id="alice") == real_spent / 2 + total = await cost.handle_budget_status(BudgetStatusInput(org="o", namespace="n")) + assert total.spent_24h_usd == 10 and total.pct_of_cap is None + ch.namespace_cap = 5 + out = await cost.handle_budget_status( + BudgetStatusInput(org="o", namespace="n", user_id="alice") + ) + assert out.namespace_over_cap is True and out.over_cap is (real_spent >= 2) + + +async def test_user_status_reports_the_namespace_gate_too(ch: BudgetCH) -> None: + ch.namespace_cap = 5 + out = await cost.handle_budget_status(BudgetStatusInput(org="o", namespace="n", user_id="bob")) + assert out.over_cap is False and out.namespace_over_cap is True + + +async def test_global_user_cap_is_the_fallback( + ch: BudgetCH, monkeypatch: pytest.MonkeyPatch +) -> None: + from server.settings import settings + + ch.user_cap = 0 + monkeypatch.setattr(settings, "default_daily_user_cost_cap_usd", 1) + out = await cost.handle_budget_status( + BudgetStatusInput(org="o", namespace="n", user_id="alice") + ) + assert out.over_cap and out.cap_source == "global_user" and out.cap_usd == 1 + + +async def test_check_time_warning_threshold_and_scope( + ch: BudgetCH, monkeypatch: pytest.MonkeyPatch +) -> None: + from server.observability import budget_notifications + from server.settings import settings + + warnings: list[budget_notifications.BudgetWarning] = [] + monkeypatch.setattr(budget_notifications, "_observer", warnings.append) + monkeypatch.setattr(settings, "cost_budget_alert_share", 0.8) + ch.inbox, ch.namespace_cap, ch.spent = "warnings", 20, 1.6 + assert not await budget.namespace_over_cap("o", "n", user_id="alice") + assert len(warnings) == 1 and warnings[0].user_id == "alice" + warnings.clear() + await budget.namespace_over_cap("o", "n") + assert warnings == [], "an unscoped check does not discover users" + ch.namespace_cap = 10 + await budget.namespace_over_cap("o", "n") + assert len(warnings) == 1 and warnings[0].user_id == "" + + +async def test_notification_failure_cannot_change_the_cap_decision( + ch: BudgetCH, monkeypatch: pytest.MonkeyPatch +) -> None: + from server.observability import budget_notifications + + def unavailable(warning: budget_notifications.BudgetWarning) -> None: + raise RuntimeError("inbox delivery unavailable") + + ch.inbox = "warnings" + monkeypatch.setattr(budget_notifications, "_observer", unavailable) + assert await budget.namespace_over_cap("o", "n", user_id="alice") + + +async def test_user_status_requires_a_namespace(ch: BudgetCH) -> None: + from server.core.errors import ValidationError + + with pytest.raises(ValidationError, match="namespace is required"): + await cost.handle_budget_status(BudgetStatusInput(org="o", user_id="alice")) + + +@pytest.mark.parametrize("cascade", [False, True]) +async def test_ask_admission_uses_the_same_named_user_as_its_ledger( + ch: BudgetCH, monkeypatch: pytest.MonkeyPatch, cascade: bool +) -> None: + from server.memory.api.models_ask import MemoryAskInput + from server.memory.app.ask.handler import _ask_clients + from server.settings import settings + + monkeypatch.setattr(settings, "memory_ask_synth_model_cheap", "fake-cheap" if cascade else "") + state = await _ask_clients( + MemoryAskInput( + org="o", namespace="n", user_id="alice", query="explain", allow_synthesis=True + ), + settings, + ) + assert state[4] is True + assert state[:4] == (None, None, None, None) + assert ch.reads[-1]["uid"] == "alice" + + +@pytest.mark.parametrize("query", ["summarize the report", "overview of the report"]) +@pytest.mark.parametrize("user_id", ["alice", "bob"]) +async def test_document_route_honors_the_named_users_cap( + ch: BudgetCH, monkeypatch: pytest.MonkeyPatch, query: str, user_id: str +) -> None: + from types import SimpleNamespace + + from server.knowledge.api.models_knowledge import KnowledgeSearchInput + from server.knowledge.app import knowledge_search, synthesize + from server.knowledge.app.knowledge_search import SearchRequest + from server.knowledge.app.source_access import ReadPlan + from server.memory.api.models_ask import MemoryAskInput + from server.memory.app.ask.handler import _maybe_route_to_synthesize + from server.memory.app.ask.source_context import PreparedKnowledge + from server.memory.domain.corpus_synthesis import CorpusChunk + + calls: list[str] = [] + + prepared = PreparedKnowledge( + SearchRequest(KnowledgeSearchInput(org="o", namespace="n", query=query), ("n",), ()), + ReadPlan("o"), + ) + + async def search(request: SearchRequest, plan: ReadPlan) -> Any: + assert request.namespaces == ("n",) and plan is prepared.plan + + async def current() -> Any: + return SimpleNamespace( + results=[SimpleNamespace(source_uri="doc://report", tags=[]) for _ in range(2)] + ) + + return SimpleNamespace(current=current, proofs=None) + + class LLM: + model = "fake" + + async def complete(self, *args: Any, **kwargs: Any) -> Any: + calls.append(user_id) + return SimpleNamespace(text="The report describes a deployment. [doc://report#0]") + + async def chunks(inp: Any) -> Any: + return [CorpusChunk(source_uri="doc://report", idx=0, text="Deployment report.")], 1 + + from server.settings import settings + + monkeypatch.setattr(settings, "memory_ask_synth_model", "") + monkeypatch.setattr("server.llm.client.get_llm_client", LLM) + monkeypatch.setattr(knowledge_search, "run_checked_search", search) + monkeypatch.setattr(synthesize, "_corpus_chunks", chunks) + out = await _maybe_route_to_synthesize( + MemoryAskInput(org="o", namespace="n", user_id=user_id, query=query), prepared + ) + if user_id == "alice": + assert out is None, "a capped user must fall through to retrieval without synthesis" + assert calls == [] + else: + assert out is not None and out.source == "synthesized" + assert calls == ["bob", "bob"] + + +async def test_direct_synthesis_checks_the_token_pinned_users_budget( + ch: BudgetCH, monkeypatch: pytest.MonkeyPatch +) -> None: + from server.identity.domain.read_scope import ReadFilters, with_read_identity + from server.knowledge.api.models_knowledge import KnowledgeSynthesizeInput + from server.knowledge.app.synthesize import handle_knowledge_synthesize + + inp = with_read_identity( + KnowledgeSynthesizeInput( + org="o", namespace="n", source_uris=["doc://report"], task="Summarize" + ), + ReadFilters("own_user", "alice", None), + ) + out = await handle_knowledge_synthesize(inp) + assert out.abstain and out.abstain_reason == "budget_capped" + assert ch.reads[-1]["uid"] == "alice" + + +@pytest.mark.parametrize("user_id", ["alice", "bob"]) +async def test_code_synthesis_checks_its_ledger_user_before_building_a_client( + ch: BudgetCH, monkeypatch: pytest.MonkeyPatch, user_id: str +) -> None: + from types import SimpleNamespace + from unittest.mock import AsyncMock + + from server.code.api.models_search import CodeAskInput + from server.code.app import answers + from server.code.app import ask as code_ask + from server.settings import settings + + class Retrieved(Exception): + pass + + clients: list[str] = [] + selected: list[Any] = [] + + def client() -> Any: + clients.append(user_id) + return SimpleNamespace(model="fake") + + async def retrieve(*args: Any, **kwargs: Any) -> Any: + selected.append(kwargs["llm"]) + raise Retrieved + + monkeypatch.setattr(code_ask, "require_code_intel", lambda: None) + monkeypatch.setattr(code_ask, "refuse_synthesis", lambda *args: None) + monkeypatch.setattr(code_ask, "resolve_code_identity", lambda org, ns: (org, ns)) + monkeypatch.setattr(code_ask, "CodeRepo", lambda: object()) + monkeypatch.setattr(code_ask, "resolve_code_thresholds", AsyncMock(return_value=(0.5, 0.1))) + monkeypatch.setattr(code_ask, "index_as_of", AsyncMock(return_value={})) + monkeypatch.setattr("server.embedding.embedder.get_embedder", lambda: object()) + monkeypatch.setattr("server.llm.client.get_llm_client", client) + monkeypatch.setattr(settings, "code_ask_llm_model", "") + monkeypatch.setattr(answers, "ask", retrieve) + with pytest.raises(Retrieved): + await code_ask.handle_code_ask( + CodeAskInput(org="o", namespace="n", user_id=user_id, question="Explain this function") + ) + assert clients == ([] if user_id == "alice" else ["bob"]) + assert (selected[0] is None) == (user_id == "alice") + assert ch.reads[-1]["uid"] == user_id + + +@pytest.mark.parametrize("user_id", ["alice", "bob"]) +async def test_code_query_expansion_checks_its_named_users_cap( + ch: BudgetCH, monkeypatch: pytest.MonkeyPatch, user_id: str +) -> None: + from unittest.mock import AsyncMock + + from server.code.api.models_search import CodeSearchInput + from server.code.app import answers + from server.code.app.search import handler + + class Retrieved(Exception): + pass + + expanded: list[str] = [] + + async def expand(*args: Any) -> list[str]: + expanded.append(user_id) + return ["retention"] + + def retrieve(*args: Any) -> Any: + raise Retrieved + + monkeypatch.setattr(handler, "require_code_intel", lambda: None) + monkeypatch.setattr(handler, "resolve_code_identity", lambda org, ns: (org, ns)) + monkeypatch.setattr(handler, "CodeRepo", lambda: object()) + monkeypatch.setattr(handler, "resolve_code_thresholds", AsyncMock(return_value=(0.5, 0.1))) + monkeypatch.setattr(handler, "_not_covered_output", lambda *args: None) + monkeypatch.setattr(handler, "_search_embedder", lambda inp: (None, "fake")) + monkeypatch.setattr(handler, "_user_recent_dirs", AsyncMock(return_value=[])) + monkeypatch.setattr(handler, "reads_llm_free", lambda: False) + monkeypatch.setattr(handler, "_budget_allows", lambda *args: True) + monkeypatch.setattr(handler, "page_plan", retrieve) + monkeypatch.setattr(answers, "_propose_identifiers", expand) + monkeypatch.setattr("server.llm.client.get_llm_client", lambda: object()) + with pytest.raises(Retrieved): + await handler.handle_code_search( + CodeSearchInput(org="o", namespace="n", user_id=user_id, query="retention", expand=True) + ) + assert expanded == ([] if user_id == "alice" else ["bob"]) + assert ch.reads[-1]["uid"] == user_id diff --git a/tests/unit/test_write_scope.py b/tests/unit/test_write_scope.py index c9b8011afd..4605fc0b23 100644 --- a/tests/unit/test_write_scope.py +++ b/tests/unit/test_write_scope.py @@ -75,8 +75,8 @@ def store(monkeypatch): calls: dict[str, list[Any]] = {"writes": [], "usage": []} - async def get_by_key(identity, key, *, scope, **kw): - ok = key == _V_ROW.memory_key and row_in_read_scope( + async def get_by_key(identity, memory_key, *, scope, **kw): + ok = memory_key == _V_ROW.memory_key and row_in_read_scope( scope, _V_ROW.user_id, _V_ROW.session_id ) return _V_ROW if ok else None @@ -175,6 +175,38 @@ def test_if_match_probe_does_not_disclose_another_users_hash(store) -> None: assert exc.value.detail["current_sha256"] == "" +def test_absence_precondition_refuses_a_live_row_without_probing_another_user( + store, monkeypatch +) -> None: + from server.memory.api.models_crud import MemorySetInput + from server.memory.app import conflicts, write + from tests.unit.test_memory_key_write_lock import FakeKeeper, _locks + + _locks(FakeKeeper(), monkeypatch) + monkeypatch.setattr(conflicts, "start_write_config", lambda *args: None) + + async def checked(input): + _, head = await write._set_fetch_existing(input) + await write._set_check_if_match(SimpleNamespace(input=input, existing=head)) + + monkeypatch.setattr(write, "_memory_set_phases", checked) + present = MemorySetInput( + org="o", + namespace="n", + agent="bot", + user_id="V", + memory_key="k", + value="new", + if_match_sha256="absent", + ) + with pytest.raises(HTTPException) as exc: + _run_as(None, lambda: write._handle_memory_set(present)) + assert exc.value.status_code == 409 and exc.value.detail["code"] == "PRECONDITION_FAILED" + own = present.model_copy(update={"user_id": "U"}) + _run_as(_pinned("U"), lambda: write._handle_memory_set(own)) + assert store["writes"] == [] + + @pytest.mark.parametrize("by", ["id", "key"]) def test_outcome_on_another_users_row_is_not_recorded(store, monkeypatch, by) -> None: import server.core.ch as ch_mod diff --git a/uv.lock b/uv.lock index c5aced7164..49ba6c530f 100644 --- a/uv.lock +++ b/uv.lock @@ -1,5 +1,5 @@ version = 1 -revision = 5 +revision = 3 requires-python = ">=3.12" resolution-markers = [ "python_full_version >= '3.15'", @@ -827,8 +827,12 @@ dev = [ { name = "build" }, { name = "cryptography" }, { name = "lemmagen3" }, + { name = "markdown" }, + { name = "markdown-it-py" }, + { name = "mdx-truly-sane-lists" }, { name = "mypy" }, { name = "pyarrow" }, + { name = "pymdown-extensions" }, { name = "pypdf" }, { name = "pytest" }, { name = "pytest-asyncio" }, @@ -881,6 +885,9 @@ requires-dist = [ { name = "idna", specifier = ">=3.7" }, { name = "lemmagen3", marker = "extra == 'dev'", specifier = ">=3.3" }, { name = "lemmagen3", marker = "extra == 'lemma'", specifier = ">=3.3" }, + { name = "markdown", marker = "extra == 'dev'", specifier = "==3.11.2" }, + { name = "markdown-it-py", marker = "extra == 'dev'", specifier = "==4.0.0" }, + { name = "mdx-truly-sane-lists", marker = "extra == 'dev'", specifier = "==1.3" }, { name = "mypy", marker = "extra == 'dev'", specifier = "==2.3.1" }, { name = "numpy", marker = "extra == 'code'", specifier = ">=1.26" }, { name = "opentelemetry-api", specifier = ">=1.45.2" }, @@ -894,6 +901,7 @@ requires-dist = [ { name = "pydantic", specifier = ">=2.9" }, { name = "pydantic-settings", specifier = ">=2.5" }, { name = "pyjwt", extras = ["crypto"], specifier = ">=2.10" }, + { name = "pymdown-extensions", marker = "extra == 'dev'", specifier = "==12.3" }, { name = "pypdf", marker = "extra == 'extractor'", specifier = ">=6.21,<7" }, { name = "pytest", marker = "extra == 'dev'", specifier = ">=8.0" }, { name = "pytest-asyncio", marker = "extra == 'dev'", specifier = ">=0.24" }, @@ -1671,6 +1679,48 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/ca/28/2635a8141c9a4f4bc23f5135a92bbcf48d928d8ca094088c962df1879d64/lz4-4.4.5-cp314-cp314-win_arm64.whl", hash = "sha256:d994b87abaa7a88ceb7a37c90f547b8284ff9da694e6afcfaa8568d739faf3f7", size = 93812, upload-time = "2025-11-03T13:02:26.133Z" }, ] +[[package]] +name = "markdown" +version = "3.11.2" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/f4/32/0b4d0297064244f04af4331b65de16237cc3cce07474171ee14222a28981/markdown-3.11.2.tar.gz", hash = "sha256:87bf5d90f2d2882e2c02fcda182c2800456b985bff38913867c49706481514b0", size = 491445, upload-time = "2026-10-19T19:41:42.687Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/fe/66/bcab3b677b71ad286b4e607e3427499537c76e13ad2e22584ba7a7d9882c/markdown-3.11.2-py3-none-any.whl", hash = "sha256:f80390747a2a0ff2ba54da074ce4f862f72a6685f608cd2637b646a6d83993f5", size = 114266, upload-time = "2026-10-19T19:41:41.244Z" }, +] + +[[package]] +name = "markdown-it-py" +version = "4.0.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "mdurl" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/5b/f5/4ec618ed16cc4f8fb3b701563655a69816155e79e24a17b651541804721d/markdown_it_py-4.0.0.tar.gz", hash = "sha256:cb0a2b4aa34f932c007117b194e945bd74e0ec24133ceb5bac59009cda1cb9f3", size = 73070, upload-time = "2025-08-11T12:57:52.854Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/94/54/e7d793b573f298e1c9013b8c4dade17d481164aa517d1d7148619c2cedbf/markdown_it_py-4.0.0-py3-none-any.whl", hash = "sha256:87327c59b172c5011896038353a81343b6754500a08cd7a4973bb48c6d578147", size = 87321, upload-time = "2025-08-11T12:57:51.923Z" }, +] + +[[package]] +name = "mdurl" +version = "0.1.2" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/d6/54/cfe61301667036ec958cb99bd3efefba235e65cdeb9c84d24a8293ba1d90/mdurl-0.1.2.tar.gz", hash = "sha256:bb413d29f5eea38f31dd4754dd7377d4465116fb207585f97bf925588687c1ba", size = 8729, upload-time = "2022-08-14T12:40:10.846Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/b3/38/89ba8ad64ae25be8de66a6d463314cf1eb366222074cfda9ee839c56a4b4/mdurl-0.1.2-py3-none-any.whl", hash = "sha256:84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8", size = 9979, upload-time = "2022-08-14T12:40:09.779Z" }, +] + +[[package]] +name = "mdx-truly-sane-lists" +version = "1.3" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "markdown" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/e6/27/16456314311abac2cedef4527679924e80ac4de19dd926699c1b261e0b9b/mdx_truly_sane_lists-1.3.tar.gz", hash = "sha256:b661022df7520a1e113af7c355c62216b384c867e4f59fb8ee7ad511e6e77f45", size = 5359, upload-time = "2022-07-19T13:42:45.153Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/3a/9e/dcd1027f7fd193aed152e01c6651a197c36b858f2cd1425ad04cb31a34fc/mdx_truly_sane_lists-1.3-py3-none-any.whl", hash = "sha256:b9546a4c40ff8f1ab692f77cee4b6bfe8ddf9cccf23f0a24e71f3716fe290a37", size = 6071, upload-time = "2022-07-19T13:42:43.375Z" }, +] + [[package]] name = "mmh3" version = "5.3.0" @@ -2756,6 +2806,19 @@ crypto = [ { name = "cryptography" }, ] +[[package]] +name = "pymdown-extensions" +version = "12.3" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "markdown" }, + { name = "pyyaml" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/f3/fe/ac50ee24a80a1b344e643f6fb626063cc7041b978cd1dd9a7f9963ae1cd1/pymdown_extensions-12.3.tar.gz", hash = "sha256:a7f2a4e0bc60c6e6babfa7922cfb3b01cd640eb00fb208f3c582e12bae00ea67", size = 870532, upload-time = "2026-10-14T22:40:43.252Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/8a/d0/758afe732c2da502c051b4d03ff88daa3c0fc1a1e671e6c5a6318177bab4/pymdown_extensions-12.3-py3-none-any.whl", hash = "sha256:345493a8e3497e24382902903a1c43a28e34a52f2b7571a1c9641429b820ca74", size = 277597, upload-time = "2026-10-14T22:40:41.543Z" }, +] + [[package]] name = "pypdf" version = "6.21.4" From 1a6858fa46e747524e2b4f116d3c3b29c653752f Mon Sep 17 00:00:00 2001 From: zlareb1 Date: Wed, 18 Nov 2026 10:39:24 +0000 Subject: [PATCH 03/22] Gateway bearer tests isolate their clock Keep token-cache time separate from model-call policy freshness. Exercise token rotation under an explicit customer and controlled process clock so stale policy cannot mask the expected 401 behavior. Signed-off-by: zlareb1 --- tests/unit/test_llm_gateway_bearer.py | 27 ++++++++++++++++++--------- 1 file changed, 18 insertions(+), 9 deletions(-) diff --git a/tests/unit/test_llm_gateway_bearer.py b/tests/unit/test_llm_gateway_bearer.py index a46ef103a4..8e88b776b8 100644 --- a/tests/unit/test_llm_gateway_bearer.py +++ b/tests/unit/test_llm_gateway_bearer.py @@ -50,7 +50,7 @@ def token_file(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> Iterator[Path @pytest.fixture def clock(monkeypatch: pytest.MonkeyPatch) -> ManualClock: c = ManualClock(t=1000.0) - monkeypatch.setattr(gateway.time, "monotonic", c.monotonic) + monkeypatch.setattr(gateway, "time", c) return c @@ -139,14 +139,23 @@ def test_the_file_is_read_at_most_once_a_minute(token_file, clock) -> None: assert asyncio.run(gateway.bearer("", "https://gateway.example/v1")) == "sa-token-2" -def test_a_401_makes_the_next_call_read_the_file_again(token_file, clock, wire) -> None: - _chat() - token_file.write_text("sa-token-2") - wire.refused.add("Bearer sa-token-1") # the gateway no longer takes it - with pytest.raises(httpx.HTTPStatusError, match="401"): - _chat() # not retried: the same token would be refused again - _chat() # no time has passed: the 401 alone made it read the file - assert wire.bearers == ["Bearer sa-token-1", "Bearer sa-token-1", "Bearer sa-token-2"] +def test_a_401_makes_the_next_call_read_the_file_again(token_file, monkeypatch, request) -> None: + from server.llm import customer + from tests.unit.switch_state import switch_off + + process_clock = ManualClock(t=0.0) + monkeypatch.setattr("time.monotonic", process_clock.monotonic) + switch_off() + request.getfixturevalue("clock") + wire = request.getfixturevalue("wire") + with customer.for_org("gateway-bearer-test"): + _chat() + token_file.write_text("sa-token-2") + wire.refused.add("Bearer sa-token-1") # the gateway no longer takes it + with pytest.raises(httpx.HTTPStatusError, match="401"): + _chat() # not retried: the same token would be refused again + _chat() # no time has passed: the 401 alone made it read the file + assert wire.bearers == ["Bearer sa-token-1", "Bearer sa-token-1", "Bearer sa-token-2"] def test_an_unreadable_file_serves_the_token_in_hand_and_with_none_is_an_outage( From d26a8e9f66110f6d342e6e8bffc01e25599f805e Mon Sep 17 00:00:00 2001 From: zlareb1 Date: Wed, 18 Nov 2026 10:49:15 +0000 Subject: [PATCH 04/22] Restore mirror failure tests to their request context Bind the marked work bag to the serialization check so later event tests cannot inherit it. Signed-off-by: zlareb1 (cherry picked from commit c31556892c452423fd098de0f67f0dc731c15958) Signed-off-by: zlareb1 --- tests/unit/test_assistant_mirror_boundary.py | 34 ++++++++++---------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/tests/unit/test_assistant_mirror_boundary.py b/tests/unit/test_assistant_mirror_boundary.py index bd51b0fbf3..6c989968dd 100644 --- a/tests/unit/test_assistant_mirror_boundary.py +++ b/tests/unit/test_assistant_mirror_boundary.py @@ -165,23 +165,23 @@ def test_mcp_failures_keep_the_mark_after_protocol_unwrapping( 500: RuntimeError("private detail"), }[status] monkeypatch.setattr(mcp_outcome, "_emit_mcp_event", lambda *a, **kw: None) - request_work.begin() - request_work.mark_mirrored() - with private_work(): - result = mcp_outcome._handler_failed( - error, - 1, - "loom_assistant_ask", - SimpleNamespace(name="assistant.ask", idempotent=False), - {}, - None, - _caller(), - "request", - "session", - rl_ns="notes", - rl_org="example", - elapsed_ms=1, - ) + with request_work.bind(request_work.RequestWork()): + request_work.mark_mirrored() + with private_work(): + result = mcp_outcome._handler_failed( + error, + 1, + "loom_assistant_ask", + SimpleNamespace(name="assistant.ask", idempotent=False), + {}, + None, + _caller(), + "request", + "session", + rl_ns="notes", + rl_org="example", + elapsed_ms=1, + ) assert next(iter(result)) == "mirrored" and result["mirrored"] is True if status == 403: body = result["result"] From b85d8f49fb35d23c0b04a26db04b37c126715fbe Mon Sep 17 00:00:00 2001 From: zlareb1 Date: Wed, 18 Nov 2026 11:29:40 +0000 Subject: [PATCH 05/22] Install Node tooling from integrity-locked package trees Keep compiler and agent CLI dependencies reproducible across native and container installs. Use a patched locked workflow package manager and check release package signatures before importing code with install scripts disabled. Signed-off-by: zlareb1 --- .devcontainer/agent-cli/package-lock.json | 142 ++ .devcontainer/agent-cli/package.json | 8 + .devcontainer/start-loom.sh | 4 +- .github/agent-clis/package-lock.json | 265 ++++ .github/agent-clis/package.json | 9 + .github/pnpm/package-lock.json | 31 + .github/pnpm/package.json | 8 + .github/workflows/docker-smoke.yml | 2 + .github/workflows/n8n-publish.yml | 13 +- .github/workflows/plugin-platforms.yml | 27 +- .github/workflows/release-check.yml | 4 +- Dockerfile | 1 + .../.devcontainer/agent-cli/package-lock.json | 142 ++ .../.devcontainer/agent-cli/package.json | 8 + .../.devcontainer/start-loom.sh | 4 +- integrations/n8n/package.json | 2 +- scripts/code-toolchains/package-lock.json | 1241 +++++++++++++++++ scripts/code-toolchains/package.json | 12 + .../yarn-modern/package-lock.json | 28 + .../code-toolchains/yarn-modern/package.json | 8 + scripts/install-code-toolchains.sh | 19 +- tests/unit/test_course_starter.py | 9 +- 22 files changed, 1955 insertions(+), 32 deletions(-) create mode 100644 .devcontainer/agent-cli/package-lock.json create mode 100644 .devcontainer/agent-cli/package.json create mode 100644 .github/agent-clis/package-lock.json create mode 100644 .github/agent-clis/package.json create mode 100644 .github/pnpm/package-lock.json create mode 100644 .github/pnpm/package.json create mode 100644 examples/course-starter/.devcontainer/agent-cli/package-lock.json create mode 100644 examples/course-starter/.devcontainer/agent-cli/package.json create mode 100644 scripts/code-toolchains/package-lock.json create mode 100644 scripts/code-toolchains/package.json create mode 100644 scripts/code-toolchains/yarn-modern/package-lock.json create mode 100644 scripts/code-toolchains/yarn-modern/package.json diff --git a/.devcontainer/agent-cli/package-lock.json b/.devcontainer/agent-cli/package-lock.json new file mode 100644 index 0000000000..5fe87ef671 --- /dev/null +++ b/.devcontainer/agent-cli/package-lock.json @@ -0,0 +1,142 @@ +{ + "name": "loom-devcontainer-agent-cli", + "version": "0.0.0", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "loom-devcontainer-agent-cli", + "version": "0.0.0", + "dependencies": { + "@anthropic-ai/claude-code": "2.1.319" + } + }, + "node_modules/@anthropic-ai/claude-code": { + "version": "2.1.319", + "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code/-/claude-code-2.1.319.tgz", + "integrity": "sha512-XoyAxGXBmNsb9ahz0xLAtyz/I6b1j+4lyLpucyTQIq4FcKUxrMDM2AzA2sHipHoN1DdMJINQQrLZxRZRq7FqBA==", + "hasInstallScript": true, + "license": "SEE LICENSE IN README.md", + "bin": { + "claude": "bin/claude.exe" + }, + "engines": { + "node": ">=22.0.0" + }, + "optionalDependencies": { + "@anthropic-ai/claude-code-darwin-arm64": "2.1.319", + "@anthropic-ai/claude-code-darwin-x64": "2.1.319", + "@anthropic-ai/claude-code-linux-arm64": "2.1.319", + "@anthropic-ai/claude-code-linux-arm64-musl": "2.1.319", + "@anthropic-ai/claude-code-linux-x64": "2.1.319", + "@anthropic-ai/claude-code-linux-x64-musl": "2.1.319", + "@anthropic-ai/claude-code-win32-arm64": "2.1.319", + "@anthropic-ai/claude-code-win32-x64": "2.1.319" + } + }, + "node_modules/@anthropic-ai/claude-code-darwin-arm64": { + "version": "2.1.319", + "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code-darwin-arm64/-/claude-code-darwin-arm64-2.1.319.tgz", + "integrity": "sha512-dyAOFnsXbeyGgFJMlo2n6zSgLli5r4fTZ3Tj48eELxjccqM4s/wUmQ6P0DyCbxU0EC44VV44T2qj5xEpen25aA==", + "cpu": [ + "arm64" + ], + "license": "SEE LICENSE IN LICENSE.md", + "optional": true, + "os": [ + "darwin" + ] + }, + "node_modules/@anthropic-ai/claude-code-darwin-x64": { + "version": "2.1.319", + "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code-darwin-x64/-/claude-code-darwin-x64-2.1.319.tgz", + "integrity": "sha512-XuzaFESZRKPupllcbbFCy0xdw9G9+VHLWbXaJhJhUD4gNTmt/ALkKMnECwr3umA7if1cAGDNb2tcgRCIpIy+nQ==", + "cpu": [ + "x64" + ], + "license": "SEE LICENSE IN LICENSE.md", + "optional": true, + "os": [ + "darwin" + ] + }, + "node_modules/@anthropic-ai/claude-code-linux-arm64": { + "version": "2.1.319", + "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code-linux-arm64/-/claude-code-linux-arm64-2.1.319.tgz", + "integrity": "sha512-PlyxaZTAuU0VF3P/ERF4+deMRjT57cr90SHCrYms3HTebr3eItEWJozw6zq9cs88tc8XoF9ESAIghKXfq9HACg==", + "cpu": [ + "arm64" + ], + "license": "SEE LICENSE IN LICENSE.md", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@anthropic-ai/claude-code-linux-arm64-musl": { + "version": "2.1.319", + "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code-linux-arm64-musl/-/claude-code-linux-arm64-musl-2.1.319.tgz", + "integrity": "sha512-969quP2nXj7GRHzLSe9kov9c/f2p+ZuZrXkrvaenbLOX6zZJtyqZKRUyhDUjaVmSEEGFSxgCr/BtUMOXV8jaOw==", + "cpu": [ + "arm64" + ], + "license": "SEE LICENSE IN LICENSE.md", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@anthropic-ai/claude-code-linux-x64": { + "version": "2.1.319", + "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code-linux-x64/-/claude-code-linux-x64-2.1.319.tgz", + "integrity": "sha512-FO4Sd23BO1VCQPiJe5vG3bNnmV5+YiTau7o1lqK3Fr5VlE4TLdKiyYpwQRwEXO91kE2l12Ep2i7J19T8Md2oOQ==", + "cpu": [ + "x64" + ], + "license": "SEE LICENSE IN LICENSE.md", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@anthropic-ai/claude-code-linux-x64-musl": { + "version": "2.1.319", + "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code-linux-x64-musl/-/claude-code-linux-x64-musl-2.1.319.tgz", + "integrity": "sha512-LAj03VLWWZ+5T2c3dMxWZh5BhFzExwywIpT6y1oHnBj0Tx/ILIXYF1z6lcKSYsmiKChixPWzso35QnIfYLO8jg==", + "cpu": [ + "x64" + ], + "license": "SEE LICENSE IN LICENSE.md", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@anthropic-ai/claude-code-win32-arm64": { + "version": "2.1.319", + "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code-win32-arm64/-/claude-code-win32-arm64-2.1.319.tgz", + "integrity": "sha512-LJXWhy1rZGysmjwmC1/kapdaM55phYFPa3MGad033F01f76+q1lT4N8TCPC6wysHxrkLed/yucLGqMSTNY63cg==", + "cpu": [ + "arm64" + ], + "license": "SEE LICENSE IN LICENSE.md", + "optional": true, + "os": [ + "win32" + ] + }, + "node_modules/@anthropic-ai/claude-code-win32-x64": { + "version": "2.1.319", + "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code-win32-x64/-/claude-code-win32-x64-2.1.319.tgz", + "integrity": "sha512-wncPKSYL/zvjs84k7wZEj+IGQx/LjqQNhgnQhzDEibP0yAVBguAs4p8nBfFAEDbDdUc4Z2co+OaKZV1t02xINA==", + "cpu": [ + "x64" + ], + "license": "SEE LICENSE IN LICENSE.md", + "optional": true, + "os": [ + "win32" + ] + } + } +} diff --git a/.devcontainer/agent-cli/package.json b/.devcontainer/agent-cli/package.json new file mode 100644 index 0000000000..ea91177227 --- /dev/null +++ b/.devcontainer/agent-cli/package.json @@ -0,0 +1,8 @@ +{ + "name": "loom-devcontainer-agent-cli", + "private": true, + "version": "0.0.0", + "dependencies": { + "@anthropic-ai/claude-code": "2.1.319" + } +} diff --git a/.devcontainer/start-loom.sh b/.devcontainer/start-loom.sh index f8ee5213e8..181db00ff7 100755 --- a/.devcontainer/start-loom.sh +++ b/.devcontainer/start-loom.sh @@ -43,7 +43,9 @@ fi # is connected below, so the installer connects no agent. LOOM_CONNECT=none sh "$installer" -npm install --global --silent @anthropic-ai/claude-code +script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd) +npm ci --prefix "$script_dir/agent-cli" --no-fund --no-audit +npm install --global --offline --ignore-scripts --silent "$script_dir/agent-cli/node_modules/@anthropic-ai/claude-code" claude plugin marketplace list 2>/dev/null | grep -Eq '[[:space:]]loom$' \ || claude plugin marketplace add ClickHouse/loom claude plugin install loom@loom diff --git a/.github/agent-clis/package-lock.json b/.github/agent-clis/package-lock.json new file mode 100644 index 0000000000..36ed216922 --- /dev/null +++ b/.github/agent-clis/package-lock.json @@ -0,0 +1,265 @@ +{ + "name": "loom-github-agent-clis", + "version": "0.0.0", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "loom-github-agent-clis", + "version": "0.0.0", + "dependencies": { + "@anthropic-ai/claude-code": "2.1.319", + "@openai/codex": "0.162.1" + } + }, + "node_modules/@anthropic-ai/claude-code": { + "version": "2.1.319", + "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code/-/claude-code-2.1.319.tgz", + "integrity": "sha512-XoyAxGXBmNsb9ahz0xLAtyz/I6b1j+4lyLpucyTQIq4FcKUxrMDM2AzA2sHipHoN1DdMJINQQrLZxRZRq7FqBA==", + "hasInstallScript": true, + "license": "SEE LICENSE IN README.md", + "bin": { + "claude": "bin/claude.exe" + }, + "engines": { + "node": ">=22.0.0" + }, + "optionalDependencies": { + "@anthropic-ai/claude-code-darwin-arm64": "2.1.319", + "@anthropic-ai/claude-code-darwin-x64": "2.1.319", + "@anthropic-ai/claude-code-linux-arm64": "2.1.319", + "@anthropic-ai/claude-code-linux-arm64-musl": "2.1.319", + "@anthropic-ai/claude-code-linux-x64": "2.1.319", + "@anthropic-ai/claude-code-linux-x64-musl": "2.1.319", + "@anthropic-ai/claude-code-win32-arm64": "2.1.319", + "@anthropic-ai/claude-code-win32-x64": "2.1.319" + } + }, + "node_modules/@anthropic-ai/claude-code-darwin-arm64": { + "version": "2.1.319", + "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code-darwin-arm64/-/claude-code-darwin-arm64-2.1.319.tgz", + "integrity": "sha512-dyAOFnsXbeyGgFJMlo2n6zSgLli5r4fTZ3Tj48eELxjccqM4s/wUmQ6P0DyCbxU0EC44VV44T2qj5xEpen25aA==", + "cpu": [ + "arm64" + ], + "license": "SEE LICENSE IN LICENSE.md", + "optional": true, + "os": [ + "darwin" + ] + }, + "node_modules/@anthropic-ai/claude-code-darwin-x64": { + "version": "2.1.319", + "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code-darwin-x64/-/claude-code-darwin-x64-2.1.319.tgz", + "integrity": "sha512-XuzaFESZRKPupllcbbFCy0xdw9G9+VHLWbXaJhJhUD4gNTmt/ALkKMnECwr3umA7if1cAGDNb2tcgRCIpIy+nQ==", + "cpu": [ + "x64" + ], + "license": "SEE LICENSE IN LICENSE.md", + "optional": true, + "os": [ + "darwin" + ] + }, + "node_modules/@anthropic-ai/claude-code-linux-arm64": { + "version": "2.1.319", + "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code-linux-arm64/-/claude-code-linux-arm64-2.1.319.tgz", + "integrity": "sha512-PlyxaZTAuU0VF3P/ERF4+deMRjT57cr90SHCrYms3HTebr3eItEWJozw6zq9cs88tc8XoF9ESAIghKXfq9HACg==", + "cpu": [ + "arm64" + ], + "license": "SEE LICENSE IN LICENSE.md", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@anthropic-ai/claude-code-linux-arm64-musl": { + "version": "2.1.319", + "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code-linux-arm64-musl/-/claude-code-linux-arm64-musl-2.1.319.tgz", + "integrity": "sha512-969quP2nXj7GRHzLSe9kov9c/f2p+ZuZrXkrvaenbLOX6zZJtyqZKRUyhDUjaVmSEEGFSxgCr/BtUMOXV8jaOw==", + "cpu": [ + "arm64" + ], + "license": "SEE LICENSE IN LICENSE.md", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@anthropic-ai/claude-code-linux-x64": { + "version": "2.1.319", + "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code-linux-x64/-/claude-code-linux-x64-2.1.319.tgz", + "integrity": "sha512-FO4Sd23BO1VCQPiJe5vG3bNnmV5+YiTau7o1lqK3Fr5VlE4TLdKiyYpwQRwEXO91kE2l12Ep2i7J19T8Md2oOQ==", + "cpu": [ + "x64" + ], + "license": "SEE LICENSE IN LICENSE.md", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@anthropic-ai/claude-code-linux-x64-musl": { + "version": "2.1.319", + "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code-linux-x64-musl/-/claude-code-linux-x64-musl-2.1.319.tgz", + "integrity": "sha512-LAj03VLWWZ+5T2c3dMxWZh5BhFzExwywIpT6y1oHnBj0Tx/ILIXYF1z6lcKSYsmiKChixPWzso35QnIfYLO8jg==", + "cpu": [ + "x64" + ], + "license": "SEE LICENSE IN LICENSE.md", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@anthropic-ai/claude-code-win32-arm64": { + "version": "2.1.319", + "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code-win32-arm64/-/claude-code-win32-arm64-2.1.319.tgz", + "integrity": "sha512-LJXWhy1rZGysmjwmC1/kapdaM55phYFPa3MGad033F01f76+q1lT4N8TCPC6wysHxrkLed/yucLGqMSTNY63cg==", + "cpu": [ + "arm64" + ], + "license": "SEE LICENSE IN LICENSE.md", + "optional": true, + "os": [ + "win32" + ] + }, + "node_modules/@anthropic-ai/claude-code-win32-x64": { + "version": "2.1.319", + "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code-win32-x64/-/claude-code-win32-x64-2.1.319.tgz", + "integrity": "sha512-wncPKSYL/zvjs84k7wZEj+IGQx/LjqQNhgnQhzDEibP0yAVBguAs4p8nBfFAEDbDdUc4Z2co+OaKZV1t02xINA==", + "cpu": [ + "x64" + ], + "license": "SEE LICENSE IN LICENSE.md", + "optional": true, + "os": [ + "win32" + ] + }, + "node_modules/@openai/codex": { + "version": "0.162.1", + "resolved": "https://registry.npmjs.org/@openai/codex/-/codex-0.162.1.tgz", + "integrity": "sha512-NWZdi/kxyjv/8EUGFupziGU38YyleugZRM4JXgY5XFH7FUmaFA33NZS2Bmq0HPazf7S3jJQQWsZ/jAK9jsrV3Q==", + "license": "Apache-2.0", + "bin": { + "codex": "bin/codex.js" + }, + "engines": { + "node": ">=16" + }, + "optionalDependencies": { + "@openai/codex-darwin-arm64": "npm:@openai/codex@0.162.1-darwin-arm64", + "@openai/codex-darwin-x64": "npm:@openai/codex@0.162.1-darwin-x64", + "@openai/codex-linux-arm64": "npm:@openai/codex@0.162.1-linux-arm64", + "@openai/codex-linux-x64": "npm:@openai/codex@0.162.1-linux-x64", + "@openai/codex-win32-arm64": "npm:@openai/codex@0.162.1-win32-arm64", + "@openai/codex-win32-x64": "npm:@openai/codex@0.162.1-win32-x64" + } + }, + "node_modules/@openai/codex-darwin-arm64": { + "name": "@openai/codex", + "version": "0.162.1-darwin-arm64", + "resolved": "https://registry.npmjs.org/@openai/codex/-/codex-0.162.1-darwin-arm64.tgz", + "integrity": "sha512-YVXpg57itBuQxjofay3KDF5UbnZF4Y1ZmNFzUCz0ZQiQN+DndxOjN5V87rnXvPaC4qCPO2El74DzewoBP8JyPQ==", + "cpu": [ + "arm64" + ], + "license": "Apache-2.0", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=16" + } + }, + "node_modules/@openai/codex-darwin-x64": { + "name": "@openai/codex", + "version": "0.162.1-darwin-x64", + "resolved": "https://registry.npmjs.org/@openai/codex/-/codex-0.162.1-darwin-x64.tgz", + "integrity": "sha512-0/WHRhbUnM1wAjfyCO54Q8s4vQRxLVBbqW6XuQf7rZTEMTYPKRIQU9aPeRgjG653ZCSjtBrslWQ+G9urY9CksQ==", + "cpu": [ + "x64" + ], + "license": "Apache-2.0", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=16" + } + }, + "node_modules/@openai/codex-linux-arm64": { + "name": "@openai/codex", + "version": "0.162.1-linux-arm64", + "resolved": "https://registry.npmjs.org/@openai/codex/-/codex-0.162.1-linux-arm64.tgz", + "integrity": "sha512-Ss7W/SrKtQFNaMtSojNoiykJgX+iDC8daM+YrcvgmJADtQPk0cd3w6Dna4CYH2CYvf9nQranj69fpcTzZ3sQIQ==", + "cpu": [ + "arm64" + ], + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=16" + } + }, + "node_modules/@openai/codex-linux-x64": { + "name": "@openai/codex", + "version": "0.162.1-linux-x64", + "resolved": "https://registry.npmjs.org/@openai/codex/-/codex-0.162.1-linux-x64.tgz", + "integrity": "sha512-cjK2mdHIfEepZ1lQ1MX3aTQC+8ncIsvnacl/6vI2dIIcfP8/MrhTQ2+qRlkXFNDzJSj1d36quIszP+3/4CUJWQ==", + "cpu": [ + "x64" + ], + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=16" + } + }, + "node_modules/@openai/codex-win32-arm64": { + "name": "@openai/codex", + "version": "0.162.1-win32-arm64", + "resolved": "https://registry.npmjs.org/@openai/codex/-/codex-0.162.1-win32-arm64.tgz", + "integrity": "sha512-teVVACnEcupkR6XSmUQKwlGg/oA15d1DQDPVSoAfilHgctPEpTi5y11jYS6JhJO+AFnYM84gyo5SOS5vlnCQSg==", + "cpu": [ + "arm64" + ], + "license": "Apache-2.0", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=16" + } + }, + "node_modules/@openai/codex-win32-x64": { + "name": "@openai/codex", + "version": "0.162.1-win32-x64", + "resolved": "https://registry.npmjs.org/@openai/codex/-/codex-0.162.1-win32-x64.tgz", + "integrity": "sha512-dfl4MhHuEi0ARKyNmrTxk+RQmsWNCQAoVLUtrYq+yrW1C8P2sg5ziwgHUUACHjYLKuACV7ARH5Nq5pnCz3GlaQ==", + "cpu": [ + "x64" + ], + "license": "Apache-2.0", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=16" + } + } + } +} diff --git a/.github/agent-clis/package.json b/.github/agent-clis/package.json new file mode 100644 index 0000000000..e93a1417be --- /dev/null +++ b/.github/agent-clis/package.json @@ -0,0 +1,9 @@ +{ + "name": "loom-github-agent-clis", + "private": true, + "version": "0.0.0", + "dependencies": { + "@anthropic-ai/claude-code": "2.1.319", + "@openai/codex": "0.162.1" + } +} diff --git a/.github/pnpm/package-lock.json b/.github/pnpm/package-lock.json new file mode 100644 index 0000000000..ea460ad8e0 --- /dev/null +++ b/.github/pnpm/package-lock.json @@ -0,0 +1,31 @@ +{ + "name": "loom-github-pnpm", + "version": "0.0.0", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "loom-github-pnpm", + "version": "0.0.0", + "dependencies": { + "pnpm": "10.34.9" + } + }, + "node_modules/pnpm": { + "version": "10.34.9", + "resolved": "https://registry.npmjs.org/pnpm/-/pnpm-10.34.9.tgz", + "integrity": "sha512-9JtajqD97bRLs8DB1ldQkqU8KVDZW3rRXfEfF5dId6LeOgHAfpNOmyjOcW5RwJqUlixzBtCb4uHksYqMh2L9Mg==", + "license": "MIT", + "bin": { + "pnpm": "bin/pnpm.cjs", + "pnpx": "bin/pnpx.cjs" + }, + "engines": { + "node": ">=18.12" + }, + "funding": { + "url": "https://opencollective.com/pnpm" + } + } + } +} diff --git a/.github/pnpm/package.json b/.github/pnpm/package.json new file mode 100644 index 0000000000..2a9092d796 --- /dev/null +++ b/.github/pnpm/package.json @@ -0,0 +1,8 @@ +{ + "name": "loom-github-pnpm", + "private": true, + "version": "0.0.0", + "dependencies": { + "pnpm": "10.34.9" + } +} diff --git a/.github/workflows/docker-smoke.yml b/.github/workflows/docker-smoke.yml index 3088015c40..55e7c33ca7 100644 --- a/.github/workflows/docker-smoke.yml +++ b/.github/workflows/docker-smoke.yml @@ -15,6 +15,7 @@ on: "frontend/**", "tests/fixtures/docker_provider_app.py", "scripts/install-code-toolchains.sh", + "scripts/code-toolchains/**", "scripts/serve.sh", "scripts/scip_harness/**", "scripts/release/build_stack_bundle.py", @@ -48,6 +49,7 @@ on: "frontend/**", "tests/fixtures/docker_provider_app.py", "scripts/install-code-toolchains.sh", + "scripts/code-toolchains/**", "scripts/serve.sh", "scripts/scip_harness/**", "scripts/release/build_stack_bundle.py", diff --git a/.github/workflows/n8n-publish.yml b/.github/workflows/n8n-publish.yml index 72244adf0f..bd05f02680 100644 --- a/.github/workflows/n8n-publish.yml +++ b/.github/workflows/n8n-publish.yml @@ -5,6 +5,7 @@ on: paths: - integrations/n8n/** - .github/workflows/n8n-publish.yml + - .github/pnpm/** push: tags: - v* @@ -22,7 +23,10 @@ jobs: - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 with: node-version: "24" - - run: npm install --global pnpm@10.32.1 + - name: Install the locked package manager + run: | + npm ci --prefix .github/pnpm --no-fund --no-audit + echo "$PWD/.github/pnpm/node_modules/.bin" >> "$GITHUB_PATH" - run: pnpm install --frozen-lockfile working-directory: integrations/n8n - run: pnpm check @@ -34,7 +38,7 @@ jobs: mkdir "$RUNNER_TEMP/n8n-package-check" cd "$RUNNER_TEMP/n8n-package-check" npm init --yes - npm install "$GITHUB_WORKSPACE/integrations/n8n/package.tgz" + npm install --ignore-scripts "$GITHUB_WORKSPACE/integrations/n8n/package.tgz" node -e 'for (const path of ["Loom/Loom.node", "LoomMemory/LoomMemory.node"]) require("@clickhouse/n8n-nodes-loom/dist/nodes/" + path + ".js")' publish: @@ -57,7 +61,10 @@ jobs: env: RELEASE_TAG: ${{ github.ref_name }} run: '[[ "$RELEASE_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]' - - run: npm install --global pnpm@10.32.1 + - name: Install the locked package manager + run: | + npm ci --prefix .github/pnpm --no-fund --no-audit + echo "$PWD/.github/pnpm/node_modules/.bin" >> "$GITHUB_PATH" - run: pnpm install --frozen-lockfile working-directory: integrations/n8n - run: pnpm build diff --git a/.github/workflows/plugin-platforms.yml b/.github/workflows/plugin-platforms.yml index b4d5899165..33ef0ab243 100644 --- a/.github/workflows/plugin-platforms.yml +++ b/.github/workflows/plugin-platforms.yml @@ -16,6 +16,7 @@ on: - ".agents/plugins/**" - ".gitattributes" - ".github/workflows/plugin-platforms.yml" + - ".github/agent-clis/**" pull_request: branches: [main, "release/**"] paths: @@ -24,6 +25,7 @@ on: - ".agents/plugins/**" - ".gitattributes" - ".github/workflows/plugin-platforms.yml" + - ".github/agent-clis/**" concurrency: group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.ref || github.sha }} @@ -34,9 +36,6 @@ permissions: env: NODE_VERSION: "22" - # The agent versions the end-to-end sessions run. - CLAUDE_CODE_VERSION: "2.1.319" - CODEX_VERSION: "0.162.1" jobs: platform: @@ -70,11 +69,11 @@ jobs: - name: install the agent CLIs if: ${{ !cancelled() }} run: | - npm install --global --no-fund --no-audit "@anthropic-ai/claude-code@$CLAUDE_CODE_VERSION" "@openai/codex@$CODEX_VERSION" - root=$(npm root --global) + npm ci --prefix .github/agent-clis --no-fund --no-audit + root=$(npm root --prefix .github/agent-clis) exe='' if [ "$RUNNER_OS" = Windows ]; then root=$(cygpath -m "$root"); exe=.exe; fi - codex=$(ls "$root"/@openai/codex/node_modules/@openai/codex-*/vendor/*/bin/codex$exe | head -1) + codex=$(ls "$root"/@openai/codex-*/vendor/*/bin/codex$exe | head -1) echo "CLAUDE_BIN=$root/@anthropic-ai/claude-code/bin/claude.exe" >> "$GITHUB_ENV" echo "CODEX_BIN=$codex" >> "$GITHUB_ENV" - name: Claude Code session @@ -123,12 +122,12 @@ jobs: # bash is for Claude Code's own shell tool; the hooks run under BusyBox sh. - name: suite and sessions in node:22-alpine run: | - docker run --rm -v "$PWD:/src:ro" -e CLAUDE_CODE_VERSION -e CODEX_VERSION "$ALPINE_IMAGE" sh -euc ' + docker run --rm -v "$PWD:/src:ro" "$ALPINE_IMAGE" sh -euc ' apk add --quiet git bash cp -r /src /tmp/repo && chown -R node /tmp/repo - npm install --global --no-fund --no-audit "@anthropic-ai/claude-code@$CLAUDE_CODE_VERSION" "@openai/codex@$CODEX_VERSION" >/dev/null - root=$(npm root --global) - codex=$(ls "$root"/@openai/codex/node_modules/@openai/codex-linux-*/vendor/*/bin/codex | head -1) + npm ci --prefix /tmp/repo/.github/agent-clis --no-fund --no-audit >/dev/null + root=$(npm root --prefix /tmp/repo/.github/agent-clis) + codex=$(ls "$root"/@openai/codex-linux-*/vendor/*/bin/codex | head -1) su node -s /bin/sh -c " set -e cd /tmp/repo @@ -163,9 +162,9 @@ jobs: # A clone inside WSL, with Linux modes and line endings, as a WSL user's is. git -c safe.directory='*' clone --quiet --no-local . /home/ci/repo chown -R ci /home/ci/repo - npm install --global --no-fund --no-audit "@anthropic-ai/claude-code@$CLAUDE_CODE_VERSION" "@openai/codex@$CODEX_VERSION" >/dev/null - root=$(npm root --global) - codex=$(ls "$root"/@openai/codex/node_modules/@openai/codex-linux-*/vendor/*/bin/codex | head -1) + npm ci --prefix /home/ci/repo/.github/agent-clis --no-fund --no-audit >/dev/null + root=$(npm root --prefix /home/ci/repo/.github/agent-clis) + codex=$(ls "$root"/@openai/codex-linux-*/vendor/*/bin/codex | head -1) su ci -s /bin/sh -c " set -e cd /home/ci/repo @@ -177,5 +176,3 @@ jobs: node integrations/claude-code-plugin/tests/e2e/agent-session.mjs claude --bin $root/@anthropic-ai/claude-code/bin/claude.exe --expect-tool Bash node integrations/claude-code-plugin/tests/e2e/agent-session.mjs codex --bin $codex " - env: - WSLENV: CLAUDE_CODE_VERSION:CODEX_VERSION diff --git a/.github/workflows/release-check.yml b/.github/workflows/release-check.yml index 98f1210e30..6fb6307b78 100644 --- a/.github/workflows/release-check.yml +++ b/.github/workflows/release-check.yml @@ -131,6 +131,6 @@ jobs: run: | mkdir -p "$RUNNER_TEMP/npm" && cd "$RUNNER_TEMP/npm" npm init -y >/dev/null - npm install --no-audit --no-fund "@clickhouse/loom@$VERSION" - node -e 'const { SDK_VERSION } = require("@clickhouse/loom"); if (SDK_VERSION !== process.argv[1]) { throw new Error(SDK_VERSION) }' "$VERSION" + npm install --ignore-scripts --no-audit --no-fund "@clickhouse/loom@$VERSION" npm audit signatures + node -e 'const { SDK_VERSION } = require("@clickhouse/loom"); if (SDK_VERSION !== process.argv[1]) { throw new Error(SDK_VERSION) }' "$VERSION" diff --git a/Dockerfile b/Dockerfile index 41de98c023..9a45ff6823 100644 --- a/Dockerfile +++ b/Dockerfile @@ -102,6 +102,7 @@ RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates && mkdir -p /usr/local/node && tar -C /usr/local/node --strip-components=1 -xJf /tmp/node.txz && rm /tmp/node.txz /tmp/node.txz.sha256 ENV PATH=/usr/local/node/bin:$PATH COPY scripts/install-code-toolchains.sh /tmp/install-code-toolchains.sh +COPY scripts/code-toolchains /tmp/code-toolchains RUN LOOM_CODE_TOOLCHAIN_PREFIX=/usr/local/node sh /tmp/install-code-toolchains.sh \ && npm cache clean --force diff --git a/examples/course-starter/.devcontainer/agent-cli/package-lock.json b/examples/course-starter/.devcontainer/agent-cli/package-lock.json new file mode 100644 index 0000000000..5fe87ef671 --- /dev/null +++ b/examples/course-starter/.devcontainer/agent-cli/package-lock.json @@ -0,0 +1,142 @@ +{ + "name": "loom-devcontainer-agent-cli", + "version": "0.0.0", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "loom-devcontainer-agent-cli", + "version": "0.0.0", + "dependencies": { + "@anthropic-ai/claude-code": "2.1.319" + } + }, + "node_modules/@anthropic-ai/claude-code": { + "version": "2.1.319", + "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code/-/claude-code-2.1.319.tgz", + "integrity": "sha512-XoyAxGXBmNsb9ahz0xLAtyz/I6b1j+4lyLpucyTQIq4FcKUxrMDM2AzA2sHipHoN1DdMJINQQrLZxRZRq7FqBA==", + "hasInstallScript": true, + "license": "SEE LICENSE IN README.md", + "bin": { + "claude": "bin/claude.exe" + }, + "engines": { + "node": ">=22.0.0" + }, + "optionalDependencies": { + "@anthropic-ai/claude-code-darwin-arm64": "2.1.319", + "@anthropic-ai/claude-code-darwin-x64": "2.1.319", + "@anthropic-ai/claude-code-linux-arm64": "2.1.319", + "@anthropic-ai/claude-code-linux-arm64-musl": "2.1.319", + "@anthropic-ai/claude-code-linux-x64": "2.1.319", + "@anthropic-ai/claude-code-linux-x64-musl": "2.1.319", + "@anthropic-ai/claude-code-win32-arm64": "2.1.319", + "@anthropic-ai/claude-code-win32-x64": "2.1.319" + } + }, + "node_modules/@anthropic-ai/claude-code-darwin-arm64": { + "version": "2.1.319", + "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code-darwin-arm64/-/claude-code-darwin-arm64-2.1.319.tgz", + "integrity": "sha512-dyAOFnsXbeyGgFJMlo2n6zSgLli5r4fTZ3Tj48eELxjccqM4s/wUmQ6P0DyCbxU0EC44VV44T2qj5xEpen25aA==", + "cpu": [ + "arm64" + ], + "license": "SEE LICENSE IN LICENSE.md", + "optional": true, + "os": [ + "darwin" + ] + }, + "node_modules/@anthropic-ai/claude-code-darwin-x64": { + "version": "2.1.319", + "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code-darwin-x64/-/claude-code-darwin-x64-2.1.319.tgz", + "integrity": "sha512-XuzaFESZRKPupllcbbFCy0xdw9G9+VHLWbXaJhJhUD4gNTmt/ALkKMnECwr3umA7if1cAGDNb2tcgRCIpIy+nQ==", + "cpu": [ + "x64" + ], + "license": "SEE LICENSE IN LICENSE.md", + "optional": true, + "os": [ + "darwin" + ] + }, + "node_modules/@anthropic-ai/claude-code-linux-arm64": { + "version": "2.1.319", + "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code-linux-arm64/-/claude-code-linux-arm64-2.1.319.tgz", + "integrity": "sha512-PlyxaZTAuU0VF3P/ERF4+deMRjT57cr90SHCrYms3HTebr3eItEWJozw6zq9cs88tc8XoF9ESAIghKXfq9HACg==", + "cpu": [ + "arm64" + ], + "license": "SEE LICENSE IN LICENSE.md", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@anthropic-ai/claude-code-linux-arm64-musl": { + "version": "2.1.319", + "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code-linux-arm64-musl/-/claude-code-linux-arm64-musl-2.1.319.tgz", + "integrity": "sha512-969quP2nXj7GRHzLSe9kov9c/f2p+ZuZrXkrvaenbLOX6zZJtyqZKRUyhDUjaVmSEEGFSxgCr/BtUMOXV8jaOw==", + "cpu": [ + "arm64" + ], + "license": "SEE LICENSE IN LICENSE.md", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@anthropic-ai/claude-code-linux-x64": { + "version": "2.1.319", + "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code-linux-x64/-/claude-code-linux-x64-2.1.319.tgz", + "integrity": "sha512-FO4Sd23BO1VCQPiJe5vG3bNnmV5+YiTau7o1lqK3Fr5VlE4TLdKiyYpwQRwEXO91kE2l12Ep2i7J19T8Md2oOQ==", + "cpu": [ + "x64" + ], + "license": "SEE LICENSE IN LICENSE.md", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@anthropic-ai/claude-code-linux-x64-musl": { + "version": "2.1.319", + "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code-linux-x64-musl/-/claude-code-linux-x64-musl-2.1.319.tgz", + "integrity": "sha512-LAj03VLWWZ+5T2c3dMxWZh5BhFzExwywIpT6y1oHnBj0Tx/ILIXYF1z6lcKSYsmiKChixPWzso35QnIfYLO8jg==", + "cpu": [ + "x64" + ], + "license": "SEE LICENSE IN LICENSE.md", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@anthropic-ai/claude-code-win32-arm64": { + "version": "2.1.319", + "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code-win32-arm64/-/claude-code-win32-arm64-2.1.319.tgz", + "integrity": "sha512-LJXWhy1rZGysmjwmC1/kapdaM55phYFPa3MGad033F01f76+q1lT4N8TCPC6wysHxrkLed/yucLGqMSTNY63cg==", + "cpu": [ + "arm64" + ], + "license": "SEE LICENSE IN LICENSE.md", + "optional": true, + "os": [ + "win32" + ] + }, + "node_modules/@anthropic-ai/claude-code-win32-x64": { + "version": "2.1.319", + "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code-win32-x64/-/claude-code-win32-x64-2.1.319.tgz", + "integrity": "sha512-wncPKSYL/zvjs84k7wZEj+IGQx/LjqQNhgnQhzDEibP0yAVBguAs4p8nBfFAEDbDdUc4Z2co+OaKZV1t02xINA==", + "cpu": [ + "x64" + ], + "license": "SEE LICENSE IN LICENSE.md", + "optional": true, + "os": [ + "win32" + ] + } + } +} diff --git a/examples/course-starter/.devcontainer/agent-cli/package.json b/examples/course-starter/.devcontainer/agent-cli/package.json new file mode 100644 index 0000000000..ea91177227 --- /dev/null +++ b/examples/course-starter/.devcontainer/agent-cli/package.json @@ -0,0 +1,8 @@ +{ + "name": "loom-devcontainer-agent-cli", + "private": true, + "version": "0.0.0", + "dependencies": { + "@anthropic-ai/claude-code": "2.1.319" + } +} diff --git a/examples/course-starter/.devcontainer/start-loom.sh b/examples/course-starter/.devcontainer/start-loom.sh index f8ee5213e8..181db00ff7 100755 --- a/examples/course-starter/.devcontainer/start-loom.sh +++ b/examples/course-starter/.devcontainer/start-loom.sh @@ -43,7 +43,9 @@ fi # is connected below, so the installer connects no agent. LOOM_CONNECT=none sh "$installer" -npm install --global --silent @anthropic-ai/claude-code +script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd) +npm ci --prefix "$script_dir/agent-cli" --no-fund --no-audit +npm install --global --offline --ignore-scripts --silent "$script_dir/agent-cli/node_modules/@anthropic-ai/claude-code" claude plugin marketplace list 2>/dev/null | grep -Eq '[[:space:]]loom$' \ || claude plugin marketplace add ClickHouse/loom claude plugin install loom@loom diff --git a/integrations/n8n/package.json b/integrations/n8n/package.json index 2ec1021916..8f3ea7108c 100644 --- a/integrations/n8n/package.json +++ b/integrations/n8n/package.json @@ -61,5 +61,5 @@ "access": "public", "provenance": true }, - "packageManager": "pnpm@10.32.1" + "packageManager": "pnpm@10.34.9" } diff --git a/scripts/code-toolchains/package-lock.json b/scripts/code-toolchains/package-lock.json new file mode 100644 index 0000000000..c7177103da --- /dev/null +++ b/scripts/code-toolchains/package-lock.json @@ -0,0 +1,1241 @@ +{ + "name": "loom-scripts-code-toolchains", + "version": "0.0.0", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "loom-scripts-code-toolchains", + "version": "0.0.0", + "dependencies": { + "@sourcegraph/scip-python": "0.6.6", + "@sourcegraph/scip-typescript": "0.4.0", + "bun": "1.4.2", + "pnpm": "12.15.0", + "yarn": "1.22.22" + } + }, + "node_modules/@cspotcode/source-map-support": { + "version": "0.8.1", + "resolved": "https://registry.npmjs.org/@cspotcode/source-map-support/-/source-map-support-0.8.1.tgz", + "integrity": "sha512-IchNf6dN4tHoMFIn/7OE8LWZ19Y6q/67Bmf6vnGREv8RSbBVb9LPJxEcnwrcwX6ixSvaiGoomAUvu4YSxXrVgw==", + "license": "MIT", + "dependencies": { + "@jridgewell/trace-mapping": "0.3.9" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/@iarna/toml": { + "version": "2.2.5", + "resolved": "https://registry.npmjs.org/@iarna/toml/-/toml-2.2.5.tgz", + "integrity": "sha512-trnsAYxU3xnS1gPHPyU961coFyLkh4gAD/0zQ5mymY4yOZ+CYvsPqUbOFSw0aDM4y0tV7tiFxL/1XfXPNC6IPg==", + "license": "ISC" + }, + "node_modules/@jridgewell/resolve-uri": { + "version": "3.1.3", + "resolved": "https://registry.npmjs.org/@jridgewell/resolve-uri/-/resolve-uri-3.1.3.tgz", + "integrity": "sha512-lhTtjtoEArWBjismtfS761S9Hlyn+nIZqOZVYoZ1Xn82PMNMVnk+jj/NhC4fAXGTs7ydONcJiR5vyQBTMDu27g==", + "license": "MIT", + "engines": { + "node": ">=6.0.0" + } + }, + "node_modules/@jridgewell/sourcemap-codec": { + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.6.0.tgz", + "integrity": "sha512-T7jf+5zgsZHwNJ4lvQ7/aezbyk0nNX+zJVWpmHA7VYsEx7a7qr5Rg5IbtJFqkgze5Y2sruq1RUY8Q837Od7iFw==", + "license": "MIT" + }, + "node_modules/@jridgewell/trace-mapping": { + "version": "0.3.9", + "resolved": "https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.9.tgz", + "integrity": "sha512-3Belt6tdc8bPgAtbcmdtNJlirVoTmEb5e2gC94PnkwEW9jI6CAHUeoG85tjWP5WquqfavoMtMwiG4P926ZKKuQ==", + "license": "MIT", + "dependencies": { + "@jridgewell/resolve-uri": "^3.0.3", + "@jridgewell/sourcemap-codec": "^1.4.10" + } + }, + "node_modules/@oven/bun-darwin-aarch64": { + "version": "1.4.2", + "resolved": "https://registry.npmjs.org/@oven/bun-darwin-aarch64/-/bun-darwin-aarch64-1.4.2.tgz", + "integrity": "sha512-MXdZkP1featqxZ+/VTXWG1BVjM4OGBehVY2Q88EeUj/7L0UMeCGItmyPYTN+wxvlGJ6F66JEtzsw+GvQWewnag==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ] + }, + "node_modules/@oven/bun-darwin-x64": { + "version": "1.4.2", + "resolved": "https://registry.npmjs.org/@oven/bun-darwin-x64/-/bun-darwin-x64-1.4.2.tgz", + "integrity": "sha512-gZTxZuLjkUhAWjTETu3tw0WhsEdNkJ64daj60ybhPf835a2yollV3yTkK9JozvzKPx4TRFzLSl8C+U525pxVbw==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ] + }, + "node_modules/@oven/bun-freebsd-aarch64": { + "version": "1.4.2", + "resolved": "https://registry.npmjs.org/@oven/bun-freebsd-aarch64/-/bun-freebsd-aarch64-1.4.2.tgz", + "integrity": "sha512-SMNItMw1Z8QeeQVKnw8jA7xQNkeXdP+OPgin4Wi/QTx/B8RHHLnuZfqmFy7NtVeT2NF0kKYppW4WWd2CCYZjhQ==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ] + }, + "node_modules/@oven/bun-freebsd-x64": { + "version": "1.4.2", + "resolved": "https://registry.npmjs.org/@oven/bun-freebsd-x64/-/bun-freebsd-x64-1.4.2.tgz", + "integrity": "sha512-THbPKXhO54N0DpFRKZNDZpQ7dpbX0bWASuARckAUS9wRtFIHsiY+uULXJvxJGo2YD1YewvXQ4G8Fj7XT5oBCiw==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ] + }, + "node_modules/@oven/bun-linux-aarch64": { + "version": "1.4.2", + "resolved": "https://registry.npmjs.org/@oven/bun-linux-aarch64/-/bun-linux-aarch64-1.4.2.tgz", + "integrity": "sha512-3BBP9ovJ2RGHFH6Ae1CAtxNtG1+YY6GD6rmYbsUosoAk9+OEl6zeDQ/k4fBkc6dYOJCtWnx8hUxzNzQATSmvYQ==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@oven/bun-linux-aarch64-android": { + "version": "1.4.2", + "resolved": "https://registry.npmjs.org/@oven/bun-linux-aarch64-android/-/bun-linux-aarch64-android-1.4.2.tgz", + "integrity": "sha512-3mZKO2rhsNgbAUtAHC1UKUlF2zTxFraDZT/Elv8wzyH0fJL9h+Iv3TgB9lO63w89PRn3eFe+NRA1bhVgikKNPQ==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "android" + ] + }, + "node_modules/@oven/bun-linux-aarch64-musl": { + "version": "1.4.2", + "resolved": "https://registry.npmjs.org/@oven/bun-linux-aarch64-musl/-/bun-linux-aarch64-musl-1.4.2.tgz", + "integrity": "sha512-+Sm6y+lSiSFBOtXmnekp5Q6n1tUKlyv71FCPWBc61Cgb14T5eBs8SN/nh4MUCOKzONkI3O+as3MGUgikS4aCBQ==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@oven/bun-linux-x64": { + "version": "1.4.2", + "resolved": "https://registry.npmjs.org/@oven/bun-linux-x64/-/bun-linux-x64-1.4.2.tgz", + "integrity": "sha512-9/E/UXOTpSo3YsV5g+FhtTd/qTpiWoKuxS12cqtuYA1ssu9fRAoPQnipFgGyck3tWO63iUdxBiygq+kELFawng==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@oven/bun-linux-x64-android": { + "version": "1.4.2", + "resolved": "https://registry.npmjs.org/@oven/bun-linux-x64-android/-/bun-linux-x64-android-1.4.2.tgz", + "integrity": "sha512-6HC5tzcC79113n2IHCTJMWv+HsQImv4ZFEK2XpYLxY6HbT8tM4cUM2Zv1bHZBQsS3jv/zYBamDJ1UX7If0d5tw==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "android" + ] + }, + "node_modules/@oven/bun-linux-x64-musl": { + "version": "1.4.2", + "resolved": "https://registry.npmjs.org/@oven/bun-linux-x64-musl/-/bun-linux-x64-musl-1.4.2.tgz", + "integrity": "sha512-vVTKUg1bnPhRP/Hp73jIVoFh2vPFNYEqYX0ERKfZBOQEEHitNAeukZzzuUDZS0SoDCIpuWUGSpd/CDMbjdR+Uw==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@oven/bun-windows-aarch64": { + "version": "1.4.2", + "resolved": "https://registry.npmjs.org/@oven/bun-windows-aarch64/-/bun-windows-aarch64-1.4.2.tgz", + "integrity": "sha512-8EJ1ST7339WJE3poPW5nBgVW/lWf9HBz4W27ZUNhburKmcBLOByPyE6DP9fHD8FQGm5c+ilUN2hX1mrW0jxq9Q==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "win32" + ] + }, + "node_modules/@oven/bun-windows-x64": { + "version": "1.4.2", + "resolved": "https://registry.npmjs.org/@oven/bun-windows-x64/-/bun-windows-x64-1.4.2.tgz", + "integrity": "sha512-+bN6OuVld/9diT/RLSXSW7JE6CvNE3gL9XsAEjULi1nUsXd6DNO6GuA9jNdNb3r8PdJFnYHr5aypNV1Oj3Rd9g==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "win32" + ] + }, + "node_modules/@pnpm/exe.android-arm64": { + "version": "12.15.0", + "resolved": "https://registry.npmjs.org/@pnpm/exe.android-arm64/-/exe.android-arm64-12.15.0.tgz", + "integrity": "sha512-eVCqmscY70LGvgRzu3mi8IBWBFGix+a6mNZoWmXxESsBdeiKEF9xQSuaeel10yn+zI7TXy2jlI63vFLzETk+aQ==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "android" + ] + }, + "node_modules/@pnpm/exe.android-x64": { + "version": "12.15.0", + "resolved": "https://registry.npmjs.org/@pnpm/exe.android-x64/-/exe.android-x64-12.15.0.tgz", + "integrity": "sha512-Gx/WbkFcdUFUg8g8AShezcS9EiQxfYvdAm2hfKLO8sfJmJvKOCt5fzlgHWDzmGhoclibgW+tUGZ/KF4F4wOTCA==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "android" + ] + }, + "node_modules/@pnpm/exe.darwin-arm64": { + "version": "12.15.0", + "resolved": "https://registry.npmjs.org/@pnpm/exe.darwin-arm64/-/exe.darwin-arm64-12.15.0.tgz", + "integrity": "sha512-N0ZykiDWCvqSBJvt71j7cSoBR993FqvYZFtmpCtqvW3pguiI+NAgraLPA5OTwu5mV+/d8hYpVcPktJA3xFDLtA==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ] + }, + "node_modules/@pnpm/exe.darwin-x64": { + "version": "12.15.0", + "resolved": "https://registry.npmjs.org/@pnpm/exe.darwin-x64/-/exe.darwin-x64-12.15.0.tgz", + "integrity": "sha512-7Ntr2HlBUxzwWOg7NwDxCbRW/3vXuqKO+hcXm+w3SBi9rrHY53li1wLqWVT7Gjxd+lVEHM1QJZo6WJEGFU8C6A==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ] + }, + "node_modules/@pnpm/exe.freebsd-x64": { + "version": "12.15.0", + "resolved": "https://registry.npmjs.org/@pnpm/exe.freebsd-x64/-/exe.freebsd-x64-12.15.0.tgz", + "integrity": "sha512-btOiyL7fL7W4uQGH0aqFai2TNC3IoKcZ7gNHBVbEFZt2dWrnrD0SufL3iGs3fLlmb4OtuU35uf4Zpr9V9Jh9mA==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ] + }, + "node_modules/@pnpm/exe.linux-arm64": { + "version": "12.15.0", + "resolved": "https://registry.npmjs.org/@pnpm/exe.linux-arm64/-/exe.linux-arm64-12.15.0.tgz", + "integrity": "sha512-qML/8aCXslh8td/w4U+HJNqUcZ2+m6EfTbWScIzZRmyPsRFN+xB4LP1U/hymxc1iSJiKtG56HJx2fvUErWFIGw==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@pnpm/exe.linux-arm64-musl": { + "version": "12.15.0", + "resolved": "https://registry.npmjs.org/@pnpm/exe.linux-arm64-musl/-/exe.linux-arm64-musl-12.15.0.tgz", + "integrity": "sha512-pNC38k+O+90FOjbPNSnw0E7apq1PKTmz3fFe1amn+lys/U5kL++uzir8bRiho8ONcyA3d9EU7wdqcY0DKkj+JA==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@pnpm/exe.linux-ppc64": { + "version": "12.15.0", + "resolved": "https://registry.npmjs.org/@pnpm/exe.linux-ppc64/-/exe.linux-ppc64-12.15.0.tgz", + "integrity": "sha512-tjRDUUl7RCJ6T/6eoNPxOqkwU4Mzi5RtTXmSAxujyz37OTwwsMU7Ps087Zk4gHcUvRSeyF40ZFsew3vtE+nmUA==", + "cpu": [ + "ppc64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@pnpm/exe.linux-riscv64": { + "version": "12.15.0", + "resolved": "https://registry.npmjs.org/@pnpm/exe.linux-riscv64/-/exe.linux-riscv64-12.15.0.tgz", + "integrity": "sha512-bF1uBWEfbwaeryz6lIiaJ8AWD082otZfvzGX5l+6LZRpRwUEpJHUsJrORaYP5/cNMv5ZR2p6TvvcJcQzwtDzmw==", + "cpu": [ + "riscv64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@pnpm/exe.linux-s390x": { + "version": "12.15.0", + "resolved": "https://registry.npmjs.org/@pnpm/exe.linux-s390x/-/exe.linux-s390x-12.15.0.tgz", + "integrity": "sha512-zKMhIzsexYMToeLmqV5jPsvV/f9vwsJb2kUH2NFYzalbxImeBrlA4kL7GwF8gD4pagV6jYYcJb8RjbZIdjHptg==", + "cpu": [ + "s390x" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@pnpm/exe.linux-x64": { + "version": "12.15.0", + "resolved": "https://registry.npmjs.org/@pnpm/exe.linux-x64/-/exe.linux-x64-12.15.0.tgz", + "integrity": "sha512-yc+QlZR+9+nr29J4fRzhMoapgxTBDndq/+peyoq1XUufnQFnfbXUMFudDIKzHi545linGqmOmXfn0NoufNgcOg==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@pnpm/exe.linux-x64-musl": { + "version": "12.15.0", + "resolved": "https://registry.npmjs.org/@pnpm/exe.linux-x64-musl/-/exe.linux-x64-musl-12.15.0.tgz", + "integrity": "sha512-A9J0Jg0Rdx+qQU4qXtwyST5tto9IOu1zi4fDk35nbc6DWahggbcKtFvZPKFwL2qgUXGXOX//hXv6z/sp6emO8A==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@pnpm/exe.win32-arm64": { + "version": "12.15.0", + "resolved": "https://registry.npmjs.org/@pnpm/exe.win32-arm64/-/exe.win32-arm64-12.15.0.tgz", + "integrity": "sha512-fPXZxuY1VclkOga9bc53qNCXcegfeoBR8+Ue+AospDwKzuGGSHll0oDxkLfkmpjyRqpe7bH5DyQPYp/xSMaIVA==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "win32" + ] + }, + "node_modules/@pnpm/exe.win32-x64": { + "version": "12.15.0", + "resolved": "https://registry.npmjs.org/@pnpm/exe.win32-x64/-/exe.win32-x64-12.15.0.tgz", + "integrity": "sha512-nrd+Tp1We1DGj4DGG5Bea9lZNh9y1PjlLBdEwdInS4D0h0UIDtM7JaGGGDJhNzIwcHASyihWI7HLV+dtG+fhYg==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "win32" + ] + }, + "node_modules/@sourcegraph/scip-python": { + "version": "0.6.6", + "resolved": "https://registry.npmjs.org/@sourcegraph/scip-python/-/scip-python-0.6.6.tgz", + "integrity": "sha512-qoKL1Rggg0o5newAFbCFAKlS0AjWxG5MA+mC28BtgxOv0DhO4zdL8u7151FxEppDpXMVvm7+yXSjXotoVH9cMQ==", + "license": "MIT", + "dependencies": { + "@iarna/toml": "^2.2.5", + "command-exists": "^1.2.9", + "commander": "^9.2.0", + "diff": "^5.0.0", + "glob": "^7.2.0", + "google-protobuf": "^3.19.3", + "ts-node": "^10.5.0", + "vscode-languageserver": "^7.0.0" + }, + "bin": { + "scip-python": "index.js" + } + }, + "node_modules/@sourcegraph/scip-typescript": { + "version": "0.4.0", + "resolved": "https://registry.npmjs.org/@sourcegraph/scip-typescript/-/scip-typescript-0.4.0.tgz", + "integrity": "sha512-k+AtsrqmS41Sd5qjkZlHcmvoSQIvBOonRj4jpgp0KNFM6aqvMGpdSuPUqrUcg8ENTKjUbfaUVszgQwq3bCOvwA==", + "license": "Apache-2.0", + "dependencies": { + "commander": "^12.1.0", + "google-protobuf": "^3.21.4", + "progress": "^2.0.3", + "typescript": "^5.6.2" + }, + "bin": { + "scip-typescript": "dist/src/main.js" + } + }, + "node_modules/@sourcegraph/scip-typescript/node_modules/commander": { + "version": "12.1.0", + "resolved": "https://registry.npmjs.org/commander/-/commander-12.1.0.tgz", + "integrity": "sha512-Vw8qHK3bZM9y/P10u3Vib8o/DdkvA2OtPtZvD871QKjy74Wj1WSKFILMPRPSdUSx5RFK1arlJzEtA4PkFgnbuA==", + "license": "MIT", + "engines": { + "node": ">=18" + } + }, + "node_modules/@sourcegraph/scip-typescript/node_modules/typescript": { + "version": "5.9.3", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz", + "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==", + "license": "Apache-2.0", + "bin": { + "tsc": "bin/tsc", + "tsserver": "bin/tsserver" + }, + "engines": { + "node": ">=14.17" + } + }, + "node_modules/@tsconfig/node10": { + "version": "1.0.14", + "resolved": "https://registry.npmjs.org/@tsconfig/node10/-/node10-1.0.14.tgz", + "integrity": "sha512-UzoEnKAHteIy/qT3dM0eyyviwfJzEDnrLKALKCvu0ToklMLgiDW5waEu/0Pl+6w4nBxGIaUskiFg7NzvQpPs0g==", + "license": "MIT" + }, + "node_modules/@tsconfig/node12": { + "version": "1.0.11", + "resolved": "https://registry.npmjs.org/@tsconfig/node12/-/node12-1.0.11.tgz", + "integrity": "sha512-cqefuRsh12pWyGsIoBKJA9luFu3mRxCA+ORZvA4ktLSzIuCUtWVxGIuXigEwO5/ywWFMZ2QEGKWvkZG1zDMTag==", + "license": "MIT" + }, + "node_modules/@tsconfig/node14": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@tsconfig/node14/-/node14-1.0.3.tgz", + "integrity": "sha512-ysT8mhdixWK6Hw3i1V2AeRqZ5WfXg1G43mqoYlM2nc6388Fq5jcXyr5mRsqViLx/GJYdoL0bfXD8nmF+Zn/Iow==", + "license": "MIT" + }, + "node_modules/@tsconfig/node16": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/@tsconfig/node16/-/node16-1.0.4.tgz", + "integrity": "sha512-vxhUy4J8lyeyinH7Azl1pdd43GJhZH/tP2weN8TntQblOY+A0XbT8DJk1/oCPuOOyg/Ja757rG0CgHcWC8OfMA==", + "license": "MIT" + }, + "node_modules/@types/node": { + "version": "26.6.6", + "resolved": "https://registry.npmjs.org/@types/node/-/node-26.6.6.tgz", + "integrity": "sha512-MzQj+8Kx3XI40OmUAE6Qoh58ZMNstNNMwn2nfd3qWsfe7nDNSqJNzes4njhz6AHwrSHOffSLwXU6yb474Q4aog==", + "license": "MIT", + "peer": true, + "dependencies": { + "undici-types": "~8.9.0" + } + }, + "node_modules/@typescript/typescript-aix-ppc64": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/@typescript/typescript-aix-ppc64/-/typescript-aix-ppc64-7.0.2.tgz", + "integrity": "sha512-MTKKkWB7p/0E9xi1d1tHtZ5PiLkGEMIq88pK2CubZjOsLtYTLqhgIgi6zepFa+9GHZ6h05NMCkQxGKiPXMxXtQ==", + "cpu": [ + "ppc64" + ], + "license": "Apache-2.0", + "optional": true, + "os": [ + "aix" + ], + "peer": true, + "engines": { + "node": ">=16.20.0" + } + }, + "node_modules/@typescript/typescript-darwin-arm64": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/@typescript/typescript-darwin-arm64/-/typescript-darwin-arm64-7.0.2.tgz", + "integrity": "sha512-gowzar9MwS/aRWp6f3a4KUqzRjAZjOsmGNCM6LcTgXum+dBfgsBVMN+AgvOCCbguXyick6LJhpBszxMebJ8syA==", + "cpu": [ + "arm64" + ], + "license": "Apache-2.0", + "optional": true, + "os": [ + "darwin" + ], + "peer": true, + "engines": { + "node": ">=16.20.0" + } + }, + "node_modules/@typescript/typescript-darwin-x64": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/@typescript/typescript-darwin-x64/-/typescript-darwin-x64-7.0.2.tgz", + "integrity": "sha512-SZ9xZInqApNlNGc9s0W1VSsktYSOe9cFqNOIqmN1Gs8SmkjKZYFt017G4VwPxASInODuAdbTW7sXiFUf893RgA==", + "cpu": [ + "x64" + ], + "license": "Apache-2.0", + "optional": true, + "os": [ + "darwin" + ], + "peer": true, + "engines": { + "node": ">=16.20.0" + } + }, + "node_modules/@typescript/typescript-freebsd-arm64": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/@typescript/typescript-freebsd-arm64/-/typescript-freebsd-arm64-7.0.2.tgz", + "integrity": "sha512-W5NH4y/J0plIIS5b2xvTEkU7JFxyqdMAOgf+Ilhl0vHQXKO5dZoxd+C/jEtq56c4F3wk71RB4BMRQ2XdI+bwYQ==", + "cpu": [ + "arm64" + ], + "license": "Apache-2.0", + "optional": true, + "os": [ + "freebsd" + ], + "peer": true, + "engines": { + "node": ">=16.20.0" + } + }, + "node_modules/@typescript/typescript-freebsd-x64": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/@typescript/typescript-freebsd-x64/-/typescript-freebsd-x64-7.0.2.tgz", + "integrity": "sha512-UMGDx5sTpzNw3WiPebH7l90IWfJggEd+egHt/q6p7/Cm3zqoV7VxkGXt+3DxPIw8CcmvAB0j3sVVfbhX+M4Tpw==", + "cpu": [ + "x64" + ], + "license": "Apache-2.0", + "optional": true, + "os": [ + "freebsd" + ], + "peer": true, + "engines": { + "node": ">=16.20.0" + } + }, + "node_modules/@typescript/typescript-linux-arm": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/@typescript/typescript-linux-arm/-/typescript-linux-arm-7.0.2.tgz", + "integrity": "sha512-gffT3xPz9sR7j/YJExkyPntrI0P2EP9XbOyWzth2/Gs0RstK+90RBcO0ncXoXy/beYll1SXw846Nf2zdnEz0QQ==", + "cpu": [ + "arm" + ], + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "peer": true, + "engines": { + "node": ">=16.20.0" + } + }, + "node_modules/@typescript/typescript-linux-arm64": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/@typescript/typescript-linux-arm64/-/typescript-linux-arm64-7.0.2.tgz", + "integrity": "sha512-Qh4eU4/y3yDjnfjjyPYihMj5/ODIlmt+Bzu17OI+fiSRDW57QmU5SiN63exPRNJPKUzcc1INa1NXdrJ+MqHjUQ==", + "cpu": [ + "arm64" + ], + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "peer": true, + "engines": { + "node": ">=16.20.0" + } + }, + "node_modules/@typescript/typescript-linux-loong64": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/@typescript/typescript-linux-loong64/-/typescript-linux-loong64-7.0.2.tgz", + "integrity": "sha512-uEHck9i8hoAzXPiYRib1O7miOnz23SxIeVl6F4LXox+qov1K35jHcEW6VHKvZI+pyvl7fZEP4MCU5LYvIq1GuQ==", + "cpu": [ + "loong64" + ], + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "peer": true, + "engines": { + "node": ">=16.20.0" + } + }, + "node_modules/@typescript/typescript-linux-mips64el": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/@typescript/typescript-linux-mips64el/-/typescript-linux-mips64el-7.0.2.tgz", + "integrity": "sha512-R4KvAMnE43W5Qeqb0Ly56O3mWMWIAgsMyz36DCaycd5nbg/9kzm0liw3JocfRqyJY0KPmzFjbswozXyW0DnIYA==", + "cpu": [ + "mips64el" + ], + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "peer": true, + "engines": { + "node": ">=16.20.0" + } + }, + "node_modules/@typescript/typescript-linux-ppc64": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/@typescript/typescript-linux-ppc64/-/typescript-linux-ppc64-7.0.2.tgz", + "integrity": "sha512-DORx5b3sd/4S7eayxm4FQv+A7CrkUIGRaHiwI8oiHTAI1fAPWhF4J0vAlkC8biAlHSVVwxMQ3tjZ2/DVbnQiiA==", + "cpu": [ + "ppc64" + ], + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "peer": true, + "engines": { + "node": ">=16.20.0" + } + }, + "node_modules/@typescript/typescript-linux-riscv64": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/@typescript/typescript-linux-riscv64/-/typescript-linux-riscv64-7.0.2.tgz", + "integrity": "sha512-wf0jqEDOjrPRnKwYRyyJDRo11KMbvMFrU+q4zqKyChODBzvlkbhNQfKvLxQCcwTpdDaXSHZTVuh0JoCrKCUMHQ==", + "cpu": [ + "riscv64" + ], + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "peer": true, + "engines": { + "node": ">=16.20.0" + } + }, + "node_modules/@typescript/typescript-linux-s390x": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/@typescript/typescript-linux-s390x/-/typescript-linux-s390x-7.0.2.tgz", + "integrity": "sha512-IkwJc3L7yhytWd/ewjyxNDfOmswCm9GWMJT/ue/dU4aZNbwZeYAetq42VyLmsmSjvoX7z74X6ZaYCtzAr0EuGw==", + "cpu": [ + "s390x" + ], + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "peer": true, + "engines": { + "node": ">=16.20.0" + } + }, + "node_modules/@typescript/typescript-linux-x64": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/@typescript/typescript-linux-x64/-/typescript-linux-x64-7.0.2.tgz", + "integrity": "sha512-EYdf2cNg7rgCWJnxCdJ+F3V39O8ihb37eHAu1LK8oAFizgTQbPOK7zHHXbPt8rX24COqODXeI3sIf0fCXG7H/A==", + "cpu": [ + "x64" + ], + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "peer": true, + "engines": { + "node": ">=16.20.0" + } + }, + "node_modules/@typescript/typescript-netbsd-arm64": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/@typescript/typescript-netbsd-arm64/-/typescript-netbsd-arm64-7.0.2.tgz", + "integrity": "sha512-+polYF4MF04aPpO5FTkHran9yUQDSXqy5GiSDKpsll5jy3l3+g9QLhpf39T+ePtefhXLOGrLl0QIjkQP6VnelA==", + "cpu": [ + "arm64" + ], + "license": "Apache-2.0", + "optional": true, + "os": [ + "netbsd" + ], + "peer": true, + "engines": { + "node": ">=16.20.0" + } + }, + "node_modules/@typescript/typescript-netbsd-x64": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/@typescript/typescript-netbsd-x64/-/typescript-netbsd-x64-7.0.2.tgz", + "integrity": "sha512-8YIT0EHM/3dq10ZOVF/A7pc/YSMtbcecct4rWtexrnSCHOPcpC2KTLXfTCR6vDpnSiY12heNb1GiN/wu+T/FyA==", + "cpu": [ + "x64" + ], + "license": "Apache-2.0", + "optional": true, + "os": [ + "netbsd" + ], + "peer": true, + "engines": { + "node": ">=16.20.0" + } + }, + "node_modules/@typescript/typescript-openbsd-arm64": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/@typescript/typescript-openbsd-arm64/-/typescript-openbsd-arm64-7.0.2.tgz", + "integrity": "sha512-APT8+ClYnuYm1u9+kgGXoMj2VzWzcymwh2gNSQVySHfkRDGOTVkoWLjCmOQSaO+PoqQ57B0flRp9SA+7GnnkzQ==", + "cpu": [ + "arm64" + ], + "license": "Apache-2.0", + "optional": true, + "os": [ + "openbsd" + ], + "peer": true, + "engines": { + "node": ">=16.20.0" + } + }, + "node_modules/@typescript/typescript-openbsd-x64": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/@typescript/typescript-openbsd-x64/-/typescript-openbsd-x64-7.0.2.tgz", + "integrity": "sha512-yX7s+Q0Dln0Dt9tEzZsAjXXR/+ytBM7AlglaqyeMPxQszJ1JhlJdZ6jLA+IzldHtflX81em7lDao1xXu+aRRkg==", + "cpu": [ + "x64" + ], + "license": "Apache-2.0", + "optional": true, + "os": [ + "openbsd" + ], + "peer": true, + "engines": { + "node": ">=16.20.0" + } + }, + "node_modules/@typescript/typescript-sunos-x64": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/@typescript/typescript-sunos-x64/-/typescript-sunos-x64-7.0.2.tgz", + "integrity": "sha512-dLJDGaLZ1D4HPQn62u1n8mBDkJREwMsAkCdkwd4Ieqw+x3TUyTsqY0YiBCtE6H6OzzgGk3iuZ3vFWRS+E8/d1g==", + "cpu": [ + "x64" + ], + "license": "Apache-2.0", + "optional": true, + "os": [ + "sunos" + ], + "peer": true, + "engines": { + "node": ">=16.20.0" + } + }, + "node_modules/@typescript/typescript-win32-arm64": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/@typescript/typescript-win32-arm64/-/typescript-win32-arm64-7.0.2.tgz", + "integrity": "sha512-Gyl1Vy6OsWesLzmq+EP0Fb7b4Nid5232AvcA2SFcdYreldpNtYFFofPjnt62y9hQy7VTaZp65ICJjuAQRaVcIQ==", + "cpu": [ + "arm64" + ], + "license": "Apache-2.0", + "optional": true, + "os": [ + "win32" + ], + "peer": true, + "engines": { + "node": ">=16.20.0" + } + }, + "node_modules/@typescript/typescript-win32-x64": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/@typescript/typescript-win32-x64/-/typescript-win32-x64-7.0.2.tgz", + "integrity": "sha512-0BQ3HkAHHlKLSp1qRvf3SUhGpGsDuhB/jgFw75guyqbxJqEaS0Cw/VFO8i2nHglJUzQCRtMMR/IBAKE3ETMC4g==", + "cpu": [ + "x64" + ], + "license": "Apache-2.0", + "optional": true, + "os": [ + "win32" + ], + "peer": true, + "engines": { + "node": ">=16.20.0" + } + }, + "node_modules/acorn": { + "version": "8.19.0", + "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.19.0.tgz", + "integrity": "sha512-oJlA3XiRm7Cyk6qFD2Jn8ak9B7jSy0qy00ADO3+8dpT0LSjFihQYv4C02LFCSYJV3Q37xYwwRy5m+IpIiUzqWw==", + "license": "MIT", + "bin": { + "acorn": "bin/acorn" + }, + "engines": { + "node": ">=0.4.0" + } + }, + "node_modules/acorn-walk": { + "version": "8.3.5", + "resolved": "https://registry.npmjs.org/acorn-walk/-/acorn-walk-8.3.5.tgz", + "integrity": "sha512-HEHNfbars9v4pgpW6SO1KSPkfoS0xVOM/9UzkJltjlsHZmJasxg8aXkuZa7SMf8vKGIBhpUsPluQSqhJFCqebw==", + "license": "MIT", + "dependencies": { + "acorn": "^8.11.0" + }, + "engines": { + "node": ">=0.4.0" + } + }, + "node_modules/arg": { + "version": "4.1.3", + "resolved": "https://registry.npmjs.org/arg/-/arg-4.1.3.tgz", + "integrity": "sha512-58S9QDqG0Xx27YwPSt9fJxivjYl432YCwfDMfZ+71RAqUrZef7LrKQZ3LHLOwCS4FLNBplP533Zx895SeOCHvA==", + "license": "MIT" + }, + "node_modules/balanced-match": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz", + "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==", + "license": "MIT" + }, + "node_modules/brace-expansion": { + "version": "1.1.22", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.22.tgz", + "integrity": "sha512-CKLDTuSsN0+r1ThM0WkzzBI7dnPI6xEGfa/JnVYIK9JNBA1N1NyPwXVHor//NKD/y3sDxp764sZdLhFK7pH8XQ==", + "license": "MIT", + "dependencies": { + "balanced-match": "^1.0.0", + "concat-map": "0.0.1" + } + }, + "node_modules/bun": { + "version": "1.4.2", + "resolved": "https://registry.npmjs.org/bun/-/bun-1.4.2.tgz", + "integrity": "sha512-TrSXo6HJfIEaczpb3kjX82I2pL47vK1QUNmHRCUdz9IzaOwa9lzOXSWwu2l18YHE3sNfGRapVLd4nNm+22vVVA==", + "cpu": [ + "arm64", + "x64" + ], + "hasInstallScript": true, + "license": "MIT", + "os": [ + "darwin", + "linux", + "android", + "freebsd", + "win32" + ], + "bin": { + "bun": "bin/bun.exe", + "bunx": "bin/bunx.exe" + }, + "optionalDependencies": { + "@oven/bun-darwin-aarch64": "1.4.2", + "@oven/bun-darwin-x64": "1.4.2", + "@oven/bun-freebsd-aarch64": "1.4.2", + "@oven/bun-freebsd-x64": "1.4.2", + "@oven/bun-linux-aarch64": "1.4.2", + "@oven/bun-linux-aarch64-android": "1.4.2", + "@oven/bun-linux-aarch64-musl": "1.4.2", + "@oven/bun-linux-x64": "1.4.2", + "@oven/bun-linux-x64-android": "1.4.2", + "@oven/bun-linux-x64-musl": "1.4.2", + "@oven/bun-windows-aarch64": "1.4.2", + "@oven/bun-windows-x64": "1.4.2" + } + }, + "node_modules/command-exists": { + "version": "1.2.9", + "resolved": "https://registry.npmjs.org/command-exists/-/command-exists-1.2.9.tgz", + "integrity": "sha512-LTQ/SGc+s0Xc0Fu5WaKnR0YiygZkm9eKFvyS+fRsU7/ZWFF8ykFM6Pc9aCVf1+xasOOZpO3BAVgVrKvsqKHV7w==", + "license": "MIT" + }, + "node_modules/commander": { + "version": "9.5.0", + "resolved": "https://registry.npmjs.org/commander/-/commander-9.5.0.tgz", + "integrity": "sha512-KRs7WVDKg86PWiuAqhDrAQnTXZKraVcCc6vFdL14qrZ/DcWwuRo7VoiYXalXO7S5GKpqYiVEwCbgFDfxNHKJBQ==", + "license": "MIT", + "engines": { + "node": "^12.20.0 || >=14" + } + }, + "node_modules/concat-map": { + "version": "0.0.1", + "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz", + "integrity": "sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg==", + "license": "MIT" + }, + "node_modules/create-require": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/create-require/-/create-require-1.1.1.tgz", + "integrity": "sha512-dcKFX3jn0MpIaXjisoRvexIJVEKzaq7z2rZKxf+MSr9TkdmHmsU4m2lcLojrj/FHl8mk5VxMmYA+ftRkP/3oKQ==", + "license": "MIT" + }, + "node_modules/diff": { + "version": "5.2.2", + "resolved": "https://registry.npmjs.org/diff/-/diff-5.2.2.tgz", + "integrity": "sha512-vtcDfH3TOjP8UekytvnHH1o1P4FcUdt4eQ1Y+Abap1tk/OB2MWQvcwS2ClCd1zuIhc3JKOx6p3kod8Vfys3E+A==", + "license": "BSD-3-Clause", + "engines": { + "node": ">=0.3.1" + } + }, + "node_modules/fs.realpath": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/fs.realpath/-/fs.realpath-1.0.0.tgz", + "integrity": "sha512-OO0pH2lK6a0hZnAdau5ItzHPI6pUlvI7jMVnxUQRtw4owF2wk8lOSabtGDCTP4Ggrg2MbGnWO9X8K1t4+fGMDw==", + "license": "ISC" + }, + "node_modules/glob": { + "version": "7.2.3", + "resolved": "https://registry.npmjs.org/glob/-/glob-7.2.3.tgz", + "integrity": "sha512-nFR0zLpU2YCaRxwoCJvL6UvCH2JFyFVIvwTLsIf21AuHlMskA1hhTdk+LlYJtOlYt9v6dvszD2BGRqBL+iQK9Q==", + "deprecated": "Old versions of glob are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me", + "license": "ISC", + "dependencies": { + "fs.realpath": "^1.0.0", + "inflight": "^1.0.4", + "inherits": "2", + "minimatch": "^3.1.1", + "once": "^1.3.0", + "path-is-absolute": "^1.0.0" + }, + "engines": { + "node": "*" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/google-protobuf": { + "version": "3.21.4", + "resolved": "https://registry.npmjs.org/google-protobuf/-/google-protobuf-3.21.4.tgz", + "integrity": "sha512-MnG7N936zcKTco4Jd2PX2U96Kf9PxygAPKBug+74LHzmHXmceN16MmRcdgZv+DGef/S9YvQAfRsNCn4cjf9yyQ==", + "license": "(BSD-3-Clause AND Apache-2.0)" + }, + "node_modules/inflight": { + "version": "1.0.6", + "resolved": "https://registry.npmjs.org/inflight/-/inflight-1.0.6.tgz", + "integrity": "sha512-k92I/b08q4wvFscXCLvqfsHCrjrF7yiXsQuIVvVE7N82W3+aqpzuUdBbfhWcy/FZR3/4IgflMgKLOsvPDrGCJA==", + "deprecated": "This module is not supported, and leaks memory. Do not use it. Check out lru-cache if you want a good and tested way to coalesce async requests by a key value, which is much more comprehensive and powerful.", + "license": "ISC", + "dependencies": { + "once": "^1.3.0", + "wrappy": "1" + } + }, + "node_modules/inherits": { + "version": "2.0.4", + "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz", + "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==", + "license": "ISC" + }, + "node_modules/make-error": { + "version": "1.3.6", + "resolved": "https://registry.npmjs.org/make-error/-/make-error-1.3.6.tgz", + "integrity": "sha512-s8UhlNe7vPKomQhC1qFelMokr/Sc3AgNbso3n74mVPA5LTZwkB9NlXf4XPamLxJE8h0gh73rM94xvwRT2CVInw==", + "license": "ISC" + }, + "node_modules/minimatch": { + "version": "3.1.5", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.5.tgz", + "integrity": "sha512-VgjWUsnnT6n+NUk6eZq77zeFdpW2LWDzP6zFGrCbHXiYNul5Dzqk2HHQ5uFH2DNW5Xbp8+jVzaeNt94ssEEl4w==", + "license": "ISC", + "dependencies": { + "brace-expansion": "^1.1.7" + }, + "engines": { + "node": "*" + } + }, + "node_modules/once": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz", + "integrity": "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==", + "license": "ISC", + "dependencies": { + "wrappy": "1" + } + }, + "node_modules/path-is-absolute": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/path-is-absolute/-/path-is-absolute-1.0.1.tgz", + "integrity": "sha512-AVbw3UJ2e9bq64vSaS9Am0fje1Pa8pbGqTTsmXfaIiMpnr5DlDhfJOuLj9Sf95ZPVDAUerDfEk88MPmPe7UCQg==", + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/pnpm": { + "version": "12.15.0", + "resolved": "https://registry.npmjs.org/pnpm/-/pnpm-12.15.0.tgz", + "integrity": "sha512-s5UdbW/0qfE9x89WzSjSuOs328ycaOUuHhGRhz6p+CoBcoerULqtxczElPA2xnwOR+sTYIwvo29HcRth6hKOYQ==", + "hasInstallScript": true, + "license": "MIT", + "bin": { + "pn": "pn", + "pnpm": "pnpm", + "pnpx": "pnpx", + "pnx": "pnx" + }, + "engines": { + "node": ">=18" + }, + "optionalDependencies": { + "@pnpm/exe.android-arm64": "12.15.0", + "@pnpm/exe.android-x64": "12.15.0", + "@pnpm/exe.darwin-arm64": "12.15.0", + "@pnpm/exe.darwin-x64": "12.15.0", + "@pnpm/exe.freebsd-x64": "12.15.0", + "@pnpm/exe.linux-arm64": "12.15.0", + "@pnpm/exe.linux-arm64-musl": "12.15.0", + "@pnpm/exe.linux-ppc64": "12.15.0", + "@pnpm/exe.linux-riscv64": "12.15.0", + "@pnpm/exe.linux-s390x": "12.15.0", + "@pnpm/exe.linux-x64": "12.15.0", + "@pnpm/exe.linux-x64-musl": "12.15.0", + "@pnpm/exe.win32-arm64": "12.15.0", + "@pnpm/exe.win32-x64": "12.15.0" + } + }, + "node_modules/progress": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/progress/-/progress-2.0.3.tgz", + "integrity": "sha512-7PiHtLll5LdnKIMw100I+8xJXR5gW2QwWYkT6iJva0bXitZKa/XMrSbdmg3r2Xnaidz9Qumd0VPaMrZlF9V9sA==", + "license": "MIT", + "engines": { + "node": ">=0.4.0" + } + }, + "node_modules/ts-node": { + "version": "10.9.2", + "resolved": "https://registry.npmjs.org/ts-node/-/ts-node-10.9.2.tgz", + "integrity": "sha512-f0FFpIdcHgn8zcPSbf1dRevwt047YMnaiJM3u2w2RewrB+fob/zePZcrOyQoLMMO7aBIddLcQIEK5dYjkLnGrQ==", + "license": "MIT", + "dependencies": { + "@cspotcode/source-map-support": "^0.8.0", + "@tsconfig/node10": "^1.0.7", + "@tsconfig/node12": "^1.0.7", + "@tsconfig/node14": "^1.0.0", + "@tsconfig/node16": "^1.0.2", + "acorn": "^8.4.1", + "acorn-walk": "^8.1.1", + "arg": "^4.1.0", + "create-require": "^1.1.0", + "diff": "^4.0.1", + "make-error": "^1.1.1", + "v8-compile-cache-lib": "^3.0.1", + "yn": "3.1.1" + }, + "bin": { + "ts-node": "dist/bin.js", + "ts-node-cwd": "dist/bin-cwd.js", + "ts-node-esm": "dist/bin-esm.js", + "ts-node-script": "dist/bin-script.js", + "ts-node-transpile-only": "dist/bin-transpile.js", + "ts-script": "dist/bin-script-deprecated.js" + }, + "peerDependencies": { + "@swc/core": ">=1.2.50", + "@swc/wasm": ">=1.2.50", + "@types/node": "*", + "typescript": ">=2.7" + }, + "peerDependenciesMeta": { + "@swc/core": { + "optional": true + }, + "@swc/wasm": { + "optional": true + } + } + }, + "node_modules/ts-node/node_modules/diff": { + "version": "4.0.4", + "resolved": "https://registry.npmjs.org/diff/-/diff-4.0.4.tgz", + "integrity": "sha512-X07nttJQkwkfKfvTPG/KSnE2OMdcUCao6+eXF3wmnIQRn2aPAHH3VxDbDOdegkd6JbPsXqShpvEOHfAT+nCNwQ==", + "license": "BSD-3-Clause", + "engines": { + "node": ">=0.3.1" + } + }, + "node_modules/typescript": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-7.0.2.tgz", + "integrity": "sha512-8FYau96o3NKOhbjKi/qNvG/W5jhzxkbdm5sj9AbZ/5T5sWqn3hJgLfGx27sRKZWTvyzCP8dLRBTf5tBTSRVUNA==", + "license": "Apache-2.0", + "peer": true, + "bin": { + "tsc": "bin/tsc" + }, + "engines": { + "node": ">=16.20.0" + }, + "optionalDependencies": { + "@typescript/typescript-aix-ppc64": "7.0.2", + "@typescript/typescript-darwin-arm64": "7.0.2", + "@typescript/typescript-darwin-x64": "7.0.2", + "@typescript/typescript-freebsd-arm64": "7.0.2", + "@typescript/typescript-freebsd-x64": "7.0.2", + "@typescript/typescript-linux-arm": "7.0.2", + "@typescript/typescript-linux-arm64": "7.0.2", + "@typescript/typescript-linux-loong64": "7.0.2", + "@typescript/typescript-linux-mips64el": "7.0.2", + "@typescript/typescript-linux-ppc64": "7.0.2", + "@typescript/typescript-linux-riscv64": "7.0.2", + "@typescript/typescript-linux-s390x": "7.0.2", + "@typescript/typescript-linux-x64": "7.0.2", + "@typescript/typescript-netbsd-arm64": "7.0.2", + "@typescript/typescript-netbsd-x64": "7.0.2", + "@typescript/typescript-openbsd-arm64": "7.0.2", + "@typescript/typescript-openbsd-x64": "7.0.2", + "@typescript/typescript-sunos-x64": "7.0.2", + "@typescript/typescript-win32-arm64": "7.0.2", + "@typescript/typescript-win32-x64": "7.0.2" + } + }, + "node_modules/undici-types": { + "version": "8.9.0", + "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-8.9.0.tgz", + "integrity": "sha512-KTDyRTYX8sWmKXAikPHHSyc63CRPETMctyjKFupcC6OBLXT3xsN0e9aF7m+mIXutFWpUXuedtowG7iLOzp0kQg==", + "license": "MIT", + "peer": true + }, + "node_modules/v8-compile-cache-lib": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/v8-compile-cache-lib/-/v8-compile-cache-lib-3.0.1.tgz", + "integrity": "sha512-wa7YjyUGfNZngI/vtK0UHAN+lgDCxBPCylVXGp0zu59Fz5aiGtNXaq3DhIov063MorB+VfufLh3JlF2KdTK3xg==", + "license": "MIT" + }, + "node_modules/vscode-jsonrpc": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/vscode-jsonrpc/-/vscode-jsonrpc-6.0.0.tgz", + "integrity": "sha512-wnJA4BnEjOSyFMvjZdpiOwhSq9uDoK8e/kpRJDTaMYzwlkrhG1fwDIZI94CLsLzlCK5cIbMMtFlJlfR57Lavmg==", + "license": "MIT", + "engines": { + "node": ">=8.0.0 || >=10.0.0" + } + }, + "node_modules/vscode-languageserver": { + "version": "7.0.0", + "resolved": "https://registry.npmjs.org/vscode-languageserver/-/vscode-languageserver-7.0.0.tgz", + "integrity": "sha512-60HTx5ID+fLRcgdHfmz0LDZAXYEV68fzwG0JWwEPBode9NuMYTIxuYXPg4ngO8i8+Ou0lM7y6GzaYWbiDL0drw==", + "license": "MIT", + "dependencies": { + "vscode-languageserver-protocol": "3.16.0" + }, + "bin": { + "installServerIntoExtension": "bin/installServerIntoExtension" + } + }, + "node_modules/vscode-languageserver-protocol": { + "version": "3.16.0", + "resolved": "https://registry.npmjs.org/vscode-languageserver-protocol/-/vscode-languageserver-protocol-3.16.0.tgz", + "integrity": "sha512-sdeUoAawceQdgIfTI+sdcwkiK2KU+2cbEYA0agzM2uqaUy2UpnnGHtWTHVEtS0ES4zHU0eMFRGN+oQgDxlD66A==", + "license": "MIT", + "dependencies": { + "vscode-jsonrpc": "6.0.0", + "vscode-languageserver-types": "3.16.0" + } + }, + "node_modules/vscode-languageserver-types": { + "version": "3.16.0", + "resolved": "https://registry.npmjs.org/vscode-languageserver-types/-/vscode-languageserver-types-3.16.0.tgz", + "integrity": "sha512-k8luDIWJWyenLc5ToFQQMaSrqCHiLwyKPHKPQZ5zz21vM+vIVUSvsRpcbiECH4WR88K2XZqc4ScRcZ7nk/jbeA==", + "license": "MIT" + }, + "node_modules/wrappy": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz", + "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==", + "license": "ISC" + }, + "node_modules/yarn": { + "version": "1.22.22", + "resolved": "https://registry.npmjs.org/yarn/-/yarn-1.22.22.tgz", + "integrity": "sha512-prL3kGtyG7o9Z9Sv8IPfBNrWTDmXB4Qbes8A9rEzt6wkJV8mUvoirjU0Mp3GGAU06Y0XQyA3/2/RQFVuK7MTfg==", + "hasInstallScript": true, + "license": "BSD-2-Clause", + "bin": { + "yarn": "bin/yarn.js", + "yarnpkg": "bin/yarn.js" + }, + "engines": { + "node": ">=4.0.0" + } + }, + "node_modules/yn": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/yn/-/yn-3.1.1.tgz", + "integrity": "sha512-Ux4ygGWsu2c7isFWe8Yu1YluJmqVhxqK2cLXNQA5AcC3QfbGNpM7fu0Y8b/z16pXLnFxZYvWhd3fhBY9DLmC6Q==", + "license": "MIT", + "engines": { + "node": ">=6" + } + } + } +} diff --git a/scripts/code-toolchains/package.json b/scripts/code-toolchains/package.json new file mode 100644 index 0000000000..3a932d33e3 --- /dev/null +++ b/scripts/code-toolchains/package.json @@ -0,0 +1,12 @@ +{ + "name": "loom-scripts-code-toolchains", + "private": true, + "version": "0.0.0", + "dependencies": { + "@sourcegraph/scip-typescript": "0.4.0", + "@sourcegraph/scip-python": "0.6.6", + "pnpm": "12.15.0", + "yarn": "1.22.22", + "bun": "1.4.2" + } +} diff --git a/scripts/code-toolchains/yarn-modern/package-lock.json b/scripts/code-toolchains/yarn-modern/package-lock.json new file mode 100644 index 0000000000..5aba16f96a --- /dev/null +++ b/scripts/code-toolchains/yarn-modern/package-lock.json @@ -0,0 +1,28 @@ +{ + "name": "loom-scripts-code-toolchains-yarn-modern", + "version": "0.0.0", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "loom-scripts-code-toolchains-yarn-modern", + "version": "0.0.0", + "dependencies": { + "@yarnpkg/cli-dist": "4.18.1" + } + }, + "node_modules/@yarnpkg/cli-dist": { + "version": "4.18.1", + "resolved": "https://registry.npmjs.org/@yarnpkg/cli-dist/-/cli-dist-4.18.1.tgz", + "integrity": "sha512-EH+A4TxAtBWXKE0DGQxW9Bo9crXHLJ73mfxjTQJuv8XonNWWTpei8BQ5JjczHJNU9GROTycwMFn8iOvRIZXUcA==", + "license": "BSD-2-Clause", + "bin": { + "yarn": "bin/yarn.js", + "yarnpkg": "bin/yarn.js" + }, + "engines": { + "node": ">=18.12.0" + } + } + } +} diff --git a/scripts/code-toolchains/yarn-modern/package.json b/scripts/code-toolchains/yarn-modern/package.json new file mode 100644 index 0000000000..55dd869adc --- /dev/null +++ b/scripts/code-toolchains/yarn-modern/package.json @@ -0,0 +1,8 @@ +{ + "name": "loom-scripts-code-toolchains-yarn-modern", + "private": true, + "version": "0.0.0", + "dependencies": { + "@yarnpkg/cli-dist": "4.18.1" + } +} diff --git a/scripts/install-code-toolchains.sh b/scripts/install-code-toolchains.sh index 6fae35d308..7c20e61e4f 100644 --- a/scripts/install-code-toolchains.sh +++ b/scripts/install-code-toolchains.sh @@ -18,14 +18,21 @@ command -v npm >/dev/null 2>&1 || { toolchain_prefix=${LOOM_CODE_TOOLCHAIN_PREFIX:-"$PWD/var/code-toolchains"} mkdir -p "$toolchain_prefix" toolchain_prefix=$(cd "$toolchain_prefix" && pwd) -npm install --global --prefix "$toolchain_prefix" --no-fund --no-audit \ - '@sourcegraph/scip-typescript@0.4.0' '@sourcegraph/scip-python@0.6.6' \ - 'pnpm@12.15.0' 'yarn@1.22.22' 'bun@1.4.2' +script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd) +packages="$toolchain_prefix/lib/loom-node-tools" +mkdir -p "$packages" "$toolchain_prefix/bin" +cp "$script_dir/code-toolchains/package.json" "$script_dir/code-toolchains/package-lock.json" "$packages/" +npm ci --prefix "$packages" --no-fund --no-audit +for tool in scip-typescript scip-python pnpm pnpx yarn yarnpkg bun bunx; do + ln -sf "../lib/loom-node-tools/node_modules/.bin/$tool" "$toolchain_prefix/bin/$tool" +done # Keep both Yarn lockfile formats supported without downloading a tool at # indexing time or following a repository's executable yarnPath/plugins. -npm install --global --prefix "$toolchain_prefix/yarn-modern" --no-fund --no-audit \ - '@yarnpkg/cli-dist@4.18.1' -ln -sf ../yarn-modern/bin/yarn "$toolchain_prefix/bin/yarn-modern" +modern="$toolchain_prefix/lib/loom-yarn-modern" +mkdir -p "$modern" +cp "$script_dir/code-toolchains/yarn-modern/package.json" "$script_dir/code-toolchains/yarn-modern/package-lock.json" "$modern/" +npm ci --prefix "$modern" --no-fund --no-audit +ln -sf ../lib/loom-yarn-modern/node_modules/.bin/yarn "$toolchain_prefix/bin/yarn-modern" # The TypeScript tier installs with this pnpm and never fetches the one a repository # pins: it must load a workspace that sets lockfile options. diff --git a/tests/unit/test_course_starter.py b/tests/unit/test_course_starter.py index 72e3347a9b..395dd6a9cc 100644 --- a/tests/unit/test_course_starter.py +++ b/tests/unit/test_course_starter.py @@ -50,9 +50,12 @@ def test_devcontainer_matches_the_root_one() -> None: } -def test_start_script_is_the_root_one() -> None: - root = ROOT / ".devcontainer" / "start-loom.sh" - assert (STARTER / ".devcontainer" / "start-loom.sh").read_bytes() == root.read_bytes() +@pytest.mark.parametrize( + "name", ["start-loom.sh", "agent-cli/package.json", "agent-cli/package-lock.json"] +) +def test_start_script_is_the_root_one(name: str) -> None: + root = ROOT / ".devcontainer" / name + assert (STARTER / ".devcontainer" / name).read_bytes() == root.read_bytes() def test_workflow_actions_are_pinned_to_commits() -> None: From 7f43d3848ac1672245cbcf67120b3d72503f09a8 Mon Sep 17 00:00:00 2001 From: zlareb1 Date: Wed, 18 Nov 2026 12:17:03 +0000 Subject: [PATCH 06/22] Bind locked native tools without vendor lifecycle downloads Disable package lifecycle scripts and require matching native packages from the committed graph before binding launchers. Retain baseline CPU variants and offline shim rebuilding, and test missing-native failures with network and process leak controls. Signed-off-by: zlareb1 --- .devcontainer/agent-cli/bind-native.cjs | 153 +++++++++++++ .devcontainer/start-loom.sh | 3 +- .github/workflows/n8n-publish.yml | 4 +- .github/workflows/plugin-platforms.yml | 14 +- .../.devcontainer/agent-cli/bind-native.cjs | 153 +++++++++++++ .../.devcontainer/start-loom.sh | 3 +- scripts/code-toolchains/bind-native.cjs | 153 +++++++++++++ scripts/code-toolchains/package-lock.json | 58 +++++ scripts/code-toolchains/package.json | 6 + scripts/install-code-toolchains.sh | 6 +- tests/unit/test_course_starter.py | 15 +- tests/unit/test_node_native_bindings.py | 210 ++++++++++++++++++ 12 files changed, 768 insertions(+), 10 deletions(-) create mode 100644 .devcontainer/agent-cli/bind-native.cjs create mode 100644 examples/course-starter/.devcontainer/agent-cli/bind-native.cjs create mode 100644 scripts/code-toolchains/bind-native.cjs create mode 100644 tests/unit/test_node_native_bindings.py diff --git a/.devcontainer/agent-cli/bind-native.cjs b/.devcontainer/agent-cli/bind-native.cjs new file mode 100644 index 0000000000..cbb49c8ed4 --- /dev/null +++ b/.devcontainer/agent-cli/bind-native.cjs @@ -0,0 +1,153 @@ +#!/usr/bin/env node +const fs = require("node:fs"); +const path = require("node:path"); +const { execFileSync } = require("node:child_process"); + +function hostPlatform() { + let arch = process.arch; + if (process.platform === "darwin" && arch === "x64") { + try { + if ( + execFileSync("/usr/sbin/sysctl", ["-n", "sysctl.proc_translated"], { + encoding: "utf8", + timeout: 1000, + stdio: ["ignore", "pipe", "ignore"], + }).trim() === "1" + ) + arch = "arm64"; + } catch (error) { + if (error.status !== 1) throw error; + } + } + const musl = process.platform === "linux" && !process.report.getReport().header.glibcVersionRuntime; + return { platform: process.platform, arch, musl }; +} + +function nativeInfo(tool, { platform, arch, musl = false }) { + if (!["x64", "arm64"].includes(arch)) throw new Error(`Unsupported native architecture: ${arch}`); + const abi = platform === "linux" && musl ? "-musl" : ""; + const exe = platform === "win32" ? ".exe" : ""; + if (tool === "bun") { + const os = { win32: "windows", android: "linux" }[platform] || platform; + const cpu = arch === "arm64" ? "aarch64" : arch; + const suffix = platform === "android" ? "-android" : abi; + const baseline = arch === "x64" && platform !== "android" && platform !== "freebsd" ? "-baseline" : ""; + return { + wrapper: "bun", + native: `@oven/bun-${os}-${cpu}${suffix}${baseline}`, + file: `bin/bun${exe}`, + targets: ["bin/bun.exe", "bin/bunx.exe"], + }; + } + if (tool === "pnpm") { + return { + wrapper: "pnpm", + native: `@pnpm/exe.${platform}-${arch}${abi}`, + file: `pnpm${exe}`, + targets: ["pnpm", "pn", "pnpx", "pnx"].map((name) => name + exe), + }; + } + if (tool === "claude") { + return { + wrapper: "@anthropic-ai/claude-code", + native: `@anthropic-ai/claude-code-${platform}-${arch}${abi}`, + file: `claude${exe}`, + targets: ["bin/claude.exe"], + }; + } + throw new Error(`Unsupported native tool: ${tool}`); +} + +function json(file) { + return JSON.parse(fs.readFileSync(file, "utf8")); +} + +function inside(root, file) { + const relative = path.relative(root, file); + if (!relative || relative === ".." || relative.startsWith(".." + path.sep) || path.isAbsolute(relative)) + throw new Error("Native package path leaves its locked project"); +} + +function bindingPlan(project, tool, host) { + const info = nativeInfo(tool, host); + const manifest = json(path.join(project, "package.json")); + const lock = json(path.join(project, "package-lock.json")); + const wrapperDir = fs.realpathSync(path.join(project, "node_modules", info.wrapper)); + const wrapper = json(path.join(wrapperDir, "package.json")); + const expected = manifest.dependencies?.[info.wrapper]; + if (!expected || wrapper.name !== info.wrapper || wrapper.version !== expected) + throw new Error(`Native wrapper version mismatch: ${info.wrapper}`); + const declared = wrapper.optionalDependencies?.[info.native] || manifest.optionalDependencies?.[info.native]; + const entry = lock.packages?.[`node_modules/${info.native}`]; + if ( + declared !== expected || + entry?.version !== expected || + !/^sha512-[A-Za-z0-9+/]{86}==$/.test(entry.integrity || "") || + !entry.resolved?.startsWith("https://registry.npmjs.org/") + ) + throw new Error(`Native package is absent from the locked graph: ${info.native}`); + const nativeDir = fs.realpathSync(path.join(project, "node_modules", info.native)); + const native = json(path.join(nativeDir, "package.json")); + if (native.name !== info.native || native.version !== expected) + throw new Error(`Native package version mismatch: ${info.native}`); + const source = fs.realpathSync(path.join(nativeDir, info.file)); + inside(project, wrapperDir); + inside(project, nativeDir); + inside(nativeDir, source); + if (!fs.statSync(source).isFile() || fs.statSync(source).size === 0) + throw new Error(`Native binary is missing: ${info.native}`); + return { ...info, source, wrapperDir, host }; +} + +function placeBinary(source, destination) { + fs.mkdirSync(path.dirname(destination), { recursive: true }); + const temporary = destination + ".loom-native"; + fs.rmSync(temporary, { force: true }); + try { + try { + fs.linkSync(source, temporary); + } catch (error) { + if (!["EXDEV", "EPERM"].includes(error.code)) throw error; + fs.copyFileSync(source, temporary, fs.constants.COPYFILE_FICLONE); + } + fs.chmodSync(temporary, 0o755); + fs.renameSync(temporary, destination); + } finally { + fs.rmSync(temporary, { force: true }); + } +} + +function bindNative(project, tools, host = hostPlatform()) { + project = fs.realpathSync(project); + const plans = tools.map((tool) => bindingPlan(project, tool, host)); + for (const plan of plans) { + for (const target of plan.targets) { + const destination = path.join(plan.wrapperDir, target); + fs.mkdirSync(path.dirname(destination), { recursive: true }); + const parent = fs.realpathSync(path.dirname(destination)); + if (parent !== plan.wrapperDir) inside(plan.wrapperDir, parent); + placeBinary(plan.source, destination); + } + if (plan.wrapper === "pnpm" && host.platform === "win32") { + const file = path.join(plan.wrapperDir, "package.json"); + const manifest = json(file); + manifest.bin = Object.fromEntries(["pnpm", "pn", "pnpx", "pnx"].map((name) => [name, name + ".exe"])); + const temporary = file + ".loom-native"; + fs.writeFileSync(temporary, JSON.stringify(manifest, null, 2) + "\n"); + fs.renameSync(temporary, file); + } + } +} + +if (require.main === module) { + try { + const [project, ...tools] = process.argv.slice(2); + if (!project || tools.length === 0) throw new Error("Supply a locked project and native tools to bind"); + bindNative(project, tools); + } catch (error) { + console.error(`Native tool installation refused: ${error.message}`); + process.exitCode = 1; + } +} + +module.exports = { bindNative, nativeInfo }; diff --git a/.devcontainer/start-loom.sh b/.devcontainer/start-loom.sh index 181db00ff7..a4dfc75d3a 100755 --- a/.devcontainer/start-loom.sh +++ b/.devcontainer/start-loom.sh @@ -44,7 +44,8 @@ fi LOOM_CONNECT=none sh "$installer" script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd) -npm ci --prefix "$script_dir/agent-cli" --no-fund --no-audit +npm ci --prefix "$script_dir/agent-cli" --ignore-scripts --no-fund --no-audit +node "$script_dir/agent-cli/bind-native.cjs" "$script_dir/agent-cli" claude npm install --global --offline --ignore-scripts --silent "$script_dir/agent-cli/node_modules/@anthropic-ai/claude-code" claude plugin marketplace list 2>/dev/null | grep -Eq '[[:space:]]loom$' \ || claude plugin marketplace add ClickHouse/loom diff --git a/.github/workflows/n8n-publish.yml b/.github/workflows/n8n-publish.yml index bd05f02680..546c482187 100644 --- a/.github/workflows/n8n-publish.yml +++ b/.github/workflows/n8n-publish.yml @@ -25,7 +25,7 @@ jobs: node-version: "24" - name: Install the locked package manager run: | - npm ci --prefix .github/pnpm --no-fund --no-audit + npm ci --prefix .github/pnpm --ignore-scripts --no-fund --no-audit echo "$PWD/.github/pnpm/node_modules/.bin" >> "$GITHUB_PATH" - run: pnpm install --frozen-lockfile working-directory: integrations/n8n @@ -63,7 +63,7 @@ jobs: run: '[[ "$RELEASE_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]' - name: Install the locked package manager run: | - npm ci --prefix .github/pnpm --no-fund --no-audit + npm ci --prefix .github/pnpm --ignore-scripts --no-fund --no-audit echo "$PWD/.github/pnpm/node_modules/.bin" >> "$GITHUB_PATH" - run: pnpm install --frozen-lockfile working-directory: integrations/n8n diff --git a/.github/workflows/plugin-platforms.yml b/.github/workflows/plugin-platforms.yml index 33ef0ab243..64aab3b3ae 100644 --- a/.github/workflows/plugin-platforms.yml +++ b/.github/workflows/plugin-platforms.yml @@ -17,6 +17,7 @@ on: - ".gitattributes" - ".github/workflows/plugin-platforms.yml" - ".github/agent-clis/**" + - "scripts/code-toolchains/bind-native.cjs" pull_request: branches: [main, "release/**"] paths: @@ -26,6 +27,7 @@ on: - ".gitattributes" - ".github/workflows/plugin-platforms.yml" - ".github/agent-clis/**" + - "scripts/code-toolchains/bind-native.cjs" concurrency: group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.ref || github.sha }} @@ -69,11 +71,13 @@ jobs: - name: install the agent CLIs if: ${{ !cancelled() }} run: | - npm ci --prefix .github/agent-clis --no-fund --no-audit + npm ci --prefix .github/agent-clis --ignore-scripts --no-fund --no-audit + node scripts/code-toolchains/bind-native.cjs .github/agent-clis claude root=$(npm root --prefix .github/agent-clis) exe='' if [ "$RUNNER_OS" = Windows ]; then root=$(cygpath -m "$root"); exe=.exe; fi codex=$(ls "$root"/@openai/codex-*/vendor/*/bin/codex$exe | head -1) + test -n "$codex" && test -x "$codex" || { echo "The locked native agent executable is missing" >&2; exit 1; } echo "CLAUDE_BIN=$root/@anthropic-ai/claude-code/bin/claude.exe" >> "$GITHUB_ENV" echo "CODEX_BIN=$codex" >> "$GITHUB_ENV" - name: Claude Code session @@ -125,9 +129,11 @@ jobs: docker run --rm -v "$PWD:/src:ro" "$ALPINE_IMAGE" sh -euc ' apk add --quiet git bash cp -r /src /tmp/repo && chown -R node /tmp/repo - npm ci --prefix /tmp/repo/.github/agent-clis --no-fund --no-audit >/dev/null + npm ci --prefix /tmp/repo/.github/agent-clis --ignore-scripts --no-fund --no-audit >/dev/null + node /tmp/repo/scripts/code-toolchains/bind-native.cjs /tmp/repo/.github/agent-clis claude root=$(npm root --prefix /tmp/repo/.github/agent-clis) codex=$(ls "$root"/@openai/codex-linux-*/vendor/*/bin/codex | head -1) + test -n "$codex" && test -x "$codex" || { echo "The locked native agent executable is missing" >&2; exit 1; } su node -s /bin/sh -c " set -e cd /tmp/repo @@ -162,9 +168,11 @@ jobs: # A clone inside WSL, with Linux modes and line endings, as a WSL user's is. git -c safe.directory='*' clone --quiet --no-local . /home/ci/repo chown -R ci /home/ci/repo - npm ci --prefix /home/ci/repo/.github/agent-clis --no-fund --no-audit >/dev/null + npm ci --prefix /home/ci/repo/.github/agent-clis --ignore-scripts --no-fund --no-audit >/dev/null + node /home/ci/repo/scripts/code-toolchains/bind-native.cjs /home/ci/repo/.github/agent-clis claude root=$(npm root --prefix /home/ci/repo/.github/agent-clis) codex=$(ls "$root"/@openai/codex-linux-*/vendor/*/bin/codex | head -1) + test -n "$codex" && test -x "$codex" || { echo "The locked native agent executable is missing" >&2; exit 1; } su ci -s /bin/sh -c " set -e cd /home/ci/repo diff --git a/examples/course-starter/.devcontainer/agent-cli/bind-native.cjs b/examples/course-starter/.devcontainer/agent-cli/bind-native.cjs new file mode 100644 index 0000000000..cbb49c8ed4 --- /dev/null +++ b/examples/course-starter/.devcontainer/agent-cli/bind-native.cjs @@ -0,0 +1,153 @@ +#!/usr/bin/env node +const fs = require("node:fs"); +const path = require("node:path"); +const { execFileSync } = require("node:child_process"); + +function hostPlatform() { + let arch = process.arch; + if (process.platform === "darwin" && arch === "x64") { + try { + if ( + execFileSync("/usr/sbin/sysctl", ["-n", "sysctl.proc_translated"], { + encoding: "utf8", + timeout: 1000, + stdio: ["ignore", "pipe", "ignore"], + }).trim() === "1" + ) + arch = "arm64"; + } catch (error) { + if (error.status !== 1) throw error; + } + } + const musl = process.platform === "linux" && !process.report.getReport().header.glibcVersionRuntime; + return { platform: process.platform, arch, musl }; +} + +function nativeInfo(tool, { platform, arch, musl = false }) { + if (!["x64", "arm64"].includes(arch)) throw new Error(`Unsupported native architecture: ${arch}`); + const abi = platform === "linux" && musl ? "-musl" : ""; + const exe = platform === "win32" ? ".exe" : ""; + if (tool === "bun") { + const os = { win32: "windows", android: "linux" }[platform] || platform; + const cpu = arch === "arm64" ? "aarch64" : arch; + const suffix = platform === "android" ? "-android" : abi; + const baseline = arch === "x64" && platform !== "android" && platform !== "freebsd" ? "-baseline" : ""; + return { + wrapper: "bun", + native: `@oven/bun-${os}-${cpu}${suffix}${baseline}`, + file: `bin/bun${exe}`, + targets: ["bin/bun.exe", "bin/bunx.exe"], + }; + } + if (tool === "pnpm") { + return { + wrapper: "pnpm", + native: `@pnpm/exe.${platform}-${arch}${abi}`, + file: `pnpm${exe}`, + targets: ["pnpm", "pn", "pnpx", "pnx"].map((name) => name + exe), + }; + } + if (tool === "claude") { + return { + wrapper: "@anthropic-ai/claude-code", + native: `@anthropic-ai/claude-code-${platform}-${arch}${abi}`, + file: `claude${exe}`, + targets: ["bin/claude.exe"], + }; + } + throw new Error(`Unsupported native tool: ${tool}`); +} + +function json(file) { + return JSON.parse(fs.readFileSync(file, "utf8")); +} + +function inside(root, file) { + const relative = path.relative(root, file); + if (!relative || relative === ".." || relative.startsWith(".." + path.sep) || path.isAbsolute(relative)) + throw new Error("Native package path leaves its locked project"); +} + +function bindingPlan(project, tool, host) { + const info = nativeInfo(tool, host); + const manifest = json(path.join(project, "package.json")); + const lock = json(path.join(project, "package-lock.json")); + const wrapperDir = fs.realpathSync(path.join(project, "node_modules", info.wrapper)); + const wrapper = json(path.join(wrapperDir, "package.json")); + const expected = manifest.dependencies?.[info.wrapper]; + if (!expected || wrapper.name !== info.wrapper || wrapper.version !== expected) + throw new Error(`Native wrapper version mismatch: ${info.wrapper}`); + const declared = wrapper.optionalDependencies?.[info.native] || manifest.optionalDependencies?.[info.native]; + const entry = lock.packages?.[`node_modules/${info.native}`]; + if ( + declared !== expected || + entry?.version !== expected || + !/^sha512-[A-Za-z0-9+/]{86}==$/.test(entry.integrity || "") || + !entry.resolved?.startsWith("https://registry.npmjs.org/") + ) + throw new Error(`Native package is absent from the locked graph: ${info.native}`); + const nativeDir = fs.realpathSync(path.join(project, "node_modules", info.native)); + const native = json(path.join(nativeDir, "package.json")); + if (native.name !== info.native || native.version !== expected) + throw new Error(`Native package version mismatch: ${info.native}`); + const source = fs.realpathSync(path.join(nativeDir, info.file)); + inside(project, wrapperDir); + inside(project, nativeDir); + inside(nativeDir, source); + if (!fs.statSync(source).isFile() || fs.statSync(source).size === 0) + throw new Error(`Native binary is missing: ${info.native}`); + return { ...info, source, wrapperDir, host }; +} + +function placeBinary(source, destination) { + fs.mkdirSync(path.dirname(destination), { recursive: true }); + const temporary = destination + ".loom-native"; + fs.rmSync(temporary, { force: true }); + try { + try { + fs.linkSync(source, temporary); + } catch (error) { + if (!["EXDEV", "EPERM"].includes(error.code)) throw error; + fs.copyFileSync(source, temporary, fs.constants.COPYFILE_FICLONE); + } + fs.chmodSync(temporary, 0o755); + fs.renameSync(temporary, destination); + } finally { + fs.rmSync(temporary, { force: true }); + } +} + +function bindNative(project, tools, host = hostPlatform()) { + project = fs.realpathSync(project); + const plans = tools.map((tool) => bindingPlan(project, tool, host)); + for (const plan of plans) { + for (const target of plan.targets) { + const destination = path.join(plan.wrapperDir, target); + fs.mkdirSync(path.dirname(destination), { recursive: true }); + const parent = fs.realpathSync(path.dirname(destination)); + if (parent !== plan.wrapperDir) inside(plan.wrapperDir, parent); + placeBinary(plan.source, destination); + } + if (plan.wrapper === "pnpm" && host.platform === "win32") { + const file = path.join(plan.wrapperDir, "package.json"); + const manifest = json(file); + manifest.bin = Object.fromEntries(["pnpm", "pn", "pnpx", "pnx"].map((name) => [name, name + ".exe"])); + const temporary = file + ".loom-native"; + fs.writeFileSync(temporary, JSON.stringify(manifest, null, 2) + "\n"); + fs.renameSync(temporary, file); + } + } +} + +if (require.main === module) { + try { + const [project, ...tools] = process.argv.slice(2); + if (!project || tools.length === 0) throw new Error("Supply a locked project and native tools to bind"); + bindNative(project, tools); + } catch (error) { + console.error(`Native tool installation refused: ${error.message}`); + process.exitCode = 1; + } +} + +module.exports = { bindNative, nativeInfo }; diff --git a/examples/course-starter/.devcontainer/start-loom.sh b/examples/course-starter/.devcontainer/start-loom.sh index 181db00ff7..a4dfc75d3a 100755 --- a/examples/course-starter/.devcontainer/start-loom.sh +++ b/examples/course-starter/.devcontainer/start-loom.sh @@ -44,7 +44,8 @@ fi LOOM_CONNECT=none sh "$installer" script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd) -npm ci --prefix "$script_dir/agent-cli" --no-fund --no-audit +npm ci --prefix "$script_dir/agent-cli" --ignore-scripts --no-fund --no-audit +node "$script_dir/agent-cli/bind-native.cjs" "$script_dir/agent-cli" claude npm install --global --offline --ignore-scripts --silent "$script_dir/agent-cli/node_modules/@anthropic-ai/claude-code" claude plugin marketplace list 2>/dev/null | grep -Eq '[[:space:]]loom$' \ || claude plugin marketplace add ClickHouse/loom diff --git a/scripts/code-toolchains/bind-native.cjs b/scripts/code-toolchains/bind-native.cjs new file mode 100644 index 0000000000..cbb49c8ed4 --- /dev/null +++ b/scripts/code-toolchains/bind-native.cjs @@ -0,0 +1,153 @@ +#!/usr/bin/env node +const fs = require("node:fs"); +const path = require("node:path"); +const { execFileSync } = require("node:child_process"); + +function hostPlatform() { + let arch = process.arch; + if (process.platform === "darwin" && arch === "x64") { + try { + if ( + execFileSync("/usr/sbin/sysctl", ["-n", "sysctl.proc_translated"], { + encoding: "utf8", + timeout: 1000, + stdio: ["ignore", "pipe", "ignore"], + }).trim() === "1" + ) + arch = "arm64"; + } catch (error) { + if (error.status !== 1) throw error; + } + } + const musl = process.platform === "linux" && !process.report.getReport().header.glibcVersionRuntime; + return { platform: process.platform, arch, musl }; +} + +function nativeInfo(tool, { platform, arch, musl = false }) { + if (!["x64", "arm64"].includes(arch)) throw new Error(`Unsupported native architecture: ${arch}`); + const abi = platform === "linux" && musl ? "-musl" : ""; + const exe = platform === "win32" ? ".exe" : ""; + if (tool === "bun") { + const os = { win32: "windows", android: "linux" }[platform] || platform; + const cpu = arch === "arm64" ? "aarch64" : arch; + const suffix = platform === "android" ? "-android" : abi; + const baseline = arch === "x64" && platform !== "android" && platform !== "freebsd" ? "-baseline" : ""; + return { + wrapper: "bun", + native: `@oven/bun-${os}-${cpu}${suffix}${baseline}`, + file: `bin/bun${exe}`, + targets: ["bin/bun.exe", "bin/bunx.exe"], + }; + } + if (tool === "pnpm") { + return { + wrapper: "pnpm", + native: `@pnpm/exe.${platform}-${arch}${abi}`, + file: `pnpm${exe}`, + targets: ["pnpm", "pn", "pnpx", "pnx"].map((name) => name + exe), + }; + } + if (tool === "claude") { + return { + wrapper: "@anthropic-ai/claude-code", + native: `@anthropic-ai/claude-code-${platform}-${arch}${abi}`, + file: `claude${exe}`, + targets: ["bin/claude.exe"], + }; + } + throw new Error(`Unsupported native tool: ${tool}`); +} + +function json(file) { + return JSON.parse(fs.readFileSync(file, "utf8")); +} + +function inside(root, file) { + const relative = path.relative(root, file); + if (!relative || relative === ".." || relative.startsWith(".." + path.sep) || path.isAbsolute(relative)) + throw new Error("Native package path leaves its locked project"); +} + +function bindingPlan(project, tool, host) { + const info = nativeInfo(tool, host); + const manifest = json(path.join(project, "package.json")); + const lock = json(path.join(project, "package-lock.json")); + const wrapperDir = fs.realpathSync(path.join(project, "node_modules", info.wrapper)); + const wrapper = json(path.join(wrapperDir, "package.json")); + const expected = manifest.dependencies?.[info.wrapper]; + if (!expected || wrapper.name !== info.wrapper || wrapper.version !== expected) + throw new Error(`Native wrapper version mismatch: ${info.wrapper}`); + const declared = wrapper.optionalDependencies?.[info.native] || manifest.optionalDependencies?.[info.native]; + const entry = lock.packages?.[`node_modules/${info.native}`]; + if ( + declared !== expected || + entry?.version !== expected || + !/^sha512-[A-Za-z0-9+/]{86}==$/.test(entry.integrity || "") || + !entry.resolved?.startsWith("https://registry.npmjs.org/") + ) + throw new Error(`Native package is absent from the locked graph: ${info.native}`); + const nativeDir = fs.realpathSync(path.join(project, "node_modules", info.native)); + const native = json(path.join(nativeDir, "package.json")); + if (native.name !== info.native || native.version !== expected) + throw new Error(`Native package version mismatch: ${info.native}`); + const source = fs.realpathSync(path.join(nativeDir, info.file)); + inside(project, wrapperDir); + inside(project, nativeDir); + inside(nativeDir, source); + if (!fs.statSync(source).isFile() || fs.statSync(source).size === 0) + throw new Error(`Native binary is missing: ${info.native}`); + return { ...info, source, wrapperDir, host }; +} + +function placeBinary(source, destination) { + fs.mkdirSync(path.dirname(destination), { recursive: true }); + const temporary = destination + ".loom-native"; + fs.rmSync(temporary, { force: true }); + try { + try { + fs.linkSync(source, temporary); + } catch (error) { + if (!["EXDEV", "EPERM"].includes(error.code)) throw error; + fs.copyFileSync(source, temporary, fs.constants.COPYFILE_FICLONE); + } + fs.chmodSync(temporary, 0o755); + fs.renameSync(temporary, destination); + } finally { + fs.rmSync(temporary, { force: true }); + } +} + +function bindNative(project, tools, host = hostPlatform()) { + project = fs.realpathSync(project); + const plans = tools.map((tool) => bindingPlan(project, tool, host)); + for (const plan of plans) { + for (const target of plan.targets) { + const destination = path.join(plan.wrapperDir, target); + fs.mkdirSync(path.dirname(destination), { recursive: true }); + const parent = fs.realpathSync(path.dirname(destination)); + if (parent !== plan.wrapperDir) inside(plan.wrapperDir, parent); + placeBinary(plan.source, destination); + } + if (plan.wrapper === "pnpm" && host.platform === "win32") { + const file = path.join(plan.wrapperDir, "package.json"); + const manifest = json(file); + manifest.bin = Object.fromEntries(["pnpm", "pn", "pnpx", "pnx"].map((name) => [name, name + ".exe"])); + const temporary = file + ".loom-native"; + fs.writeFileSync(temporary, JSON.stringify(manifest, null, 2) + "\n"); + fs.renameSync(temporary, file); + } + } +} + +if (require.main === module) { + try { + const [project, ...tools] = process.argv.slice(2); + if (!project || tools.length === 0) throw new Error("Supply a locked project and native tools to bind"); + bindNative(project, tools); + } catch (error) { + console.error(`Native tool installation refused: ${error.message}`); + process.exitCode = 1; + } +} + +module.exports = { bindNative, nativeInfo }; diff --git a/scripts/code-toolchains/package-lock.json b/scripts/code-toolchains/package-lock.json index c7177103da..0c50229f8e 100644 --- a/scripts/code-toolchains/package-lock.json +++ b/scripts/code-toolchains/package-lock.json @@ -13,6 +13,12 @@ "bun": "1.4.2", "pnpm": "12.15.0", "yarn": "1.22.22" + }, + "optionalDependencies": { + "@oven/bun-darwin-x64-baseline": "1.4.2", + "@oven/bun-linux-x64-baseline": "1.4.2", + "@oven/bun-linux-x64-musl-baseline": "1.4.2", + "@oven/bun-windows-x64-baseline": "1.4.2" } }, "node_modules/@cspotcode/source-map-support": { @@ -84,6 +90,19 @@ "darwin" ] }, + "node_modules/@oven/bun-darwin-x64-baseline": { + "version": "1.4.2", + "resolved": "https://registry.npmjs.org/@oven/bun-darwin-x64-baseline/-/bun-darwin-x64-baseline-1.4.2.tgz", + "integrity": "sha512-lVDbk/HkN+RP8QKXBe0aou7EifA2PC9+Z4cvy2VDpmR1ONdDm8e2h/HsU7ABq7mvVs/76iq5H86nMvAhwJDadQ==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ] + }, "node_modules/@oven/bun-freebsd-aarch64": { "version": "1.4.2", "resolved": "https://registry.npmjs.org/@oven/bun-freebsd-aarch64/-/bun-freebsd-aarch64-1.4.2.tgz", @@ -175,6 +194,19 @@ "android" ] }, + "node_modules/@oven/bun-linux-x64-baseline": { + "version": "1.4.2", + "resolved": "https://registry.npmjs.org/@oven/bun-linux-x64-baseline/-/bun-linux-x64-baseline-1.4.2.tgz", + "integrity": "sha512-OKKzX/SOVIUVARCzTg+2r4Rcc4fPyWnQmBsd3K08buxeu7DAof4iwW9zSb6Lt1NhTCu4Uhi8k9UeI6f7GEE4Zg==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, "node_modules/@oven/bun-linux-x64-musl": { "version": "1.4.2", "resolved": "https://registry.npmjs.org/@oven/bun-linux-x64-musl/-/bun-linux-x64-musl-1.4.2.tgz", @@ -188,6 +220,19 @@ "linux" ] }, + "node_modules/@oven/bun-linux-x64-musl-baseline": { + "version": "1.4.2", + "resolved": "https://registry.npmjs.org/@oven/bun-linux-x64-musl-baseline/-/bun-linux-x64-musl-baseline-1.4.2.tgz", + "integrity": "sha512-Rn9yJ/7FPA+WZe7L2BvGifFFCiiRfB8zeLZa2Ye0ojOvdN1FJ2ddthH80L4twNMW0N142LrDEaMnTLUYAX971w==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, "node_modules/@oven/bun-windows-aarch64": { "version": "1.4.2", "resolved": "https://registry.npmjs.org/@oven/bun-windows-aarch64/-/bun-windows-aarch64-1.4.2.tgz", @@ -214,6 +259,19 @@ "win32" ] }, + "node_modules/@oven/bun-windows-x64-baseline": { + "version": "1.4.2", + "resolved": "https://registry.npmjs.org/@oven/bun-windows-x64-baseline/-/bun-windows-x64-baseline-1.4.2.tgz", + "integrity": "sha512-lq82LqVjSXAx9gNUcibCdfQdtrelh86FxQqlhpOdiV4SZQAP8HHUxWhnfbjx2fqz+jzglwBvjmlEs7xFyONBZw==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "win32" + ] + }, "node_modules/@pnpm/exe.android-arm64": { "version": "12.15.0", "resolved": "https://registry.npmjs.org/@pnpm/exe.android-arm64/-/exe.android-arm64-12.15.0.tgz", diff --git a/scripts/code-toolchains/package.json b/scripts/code-toolchains/package.json index 3a932d33e3..8150d64ee8 100644 --- a/scripts/code-toolchains/package.json +++ b/scripts/code-toolchains/package.json @@ -8,5 +8,11 @@ "pnpm": "12.15.0", "yarn": "1.22.22", "bun": "1.4.2" + }, + "optionalDependencies": { + "@oven/bun-darwin-x64-baseline": "1.4.2", + "@oven/bun-linux-x64-baseline": "1.4.2", + "@oven/bun-linux-x64-musl-baseline": "1.4.2", + "@oven/bun-windows-x64-baseline": "1.4.2" } } diff --git a/scripts/install-code-toolchains.sh b/scripts/install-code-toolchains.sh index 7c20e61e4f..c637b097e9 100644 --- a/scripts/install-code-toolchains.sh +++ b/scripts/install-code-toolchains.sh @@ -22,7 +22,9 @@ script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd) packages="$toolchain_prefix/lib/loom-node-tools" mkdir -p "$packages" "$toolchain_prefix/bin" cp "$script_dir/code-toolchains/package.json" "$script_dir/code-toolchains/package-lock.json" "$packages/" -npm ci --prefix "$packages" --no-fund --no-audit +npm ci --prefix "$packages" --ignore-scripts --no-fund --no-audit +node "$script_dir/code-toolchains/bind-native.cjs" "$packages" bun pnpm +npm rebuild --prefix "$packages" --ignore-scripts --offline --no-fund --no-audit for tool in scip-typescript scip-python pnpm pnpx yarn yarnpkg bun bunx; do ln -sf "../lib/loom-node-tools/node_modules/.bin/$tool" "$toolchain_prefix/bin/$tool" done @@ -31,7 +33,7 @@ done modern="$toolchain_prefix/lib/loom-yarn-modern" mkdir -p "$modern" cp "$script_dir/code-toolchains/yarn-modern/package.json" "$script_dir/code-toolchains/yarn-modern/package-lock.json" "$modern/" -npm ci --prefix "$modern" --no-fund --no-audit +npm ci --prefix "$modern" --ignore-scripts --no-fund --no-audit ln -sf ../lib/loom-yarn-modern/node_modules/.bin/yarn "$toolchain_prefix/bin/yarn-modern" # The TypeScript tier installs with this pnpm and never fetches the one a repository diff --git a/tests/unit/test_course_starter.py b/tests/unit/test_course_starter.py index 395dd6a9cc..8a8383de95 100644 --- a/tests/unit/test_course_starter.py +++ b/tests/unit/test_course_starter.py @@ -51,13 +51,26 @@ def test_devcontainer_matches_the_root_one() -> None: @pytest.mark.parametrize( - "name", ["start-loom.sh", "agent-cli/package.json", "agent-cli/package-lock.json"] + "name", + [ + "start-loom.sh", + "agent-cli/package.json", + "agent-cli/package-lock.json", + "agent-cli/bind-native.cjs", + ], ) def test_start_script_is_the_root_one(name: str) -> None: root = ROOT / ".devcontainer" / name assert (STARTER / ".devcontainer" / name).read_bytes() == root.read_bytes() +def test_copied_native_binding_helper_matches_the_installer() -> None: + helper = ROOT / "scripts" / "code-toolchains" / "bind-native.cjs" + assert ( + ROOT / ".devcontainer" / "agent-cli" / "bind-native.cjs" + ).read_bytes() == helper.read_bytes() + + def test_workflow_actions_are_pinned_to_commits() -> None: """A teacher's copy keeps its pins; a commit, unlike a tag, cannot move under it.""" workflow = (STARTER / ".github" / "workflows" / "grade.yml").read_text() diff --git a/tests/unit/test_node_native_bindings.py b/tests/unit/test_node_native_bindings.py new file mode 100644 index 0000000000..7e47375066 --- /dev/null +++ b/tests/unit/test_node_native_bindings.py @@ -0,0 +1,210 @@ +"""Locked tooling never delegates a missing native package to an installer download.""" + +from __future__ import annotations + +import json +import os +import shlex +import shutil +import subprocess +from pathlib import Path + +import pytest + +ROOT = Path(__file__).resolve().parents[2] +HELPER = ROOT / "scripts/code-toolchains/bind-native.cjs" +HOST = {"platform": "linux", "arch": "x64", "musl": False} +CASES = { + "bun": ("bun", "@oven/bun-linux-x64-baseline", "bin/bun", ("bin/bun.exe", "bin/bunx.exe")), + "pnpm": ("pnpm", "@pnpm/exe.linux-x64", "pnpm", ("pnpm", "pn", "pnpx", "pnx")), + "claude": ( + "@anthropic-ai/claude-code", + "@anthropic-ai/claude-code-linux-x64", + "claude", + ("bin/claude.exe",), + ), +} +NATIVE = b"native binary from the locked optional package\n" +PLACEHOLDER = b"unbound placeholder\n" + + +def make_project(tmp_path: Path, tools: tuple[str, ...]) -> Path: + project = tmp_path / "project" + project.mkdir() + manifest: dict = {"dependencies": {}, "optionalDependencies": {}} + lock: dict = {"packages": {}} + for tool in tools: + wrapper, native, binary, targets = CASES[tool] + manifest["dependencies"][wrapper] = "1.2.3" + manifest["optionalDependencies"][native] = "1.2.3" + wrapper_dir = project / "node_modules" / wrapper + native_dir = project / "node_modules" / native + wrapper_dir.mkdir(parents=True) + native_dir.mkdir(parents=True) + (wrapper_dir / "package.json").write_text(json.dumps({"name": wrapper, "version": "1.2.3"})) + (native_dir / "package.json").write_text(json.dumps({"name": native, "version": "1.2.3"})) + source = native_dir / binary + source.parent.mkdir(parents=True, exist_ok=True) + source.write_bytes(NATIVE) + for target in targets: + dest = wrapper_dir / target + dest.parent.mkdir(parents=True, exist_ok=True) + dest.write_bytes(PLACEHOLDER) + lock["packages"][f"node_modules/{native}"] = { + "version": "1.2.3", + "integrity": "sha512-" + "A" * 86 + "==", + "resolved": f"https://registry.npmjs.org/{native}/-/native.tgz", + } + (project / "package.json").write_text(json.dumps(manifest)) + (project / "package-lock.json").write_text(json.dumps(lock)) + return project + + +def bind( + project: Path, + tools: tuple[str, ...], + tmp_path: Path, + host: dict[str, object] | None = None, +) -> subprocess.CompletedProcess[str]: + guard = tmp_path / "network-guard.cjs" + guard.write_text( + "const fs = require('node:fs');\n" + "function blocked() { fs.appendFileSync(process.env.BIND_LEAK_LOG, 'leak\\n'); throw Error('network or process launch'); }\n" + "globalThis.fetch = blocked;\n" + "for (const name of ['node:http', 'node:https']) { const api = require(name); api.get = api.request = blocked; }\n" + "const net = require('node:net'); net.connect = net.createConnection = blocked;\n" + "const cp = require('node:child_process');\n" + "for (const name of ['spawn', 'spawnSync', 'exec', 'execSync', 'execFile', 'execFileSync', 'fork']) cp[name] = blocked;\n" + ) + return subprocess.run( + [ + shutil.which("node") or "node", + "--require", + str(guard), + "-e", + "require(process.argv[1]).bindNative(process.argv[2], JSON.parse(process.argv[3]), JSON.parse(process.argv[4]));", + str(HELPER), + str(project), + json.dumps(tools), + json.dumps(HOST if host is None else host), + ], + env={**os.environ, "BIND_LEAK_LOG": str(tmp_path / "leaks")}, + capture_output=True, + text=True, + timeout=10, + ) + + +@pytest.mark.parametrize("tool", CASES) +def test_native_binding_uses_the_locked_optional_package(tmp_path: Path, tool: str) -> None: + project = make_project(tmp_path, (tool,)) + result = bind(project, (tool,), tmp_path) + assert result.returncode == 0, result.stderr + wrapper, _, _, targets = CASES[tool] + assert all( + (project / "node_modules" / wrapper / target).read_bytes() == NATIVE for target in targets + ) + assert not (tmp_path / "leaks").exists() + + +@pytest.mark.parametrize("tool", CASES) +@pytest.mark.parametrize("missing", ["package", "binary"]) +def test_missing_native_fails_without_a_download(tmp_path: Path, tool: str, missing: str) -> None: + project = make_project(tmp_path, (tool,)) + wrapper, native, binary, targets = CASES[tool] + native_dir = project / "node_modules" / native + if missing == "package": + shutil.rmtree(native_dir) + else: + (native_dir / binary).unlink() + result = bind(project, (tool,), tmp_path) + assert result.returncode != 0 + assert all( + (project / "node_modules" / wrapper / target).read_bytes() == PLACEHOLDER + for target in targets + ) + assert not (tmp_path / "leaks").exists() + + +def test_all_required_packages_are_checked_before_binding(tmp_path: Path) -> None: + project = make_project(tmp_path, ("bun", "pnpm")) + (project / "node_modules" / CASES["pnpm"][1] / "pnpm").unlink() + result = bind(project, ("bun", "pnpm"), tmp_path) + assert result.returncode != 0 + assert (project / "node_modules/bun/bin/bun.exe").read_bytes() == PLACEHOLDER + assert not (tmp_path / "leaks").exists() + + +def test_native_binary_cannot_escape_its_locked_package(tmp_path: Path) -> None: + project = make_project(tmp_path, ("bun",)) + source = project / "node_modules" / CASES["bun"][1] / "bin/bun" + source.unlink() + outside = tmp_path / "unlocked" + outside.write_bytes(NATIVE) + source.symlink_to(outside) + result = bind(project, ("bun",), tmp_path) + assert result.returncode != 0 + assert (project / "node_modules/bun/bin/bun.exe").read_bytes() == PLACEHOLDER + assert not (tmp_path / "leaks").exists() + + +def test_windows_package_manager_targets_native_executables(tmp_path: Path) -> None: + project = make_project(tmp_path, ("pnpm",)) + old_name = CASES["pnpm"][1] + native = "@pnpm/exe.win32-x64" + native_dir = project / "node_modules" / native + (project / "node_modules" / old_name).rename(native_dir) + (native_dir / "pnpm").rename(native_dir / "pnpm.exe") + (native_dir / "package.json").write_text(json.dumps({"name": native, "version": "1.2.3"})) + file = project / "package.json" + manifest = json.loads(file.read_text()) + manifest["optionalDependencies"] = {native: "1.2.3"} + file.write_text(json.dumps(manifest)) + file = project / "package-lock.json" + lock = json.loads(file.read_text()) + lock["packages"][f"node_modules/{native}"] = lock["packages"].pop(f"node_modules/{old_name}") + file.write_text(json.dumps(lock)) + result = bind(project, ("pnpm",), tmp_path, {"platform": "win32", "arch": "x64"}) + assert result.returncode == 0, result.stderr + wrapper = project / "node_modules/pnpm" + targets = {name: name + ".exe" for name in ("pnpm", "pn", "pnpx", "pnx")} + assert json.loads((wrapper / "package.json").read_text())["bin"] == targets + assert all((wrapper / target).read_bytes() == NATIVE for target in targets.values()) + assert not (tmp_path / "leaks").exists() + + +def test_the_leak_control_intercepts_a_nested_package_install(tmp_path: Path) -> None: + project = make_project(tmp_path, ("bun",)) + assert bind(project, ("bun",), tmp_path).returncode == 0 + result = subprocess.run( + [ + shutil.which("node") or "node", + "--require", + str(tmp_path / "network-guard.cjs"), + "-e", + "try { require('node:child_process').spawnSync('npm', ['install', 'unlocked']); } catch {}", + ], + env={**os.environ, "BIND_LEAK_LOG": str(tmp_path / "leaks")}, + capture_output=True, + timeout=10, + ) + assert result.returncode == 0 + assert (tmp_path / "leaks").read_text() == "leak\n" + + +def test_tool_projects_never_run_vendor_lifecycle_scripts() -> None: + paths = [ + "scripts/install-code-toolchains.sh", + ".devcontainer/start-loom.sh", + "examples/course-starter/.devcontainer/start-loom.sh", + ".github/workflows/plugin-platforms.yml", + ".github/workflows/n8n-publish.yml", + ] + for filename in paths: + commands = [ + shlex.split(line.strip()) + for line in (ROOT / filename).read_text().splitlines() + if line.strip().startswith("npm ci ") + ] + assert commands, filename + assert all("--ignore-scripts" in command for command in commands), filename From 40b8953523d11dedbef90a8b3a98ae7160c7a48f Mon Sep 17 00:00:00 2001 From: zlareb1 Date: Wed, 18 Nov 2026 12:18:18 +0000 Subject: [PATCH 07/22] Validate native package containment before reading metadata Signed-off-by: zlareb1 --- .devcontainer/agent-cli/bind-native.cjs | 4 ++-- .../course-starter/.devcontainer/agent-cli/bind-native.cjs | 4 ++-- scripts/code-toolchains/bind-native.cjs | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/.devcontainer/agent-cli/bind-native.cjs b/.devcontainer/agent-cli/bind-native.cjs index cbb49c8ed4..8779a17a23 100644 --- a/.devcontainer/agent-cli/bind-native.cjs +++ b/.devcontainer/agent-cli/bind-native.cjs @@ -73,6 +73,7 @@ function bindingPlan(project, tool, host) { const manifest = json(path.join(project, "package.json")); const lock = json(path.join(project, "package-lock.json")); const wrapperDir = fs.realpathSync(path.join(project, "node_modules", info.wrapper)); + inside(project, wrapperDir); const wrapper = json(path.join(wrapperDir, "package.json")); const expected = manifest.dependencies?.[info.wrapper]; if (!expected || wrapper.name !== info.wrapper || wrapper.version !== expected) @@ -87,12 +88,11 @@ function bindingPlan(project, tool, host) { ) throw new Error(`Native package is absent from the locked graph: ${info.native}`); const nativeDir = fs.realpathSync(path.join(project, "node_modules", info.native)); + inside(project, nativeDir); const native = json(path.join(nativeDir, "package.json")); if (native.name !== info.native || native.version !== expected) throw new Error(`Native package version mismatch: ${info.native}`); const source = fs.realpathSync(path.join(nativeDir, info.file)); - inside(project, wrapperDir); - inside(project, nativeDir); inside(nativeDir, source); if (!fs.statSync(source).isFile() || fs.statSync(source).size === 0) throw new Error(`Native binary is missing: ${info.native}`); diff --git a/examples/course-starter/.devcontainer/agent-cli/bind-native.cjs b/examples/course-starter/.devcontainer/agent-cli/bind-native.cjs index cbb49c8ed4..8779a17a23 100644 --- a/examples/course-starter/.devcontainer/agent-cli/bind-native.cjs +++ b/examples/course-starter/.devcontainer/agent-cli/bind-native.cjs @@ -73,6 +73,7 @@ function bindingPlan(project, tool, host) { const manifest = json(path.join(project, "package.json")); const lock = json(path.join(project, "package-lock.json")); const wrapperDir = fs.realpathSync(path.join(project, "node_modules", info.wrapper)); + inside(project, wrapperDir); const wrapper = json(path.join(wrapperDir, "package.json")); const expected = manifest.dependencies?.[info.wrapper]; if (!expected || wrapper.name !== info.wrapper || wrapper.version !== expected) @@ -87,12 +88,11 @@ function bindingPlan(project, tool, host) { ) throw new Error(`Native package is absent from the locked graph: ${info.native}`); const nativeDir = fs.realpathSync(path.join(project, "node_modules", info.native)); + inside(project, nativeDir); const native = json(path.join(nativeDir, "package.json")); if (native.name !== info.native || native.version !== expected) throw new Error(`Native package version mismatch: ${info.native}`); const source = fs.realpathSync(path.join(nativeDir, info.file)); - inside(project, wrapperDir); - inside(project, nativeDir); inside(nativeDir, source); if (!fs.statSync(source).isFile() || fs.statSync(source).size === 0) throw new Error(`Native binary is missing: ${info.native}`); diff --git a/scripts/code-toolchains/bind-native.cjs b/scripts/code-toolchains/bind-native.cjs index cbb49c8ed4..8779a17a23 100644 --- a/scripts/code-toolchains/bind-native.cjs +++ b/scripts/code-toolchains/bind-native.cjs @@ -73,6 +73,7 @@ function bindingPlan(project, tool, host) { const manifest = json(path.join(project, "package.json")); const lock = json(path.join(project, "package-lock.json")); const wrapperDir = fs.realpathSync(path.join(project, "node_modules", info.wrapper)); + inside(project, wrapperDir); const wrapper = json(path.join(wrapperDir, "package.json")); const expected = manifest.dependencies?.[info.wrapper]; if (!expected || wrapper.name !== info.wrapper || wrapper.version !== expected) @@ -87,12 +88,11 @@ function bindingPlan(project, tool, host) { ) throw new Error(`Native package is absent from the locked graph: ${info.native}`); const nativeDir = fs.realpathSync(path.join(project, "node_modules", info.native)); + inside(project, nativeDir); const native = json(path.join(nativeDir, "package.json")); if (native.name !== info.native || native.version !== expected) throw new Error(`Native package version mismatch: ${info.native}`); const source = fs.realpathSync(path.join(nativeDir, info.file)); - inside(project, wrapperDir); - inside(project, nativeDir); inside(nativeDir, source); if (!fs.statSync(source).isFile() || fs.statSync(source).size === 0) throw new Error(`Native binary is missing: ${info.native}`); From ad64a7d255f856319845fd38944346f281e4a77e Mon Sep 17 00:00:00 2001 From: Mohammad Lareb Zafar Date: Wed, 18 Nov 2026 20:34:54 +0530 Subject: [PATCH 08/22] Prepare release 1.3.0 from current main (#845) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ### Changelog category (leave one): - Not for changelog (changelog entry is not required) ### Why Reconcile the existing release preparation with the merged source through the preparation branch's required pull-request workflow. The resulting tree retains main's source, generated clients and documentation together with the release version pins and two test-isolation repairs. ### Scope and risk This forward merge includes main through #839. Relative to that main snapshot, 22 version paths set the release pins: the server, SDKs, frontend, root packages and skills use 1.3.0; the chart uses 0.3.0 with appVersion 1.3.0; the paired coding-agent plugins use 1.2.30 and require server 1.3.0. Two existing test files also isolate their clock and marked request context. The clock fixture replaces only the gateway module dependency, and the mirror-failure test restores its prior request-work context through the existing binding helper. Production freshness and required-tail refusals remain unchanged. Every other file and mode matches that main snapshot. The existing preparation branch and its history are retained. The release pull request into main follows after this protected update lands. A release candidate, its soak and final publication remain separate steps. ### Compatibility, rollout and rollback - Wire and operator changes inherited from the included features are listed in the release notes below. The version reconciliation adds no wire operation, schema migration, feature activation or default setting. - Keep mirrored-source creation, query history, gap drafting and independent source push disabled unless their documented activation requirements are met. Native analyst provisioning and ordinary-event compatibility require their supported runtime proof. - Final composition, generated notes, plugin versions and every required check must be reconciled again before the release pull request merges. Version collisions must be resolved against the versions actually merged on main. - Rolling upgrades and rollback retain the data, accounting, erasure and protection requirements in the release notes. No tag or publication is performed by this update. ### Tests - `prepare.py check 1.3.0`, `prepare.py check-chart 1.3.0` and `scripts.codegen.agent_plugin_sync --check` pass. - The included version checkpoint passed 108 focused release-version and release-preparation checks and all eight Node plugin server-version checks. Full local suites were not run. - The combined focused regression passes all 44 checks, including mirror serialization followed by consumer-event emission, the bearer-cache module and both model-policy denial controls. The two source repairs also retain their diagnosed failing reproductions. - Fresh generated notes use this complete source and history. The generated wire appendix is retained verbatim in the curated notes. - Full unit, integration, coverage, schema, SDK, frontend, plugin and security checks run in remote CI and must pass on this head and its tested merge composition. - Internal independent whole-source and public-content review runs alongside CI. ### AI assistance in the code (leave one; writing this description with AI is fine): - AI-generated: Codex reconciled the merge, checked source provenance, incorporated the published test-isolation repairs and prepared the version pins and release notes. - [x] I can explain every authored change and its interaction with the included source. ### Checklist - [x] Commits are signed off. - [x] Version and chart checks pass; both plugins and their minimum server version agree. - [x] Non-version content matches the included main snapshot except the two published, focused-tested isolation repairs. - [ ] Fresh independent whole-source and complete public-body review reports no findings or nits. - [ ] Every applicable remote CI check passes for the exact tested composition. - [ ] The protected branch's actual merge requirements are satisfied. - [ ] Concurrent plugin versions and current main are reconciled before the final release merge. ## Release notes for v1.3.0 ### New features - Framework integrations provide retrievers, memory stores, toolsets, conversation sessions and native storage through the Python and TypeScript SDKs. Python extras include `langchain`, `llamaindex`, `openai-agents`, `crewai`, `autogen`, `pydantic-ai`, `ag2`, `agent-framework`, `claude-memory`, `google-adk`, `haystack`, `pipecat` and `agno`. TypeScript integrations use optional peers and package subpaths. Install only the dependencies your application uses. (#607, #609, #650, #653, #655, #658, #661, #663, #666, #696, #729, #736, #737, #750, #765, #766, #779) - Native file-tree memory tools create, view, edit, delete and rename documents shared across both SDKs. Python uses the `claude-memory` extra; TypeScript uses the matching integration subpath. A store groups files within a namespace and is not an authorization boundary: private user trees require separate namespaces. (#736) - Native TypeScript memory storage persists threads, messages and resource working memory. Construct one `LoomMemoryStorage` per canonical user resource. Writes clear default expiry; retention, erasure, refusal and deletion policies still apply. `memory.set` accepts `if_match_sha256="absent"` for conditional first creation under a concrete identity. An older server refuses that condition rather than writing unconditionally. (#779) - The Python and TypeScript `LoomSession` implementations persist conversation history. Processes with the same language, agent, user and session resume the same history. (#737) - Separate workflow and plugin packages expose AI memory, remember, recall and knowledge-search tools for applications configured with a Loom endpoint and scoped token. Their publication and catalog acceptance are separate from the SDK release. (#754, #763) - `LOOM_LLM_PROVIDER=local` runs model jobs against a chat-completions server you operate. `LOOM_ASSISTANT_PROVIDER=local` does the same for the assistant and requires `LOOM_ASSISTANT_MODEL`. The installer can discover a local model server; `LOOM_LOCAL_MODELS=ollama` selects that setup without a prompt. (#634) - `knowledge.gaps.list` and the Library show questions that repeated searches could not answer. Recording is off by default through `LOOM_KNOWLEDGE_GAPS_ENABLED` and requires capture permission. (#598) - `knowledge.source.parse_links` identifies pasted links before registration. Source registration accepts item lists and file-kind filters, while `knowledge.source.update` adds or removes source items without recreating the source. The CLI supports `--link`. (#562) - `knowledge.list` accepts several `namespaces`. The Library's **All documents** view lists documents from every readable namespace and collection; **Everywhere** expands a collection search to every readable place. (#615, #686) - `knowledge.move` relocates documents with their chunks, vectors, originals and tables. The Library offers **Move to…**, drag destinations and **Add to collection…**, with a confirmation explaining relocation and sharing. (#672, #734, #772) - Uploading a folder preserves its nested structure as collections. The Library shows collection trees, document counts, folder chips and sharing information. Empty writable collections accept dropped files and folders. (#525, #613, #680, #771, #772) - Ask AI opens beside the page on a wide screen, over it on a narrow one and as a sheet on a phone. Search can answer a question in place and continue the same conversation in chat. A deployment without an assistant URL retains Loom's own reads without chat controls. (#580, #596) - Code answers include memories linked to their top files, with stale-code status and the commit at which the code changed. `include_lessons: false` or `code_result_lessons` disables these lessons. (#638, #659) - `memory.definitions.list` reports governed definitions and lapse reasons. `memory.search` gives an exact term or alias a governed-definition leg and reports its outcome. (#679, #725) - Operator routes support the first cell's attach sequence. A later cell registers only after the first serves; `loom cell remove` deletes an unattached cell with no placements. (#681) - Additional extension manifests, experimental CLI hooks and team marketplace configuration make Loom available to more coding clients. See the integration documentation for each client's installation and tested status. (#594, #642, #694, #730) - Admins can draft definitions from eligible search gaps or an opt-in query-history source, then review and publish them from the learnings queue. Query-history credentials are sealed; the model sees normalized SQL, which still contains identifiers. Distinct source accounts do not establish distinct people or anonymity. Drafts and supporting evidence remain private to namespace admins until publication. (#768) - `loom_search` and `search.query` include readable tracker issues and pull requests for ordinary questions, with namespace citations. Scoped defect reports keep the duplicate-check verdict, including a successful empty result. (#773) - The Helm chart exposes an optional private cell identity listener through a ClusterIP Service using `cellProbe.port`. The default zero keeps the listener disabled. (#806) - Named users can have separate rolling-24-hour cost caps within a namespace, with threshold warnings sent to an existing namespace-owned task inbox. The user cap does not raise the namespace ceiling; concurrent calls can exceed these soft caps. (#777) - Experimental source push setup accepts provider notifications as hints to request normal document-source syncs. Push is off by default; polling remains the recovery path. Notifications cannot write document content or widen access. (#784) - `loom tracker-feed` maintains GitHub issues, pull requests and comments in a team-owned ClickHouse tracker record. Contract views apply observed repository visibility and hide content when the observation expires. Setup requires a dedicated record, separate writer and reader credentials, allowlisted repositories and an operator-scheduled feed. (#786) ### Improvements and fixes - New installs verify a memory write/read round trip, offer to connect detected coding clients and open the dashboard where supported. `LOOM_CONNECT` controls client setup and `LOOM_NO_OPEN=1` suppresses the browser. Port conflicts stop installation before pulling or starting containers; pull errors point to proxy settings. (#574, #583) - SDK memory adapters honor the calibrated abstention floor. Results above the full-value threshold use stored clips up to 1,200 characters, and `loom_recall` keeps valid JSON by omitting whole lower-ranked results when its size bound is reached. Explicit `defer=False` extracts inline. (#643, #647, #664) - Framework context providers reject padded user ids; the corresponding optional dependency stays within its tested minor series. Exact memory deletion requires a server response containing the writer field; older responses return no deletion id. (#696, #746) - On single-user installs, HTTP requests may omit their identity where supported. Writes use agent `http`, and searches read every agent; an explicit agent `"-"` keeps its meaning. Python `Agent()` and `SyncAgent()` support omitted identity. (#576, #595) - Memory writes with a user compare against that user's rows and namespace pins. A restatement under a different key cannot merge into another user's row. (#701) - Namespace erasure includes promoted shared rows. Redaction scrubs shared copies, and promotion or demotion invalidates cached answers and advances the write mark across replicas. (#572, #684, #697) - Definition keys identify their own rows: conflict resolution cannot merge different keys. Shared definitions with a sensitive or deleted source stay out of search. (#656, #685) - Linked-code memories whose definitions moved can follow those definitions across larger changes, within the documented bounds. Changed, unresolved or removed code lowers a memory by three search places by default rather than excluding it. (#612, #635) - Document source sync limits new documents through `LOOM_KNOWLEDGE_SOURCE_MAX_DOCUMENTS` while still updating or retiring held documents. Cleanup has its own live per-pass bound, `LOOM_KNOWLEDGE_SOURCE_RETIRE_DOCUMENTS_PER_PASS`, default 40. Metadata edits survive sync until the source file changes. (#662, #683, #791) - Namespaces matching `acl-` followed by 24 hexadecimal digits are reserved for permission-aware source mirrors and excluded from ordinary requests, org-wide reads and exports. Mirror creation remains disabled; its additive schema and erasure coverage are included. (#665, #670, #678, #778) - Dashboard actions remain visible with their required role. Namespace and audit labels explain what they show. Source-list errors include a request id and Retry; run details copy complete ids. Standard control keys remain, while application-specific shortcuts and their hints are removed. (#551, #589, #602, #649, #698, #699) - Coding-agent hooks launch Node directly, match temporary recall filenames literally and avoid running Python merely to locate pytest. Plugin 1.2.30 warns when its Loom server is older than 1.3.0. (#566, #573, #638, #733) - MCP descriptions use callable tool names and explain how to reach unlisted operations through `loom_op`. The readonly toolset also restricts implicit `loom_op` routing. Context instructions request an initial task pack when hooks have not supplied it. (#570, #645) - The CLI's commented-settings merge preserves unrelated settings and prints a manual entry when it cannot merge. Re-run the relevant client installation command to replace an obsolete client configuration. (#740) - Indexing comment-heavy template strings and normalizing SDK URL/key-prefix slashes take linear time. Finished dependency-install tunnels release their slots after the configured half-close timeout. (#564, #565, #579) - Under Postgres memory authority, `memory.update` resolves a committed key before its ClickHouse projection appears. (#781) - The analyst probe checks its signed key canary before trusting a newer catalog version. The signed key canary remains mandatory. (#793) - Translation checks distinguish literal comparisons from complete HTML markup. Shell launchers and skill files retain their committed LF bytes during checkout. (#767, #792) - Checked document reads require current source permissions, reader identity and the exact content version before serving mirrored content. Public mirrored-source creation remains disabled until the fleet, request and session protections are complete. (#799) - Checked document requests keep private diagnostics and derived activity behind their privacy boundary and finish required accounting before publishing content. Loss of the selected source/version proof refuses the complete response frame; after headers, the unchecked body is aborted. It does not rerender a replacement. Public mirrored-source creation remains disabled. (#803) - Deployment session protection survives process switches and tenant erasure. Unverifiable protection state refuses session-content operations before their content is processed. (#819) - Plugin 1.2.30 explains repository tags for code-related facts while keeping unrelated facts outside that repository filter. (#787) - Available machine translations accompany canonical English in Simplified Chinese, Japanese, Korean, Brazilian Portuguese and Spanish. Documentation navigation retains the selected language. Translation maintenance preserves completed units across English edits, bounds refinement requests and checks technical literals before publishing reviewed content. (#764, #794, #797, #824, #829, #830, #833, #838) - Guides explain persistent coding-agent memory, code-linked memories, metadata-first retrieval and the difference between fake-model test output and meaningful answers. The code-linked memory guide points to the packaged MCP checks. (#726, #727, #807, #815, #816, #818, #831) - The desktop installer opens the dashboard when its terminal closes before the browser helper starts. (#822) - Assistant answers mark mirrored-source access before output and keep mirror admission fixed for the answer's lifetime. Shared HTTP and MCP success/error responses preserve the privacy flag. Python and TypeScript assistant stream clients reject incomplete answers. Public mirrored-source creation remains disabled. (#835) - Recall Lab reuses score rows while a draft query changes and keeps immediate clearing. (#786) ### Compatibility and deployment - A Postgres-backed process reads cell state before serving. A process without `LOOM_CELL` refuses an enforced or partial cell; a failed initial Postgres read fails boot, except while migrations are pending, when the process remains unready. (#586) - An enforced cell checks tenancy on writes, including the tenancy row itself. `LOOM_PG_DSN` must connect directly to Postgres. Older pods on an already prepared later cell must be rolled in one step once migrating boot installs the triggers. `loom doctor` detects missing, altered or disabled triggers and lost session markers. (#599, #676) - CLI writes check the deployment and require the grants in upgrade step 15. Without `LOOM_CELL`, they refuse a cell past recording. Commands configured for a cell refuse another cell's stores; revocations that cannot restore access retain their documented outage behavior. New org names are bounded at 2048 UTF-8 bytes. (#668, #671, #673) - `memory.promote` for a definition requires `approved_sha256` and promotes the namespace-wide row by the token's actor. Sensitive values, empty terms, conflicting terms or aliases and the shared-definition cap refuse promotion. (#667) - Native HTTPS uses `LOOM_TLS_CERT_FILE` and `LOOM_TLS_KEY_FILE`, with certificate reload in each web process. The chart's `tls.secretName` configures the certificate mount and HTTPS probes. The image launcher refuses `UVICORN_*` variables; remove those variables before upgrading and use the documented Loom settings. (#756) - Each metric retains up to `otel_metrics_cardinality_limit` series per process, default 20,000; additional attribute sets accumulate in an overflow series. (#648) - Query-history and gap drafting introduce private definition candidates. Before downgrading to an older reader, use a maintenance window: disable both drafting features, quiesce drafting/review/registration/worker traffic, drain queued/model work, settle uncertain sends and retained leases, remove all versions of private candidate kinds and all registrations, and verify zero on every readable storage replica. Keep private producers disabled throughout the downgrade. Published definitions retain their existing lifecycle. (#768) - `memory.search` and `memory.search_trace` accept at most 64 raw `entity_filter` entries, including repeated names. Canonical alias expansion is bounded at 256 names. Entity-summary retrieval separately bounds the case-insensitive distinct union of the canonical filter, query handles and known vocabulary tokens at 256 names. Overflow of either 256-name bound returns 422 `VECTOR_INPUT_TOO_LARGE` through retries, `memory.ask` widening and composed search, without a partial ranking. Narrow the query or filter before retrying. (#800, #808) - `POST /v1/me/personal_tokens.create` issues the explicit personal-agent token kind only from the person's own primary sign-in session. The optional signed `reads_as_creator` claim defaults to false and ordinary delegation does not copy it. No operation-transport RPC is added by this route. (#799) - Source membership and listing evidence must be present and current for checked reads. `LOOM_KNOWLEDGE_SOURCE_ACL_STALE_SECONDS` defaults to 3600; no backfill infers domain membership from an email address. Before rolling back after mirrored writes, stop those writers, settle outstanding work and follow the documented mirror erasure and telemetry sweep. Keep mirrored creation disabled on an incomplete fleet. (#799) - Ordinary event inserts and signed, namespace-scoped analysis remain available across serving builds. `agent_events` retains ordinary columns and values; a permanent `ordinary_events_only` CHECK rejects marked events and reserved mirror namespaces. Marked requests and mirror workers write the separate `agent_events_private` store, which has no analyst grant or analyst-visible physical metadata. (#825) - The signed `analysis_agent_events` catalog view unions ordinary and private events and masks protected fields before caller predicates and grouping. Ordinary `agent_events` reads retain their signed namespace scope; the analyst cannot read the private table. Trusted cost, budget and history-policy reads cover both stores, and user erasure scrubs both through `agent_events.scrub`. Private events use the ordinary ledger's retention and tiering policy. (#803, #825) - Analyst administration uses `loom ch-setup --apply-analyst-sql` with explicitly configured existing access-management credentials. It applies only the analyst boundary under the live proof and lease, without rebuilding reader credentials. `--print-analyst-sql` refuses with a nonzero result and prints no SQL or secrets. General `--print-sql` remains available for database and reader preparation; print and apply modes are mutually exclusive. (#825) - Session-content operations require exactly one `X-Loom-Session-Protection: v1` header once deployment protection is set. Missing, repeated or unknown declarations grant no promise. The gate includes dual-use `memory.set`, `memory.bulk_set`, `memory.search` and code/context operations used by automatic clients. Missing protection or unverifiable deployment state returns nonretryable 409 `SESSION_PROTECTION_REQUIRED`. HTTP checks before reading the body; MCP checks before content validation, identity defaults, replay or implicit session runs. (#819) - The optional `LOOM_KNOWLEDGE_MIRRORED_SOURCES_ENABLED` setting now exists, defaults false and requires restart. Setting it true persists a deployment-wide latch before startup admits clients or workers; the heartbeat repairs that protection. Setting it false does not clear the latch. With the switch false, an undeclared client still needs a fresh service-principal Keeper absence proof; a declared client does not exercise that default path. This setting does not make public mirrored-source creation available. (#819) - Named-user budget status withholds exact spend and its percentage except for a verified platform admin without namespace-role restrictions. Admission and routing still count all spend, including marked requests. User warnings always withhold exact spend, including webhooks and operator-triggered delivery. Namespace and org totals retain their existing numeric form. (#777) - Before a downgrade after budget warnings were produced, stop request/background budget-check producers and status polling, drain scheduled deliveries, settle uncertain writes and writer leases, then remove only `budget.warning` events and verify completion and zero warnings on every storage replica. Save the global and namespace policies first: older namespace writes reset the new cap/inbox fields. Keep the feature disabled on older builds and reapply saved policy only after the full fleet supports it again. (#777) - Tracker feeds support a single self-hosted server or shared storage with `ReplacingMergeTree` or `SharedReplacingMergeTree`; self-hosted replicated tables are refused. Feed connections retain the deployment's storage-authority, organization and cell checks. The dedicated writer must have verified limited direct and effective grants and remain separate from the serving reader. (#786) - Assistant mirror admission uses a separate strict server-issued `answer_mirrors` Boolean. Missing admission is false, and mirror discovery also requires the caller's separate `session_protection` promise. An older verifier accepting the signed claim does not enforce it. Keep mirrored-source creation disabled until every serving build and consumer enforces the documented privacy protocol. No migration or backfill is added by this protocol change. (#835) ### Operator steps 1. Follow [the upgrade checklist](https://clickhouse.github.io/loom/operations/upgrades/) and apply the additive migrations through the normal migrating boot. This release's cell and shared-memory changes have additional steps below. 2. After every older replica is gone, follow upgrade step 14 to identify promoted rows left by earlier namespace erasures. Use the ledger's census cutoff and namespace when applying the documented tombstone or purge mutation, including hidden versions. Only a namespace-list erasure authorizes a purge. Erasures beyond the ledger's retention cannot be identified by that query. (#572) 3. Run `loom secrets reseal` with this build so document-source secrets and any existing source-push registry secrets are covered. No synthetic push setup is needed for an empty registry. (#562, #784) 4. Before migrating reserved mirror namespaces, resolve any migration refusal with the preceding build: erase the affected namespace contents, remove its code repository and delete the namespace, then retry. (#665) 5. Apply upgrade step 15's CLI grants, including ClickHouse `SELECT` on `loom.storage_authority`, the Postgres cell-state grants, connection limit and bucket settings. Complete step 16 before first-cell attach. (#668, #673) 6. Upgrade every router replica before attaching cells or upgrading cell processes. The cell processes read router state on each heartbeat; older routers do not have the required per-replica cache. Validate readiness and session tenancy markers after rollout. (#681, #693) 7. Keep the document-source limit at or below 50,000 while any older replica serves. After rollout, the live setting may be raised. (#662) 8. After all older replicas are gone, have an admin promote each existing shared definition again so its approved hash and token-stamped actor are recorded. The new live cap `memory_shared_definitions_max` defaults to 500. (#667) 9. For local assistant models, configure the model and endpoint, mount the assistant secret and add explicit network-policy egress to the model server's port. (#634) 10. Before enabling TLS, mount a certificate/key pair and change the upstream proxy to HTTPS in the same deployment window. Deployments using launcher-level `UVICORN_*` variables must remove them even when TLS remains off. (#756) 11. A desktop-launched coding client must find Node on its startup `PATH`; configure the client's environment when Node is installed only through a version manager. Upgrade Loom to 1.3.0 before relying on plugin 1.2.30's new server calls. (#573, #638) 12. Install an SDK extra or optional peer for each framework integration used. Separate plugin/community packages require their own installation and publication prerequisites; the release does not imply catalog approval. (#696, #750, #754, #763, #765, #766) 13. Before analyst provisioning, use a ClickHouse release that supplies `system.constraints`, as the pinned database release does. Missing CHECK metadata refuses the cutover. The operator must verify this on the actual database before the candidate starts. (#825) 14. Apply the additive query-history registration migration and upgrade every server and worker before registering a source or creating private candidates. `knowledge_query_history_enabled` defaults off; gap drafting also requires `knowledge_gaps_enabled`. Review the bounded read/pass/source/group/draft settings before enabling either feature. (#768) 15. For the private cell probe, configure Postgres and authentication, choose `cellProbe.port` and finish both web and worker rollouts before preparation. Use the Service origin for the probe URL. Configure this port only through the chart value, not `env`, `extraEnv`, `settingsFile` or `secrets.extra`. Set zero to disable it. (#806) 16. Apply the additive source-ACL schema before serving checked reads. Keep public mirrored creation disabled until the documented fleet, request, session and enablement protections are complete. (#799) 17. Apply migrations 103–106 in order for checked reads and marked accounting. Migration 106 pauses and waits for the three local refresh schedulers, changes their definitions and resumes them; complete the cutover on every refresh-owning replica. Existing ordinary aggregate types are preserved and prior input is not replayed. Keep mirrored creation disabled. (#799, #803) 18. Apply migration 107 before configuring named-user budgets. While any serving build is older or unknown, keep `LOOM_DEFAULT_DAILY_USER_COST_CAP_USD=0`, every namespace's `daily_user_cost_cap_usd=0` and `budget_alert_inbox=''`. The last value disables warning configuration; it does not require emptying an inbox and does not drain existing sends. The global user cap and `LOOM_COST_BUDGET_ALERT_SHARE` are live; the share defaults to 0.8. Do not rely on user caps during overlap. (#777) 19. Apply migration 108 and preserve its deployment protection state. Keep the mirrored-source switch and both private-drafting switches off on every server and worker through the mixed fleet. Verify ordinary undeclared client calls through the supported route, including the required Keeper proof. Missing metadata, backend identity changes or uncertain proof writes refuse admission; adding a promise header is not a repair. Only the documented complete mirror cleanup can clear protection, last; tenant erasure and a local switch change cannot. (#819) 20. Apply migration 109. Keep `LOOM_KNOWLEDGE_SOURCE_PUSH_ENABLED=false` unless opting into source push; this switch is separate from mirrored-source protection. Later setup needs a fleet supporting the registry's erasure, an explicit HTTPS `LOOM_PUBLIC_BASE_URL` origin and provider-specific confirmation. Source credential/item changes retire setup. Before rollback after use, disable push and complete the documented fenced registry cleanup, including historical versions, while preserving unrelated namespace data. (#784) 21. Documentation publication uses the existing site workflow. Automatic translation generation requires the documented restricted runner, initialized budget ledger and explicit cumulative allowance, which defaults to zero. This release does not configure that allowance or authorize generation. (#764) 22. Apply migration 110 after migration 109. It creates private event storage, adds the ordinary-table CHECK and updates union readers without moving, erasing or replaying existing rows or aggregate history. Complete its pause/wait/update/resume of both refresh definitions on every refresh-owning replica. Before grants, analyst provisioning verifies exact CHECK/table identities on every writer, freezes and drains the finite set of prepared INSERTs, then requires a zero contamination census. Existing contaminated rows remain untouched for explicit operator resolution. ALTER completion or client disconnection alone does not settle a prepared write. (#825) 23. `LOOM_CH_ANALYSIS_OBSERVER_URLS` is a restart-only list of additional trusted writer HTTP origins, default `[]`. The configured service origin is included and the existing service credentials are reused. Every writer UUID needs exactly one attested route. Complete native policy-catalog visibility, principal/role identity and non-replaying POST semantics are required; missing/duplicate writers, hidden metadata, redirects, HTTPS downgrade, identity drift or incomplete replies refuse provisioning. Intermediaries must preserve those semantics. Use the guarded analyst apply command for administrative setup. (#825) 24. Before an older build returns after mirrored enablement, settle outstanding writes and complete the documented mirror cleanup, including `agent_events_private`, marked receipts/audit figures and the cost rollup, before clearing deployment protection. Disabling a feature or downgrading schema alone does not establish privacy. Keep mirrored creation disabled until the separate fleet, client, restore and final erasure requirements are complete. (#803, #819, #825) 25. To opt into tracker feeds, create the dedicated record with separate writer/reader credentials, set the tracker organization, initialize the record and register its read-only contract views, then configure and schedule each allowlisted repository. Attest the supplied token's read-only permissions: a successful API read does not certify its grants. Renew installation tokens externally and configure each replacement before expiry. (#786) 26. Tracker visibility observations expire after 15 minutes and are not an instant permission mirror. Turns are bounded to 120 seconds, 100 items per page and 2–100 pages per stream. Incremental polling does not detect deletions. Stop every writer before erasing raw rows, comments and checkpoints or retiring a repository. Namespace deletion removes Loom's derived state and grants, not the external record or its backups. Rollback stops the scheduled writer; observation expiry hides serving rows without erasing the record. (#786) ### Release artifacts Release assets include the installer, stack bundle, SDK packages, coding-agent plugin archives and agent setup contract. Each carries a `.sigstore.json` bundle for `cosign verify-blob`; verify the certificate identity for this release's `release.yml` tag and the workflow OIDC issuer. Older assets without a bundle cannot pass this file-signature check. Both container images also carry signatures. (#689) ### Maintenance checks Translation validation indexes protected ranges and table rows to avoid repeated scans on large reference pages. Request boundaries, labels and source offsets are preserved. (#834) Original-unit reconciliation permits correction of a faulty completed whole-page translation when the prepared English input is unchanged. Existing request bounds and changed-input replacement restrictions remain. (#839) Tracker reply parsing gains regression coverage, and CI action dependencies are updated. Additional tests cover budget bounds, memory-history diffs, audit privacy identifiers and port allocation. (#675, #705, #674, #700, #821, #812) ### What changed for clients since v1.2.0 373 operations served (was 361); ops +12 −0; request fields +22 −0; response fields +25 −0. #### New operations - `knowledge.gaps.draft` — role ADMIN, budget 30000 ms, MCP extended; request fields: gap_id, namespace, org - `knowledge.gaps.list` — role ADMIN, budget 300 ms, MCP extended; request fields: limit, namespace, org - `knowledge.move` — role WRITER, budget 8000 ms, MCP extended; request fields: namespace, org, source_uris, to_namespace - `knowledge.query_history.add` — role ADMIN, budget 30000 ms, MCP extended; request fields: cluster, databases, host, name, namespace, org, password, port, secure, user - `knowledge.query_history.list` — role ADMIN, budget 250 ms, MCP extended; request fields: fields, limit, namespace, org - `knowledge.query_history.remove` — role ADMIN, budget 1000 ms, MCP extended; request fields: name, namespace, org - `knowledge.source.parse_links` — role VIEWER, budget 50 ms, MCP extended; request fields: links, namespace, org - `knowledge.source.push_configure` — role ADMIN, budget 60000 ms, MCP extended; request fields: agent, enabled, name, namespace, org, session_id, user_id - `knowledge.source.push_confirm` — role ADMIN, budget 1000 ms, MCP extended; request fields: challenge_fingerprint, generation, name, namespace, org, signing_secret - `knowledge.source.push_status` — role ADMIN, budget 1000 ms, MCP extended; request fields: name, namespace, org, reveal_challenge - `knowledge.source.update` — role ADMIN, budget 60000 ms, MCP extended; request fields: add_items, add_links, include, name, namespace, org, remove_items, remove_links - `memory.definitions.list` — role ADMIN, budget 400 ms, MCP extended; request fields: namespace, org #### Changed operations - `assistant.ask`: response +`mirrored` - `code.callees`: request +`include_lessons`, `lesson_namespaces`; response +`lessons`, `lessons_left_out` - `code.callers`: request +`include_lessons`, `lesson_namespaces`; response +`lessons`, `lessons_left_out` - `code.context_pack`: request +`include_lessons`, `lesson_namespaces`; response +`lessons`, `lessons_left_out` - `code.impact`: request +`include_lessons`, `lesson_namespaces`; response +`lessons`, `lessons_left_out` - `code.outline`: request +`include_lessons`, `lesson_namespaces`; response +`lessons`, `lessons_left_out` - `code.search`: request +`include_lessons`, `lesson_namespaces`; response +`lessons`, `lessons_left_out` - `collection.list`: request +`include_document_counts` - `cost.budget_status`: request +`user_id`; response +`namespace_over_cap`, `user_id` - `knowledge.list`: request +`namespaces` - `knowledge.source.add`: request +`include`, `items`, `links`; response +`include`, `items`; budget_p99_ms 30000 → 60000 - `knowledge.source.check`: response +`checked`, `sampled` - `knowledge.source.inspect`: response +`include`, `items` - `knowledge.synthesize`: request +`user_id` - `memory.promote`: request +`approved_sha256`; response +`ignored_args` - `memory.search`: response +`term_leg` - `namespace.get`: response +`budget_alert_inbox`, `daily_user_cost_cap_usd` - `namespace.register`: request +`budget_alert_inbox`, `daily_user_cost_cap_usd` ### Other client changes - General search's optional `tracker` response section can carry `mode="search"`, `namespaces`, `namespace_limit` and cited `results`. Existing duplicate verdicts keep their shape. (#773) - `memory.search` hits include `agent`, identifying the writer when row identity is available; otherwise it is empty. (#696) - `collection.list` entries include nullable `document_count`. It is null unless `include_document_counts` is requested and counts documents directly in the collection. (#771) - Learning entries include `source_resource_id`, defaulting to an empty string. `learnings.review` promotes private definition candidates only to `memory`. (#768) - `cost.budget_status` user mode requires a namespace. `spent_24h_usd` is nullable, and `pct_of_cap` is null when user spend is withheld. `cap_source` adds `namespace_user` and `global_user`; nullable `namespace_over_cap` reports the independent namespace ceiling. Namespace get/list entries expose `daily_user_cost_cap_usd` and `budget_alert_inbox`. A positive namespace user cap overrides the global default; zero inherits, and zero at both tiers disables it. (#777) - `knowledge.synthesize` accepts `user_id`, default `'-'`; the Python convenience method forwards its optional user id. Transport user pins take precedence. Named-user caps cover supported synthesis and query expansion; unattributed work remains namespace-only. (#777) - Budget warnings arrive asynchronously on a later point check or status poll after the configured share is reached; there is no discovery scan. Repeated observations deduplicate within a UTC day for the same scope, inbox, cap and share. User warning payloads set `spent_24h_usd` to null for every recipient. Polling and watch streams filter warning user/session scope before pagination; ordinary task events retain inbox visibility. (#777) - Assistant answer tokens carry their caller's strict Boolean `session_protection` claim. Descendant answers cannot override it with a transport header, and ordinary delegation does not inherit it. Clients promising protection must stop automatic session-content capture after a mirrored read and preserve that state across child/resumed sessions. (#819) - Multi-entry MCP batches replace every response-bearing marked entry, including denied or empty entries, with `INVALID_REQUEST` and `Send this request individually`. Notifications remain silent. Single calls and one-entry arrays retain checked reads. (#803) - Protected history makes enforcing policy rules evaluate potentially matching marked participation as unknown before success/argument filters, unresolved references or negation; it can refuse reads as well as writes. `policy.check` reports `protected history unavailable` with null protected leaf values. Shadow policies remain non-enforcing. (#803) - Marked cost is disclosed only to a verified unrestricted platform admin or authorized namespace/whole-day totals without fine-grained filters. Fine-grained marked cost is withheld; marked-only latency has no ordinary samples and returns zero latency values. This does not disable internal budget checks. (#803) - Source-push setup operations are experimental, namespace-admin only and non-idempotent, including status. `push_status` reveals a pending verification token only with `reveal_challenge=true`; ordinary inspection, audit and idempotency replay omit it. The response's `enabled` reports the global switch, while `status` reports source setup state. (#784) - Provider notifications use the separate non-RPC `POST /hooks/knowledge/{namespace}/{source_id}/{generation}?org=` route with provider proof, rather than an RPC bearer token. Bodies are bounded at 65,536 bytes. A 200 acknowledgement can represent an early synchronization notification and does not prove that work was requested or content ingested. Drive uses channel-token verification rather than signed delivery; other supported providers require their documented HMAC and identity checks. (#784) - `assistant.ask` adds optional response field `mirrored`, default false. Marked chat output begins with `mirrored: true`; marked SSE begins with `data: {"mirrored":true}` before answer text. HTTP/MCP success and error output retains the mark after serialization and protocol unwrapping; MCP structured and JSON text results preserve it, and a marked search summary follows a first JSON marker block. (#835) - The server fixes `answer_mirrors` before spend or model work from active mirrored registrations in the authorized namespace. Active registrations keep the answer marked even when ACL checks exclude every private row. Caller fields, headers, token-mint endpoints and CLI flags cannot supply admission. An initially ordinary answer cannot gain a mirror leg after source activation. Ordinary delegated children omit both `answer_mirrors` and `session_protection`; descendants cannot widen either claim with a header. Current document authorization still applies. (#835) - Incremental assistant text is provisional. A marked response retains required accounting after headers, joins producer cleanup through repeated cancellation and confirms its required private cost row before terminal completion. Failed required capture or delivery cannot complete successfully. Whole responses and checked source frames retain accounting before publication. (#835) - Python and TypeScript assistant streams require `[DONE]` before returning a completed answer. Incomplete EOF fails; text after `[DONE]` is ignored while later transport errors still propagate. Stream completion does not qualify durable automatic capture or privacy state across child/resumed sessions; clients promising protection must satisfy the separate session contract. (#835) Signed-off-by: zlareb1 --- docs/architecture/assistant.md | 39 + docs/architecture/document-sources.md | 12 + docs/architecture/github-feed.md | 162 ++++ docs/features/tracker/github-feed.md | 118 +++ docs/features/tracker/overview.md | 1 + docs/reference/cli.md | 4 + docs/reference/operations/assistant.md | 1 + frontend/src/views/RecallLab.table.test.tsx | 20 + frontend/src/views/RecallLab.tsx | 30 +- .../es/docs/development/migrations.md | 151 ++++ .../features/memory/retention-and-erasure.md | 292 +++++++ i18n/.pending/es/docs/operations/postgres.md | 246 ++++++ .../ja/docs/operations/backup-and-recovery.md | 261 ++++++ .../.pending/ja/docs/operations/monitoring.md | 323 +++++++ i18n/.pending/ja/docs/reference/cli.md | 302 +++++++ i18n/.pending/ko/docs/reference/cli.md | 305 +++++++ .../docs/architecture/system-overview.md | 494 +++++++++++ .../docs/operations/code-index-operations.md | 817 ++++++++++++++++++ i18n/.pending/zh-CN/docs/concepts/memory.md | 425 +++++++++ .../docs/features/namespaces-and-sharing.md | 271 ++++++ .../docs/features/observability/telemetry.md | 326 +++++++ .../docs/features/tasks-and-decisions.md | 415 +++++++++ .../zh-CN/docs/operations/monitoring.md | 323 +++++++ i18n/es/docs/architecture/agno-adapter.md | 37 + .../docs/architecture/google-adk-adapter.md | 26 + i18n/es/docs/architecture/haystack-adapter.md | 27 + .../es/docs/getting-started/whats-included.md | 80 ++ .../reference/operations/working_memory.md | 179 ++++ i18n/ja/docs/architecture/agno-adapter.md | 25 + .../docs/architecture/google-adk-adapter.md | 26 + i18n/ja/docs/architecture/haystack-adapter.md | 27 + .../docs/features/observability/telemetry.md | 326 +++++++ .../docs/features/tracker/record-contract.md | 286 ++++++ .../docs/operations/code-index-operations.md | 422 +++++++++ i18n/ja/docs/operations/sso.md | 354 ++++++++ i18n/ko/docs/architecture/agno-adapter.md | 25 + i18n/ko/docs/architecture/cells.md | 354 ++++++++ .../architecture/code-index-architecture.md | 348 ++++++++ .../docs/architecture/failure-and-recovery.md | 445 ++++++++++ .../docs/architecture/google-adk-adapter.md | 26 + i18n/ko/docs/architecture/haystack-adapter.md | 27 + .../ko/docs/architecture/server-layout.md | 0 .../ko/docs/development/adding-a-worker.md | 0 .../development/adding-language-support.md | 0 .../features/code-index/history-and-prs.md | 0 i18n/ko/docs/operations/monitoring.md | 328 +++++++ .../reference/operations/working_memory.md | 179 ++++ .../code-intelligence-by-language.md | 34 +- i18n/pt-BR/docs/architecture/agno-adapter.md | 41 + .../docs/architecture/google-adk-adapter.md | 50 ++ .../docs/architecture/haystack-adapter.md | 27 + i18n/zh-CN/docs/architecture/agno-adapter.md | 25 + .../docs/architecture/google-adk-adapter.md | 26 + .../docs/architecture/haystack-adapter.md | 27 + llms.txt | 2 + scripts/i18n/lifecycle.py | 24 +- scripts/i18n/reconcile.py | 1 + sdk/python/loom/assistant.py | 10 +- sdk/python/loom/ops.py | 1 + sdk/typescript/src/assistant.test.ts | 25 + sdk/typescript/src/assistant.ts | 8 +- sdk/typescript/src/generated/ops.ts | 2 + server/assistant/api/models.py | 6 + server/assistant/app/ask.py | 1 + server/assistant/app/bridge.py | 128 ++- server/assistant/app/routes.py | 56 +- server/auth/delegation.py | 2 + server/auth/jwt.py | 13 +- server/cli/_ch.py | 13 +- server/cli/app.py | 2 + server/cli/tracker_feed.py | 205 +++++ server/clients/github_feed.py | 93 ++ server/core/ch.py | 54 +- server/core/errors.py | 12 +- server/core/github_values.py | 28 + server/core/request_tail.py | 31 +- server/core/request_work.py | 17 + server/core/rmt_carry.py | 20 + server/knowledge/app/source_access.py | 7 + server/memory/domain/provenance.py | 1 + server/tracker/app/github_feed.py | 310 +++++++ server/tracker/domain/github_feed.py | 171 ++++ server/tracker/store/github_feed.py | 238 +++++ server/transport/arg_check.py | 4 +- server/transport/mcp_outcome.py | 84 +- tests/analyzer/cases/tracker.py | 14 + tests/analyzer/shapes.txt | 2 + tests/integration/test_github_feed.py | 295 +++++++ .../test_mirror_checked_search_http.py | 57 +- tests/unit/snapshots/cli_help.json | 21 +- tests/unit/snapshots/cli_tree.json | 527 +++++++++++ tests/unit/test_assistant_bridge.py | 222 +++++ tests/unit/test_assistant_mirror_boundary.py | 266 ++++++ tests/unit/test_external_ch.py | 110 +++ tests/unit/test_github_feed.py | 165 ++++ tests/unit/test_github_feed_app.py | 527 +++++++++++ tests/unit/test_github_feed_client.py | 112 +++ tests/unit/test_github_feed_consistency.py | 141 +++ tests/unit/test_github_feed_sql.py | 294 +++++++ tests/unit/test_github_feed_store.py | 192 ++++ tests/unit/test_i18n_lifecycle.py | 121 +++ tests/unit/test_i18n_reconcile.py | 87 ++ tests/unit/test_llm_gateway_bearer.py | 27 +- tests/unit/test_rmt_carry.py | 4 + tests/unit/test_sdk_assistant_client.py | 26 + tests/unit/test_sdk_set_coalescer.py | 14 +- .../test_session_protection_declaration.py | 7 +- tests/unit/test_tracker_feed_cli.py | 305 +++++++ 108 files changed, 14086 insertions(+), 134 deletions(-) create mode 100644 docs/architecture/github-feed.md create mode 100644 docs/features/tracker/github-feed.md create mode 100644 i18n/.pending/es/docs/development/migrations.md create mode 100644 i18n/.pending/es/docs/features/memory/retention-and-erasure.md create mode 100644 i18n/.pending/es/docs/operations/postgres.md create mode 100644 i18n/.pending/ja/docs/operations/backup-and-recovery.md create mode 100644 i18n/.pending/ja/docs/operations/monitoring.md create mode 100644 i18n/.pending/ja/docs/reference/cli.md create mode 100644 i18n/.pending/ko/docs/reference/cli.md create mode 100644 i18n/.pending/pt-BR/docs/architecture/system-overview.md create mode 100644 i18n/.pending/pt-BR/docs/operations/code-index-operations.md create mode 100644 i18n/.pending/zh-CN/docs/concepts/memory.md create mode 100644 i18n/.pending/zh-CN/docs/features/namespaces-and-sharing.md create mode 100644 i18n/.pending/zh-CN/docs/features/observability/telemetry.md create mode 100644 i18n/.pending/zh-CN/docs/features/tasks-and-decisions.md create mode 100644 i18n/.pending/zh-CN/docs/operations/monitoring.md create mode 100644 i18n/es/docs/architecture/agno-adapter.md create mode 100644 i18n/es/docs/architecture/google-adk-adapter.md create mode 100644 i18n/es/docs/architecture/haystack-adapter.md create mode 100644 i18n/es/docs/getting-started/whats-included.md create mode 100644 i18n/es/docs/reference/operations/working_memory.md create mode 100644 i18n/ja/docs/architecture/agno-adapter.md create mode 100644 i18n/ja/docs/architecture/google-adk-adapter.md create mode 100644 i18n/ja/docs/architecture/haystack-adapter.md create mode 100644 i18n/ja/docs/features/observability/telemetry.md create mode 100644 i18n/ja/docs/features/tracker/record-contract.md create mode 100644 i18n/ja/docs/operations/code-index-operations.md create mode 100644 i18n/ja/docs/operations/sso.md create mode 100644 i18n/ko/docs/architecture/agno-adapter.md create mode 100644 i18n/ko/docs/architecture/cells.md create mode 100644 i18n/ko/docs/architecture/code-index-architecture.md create mode 100644 i18n/ko/docs/architecture/failure-and-recovery.md create mode 100644 i18n/ko/docs/architecture/google-adk-adapter.md create mode 100644 i18n/ko/docs/architecture/haystack-adapter.md rename i18n/{.pending => }/ko/docs/architecture/server-layout.md (100%) rename i18n/{.pending => }/ko/docs/development/adding-a-worker.md (100%) rename i18n/{.pending => }/ko/docs/development/adding-language-support.md (100%) rename i18n/{.pending => }/ko/docs/features/code-index/history-and-prs.md (100%) create mode 100644 i18n/ko/docs/operations/monitoring.md create mode 100644 i18n/ko/docs/reference/operations/working_memory.md create mode 100644 i18n/pt-BR/docs/architecture/agno-adapter.md create mode 100644 i18n/pt-BR/docs/architecture/google-adk-adapter.md create mode 100644 i18n/pt-BR/docs/architecture/haystack-adapter.md create mode 100644 i18n/zh-CN/docs/architecture/agno-adapter.md create mode 100644 i18n/zh-CN/docs/architecture/google-adk-adapter.md create mode 100644 i18n/zh-CN/docs/architecture/haystack-adapter.md create mode 100644 server/cli/tracker_feed.py create mode 100644 server/clients/github_feed.py create mode 100644 server/core/github_values.py create mode 100644 server/tracker/app/github_feed.py create mode 100644 server/tracker/domain/github_feed.py create mode 100644 server/tracker/store/github_feed.py create mode 100644 tests/integration/test_github_feed.py create mode 100644 tests/unit/test_assistant_mirror_boundary.py create mode 100644 tests/unit/test_external_ch.py create mode 100644 tests/unit/test_github_feed.py create mode 100644 tests/unit/test_github_feed_app.py create mode 100644 tests/unit/test_github_feed_client.py create mode 100644 tests/unit/test_github_feed_consistency.py create mode 100644 tests/unit/test_github_feed_sql.py create mode 100644 tests/unit/test_github_feed_store.py create mode 100644 tests/unit/test_tracker_feed_cli.py diff --git a/docs/architecture/assistant.md b/docs/architecture/assistant.md index 1a114ae279..42e9c04111 100644 --- a/docs/architecture/assistant.md +++ b/docs/architecture/assistant.md @@ -71,6 +71,45 @@ session and components, and links verified citations into the memory and documen ## The bridge: each caller's own identity +Before checking model spend, the bridge reads the authorized namespace's public +mirrored-source registrations. Any active registration marks the complete answer, +even when its tools admit no document. The chat route sends `data: {"mirrored":true}` +as its first SSE event, or `mirrored: true` as its whole response's first field. +`assistant.ask` carries the same first field. A marked refusal carries it too. This +decision also routes the answer's cost row to private storage and suppresses public +diagnostics before subsequent model, budget or tool work. + +Marked operation results carry the same server-owned flag after their typed output is +serialized. HTTP success responses retain it before post-handler rows. MCP success +responses retain it in the outer envelope, tool result, structured content and canonical +JSON text. The search tool's prose summary follows a separate first JSON marker block, +so consuming its text blocks in order observes protection before the summary. Ordinary +unmarked results keep their existing shapes. + +The answer token keeps the caller's `session_protection` promise and a separate +`answer_mirrors` admission bit. Only an already marked answer for a declared caller +receives positive admission. Missing or false admission disables its mirror legs, +including when a source becomes active during an initially ordinary answer. Ordinary +namespace reads retain their authorization. Current ACL checks still decide each +mirrored item; the bit grants no access by itself. Ordinary delegated children omit +both claims and cannot regain mirror admission through a request header. An answer +token or any descendant cannot start another assistant answer. + +Streaming output is provisional until `[DONE]`. The response owns its required +accounting lifetime beyond HTTP headers: it closes and joins model and citation work, +captures final usage once, and confirms private cost delivery before sending `[DONE]` +or a terminal error. Disconnects join producer cleanup and required delivery before +propagating cancellation. A failed cost write cannot publish a completed answer. +Whole answers and checked tool responses retain their accounting-before-publication +boundary. Incremental text precedes final usage, so its completion boundary is the +terminal event. A streaming client must reject EOF without `[DONE]` as incomplete. + +Mirrored-source creation stays unavailable until every serving build and consumer +implements the admission, first-output marker, session and accounting boundaries. +An older verifier accepting an unknown claim does not enforce it; schema equality +does not establish this capability. The fleet and rollback requirements in +[rolling upgrades](rolling-upgrades.md) still apply. + LibreChat's agents API authenticates a LibreChat API key and runs the agent as that key's LibreChat user. The agent's tools are Loom's MCP server, and what they may read is decided by the token on each tool call, never by the LibreChat user. LibreChat v0.8.8 diff --git a/docs/architecture/document-sources.md b/docs/architecture/document-sources.md index 06b7c31086..e954ca35cd 100644 --- a/docs/architecture/document-sources.md +++ b/docs/architecture/document-sources.md @@ -613,6 +613,18 @@ their contributing proofs. A raw download owns the same required marked accounti attempt as a registered operation. Cancellation and disconnects still propagate through owned cleanup. These checks end at the server's response-send boundary. +The assistant's incremental stream has a terminal accounting boundary because final +usage is unavailable before its early text. Its server-owned first event is +`data: {"mirrored":true}` when marked. Partial text remains provisional until the +response closes and joins its producers, captures final usage and confirms its +required private cost row before `[DONE]` or a terminal error. Disconnect cleanup +retains and joins that required delivery. Whole answers and checked source frames +keep the accounting-before-publication boundary above. The answer token's distinct +`answer_mirrors` bit fixes mirror admission before model work, so a source activated +during a negative answer cannot introduce an unmarked tool leg. Missing admission is +false; ordinary delegation drops it. See the +[assistant boundary](assistant.md#the-bridge-each-callers-own-identity). + A multi-entry MCP batch refuses every response-bearing marked entry with the same instruction to send it individually, including denied and empty entries. Notifications remain silent. It discards each marked entry's complete frame before buffering it or diff --git a/docs/architecture/github-feed.md b/docs/architecture/github-feed.md new file mode 100644 index 0000000000..bcf5026816 --- /dev/null +++ b/docs/architecture/github-feed.md @@ -0,0 +1,162 @@ +# GitHub tracker feed + +The GitHub feed maintains a team's tracker record in the team's ClickHouse database. +Loom's serving processes read that record through the existing +[read-only tracker source](../features/tracker/record-contract.md). The feed does not +put issue bodies, comments or pull requests in Loom's deployment tables. + +## Ownership and credentials + +An operator runs the feed as a bounded CLI job, scheduled by the team's job runner. +Before reading the registered endpoint or opening the record, the CLI checks its +actual deployment's storage authority and whether its cell holds the feed organization. +The external connection repeats that deployment gate; it never treats the record's +metadata as deployment authority. The job closes both clients and the deployment's +Postgres pool on exit. +Initialization creates feed tables and contract views in an empty, dedicated database; +it refuses existing objects. The operator then registers that database as a tracker +source with a separate read-only credential. Configuration and sync require that +registered endpoint and its repository allowlist. A separately supplied writer +credential can write only the team's feed database; the reader credential is never +upgraded or reused for writes. + +The source credential is a read-only fine-grained GitHub token or App installation +token restricted to the configured repositories: Metadata, Issues and Pull requests, +all read-only. Token permissions are operator-attested configuration: a successful +GET, token prefix or endpoint-permission header cannot certify absence of write grants. +An unidentified host token is not eligible for a read-only live probe. The token is +sealed with the existing secret-root mechanism in the team's +feed configuration table. No token appears in arguments, output or contract views. +The CLI receives the database writer password through a named environment variable; +it does not persist that password. GitHub requests use GET on the fixed +`https://api.github.com` origin, refuse redirects and construct paths from validated +repository names and numeric item ids. They never follow response URLs. + +The team owns the copied record, its backup retention and erasure. To erase copied +content, the team stops its scheduled writer and removes the affected feed rows, +comments and checkpoints before restarting with an exclusion or removing the source +repository. Deleting a Loom namespace retires Loom's derived data and grants; it +does not delete the team's record. This is the same boundary as any registered tracker +database. The record-writer credential cannot address Loom's own database; copied +content is never written there. Only the existing deployment-store lease is local. + +## Record and progress + +Raw items and comments are versioned in the team's database with the identity tuple, +process actor and imported source class. Contract views expose the latest item version, +contract UUIDs and effective visibility. Issue and pull-request comments are +kept separately and included in the corresponding item's searchable body. Unsupported +triage fields use the contract's typed defaults; edges are empty until evidence exists. +Contract `updated_at` is the latest persisted publication timestamp across the item +and its comments, so late imports and comment edits advance incremental tracker reads. +Publication versions use whole milliseconds to match tracker cursors. Under the record's +writer lease, each content batch receives the later of the record clock and one millisecond +beyond every persisted content version for its organization, across all repositories. +This ordering also covers namespaces that read multiple repositories through one cursor. +Repository control writes likewise advance beyond the persisted version for their exact +organization and repository, even when the receiving clock moves backward. Visibility +revocation, credential rotation and cursor checkpoints therefore replace the prior control +row rather than losing to its timestamp. +Raw upstream timestamps remain separate and drive API cursors. No model or embedding +call is required. Repository identities retain the registered allowlist's spelling, +including when the API returns different capitalization. + +Owner, repository revision and publication watermark reads request +`select_sequential_consistency = 1`; the writer lease alone does not make a replica +current. Feed writers require SharedMergeTree storage or a single self-hosted server, +following the [read-your-writes guarantees](clickhouse.md#read-your-writes). +The setting alone does not cover acknowledged writes on self-hosted replicated tables. +Writer validation accepts only `ReplacingMergeTree` and `SharedReplacingMergeTree` +for the five feed tables in the connected record database. Replicated, distributed +and unrecognized table engines are refused before the job can publish. + +Each repository has independent item, issue-comment and review-comment cursors. The +[issues endpoint](https://docs.github.com/en/rest/issues/issues#list-repository-issues) +lists issues and pull requests together; pull requests are hydrated through their +numeric endpoint. The +[issue comments endpoint](https://docs.github.com/en/rest/issues/comments#list-issue-comments-for-a-repository) +and [review comments endpoint](https://docs.github.com/en/rest/pulls/comments#list-review-comments-in-a-repository) +have separate updated-time scans. Each uses ascending `updated_at`, bounded pages, +response bytes and request time. Cursor advancement follows acknowledged writes only, +through a complete timestamp boundary. Requests lower the saved timestamp by one second +because `since` is exclusive. A full page budget saves the earliest timestamp on its +final page; the next turn replays that boundary. The budget is 2 to 100 pages: a preceding +page permits progress while the final page retains an incomplete timestamp boundary. +If one timestamp fills the entire configured page budget, +the job reports a capacity error and keeps the checkpoint rather than skipping rows or +claiming progress. The operator can raise the bounded page budget for that repository. +Replayed rows replace the same identity. The API is a changing collection, not a snapshot; +overlapping scans reduce pagination races without claiming transactional upstream reads. + +Every turn verifies repository identity and visibility before copying content. An +unavailable, moved or mismatched repository first hides that repository's contract rows +and then refuses the turn. Contract views also require a recent successful visibility +observation, expiring after a bounded interval if the scheduler stops. Each item and +comment publication stores the observation's privacy classification in the same row as +its content. Views use the most restrictive classification from the repository, item +and stored comments for both `is_private` and the contract UUID. A replica that learns +new content before repository metadata therefore cannot label a private publication +public. The standard tracker's existing predicate excludes those rows. Restricted +namespaces retain their live direct-grant check. Visibility is a polling observation, +not an instant permission mirror. +A validated identity mismatch or private observation can hide the current record even +when another turn changed its revision; this preserves current credentials and cursors. +Generic failures from an older credential retain the revision check. Stale public +observations cannot widen access. + +When a repository becomes public, configuration or sync resets its existing stream +cursors before publishing public metadata. Bounded scans replay the items and comments +and stamp each with the public observation. An item remains restricted until its own +row and its stored comments have been replayed. Repeated scheduled turns continue a +backlog under the same page and timestamp-boundary limits. Deleted upstream rows cannot +be replayed; the team must erase those retained copies to clear their private +classification. + +Incremental API lists do not report deleted issues or comments. The team handles those +erasures explicitly; the feed does not claim deletion detection. Configuration, sealed +credentials and cursors stay with the team's record, so CLI restarts do not depend on +local files. Initialization binds the record to one Loom deployment's database UUID; +configuration and sync refuse any other deployment. Concurrent jobs in that deployment +use one publication lease keyed by the record database UUID, independent of source +aliases and repository renames. Provider fetches happen outside that lease; initialization, +configuration and publication share it so concurrent first-time identity observations +cannot bypass serialization. An uncertain database write retains its claim through the bounded +server send window. Record erasure requires the team to stop all writers first. + +## Validation and rollout + +Fakes cover pagination ties, partial responses, rate limits, retries, visibility changes, +redirects and credential redaction. A private ClickHouse verifies the contract, current +views, replay and interrupted cursor publication. A read-only token, when available, +checks a bounded public-repository slice; a write-capable CLI token is never substituted. +The feed adds no Loom wire operation or automatic worker. Existing deployments and +registered trackers are unchanged until an operator initializes and schedules a feed. + +## Source entry points + +- [CLI](../../server/cli/tracker_feed.py): `register_tracker_feed` and `_run` select the + owned record and its separate writer credential; `_validate_writer` checks grants + and supported table engines. +- [Feed application](../../server/tracker/app/github_feed.py): `initialize`, `configure`, + `sync` and `_publish` enforce ownership, stamp publication privacy and fence writes. +- [Record store](../../server/tracker/store/github_feed.py): `statements` defines the + contract views; `repository`, `put_repository` and `put_items` read publication + state consistently. +- [API client](../../server/clients/github_feed.py): `pages` bounds upstream scans; + [domain rules](../../server/tracker/domain/github_feed.py) validate identities and + choose replay boundaries through `next_cursor`. + +## Invariants + +- Copied content stays in the team's registered record, with team-owned erasure. +- Repository identity, visibility and revision checks precede content publication; + control reads include acknowledged record writes on the supported storage topology. +- Content and its privacy classification share one raw row version. Contract privacy + and UUIDs include every stored component's classification, even when tables lag + independently. +- A private-to-public transition resets cursors before public publication, so retries + replay retained content without dropping its private classification prematurely. +- The record-wide writer lease covers publication and checkpoint writes. An uncertain + send retains its claim until it settles; a cursor advances only after acknowledged writes. +- Whole-millisecond content versions increase across every repository in the record, + so combined item/comment bodies remain visible to existing tracker cursors. diff --git a/docs/features/tracker/github-feed.md b/docs/features/tracker/github-feed.md new file mode 100644 index 0000000000..81fe53135d --- /dev/null +++ b/docs/features/tracker/github-feed.md @@ -0,0 +1,118 @@ +# Maintain a GitHub tracker record + +`loom tracker-feed` copies repository issues, pull requests, issue comments and inline +review comments into a team's dedicated ClickHouse database. Loom reads the resulting +views through a [read-only tracker source](record-contract.md). The team owns the copied +content, backups and erasure. The job makes no model or embedding calls. + +## Prepare the record + +Use an empty database with a stable database UUID, separate from the Loom deployment +database. Give a dedicated writer permission to create tables and views and to read and +insert rows in that database. Keep its credentials separate from the tracker reader. + +```sql +CREATE DATABASE team_feed; +CREATE USER feed_writer IDENTIFIED BY '…'; +GRANT CREATE TABLE, CREATE VIEW, SELECT, INSERT ON team_feed.* TO feed_writer; +GRANT SELECT ON system.columns TO feed_writer; +GRANT SELECT ON system.databases TO feed_writer; +GRANT SELECT ON system.tables TO feed_writer; +CREATE USER feed_reader IDENTIFIED BY '…' SETTINGS readonly = 2; +GRANT SELECT ON system.columns TO feed_reader; +``` + +Supply the writer password as `LOOM_TRACKER_FEED_WRITER_PASSWORD` through the scheduler's +secret facility. Run the CLI with the same Loom deployment configuration used by the +serving process, including its ClickHouse connection and secret root. +Set `LOOM_TRACKER_ORG` to the organization being initialized. The CLI verifies direct +writer grants before use and refuses roles, grant options and authority outside this +database, apart from those three system metadata tables. + +```bash +loom tracker-feed init --org acme --host record.example --database team_feed \ + --writer-user feed_writer +``` + +Initialization creates `github_issues`, `github_prs` and `edges` as definer views. +Grant the reader access only to those views: + +```sql +GRANT SELECT ON team_feed.github_issues TO feed_reader; +GRANT SELECT ON team_feed.github_prs TO feed_reader; +GRANT SELECT ON team_feed.edges TO feed_reader; +``` + +[Register the tracker source](record-contract.md#adding-a-tracker-source) in views mode +using `feed_reader`. Include each repository in the source's namespace allowlist and +use restricted namespaces for private records. Set the deployment's `LOOM_TRACKER_ORG` +to the same organization. Source registration keeps its existing host, credential and +contract checks. HTTP and private addresses require the development private-host +setting; production connections use HTTPS. + +## Configure and schedule a repository + +Create a read-only fine-grained token or App installation token restricted to the +repositories being copied. It needs Metadata, Issues and Pull requests read permissions. +`--read-only-token` is the operator's permission attestation; the CLI cannot certify the +absence of write grants from a successful request or token prefix. + +Supply that token as `LOOM_TRACKER_FEED_GITHUB_TOKEN` through the secret facility, then +configure one allowlisted repository: + +```bash +loom tracker-feed configure --org acme --source widgets --repo acme/widgets \ + --writer-user feed_writer --read-only-token --max-pages 5 +loom tracker-feed sync --org acme --source widgets --repo acme/widgets \ + --writer-user feed_writer +``` + +Configuration seals the token in the team's feed database. Sync needs the writer +password and deployment secret root; it does not need the token environment variable. +Copied repository identities keep the spelling in the registered source's allowlist, +so namespace filters match even if API capitalization differs. +App installation tokens [expire after one hour](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation). +An external secret process must refresh the installation token and rerun `configure` +before expiry. The feed does not issue or refresh installation tokens. +Use `--writer-password-env` or `--token-env` to select another credential variable. +During a root-secret rotation, successful metadata writes reseal credentials opened by +`LOOM_JWT_SECRET_PREVIOUS`. Complete a successful turn before retiring the previous root. + +Schedule `sync` every five minutes or more frequently. Visibility observations expire +after 15 minutes, hiding the repository if checks stop succeeding. Each job has a +120-second limit and reads at most `--max-pages` pages per stream, with 100 items per +page and a budget of 2 to 100 pages. The final page's timestamp boundary is replayed; +the minimum leaves a preceding page from which to make progress. +A capacity error leaves the cursor unchanged; raise +the bounded page budget or shorten the repository's backlog before retrying. Counts +on standard output report processed rows, including replayed rows. + +## Visibility and erasure + +Every stream verifies the repository's immutable identity and current visibility. +Failed checks hide its views. Each item and comment keeps the observation's privacy +classification with its content. The views use the most restrictive classification +from the repository, item and stored comments, including when those tables reach a +replica at different times. This is a polling observation with a bounded expiry, +rather than an instant permission mirror. Normal tracker privacy and direct grant +checks still apply. + +When a repository becomes public, configuration or sync resets its cursors and +scheduled turns replay all streams within the same page budget. An item becomes public +after its row and stored comments have been refreshed under public observations. +Deleted upstream rows require erasure of the retained copies; replay cannot refresh them. + +Bodies include up to 32,768 item characters and the 64 most recently updated comments, +with up to 2,048 characters per comment. Review requests and test evidence remain +unknown when the source does not provide that evidence. +The views' `updated_at` tracks item and comment publication in the record, so a comment +imported after its item remains visible to incremental tracker reads. + +Incremental lists do not report deletions. To erase copied content, stop every scheduled +writer, erase the affected raw rows, comments and repository configuration or cursors, +and exclude the repository before restarting. Dropping a Loom namespace removes Loom's +derived data; it does not erase the team's database or backups. Initialization binds a +record to one deployment and organization. Use a separate record for another deployment. + +See the [feed architecture](../../architecture/github-feed.md) for cursor boundaries, +concurrency and ownership. diff --git a/docs/features/tracker/overview.md b/docs/features/tracker/overview.md index 657b33b56c..c43c9c14bb 100644 --- a/docs/features/tracker/overview.md +++ b/docs/features/tracker/overview.md @@ -340,6 +340,7 @@ Thresholds, legs, judge, rerank, bisect scope and test-signal settings are in th ## Related +- [GitHub feed](github-feed.md): maintain a team-owned record with a scheduled CLI job - [Record contract](record-contract.md): tables, columns, aliases, mapping mode, sources - [History and PRs](../code-index/history-and-prs.md): the code-plane ops that read a tracker - [Adding repositories](../code-index/repositories.md) diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 72ae7ed997..ff52c7d0fe 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -334,6 +334,10 @@ python scripts/codegen/docs_reference.py | `loom tracker-contract-check` | Read-only: does each tracker source's schema meet the record contract (docs/features/tracker/record-contract.md)? | `--source`, `--namespace`, `--json` | | `loom tracker-dupcheck-fit` | Refit tracker.duplicate_check's calibrated confidence for one tracker namespace now: replays the duplicate gold at filing time, fits, stores the fit. | `--namespace`, `--org`, `--negatives`, `--dry-run`, `--out` | | `loom tracker-embed-reset` | Clear the tracker_embed pass cursors of one tracker namespace so the next pass re-walks the window and re-embeds every item whose text recipe changed. | `--namespace`, `--org`, `--kind`, `--apply`, `--dry-run` | +| `loom tracker-feed` | Maintain a team's GitHub tracker record | | +| `loom tracker-feed init` | | `--org`, `--writer-user`, `--writer-password-env`, `--host`, `--port`, `--database`, `--insecure` | +| `loom tracker-feed configure` | | `--org`, `--writer-user`, `--writer-password-env`, `--source`, `--repo`, `--token-env`, `--read-only-token`, `--max-pages` | +| `loom tracker-feed sync` | | `--org`, `--writer-user`, `--writer-password-env`, `--source`, `--repo` | | `loom namespaces-adopt` | Give namespaces that hold live memory and no registry row an owner row: kind=bench under the bench prefixes, else memory; retention_days 0, no TTL. | `--org`, `--owner`, `--prefix`, `--namespace`, `--kind`, `--apply`, `--dry-run`, `--show` | | `loom sensitivity-sweep` | Label live rows the sensitivity detector would have labelled on write but a path skipped. | `--org`, `--namespace`, `--since-days`, `--limit`, `--show`, `--only-shape`, `--apply`, `--dry-run` | | `loom integrity-repair` | Read the row-level integrity gauges (dim-0 rows holding a vector, tombstoned_at/status drift, active rows past valid_to) and, with --apply, re-emit the dim-0 rows with their true dimension so search… | `--org`, `--namespace`, `--limit`, `--show`, `--apply`, `--dry-run` | diff --git a/docs/reference/operations/assistant.md b/docs/reference/operations/assistant.md index 431a746653..8776e14406 100644 --- a/docs/reference/operations/assistant.md +++ b/docs/reference/operations/assistant.md @@ -23,6 +23,7 @@ Ask the Loom assistant one question about this namespace and get one cited answe | Output field | Type | Meaning | | --- | --- | --- | +| `mirrored` | `bool` | True when this answer is private to the caller's protected session; false by default. | | `answer` | `str` | The assistant's answer, with its citations as the agent wrote them. | | `run_id` | `str` | The answer's id: the run its tool calls are ledgered under (agent_events.run_id). | | `model` | `str` | The model that answered. | diff --git a/frontend/src/views/RecallLab.table.test.tsx b/frontend/src/views/RecallLab.table.test.tsx index d7383be8fb..f2391d721e 100644 --- a/frontend/src/views/RecallLab.table.test.tsx +++ b/frontend/src/views/RecallLab.table.test.tsx @@ -106,6 +106,26 @@ describe("Recall Lab: the scores table", () => { expect(screen.queryByRole("button", { name: "deploy_note" })).toBeNull(); }); + it("keeps settled scores out of draft query edits and clears them with the query", async () => { + const result = hit("deploy_note", 0.9); + const readTerms = vi.fn(() => ({ semantic: 0.6, entity_ann_boost_effective: 0.06 })); + Object.defineProperty(result, "score_components", { get: readTerms }); + searchMemory.mockResolvedValue({ results: [result], embedding_model: "m" }); + render(); + const table = await score(); + expect(readTerms).toHaveBeenCalled(); + readTerms.mockClear(); + + fireEvent.change(screen.getByLabelText("Recall query"), { target: { value: "deploy lane" } }); + expect(screen.getByLabelText("Recall query")).toHaveValue("deploy lane"); + expect(within(table).getByText("excerpt of deploy_note")).toBeInTheDocument(); + expect(readTerms).not.toHaveBeenCalled(); + expect(searchMemory).toHaveBeenCalledTimes(1); + + fireEvent.change(screen.getByLabelText("Recall query"), { target: { value: "" } }); + expect(screen.queryByRole("table", { name: "Recall scores" })).toBeNull(); + }); + it("draws the score as Click UI's table bar, relative to the top score", async () => { searchMemory.mockResolvedValue({ results: [hit("deploy_note", 0.8), hit("rollback_runbook", 0.4)], diff --git a/frontend/src/views/RecallLab.tsx b/frontend/src/views/RecallLab.tsx index 3398a2b133..03a6f977eb 100644 --- a/frontend/src/views/RecallLab.tsx +++ b/frontend/src/views/RecallLab.tsx @@ -1,4 +1,4 @@ -import { useCallback, useEffect, useState } from "react"; +import { useCallback, useEffect, useMemo, useState } from "react"; import { Badge } from "@clickhouse/click-ui/Badge"; import { Button } from "@clickhouse/click-ui/Button"; import { Icon } from "@clickhouse/click-ui/Icon"; @@ -509,7 +509,21 @@ export function RecallLab() { }, [query, identity, attempt]); const showResults = !abstain || showWeak; - const topScore = Math.max(0, ...(rows ?? []).map((row) => row.hit?.rank_score ?? 0)); + const scoresTable = useMemo(() => { + if (rows == null || rows.length === 0 || !showResults) return null; + const topScore = Math.max(0, ...rows.map((row) => row.hit?.rank_score ?? 0)); + return ( + scoreRow(row, i, topScore, open, rowsQuery))} + /> + ); + }, [rows, rowsQuery, open, loading, showResults]); const count = rows != null && rows.length > 0 && showResults && error == null ? `${rows.length} row${rows.length === 1 ? "" : "s"}${model ? ` · ${model}` : ""}` @@ -593,17 +607,7 @@ export function RecallLab() { )} )} - {showResults && ( -
scoreRow(row, i, topScore, open, rowsQuery))} - /> - )} + {scoresTable} )} diff --git a/i18n/.pending/es/docs/development/migrations.md b/i18n/.pending/es/docs/development/migrations.md new file mode 100644 index 0000000000..59bf277b6c --- /dev/null +++ b/i18n/.pending/es/docs/development/migrations.md @@ -0,0 +1,151 @@ + +> Esta página es una traducción automática de la [página en inglés](https://github.com/ClickHouse/loom/blob/main/docs/development/migrations.md), que prevalece. +> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/development/migrations.md), which is authoritative. + + + +# Migraciones + +Esta página contiene las reglas para escribir una migración. La forma en que un despliegue las aplica, y los pasos de actualización y reversión, están en [actualizaciones](https://github.com/ClickHouse/loom/blob/main/docs/operations/upgrades.md#how-migrations-run). [`schemas/README.md`](https://github.com/ClickHouse/loom/blob/main/schemas/README.md) describe el directorio `schemas/` y enumera las herramientas del operador. + + + +## El journal y el ledger + +- El esquema es un journal de archivos SQL numerados en `schemas/migrations/`, aplicados en + orden de prefijo numérico por `server/core/schema/migrate.py`. `000_migrations.sql` crea el ledger; + `016_baseline.sql` es el esquema inicial; cada archivo posterior es un delta. +- Cada archivo aplicado se registra en `loom._migrations` con el SHA-256 de su contenido. + Una nueva ejecución aplica solo los archivos nuevos. Un archivo modificado es **checksum drift** (deriva de checksum) y un archivo que el + repositorio ya no tiene es una **fila solo del ledger**; `loom migrate --dry-run --strict` + (un paso de CI y la verificación previa al despliegue) falla en ambos casos. Un archivo renombrado con su texto + sin cambios no es una fila solo del ledger: su SHA-256 lo identifica, y se registra con el nuevo + nombre sin ejecutarse de nuevo. +- Cada archivo usa `loom.
` y `loom_telemetry.
`. El runner los asigna + a `LOOM_CH_DATABASE` y `LOOM_CH_TELEMETRY_DATABASE` al enviar cada sentencia + (`server/core/ch_names.py`), de modo que el checksum se calcula sobre el archivo tal como está escrito. Una base de datos + se compara por valor como `currentDatabase()` o un nombre enlazado, nunca como un literal `'loom'` + (`tests/unit/test_ch_names.py`). Un archivo que cambia la clave o el TTL de una tabla cuyo + nombre empieza con `_`, o que renombra o intercambia una, también actualiza su fila en [disposición del + almacenamiento](https://github.com/ClickHouse/loom/blob/main/docs/architecture/storage-layout.md) y la protección de remodelado de + `tests/unit/test_storage_layout_rows.py`. + + + +## Numeración + +Un archivo se llama `NNN_description.sql`. El runner ordena por el prefijo entero, no por el +nombre (`server/core/schema/journal.py`, `migration_order`), de modo que `1030_x.sql` se ejecuta después de `220_y.sql`. Toma el siguiente número libre, revisando `main` +y los pull requests abiertos, y consérvalo: dos archivos con el mismo número se aplican igualmente, pero en el +orden léxico de sus sufijos, que no es el orden que nadie pretendía, y un rebase +que renombra uno no vuelve a aplicar nada. `tests/unit/test_migration_numeric_order.py` falla si +se comparte un número. + + + +## Reglas para escribir una migración + +- **Nunca edites ni elimines una migración ya fusionada.** Los registros de los despliegues guardan su hash. Una corrección es un archivo nuevo. +- **Solo cambios aditivos.** Añade tablas, columnas, índices, projections y vistas; elimina un índice de omisión (skip index) o una projection que ningún código bajo `server/`, `scripts/`, `bench/` o `dev/` nombre (la compilación anterior pierde una optimización, nunca una columna); cambia codecs, valores por defecto o ajustes de tabla; amplía tipos; extiende un enum. Nunca elimines ni renombres una tabla o una columna, y nunca intercambies tablas. `tests/unit/test_migrations_additive.py` lo hace cumplir. De las vistas y las tablas, solo permite `DROP VIEW IF EXISTS` de una vista materializada que actúa al insertar y `DROP TABLE IF EXISTS` de una tabla reemplazada, en cada caso cuando ningún archivo bajo `server/`, `scripts/`, `bench/` o `dev/` la nombra: ni una compilación en servicio ni una herramienta de operador (que se ejecutan contra el servicio de producción) la lee. Restringir un tipo queda como cuestión de revisión, ya que una expresión regular no puede distinguirlo de una ampliación. +- **Retira una columna en dos versiones.** Primero publica una versión cuyo código ya no la lea ni la escriba; elimínala solo cuando ninguna compilación en servicio la nombre. +- **Todo escritor lleva una columna nueva.** Añadir una columna a `loom.memory` o `loom.shared` implica actualizar los constructores de filas en `server/memory/store/rows.py` (`build_memory_version_row`, `build_embedding_row`) y cada projection que los alimenta en el mismo cambio: son tablas `ReplacingMergeTree(version)` que se leen con `FINAL`, y una fila de versión que omite una columna la pone a cero en silencio para todos los lectores. Una columna nueva de `loom.memory` también debe añadirse a `loom.memory_versions` y al `SELECT` de la vista `memory_versions_mv` en la misma migración; de lo contrario, el historial deja de registrarla (`tests/unit/test_memory_versions_schema.py` compara las listas de columnas). +- **Una tabla que pueda contener contenido de memoria** necesita además un paso en la saga de borrado y una fila en el censo de residuos (`server/erasure/store/census.py`, `_CENSUS`); `tests/unit/test_every_table_is_classified.py` falla ante una tabla nueva que no figure en ninguna lista ([añadir una tabla](https://github.com/ClickHouse/loom/blob/main/docs/development/adding-a-table.md)). +- **DDL portable entre motores.** Declara las columnas vectoriales como `Array(BFloat16) CODEC(NONE)`; donde el codec `Quantized` pueda estar activo, el runner las crea ya codificadas ([ajustes restringidos](../architecture/clickhouse.md#gated-clickhouse-settings)). Usa nombres de motor `MergeTree` simples, que ClickHouse Cloud ejecuta como `SharedMergeTree`. + +**Por qué aditivo.** La compilación que estaba en servicio antes de ejecutar una migración debe poder seguir leyendo y escribiendo después todas las tablas que conocía. Eso convierte un rollback blue/green en un cambio de proxy en lugar de un rollback de esquema, y permite que el color anterior siga sirviendo mientras el nuevo aplica las migraciones al arrancar. El precio se paga aquí: dos versiones para retirar una columna y reconstrucciones en lugar de `ALTER` para los cambios de clave. + + + +## Directivas del runner + +Un archivo de migración puede llevar directivas en comentarios que el runner lee: + +| Directiva | Efecto | +| ----------------------------------- | -------------------------------------------------------------------------------------------------------- | +| `-- loom: tolerate-error ` | el archivo sobrevive a un error del servidor con nombre (por ejemplo, un setting que solo aceptan algunos servidores) | +| `-- loom: rebuild-if-empty
` | declara una clave de ordenación o de partición objetivo para `
` (abajo) | +| `-- loom: baseline covers N` | el archivo reemplaza a todos los archivos numerados N o menos que el repositorio ya no incluye | + +**Baselines.** Un baseline lleva el número N, posterior al del archivo más reciente que reemplaza. Una base de datos nueva lo ejecuta. Una base de datos cuyo ledger contiene el archivo N lo registra sin ejecutarlo y conserva las filas reemplazadas, que el modo estricto informa como reemplazadas (superseded) y no como errores. Así, una compactación (squash) no requiere editar a mano ningún ledger, y una compilación anterior a ella sigue encontrando aplicados todos sus propios archivos. Una base de datos cuyo ledger contiene algunos archivos reemplazados pero no el archivo N se detuvo a medio camino: `loom migrate` la rechaza (`stranded`) y no cambia nada, ya que ejecutar el baseline omitiría los archivos que le faltan y registrarlo daría por hecho su esquema. Aplica los archivos que faltan con una compilación anterior a la compactación y vuelve a migrar. Compacta en una versión, no en cada cambio; la compactación construye el baseline a partir de `schemas/schema.sql` (el cuerpo del volcado sin los objetos que crean los archivos que conserva) y lo comprueba en un servidor nuevo, en un ledger totalmente migrado y en uno a medio migrar. + +El runner también adapta sentencias al aplicarlas sin cambiar los archivos ni sus checksums: elimina el flag experimental de NLP donde el servidor lo prohíbe, crea las columnas vectoriales con el códec `Quantized` donde puede estar activo, quitando un códec general encadenado después de él donde `allow_suspicious_codecs` no puede estarlo (`server/core/schema/vector_codec_ddl.py`), crea cada vista con el usuario que ejecuta la migración (`DEFINER = CURRENT_USER`: el volcado nombra a su propio usuario, que otro servidor puede no tener) y espera a que termine cada mutación que emite un archivo antes de registrarlo (`LOOM_MIGRATE_MUTATION_WAIT_S`). + +**Verificaciones previas.** Un archivo que no debe ejecutarse mientras los datos contengan algo que el archivo por sí solo no puede ver registra una verificación en `server/core/schema/prechecks.py`, indexada por su nombre sin el número, de modo que un archivo renumerado la conserva. El runner ejecuta la verificación antes del archivo, también en una ejecución de prueba (dry run); una verificación que rechaza detiene la ejecución con su mensaje y no ejecuta nada del archivo. `097_mirror_names_reserved.sql` usa una: rechaza mientras un espacio de nombres con la forma reservada de espejo esté registrado o contenga filas vivas. + + + +## Cambiar una clave de ordenación o una clave de partición + +ClickHouse no cambia ninguna de las dos en el lugar, así que una migración declara el destino y la tabla se reconstruye, nunca se altera: + +```sql +-- loom: rebuild-if-empty code_test_facets +CREATE TABLE loom.code_test_facets ( ...every column, unchanged... ) ... ORDER BY (...); +``` + +Esa sentencia es la única copia del DDL de destino. El runner (`server/core/schema/table_rebuild.py`) compara el `sorting_key` y el `partition_key` de la tabla en vivo con ella: si coinciden, registra el archivo; una tabla vacía (una instalación nueva) se intercambia al instante por una gemela con el DDL de destino; y una tabla con filas hace fallar el arranque con un mensaje que nombra la herramienta. Un arranque nunca copia filas. En un despliegue con datos, el operador ejecuta primero la herramienta, una tabla a la vez: + +```bash +python -P -m scripts.ops.table_rebuild --table code_test_facets --dry-run +python -P -m scripts.ops.table_rebuild --table code_test_facets --yes +``` + +Toda acción que modifica algo (`--yes` solo, `--rollback`, `--drop-pre-rebuild`) imprime el ClickHouse con el que se comunica y su plan, y no cambia nada sin `--yes`. La herramienta copia todas las filas (sin FINAL) a `loom._rebuild` en lotes acotados, copia las partes escritas entretanto, comprueba el número de filas bajo FINAL y la versión más reciente de una muestra de claves, intercambia con `EXCHANGE TABLES` y conserva la tabla antigua como `loom._pre_rebuild` para `--rollback` hasta `--drop-pre-rebuild`. Se niega a intercambiar, conservando la gemela, cuando un `ALTER` cambió la tabla en vivo durante la copia: sale con 6 si ClickHouse lo ejecuta como mutación (eliminar, renombrar o cambiar el tipo de una columna, eliminar un índice, un TTL) y con 3 si solo mueve el tiempo de sus metadatos (un índice, un ajuste, el valor por defecto o el códec de una columna). Una columna añadida hace fallar la copia (salida 1, sin intercambio), o la ejecución sale con 3 tras la última pasada de verificación. Una reconstrucción no arrastra un `ALTER`: vuelve a expresarlo en la sentencia de destino y ejecuta de nuevo con `--restart`. Además, rechaza una tabla que ninguna migración declara. +`loom migrate --dry-run --strict` falla mientras una tabla declarada siga teniendo filas en la disposición antigua, de modo que la comprobación previa al despliegue detecta un paso omitido. + +El destino conserva las columnas de la tabla (así el intercambio es aditivo), y su clave de ordenación conserva las columnas de la clave antigua, reordenadas: esa clave es también la que usa un `ReplacingMergeTree` para fusionar. Una clave con otras columnas fusiona otras filas y se lista con su motivo en `tests/unit/test_migrations_additive.py`. Nombra la reconstrucción en las notas de la versión como un paso del operador ([proceso de publicación](https://github.com/ClickHouse/loom/blob/main/docs/development/release-process.md#release-notes)). + + + +## Migraciones de Postgres + +Los archivos `schemas/pg_migrations/NNN_*.sql` siguen las mismas reglas: están numerados, son aditivos, nunca se editan una vez fusionados, y cada `CREATE`, `ALTER` o `DROP` de una tabla nombra `loom.
`, salvo el nombre nuevo de un renombrado, donde Postgres no admite esquema (`tests/unit/test_storage_layout_rows.py`). Un arranque los aplica bajo un bloqueo consultivo (advisory lock) de Postgres, cada archivo en una transacción junto con su fila del registro. Una migración espera como máximo 5 s a un bloqueo de tabla (`lock_timeout`, y luego reintenta), de modo que un `ALTER` nunca deja en cola todas las consultas de la tabla detrás de una transacción larga. Una compilación sirve con un registro que contiene archivos de una compilación posterior, con una advertencia que los nombra; un archivo del registro que no incluye, numerado igual o por debajo de su propio último archivo, o uno cuyo checksum cambió, rechaza el arranque. + +Cada archivo se ejecuta en una transacción, por lo que una migración no crea índices en una tabla grande: la creación bloquearía las escrituras de la tabla, y cada commit respondería 503, hasta que termine. Un índice así necesita `CREATE INDEX CONCURRENTLY` fuera de una transacción, y un arranque que espera el bloqueo consultivo entra en interbloqueo con él (una sesión en espera mantiene un snapshot que la creación debe esperar a que termine): un cambio que añade un archivo de ese tipo también toma el bloqueo reintentando `pg_try_advisory_lock`. Cuando la primera versión que escribe en una tabla incluye el archivo, la tabla es pequeña dondequiera que se ejecute el archivo, y su índice puede crearse en la transacción del archivo (`010_revision_delivered_at.sql`). + + + +## Volcado y verificación del esquema + +`schemas/schema.sql` es el resultado volcado de aplicar todas las migraciones: léelo para +entender la forma actual, nunca lo edites a mano. Después de cambiar una migración, regénéralo +contra un ClickHouse nuevo de la versión que prueba CI (`clickhouse/clickhouse-server:latest`): + +```bash +bash dev/ci_start_clickhouse.sh # that image with Loom's server config +make migrate +make schema-dump # rewrites schemas/schema.sql only when the dump differs +make schema-check # exit 1 with the head of the diff; writes nothing +``` + +Si el volcado falla, el archivo queda como estaba. Otra versión de ClickHouse, un servidor donde el +códec `Quantized` o su cadena `LZ4` no se pueden activar, o una base de datos que contiene gemelas de reconstrucción producen un volcado +distinto, y por eso importa el contenedor fijado. Las tablas internas (`_migrations`, nombres que empiezan por `_` o `.`) +se excluyen. El job `schema-check` de CI reproduce todas las migraciones en un servidor nuevo, ejecuta +la prueba en seco estricta y después `make schema-check`. + +CI sigue `latest`, así que una nueva versión de ClickHouse que imprima el DDL de otra forma pone +`schema-check` en rojo sin ningún cambio en Loom. Lee la diferencia que imprime el job: cuando solo es +de formato, ejecuta los cuatro comandos anteriores (descargan la nueva versión) y confirma +`schemas/schema.sql` por separado. Un cambio de significado (un tipo, un valor por defecto, un ajuste +del motor) es un cambio de comportamiento de ClickHouse que conviene investigar antes de volcar encima; +`LOOM_CLICKHOUSE_IMAGE=clickhouse/clickhouse-server:A.B.C.D` ejecuta los comandos anteriores sobre la +última versión que se volcó sin diferencias, para comparar. + + + +## Lista de verificación + +1. Toma el siguiente número libre; escribe el archivo de forma aditiva. +2. Actualiza los constructores de filas, `loom.memory_versions`, el censo de borrado y los casos del analizador si el cambio los afecta. +3. Ejecuta `make migrate` contra un ClickHouse local, luego `make schema-dump` y confirma `schemas/schema.sql` junto con la migración. +4. Ejecuta `make test-unit` (las pruebas de aditividad, numeración y clasificación del esquema) y la suite de integración para las rutas que leen la nueva forma. +5. Anota cualquier paso del operador (una reconstrucción, un backfill) para las notas de la versión. + + + +## Relacionado + +- [Actualizaciones](https://github.com/ClickHouse/loom/blob/main/docs/operations/upgrades.md): cómo el runner aplica los archivos en un despliegue +- [ClickHouse](../architecture/clickhouse.md) +- [Referencia del esquema](https://github.com/ClickHouse/loom/blob/main/docs/reference/schema.md) diff --git a/i18n/.pending/es/docs/features/memory/retention-and-erasure.md b/i18n/.pending/es/docs/features/memory/retention-and-erasure.md new file mode 100644 index 0000000000..710b294d5e --- /dev/null +++ b/i18n/.pending/es/docs/features/memory/retention-and-erasure.md @@ -0,0 +1,292 @@ + +> Esta página es una traducción automática de la [página en inglés](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/retention-and-erasure.md), que prevalece. +> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/retention-and-erasure.md), which is authoritative. + + + +# Retención y borrado + +Loom no elimina ninguna memoria a menos que lo solicite quien la escribió, el propietario del espacio de nombres o el operador. La memoria no tiene una vida útil por defecto. Los datos salen de tres maneras: una expiración o eliminación hecha por quien escribe, una retención que configuró un propietario u operador, y un borrado que elimina un ámbito en todos los lugares donde Loom lo guarda. + + + +## Qué se conserva y por cuánto tiempo + +Ninguna tabla de memoria, embeddings, historial de versiones, conversaciones, entidades, resúmenes, memoria de trabajo o conocimiento tiene un TTL en `schemas/schema.sql`, y ningún worker retira filas por antigüedad. +Las tablas de enlaces `entity_triple_rows` y `entity_edge_rows` siguen a `entity_triples` y +`entity_edges`: sin TTL. Una eliminación definitiva (erasure) borra los enlaces de las memorias que elimina, y +`loom erasure-re-verify --completed-since … --resume` borra los enlaces huérfanos que dejó la eliminación de una compilación anterior. +Una fila sale del conjunto servido solo cuando: + +- **la elimina quien la escribió**: `memory.delete`, una reescritura con la misma clave que la sustituye, + `memory.apply`, `memory.clear`, `conflicts.resolve`, `blacklist.add(sweep=true)`; +- **quien la escribió definió una caducidad**: `ttl_seconds` o `valid_to` en `memory.set`, + `memory.touch`, `run.complete(retain="expire")`, el `expires_in_days` de una reflexión; +- **el propietario o el operador configuró una**: consulta la [retención configurada](#configured-retention). + +Las tablas operativas (telemetría, cachés, colas) tienen TTL fijos: `loom.search_trace_log` +y `loom.memory_exposures` 180 días; `loom.erasure_requests` y +`loom.policy_decisions` 90 días; `loom.memory_drops`, `loom.memory_extraction_queue`, +`loom.events` y `loom.embedding_cache` 30 días; `loom.llm_response_cache` 7 días. La +[referencia del esquema](https://github.com/ClickHouse/loom/blob/main/docs/reference/schema.md) lista el TTL de cada tabla. + +Un worker elimina datos según un temporizador: `namespace_gc` purga los espacios de nombres de +`kind = 'bench'` (identificados por `LOOM_NAMESPACE_BENCH_PREFIXES` en el registro automático) sin +escrituras durante `LOOM_NAMESPACE_GC_IDLE_HOURS`, mediante una saga de eliminación definitiva. Nunca toca +otros tipos. Consulta [espacios de nombres y uso compartido](https://github.com/ClickHouse/loom/blob/main/docs/features/namespaces-and-sharing.md). + + + +### Borrar no es eliminar definitivamente + +Una lápida (tombstone) es una nueva versión con `tombstoned_at` definido. Las lecturas dejan de servirla de inmediato, pero +la fila y sus versiones anteriores en `loom.memory_versions` siguen en disco: + +- `memory.restore` revive una clave con lápida dentro de 14 días (después responde + `expired=true`). También revierte una sustitución automática. +- `memory.clear` (admin) pone una lápida a todas las memorias de un agente o usuario en un espacio de nombres; + `confirm_subject` debe repetir el `user_id` o `agent` concreto (ni `'*'` ni `'-'` + confirman). `agent="*"` con un `user_id` borra las filas de ese usuario bajo cualquier agente, y + `user_id="*"` con un `agent` borra las filas de ese agente para todos los usuarios. Se rechaza un alcance que no nombre a nadie + salvo `'-'`, igual que un borrado de todo el espacio de nombres. Las filas bloqueadas permanecen y se cuentan en + `locked_skipped`. Las claves borradas se reviven del mismo modo. + +Para eliminar los bytes, usa una [eliminación definitiva](#erasure). Para quitar un valor pero conservar la fila y el +rastro de auditoría, usa [`memory.redact`](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/history-and-provenance.md#scrubbing-history-memoryredact). + + + +### Caducidad definida por el escritor + +Una fila se oculta de las lecturas en el momento en que pasa su `expires_at`. Después, el worker +`memory_expiry_sweep` aplica el `on_expire` del escritor como una nueva versión: + +| `on_expire` | Efecto | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------- | +| `tombstone` (predeterminado) | Se le pone lápida, con la ventana de restauración de 14 días. | +| `demote` | Se borra la caducidad; confianza × `LOOM_MEMORY_EXPIRY_DEMOTE_FACTOR` (0.5), nunca por debajo de `LOOM_MEMORY_EXPIRY_DEMOTE_FLOOR` (0.05). | +| `anonymize` | El valor se reemplaza por un marcador y se descartan los embeddings; la fila permanece como prueba de que existió. | + +`memory.touch` cambia solo la caducidad de una fila, para una clave o hasta 1,000 (`memory_keys`): un +nuevo `ttl_seconds`, `clear_expiry=true` o un nuevo `on_expire`. `memory.sweep_expired` +(admin) ejecuta un barrido para un espacio de nombres bajo demanda, con `dry_run`. Una edición de otros campos +mantiene una caducidad vigente. + + + +### Retención configurada + +Todo está desactivado de forma predeterminada (0 = conservar siempre). + +| Dónde | Se define con | Efecto | +| ---------------------------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Un tipo de memoria en un espacio de nombres | `retention_days` en una entrada `tag_registry` de `namespace.register` | Una fila que `memory.set` escribe sin caducidad vigente, `ttl_seconds` ni `clear_expiry` recibe `expires_at = now + N days`; una fila `read_only` reafirmada no recibe ninguna. | +| Filas sensibles | `LOOM_MEMORY_SENSITIVE_RETENTION_DAYS`, `LOOM_MEMORY_SENSITIVE_ON_EXPIRE` (predeterminado `anonymize`) | Las filas nuevas de sensibilidad `medium` / `high` reciben una caducidad; prevalece una caducidad más corta del llamante. | +| Las escrituras de una ejecución | `LOOM_MEMORY_RUN_COMPLETE_RETAIN` (`keep`, `demote`, `expire`), `LOOM_MEMORY_RUN_COMPLETE_EXPIRE_DAYS` (7) | Lo que `run.complete` hace con las filas de la ejecución cuando la llamada no lo indica. Las filas fijadas, verificadas, promovidas, bloqueadas, episódicas y de reflexión siempre se conservan. | +| Un espacio de nombres completo | `retention_days`, `warm_days` en `namespace.register` | Un TTL de tabla (y traslado al nivel cálido) para las filas de ese espacio de nombres. | +| El despliegue | `LOOM_RETENTION_
_DAYS`, `LOOM_TIERING_
_WARM_DAYS` | Un TTL de tabla (y traslado al nivel cálido) en `audit_log`, `agent_events`, `memory`, `memory_embeddings`, `conversations`, `chunks`, `documents`. | + +Bajo la autoridad de Postgres, ninguna de las dos últimas filas pone un TTL de retención en +`memory`, `memory_embeddings` ni `documents`: eliminaría la copia en ClickHouse de filas que +Postgres aún sirve, por lo que el arranque rechaza `LOOM_RETENTION_MEMORY_DAYS`, +`LOOM_RETENTION_MEMORY_EMBEDDINGS_DAYS` y `LOOM_RETENTION_DOCUMENTS_DAYS` +([autoridad de almacenamiento](../../architecture/storage-authority.md)). El +`retention_days` de un espacio de nombres tampoco afecta a `chunks`, de modo que un documento que permanece conserva los fragmentos con los que la búsqueda lo encuentra; `LOOM_RETENTION_CHUNKS_DAYS` sigue aplicándose. + +El worker `retention_reconcile` aplica las dos últimas filas como un `ALTER TABLE … MODIFY TTL` idempotente por tabla, por `(org, namespace)` cuando existen sobrescrituras, y +elimina el TTL de una tabla cuando ya no queda ningún espacio de nombres ni ventana de despliegue sobre ella. En +`loom.memory` el TTL se basa en `coalesce(expires_at, created_at)`, de modo que la caducidad del escritor +prevalece. + +- **Un TTL de tabla elimina físicamente** en la siguiente fusión (merge) de la parte. No hay ventana de restauración, y las lápidas caducan junto con las filas que ocultan. +- **Un Undo se mantiene mientras se mantenga su registro.** El resolutor de conflictos respeta el Undo de una persona + sobre una retirada mediante su fila `memory.unsupersede` en `audit_log`. Con un TTL de `audit_log` + más corto que la vida de un par, un Undo caducado deja de mantenerse, y el resolutor puede juzgar + y retirar ese par de nuevo. +- **El almacenamiento por niveles necesita un volumen.** `LOOM_TIERING_WARM_VOLUME_NAME` debe nombrar un volumen de la + política de almacenamiento, y la antigüedad cálida debe ser menor que la antigüedad de retención. + + + +## Borrado + +`erasure.request` borra un ámbito en todos los lugares donde Loom lo conserva, y responde cuando puede demostrar que no queda nada del ámbito. Para borrar todo lo que un id de usuario tiene en la organización, un administrador de la organización solicita el ámbito `user_id`, que borra las filas del usuario en todos los espacios de nombres de la organización (`purge=true` las elimina en lugar de marcarlas con una lápida; lo que deja se enumera más abajo). `memory.clear` marca con una lápida las memorias de un agente o de un usuario solo en un espacio de nombres ([eliminar no es borrar](#delete-is-not-erase)). + +| `scope_type` | `scope_value` | Quién puede solicitarlo | +| ---------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------- | +| `user_id` | El id de usuario, en todos los espacios de nombres de la organización | Un administrador de la organización | +| `namespace` | Un espacio de nombres | Un administrador de ese espacio de nombres (o de la organización) | +| `namespace_list` | Un arreglo JSON de 1–500 espacios de nombres, o `{"namespaces": [...], "purge": bool}` | Un administrador de la organización | + +La op se puede invocar con un token de escritor, pero el handler exige permisos de administrador sobre el destino (de lo contrario, 403 `AUTH_INSUFFICIENT`). + +Los vínculos de categoría (`loom.memory_categories`) no llevan usuario, así que un borrado de `user_id` los deja, junto con las filas de auditoría de `memory.import` que los enumeran. Para un elemento importado, la clave del vínculo es `import:` más un resumen (digest) de su texto, que permite confirmar un texto adivinado; un borrado de `namespace` elimina los vínculos. + +Un borrado de `user_id` elimina los chunks literales marcados con el usuario y los chunks sin usuario (`-`) bajo alguno de los pares `(namespace, key)` del usuario, sea de quien sea la memoria a la que pertenezcan: un chunk `-` puede contener texto del usuario, y la ruta de escritura también los retira como del escritor. Los chunks marcados con otro usuario permanecen. + +Un borrado de `user_id` también retira los resúmenes consolidados construidos a partir de las memorias del usuario, con la identidad que los haya escrito ([cuáles](../../architecture/memory-architecture.md#background-passes)), junto con lo derivado de ellos: su historial de versiones, sus chunks literales y vectores de entidades, las filas del grafo extraídas de ellos y las copias a nivel de espacio de nombres promovidas a partir de ellos. También elimina las respuestas de `memory.ask` en caché y los precedentes que los citaban. + + + +### La saga + +```mermaid +flowchart TD + R["erasure.request"] --> L["ledger row in loom.erasure_requests
(in_progress)"] + L --> S["Loom steps: memory, embeddings, versions,
chunks, evidence, summaries, graph,
conversations, blobs, briefs, runs, tasks, ..."] + S --> X["external backends:
Langfuse, ClickStack"] + X --> V["verify.residue census"] + V -->|no live rows| C["completed
(residue_count 0, verified_at)"] + V -->|rows left| F["failed
(residue per table)"] + S -->|step error| F + X -->|backend cannot confirm| F + F --> W["erasure_recovery worker
resumes from steps_completed"] + W --> S + W -->|5 attempts| A["failed + erasure.abandoned audit row"] +``` + +- **Pasos con puntos de control e idempotentes.** Cada paso terminado se registra en `steps_completed`. El worker `erasure_recovery` reanuda desde su punto de control una saga que quedó en `in_progress` o `failed`. Un paso espera hasta `LOOM_ERASURE_MUTATION_WAIT_S` a su mutación y, si no termina, falla nombrándola. +- **Las fuentes de documentos se detienen antes de que se vayan los documentos.** Un borrado de espacio de nombres retira las [fuentes de documentos](https://github.com/ClickHouse/loom/blob/main/docs/features/knowledge.md#document-sources) del espacio de nombres en `knowledge_sources.retire`, su primer paso, y borra sus credenciales; luego espera a que termine el turno de sincronización de cada fuente que siga en ejecución (hasta 30 segundos en total; un turno que sigue en ejecución hace fallar el paso con `OVERLOADED`, y `erasure_recovery` reintenta la saga), de modo que ninguna sincronización vuelva a escribir un documento o una decisión extraída después de que los pasos posteriores los borren. +- **Los vínculos de código esperan al worker de vínculos.** `code_links.delete` toma el lease de cola del worker de vínculos de código, de modo que ninguna pasada publique un cursor que leyó antes del borrado: entre hosts con Keeper, dentro de un mismo proceso sin él. Espera hasta 15 minutos a que termine una pasada; pasado ese tiempo el paso falla con `LeaseBusy` y `erasure_recovery` lo reintenta. +- **Lápida o purga.** De forma predeterminada, las tablas de borrado lógico (memoria, embeddings, chunks, resúmenes, vínculos) se marcan con una lápida, y `memory.restore` todavía puede revivirlas dentro de la ventana; `erasure.list` informa esas reanimaciones como `reversals_count`. `purge=true` elimina las filas en su lugar (un `DELETE FROM` ligero en las tablas anchas). Un ámbito que contiene un espacio de nombres que alguna vez tuvo un mirror se purga entero, todos los espacios de nombres que contiene, de modo que ninguno tiene esa ventana ([fuentes de documentos](https://github.com/ClickHouse/loom/blob/main/docs/architecture/document-sources.md#the-mirror)). Un borrado de usuario encuentra lo que las memorias del usuario alimentaron a través de sus claves, así que en una purga sus filas de `loom.memory` y los resúmenes consolidados construidos a partir de ellas se marcan primero con una lápida y se eliminan en `memory.retire`, después de todos los pasos que leen esas claves; hasta entonces `memory.restore` puede revivirlos (las filas propias del usuario cuentan como una reversión, los resúmenes no), y `memory.retire` elimina lo que `memory.restore` revivió. +- **Originales subidos** de documentos de conocimiento: primero se eliminan las filas del espacio de nombres en `loom.document_blobs` y se registra `blob_erased_at`. Un borrado de usuario elimina los originales que ese usuario subió y que no comparte ningún documento activo de otro escritor, encontrados a través de `loom.blob_uploads` (una fila por subida de cada usuario final, ya que la versión del documento que nombraba un original pudo haber sido reemplazada y fusionada) y a través de sus documentos; después se van sus filas de `loom.blob_uploads`. El censo cuenta ambas tablas. Los originales guardados en un bucket compatible con S3 (`LOOM_DOCUMENT_OBJECT_STORE=s3`) se eliminan antes que sus filas: un borrado de espacio de nombres elimina todos los objetos del ámbito bajo su prefijo y el censo cuenta lo que queda allí (`objects.document_originals`); un borrado de usuario elimina todos los objetos que contienen bytes de los originales propios del usuario, los nombre una fila o no, vuelve a listar sus prefijos y hace fallar el paso si el almacén conservó alguno, luego elimina las filas y después elimina lo que esos prefijos aún contienen y ninguna fila nombra, de modo que la propia subida del usuario de esos bytes, cuya fila se llevó el borrado, también pierde su objeto. Una subida de esos bytes que siga en curso cuando se ejecuta el paso, de cualquier escritor (su objeto almacenado, su fila aún no insertada), pierde su objeto, y su fila, una vez insertada, responde `410 BLOB_GONE`. Cada lote de originales se vuelve a leer justo antes de eliminarse, así que un original que el documento de otro escritor haya nombrado desde entonces permanece; otro escritor que almacene los mismos bytes en el mismo espacio de nombres después de esa lectura puede perderlos, igual que en el almacén de ClickHouse. Una fila que nombra un objeto mientras no hay bucket configurado, o uno fuera del bucket y prefijo configurados, hace fallar el paso en lugar de dejar los bytes. En cualquiera de los dos almacenes, un borrado de usuario elimina las filas en el menor número de mutaciones en que caben sus originales (cada una enlaza tantos como un parámetro de ClickHouse puede llevar). Mover originales de ClickHouse al bucket (`loom knowledge migrate-originals`) está protegido por este ledger: no mueve un original que cubra un borrado sin terminar, y un movimiento que un borrado alcanza termina como ese borrado decida ([dónde se almacenan los originales](https://github.com/ClickHouse/loom/blob/main/docs/features/knowledge.md#where-originals-are-stored)). +- **Las cancelaciones de ingesta.** Un borrado de usuario elimina las filas de ingesta del usuario, entre ellas las cancelaciones. Una cancelación que el usuario pidió sobre el trabajo de otro escritor que sigue pendiente o en procesamiento se conserva primero como una fila sin identidad (`agent`, `user_id` y `session_id` en `'-'`, `actor` vacío), de modo que ese trabajo siga cancelado. +- **Cachés de toda la organización.** `loom.idempotency` (respuestas reproducidas) y `loom.embedding_cache` (vectores de consultas, nunca su texto) llevan la organización pero no un espacio de nombres ni un usuario final, así que un borrado en cualquiera de los dos ámbitos elimina todas las filas de la organización en ambas tablas. El costo son fallos de caché. El censo cuenta `loom.idempotency` en toda la organización pero no `loom.embedding_cache`, que cualquier búsqueda de la organización vuelve a llenar; la caché de vectores en el proceso de cada réplica expira dentro de `LOOM_EMBEDDING_CACHE_TTL_S`. +- **Aprendizajes de reglas del bot.** Las palabras de un usuario en la cola de aprendizajes viven solo en sus filas de `loom.learnings_supporters`, que un borrado de usuario elimina. Un candidato a regla que se queda sin ningún respaldo se elimina entonces si está pendiente, o conserva su decisión con la regla en blanco ([extracción](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/extraction.md#rules-the-assistant-states-about-itself)). El censo cuenta esos candidatos sin respaldo en toda la organización, no solo los del usuario borrado, por lo que una saga puede fallar por un candidato que otro borrado de la organización dejó a medio paso; su paso reabierto lo limpia. + + + +### La cascada federada + +Los datos que Loom envió a otros sistemas se borran en la misma saga. Los pasos externos fallan en modo cerrado: un backend que no puede confirmar el borrado (5xx, timeout, caída de red, una respuesta de salud de Langfuse sin versión) hace fallar el paso, y el worker reintenta. "Nada que borrar" (cero filas coincidentes, o una tabla de ClickStack que el servicio no tiene) cuenta como éxito. + +| Backend | Configurado por | Borra | +| ---------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | +| Langfuse | `LOOM_LANGFUSE_URL` + `LOOM_LANGFUSE_ADMIN_TOKEN` | Trazas encontradas por `userId` dentro de la etiqueta de la organización, o por el par de etiquetas `org:` + `namespace:`. | +| ClickStack | `LOOM_CLICKSTACK_DATABASE`, `LOOM_CLICKSTACK_USER_ID_KEYS` | Filas OTel en el mismo servicio de ClickHouse, que coinciden con las claves de atributo del id de usuario o con el espacio de nombres. | + +Un borrado de espacio de nombres en ClickStack solo coincide con una fila `loom.namespace` cuando lleva el `loom.org` de la organización que borra, de modo que las métricas propias de Loom de ops y de dominio, que no llevan organización, conservan la etiqueta del espacio de nombres ([borrado en ClickStack](https://github.com/ClickHouse/loom/blob/main/docs/features/integrations/clickstack.md#erasure)). + +Un backend sin configurar registra la intención y no borra nada. Solo un borrado de `namespace_list` puede pasar `external=false`; los borrados de `user_id` y `namespace` siempre incluyen los backends. `LOOM_EXTERNAL_ERASURE_TIMEOUT_S` limita cada llamada. Configuración: [Langfuse](https://github.com/ClickHouse/loom/blob/main/docs/features/integrations/langfuse.md) y [ClickStack](https://github.com/ClickHouse/loom/blob/main/docs/features/integrations/clickstack.md). + + + +### El censo de residuos + +El último paso, `verify.residue`, cuenta las filas activas del ámbito en todas las tablas que tocan las rutas de lectura. Cualquier fila restante hace fallar la saga; la fila terminal lleva `residue_count`, `residue` (por tabla), `verified_at` y `census` (todos los conteos, más abajo). Una saga reanudada vuelve a ejecutar el paso que es dueño de cualquier tabla en la que el último censo encontró filas, aunque su punto de control diga que terminó, y siempre vuelve a contar. + + + +### El comprobante + +`erasure.status` (y la respuesta de `erasure.request`) lleva el comprobante del censo de la última ejecución. `census` es null cuando la última fila del ledger no contiene un censo que haya contado todos los almacenes: una ejecución en curso, un censo que no pudo ejecutarse o dejó un almacén sin contar, o una fila escrita por una compilación que no guarda censo. Los campos del comprobante: + +- `census`: cada sustrato que el censo contó y su conteo, incluidos los ceros. Las claves son nombres de tabla, `pg:
` para la autoridad de Postgres, `objects.document_originals` para el bucket de documentos en un ámbito de espacio de nombres, y `provider_rebuild_copies` sumado sobre las copias de una reconstrucción de proveedor, 0 cuando no existe ninguna (contado en todo el despliegue cuando una copia no tiene columna de organización). Un conteo son las filas que el censo cuenta como residuo en este ámbito: filas activas, o todas las filas cuando la saga purga o la tabla no conserva lápidas ([las reglas del censo](../../architecture/memory-architecture.md#erasure-saga)). `objects.document_originals` cuenta una primera página de listado, así que se lee como "al menos". +- `purge`: el modo de eliminar o marcar con lápida del ámbito (el de un solo espacio de nombres es lápida, se haya pedido lo que se haya pedido); un ámbito que contiene un mirror ([fuentes de documentos](https://github.com/ClickHouse/loom/blob/main/docs/architecture/document-sources.md#the-mirror)) se elimina digan lo que digan estos valores. Sin purga, una fila con lápida conserva sus bytes en su parte hasta que la tabla se fusiona; con purga las filas se eliminan, y sus bytes permanecen en disco hasta que una fusión o el worker de recuperación de espacio los elimina. +- El sujeto y el momento son `org`, `scope_type`, `scope_value` y `verified_at` del estado. + +El comprobante es el conteo de Loom. Conserve la respuesta: `erasure.status` sirve la fila del ledger durante 89 días después de la solicitud, y la fila de auditoría `erasure.completed`, que también lleva el censo, se escribe después de la fila completada, en la medida de lo posible, y se conserva durante `LOOM_RETENTION_AUDIT_LOG_DAYS`. Cuando quien lo solicitó no recibió respuesta (una saga que terminó el worker de recuperación, una ejecutada en segundo plano, una llamada que agotó el tiempo), lea `erasure.status` dentro de los 89 días. + + + +#### Verificar usted mismo un borrado + +Un operador que tenga la concesión de la superficie SQL de la organización con `--namespaces '*'`, o `--all` ([superficie SQL](https://github.com/ClickHouse/loom/blob/main/docs/reference/sql-surface.md#access)), puede volver a contar tres de las claves del censo, `loom.memory`, `loom.memory_versions` y `loom.conversations`, y revisar el ledger de solicitudes (la cuarta sentencia, más abajo). Enlace el id borrado y el momento del censo como parámetros. ClickHouse igualmente escribe los valores enlazados en `system.query_log`, como hace con las sentencias del propio borrado (más abajo), así que ejecute la verificación desde `clickhouse-client` en lugar de hacerlo a través de `pg_clickhouse`, cuyo texto delegado un registro de sentencias de Postgres conservaría como una copia más: + +```bash +read -r uid # the erased id, typed at the prompt so it stays out of the shell history +clickhouse-client --param_org='' --param_uid="$uid" --param_at='' \ + --multiquery --query " +SELECT count() FROM loom.sql_v1_memories WHERE org = {org:String} + AND user_id = {uid:String} AND created_at <= {at:DateTime64(6, 'UTC')}; +SELECT count() FROM loom.sql_v1_memory_history WHERE org = {org:String} + AND user_id = {uid:String} AND created_at <= {at:DateTime64(6, 'UTC')}; +SELECT count() FROM loom.sql_v1_conversations WHERE org = {org:String} + AND user_id = {uid:String} AND ts <= {at:DateTime64(6, 'UTC')}; +SELECT count() FROM loom.sql_v1_agent_events WHERE org = {org:String} + AND user_id = {uid:String} AND ts <= {at:DateTime64(6, 'UTC')};" +``` + +El filtro `org` limita al org de la eliminación una concesión que cubre más de un org (`--all`). +Cada sentencia sigue leyendo todo el alcance de la concesión antes de filtrar ([qué cuesta una lectura](https://github.com/ClickHouse/loom/blob/main/docs/reference/sql-surface.md#what-a-read-costs)), de modo que en un org grande o con una concesión `--all` una sentencia puede detenerse en los límites del usuario SQL (`LOOM_CH_ANALYSIS_MAX_ROWS_TO_READ`, `_MAX_EXECUTION_S`) con un error en lugar de un recuento; súbelos para la comprobación. Para un alcance de espacio de nombres, pasa `--param_ns=''` y filtra las tres primeras por `namespace = +{ns:String}` en lugar de `user_id`; para un `namespace_list`, ejecútalo una vez por cada nombre en los `namespaces` de su `scope_value`; la sentencia `sql_v1_agent_events` es solo para un alcance de usuario, ya que una eliminación de espacio de nombres conserva las filas del registro de solicitudes del espacio de nombres. Cada recuento es 0 después de una eliminación completada, con estas diferencias respecto al censo: las vistas excluyen los espacios de nombres restringidos, `sql_v1_memories` excluye las filas rechazadas y con tombstone, y `sql_v1_memory_history` excluye las versiones rechazadas (conserva las que tienen tombstone), y un resumen consolidado a partir de las memorias del usuario lleva otro `user_id`, que el censo cuenta y estas consultas no. El recuento del registro de solicitudes es una comprobación aparte, fuera del recibo: una eliminación depura las filas del registro de solicitudes de un usuario a `` en lugar de borrarlas, y la vista del registro de solicitudes contiene solo su ventana ([`sql_v1_agent_events`](https://github.com/ClickHouse/loom/blob/main/docs/reference/sql-surface.md#sql_v1_agent_events)), así que confirma la depuración solo para las filas dentro de ella. Cualquier otra clave del censo es solo el recuento de Loom. + +Lo que el recibo no cubre: + +- copias de seguridad, recuperación a un punto en el tiempo, WAL y standbys de cualquiera de los dos servicios; +- copias hechas fuera de Loom, como una tabla creada en el Postgres propio de un org a partir de la [superficie SQL](https://github.com/ClickHouse/loom/blob/main/docs/reference/sql-surface.md); +- filas que un worker escribe después del censo a partir de una lectura que hizo antes ([autoridad de almacenamiento](../../architecture/storage-authority.md#erasure)); +- un `namespace.restore` desde una instantánea tomada antes de la eliminación, que recupera filas: ejecuta la eliminación de nuevo, y su censo es el nuevo recibo; +- para un alcance de usuario, los originales de documentos en el bucket, que el censo cuenta solo para un alcance de espacio de nombres. + +El id eliminado permanece donde la prueba de eliminación lo necesita: en la fila del registro (hasta que el TTL de la tabla la descarta, 90 días después de la solicitud), en la auditoría, en `loom.erasure_reversals` y en los logs propios del despliegue de las sentencias que lo nombraron (el log de mutaciones de ClickHouse, `system.query_log` y `system.text_log` para una sentencia que lo escribió, y los logs de sentencias de Postgres con `log_statement` o `log_min_duration_statement` activados). + + + +### Sagas abandonadas + +Tras 5 intentos el worker marca la solicitud como `failed` de forma definitiva y escribe una fila de auditoría `erasure.abandoned`, con `failure_reason` y `steps_completed`. Entonces una persona debe escalar el caso. `loom erasure-re-verify` vuelve a comprobar las sagas terminales; `--resume` vuelve a ejecutar las fallidas desde su punto de control (`--skip-external` para una saga `namespace_list` cuyo paso externo sigue fallando). `--completed-since ` vuelve a comprobar las sagas completadas verificadas desde entonces en lugar de las fallidas, para las eliminaciones que ejecutó una versión anterior durante una actualización; con `--resume` borra solo los vínculos de filas huérfanas ([mantenimiento](https://github.com/ClickHouse/loom/blob/main/docs/operations/maintenance.md#erasure)). Consulta la [resolución de problemas](https://github.com/ClickHouse/loom/blob/main/docs/operations/troubleshooting.md). + + + +### Operaciones + +| Op | Rol | Qué hace | +| ----------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `erasure.request` | writer (admin sobre el destino) | Ejecuta la saga para un alcance. `urgency` `normal` o `urgent`; `purge`; `external`. | +| `erasure.status` | viewer | El estado de una solicitud, el paso actual, el motivo del fallo y el censo. La eliminación de un usuario solo la responde un admin del org o un admin de plataforma de su org. No figura en los toolsets de MCP. | +| `erasure.list` | viewer | Solicitudes recientes (filtra por `status`), con `steps_completed_count`, `reversals_count`, `residue_count`. | +| `erasure.export` | admin | Los datos de un sujeto como JSON: `memory`, `knowledge`, `conversations` (turnos de transcripción y mensajes guardados), `conversation_threads`, `agent_events`, `audit_log`, cada uno limitado por `section_limit` (por defecto 10,000; `truncated` si se supera), y `conversations` también por `LOOM_ERASURE_EXPORT_CONVERSATION_MAX_BYTES` de texto. Incluye por defecto las filas con tombstone. | + +`erasure.status` y `erasure.list` leen una fila del registro durante 89 días; el TTL de la tabla la descarta a los 90. Listas de campos: [referencia de operaciones](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md#erasure). + + + +### Ejemplo + +```python +from loom import Agent + +async with Agent(org="acme", namespace="support", agent="privacy-desk") as admin: + out = await admin.erasure.request_user_id("u-42", requester="dpo@acme.example") + print(out["status"], out["residue_count"], out["verified_at"]) + if out["status"] != "completed": + print(out["failure_reason"], out["residue"]) +``` + +El `request` del SDK no expone `purge` ni `external`; envíalos por HTTP: + +```bash +curl -sX POST "$LOOM_BASE_URL/v1/erasure.request" \ + -H "Authorization: Bearer $LOOM_API_KEY" -H "Content-Type: application/json" \ + -d '{"org":"acme","scope_type":"namespace_list", + "scope_value":"[\"bench-a\",\"bench-b\"]", + "requester":"ops@acme.example","purge":true,"external":false}' +``` + + + +### Para colaboradores + +Una tabla nueva que pueda contener contenido de memoria necesita un paso de la saga y una entrada del censo (un `Substrate(...)` en `server/erasure/store/census.py` `_CENSUS`), o una línea en `STEP_ONLY_TABLES` con su motivo; si no, falla una prueba unitaria. La saga es `server/erasure/app/saga.py` (`run_saga`), los backends `server/erasure/app/backends.py`, el worker `server/erasure/workers/recovery.py`. + + + +## Límites + +- **No es una garantía de cumplimiento normativo.** La saga, el censo y los hashes de auditoría son primitivas de ingeniería; que cumplan o no una obligación es decisión tuya. +- **Un borrado es lento.** Cada paso espera a una mutación; calcula varios minutos en un ámbito grande. El SDK espera hasta 120 segundos la primera respuesta; después de eso, consulta periódicamente `erasure.status`. +- **No existe el ámbito `org`.** Borra los espacios de nombres de una organización con `namespace_list`. +- **No se puede restaurar desde los TTL de tabla.** Usa la expiración definida por el escritor con `on_expire` cuando el fin de vida deba ser reversible. +- **Las copias de seguridad quedan fuera de la saga**; consulta + [copia de seguridad y recuperación](https://github.com/ClickHouse/loom/blob/main/docs/operations/backup-and-recovery.md). +- **El bucket de exportación de analítica queda fuera de la saga.** Sus archivos contienen nombres hasheados de organización, espacio de nombres y agente, y recuentos de uso, nunca contenido de la memoria; consulta + [nombres hasheados](https://github.com/ClickHouse/loom/blob/main/docs/operations/analytics-export.md#hashed-names). + + + +## Relacionado + +- [Historial y procedencia](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/history-and-provenance.md): `memory.history`, `memory.redact`. +- [Escritura de memoria](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/writing.md): `ttl_seconds`, `valid_to`, `on_expire` en una escritura. +- [Ejecuciones](https://github.com/ClickHouse/loom/blob/main/docs/features/runs.md): `retain` en `run.complete`. diff --git a/i18n/.pending/es/docs/operations/postgres.md b/i18n/.pending/es/docs/operations/postgres.md new file mode 100644 index 0000000000..52fcb9b963 --- /dev/null +++ b/i18n/.pending/es/docs/operations/postgres.md @@ -0,0 +1,246 @@ + +> Esta página es una traducción automática de la [página en inglés](https://github.com/ClickHouse/loom/blob/main/docs/operations/postgres.md), que prevalece. +> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/operations/postgres.md), which is authoritative. + + + +# Autoridad de memoria en Postgres + +Esta guía configura un despliegue de Loom cuyas memorias activas y cabeceras de documentos de conocimiento se almacenan en Postgres, ya sea en ClickHouse Managed Postgres o en un Postgres autoalojado, y explica qué comprobar antes de ponerlo en servicio. El funcionamiento interno se describe en [autoridad de almacenamiento](../architecture/storage-authority.md). + +La autoridad se elige una sola vez, en el primer arranque de un despliegue. Un ClickHouse que ya contiene memorias conserva la autoridad de ClickHouse; inicie un despliegue con Postgres sobre un ClickHouse vacío. + + + +## Requisitos + +- Postgres 16 o superior. No se necesita ninguna extensión. +- Una base de datos y un rol que sea su propietario (Loom crea en ella el esquema `loom`). +- El rol puede ejecutar `pg_logical_emit_message` (por defecto el público puede; de lo contrario, el arranque se rechaza y nombra el `GRANT`). +- Para `LOOM_PG_DURABILITY=synchronous` (el valor por defecto): al menos un standby síncrono + en otro dominio de fallo, de modo que una escritura confirmada sobreviva a la pérdida del primario. +- `wal_level = logical` si la base de datos también alimentará una herramienta de replicación; Loom en sí + no lo necesita. + + + +## Configuración + +| Ajuste | Valor | +| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| `LOOM_STORAGE_AUTHORITY` | `postgres` | +| `LOOM_PG_DSN` | `postgres://loom:@:5432/?sslmode=verify-full&sslrootcert=`, el endpoint directo, nunca un pooler de transacciones | +| `LOOM_PG_POOL_MIN_SIZE`, `LOOM_PG_POOL_MAX_SIZE` | conexiones por proceso de Loom (2 y 20); dimensione `max_connections` para cada proceso de cada réplica | +| `LOOM_PG_DURABILITY` | `synchronous` (se niega a iniciar sin un standby síncrono) o `local` | + +Indique la autoridad de certificación del servidor y exija `sslmode=verify-full`: +comprueba el certificado y el nombre del host, de modo que nada en la ruta pueda +hacerse pasar por la autoridad ni leer la memoria o la contraseña. `require` y los +modos inferiores cifran sin comprobar con quién se habla, y son solo para un servidor +de desarrollo local. + +Loom gestiona su propio pool de conexiones. Apunte `LOOM_PG_DSN` más allá de cualquier +pooler que entregue al cliente una conexión de servidor distinta por transacción +(transaction pooling): las migraciones de Loom mantienen un bloqueo advisory de sesión +y su driver prepara sentencias, y un pooler de ese tipo no conserva ninguna de las dos +cosas entre transacciones. El `LOOM_PG_DSN` de una [celda](../architecture/cells.md) +apunta directamente a Postgres, sin ningún pooler de ningún modo: sus procesos marcan +cada sesión con el parámetro de inicio `loom.tenancy_checked`, que un pooler de sesión +rechaza o descarta (entonces sus triggers de org rechazan las escrituras del propio +Loom para una org de la que la celda no tiene ninguna fila, y la protección +`loom.tenancy` rechaza su fila de tenencia para cada org recién asignada), y +`loom doctor` señala la sesión que lo perdió. Los scripts y los cargadores masivos +nunca deben establecer `session_replication_role = replica` en una celda: omite los +triggers de org y la protección. + +Todas las réplicas del despliegue, y su proceso worker, usan los mismos valores. La +lista completa, con los ajustes de admisión y de entrega, está en la +[referencia de configuración](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md). + + + +## Postgres administrado de ClickHouse + +1. Crea el servicio con **dos standbys de HA**. Con un solo standby el servicio replica de forma asíncrona, y una escritura confirmada se puede perder junto con el primario. +2. Crea la base de datos y el rol, concede al rol `pg_read_all_stats` para que Loom pueda ver qué standbys están conectados, y toma la cadena de conexión **directa**, en el puerto 5432, de los detalles de conexión del servicio, no la del pooler: el pooler del servicio funciona en modo de transacción. +3. Define los [ajustes](#settings) e inicia Loom. Comprueba que `GET /v1/health?include=postgres` informe `postgres.standby` `synchronous`: el arranque rechaza un `synchronous_standby_names` vacío y emite una advertencia cuando hay menos standbys conectados de los que nombra ([qué comprueba el arranque](#what-the-boot-checks)). + +La conmutación por error, la ubicación de los standbys y el aislamiento del antiguo primario son responsabilidad del servicio. En Kubernetes, los valores `postgres` del chart definen los [ajustes](#settings) ([ClickHouse Cloud y Postgres administrado](https://github.com/ClickHouse/loom/blob/main/docs/operations/clickhouse-cloud.md)). + + + +## Postgres autoalojado + +Ejecute Postgres bajo un gestor de HA que mantenga un standby síncrono, aísle (fence) al primario anterior en la promoción y promueva solo un standby que contenga todos los commits confirmados. +Configúrelo en su modo síncrono estricto: se requiere al menos un standby síncrono, y las escrituras se rechazan en lugar de ser confirmadas solo por el primario cuando no hay ninguno conectado. Un gestor que no es estricto vacía `synchronous_standby_names` cuando su standby se desconecta, y entonces el primario confirma los commits por sí solo. + +Loom comprueba la configuración del standby al arrancar, y `GET /v1/health?include=postgres` informa `postgres.standby` mientras está en servicio: `synchronous` cuando los standbys que un commit espera (`n` de `FIRST n`, `ANY n` o `n (...)`, y si no, uno) están conectados; `primary_only` cuando no se nombra ninguno, de modo que solo el primario confirma los commits; `waiting` cuando hay menos conectados, de modo que los commits esperan hasta que lo estén; `null` cuando no se pudo leer el estado, porque Postgres no respondió o el rol no puede ver `pg_stat_replication`. + +Apunte `LOOM_PG_DSN` al endpoint primario del gestor (el servicio o la dirección que sigue al líder), nunca a un único host, de modo que una promoción mueva a Loom con ella. + +Un primario con un standby y sin gestor, como lo inicia `dev/ci_start_postgres.sh` para las pruebas, muestra la configuración: + +```text +synchronous_commit = on +synchronous_standby_names = 'FIRST 1 (loom_standby)' +``` + + + +## Qué comprueba el arranque + +| Comprobación | Se niega a arrancar cuando | +| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Conexión | `LOOM_PG_DSN` está vacío o Postgres no responde | +| Migraciones | se editó un archivo ya aplicado de `schemas/pg_migrations/`, o falta en esta compilación uno anterior al último aplicado | +| Durabilidad | con `LOOM_PG_DURABILITY=synchronous`, `synchronous_standby_names` está vacío; con cualquier valor, el rol no puede ejecutar `pg_logical_emit_message` | +| Autoridad | el despliegue registró la autoridad de ClickHouse, este ClickHouse contiene memoria bajo ella, o este Postgres pertenece a otro despliegue | +| Estado de la celda | falla la primera lectura de las filas de estado de la celda (`loom.cell_first`, `loom.tenancy_mode`, `loom.cell_self`, `loom.tenancy`); con migraciones de Postgres pendientes, el proceso arranca bloqueado y no listo hasta que una lectura se completa ([solución de problemas](https://github.com/ClickHouse/loom/blob/main/docs/operations/troubleshooting.md#a-process-with-loom_cell-unset-is-gated)) | + +Una migración espera como máximo 5 s a un bloqueo de tabla y se intenta cinco veces; un +arranque que registra `Postgres migration waited too long for a lock` cuatro +veces y después falla con `LockNotAvailableError` encontró una transacción larga que +retiene la tabla: termínela (`pg_stat_activity` la nombra) y vuelva a arrancar. Un +arranque que encuentra a otro arranque migrando lo espera, sin límite, y arranca cuando +sus migraciones terminan. + +Cada conexión de Loom establece `synchronous_commit = on` por sí misma, sea cual sea el +valor por defecto del servidor. El arranque emite una advertencia cuando hay menos +standbys conectados de los que un commit espera, y cuando su rol no puede ver +`pg_stat_replication`. Mientras no estén conectados, un commit los espera, hasta +`LOOM_PG_STATEMENT_TIMEOUT_MS` más un segundo, y luego responde 503 +`POSTGRES_UNAVAILABLE` con `outcome_unknown`: la espera cancelada deja el commit solo en +el primario. El worker de entrega lo publica en ClickHouse únicamente cuando los standbys +lo contienen, de modo que una conmutación por error intermedia no deja nada de él en +ClickHouse +([autoridad de almacenamiento](../architecture/storage-authority.md#only-durable-revisions-are-published)). +Un publicador que envía el commit de otra sesión lo vuelve a leer en una transacción que +confirma un mensaje lógico transaccional con el prefijo `loom.durable`, por lo que un +consumidor de captura de cambios de la base de datos recibe uno por cada lectura de ese +tipo; el arranque rechaza un rol que no puede escribir uno. + +`GET /v1/health` informa `storage_authority` y, con Postgres, `pg_ok`; con +`?include=postgres` también un bloque `postgres` con `standby`, `parked_deliveries`, +`parked_audits`, `parked_knowledge_deliveries` y `backlog` (las entregas pendientes y +aparcadas de cada fuente, contadas hasta `LOOM_PG_BACKLOG_COUNT_CAP`, `capped` más allá, +la antigüedad de la más antigua y la de la lectura, +[SLO del pipeline](https://github.com/ClickHouse/loom/blob/main/docs/operations/monitoring.md#pipeline-slos)), sentencias que la respuesta por defecto omite en una sonda de +liveness. `pg_ok` es false cuando una consulta en el pool de peticiones no obtuvo +respuesta en dos segundos, incluida la situación en que todas las conexiones del pool +están ocupadas. `/v1/health/ready` no espera a Postgres: una réplica que no puede +alcanzarlo sigue sirviendo los planos que no lo usan. Responde 503 +`POSTGRES_UNAVAILABLE` para las operaciones de memoria, para toda operación de knowledge +que lee la fila actual de un documento desde su cabeza o la confirma, para la búsqueda y +las lecturas que comprueban cabezas (`knowledge.search`, `knowledge.outline`, +`knowledge.synthesize`), y para las operaciones de datasets, que allí leen o confirman el +catálogo de datasets (`knowledge.dataset_get`, `knowledge.dataset_approve`, +`knowledge.query`). Las operaciones de knowledge que leen o escriben solo en ClickHouse, +como `knowledge.list` y `knowledge.dedup_resolve`, siguen sirviendo. +`knowledge.ingest`, `knowledge.ingest_status` y `knowledge.ingest_cancel` también +responden 503, ya que cada una lee o confirma su trabajo allí (`loom.knowledge_jobs`); una +ejecución detenida por una caída cuenta ese intento y se ejecuta de nuevo cuando Postgres +responde. + +`parked_deliveries` cuenta cada entrega de memoria con un arrendamiento sin fin: +revisiones confirmadas en Postgres que ClickHouse rechazó `LOOM_PG_DELIVERY_MAX_ATTEMPTS` +veces, las versiones reemplazadas cuyo payload borrado no dejó nada que enviar (abajo), y +las entregas que `loom reconcile` retiene (`last_error` `held by loom reconcile`) hasta +que las libera. Una cuyo `targets` no contiene ninguno de 1, 2 y 4 tiene su fila de +memoria en ClickHouse (también su documento de búsqueda cuando le corresponde), su fila de +auditoría allí o en `loom.audit_outbox`, y solo debe retiradas: 8, el registro de su +decisión eliminada, que `decision.chain` sigue sirviendo hasta que se retira; 16, los +vectores de la versión que reemplazó, que la búsqueda sigue encontrando hasta que se +retiran (para una fila `high`, su valla oculta mientras tanto los vectores del modelo en +servicio). Una que agotó sus intentos no se reintenta; su `last_error` en +`loom.memory_deliveries` contiene el tipo del error y su código de ClickHouse, estado HTTP +o SQLSTATE de Postgres, nunca su texto, que podría citar la memoria. Esta sentencia +reintenta una (nunca una retención de reconcile, que `loom reconcile` libera por sí +mismo): + +```sql +UPDATE loom.memory_deliveries SET attempts = 0, held = false, lease_until = now() WHERE … +``` + +Una vez que se ha ejecutado la pasada de [borrado de payloads](../architecture/storage-authority.md#payload-clearing), +una compilación sin `010_revision_delivered_at.sql` no puede enviar una revisión cuyo +payload fue borrado: mientras esa compilación sirve, un reintento las excluye, añadiendo +esto a su `WHERE` (una sonda de clave primaria por entrega): + +```sql +AND NOT EXISTS (SELECT 1 FROM loom.memory_revisions r + WHERE r.org = memory_deliveries.org + AND r.namespace = memory_deliveries.namespace + AND r.seq = memory_deliveries.seq + AND r.row IS NULL) +``` + +Una publicación que termina el proceso del worker (falta de memoria con un valor enorme) +cuenta como un intento cuando la siguiente pasada toma su reclamo (`last_error` +`stopped mid-publish`): al llegar al límite la revisión se aparca o, cuando lo único que +aún debe es su documento de búsqueda, recibe un stub que el worker de embeddings rellena. + +Una publicación que supera el plazo de sentencia de ClickHouse cuenta como fallo propio de +las filas, ya que ClickHouse aún responde: tras una ralentización que aparcó revisiones +sanas, la sentencia de reintento anterior con `WHERE attempts >= …` las reintenta todas. + +Una aparcada con `last_error` `payload cleared, nothing to send` es una versión cuyo +payload borró la pasada de [borrado de payloads](../architecture/storage-authority.md#payload-clearing) +y que una versión posterior de su clave ha reemplazado: ClickHouse sirve la cabeza de la +clave, y el contenido de esa versión ya no existe (una restauración que omitió el +[procedimiento operativo](https://github.com/ClickHouse/loom/blob/main/docs/operations/backup-and-recovery.md#the-postgres-journal-and-a-clickhouse-restore)). Su fila de +auditoría tampoco se envía de nuevo: permanece en el `audit` de la revisión en +`loom.memory_revisions`. Reintentar la entrega no puede tener éxito; una vez anotada, +elimine su fila: + +```sql +DELETE FROM loom.memory_deliveries +WHERE lease_until = 'infinity' AND last_error = 'payload cleared, nothing to send'; +``` + +El worker de entrega de knowledge publica una entrega a la vez, cada retirada por +separado: hasta dos inserciones por entrega y `LOOM_PG_DELIVERY_BATCH_ROWS` entregas por +pasada, dentro de un arrendamiento de `LOOM_PG_DELIVERY_LEASE_SECONDS`, que con un backlog +suele terminar la pasada antes. Una pasada que el fin del arrendamiento interrumpe libera +el resto sin contarlo, y la siguiente pasada las toma. + +`parked_knowledge_deliveries` cuenta los documentos de knowledge confirmados en Postgres +cuya fila de `loom.documents` ClickHouse rechazó `LOOM_PG_DELIVERY_MAX_ATTEMPTS` veces: la +cabeza sirve `knowledge.get` y la búsqueda, que omite los fragmentos de la versión +anterior que ClickHouse lee como vigentes hasta que se ejecuta la retirada de la entrega +([búsqueda de knowledge](../architecture/storage-authority.md#knowledge-search)). La +retirada de un borrado aparcado se ejecuta antes que su fila: `knowledge.get` lo responde +como borrado, la búsqueda no sirve ninguno de sus fragmentos, y `knowledge.restore` +responde 503 mientras una publicación de la fuente aún pueda llegar: hasta que la entrega +aterriza, y durante el límite de inserción después. El barrido de originales conserva el +original que nombra un documento vigente aparcado, y también lo hace el borrado de un +usuario distinto de su autor. Su `last_error` en `loom.knowledge_deliveries` contiene el +tipo y el código del error. Una entrega de un alcance que una compilación anterior borró +durante una actualización progresiva no se reintenta: ejecute primero ese borrado de nuevo +([actualizaciones progresivas](../architecture/rolling-upgrades.md)). Esta sentencia +reintenta una: + +```sql +UPDATE loom.knowledge_deliveries SET attempts = 0, lease_until = now() WHERE … +``` + +`parked_audits` cuenta las filas de `loom.audit_outbox` que ClickHouse rechazó el mismo +número de veces, dejadas allí con su `last_error`: las filas de auditoría de un borrado, y +las que un reclamo aplazó porque el titular al que reemplazó aún puede insertarlas. Esta +sentencia reintenta una: + +```sql +UPDATE loom.audit_outbox SET attempts = 0, due_at = now() WHERE … +``` + + + +## Actualizaciones continuas y rollback + +Cada réplica debe ejecutar una compilación que registre la autoridad. Un despliegue de la autoridad de Postgres no puede volver a una compilación que no la incluya: dicha compilación no lee ningún registro y escribe en `loom.memory` directamente ([actualizaciones continuas](../architecture/rolling-upgrades.md)). + + + +## Copia de seguridad + +Haz la copia de seguridad de Postgres con las herramientas del proveedor o del gestor, y la de ClickHouse con las suyas. Una restauración es de un solo almacén, seguida de `loom reconcile`, que vuelve a ejecutar en él lo que el otro almacén registró después del punto de restauración ([restaurar un solo +almacén](https://github.com/ClickHouse/loom/blob/main/docs/operations/backup-and-recovery.md#restoring-one-store)). Un Postgres de otro despliegue se niega a iniciar. diff --git a/i18n/.pending/ja/docs/operations/backup-and-recovery.md b/i18n/.pending/ja/docs/operations/backup-and-recovery.md new file mode 100644 index 0000000000..995881e2d0 --- /dev/null +++ b/i18n/.pending/ja/docs/operations/backup-and-recovery.md @@ -0,0 +1,261 @@ + +> このページは[英語の原文](https://github.com/ClickHouse/loom/blob/main/docs/operations/backup-and-recovery.md)の機械翻訳です。内容は英語の原文が優先されます。 +> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/operations/backup-and-recovery.md), which is authoritative. + + + +# バックアップとリカバリ + +Loom のバックアップは ClickHouse のバックアップです。カタログのいずれかの行がドキュメントバケット内のオブジェクトを指している間は、そのバケットも対象に含めます。Postgres をオーソリティとして使う場合は、Postgres のバックアップも必要です。 +ClickHouse には、元ドキュメントのカタログ(`loom.document_blobs`。デフォルトのストアではそのバイト列も)、トークンの署名鍵(`loom.signing_keys`)、管理者のランタイムオーバーライド(`loom.runtime_overrides`)が保存されています。次のものは ClickHouse の外にあります。 + +- `LOOM_JWT_SECRET`:ルートシークレットです。保存された認証情報と署名鍵を暗号化しているため、これなしで復元したバックアップでは、どちらも開けません。env 設定とともに保管してください。 +- `var/code_repos` 配下のコードインデックスの git ミラー:ClickHouse に記録されたリモートのキャッシュです。ミラーのないホストは、再度クローンします。 +- `LOOM_DOCUMENT_S3_BUCKET`:`LOOM_DOCUMENT_OBJECT_STORE=s3` の間に書き込まれた元ドキュメントのバイト列を保持します(設定を戻しても、バイト列はそこに残ります)。各オブジェクトの場所は ClickHouse が保持します。 + + + +## バックアップの選び方 + +| 方法 | 対象 | 一貫したスナップショット | 用途 | +| ----------------------------------------------------------------------- | --------------------------------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------ | +| ClickHouse Cloud のバックアップ | サービスのすべてのテーブル | あり(サービス単位) | Cloud でのディザスタリカバリ | +| `BACKUP DATABASE loom TO Disk(...)` / `S3(...)`、または `clickhouse-backup` | すべての `loom.*` テーブル | あり | セルフマネージドの OSS でのディザスタリカバリ | +| `BACKUP DATABASE loom_telemetry TO ...` | SLI ロールアップ(`loom_telemetry.sli_minute`) | あり | 台帳の再フォールドで復元できる 31 日を超えて SLO 履歴を保持する | +| `dev/backup_loom.py` ポータブルダンプ | すべての Loom テーブル(下記) | テーブルごと。テーブル間ではなし | デプロイメント、組織、名前空間の移行(元データはバケット内:[下記](#the-portable-dump))、コールドコピー | +| `namespace.snapshot` | 1 つの名前空間のキュレーション済みメモリ、型、権限付与、監査ログの末尾 | 1 回の呼び出し | API 経由での名前空間のコピーまたは凍結 | + + + +## ポータブルダンプ + +`dev/backup_loom.py` はテーブルごとに 1 つの `JSONEachRow` ファイルを書き出し、続いて `manifest.json` を書き出します。manifest には元のデータベースと、テーブルごとのファイル、行数、バイトサイズ、SHA-256、`CREATE` 文(失敗した場合は停止の原因となったエラー)が記録されます。終了コード 1 はテーブルの失敗(`complete: false`)を、終了コード 2 は不正な引数、ClickHouse の接続先がないこと、または出力先ディレクトリに既にバックアップがあることを表します。 + +データベースのすべての MergeTree ファミリーのテーブルを `system.tables` から読み取ってダンプします。マイグレーションランナーの `_` で始まるテーブル、`.inner` テーブル、KeeperMap のリース(データではなくライブの協調状態)、および `loom migrate` が作成するビューは対象外です。manifest の `backup_version` は 3 です。`--org` は `org` 列を持つすべてのテーブルを絞り込み、その列を持たないテーブル(`idempotency`、`signing_keys` など)はスキップします。これらのテーブルにはすべての org の行が入っています。 + +`dev/restore_loom.py` は、すべてのファイルを manifest と照合して検証し(サイズ、行数、SHA-256)、計画を表示し、記録された `CREATE` 文から対象のデータベースと不足しているテーブルを作成します。その後、各ファイルをそのテーブルのステージングコピーに読み込み、ステージされたパーツをテーブルにアタッチします。アタッチではマテリアライズドビューが発火しないため、復元された行は、バックアップが同じく復元するテーブルに再度コピーされません(そうでなければ `memory_versions` はすべてのバージョンを 2 重に保持します)。また、ビューはライブデータベースへの書き込みに対しては動作し続けます。復元先は、`loom migrate` が準備したデータベース(ビューが存在する)か、スクラッチデータベース(テーブルは記録された DDL から作成される)にしてください。コード化されたベクトルテーブル(記録された `CREATE` に `Quantized(` を含む)を持つバックアップは、何かを書き込む前に拒否されます(`--dry-run` も同様)。これは、復元先のコーデック設定を読み取れない場合、または `enable_quantized_codec` を有効にできない場合です。有効にできる場合でも、`allow_suspicious_codecs` を有効にできないときは、テーブルから `Quantized` の後の汎用コーデックが外されます([制限付き設定](https://github.com/ClickHouse/loom/blob/main/docs/architecture/clickhouse.md#gated-clickhouse-settings))。挿入は `optimize_on_insert = 0` で実行されるため、`ReplacingMergeTree` キーの重複を含め、ダンプされたすべての行が書き込まれ、テーブルは自身のマージで重複をまとめます。各テーブルは、アタッチの前に `… attaching
` を、後に `✓` を表示します。実行が途中で打ち切られた場合、最後の行がそのときのテーブルを示します。`--into-nonempty` で再実行する前に、そのテーブルの件数を確認してください。再実行すると同じ行が再び追加されます。 + +manifest には、挿入で発火する各マテリアライズドビューのソーステーブルとターゲットテーブルが記録されます。アタッチではビューが発火しないため、復元は、ビューの片方の端だけを含む選択を拒否します。`memory` を `memory_versions`(および `memory_code_link_queue`)なしで復元すると、`memory.history`、`memory.redact`、`namespace.rollback` が復元されたバージョンを認識できなくなります。`code_term_freq` を `code_chunks` なしで復元すると、コードの再取り込み時に再び埋められることになります。`documents` と `document_blobs` を結ぶビューはありませんが、復元は片方だけの選択も拒否します。原本のない documents は、ダウンロードのたびに 410 を返します。documents のない原本は、原本スイープが削除する対象です。両ツールは `documents` を他のどのテーブルよりも先に処理するため、`--into-live` でワーカーが動いていても、スイープは、それを参照する document より先に復元された原本の行を見ることがありません(バケットのオブジェクトについては後述)。両方の端を選択するか、復元先に既に行がある場合は `--allow-view-split` を渡してください。`dev/backup_loom.py --exclude t1,t2` は、パスが再構築するテーブルと、ビューがそれらから埋めるすべてのテーブルを除外します(`code_chunks` を除外すると `code_term_freq` と `code_doc_stats` も除外されます)。`restore_loom.py --exclude` はバックアップのテーブルを除外します。 + +ドキュメントの原本(`document_blobs`)はバイナリです。ダンプはそれを生のバイト列として書き出し、`output_format_json_validate_utf8 = 0` を自身で設定するため、UTF-8 を検証するプロファイルでも置き換えられることはありません。バイナリの原本は、ダンプ内で元のサイズの約 1.6 倍になります。 + +`LOOM_DOCUMENT_OBJECT_STORE=s3` で書き込まれた行にはオブジェクトの場所だけが入り、バイト列はバケットにあります。バケットは、そのバケット自身のバージョニングまたはレプリケーションでバックアップしてください。復元は、オブジェクトを参照する ClickHouse バックアップの後に、同じ名前のバケット(各行がその名前を保持しています)へ行うか、両方が戻るまで `LOOM_DOCUMENT_BLOB_GC_ENABLED=false` にして行います。復元されたオブジェクトは古い更新時刻を保持することがあり(復元方法に依存します)、その場合、バケットの走査は、`document_blobs` の行がまだ反映されていないオブジェクトをすべて削除してしまいます。 + +バージョニングされたバケットは、削除されたオブジェクトをすべて非現行バージョンとして保持し、レプリケーションは既定では削除をレプリケートしません。そのため、消去およびスイープされた原本は、ライフサイクルルール(`NoncurrentVersionExpiration`、およびレプリカ側の有効期限)が削除するまで、バケット(またはそのレプリカ)に残ります。このルールの期間が、消去された原本をまだ復元できる期間であり、これは ClickHouse バックアップの保持期間が行に対して持つ意味と同じです。 + +ダンプにはこのような行の原本のバイト列が含まれないため、移行できません。別のデプロイメントに復元された行は元のバケットを指したままで、その消去はバケットとプレフィックスの外にあるものとして拒否され、元のデプロイメントのスイープは、元の行がなくなるとオブジェクトを削除します。また、元のバケットとプレフィックスを指すターゲットは、そのカタログが参照していない元のオブジェクトをすべてスイープしてしまいます。移すには、ターゲットにドキュメントを再アップロードするか、元を停止してデプロイメント全体を移動してください。 + +ステージングコピーはテーブルのエンジンを繰り返しますが、`Replicated` ではないデータベース内のレプリケートエンジンは、同じパラメータのローカル形式になります(コピーがテーブルの Keeper パスを再び要求してしまうためです)。その後、アタッチによってパーツがレプリケートされます。復元が作成するレプリケートテーブルは、記録された Keeper パスを、バックアップ元と同じデータベースでのみ、かつそのパスでレプリケートしているものが他になくなった後でのみ保持します(ライブのレプリカが残っている間は拒否されます)。別のデータベースでは独立したパスになります。サーバーの `default_replica_path` の下に新しい UUID を付けたもの、または Replicated データベースではそのデータベース独自のパスです。その既定値に必要なマクロがサーバーにない場合は拒否されます。 +各実行は、ステージングテーブルを `_restore__
` と名付け、最初に run id を表示し、自分のものだけを削除します。1 つのデータベースへの復元(たとえば 2 つの org)は 1 度に 1 つずつ実行されます。実行は `default._loom_restore_lock_` を要求し(他の実行の要求を最大 5 分待ちます)、ターゲットをもう一度調べ、前の実行が残したものに以下の拒否を適用します。そのため、同じスコープの 2 回目の復元は、最初の行に折り込まれてしまう行をアタッチせずに、拒否されます。この要求は `default` 内のテーブルなので、セルフマネージドクラスタでは同じサーバー経由の実行の順序づけだけを行います。すべての復元を 1 台に向けてください。クラッシュした実行は、ステージングテーブルと要求を残します。その実行のプロセスが残っていなければ、`restore_loom.py --database --drop-staging ` で削除できます。 +挿入のステップより前には何も書き込まれません。`--dry-run` は計画の後で停止します。次のものは拒否されます。 + +- `--into-live` なしでのライブデータベース(`loom`、またはサーバー設定が指定するデータベース) +- `--into-nonempty` なしでの、バックアップのスコープ内で既に行を持つテーブル。挿入は追記なので、通常の MergeTree テーブル(`audit_log`、`agent_events`)はすべての行を 2 重に保持することになります。 + +両ツールはサーバーと同様に ClickHouse の接続先を解決し(環境変数または `.env` の `LOOM_CH_*`。それぞれ `--host`、`--port`、`--user`、`--database`、`--secure` で上書きできます)、ホストが指定されていない場合は実行を拒否し、パスワードは `LOOM_CH_PASSWORD` からのみ読み取ります。 + +```bash +python dev/backup_loom.py --out-dir ./backups/$(date +%F) [--org acme] [--tables memory,namespaces] +python dev/restore_loom.py --in-dir ./backups/ --database loom_restore --dry-run +python dev/restore_loom.py --in-dir ./backups/ --database loom_restore --skip-idempotency +python dev/restore_loom.py --in-dir ./backups/ --into-live \ + --tables memory,memory_versions,memory_code_link_queue # one end of a view needs the other +./scripts/ops/backup_drill.sh [--full-restore] # round-trip check into a scratch database +``` + +`scripts/ops/backup_drill.sh` はライブデータベースを一時ディレクトリにダンプし、manifest を行数のスナップショットと照合します。`--full-restore` を付けるとスクラッチデータベース `_drill` に復元し、すべてのテーブルの行数を比較し、終了時にスクラッチデータベースを削除します。同じキーの行をまとめるテーブル(`ReplacingMergeTree`、`AggregatingMergeTree` など)は、アタッチの直後にスクラッチデータベース内でマージされることがあります。そこでの行数の減少は、マージが実行された後なら警告、そうでなければ失敗です。このスクリプトはライブデータベースを読み取るだけです。ドリルは定期的に実行してください。 + +ダンプはテーブルごとのもので、テーブル間のスナップショットではありません。クラスタ間でデータを移すために使い、ディザスタリカバリには使わないでください。 + + + +## リストア後の監査ログの検証 + +`python dev/verify_audit_chain.py [--org X] [--ts-since YYYY-MM-DD] [--json]` は、すべての `audit_log` 行のコンテンツハッシュを再計算します。不一致があれば終了コード 1 で終了し、検証を実行できなかった場合(不正な引数、対象なし、クエリの失敗)は 2、それ以外は 0 で終了します(行が 0 件の場合も成功として扱います)。不一致のレポートでは、行をパーティション、タイムスタンプ、リクエスト ID で示し、アクター、サブジェクト、名前空間は示しません。`audit_verifier` ワーカーは、同じ行単位のチェックをスケジュールに従って実行します。このチェックは行単位の改ざん検出であり、行にわたるハッシュチェーンではありません。1 時間ごとのチェックポイントは別途チェーンされています([監査](https://github.com/ClickHouse/loom/blob/main/docs/features/observability/audit.md))。 + + + +## 名前空間内の変更の取り消し + +これらの操作は、誤った書き込み、誤動作したエージェント、誤ったインポートを、ClickHouse のリストアなしで取り消します。いずれも 1 つの名前空間を対象とします。`namespace.snapshot`、`namespace.restore`、`namespace.rollback` は MCP の `all` 一覧に含まれません。名前を指定するか HTTP 経由で呼び出すか、[ダッシュボード](https://github.com/ClickHouse/loom/blob/main/docs/features/dashboard.md)の Health → Repairs タブを使用してください。このタブでは、名前空間の管理者がスナップショットのダウンロード、リストア、ロールバックを行えます。 + +| 操作 | ロール | 内容 | +| -------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `memory.restore` | `WRITER` | トゥームストーン化された 1 つのキーを元に戻します | +| `namespace.snapshot` | `ADMIN` | 名前空間のメモリ、型、グラント、監査ログの末尾(`include_audit_tail_n`、デフォルトは 1000)を JSON ペイロードとして固定します。`include_embeddings=false`(デフォルト)の場合、ターゲット側は自身のモデルで再埋め込みを行います | +| `namespace.restore` | 新規ターゲットでは `VIEWER`、既存ターゲットでは `ADMIN` | スナップショットのペイロードを `target_namespace` に書き込みます(任意で `rebind_agent` を指定できます)。`snapshot_id` により冪等です。行は `version`、`content_sha256`、およびアテステーションのカラムを保持するため、`verified_by` は残ります。カラムに格納できない値(UUID ではないメモリ ID など)がペイロードにある場合は 422 で拒否されます。コレクションは拒否されます。そのスナップショットは通常の名前空間にリストアします | +| `namespace.rollback` | `ADMIN` | すべてのメモリヘッド(または `memory_keys`)を `as_of` 時点のバージョンに戻します。古いバージョンを新しいヘッドとして復元し、それ以降に作成されたキーはトゥームストーン化します。デフォルトはドライランです(適用するには `dry_run=false`)。1 回の呼び出しで処理するのは最大 `max_keys` 件です(再度呼び出すべきかどうかは `truncated` が示します) | + +Postgres オーソリティの下では、消去によってターゲットから削除されたメモリは、その[削除エビデンス](../architecture/storage-authority.md)が保持されている間、リストアの対象から除外され、`counts.erased_skipped` に計上されます。エビデンスは、消去によってそのメモリが削除された名前空間のみを対象とします。そのため、消去前のスナップショットを別の場所にリストアすると、消去されたメモリが復活します。そのようなリストアの後は、同じ消去(そのスコープ)を再実行してください。 + +`namespace.rollback` と `memory.history` は `loom.memory_versions` を読み取ります。これは `loom.memory` へのすべての挿入を記録する追記専用のミラーです(マージでは、置き換えられたバージョンが `loom.memory` 自体から削除されます)。ロールバックの動作は次のとおりです。 + +- 名前空間の履歴より古い、または未来の `as_of` は拒否します。 +- ハード削除されたキーはスキップします(`skipped_no_head`)。 +- 復元されたヘッドの再埋め込みは、埋め込みワーカーに任せます。 + +```bash +AS_OF=$(date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%SZ) # GNU date; the instant before the bad writes +curl -s -XPOST http://localhost:7777/v1/namespace.rollback -H "Authorization: Bearer $ADMIN_TOKEN" \ + -H 'Content-Type: application/json' \ + -d '{"org":"acme","namespace":"support","as_of":"'"$AS_OF"'"}' | jq '{dry_run, reinstate, remove, truncated}' +``` + + + +## Postgres を権威とする場合 + +`LOOM_STORAGE_AUTHORITY=postgres` では、ライブメモリ、そのリビジョンジャーナル、ナレッジヘッド、取り込みジョブ、データセットカタログが Postgres にあり([ストレージ権威](../architecture/storage-authority.md))、デプロイメントでバックアップすべきストアは Postgres と ClickHouse の 2 つになります。 + +| ストア | 単独で保持するもの | RPO | バックアップ手段 | +| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | +| Postgres | すべてのメモリヘッドとリビジョン、ナレッジヘッド、取り込みジョブ、データセットカタログ、冪等性の応答 | 同期スタンバイへのフェイルオーバーをまたいでも、確認応答済みの書き込みについては 0。ポイントインタイムリストアでは、そのポイント以降の内容が失われます | HA マネージャーまたはサービスのベースバックアップと WAL アーカイブ | +| ClickHouse | 検索ドキュメントとベクトル、ナレッジドキュメントおよび長いメモリ値のチャンク、Postgres が保持する範囲を超えた履歴、アナリティクス、トレース、監査行 | ClickHouse のみが保持するものについては、最後のバックアップからの経過時間。Postgres が保持するメモリリビジョンとナレッジドキュメントは再公開されますが、そのチャンクとデータセットの行は再公開されません。`loom reconcile` は再チャンク化すべき各ナレッジソースを示し、20 を超える場合はその名前空間(`loom rechunk`)を示し、あわせて再取り込みすべき各ソースを示します。長いメモリ値は、再設定されるまで抜粋で検索可能です | 上記の方法 | + +リストアの復旧時間は、ストア自体のリストア時間に `loom reconcile` の実行時間を加えたものです。この実行は、リストアされたストアが失った、もう一方のストアの記録を再実行します。 + + + +### 片方のストアのリストア + +`LOOM_PG_PAYLOAD_CLEAR_ENABLED` を有効にした状態で ClickHouse をリストアする前に、ペイロードのクリアを停止し、[Postgres ジャーナルと ClickHouse のリストア](#the-postgres-journal-and-a-clickhouse-restore)の説明に従ってバックアップを選んでください。クリア処理が一度でも実行された場合は、手順 3 の `loom reconcile` を `010_revision_delivered_at.sql` を含むビルドで実行し、手順 4 でもそのビルドでデプロイメントを起動してください(ローリングアップグレードの[ルール 43](../architecture/rolling-upgrades.md#the-rules))。そのうえで次を行います。 + +1. デプロイメントのすべてのサーバーとワーカーを停止します。 +2. バックアップからストアをリストアし、バックアップ自体のメタデータからバックアップ時刻を控えます(ClickHouse では `BACKUP` の開始時刻、Postgres ではリカバリターゲット)。 +3. `loom reconcile --restored clickhouse --point