attention-manifest-protocol 0.4.6 → 0.5.0

package/CHANGELOG.md

@@ -5,6 +5,29 @@ 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).
 
+## [0.5.0] - 2026-11-03
+
+### Added
+
+- 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
+
+- 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
@@ -24,6 +47,12 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### 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.

package/CHANGELOG.zh-CN.md

@@ -5,6 +5,29 @@
 格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，版本号遵循
 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [0.5.0] - 2026-11-03
+
+### 新增
+
+- 八个规范作用域控制工具，覆盖 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` 参数，并由宿主配置和同步搜索后端。
+
+### 修复
+
+- 保留公开 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
 
 ### 新增
@@ -24,6 +47,12 @@
 
 ### 新增
 
+- 官方 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`。

package/README.md

@@ -53,22 +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 authorized projects, host components, skills, knowledge and protocols. 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 projects and components through `HostCatalog`, reusable instructions through `SkillRegistry`, source-aware entries through `KnowledgeRegistry`, and protocol metadata through `ProtocolRegistry`. Discovery exposes skill/knowledge/protocol metadata only; full entries are fetched from their registries by ID. 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";
@@ -225,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

@@ -53,22 +53,76 @@ Context 使用结构树和类型化关系图。项目依赖、导入、调用与
 
 ### 发现
 
-`amp_tool_workspace_discover` 以一棵结构树返回获准项目、宿主组件、skill、knowledge 与 protocol。文件节点带模块分类（`service`、`tool`、`controller`、`route`、`repository`、`model`、`config`、`test`、`middleware`、`component`、`util`）、扩展名与有界内容匹配。宿主通过 `HostCatalog` 登记项目与插件/服务/工具，通过 `SkillRegistry`、`KnowledgeRegistry`、`ProtocolRegistry` 登记可复用指令、知识条目与协议元数据。发现只暴露 skill/knowledge/protocol 元数据，不返回指令或正文；注册中心按 ID 提供完整条目。发现是只读的，不会扩大 `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";
@@ -222,6 +276,7 @@ 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/) | 线上协议契约、通道，以及宿主维护的协议元数据注册中心 |

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`。

package/lib/context/workspaceService.d.ts

@@ -1,5 +1,7 @@
+import type { ControlPort } from "../control/types.js";
 import type { Frame } from "../frame/frame.js";
-import { HostCatalog } from "../discover/host.js";
+import type { HostCatalog } from "../discover/host.js";
+import type { DiscoverySearch } from "../discover/types.js";
 import type { KnowledgeRegistry } from "../knowledge/registry.js";
 import type { ProtocolRegistry } from "../protocol/registry.js";
 import type { SkillRegistry } from "../skill/registry.js";
@@ -97,6 +99,8 @@ export interface WorkspaceRunner {
     run(request: WorkspaceRunRequest): WorkspaceRunOutcome;
 }
 export interface WorkspaceServiceOptions {
+    /** Host-authenticated port; calls always bind the workspace scope. */
+    control?: ControlPort;
     agentId: string;
     projectIds: readonly string[];
     snapshot: WorkspaceSnapshot;
@@ -119,6 +123,8 @@ export interface WorkspaceServiceOptions {
      * components are filtered against `projectIds` before discovery sees them.
      */
     host?: HostCatalog;
+    /** Host-managed search index; services never create or synchronize it. */
+    search?: DiscoverySearch;
     skills?: SkillRegistry;
     knowledge?: KnowledgeRegistry;
     protocols?: ProtocolRegistry;
@@ -132,14 +138,12 @@ export declare class WorkspaceAgentService {
     private readonly retired;
     private readonly roots;
     private readonly definitions;
-    private readonly host;
-    private readonly skills?;
-    private readonly knowledge?;
-    private readonly protocols?;
+    private readonly search?;
     private readonly projectIds;
     private readonly store;
     private readonly writer?;
     private readonly runner?;
+    private readonly control?;
     /**
      * Files the host already persisted through this service. The snapshot stays
      * immutable, so this overlay is what keeps a read after a write honest.
@@ -155,7 +159,8 @@ export declare class WorkspaceAgentService {
     private cacheVersion;
     private cachedCatalog;
     private calls;
-    constructor(options: WorkspaceServiceOptions);
+    /** The second argument is a host-only schema override for the global adapter. */
+    constructor(options: WorkspaceServiceOptions, controlDefinitions?: readonly WorkspaceToolDefinition[]);
     /**
      * Host-only registration. Frames bind to this snapshot revision explicitly;
      * their digest remains the AMP Frame digest, not a workspace revision field.
@@ -190,16 +195,14 @@ export declare class WorkspaceAgentService {
      */
     catalog(): ToolCatalog;
     call(name: string, raw: unknown): WorkspaceResponse;
+    /** Search is asynchronous; other tools preserve their synchronous behavior. */
+    callAsync(name: string, raw: unknown): Promise<WorkspaceResponse>;
+    /** Every entry point spends one call before validating the same wire schema. */
+    private prepareCall;
+    private failure;
     private reply;
     private requireEntity;
     private dispatch;
-    /**
-     * Agent-callable project discovery. The result is a structural tree over
-     * only the authorized snapshot plus host components that belong to the
-     * authorized project scope. Content matches are bounded snippets, never a
-     * replacement for a Frame-allocated detail read.
-     */
-    private discover;
     /**
      * Project scope: one explicitly named project or every authorized root.
      */
@@ -268,7 +271,6 @@ export declare class WorkspaceAgentService {
      * writer, CAS and overlay as `write`.
      */
     private diffWrite;
-    private builtInComponents;
     private materialize;
     /**
      * Bounded detail read. The page is addressed by characters, lines or bytes,