attention-manifest-protocol 0.4.5 → 0.5.0

package/CHANGELOG.md

@@ -5,24 +5,54 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
 project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.5.0] - 2026-11-03
+
+### Added
 
-## [0.4.5] - 2026-10-31
+- Eight canonical scoped control tools for registry metadata, defaults, interaction and scenario settings across global, workspace and session scopes; host-bound identities, CAS, dry-run and atomic session batches.
+- SQLite workspace ownership, default workspace selection, inherited settings and v4-to-v5 migration, with authenticated runtime settings applied on the next turn.
+- Elasticsearch catalog search with independent immutable snapshot indices, verified namespace ownership, SQLite publication CAS, retryable timeout/restart recovery and guarded Catalog SQL writes.
+- Environment defaults, typed catalog projections and serial module boundary audit reports.
+
+### Changed
+
+- **Breaking:** workspace/global discover now requires `queries` and asynchronous calls, returning a separate relation tree for each match. Migrate from the old `text`/`scope` filter arguments; configure and synchronize the host search backend before discovery.
 
 ### Fixed
 
-- Bound discovery tree construction and subtree lookahead under small output limits, deep or cyclic input, and exhausted traversal budgets; extensionless file filters now work consistently.
-- Enforced filesystem session read/write/create permissions across MCP tools, sanitized classified failures, and kept stdio sessions alive after malformed or escaping requests.
-- Checked excluded paths against case-folded Windows paths and resolved symlink targets; preserved selected-root routing for multi-root outlines and dependency graphs.
-- Applied session and service read/tree/graph budgets consistently and report truncation instead of returning incomplete results as complete.
+- Isolate session root storage while preserving public root IDs; prevent stale session registries from reviving revoked credentials, authentication reentry and revision overflow.
+- Reject hidden JSON callbacks and mutable protocol schemas; enforce workspace ownership even when a stdio host is configured with search only.
+
+### Validation
+
+- Joint functional and boundary regression: 366/366; final audit recheck: 48/48; source/tools typechecks, library build and patch checks passed. Real Elasticsearch 9.2.0 single-node faults were previously verified 9/9; fixture tests are reported separately.
+- Known repository limitation: the architecture check still fails on coexisting legacy dashed and camelCase scripts; it is excluded from the functional counts above.
+
+## [0.4.6] - 2026-11-02
+
+### Added
+
+- Host-owned `SkillRegistry`, `KnowledgeRegistry` and `ProtocolRegistry` with validated registration, duplicate rejection, defensive copies and deterministic listing.
+- Metadata-only `skills`, `knowledge` and `protocols` discovery scopes, with registry injection through workspace and global agent services. Disabled skills and protocols are excluded from discovery.
 
 ### Changed
 
-- Standardized TypeScript tool filenames on lowerCamelCase and updated repository documentation and references.
-- Advanced the npm package version to 0.4.5.
+- Share in-memory registry storage and query mechanics through `InMemoryRegistry` while keeping validation and list policies in each domain.
+
+### Fixed
+
+- Reserve discovery node capacity for ancestors before visiting descendants so tight limits preserve tree structure and accurate summary counts.
+
+## [Unreleased]
 
 ### Added
 
+- Elasticsearch search module using the official SDK, explicit strict index mapping, scoped metadata search, full snapshot synchronization and defensive response projection.
+- Unified catalog entities, directed relations, cache, service, repository and SQLite tables with atomic snapshot replacement, persistent synchronization generations and retryable dirty states.
+- Workspace/global discover now accepts one or multiple `queries` and returns a separate bounded relation tree for every matching root; services, executors and MCP support asynchronous search. This replaces the previous discover tool filter schema.
+- Typed catalog projections for workspace, host projects/components, skills, knowledge, protocols, environments and generic module records; SDK wire, SQLite, projection and multi-tree isolation checks.
+- Explicit environment defaults for runtimes, applications, languages and project types, backed by `HostCatalog`, with category/availability metadata and links.
+
 - `amp_tool_workspace_project`: offline brand detection from manifest/lockfile evidence (npm/pnpm/yarn/bun, Maven, Gradle, CMake, Cargo, Go, Python, Make, Composer, .NET, Bundler, Swift, sbt) plus host-delegated `build`/`compile`/`run`/`test`. The agent never supplies a command string; the brand table produces one and `WorkspaceServiceOptions.runner` decides whether to run it (`run_unavailable`, `unsupported_action`, bounded tail of stdout/stderr).
 - `amp_tool_workspace_outline`: one cascading project → directory → file → symbol/knowledge outline with 1-based ranges, bounded `maxDepth`/`limit`, `childCount`, `includeSymbols` and path/extension filters.
 - `amp_tool_workspace_dependency`: project-level `project_depends_on` dependencies and dependents with the declaring source, method and paginated project list.
@@ -33,8 +63,8 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - Agent workspace: a `File`/`Directory` tree, paged reads, CAS atomic writes, strategy-based outlines, import/export/dependency graphs and Office parsing (DOCX/XLSX/PPTX, with best-effort DOC/XLS/PPT/PUB/ACCDB).
 - Session module: `ses_` identity, one-time bearer token, TTL, suspend/revoke/rotate, fork, per-session context isolation and quotas; SQLite adapters `SqliteWorkspaceSessionStore` / `SqliteWorkspaceSessionContextStore`.
 - `src/hook`: `useRead`, `useWrite`, `useDiff`, `useParse`, `useDependency`, `useExportation`, `useImportation`, `useOutline`, `useCode`, `useProject`. Every hook is read-only except `useWrite`, and runs are recorded in `hook_runs`.
-- `amp_tool_file_*` (ten tools), the `amp_tool_globalfs_*` global naming adapter, and `amp_service_filesystem` / `amp_protocol_filesystem`.
-- Lossless read-only syntax trees: `amp_tool_file_ast`, `useAst`, `src/syntax/syntaxTree.ts` and `src/syntax/syntaxRegistry.ts`; languages, token kinds and node kinds are registry data, every token keeps UTF-8 byte and line ranges, and the target file is never executed.
+- `amp_tool_filesystem_*` (ten tools), the `amp_tool_globalfs_*` global naming adapter, and `amp_service_filesystem` / `amp_protocol_filesystem`.
+- Lossless read-only syntax trees: `amp_tool_filesystem_ast`, `useAst`, `src/syntax/syntaxTree.ts` and `src/syntax/syntaxRegistry.ts`; languages, token kinds and node kinds are registry data, every token keeps UTF-8 byte and line ranges, and the target file is never executed.
 - SQLite tables: `workspace_sessions`, `session_roots`, `session_context`, `file_nodes`, `file_annotations`, `file_writes`, `file_outlines`, `file_imports`, `file_exports`, `file_dependencies`, `hook_runs`.
 - Data structures: `Trie`, `ByteLineIndex` (segment-tree prefix sums) and `OutlineIndex` (AST + Trie + SegmentTree).
 - Outline strategies cover code (TS/JS/Python/Java/C/C++/C#/Go/Rust), Vue, project manifests (npm/Maven/Gradle/CMake/Cargo/Go/pyproject/Make), prose (Markdown/TeX/plain text), HTML/CSS/SCSS/Sass/XML/OPML and Office; `outlineCoverageCheck` verifies 74 cases.

package/CHANGELOG.zh-CN.md

@@ -5,29 +5,59 @@
 格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，版本号遵循
 [语义化版本](https://semver.org/lang/zh-CN/)。
 
-## [未发布]
+## [0.5.0] - 2026-11-03
+
+### 新增
 
-## [0.4.5] - 2026-10-31
+- 八个规范作用域控制工具，覆盖 global/workspace/session 的注册元数据、默认值、交互和情景配置；提供宿主固定身份、CAS、dry-run 和原子 session 批处理。
+- SQLite workspace 归属、默认 workspace、配置继承及 v4→v5 迁移；已认证配置从运行时下一轮生效。
+- Elasticsearch 统一目录检索、独立不可变快照索引、namespace 归属验证、SQLite 发布 CAS、超时/重启可重试和 Catalog SQL 写入防护。
+- Environment 默认目录、类型化目录投影与串行模块边界审计报告。
+
+### 变更
+
+- **不兼容变更：** workspace/global discover 改用 `queries` 与异步调用，每个命中返回独立关系树；需迁移旧 `text`/`scope` 参数，并由宿主配置和同步搜索后端。
 
 ### 修复
 
-- 对小输出限额、深层或循环输入以及遍历预算耗尽场景限制 discovery 树构建和子树探测；无扩展名文件过滤现在保持一致。
-- 在 MCP 工具中落实 filesystem session 的读取、写入和创建权限，统一错误分类并隐藏主机路径；畸形或越界请求后 stdio 会话仍可继续处理。
-- 路径排除检查覆盖 Windows 大小写折叠及符号链接真实目标；多根 workspace 的大纲和依赖查询保持所选根目录。
-- 一致执行 session 与 service 的读取、目录树和依赖图预算；结果截断时明确标记，不再伪报完整。
+- 保留公开 root ID 并隔离 session root 存储；阻止旧 registry 复活撤销凭据、认证重入及 revision 溢出。
+- 拒绝隐藏 JSON 回调和可变协议 schema；search-only stdio 宿主同样校验已有 workspace 归属。
+
+### 验证
+
+- 联合功能与边界回归 366/366，最终审计复核 48/48；源代码/工具类型检查、库构建及补丁检查通过。真实 Elasticsearch 9.2.0 单节点故障此前通过 9/9，与 fixture 测试分别记录。
+- 已知仓库限制：旧连字符脚本与 camelCase 脚本并存导致架构检查失败，未计入上述功能测试通过数。
+
+## [0.4.6] - 2026-11-02
+
+### 新增
+
+- 宿主维护的 `SkillRegistry`、`KnowledgeRegistry` 与 `ProtocolRegistry`，支持登记校验、重复 ID 拒绝、防御性副本与稳定列表。
+- 只返回元数据的 `skills`、`knowledge`、`protocols` 发现范围，并贯通 workspace/global agent 服务的注册中心注入；发现时排除禁用的 skill 与 protocol。
 
 ### 变更
 
-- TypeScript 工具文件名统一为小写开头的 camelCase，并更新仓库内路径引用和文档。
-- npm 包版本升至 0.4.5。
+- 通过 `InMemoryRegistry` 复用内存存储与查询机制，各领域保留独立校验和列表策略。
+
+### 修复
+
+- 发现树先为祖先预留节点容量，紧凑预算下仍保留树结构并准确统计节点。
+
+## [未发布]
 
 ### 新增
 
+- 官方 Elasticsearch SDK 搜索模块：显式 strict 索引映射、项目范围元数据搜索、全量快照同步和防御性响应投影。
+- 统一目录实体、定向关系、缓存、服务、仓储与 SQLite 表，提供原子快照替换、持久同步 generation 和可重试的 dirty 状态。
+- workspace/global discover 改为接收一个或多个 `queries`，每个命中根条目独立返回有界关系树；服务、执行器和 MCP 支持异步搜索。旧 discover 工具过滤参数已移除。
+- workspace、宿主项目/组件、skills、knowledge、protocol、environment 及通用模块记录的类型化投影，以及 SDK、SQLite、投影和多树隔离检查。
+- 基于 `HostCatalog` 的 environment 默认目录，覆盖运行时、应用、语言与项目类型，支持显式加载和关联元数据。
+
 - Agent 工作区：`File`/`Directory` 树、分页读、CAS 原子写、策略化大纲、import/export/dependency 图与 Office（DOCX/XLSX/PPTX，DOC/XLS/PPT/PUB/ACCDB best-effort）解析。
 - Session 模块：`ses_` 身份、一次性 bearer 令牌、TTL、暂停/撤销/rotate、fork、每会话上下文隔离与配额；SQLite 适配器 `SqliteWorkspaceSessionStore` / `SqliteWorkspaceSessionContextStore`。
 - `src/hook` 组合层：`useRead`、`useWrite`、`useDiff`、`useParse`、`useDependency`、`useExportation`、`useImportation`、`useOutline`、`useCode`、`useProject`；除 `useWrite` 外只读，并记录 `hook_runs`。
-- `amp_tool_file_*` 十个工具与 `amp_tool_globalfs_*` 全局命名适配器；`amp_service_filesystem` / `amp_protocol_filesystem`。
-- 无损只读语法树：`amp_tool_file_ast`、`useAst`、`src/syntax/syntaxTree.ts` 与 `src/syntax/syntaxRegistry.ts`；语言/Token/节点类别由注册中心管理，全部 token 保留 UTF-8 字节与行范围，不执行目标文件。`syntaxTreeCheck` 8 例，完整 verify 135/135。
+- `amp_tool_filesystem_*` 十个工具与 `amp_tool_globalfs_*` 全局命名适配器；`amp_service_filesystem` / `amp_protocol_filesystem`。
+- 无损只读语法树：`amp_tool_filesystem_ast`、`useAst`、`src/syntax/syntaxTree.ts` 与 `src/syntax/syntaxRegistry.ts`；语言/Token/节点类别由注册中心管理，全部 token 保留 UTF-8 字节与行范围，不执行目标文件。`syntaxTreeCheck` 8 例，完整 verify 135/135。
 - SQLite 表：`workspace_sessions`、`session_roots`、`session_context`、`file_nodes`、`file_annotations`、`file_writes`、`file_outlines`、`file_imports`、`file_exports`、`file_dependencies`、`hook_runs`。
 - 数据结构：`Trie`、`ByteLineIndex`（SegmentTree 前缀和）、`OutlineIndex`（AST + Trie + SegmentTree）。
 - 大纲策略覆盖代码（TS/JS/Python/Java/C/C++/C#/Go/Rust）、Vue、项目清单（npm/Maven/Gradle/CMake/Cargo/Go/pyproject/Make）、文章（Markdown/TeX/plain text）、HTML/CSS/SCSS/Sass/XML/OPML 与 Office；`outlineCoverageCheck` 74 例逐项验证。

package/README.md

@@ -2,7 +2,7 @@
 
 **English** · [简体中文](README.zh-CN.md) · [Changelog](CHANGELOG.md)
 
-AMP is a metacognitive protocol for agents: declare knowledge and obligations, allocate finite attention, obtain evidence, and record costs and outcomes. The reference implementation is version `0.4.5`, requires **Node.js 24 or later**, and uses Apache-2.0.
+AMP is a metacognitive protocol for agents: declare knowledge and obligations, allocate finite attention, obtain evidence, and record costs and outcomes. The reference implementation is version `0.4.2`, requires **Node.js 24 or later**, and uses Apache-2.0.
 
 ## Architecture
 
@@ -53,20 +53,74 @@ Offline parsers live in `tools/support/`. The runtime stays database-free and us
 
 ### Discovery
 
-`amp_tool_workspace_discover` returns one structural tree over the authorized projects. File nodes carry a module kind (`service`, `tool`, `controller`, `route`, `repository`, `model`, `config`, `test`, `middleware`, `component`, `util`), an extension and bounded content matches. Hosts register project descriptions, purposes, summaries, plugins, services and tools through `HostCatalog`; project metadata is attached to project nodes, and an unregistered project falls back to its workspace summary. Discovery is read-only, never widens `projectIds`, and returns snippets as discovery evidence rather than as a Frame-allocated detail read.
+`amp_tool_workspace_discover` and its global counterpart search a unified catalog through Elasticsearch. Pass `queries` as one string or up to eight strings. Each matching entry becomes the root of a separate structural tree, so a single query can return multiple trees. The response is `{ trees: [{ query, tree, total, totalRelation, took, timedOut, truncated }] }`; no matches produce an empty `trees` array. Each tree contains current metadata and `children` expanded from SQLite entity relations, without skill instructions or knowledge bodies. `limit` bounds hits per query; `maxDepth` and `nodeLimit` bound each tree. Optional `kinds` and `tags` filter metadata. Hosts project `HostCatalog`, `SkillRegistry`, `KnowledgeRegistry` and `ProtocolRegistry` entries into `CatalogRecord`; other modules use the same record and relation contract.
+
+The catalog follows `entity → cache → service → repository → SQL → SQLite`. SQLite stores complete entries, directed relations and synchronization generations; Elasticsearch stores a rebuildable search projection. Hosts explicitly synchronize after snapshot changes. Failed builds or concurrent catalog updates leave the index dirty, and discover refuses stale results. Hits and every related node are checked against service-owned project authorization and workspace revision; global records are controlled by `includeGlobal`. Discovery grants no detail-read or execution access. `buildDiscoveryTree` remains available as a local structure-building API.
+
+These registries are domain-owned catalogs, not a mandate to duplicate every concept as a generic registry. Existing runtime state and policies for ability, cognition, progress and behavior should stay in their domain models; add a read-only catalog/discovery projection only when enumeration is needed. Agents should not write directly to active registries by default. A future contribution flow should create a sourced, versioned proposal and require host authorization, review and audit before activation.
+
+The `environment` module describes runtimes, applications, languages and project types as `HostCatalog` modules. `category` is `runtime`, `application`, `language` or `projectType`; `availability` is `unknown`, `available` or `unavailable`, independent of the component lifecycle `status`. Optional `platforms`, `extensions`, `relatedIds`, `skillIds`, `knowledgeIds`, `toolIds` and `protocolIds` link metadata without granting execution access. Hosts explicitly confirm availability; catalog registration does not install software or probe the machine.
+
+```ts
+import { HostCatalog, loadDefaultEnvironments, WorkspaceAgentService } from "attention-manifest-protocol";
+
+const host = new HostCatalog();
+loadDefaultEnvironments(host);
+// Project host into the catalog, synchronize Elasticsearch, then inject search into the service.
+// Discover with { revision, queries: "runtime", kinds: ["module"] }.
+```
+
+Defaults cover PowerShell 7/Windows PowerShell 5.1, sh/bash/zsh, Word/Excel/PowerPoint/Publisher/Access/Microsoft Project, common programming languages and project types such as npm/Maven/CMake. All defaults start with `availability: "unknown"`. `getDefaultEnvironments()` returns independent definitions; `loadDefaultEnvironments(host)` returns only newly added entries and skips existing IDs, preserving host overrides. Register host-confirmed entries before loading defaults. Category, availability and platform metadata enter the search projection and can be searched through `queries`, with `kinds: ["module"]` restricting the entry type. Local `buildDiscoveryTree` retains category and availability filters.
+
+Host wiring example (requires a running Elasticsearch 9 service; `index` is the prefix for independent namespace snapshots):
+
+```ts
+import { CatalogSearch, projectSearchRecords, WorkspaceAgentService } from "attention-manifest-protocol";
+import { Database } from "attention-manifest-protocol/database/service";
+
+const database = new Database("catalog.sqlite");
+const search = CatalogSearch.create({
+    namespace: "host-catalog",
+    catalog: database.catalogService,
+    cache: database.catalogStore,
+    elasticsearch: {
+        connection: { node: "http://127.0.0.1:9200" },
+        index: "amp-host-catalog",
+    },
+});
+search.replaceSnapshot(projectSearchRecords({
+    namespace: "host-catalog", revision: snapshot.revision,
+    workspace: snapshot.entities, relations: snapshot.relations,
+    projects: host.projects(), host: host.components(),
+    skills: skills.list(), knowledge: knowledge.list(), protocols: protocols.list(),
+    // records: [...CatalogRecord entries provided by other modules]
+}));
+await search.sync();
+const service = new WorkspaceAgentService({ ...options, snapshot, search });
+const response = await service.callAsync("amp_tool_workspace_discover", {
+    revision: snapshot.revision, queries: ["repository", "runtime"],
+    limit: 10, maxDepth: 3, nodeLimit: 50,
+});
+// Multiple roots and their relation trees can share the same query in response.data.trees.
+// On shutdown: await search.close(), then database.close().
+```
+
+`replaceSnapshot` replaces the complete namespace snapshot, pruning removed entries and outgoing relations. Its synchronous SQLite SAVEPOINT never spans network awaits. Each `sync` creates a separate namespace-owned concrete index, verifies its contents and write block, then publishes its index/digest/generation through a SQLite epoch CAS. A later attempt fences an earlier build, so failed or timed-out builds can be retried immediately; late remote writes affect only their unpublished indices. Configured indices and aliases are not cleared or adopted. Discovery rechecks concrete index ownership, the write block, document count and content digest before and after its search, and checks SQLite generation again before returning. `CatalogSearch` queues its own synchronization and discovery, while independent coordinators use separate builds and publication CAS. Sync cancellation and timeout include queue wait. Commit any outer SQLite transaction before synchronizing or searching, and do not open one on the shared connection while an operation awaits Elasticsearch. Failed attempts and older snapshots can leave unused indices; hosts manage their retention without deleting a currently published index or an active build. The write block and namespace marker do not isolate a privileged Elasticsearch administrator who can remove or alter them. Hosts configure SDK connection, authentication and TLS through `connection`; credentials do not enter the catalog. Without search configuration, discover returns `search_unavailable`; synchronous `call` returns `async_required` when search is configured. MCP integrations use `handleAsync`. Old discover tool parameters such as `text` and `scope` have been removed.
+
+Scoped control adds eight canonical tools: global/workspace `adjust`, and global/workspace/session `interaction` and `scenario`. Host-bound identities, persistent workspace isolation, inherited settings, CAS, dry-run and stdio configuration are documented in [the scoped control guide](docs/scoped-control.zh-CN.md).
 
 ## Quick start
 
 ```sh
 npm ci
 npm run build
-npm run verify
-npm run scenario
+npm run build:lib
+node --test tools/controlProtocolCheck.ts tools/controlPersistenceCheck.ts tools/controlIntegrationCheck.ts
 ```
 
 ## Library usage
 
-`npm install attention-manifest-protocol` ships the compiled ESM build in `lib/` with its declarations, alongside the source, JSON Schemas and executable checks. Node.js 24 or later is required. The root entry exposes the documented protocol surfaces; every module is also reachable as a subpath.
+`npm install attention-manifest-protocol` ships the compiled ESM build in `lib/` with its declarations, JSON Schemas and the scoped control guide. Source and executable checks are available in the GitHub repository. Node.js 24 or later is required. The root entry exposes the documented protocol surfaces; every module is also reachable as a subpath.
 
 ```js
 import { generateSigningKey, signManifest, verifyManifest } from "attention-manifest-protocol";
@@ -85,7 +139,7 @@ import { ToolIds, parseId } from "attention-manifest-protocol/naming";
 
 `npm run build:lib` rebuilds `lib/` and `prepublishOnly` runs it before publishing. The build compiles only the library; the Vite demo entry (`src/main.ts`) is not part of it.
 
-Focused checks can be run directly with the corresponding camelCase tools, such as `node tools/workspaceAgentCheck.ts`, `node tools/workspaceProjectCheck.ts`, `node tools/workspaceDiffCheck.ts`, `node tools/workspaceReactiveDiffCheck.ts`, `node tools/discoverCheck.ts` and `node tools/discoverAgentCheck.ts`. `verify` runs the full chain and both type checks. Evaluation inputs/reports remain in [docs/eval](docs/eval/) and [docs/probes](docs/probes/) as JSON; fixture and recorded-probe results are not independent human studies or production-quality evidence.
+Focused checks: `npm run workspace-agent-check`, `workspace-project-check`, `workspace-diff-check`, `workspace-reactive-diff-check` and the `workspace-*-boundary-check` suites, `workspace-context-check`, `document-context-check`, `tex-context-check`, `governance-check`, `assignment-check`, `interaction-binding-check`, `discover-check`, `discover-agent-check`, `typecheck` and `typecheck:tools`. `verify` runs the full chain and both type checks. Evaluation inputs/reports remain in [docs/eval](docs/eval/) and [docs/probes](docs/probes/) as JSON; fixture and recorded-probe results are not independent human studies or production-quality evidence.
 
 ## Agent tools
 
@@ -116,20 +170,20 @@ The `amp_protocol_workspace` v1 response contains `protocol`, `version`, `revisi
 
 ### Filesystem tools
 
-`amp_tool_file_*` is bound to one authenticated Session; the bearer token never appears in a tool argument. Every tool except `write` is read-only.
+`amp_tool_filesystem_*` is bound to one authenticated Session; the bearer token never appears in a tool argument. Every tool except `write` is read-only.
 
 | Tool | Purpose |
 | --- | --- |
-| `amp_tool_file_session` | Current identity, roots, permissions, remaining TTL and quotas |
-| `amp_tool_file_file` | One File/Directory node; `depth`/`offset`/`limit` bound the subtree |
-| `amp_tool_file_directory` | Flat listing of direct children |
-| `amp_tool_file_read` | 1-based line page with fingerprint, charset and the next line |
-| `amp_tool_file_write` | Atomic write; create/overwrite/upsert/append, CAS, dry-run |
-| `amp_tool_file_outline` | Structural outline with `query`/`startLine`/`endLine` filters |
-| `amp_tool_file_import` | Outgoing, incoming or two-way imports |
-| `amp_tool_file_export` | Exported symbols, signatures and re-export edges |
-| `amp_tool_file_dependency` | Cycles, topological order and bounded closures |
-| `amp_tool_file_ast` | Lossless syntax tree: every non-whitespace token, declaration/markup hierarchy, UTF-8/line ranges; read-only, never executes |
+| `amp_tool_filesystem_session` | Current identity, roots, permissions, remaining TTL and quotas |
+| `amp_tool_filesystem_file` | One File/Directory node; `depth`/`offset`/`limit` bound the subtree |
+| `amp_tool_filesystem_directory` | Flat listing of direct children |
+| `amp_tool_filesystem_read` | 1-based line page with fingerprint, charset and the next line |
+| `amp_tool_filesystem_write` | Atomic write; create/overwrite/upsert/append, CAS, dry-run |
+| `amp_tool_filesystem_outline` | Structural outline with `query`/`startLine`/`endLine` filters |
+| `amp_tool_filesystem_import` | Outgoing, incoming or two-way imports |
+| `amp_tool_filesystem_export` | Exported symbols, signatures and re-export edges |
+| `amp_tool_filesystem_dependency` | Cycles, topological order and bounded closures |
+| `amp_tool_filesystem_ast` | Lossless syntax tree: every non-whitespace token, declaration/markup hierarchy, UTF-8/line ranges; read-only, never executes |
 
 The global variant is `amp_tool_globalfs_*`, a naming adapter in [src/global/filesystem.ts](src/global/filesystem.ts) that grants no new root or permission. Outline nodes carry `isFile`/`isDirectory`/`file?`/`directory?`/`path` (for example `add.py#add`) and `range` (UTF-8 bytes plus 1-based lines as bigint; decimal strings on the wire). Strategies cover code, Vue, project manifests, Markdown/TeX/plain text, CSS/SCSS/Sass, HTML, XML/OPML and Office; Office parsing covers DOCX/XLSX/PPTX and treats DOC/XLS/PPT/PUB/ACCDB as best-effort CFB.
 
@@ -153,8 +207,8 @@ await diff.run({ path: "src/new.ts", before: "" });
 ### MCP stdio
 
 ```sh
-node tools/workspaceAgentDemo.ts
-node tools/workspaceAgentServer.ts --config .cache/workspace-agent.local
+npm run workspace-agent-demo
+npm run workspace-agent -- --config .cache/workspace-agent.local
 ```
 
 For an MCP client, start Node directly to keep package-manager banners out of stdout. Replace absolute paths with your checkout location:
@@ -223,6 +277,7 @@ Service errors: `invalid_arguments`, `unknown_tool`, `revision_mismatch`, `not_a
 | [src/syntax](src/syntax/) | Charset detection/encoding, byte/line indexing, syntax registry and lossless read-only syntax trees |
 | [src/outline](src/outline/) | Code/document outlines, range and label indexes, keyword/strategy registries, React/Shell/SQL/Visual Basic strategies and Office parsing |
 | [src/hook](src/hook/) | Agent-facing composition hooks and run records |
+| [src/environment](src/environment/) | Explicit defaults and availability/link metadata for runtimes, applications, languages and project types |
 | [src/protocol](src/protocol/) | Wire contracts: envelopes, A2A, channels and the `amp_protocol_workspace` surface |
 | [src/module](src/module/) | LLM/tool ports, MCP adapters and execution policies |
 | [src/runtime](src/runtime/) | Agent turn/tool loop and governance integration |

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) · **简体中文** · [更新日志](CHANGELOG.zh-CN.md)
 
-AMP 是供 agent 使用的元认知协议：声明知识和义务，分配有限注意力，获取证据，记录成本与结果。当前参考实现为 `0.4.5`，要求 **Node.js 24 或以上**，使用 Apache-2.0 许可证。
+AMP 是供 agent 使用的元认知协议：声明知识和义务，分配有限注意力，获取证据，记录成本与结果。当前参考实现为 `0.4.2`，要求 **Node.js 24 或以上**，使用 Apache-2.0 许可证。
 
 ## 架构
 
@@ -38,7 +38,7 @@ Context 使用结构树和类型化关系图。项目依赖、导入、调用与
 - MCP 执行、参数 Schema 校验、摘要固定与旧式握手回退，以及 A2A 发现与消息绑定。
 - 项目树、项目依赖图、TS/JS 的部分静态导入/调用/引用图，以及知识库词法检索。
 - Agent 工作区：`File`/`Directory` 树（指纹、字符集、bigint 行数/字节数、时间、描述/摘要/用途）；分页读、CAS 原子写、按策略提取的大纲（代码/项目/文章/Office）；import/export/dependency 图（Tarjan SCC、拓扑序、有界闭包）；Session 身份与上下文隔离；`src/hook` 组合层；SQLite 实体与仓储。
-- 宿主发现：以一棵结构树返回获准项目、内部模块（service/tool/controller/route/repository/model/config/test/...）、文件名、有界内容匹配，以及宿主注册的插件、服务与工具。项目节点带描述、用途与简介。
+- 宿主发现：以一棵结构树返回获准项目、内部模块（service/tool/controller/route/repository/model/config/test/...）、文件名、有界内容匹配，以及宿主注册的插件、服务、工具、skills 和 knowledge。项目节点带描述、用途与简介；skill/knowledge 节点只暴露元数据，详情由注册中心按 ID 查询。
 - Markdown、TXT、DOCX、XLSX、PPTX、TeX/LaTeX/BibTeX 的结构提取、原生定位与摘要/详情分层。
 - `amp_protocol_workspace` v1 服务、8 个 agent 工具、本地运行时接入与 MCP stdio 服务端。
 - 带显式策略的指纹：值使用 RFC 8785 规范化 JSON，文件按字节哈希，目录树使用域分隔的 Merkle 根，`verify` 比较算法、`kind` 与策略，而不是只比对裸十六进制字符串。未配对代理项与 `-0` 被拒绝，而不是被静默改写。
@@ -53,20 +53,76 @@ Context 使用结构树和类型化关系图。项目依赖、导入、调用与
 
 ### 发现
 
-`amp_tool_workspace_discover` 以一棵结构树返回获准项目。文件节点带模块分类（`service`、`tool`、`controller`、`route`、`repository`、`model`、`config`、`test`、`middleware`、`component`、`util`）、扩展名与有界内容匹配。宿主通过 `HostCatalog` 登记项目的描述、用途、简介，以及插件、服务和工具；项目元数据附在项目节点上，未登记的项目回退到 workspace 摘要。发现是只读的，不会扩大 `projectIds`；内容匹配只是发现证据，不能替代 Frame 分配后的详情读取。
+`amp_tool_workspace_discover` 和 global 对应工具通过 Elasticsearch 检索统一目录。传入 `queries`（一个字符串或最多八个字符串），每个命中条目作为根节点返回一棵结构树，因此一个查询也可以返回多棵树。响应为 `{ trees: [{ query, tree, total, totalRelation, took, timedOut, truncated }] }`；没有命中时 `trees` 为空。`tree` 包含元数据及由 SQLite 实体关系展开的 `children`，不返回 skill 指令或 knowledge 正文。`limit` 限制每个查询的命中数量，`maxDepth` 和 `nodeLimit` 分别限制每棵树的深度和节点数。可用 `kinds`、`tags` 筛选元数据。宿主通过 `HostCatalog`、`SkillRegistry`、`KnowledgeRegistry`、`ProtocolRegistry` 登记条目，再统一投影为 `CatalogRecord`；其他模块通过同一记录格式及关系接入。
+
+目录沿 `entity → cache → service → repository → SQL → SQLite` 持久化。Elasticsearch 保存可重建的搜索投影，SQLite 保存完整条目、关系和同步 generation。宿主必须在快照变更后显式同步；失败或并发修改会保留未同步状态，discover 拒绝使用过期索引。查询命中及全部关联节点都按服务的 `projectIds` 和工作区 revision 再次检查，全局条目由 `includeGlobal` 控制。元数据发现不会授予详情读取或执行权限；原本的 `buildDiscoveryTree` 仍可作为本地结构构建 API 使用。
+
+这些 registry 是各自领域的宿主目录，不要求每个概念都复制成同构 registry。Ability、cognition、progress 等若已有运行时状态、策略或事件模型，应由现有领域模块维护；需要统一枚举时增加只读 catalog/discovery 投影即可。Agent 默认只读正式目录；可选的登记工作流应先创建带来源、版本和提案状态的候选项，再经宿主权限校验、人工审核与审计后发布，不授予模型直接改写已生效条目的能力。
+
+`environment` 模块将运行时、应用程序、编程语言与项目类型作为 `HostCatalog` 的 module 条目维护。`category` 为 `runtime`、`application`、`language` 或 `projectType`；`availability` 为 `unknown`、`available` 或 `unavailable`，与组件生命周期 `status` 分开。可选的 `platforms`、`extensions`、`relatedIds`、`skillIds`、`knowledgeIds`、`toolIds`、`protocolIds` 描述平台、格式与关联，不授予执行权限。可用性由宿主确认，登记目录不会安装软件或探测本机。
+
+```ts
+import { HostCatalog, loadDefaultEnvironments } from "attention-manifest-protocol";
+
+const host = new HostCatalog();
+loadDefaultEnvironments(host);
+// 将 host 投影到统一目录并同步 Elasticsearch，然后注入服务的 search 选项。
+// 发现参数：{ revision, queries: "runtime", kinds: ["module"] }
+```
+
+默认目录包括 PowerShell 7/Windows PowerShell 5.1、sh/bash/zsh、Word/Excel/PowerPoint/Publisher/Access/Microsoft Project、常见编程语言，以及 npm/Maven/CMake 等项目类型，默认可用性全部为 `unknown`。`getDefaultEnvironments()` 返回独立定义副本；`loadDefaultEnvironments(host)` 只返回本次新增项，遇到已有 ID 会跳过并保留宿主覆盖。因此，宿主可在加载默认值之前登记已确认的条目。分类、可用性及平台信息会进入搜索投影，可在 `queries` 中检索并以 `kinds: ["module"]` 限定条目类型。本地 `buildDiscoveryTree` 保留原有分类和可用性筛选。
+
+宿主接线示例（需要宿主提供已运行的 Elasticsearch 9 服务；`index` 用作各 namespace 独立快照索引的前缀）：
+
+```ts
+import { CatalogSearch, projectSearchRecords, WorkspaceAgentService } from "attention-manifest-protocol";
+import { Database } from "attention-manifest-protocol/database/service";
+
+const database = new Database("catalog.sqlite");
+const search = CatalogSearch.create({
+    namespace: "host-catalog",
+    catalog: database.catalogService,
+    cache: database.catalogStore,
+    elasticsearch: {
+        connection: { node: "http://127.0.0.1:9200" },
+        index: "amp-host-catalog",
+    },
+});
+search.replaceSnapshot(projectSearchRecords({
+    namespace: "host-catalog", revision: snapshot.revision,
+    workspace: snapshot.entities, relations: snapshot.relations,
+    projects: host.projects(), host: host.components(),
+    skills: skills.list(), knowledge: knowledge.list(), protocols: protocols.list(),
+    // records: [...其他模块提供的 CatalogRecord]
+}));
+await search.sync();
+const service = new WorkspaceAgentService({ ...options, snapshot, search });
+const response = await service.callAsync("amp_tool_workspace_discover", {
+    revision: snapshot.revision, queries: ["repository", "runtime"],
+    limit: 10, maxDepth: 3, nodeLimit: 50,
+});
+// response.data.trees 中，同一个 query 可以对应多个根节点及其关联树。
+// 宿主退出：先 await search.close()，再 database.close()。
+```
+
+`replaceSnapshot` 替换该 namespace 的完整快照；已删除条目及其出边会清理。它通过同步 SQLite SAVEPOINT 提交，不跨越网络等待。每次 `sync` 创建独立、带 namespace 归属的 concrete index，验证内容并封锁写入，再通过 SQLite epoch CAS 发布索引名、digest 和 generation。后启动的尝试会阻止更早的构建发布，因此失败或超时后可立即重试；远程迟到写入只能影响它自身未发布的索引。配置的索引及 alias 不会被清空或接管。发现查询前后重新校验具体索引、归属 marker、写封锁、文档数量与内容摘要，返回前还要确认 SQLite generation。`CatalogSearch` 在实例内排队，独立协调器分别构建并通过发布 CAS 协调；同步取消和超时包含排队耗时。调用前必须提交外层 SQLite 事务，也不要在等待 Elasticsearch 时在共享连接上开启事务。失败尝试及旧快照可能遗留闲置索引，宿主应管理保留策略，避免删除正在发布的索引或活动构建。写封锁和 namespace marker 无法隔离能移除或修改它们的 Elasticsearch 管理员。连接、认证和 TLS 选项通过 SDK 的 `connection` 在宿主侧配置，不会写入目录。没有搜索配置时 discover 返回 `search_unavailable`，同步 `call` 返回 `async_required`；MCP 集成使用 `handleAsync`。旧的 discover 工具参数 `text`、`scope` 等已移除。
+
+作用域控制新增八个规范工具：global/workspace 的 `adjust`，以及 global/workspace/session 的 `interaction`、`scenario`。注册元数据和默认值按 workspace 持久隔离，配置继承并接入运行时；完整身份接线、action、CAS、dry-run 与 stdio 配置见[作用域控制说明](docs/scoped-control.zh-CN.md)。
+
+作用域控制新增八个规范工具：global/workspace `adjust`，以及 global/workspace/session 的 `interaction` 与 `scenario`。宿主绑定身份、workspace 持久隔离、配置继承、CAS、dry-run 和 stdio 配置见[作用域控制文档](docs/scoped-control.zh-CN.md)。
 
 ## 快速开始
 
 ```sh
 npm ci
 npm run build
-npm run verify
-npm run scenario
+npm run build:lib
+node --test tools/controlProtocolCheck.ts tools/controlPersistenceCheck.ts tools/controlIntegrationCheck.ts
 ```
 
 ## 作为库使用
 
-`npm install attention-manifest-protocol` 会安装 `lib/` 中的编译产物及其声明文件，同时附带源码、JSON Schema 与可执行检查。运行时要求 Node.js 24 及以上。包根入口提供文档中的协议核心接口，其余模块均可按子路径导入。
+`npm install attention-manifest-protocol` 会安装 `lib/` 中的编译产物及其声明文件、JSON Schema 和作用域控制文档。源码和可执行检查保存在 GitHub 仓库中。运行时要求 Node.js 24 及以上。包根入口提供文档中的协议核心接口，其余模块均可按子路径导入。
 
 ```js
 import { generateSigningKey, signManifest, verifyManifest } from "attention-manifest-protocol";
@@ -85,7 +141,7 @@ import { ToolIds, parseId } from "attention-manifest-protocol/naming";
 
 `npm run build:lib` 重新构建 `lib/`，发布前由 `prepublishOnly` 自动执行。该构建只编译库代码，Vite 演示入口（`src/main.ts`）不在其中。
 
-专项检查可直接运行对应的 camelCase 工具，例如 `node tools/workspaceAgentCheck.ts`、`node tools/workspaceProjectCheck.ts`、`node tools/workspaceDiffCheck.ts`、`node tools/workspaceReactiveDiffCheck.ts`、`node tools/discoverCheck.ts` 与 `node tools/discoverAgentCheck.ts`。`verify` 执行完整验证链和两份类型检查。评测输入/结果以 JSON 保存在 [docs/eval](docs/eval/) 与 [docs/probes](docs/probes/)，夹具与录制探针不等同于独立的人类研究或生产质量证明。
+专项检查为 `npm run workspace-agent-check`、`workspace-project-check`、`workspace-diff-check`、`workspace-reactive-diff-check` 与 `workspace-*-boundary-check` 系列、`workspace-context-check`、`document-context-check`、`tex-context-check`、`governance-check`、`assignment-check`、`interaction-binding-check`、`discover-check`、`discover-agent-check`、`typecheck` 与 `typecheck:tools`。`verify` 执行完整验证链和两份类型检查。评测输入/结果以 JSON 保存在 [docs/eval](docs/eval/) 与 [docs/probes](docs/probes/)，夹具与录制探针不等同于独立的人类研究或生产质量证明。
 
 ## Agent 工具
 
@@ -116,20 +172,20 @@ import { ToolIds, parseId } from "attention-manifest-protocol/naming";
 
 ### 文件系统工具
 
-`amp_tool_file_*` 绑定一个已认证 Session；令牌不出现在工具参数里。除 `write` 外全部只读。
+`amp_tool_filesystem_*` 绑定一个已认证 Session；令牌不出现在工具参数里。除 `write` 外全部只读。
 
 | 工具 | 用途 |
 | --- | --- |
-| `amp_tool_file_session` | 当前身份、根、权限、剩余 TTL 与配额 |
-| `amp_tool_file_file` | 返回一个 File/Directory 节点；`depth`/`offset`/`limit` 控制子树与分页 |
-| `amp_tool_file_directory` | 平铺列出一级子节点 |
-| `amp_tool_file_read` | 按 1-based 行号读取文本页；返回指纹、字符集与下一页行号 |
-| `amp_tool_file_write` | 原子写入；create/overwrite/upsert/append、CAS、dry-run |
-| `amp_tool_file_outline` | 结构化大纲；支持 `query`/`startLine`/`endLine` 过滤 |
-| `amp_tool_file_import` | 出边/入边/两向导入关系 |
-| `amp_tool_file_export` | 导出符号、签名与 re-export 边 |
-| `amp_tool_file_dependency` | 环、拓扑序、依赖/被依赖闭包 |
-| `amp_tool_file_ast` | 无损语法树：每个非空白 token、声明/块/标签层级、UTF-8 字节与行范围；只读，不执行 |
+| `amp_tool_filesystem_session` | 当前身份、根、权限、剩余 TTL 与配额 |
+| `amp_tool_filesystem_file` | 返回一个 File/Directory 节点；`depth`/`offset`/`limit` 控制子树与分页 |
+| `amp_tool_filesystem_directory` | 平铺列出一级子节点 |
+| `amp_tool_filesystem_read` | 按 1-based 行号读取文本页；返回指纹、字符集与下一页行号 |
+| `amp_tool_filesystem_write` | 原子写入；create/overwrite/upsert/append、CAS、dry-run |
+| `amp_tool_filesystem_outline` | 结构化大纲；支持 `query`/`startLine`/`endLine` 过滤 |
+| `amp_tool_filesystem_import` | 出边/入边/两向导入关系 |
+| `amp_tool_filesystem_export` | 导出符号、签名与 re-export 边 |
+| `amp_tool_filesystem_dependency` | 环、拓扑序、依赖/被依赖闭包 |
+| `amp_tool_filesystem_ast` | 无损语法树：每个非空白 token、声明/块/标签层级、UTF-8 字节与行范围；只读，不执行 |
 
 全局变体为 `amp_tool_globalfs_*`，由 [src/global/filesystem.ts](src/global/filesystem.ts) 做命名适配；它不扩大任何根或权限。
 大纲节点带 `isFile`/`isDirectory`/`file?`/`directory?`/`path`（如 `add.py#add`）与 `range`（UTF-8 字节 + 1-based 行，bigint；JSON 中为十进制字符串）。策略覆盖代码、Vue、项目清单、Markdown/TeX/纯文本、CSS/SCSS/Sass、HTML、XML/OPML 与 Office；Office 文件由 `office.ts` 解析 DOCX/XLSX/PPTX，DOC/XLS/PPT/PUB/ACCDB 为 CFB best-effort。
@@ -154,8 +210,8 @@ await diff.run({ path: "src/new.ts", before: "" });
 ### MCP stdio 接入
 
 ```sh
-node tools/workspaceAgentDemo.ts
-node tools/workspaceAgentServer.ts --config .cache/workspace-agent.local
+npm run workspace-agent-demo
+npm run workspace-agent -- --config .cache/workspace-agent.local
 ```
 
 真实 MCP 客户端应直接启动 Node，避免包管理器提示混入协议 stdout。将以下绝对路径替换为实际项目目录：
@@ -220,11 +276,14 @@ Frame、快照、ContentStore 与后备执行器由宿主提供；将 `tools` /
 | [src/naming](src/naming/) | 冻结的 ID 表、ID 文法、兼容别名与 catalog 摘要 |
 | [src/context](src/context/) | Context 生命周期、树/图投影、CAS、工作区事实、上下文装配与 agent 服务 |
 | [src/session](src/session/) | 身份、令牌、TTL、上下文隔离、fork/revoke/rotate |
+| [src/environment](src/environment/) | 运行时、应用、语言和项目类型的默认目录、可用性与关联元数据 |
+| [src/skill](src/skill/) | 可复用 agent skill 注册、校验、查询与隔离副本 |
+| [src/knowledge](src/knowledge/) | 带来源元数据的 knowledge 注册、校验、查询与隔离副本 |
+| [src/protocol](src/protocol/) | 线上协议契约、通道，以及宿主维护的协议元数据注册中心 |
 | [src/file](src/file/) | File/Directory 树、元数据、分页读、原子写、会话运行时/服务、模块图与 ZIP/CFB 容器 |
 | [src/syntax](src/syntax/) | 字符集检测/编解码、字节/行索引、语法注册表与无损只读语法树 |
 | [src/outline](src/outline/) | 代码/文档大纲、范围与标签索引、关键字/策略注册表、React/Shell/SQL/Visual Basic 策略与 Office 解析 |
 | [src/hook](src/hook/) | 面向 agent 的组合 hooks 与运行记录 |
-| [src/protocol](src/protocol/) | 线上契约：信封、A2A、通道与 `amp_protocol_workspace` 接口 |
 | [src/module](src/module/) | 模型/工具端口、MCP 适配器与执行策略 |
 | [src/runtime](src/runtime/) | agent 回合、工具循环与治理接入 |
 | [src/governance](src/governance/) | 清单、凭据、预算、工作流、签名与审计 |

package/docs/scoped-control.zh-CN.md

@@ -0,0 +1,93 @@
+# 作用域注册调整与交互配置
+
+八个工具仅使用以下规范名称，不提供省略 `tool` 的别名：
+
+| 工具 | 作用域 |
+| --- | --- |
+| `amp_tool_global_adjust` | 全局注册数据，或显式授权的 workspace 目标 |
+| `amp_tool_workspace_adjust` | 当前宿主绑定的 workspace |
+| `amp_tool_global_interaction` / `amp_tool_global_scenario` | 全局默认配置，或显式授权的 workspace 目标 |
+| `amp_tool_workspace_interaction` / `amp_tool_workspace_scenario` | 当前 workspace 的默认配置与现有 session |
+| `amp_tool_session_interaction` / `amp_tool_session_scenario` | 当前宿主绑定的 session |
+
+## 身份与持久化
+
+宿主使用 `database.controlService.bind(identity)` 绑定端口，并注入 `WorkspaceAgentService`、`GlobalAgentService` 或 `SessionControlService` 的 `control` 选项。`identity` 的 `workspaceId`、`sessionId`、`allowGlobal`、授权 workspace 集合与认证回调来自宿主。工具参数不能指定 session 身份；仅 global 工具接受目标 `workspaceId`，端口会再次验证授权。缺少端口返回 `control_unavailable`。
+
+```ts
+import { Database } from "attention-manifest-protocol/database";
+import { SessionRegistry } from "attention-manifest-protocol/session";
+import { SessionControlService } from "attention-manifest-protocol/control";
+import { registerSessionControlTools } from "attention-manifest-protocol/module";
+
+const database = new Database("state.sqlite");
+const identities = new SessionRegistry({ store: database.workspaceSessions });
+// roots 由宿主审核；下面示例中的 roots 由应用传入。
+const opened = identities.open({ agentId: "agent.example", roots });
+const control = database.controlService.bind({
+    workspaceId: opened.descriptor.workspaceId!,
+    sessionId: opened.descriptor.id,
+    authenticate: () => {
+        identities.verify(opened.credential.sessionId, opened.credential.token);
+    },
+});
+const sessionControl = new SessionControlService({ control });
+registerSessionControlTools(toolRegistry, sessionControl);
+```
+
+Session 执行器为 `SessionControlToolExecutor`。Workspace 和 Global 使用已有的注册函数与执行器，新增工具会随其 descriptors 注册。所有新增工具的静态风险为 `write`，包括同名工具的读取 action；宿主审批与工具策略继续生效。意外异常只返回 `internal_error`，不会回传后端错误内容。
+
+`workspaces` 保存显式 workspace；默认 workspace 是普通 workspace，与 global scope 分开。宿主可使用 `createWorkspace(id, name)`、`defaultWorkspace()`、`setDefaultWorkspace(id, expectedVersion?)` 管理工作区。默认切换只影响之后省略 workspaceId 的新 session；既有 session 和 fork 保留原绑定。v4 数据库通过增量迁移升级到 v5，保留 scheduler 和证据 hash chain，未知未来版本拒绝打开。SQLite 连接是可信宿主边界，不应暴露任意 SQL 给 agent。
+
+## 注册项调整
+
+`registry` 为 `modules`、`skills`、`knowledge`、`protocols`、`environments`、`concepts` 之一。`value` 是 JSON 元数据，不允许修改可执行函数、工具 schema、风险或授权策略。
+
+| action | 必填字段（除 action、registry） |
+| --- | --- |
+| `list` | 无 |
+| `get` / `remove` | `id` |
+| `register` / `update` | `id`, `value`（对象） |
+| `default_get` / `default_reset` | `key` |
+| `default_set` | `key`, `value`（JSON） |
+| `link` / `unlink` | `id`, `targetId`, `relation` |
+
+变更 action 支持 `expectedVersion` 和 `dryRun`。首次本地写入的 CAS 版本为 0；继承项的 `get` 返回本地 `version`、来源和 `effectiveVersion`。Workspace 对全局项的 update/remove 创建本地覆盖或删除遮蔽。默认值 reset 恢复继承；条目 remove 保留版本和删除标记。Link 的目标属于同 registry，版本随源条目递增。
+
+```json
+{"action":"register","registry":"modules","id":"module.search","value":{"name":"Search","description":"Metadata search"},"expectedVersion":0}
+```
+
+```json
+{"action":"update","registry":"modules","id":"module.search","value":{"name":"Search v2"},"expectedVersion":1,"dryRun":true}
+```
+
+宿主通过 `listRegistry(workspaceId, registry)` 读取有效注册目录，或 `applyControlRegistry(...)` 将覆盖和删除标记应用到搜索目录。此投影固定 record kind 和宿主 scope，不会创建可执行工具。一般嵌入式宿主应在调整后重建快照并同步搜索；stdio host 配置 control 与 search 时已接好更新链路。
+
+## 交互模式与情景
+
+两个域都支持 `get`、`set`、`reset`。set 提供一个模式选择器，或一个权重 `mix`，二者互斥。
+
+- interaction 的 `mode`：`affect`、`think`、`inspire`、`converge`、`orchestrate`。
+- scenario 的 `scenario`：`chat`、`writing`、`office`、`collaboration`、`investigation`、`research`、`engineering`、`iteration`。
+- mix 只接受该域的合法 key，权重必须为有限非负数，至少一项正数；服务调用已有 resolver 归一化。
+
+```json
+{"action":"set","mode":"think","expectedVersion":0}
+```
+
+```json
+{"action":"set","mix":{"engineering":0.7,"research":0.3},"applyTo":"all","dryRun":true}
+```
+
+有效配置按 global → workspace → session 继承，更具体的配置优先；reset 清除本地选择并恢复继承。get 返回 `mix`/`effectiveMix`、`source`、本地 `version`、`effectiveVersion` 与解析计划；没有配置时 mix 为 null。
+
+Global/workspace 变更支持 `applyTo`：`defaults` 修改该 scope 的配置（默认）；`existing` 写入当前授权范围内有效 session 的本地配置；`all` 同时修改默认和现有 session。批量操作在一个事务内完成，失败时全部回滚。Session 工具不接受 `applyTo`。授权集合只覆盖部分 workspace 的 global 端口，必须指定获准的目标 workspace，不能通过全局继承扩大影响。
+
+`CognitiveRuntime` 的 `control` 选项接收同一个已认证 session 端口，每轮开始读取有效配置。显式 turn override 优先，其后依次采用作用域配置、runtime 显式默认、runtime session 默认、自动推断。工具在本轮改变配置后，从下一轮生效。凭据或 session 生命周期失效时，在调用模型前拒绝执行。
+
+## stdio host
+
+本地 bootstrap 可配置 `control: { databasePath: "state.sqlite", workspaceId?: "workspace-id" }`。省略 workspaceId 时绑定数据库的默认 workspace。若同时配置 search，两者使用同一数据库；搜索 namespace 持久绑定到该 workspace，不能被另一个 workspace 接管；仅配置 search 而未绑定 control 身份的宿主，也不能复用已绑定的 namespace。配置属于宿主启动输入，不能通过 tools/call 更改。
+
+Control 工具的 workspace/global `revision` 可选，提供时执行既有快照版本检查；其他 workspace 工具仍遵循原 revision 契约。Session 工具独立于项目快照，不接受 revision。需要版本竞争保护时，变更请求应提供 `expectedVersion`。