attention-manifest-protocol 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -5,6 +5,27 @@ 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.6.0] - 2026-11-03
+
+### Added
+
+- `outlineAddress(range, charset, bounds)` and the related line/byte request helpers convert an outline node's `range` into the `startLine`/`endLine` and `offsetBytes`/`endBytes` fields the workspace read and write tools accept, removing the UTF-8 BOM prefix and failing closed on reversed, out-of-bounds or non-representable values.
+- Every mutable registry is read-write: `SkillRegistry`, `KnowledgeRegistry`, `ProtocolRegistry`, `ToolRegistry`, `OutlineRegistry`, `OutlineKeywordRegistry`, `SyntaxRegistry`, `SqlDialectRegistry`, `CalibrationRegistry`, `BehaviorRegistry` and `EntityRegistry` expose `update` and `remove` (plus `clear` for list-shaped containers) on top of `register`.
+
+### Changed
+
+- Writing a file now rebuilds that file's outline and drops its previous cache generation in the same call, so a later outline read never serves the pre-write tree and storage keeps one cache row per file instead of one per edit.
+- `SyntaxRegistry.updateLanguage` and `removeLanguage` release the language's extensions so a new language can claim them.
+
+### Fixed
+
+- The session-scoped filesystem store did not forward `removeOutline`, silently dropping cache invalidation; it now scopes and forwards it.
+- The calibration registry now accepts a host-supplied model for a scope it has never fitted, so persisted calibration can be restored.
+
+### Validation
+
+- Joint regression: 168/168 across registry, discovery, outline, runtime and database suites; source and tools typechecks passed.
+
 ## [0.5.0] - 2026-11-03
 
 ### Added

package/CHANGELOG.zh-CN.md

@@ -5,6 +5,27 @@
 格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，版本号遵循
 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [0.6.0] - 2026-11-03
+
+### 新增
+
+- `outlineAddress(range, charset, bounds)` 及配套的行/字节请求辅助函数，把大纲节点的 `range` 转成 workspace 读写工具接受的 `startLine`/`endLine` 与 `offsetBytes`/`endBytes`，扣除 UTF-8 BOM 前缀；倒序、越界或无法精确表示时报错而不静默裁剪。
+- 所有可变注册中心均可读写：`SkillRegistry`、`KnowledgeRegistry`、`ProtocolRegistry`、`ToolRegistry`、`OutlineRegistry`、`OutlineKeywordRegistry`、`SyntaxRegistry`、`SqlDialectRegistry`、`CalibrationRegistry`、`BehaviorRegistry` 与 `EntityRegistry` 在 `register` 之外提供 `update` 与 `remove`（列表型容器另有 `clear`）。
+
+### 变更
+
+- 写入文件时在同一次调用内重建该文件大纲并删除旧缓存代次，之后读取大纲不会返回写入前的树，存储中也保持每个文件一条缓存而非每次编辑一条。
+- `SyntaxRegistry.updateLanguage` 与 `removeLanguage` 会释放语言的扩展名，允许新语言重新占用。
+
+### 修复
+
+- 会话限定的文件存储未转发 `removeOutline`，导致缓存失效被静默丢弃；现已按会话键转发。
+- 校准注册中心现在接受宿主为从未拟合过的 scope 提供模型，便于恢复已持久化的校准。
+
+### 验证
+
+- 联合回归 168/168 通过（注册中心、发现、大纲、运行时与数据库套件）；源代码与工具两套类型检查通过。
+
 ## [0.5.0] - 2026-11-03
 
 ### 新增

package/README.md

@@ -59,6 +59,8 @@ The catalog follows `entity → cache → service → repository → SQL → SQL
 
 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.
 
+Every mutable registry is read-write for the host that owns it: `SkillRegistry`, `KnowledgeRegistry`, `ProtocolRegistry`, `ToolRegistry`, `OutlineRegistry`, `OutlineKeywordRegistry`, `SyntaxRegistry` (languages, token kinds and node kinds), `SqlDialectRegistry`, `CalibrationRegistry`, `BehaviorRegistry` and `EntityRegistry` all expose `update`/`remove` (and `clear` where the container is a list), on top of `register` and their read accessors. An update keeps the entry's registration slot and re-runs the same validation as register, so a host can change or drop an entry in place instead of building a second registry that disagrees with the first; `SyntaxRegistry.updateLanguage`/`removeLanguage` also release and re-use extensions. The host is still the only caller allowed to write these catalogs.
+
 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
@@ -185,7 +187,7 @@ The `amp_protocol_workspace` v1 response contains `protocol`, `version`, `revisi
 | `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.
+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). `outlineAddress(range, charset, bounds)` in [src/outline/rangeBridge.ts](src/outline/rangeBridge.ts) converts that range into the `startLine`/`endLine` and `offsetBytes`/`endBytes` fields the workspace `read`, `write` and `diff_write` tools accept: it removes the UTF-8 BOM prefix, keeps bytes half-open and lines inclusive, and fails closed on reversed, out-of-bounds or non-representable values instead of clamping. A successful file write rebuilds that file's outline and drops its previous cache generation in the same call, so a later outline read never serves the pre-write tree. 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.
 
 ### Hooks
 

package/README.zh-CN.md

@@ -59,6 +59,8 @@ Context 使用结构树和类型化关系图。项目依赖、导入、调用与
 
 这些 registry 是各自领域的宿主目录，不要求每个概念都复制成同构 registry。Ability、cognition、progress 等若已有运行时状态、策略或事件模型，应由现有领域模块维护；需要统一枚举时增加只读 catalog/discovery 投影即可。Agent 默认只读正式目录；可选的登记工作流应先创建带来源、版本和提案状态的候选项，再经宿主权限校验、人工审核与审计后发布，不授予模型直接改写已生效条目的能力。
 
+每个可变的注册中心对宿主都是可读写的：`SkillRegistry`、`KnowledgeRegistry`、`ProtocolRegistry`、`ToolRegistry`、`OutlineRegistry`、`OutlineKeywordRegistry`、`SyntaxRegistry`（语言、token 类别与节点类别）、`SqlDialectRegistry`、`CalibrationRegistry`、`BehaviorRegistry` 与 `EntityRegistry` 都在 `register` 和读取接口之外提供 `update`/`remove`（列表型容器另有 `clear`）。更新保留原登记位置并执行与注册相同的校验，宿主可以原地修改或删除条目，而不必再建一份与前者不一致的注册中心；`SyntaxRegistry.updateLanguage`/`removeLanguage` 会释放并允许复用扩展名。写这些目录的仍只能是宿主。
+
 `environment` 模块将运行时、应用程序、编程语言与项目类型作为 `HostCatalog` 的 module 条目维护。`category` 为 `runtime`、`application`、`language` 或 `projectType`；`availability` 为 `unknown`、`available` 或 `unavailable`，与组件生命周期 `status` 分开。可选的 `platforms`、`extensions`、`relatedIds`、`skillIds`、`knowledgeIds`、`toolIds`、`protocolIds` 描述平台、格式与关联，不授予执行权限。可用性由宿主确认，登记目录不会安装软件或探测本机。
 
 ```ts
@@ -188,7 +190,7 @@ import { ToolIds, parseId } from "attention-manifest-protocol/naming";
 | `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。
+大纲节点带 `isFile`/`isDirectory`/`file?`/`directory?`/`path`（如 `add.py#add`）与 `range`（UTF-8 字节 + 1-based 行，bigint；JSON 中为十进制字符串）。`outlineAddress(range, charset, bounds)`（[src/outline/rangeBridge.ts](src/outline/rangeBridge.ts)）把该 range 转成 workspace `read`、`write`、`diff_write` 接受的 `startLine`/`endLine` 与 `offsetBytes`/`endBytes`：扣除 UTF-8 BOM 前缀，字节半开、行闭区间；倒序、越界或无法精确表示时直接报错而不做静默裁剪。文件写入成功后会在同一次调用内重建该文件大纲并删除旧的缓存代次，之后读取大纲不会返回写入前的树。策略覆盖代码、Vue、项目清单、Markdown/TeX/纯文本、CSS/SCSS/Sass、HTML、XML/OPML 与 Office；Office 文件由 `office.ts` 解析 DOCX/XLSX/PPTX，DOC/XLS/PPT/PUB/ACCDB 为 CFB best-effort。
 
 ### Hooks
 

package/lib/bayes/calibrationRegistry.d.ts

@@ -35,5 +35,17 @@ export declare class CalibrationRegistry {
     register(scope: string, points: readonly CalibrationPoint[], options?: RegisterOptions): RegisterResult;
     calibrate(scope: string, predicted: number): number;
     model(scope: string): CalibrationModel | undefined;
+    /**
+     * Set the model of one scope.
+     *
+     * Unlike `register`, which fits a model from samples, this stores a complete
+     * model as-is: it replaces the scope's current model or creates it. Hosts
+     * that persist or hand-author a calibration use this to restore it.
+     */
+    update(model: CalibrationModel): CalibrationModel;
+    /** Remove one scope's model, returning it to raw probabilities. */
+    remove(scope: string): boolean;
+    /** Remove every calibrated scope. */
+    clear(): number;
     scopes(): string[];
 }

package/lib/bayes/calibrationRegistry.js

@@ -55,6 +55,28 @@ export class CalibrationRegistry {
     model(scope) {
         return this.models.get(scope);
     }
+    /**
+     * Set the model of one scope.
+     *
+     * Unlike `register`, which fits a model from samples, this stores a complete
+     * model as-is: it replaces the scope's current model or creates it. Hosts
+     * that persist or hand-author a calibration use this to restore it.
+     */
+    update(model) {
+        const stored = { ...model };
+        this.models.set(stored.scope, stored);
+        return { ...stored };
+    }
+    /** Remove one scope's model, returning it to raw probabilities. */
+    remove(scope) {
+        return this.models.delete(scope);
+    }
+    /** Remove every calibrated scope. */
+    clear() {
+        const count = this.models.size;
+        this.models.clear();
+        return count;
+    }
     scopes() {
         return [...this.models.keys()];
     }

package/lib/database/adapter/filesystemStore.d.ts

@@ -88,6 +88,13 @@ export declare class SqliteFilesystemStore implements FilesystemStore {
      * @param outline - Parsed outline.
      */
     saveOutline(rootId: string, outline: OutlineResult): void;
+    /**
+     * Drop every cached outline of one file, whatever its fingerprint.
+     *
+     * @param rootId - Session root id.
+     * @param path - Root-relative POSIX path.
+     */
+    removeOutline(rootId: string, path: string): void;
     /**
      * Load a cached import report by exact fingerprint.
      *

package/lib/database/adapter/filesystemStore.js

@@ -236,6 +236,15 @@ export class SqliteFilesystemStore {
     saveOutline(rootId, outline) {
         this.outlines.save(rootId, outline, now());
     }
+    /**
+     * Drop every cached outline of one file, whatever its fingerprint.
+     *
+     * @param rootId - Session root id.
+     * @param path - Root-relative POSIX path.
+     */
+    removeOutline(rootId, path) {
+        this.outlines.remove(rootId, path);
+    }
     /**
      * Load a cached import report by exact fingerprint.
      *

package/lib/database/entity/entity.d.ts

@@ -688,6 +688,21 @@ export declare class EntityRegistry {
      * @throws EntityMetadataError for invalid or duplicate metadata.
      */
     register(entity: Entity): this;
+    /**
+     * Replace one registered entity, keeping its registration position.
+     *
+     * @param entity - Validated replacement metadata with the same name.
+     * @returns This registry, for chaining.
+     * @throws EntityMetadataError for invalid metadata or an unknown name.
+     */
+    update(entity: Entity): this;
+    /**
+     * Remove one entity.
+     *
+     * @param name - Logical entity name.
+     * @returns `true` when it was registered.
+     */
+    remove(name: EntityName): boolean;
     /**
      * Look up an entity by logical name.
      *

package/lib/database/entity/entity.js

@@ -225,6 +225,33 @@ export class EntityRegistry {
         this.entities.set(entity.name, entity);
         return this;
     }
+    /**
+     * Replace one registered entity, keeping its registration position.
+     *
+     * @param entity - Validated replacement metadata with the same name.
+     * @returns This registry, for chaining.
+     * @throws EntityMetadataError for invalid metadata or an unknown name.
+     */
+    update(entity) {
+        const problems = validateEntity(entity);
+        if (problems.length > 0) {
+            throw new EntityMetadataError(entity.name, problems);
+        }
+        if (!this.entities.has(entity.name)) {
+            throw new EntityMetadataError(entity.name, ["no entity with this name is registered"]);
+        }
+        this.entities.set(entity.name, entity);
+        return this;
+    }
+    /**
+     * Remove one entity.
+     *
+     * @param name - Logical entity name.
+     * @returns `true` when it was registered.
+     */
+    remove(name) {
+        return this.entities.delete(name);
+    }
     /**
      * Look up an entity by logical name.
      *

package/lib/database/repository/fileOutlineRepository.d.ts

@@ -28,6 +28,18 @@ export declare class FileOutlineRepository extends BaseRepository<FileOutlineRow
      * @param at - ISO timestamp for the write.
      */
     save(rootId: string, outline: OutlineResult, at: string): void;
+    /**
+     * Drop every cached outline of one file regardless of fingerprint.
+     *
+     * The cache is keyed by content fingerprint, so a write leaves the previous
+     * generation behind forever. A writer calls this after it replaces the file
+     * and saves the new outline, keeping one row per file instead of one row per
+     * edit.
+     *
+     * @param rootId - Session root id.
+     * @param path - Root-relative POSIX path.
+     */
+    remove(rootId: string, path: string): void;
     /**
      * Load the outline of one exact fingerprint.
      *

package/lib/database/repository/fileOutlineRepository.js

@@ -73,6 +73,20 @@ export class FileOutlineRepository extends BaseRepository {
             created_at: at,
         });
     }
+    /**
+     * Drop every cached outline of one file regardless of fingerprint.
+     *
+     * The cache is keyed by content fingerprint, so a write leaves the previous
+     * generation behind forever. A writer calls this after it replaces the file
+     * and saves the new outline, keeping one row per file instead of one row per
+     * edit.
+     *
+     * @param rootId - Session root id.
+     * @param path - Root-relative POSIX path.
+     */
+    remove(rootId, path) {
+        this.deleteWhere(conditions(FileOutlineTable, ["root_id", "path"]), rootId, path);
+    }
     /**
      * Load the outline of one exact fingerprint.
      *

package/lib/file/index.d.ts

@@ -32,6 +32,8 @@ export { DefaultSyntaxRegistry, SyntaxRegistry, buildSyntaxTreeFromText, createS
 export type { SyntaxLanguage, SyntaxLanguageDefinition, SyntaxNode, SyntaxNodeKind, SyntaxNodeKindDefinition, SyntaxToken, SyntaxTokenKind, SyntaxTokenKindDefinition, SyntaxTree, SyntaxTreeOptions, WireSyntaxNode, WireSyntaxToken, WireSyntaxTree, } from "../syntax/syntaxTree.js";
 export { OutlineIndex, buildOutlineIndex, filterOutline, hasLabelPrefix, wireOutline, wireOutlineNode, wireOutlineRange, outlineFromWire } from "../outline/outlineIndex.js";
 export type { OutlinePayload } from "../outline/outlineIndex.js";
+export { OutlineRangeError, outlineAddress, outlineBomOffset, outlineByteRange, outlineLineRange, readByteRequest, readLineRequest, writeByteRequest, writeLineRequest, } from "../outline/rangeBridge.js";
+export type { OutlineAddress, OutlineByteRange, OutlineLineRange, OutlineRangeErrorCode } from "../outline/rangeBridge.js";
 export { extractImports, importedBy, isParseableSource, readSourceFile, resolveImportSpecifier, tokenizeSource } from "./importGraph.js";
 export type { ResolvedSpecifier, SourceFileSnapshot, SourceToken } from "./importGraph.js";
 export { extractExports } from "./exportGraph.js";

package/lib/file/index.js

@@ -22,6 +22,7 @@ export { DefaultOutlineKeywords, OutlineKeywordRegistry, createOutlineKeywordReg
 export { buildSyntaxTree } from "./syntaxTree.js";
 export { DefaultSyntaxRegistry, SyntaxRegistry, buildSyntaxTreeFromText, createSyntaxRegistry, disposeSyntaxNode, syntaxLanguageOf, wireSyntaxTree, } from "../syntax/syntaxTree.js";
 export { OutlineIndex, buildOutlineIndex, filterOutline, hasLabelPrefix, wireOutline, wireOutlineNode, wireOutlineRange, outlineFromWire } from "../outline/outlineIndex.js";
+export { OutlineRangeError, outlineAddress, outlineBomOffset, outlineByteRange, outlineLineRange, readByteRequest, readLineRequest, writeByteRequest, writeLineRequest, } from "../outline/rangeBridge.js";
 export { extractImports, importedBy, isParseableSource, readSourceFile, resolveImportSpecifier, tokenizeSource } from "./importGraph.js";
 export { extractExports } from "./exportGraph.js";
 export { DependencyGraph, buildDependencyReport, graphFromImports } from "./dependency.js";

package/lib/file/runtime.d.ts

@@ -50,6 +50,8 @@ export declare class SessionRuntime {
     persistenceKey(rootId: string): string;
     loadOutline(rootId: string, path: string, fingerprint: string): import("./types.js").OutlineResult | undefined;
     saveOutline(rootId: string, outline: import("../outline/types.js").OutlineResult): void;
+    /** Drop every cached generation of one file's outline after it changed. */
+    removeOutline(rootId: string, path: string): void;
     /**
      * Resolve a caller path and return the tree that owns it.
      */

package/lib/file/runtime.js

@@ -25,6 +25,8 @@ export class SessionRuntime {
     persistenceKey(rootId) { return JSON.stringify([this.descriptor.workspaceId ?? "default", this.descriptor.id, rootId]); }
     loadOutline(rootId, path, fingerprint) { return this.store?.loadOutline(rootId, path, fingerprint); }
     saveOutline(rootId, outline) { this.store?.saveOutline(rootId, outline); }
+    /** Drop every cached generation of one file's outline after it changed. */
+    removeOutline(rootId, path) { this.store?.removeOutline?.(rootId, path); }
     /**
      * Resolve a caller path and return the tree that owns it.
      */

package/lib/file/scopedStore.js

@@ -13,6 +13,7 @@ export const scopeFilesystemStore = (store, session) => {
         }),
         loadOutline: (rootId, path, fingerprint) => store.loadOutline(key(rootId), path, fingerprint),
         saveOutline: (rootId, outline) => store.saveOutline(key(rootId), outline),
+        ...(store.removeOutline === (void 0) ? {} : { removeOutline: (rootId, path) => store.removeOutline(key(rootId), path) }),
         loadImports: (rootId, path, fingerprint) => store.loadImports(key(rootId), path, fingerprint),
         saveImports: (rootId, report) => store.saveImports(key(rootId), report),
         loadExports: (rootId, path, fingerprint) => store.loadExports(key(rootId), path, fingerprint),

package/lib/file/service.d.ts

@@ -152,6 +152,22 @@ export declare class FilesystemService {
      */
     read(runtime: SessionRuntime, request: import("./types.js").ReadRequest): ReadPage;
     write(runtime: SessionRuntime, request: import("./types.js").WriteRequest): Promise<WriteResult>;
+    /**
+     * Rebuild the outline cache of one written file.
+     *
+     * A write changes the file's fingerprint, and the cache is keyed by that
+     * fingerprint, so a stale row can never be read — but the old generation
+     * would linger in storage forever and the next read would parse again. This
+     * replaces every generation of the file with the outline of the new content
+     * at write time, so "the file changed" and "its outline changed" happen
+     * together. A file that cannot be outlined (binary, oversized, Office) is
+     * dropped from the cache and is not an error for the write itself.
+     *
+     * @param runtime - Session runtime owning the root.
+     * @param root - The root the written path belongs to.
+     * @param path - Caller path of the written file.
+     */
+    private refreshOutline;
     outline(runtime: SessionRuntime, request: OutlineRequest): OutlineResult;
     imports(runtime: SessionRuntime, request: ImportRequest): ImportReport;
     exports(runtime: SessionRuntime, request: ExportRequest): ExportReport;

package/lib/file/service.js

@@ -28,7 +28,7 @@ import { isOfficeFile, officeExports, officeReferences, parseOffice } from "../o
 import { buildSyntaxTree } from "./syntaxTree.js";
 import { wireSyntaxTree } from "../syntax/syntaxTree.js";
 import { buildDependencyReport, graphFromImports } from "./dependency.js";
-import { isFilesystemError } from "./errors.js";
+import { fail, isFilesystemError } from "./errors.js";
 import { readPage } from "./read.js";
 import { writeFile } from "./write.js";
 import { SessionRuntime } from "./runtime.js";
@@ -276,8 +276,52 @@ export class FilesystemService {
         };
         const result = await writeFile(runtime.sandbox, runtime.descriptor.id, request, settings);
         runtime.persist(rooted.root, tree.snapshot());
+        this.refreshOutline(runtime, rooted.root, request.path);
         return result;
     }
+    /**
+     * Rebuild the outline cache of one written file.
+     *
+     * A write changes the file's fingerprint, and the cache is keyed by that
+     * fingerprint, so a stale row can never be read — but the old generation
+     * would linger in storage forever and the next read would parse again. This
+     * replaces every generation of the file with the outline of the new content
+     * at write time, so "the file changed" and "its outline changed" happen
+     * together. A file that cannot be outlined (binary, oversized, Office) is
+     * dropped from the cache and is not an error for the write itself.
+     *
+     * @param runtime - Session runtime owning the root.
+     * @param root - The root the written path belongs to.
+     * @param path - Caller path of the written file.
+     */
+    refreshOutline(runtime, root, path) {
+        let relative;
+        let node;
+        try {
+            const rooted = runtime.sandbox.resolve(path, "read");
+            relative = rooted.relative;
+            node = runtime.treeFor(root).node(relative);
+        }
+        catch {
+            return;
+        }
+        if (node === (void 0) || node.type !== "File") {
+            return;
+        }
+        try {
+            runtime.removeOutline(root.id, relative);
+        }
+        catch {
+            return fail("store_failure");
+        }
+        try {
+            const outline = buildOutline(runtime.sandbox, relative, { anchor: { file: node } }, { file: node });
+            runtime.saveOutline(root.id, outline);
+        }
+        catch {
+            // An unoutlinable file stays uncached; the write already succeeded.
+        }
+    }
     outline(runtime, request) {
         const { rooted, node, tree } = runtime.node(request.path, "read");
         const cached = runtime.loadOutline(rooted.root.id, rooted.relative, node.fingerprint);

package/lib/file/types.d.ts

@@ -354,6 +354,12 @@ export interface FilesystemStore {
     listWrites(sessionId: string, limit: number): WriteJournalEntry[];
     loadOutline(rootId: string, path: string, fingerprint: string): OutlineResult | undefined;
     saveOutline(rootId: string, outline: OutlineResult): void;
+    /**
+     * Drop every cached outline of one file. A writer calls this before saving
+     * the rebuilt outline so one file keeps one cache row instead of one per
+     * edited fingerprint. Optional: in-memory stores may only keep the latest.
+     */
+    removeOutline?(rootId: string, path: string): void;
     loadImports(rootId: string, path: string, fingerprint: string): ImportReport | undefined;
     saveImports(rootId: string, report: ImportReport): void;
     loadExports(rootId: string, path: string, fingerprint: string): ExportReport | undefined;

package/lib/knowledge/registry.d.ts

@@ -13,6 +13,12 @@ export interface KnowledgeEntry {
 export declare class KnowledgeRegistry {
     private readonly entries;
     register(knowledge: KnowledgeEntry): KnowledgeEntry;
+    /** Replace an existing knowledge entry. The id must stay the same. */
+    update(knowledge: KnowledgeEntry): KnowledgeEntry;
+    /** Remove one knowledge entry; the result says whether it existed. */
+    remove(id: string): boolean;
+    /** Remove every knowledge entry and report how many were dropped. */
+    clear(): number;
     get(id: string): KnowledgeEntry | undefined;
     list(): KnowledgeEntry[];
     has(id: string): boolean;

package/lib/knowledge/registry.js

@@ -25,6 +25,19 @@ export class KnowledgeRegistry {
         validateKnowledge(knowledge);
         return this.entries.register(knowledge);
     }
+    /** Replace an existing knowledge entry. The id must stay the same. */
+    update(knowledge) {
+        validateKnowledge(knowledge);
+        return this.entries.update(knowledge.id, knowledge);
+    }
+    /** Remove one knowledge entry; the result says whether it existed. */
+    remove(id) {
+        return this.entries.remove(id);
+    }
+    /** Remove every knowledge entry and report how many were dropped. */
+    clear() {
+        return this.entries.clear();
+    }
     get(id) {
         return this.entries.get(id);
     }

package/lib/module/tool/tool.d.ts

@@ -20,6 +20,12 @@ export interface ToolExecutor {
 export declare class ToolRegistry {
     private readonly tools;
     register(descriptor: ToolDescriptor): this;
+    /** Replace an existing tool descriptor, keeping its registration slot. */
+    update(descriptor: ToolDescriptor): this;
+    /** Remove one tool descriptor. */
+    remove(name: string): boolean;
+    /** Remove every tool descriptor. */
+    clear(): number;
     get(name: string): ToolDescriptor | undefined;
     list(): ToolDescriptor[];
     get size(): number;

package/lib/module/tool/tool.js

@@ -12,6 +12,24 @@ export class ToolRegistry {
         this.tools.set(descriptor.name, descriptor);
         return this;
     }
+    /** Replace an existing tool descriptor, keeping its registration slot. */
+    update(descriptor) {
+        if (!this.tools.has(descriptor.name)) {
+            throw new Error(`unknown tool ${descriptor.name}`);
+        }
+        this.tools.set(descriptor.name, descriptor);
+        return this;
+    }
+    /** Remove one tool descriptor. */
+    remove(name) {
+        return this.tools.delete(name);
+    }
+    /** Remove every tool descriptor. */
+    clear() {
+        const count = this.tools.size;
+        this.tools.clear();
+        return count;
+    }
     get(name) {
         return this.tools.get(name);
     }

package/lib/outline/index.d.ts

@@ -2,6 +2,7 @@
 export * from "./types.js";
 export * from "./outline.js";
 export * from "./outlineIndex.js";
+export * from "./rangeBridge.js";
 export * from "./outlineKeywords.js";
 export { builtinOutlineStrategies } from "./outlineStrategies.js";
 export { hasOfficeOutlineParser, registerOfficeOutlineParser } from "./officeBridge.js";

package/lib/outline/index.js

@@ -2,6 +2,7 @@
 export * from "./types.js";
 export * from "./outline.js";
 export * from "./outlineIndex.js";
+export * from "./rangeBridge.js";
 export * from "./outlineKeywords.js";
 export { builtinOutlineStrategies } from "./outlineStrategies.js";
 export { hasOfficeOutlineParser, registerOfficeOutlineParser } from "./officeBridge.js";

package/lib/outline/outline.d.ts

@@ -90,6 +90,25 @@ export declare class OutlineRegistry {
      * @param strategy - Strategy to add.
      */
     register(strategy: OutlineStrategy): void;
+    /**
+     * Replace one registered strategy in place, keeping its selection position.
+     *
+     * @param strategy - Replacement; its `id` must already be registered.
+     */
+    update(strategy: OutlineStrategy): void;
+    /**
+     * Remove one strategy.
+     *
+     * @param id - Strategy id.
+     * @returns `true` when it was registered.
+     */
+    remove(id: string): boolean;
+    /**
+     * Remove every strategy.
+     *
+     * @returns Number of removed strategies.
+     */
+    clear(): number;
     /**
      * Strategies in selection order.
      */

package/lib/outline/outline.js

@@ -541,6 +541,48 @@ export class OutlineRegistry {
         this.byId.set(strategy.id, strategy);
         this.strategies.push(strategy);
     }
+    /**
+     * Replace one registered strategy in place, keeping its selection position.
+     *
+     * @param strategy - Replacement; its `id` must already be registered.
+     */
+    update(strategy) {
+        if (typeof (strategy) !== "object" || strategy === null || typeof (strategy.id) !== "string" || strategy.id.trim().length === 0) {
+            throw new Error("invalid outline strategy");
+        }
+        const index = this.strategies.findIndex((current) => current.id === strategy.id);
+        if (index < 0) {
+            throw new Error(`unknown outline strategy: ${strategy.id}`);
+        }
+        this.strategies[index] = strategy;
+        this.byId.set(strategy.id, strategy);
+    }
+    /**
+     * Remove one strategy.
+     *
+     * @param id - Strategy id.
+     * @returns `true` when it was registered.
+     */
+    remove(id) {
+        const index = this.strategies.findIndex((current) => current.id === id);
+        if (index < 0) {
+            return false;
+        }
+        this.strategies.splice(index, 1);
+        this.byId.delete(id);
+        return true;
+    }
+    /**
+     * Remove every strategy.
+     *
+     * @returns Number of removed strategies.
+     */
+    clear() {
+        const count = this.strategies.length;
+        this.strategies.length = 0;
+        this.byId.clear();
+        return count;
+    }
     /**
      * Strategies in selection order.
      */

package/lib/outline/outlineKeywords.d.ts

@@ -25,6 +25,16 @@ export declare class OutlineKeywordRegistry {
      * the first category and is a no-op, so aliases cannot silently reclassify.
      */
     register(category: OutlineKeywordCategory, word: string): this;
+    /**
+     * Move one word to another category, replacing its previous classification.
+     */
+    update(category: OutlineKeywordCategory, word: string): this;
+    /**
+     * Remove one word.
+     *
+     * @returns `true` when it was registered.
+     */
+    remove(word: string): boolean;
     /**
      * Category of one word, or `undefined`.
      */