@sema-agent/core 5.20.0 → 5.21.0

package/dist/core/memory-engine/types.d.ts

@@ -1,25 +1,62 @@
+/**
+ * Structured header fields of one memory entry (the CC frontmatter shape: `name`/`description`/
+ * `metadata.type`). `extra` preserves any additional frontmatter lines VERBATIM (round-trip safety:
+ * the engine must never destroy model-authored frontmatter it doesn't understand — same posture as
+ * the file store's unknown-op replay skip).
+ */
 export interface MemoryEntryFrontmatter {
+    /** Short kebab-case slug (CC `name:`). Defaults to the file slug when the model omits it. */
     name?: string;
+    /** One-line summary used for recall relevance (CC `description:`). */
     description?: string;
+    /** CC `metadata.type`: user | feedback | project | reference (unknown strings degrade, design/65). */
     type?: string;
+    /** design/138 §2.4 删除防线 — the EXPLICIT tombstone. A file that merely disappears is NEVER a
+     *  delete; only `deleted: true` in frontmatter produces a delete patch. */
     deleted?: boolean;
+    /**
+     * design-A C-5 (AGENTS.md×ingest, [A1]) — TYPED provenance for entries an INGEST producer minted
+     * from a repo file (project instruction files: AGENTS.md/CLAUDE.md — the file-name policy lives
+     * in the deployment; this type never names files). `path` is repo-relative; `contentHash` covers
+     * the raw pre-cap source bytes (opaque to the engine — equality comparison only); `ingestedAt`
+     * is ms epoch. Closed kind on purpose: `"repo_file"` is the only provenance the trust gates
+     * reason about (I-2 below); a malformed/unknown provenance block in a file round-trips through
+     * `extra` verbatim instead (never destroyed, never trusted).
+     */
     provenance?: {
         kind: "repo_file";
         path: string;
         contentHash: string;
         ingestedAt: number;
     };
+    /**
+     * design-A C-5/I-2 — the trust marker for repo-originated content: once `"untrusted"`, it can
+     * never be whitewashed. Enforcement is STRUCTURAL, not conventional: the backend contract
+     * (memory-backend-contract.ts) refuses any update patch that strips `trust`/`provenance` from an
+     * entry whose committed state carries `provenance.kind === "repo_file"` (malformed-refusal seat,
+     * same family as the `entry.id !== patch.id` clause). Single-value union on purpose — there is
+     * no `"trusted"` spelling to escalate to.
+     */
     trust?: "untrusted";
+    /** Unknown frontmatter lines preserved verbatim (order kept), re-serialized on projection. */
     extra?: string[];
 }
+/** design/138 §2.1 — one memory entry (the unit the backend stores and the engine projects to a file). */
 export interface MemoryEntry {
+    /** IMMUTABLE uuid — survives slug renames (consolidation cursors/vectors/dedup all key on it).
+     *  Hidden in the file's frontmatter as `id:`; minted at harvest for id-less new files. */
     id: string;
+    /** File-name identity (the path relative to its scope dir, without `.md`) — model-visible, renameable. */
     slug: string;
     frontmatter: MemoryEntryFrontmatter;
+    /** The markdown body (everything after the frontmatter block). */
     body: string;
+    /** CAS baseline — a content hash over (id, frontmatter, body). See {@link computeEntryRev}. */
     rev: string;
+    /** Owning scope (tenant/layer key, same vocabulary as `TaskSpec.memory.scopes`). */
     scope: string;
 }
+/** Manifest-level header: enough to judge relevance / build the derived index, never the body. */
 export interface MemoryEntryHeader {
     id: string;
     slug: string;
@@ -27,20 +64,45 @@ export interface MemoryEntryHeader {
     name?: string;
     description?: string;
     type?: string;
+    /** Last content change (ms epoch) — drives the natural-language age rendering in the derived index. */
     mtimeMs: number;
     rev: string;
+    /** Approximate stored size (bytes of body+frontmatter) — drives the per-scope materialization budget. */
     sizeBytes: number;
 }
+/** A scored search hit (FileBackend = lexical floor; PgBackend = design/81 vector rungs, S3). */
 export interface ScoredMemoryEntry extends MemoryEntryHeader {
+    /** Cosine-DISTANCE ∈ [0,2], 0 = identical (same contract as {@link import("../memory.js").ScoredMemory}). */
     score: number;
 }
+/**
+ * design/138 §2.1 — one entry transaction. `add`/`delete` are naturally commutative; `update` carries
+ * a per-id CAS baseline (`baseRev`): when the backend's current rev differs, the patch is reported as a
+ * CONFLICT (never blind-written) and the next task re-materializes fresh state (§2.4 并发).
+ */
 export interface NotePatch {
     op: "add" | "update" | "delete";
+    /** The immutable entry id this patch addresses. */
     id: string;
+    /** The full new entry state (`add`/`update`). Absent for `delete`. */
     entry?: MemoryEntry;
+    /** CAS baseline for `update`/`delete`: the rev this patch was computed against. Absent (a brand-new
+     *  add) ⇒ no CAS. */
     baseRev?: string;
+    /** ADD-ONLY guard (design/142 S2.5, E-02). Meaningful only on `op: "add"`:
+     *  - `"absent"` ⇒ add-if-absent: if the target id already exists, the backend compares revs —
+     *    same rev AND same projection (scope+slug) = idempotent apply; DIFFERENT rev, or same rev at a
+     *    DIFFERENT projection (三轮复查: rev hashes id/frontmatter/body, not slug/scope — a same-content
+     *    copy at another slug/scope is no no-op, "applying" it would mint a duplicate file for the id) =
+     *    a REPORTED conflict (`add_guard_absent_conflict`, carrying `currentRev`), NEVER a blind
+     *    overwrite or a duplicate. This is for sync's first-round pull adds, where a concurrent local
+     *    create during the RTT must not be clobbered.
+     *  A plain add WITHOUT this guard keeps its existing idempotent-overwrite semantics (the
+     *  `same-scope re-add of an existing id is the idempotent overwrite` contract clause is unchanged).
+     *  Ignored on `update`/`delete`. */
     guard?: "absent";
 }
+/** Result of {@link MemoryBackend.applyPatches} — applied ops + per-id CAS conflicts (reported, not thrown). */
 export interface PatchReport {
     applied: Array<{
         op: NotePatch["op"];
@@ -55,81 +117,207 @@ export interface PatchReport {
         currentRev?: string;
     }>;
 }
+/**
+ * design/138 §2.1 — the storage seam under the MemoryEngine. NOT a MemoryStore replacement shim: this
+ * is the S1 new-architecture surface (the legacy `MemoryStore` path is untouched and switched off it).
+ */
 export interface MemoryBackend {
+    /** Headers for every entry in the given scopes (manifest surface — bodies excluded). */
     listHeaders(scopes: readonly string[]): Promise<MemoryEntryHeader[]>;
+    /** Full entries for the selected ids (unknown ids silently skipped). */
     getByIds(ids: readonly string[]): Promise<MemoryEntry[]>;
+    /** Scored retrieval (FileBackend = lexical floor; vector rungs live in the S3 PgBackend). */
     search(query: string, scopes: readonly string[], opts?: {
         limit?: number;
     }): Promise<ScoredMemoryEntry[]>;
+    /**
+     * Apply entry transactions (add/update/delete) against the backend's CURRENT state (per-id CAS).
+     *
+     * Behavior clauses a conforming implementation MUST honor (ext-dogfood F1 — each is asserted by
+     * `memoryBackendContract`, listed here so a third party doesn't have to discover them case by case):
+     * - a repeated id WITHIN one batch: first op wins, later ones conflict with reason matching
+     *   /duplicate id in batch/;
+     * - `entry.id !== patch.id` (either op) is refused with reason matching /malformed patch refused/
+     *   — never silently rekeyed;
+     * - an `add` whose slug is taken by a DIFFERENT id in the same scope gets a deterministic `-n`
+     *   suffix (`taken` → `taken-2`); the id stays the identity anchor;
+     * - SAME-SCOPE re-`add` of an existing id is the idempotent overwrite — not a conflict. An add of
+     *   an id living in ANOTHER scope is REFUSED with reason matching /cross-scope add refused/ (2026-07-12
+     *   裁定, all three backends agree — the Pg/TiDB twins always pre-checked this; File now matches).
+     *   The one spelling of a cross-scope MOVE is `update` (next clause) — an add can never relocate an id;
+     * - an `add` carrying `guard: "absent"` is add-if-absent: onto a MISSING id it is a plain add;
+     *   onto an EXISTING id it is idempotent when the rev AND the projection (scope+slug) match, else a
+     *   REPORTED conflict with reason matching /add_guard_absent_conflict/ carrying `currentRev` —
+     *   NEVER a blind overwrite, never a second file for one id (E-02 + 三轮复查投影校验);
+     * - `update` MAY move an entry across scopes; a stale `baseRev` is a REPORTED conflict, never
+     *   thrown, never blind-written;
+     * - design-A I-2 洗白拒收 ([A1]): when the entry's CURRENT committed state carries
+     *   `frontmatter.provenance.kind === "repo_file"`, an `update` whose new frontmatter drops
+     *   `provenance`, or drops a present `trust` marker, is refused with reason matching
+     *   /malformed patch refused/ (same seat as the id-mismatch clause) — repo-originated content
+     *   can never be whitewashed into an unmarked (implicitly trusted) entry. A conforming update of
+     *   such an entry (the ingest producer's own re-ingest) always carries both fields forward;
+     * - conflicts are per-patch and non-fatal: the rest of the batch still applies.
+     */
     applyPatches(patches: readonly NotePatch[]): Promise<PatchReport>;
+    /** design/84 Seam B cursor pair, migrated verbatim onto the entry-id plane (S2 rewires consolidation). */
     getConsolidationCursor(scope: string): Promise<string | undefined>;
     setConsolidationCursor(scope: string, cursor: string): Promise<void>;
 }
+/** One file the engine materialized into the session memory directory. */
 export interface MaterializedFile {
+    /** Absolute canonical path of the projected file. */
     path: string;
+    /** Path relative to the memory dir root (the link target used in the derived MEMORY.md index). */
     relPath: string;
     scope: string;
     id: string;
     slug: string;
+    /** Rev of the ON-DISK content at materialize time (for a stub: the stub content's rev). */
     rev: string;
+    /** True when this file is a budget stub (frontmatter+description only, body archived — §2.3). */
     stub: boolean;
+    /** True when the file belongs to a read-only inherited layer (chmod-protected, never harvested as a write). */
     readonly: boolean;
 }
+/**
+ * design/138 §2.2 — the session handle `materialize` returns and `harvest`/`rebaseline` consume.
+ * `materialized` IS the harvest diff domain (plus session-new files under `writableRoot`): an entry
+ * that was never materialized can never be deleted by its absence (镜头 G).
+ */
 export interface MemorySessionHandle {
+    /** The memory directory root. PURE CONFIG (§2.7 r2.1): a project scope may live IN-REPO
+     *  (git-tracked `memory/`), a user/personal scope OUTSIDE — the engine never asserts either.
+     *  TODO(S1b): per-scope PHYSICAL roots (project scope in-repo + user scope in the home mount in ONE
+     *  session) — `fileToScope` already keys absolute paths, so only the layout mapping needs the split. */
     memoryDir: string;
+    /** The single directory the model may write memory into (the writeScope's home). Equals `memoryDir`
+     *  when the writeScope owns the root (the standard TOC layout). */
     writableRoot: string;
     writeScope: string | null;
     scopes: string[];
+    /** The materialized manifest = the harvest diff domain. */
     materialized: MaterializedFile[];
+    /** Absolute file path → owning scope. */
     fileToScope: Map<string, string>;
+    /** Absolute file path → materialize-time rev (the per-id CAS baseline harvest sends with updates). */
     baseRevs: Map<string, string>;
+    /** Absolute file path → entry id at materialize time (rename/id-restore bookkeeping). */
     baseIds: Map<string, string>;
+    /** design-A C-6 ([A3]) — ingest 条目不投影: entry id → repo-relative `provenance.path` for the
+     *  repo-ingested entries (`frontmatter.provenance.kind === "repo_file"`) materialize did NOT
+     *  project into the writable memory dir (copy-out mode only — the true body lives in the repo;
+     *  a projection would be a duplicate the model can edit into a forgery, I-3). The derived-index
+     *  rebuild links these entries to the recorded repo path instead of a projection file. Absent /
+     *  empty when the session has no such entries (projection behavior byte-identical, pinned). */
     repoIndexTargets?: Map<string, string>;
+    /** Lines of the derived MEMORY.md at materialize time (the index-cleared fuse baseline). */
     indexBaselineLines: number;
+    /** 评审 M6 — the derived index TEXT as of materialize. `inject` reads THIS when no on-disk
+     *  MEMORY.md exists (a read-only layering never writes one), so first-session read-only injection
+     *  works without a disk round-trip. */
     indexText: string;
+    /** Set when the index gate fired AND its containment did not complete — the on-disk MEMORY.md
+     *  still holds the rejected bytes (a clear can be refused: a non-file index path, an unwritable
+     *  one). `inject` then reads {@link indexText} instead of the live file, and offers no index seed:
+     *  the gate's whole purpose is keeping those bytes out of the prompt, so a refused clear must not
+     *  leave the injection path reading them anyway. Absent ⇒ the normal "live file wins" behavior. */
+    indexOnDiskUntrusted?: boolean;
 }
+/** Stable rejection codes a harvest gate can produce (model-visible gate events — 镜头 I). */
 export type HarvestRejectionCode = "outside_root" | "symlink" | "secret" | "injection" | "filename" | "too_large" | "file_cap" | "readonly_layer" | "stub_modified" | "nested_too_deep" | "quarantine_failed" | "unreadable" | "polluted" | "invalid";
+/** One rejected file: path (relative to the memory dir), stable code, and a model-readable reason. */
 export interface HarvestRejection {
     path: string;
     code: HarvestRejectionCode;
     reason: string;
 }
+/**
+ * design/138 S2-C — one finding from the shared write-time/harvest scan rule set
+ * (`scan.ts` `scanMemoryWrite`/`scanMemoryFileName`; ONE rule set, TWO mount points).
+ */
 export interface ScanFinding {
+    /** The subset of {@link HarvestRejectionCode} the scan can produce. */
     code: "secret" | "injection" | "filename" | "too_large";
+    /** Engine-composed, model-readable reason fragment (for `secret`: the pattern LABEL, never the value). */
     reason: string;
 }
+/**
+ * design/138 S2-B — one queued memory-change announcement, drained into the NEXT session's first
+ * injection (时机① only; there is no in-run delivery lane — O-F2/C-F4 裁撤). Queued via the
+ * journaled control-plane queue ({@link import("./layout.js").enqueueMemoryAnnouncement}) so
+ * concurrent writers never overwrite each other (O-F6/C-F5).
+ */
 export interface MemoryAnnouncement {
+    /** `gate` = engine gate/harvest events (rejections, quarantine, incidents, restores, conflicts,
+     *  degradation, applied-patch summary); `external` = out-of-session changes the backend's read-side
+     *  detected (disk rev ≠ ledger: adopted external edits + inbound-gate rejects). */
     kind: "gate" | "external";
+    /** ms epoch at enqueue. */
     at: number;
+    /** Optional producing-session id (repo-level event stream — Q-G: no worktree attribution in S2). */
     sessionId?: string;
+    /** Engine-composed single-line items. O-F1/C-F8: every model/collaborator-controllable identifier
+     *  (path/slug/name/description) is neutralized (inlineUntrusted) AND JSON-quoted at ENQUEUE time —
+     *  the stored strings are already render-safe; the render step only adds the trusted lead/frame. */
     items: string[];
 }
+/**
+ * design/138 §2.4 — the harvest outcome. Rejections are MODEL-VISIBLE gate events: S1 delivers the
+ * structure; the runner's boundary-announcement wiring (attachments member) lands in S2 (TODO(S2)).
+ */
 export interface HarvestReport {
+    /** False ⇔ the whole harvest was refused (deletion fuse / missing dir / corrupt sidecar incident). */
     ok: boolean;
+    /** Set when a fuse tripped (§2.4 删除防线 / B3 fail-closed): the harvest is refused wholesale, NO
+     *  patches (especially no deletes) are produced, and the report is surfaced as an alert. */
     incident?: {
         kind: "mass_deletion" | "index_cleared" | "dir_missing" | "sidecar_corrupt";
         detail: string;
     };
+    /** Patch counts actually APPLIED by the backend. */
     patches: {
         add: number;
         update: number;
         delete: number;
     };
+    /** Per-id CAS conflicts from the backend (reported, never blind-written). */
     conflicts: PatchReport["conflicts"];
     rejections: HarvestRejection[];
+    /** Non-`.md` / non-structural files found in the diff domain — listed, never persisted (they stay
+     *  on disk: they may be the model's working files). Files REMOVED from the model-visible plane go
+     *  in {@link movedToQuarantine}. */
     quarantined: string[];
+    /** Gate-rejected files physically MOVED into the control plane's `quarantine/` (out of the scan
+     *  domain and off the model-visible disk — B2/验收 L4: secret-bearing files never linger). */
     movedToQuarantine: string[];
+    /** C-F9 (S2-0) — quarantine escalations: any deviation from the clean capture+remove path is
+     *  REPORT-VISIBLE here (never a debug-only downgrade). `contained` = the suspect content no longer
+     *  sits raw on the model-visible plane (deleted / cleared in place / overwritten with the committed
+     *  copy); `contained: false` is the worst case — residue remains and a human/runner must act. */
     quarantineFailures?: Array<{
         path: string;
         contained: boolean;
         detail: string;
     }>;
+    /** Materialized files absent at harvest. NOT deletes (§2.4: 文件缺失≠删除). Files whose entry id
+     *  re-appears at another path (a RENAME) are NOT counted here (验收 M1 — a rename is an id-keyed
+     *  update, never a missing file, and never feeds the deletion fuse). */
     missing: string[];
+    /** B1 committed-shadow recovery: missing (non-tombstoned) files RESTORED onto disk from the
+     *  committed copy (backend/shadow). Disclosed here (the restore is an engine action, never silent).
+     *  Restored paths also appear in {@link missing} (the honest record of what vanished). */
     restored: string[];
+    /** Index self-heal notes (L8): suspected-duplicate index lines kept-with-warning, cleared orphans. */
     warnings: string[];
+    /** M7 harvest budget: set when the deadline/file budget cut the harvest short. `pending` files were
+     *  NOT processed this round (no patches, still on disk) — the next boundary harvest picks them up. */
     degraded?: {
         reason: "deadline" | "file_budget";
         pending: string[];
     };
+    /** B2 §2.7 r2.1 inbound gate: findings from scanning changes that did NOT originate in this session
+     *  (e.g. a git-pull-borne edit of an in-repo memory dir — a write channel that bypasses the harvest
+     *  gate). Populated by the backend's read-side sync gate and drained into the report at harvest. */
     inboundFindings?: HarvestRejection[];
 }

package/dist/core/memory-recall.d.ts

@@ -1,14 +1,70 @@
 import type { MemoryNoteHeader, MemoryNoteRecord, MemoryStore } from "./memory.js";
+/**
+ * Selective memory recall (design/65 §2.2 — port of CC `findRelevantMemories`). For a LARGE memory scope,
+ * instead of injecting the whole `<user_memory>` block (inject-all), we inject a compact **manifest** (one
+ * header line per note) + a side-query that picks the ≤K relevant note ids + only those bodies. Small
+ * scopes keep inject-all (the common case after consolidation) — this path is threshold-gated, so most
+ * tasks pay nothing.
+ *
+ * ⚠️ WHAT IS ACTUALLY IN THIS FILE (RB-446, corrected 2026-07-31 — the text below used to describe a
+ * DRIVER that no longer exists here, in the present tense). The 2.0.0 B19 export sweep removed the
+ * function that ran the pipeline; what remains, and what the rest of core consumes, is the set of PURE
+ * HELPERS plus the declared shape of that pipeline:
+ *   · helpers, all live and in use: {@link formatMemoryAge}, {@link RECALL_CAVEAT},
+ *     {@link buildManifestText}, {@link validateSelectedIds}, {@link resolveLinkedIds},
+ *     {@link composeSelectiveBody}, {@link encodeSurfacedKey};
+ *   · seam DECLARATIONS with no in-tree caller: {@link MemorySelector} /
+ *     {@link SelectiveRecallOptions} / {@link SelectiveRecallResult} / {@link LayeredRecallOptions} /
+ *     {@link LayeredRecallResult}. They stay exported because they are the published contract a
+ *     deployment implements its own driver against — the helpers above are exactly the pieces such a
+ *     driver assembles — but nothing under `src/` calls them today. Read them as a specification, not
+ *     as a description of code that runs.
+ *
+ * The pipeline those declarations specify: pure + deterministic given a selector — validate the returned
+ * ids against the manifest (reject hallucinated ids, council #5), cap at K, apply a hard timeout
+ * (council #12), and on ANY selector failure/timeout DEGRADE to inject-all (council #4 — never silently
+ * drop knowledge). Output goes in the variable tail (manifest + selected bodies are per-user/volatile,
+ * like the current memory block). `validateSelectedIds` is the one rung of it that IS implemented here.
+ */
+/** Default max notes the side-query may select (CC `findRelevantMemories` ≤5). */
 export declare const DEFAULT_MAX_SELECTED = 5;
+/** Default max 1-hop link-followed notes appended after the selected ones (design/65 P3). */
 export declare const DEFAULT_MAX_LINKED = 3;
+/** Default side-query hard timeout (ms) — council #12; on timeout we degrade to inject-all. */
 export declare const DEFAULT_SELECT_TIMEOUT_MS = 5000;
+/**
+ * Render a memory note's age as a natural-language phrase (CC-parity P0-1, design/65). CC's eval found
+ * models reason about memory age much better from natural language ("3 days ago") than from a boolean
+ * "older note" flag (verify-claims 0/2 → 3/3 once the age was spelled out), because the model can weigh
+ * staleness proportionally instead of as a single cliff. This is the relative phrase only; the
+ * point-in-time / verify-before-trust discipline still lives in {@link RECALL_CAVEAT} + the per-note
+ * "verify it's still current" hint (the age is ADDITIONAL signal, not a replacement).
+ *
+ * Buckets (each chooses the coarsest unit that's ≥1): `today` (<1 day, incl. future mtime / clock skew →
+ * clamped to today, never a negative age), `yesterday` (1–2 days), `N days ago` (2–7 days),
+ * `N weeks ago` (1 week – ~1 month), `N months ago` (≥ ~1 month). N is floored to the whole unit.
+ */
 export declare function formatMemoryAge(ageMs: number): string;
+/**
+ * Read-side recall caveat (design/65 §8#2 / §9#1 — ported from CC's MEMORY_DRIFT_CAVEAT +
+ * TRUSTING_RECALL_SECTION). The council found CC's two-section form is **eval-validated** (verify-claims
+ * 0/2→3/3) and that the structure carries the effect: the precise decision-point heading
+ * "## Before recommending from memory" scored 3/3 while an abstract heading or a buried bullet scored 0/3.
+ * So this is deliberately TWO sections — a drift bullet + a titled action section with the frame-shift
+ * sentence and concrete verify actions — NOT one merged paragraph (same semantics, 3× worse eval).
+ * MEMORY_SAFETY already carries the authority hierarchy; this adds the point-in-time / verify-before-trust
+ * discipline selective recall specifically needs.
+ */
 export declare const RECALL_CAVEAT: string;
 export interface MemorySelectRequest {
+    /** The task objective the recall is for. */
     objective: string;
+    /** The manifest the selector chooses from (id + description [+ type]). */
     manifest: MemoryNoteHeader[];
+    /** Tools the task will use — for these, keep gotchas/warnings, skip pure usage notes (design/65 §2.2). */
     recentTools?: string[];
 }
+/** The side-query seam: pick the relevant note ids from the manifest. MUST be fail-fast (throw → degrade). */
 export type MemorySelector = (req: MemorySelectRequest, signal?: AbortSignal) => Promise<string[]>;
 export interface SelectiveRecallOptions {
     store: MemoryStore;
@@ -16,13 +72,54 @@ export interface SelectiveRecallOptions {
     objective: string;
     selector: MemorySelector;
     recentTools?: string[];
+    /** Absolute time for the freshness caveat (default Date.now()). */
     nowMs?: number;
     maxSelected?: number;
+    /** Max 1-hop `[[name]]` link-followed notes appended after the selected ones (design/65 P3).
+     *  `0` disables link-following. Default {@link DEFAULT_MAX_LINKED}. */
     maxLinked?: number;
     timeoutMs?: number;
     signal?: AbortSignal;
+    /**
+     * CC-parity P1 (durable cross-worker recall de-dup). Note ids ALREADY surfaced to this logical
+     * conversation in earlier turns/runs (CC's in-process `alreadySurfaced`/readFileState filter, lifted
+     * to a **durable, caller-owned** set so it survives task hops, resume, and multi-worker fan-out). When
+     * provided, these ids are **filtered out of the manifest BEFORE the selector sees it** — the selector
+     * never sees an already-shown note, so it cannot re-select it, so a long/resumed/multi-worker session
+     * does not re-inject the same bodies. core does NOT store this set (like {@link CheckpointStore}, the
+     * durable store is the caller's): the caller persists {@link surfacedIds} from one call and feeds it
+     * back here as `priorSurfacedIds` on the next. Omitted ⇒ no filtering (the prior, non-de-duped behavior).
+     */
     priorSurfacedIds?: ReadonlySet<string>;
 }
+/**
+ * Result of a single-scope selective-recall pass. `surfacedIds` (CC-parity P1) is the set of note ids whose
+ * BODIES this call injected into the prompt — the caller appends them to its durable surfaced-set and
+ * feeds that back as {@link SelectiveRecallOptions.priorSurfacedIds} next time, so a long/resumed/
+ * multi-worker session does not re-inject the same notes. THREE shapes (all carry `surfacedIds`):
+ *
+ *  - **block branch** (`{ block: string }`): a selective-recall block was rendered. `surfacedIds` = the
+ *    validated selection + the 1-hop linked notes (everything whose body was rendered). The caller injects
+ *    `block` verbatim.
+ *
+ *  - **no-new branch** (`{ block: undefined }`): a SUCCESS, NOT a degrade. Every selectable candidate was
+ *    already surfaced earlier (filtered out by {@link SelectiveRecallOptions.priorSurfacedIds}), so there is
+ *    NOTHING NEW to inject. The caller injects NOTHING (no block) — it must NOT fall back to inject-all,
+ *    because inject-all would re-dump the WHOLE scope including the already-shown notes, defeating the
+ *    de-dup. `surfacedIds` is `[]` (this call added no new note to the durable set; the prior ids are
+ *    already in the caller's store). Distinguished from `degrade` precisely so the caller does not
+ *    re-inject (the bug this branch fixes). `"block" in result` is TRUE here (the key is present, value
+ *    `undefined`), so the caller's `"degrade" in result` narrow routes this to the non-degrade path.
+ *
+ *  - **degrade branch** (`{ degrade: true }`): a true FALLBACK — the store can't do selective recall
+ *    (missing manifest/getByIds), the scope is empty, OR the selector failed/timed out. The caller falls
+ *    back to inject-all (never drops knowledge, council #4), a best-effort FULL DUMP that
+ *    `composeMemoryBlock` hard-truncates to a head slice (so it does NOT reliably render every body), and
+ *    the caller already holds the prior surfaced ids. Degrade is therefore not a precise per-id surface that
+ *    can be de-duped: `surfacedIds` is ALWAYS `[]` and degrade does **not** advance the durable surfaced-set.
+ *    (Reporting the full header id list here would over-claim the truncated tail as surfaced → permanent
+ *    silent under-recall on the next turn.)
+ */
 export type SelectiveRecallResult = {
     block: string;
     surfacedIds: string[];
@@ -34,18 +131,57 @@ export type SelectiveRecallResult = {
     surfacedIds: string[];
 };
 export declare function resolveLinkedIds(headers: MemoryNoteHeader[], selected: MemoryNoteRecord[], max: number): string[];
+/** Render the manifest as compact lines, double-capped (council #7). One line per note, guaranteed. */
 export declare function buildManifestText(headers: MemoryNoteHeader[]): string;
+/** Keep only ids present in the manifest (reject hallucinated, council #5), de-duped, capped at `max`. */
 export declare function validateSelectedIds(headers: MemoryNoteHeader[], ids: string[], max: number): string[];
+/**
+ * Render the BODY of a selective-recall block: the optional `recall` manifest index + the selected note
+ * bodies (+ 1-hop linked notes), WITHOUT the outer `<user_memory>` wrapper and WITHOUT {@link RECALL_CAVEAT}.
+ * The wrapper + caveat are the caller's job — a single-scope caller places ONE caveat
+ * inside ONE `<user_memory scope=… mode="selective">`, and the layered renderer places ONE caveat inside ONE
+ * `<user_memory mode="selective">` ahead of N `<scope>` subsections (MAJOR fix: no nested fences, no per-scope
+ * caveat duplication).
+ *
+ * `recallable` controls the "Memory index — load in full …" affordance (MAJOR fix): the on-demand recall
+ * tool is bound to a SINGLE scope, so the "load in full" instruction is only TRUE for that scope. Pass
+ * `false` for non-recallable layers — the selected bodies are already rendered inline, so the index is just a
+ * false affordance that wastes a tool call (model searches the wrong scope → "No memory matches").
+ *
+ * `recallToolName` (#181-F1, additive) is the WIRE name of the host-mounted recall tool the affordance
+ * teaches. Core mounts no such tool ("Recall" is a RETIRED name — tool-name-aliases.ts), so a hard-coded
+ * name here can only ever be stale; the host that mounted the tool passes the name it mounted it under.
+ * Omitted ⇒ a name-free "search the memory-recall tool" wording (honest without inventing a name).
+ *
+ * Notes are tagged with their natural-language age (CC-parity P0-1, design/65; >1-day-old ones keep the
+ * "verify it's still current" hint, council #8). `linked` (design/65 P3) are 1-hop `[[name]]`-followed notes,
+ * rendered in their own clearly-labeled subsection AFTER the selected ones — expanded as DATA under the same
+ * fence/sanitize/byte-cap discipline (design/65 §8#9: a followed link must not become markup or escalate authority).
+ */
 export declare function composeSelectiveBody(manifestText: string, selected: MemoryNoteRecord[], nowMs: number, linked?: MemoryNoteRecord[], recallable?: boolean, recallToolName?: string): string;
+/** A `(scope, id)` composite key for the multi-scope durable de-dup (design/84 Seam A decision 5). Note ids
+ *  are only unique WITHIN a scope, so the cross-scope `priorSurfacedKeys`/`surfacedKeys` set MUST be keyed on
+ *  both. Core owns the FORMAT so a caller can't drift the wire format (decision 7) — the encoding is OPAQUE
+ *  and length-prefixes the scope so a scope/id containing the separator cannot forge a collision.
+ *
+ *  ONE-WAY by design (codex MINOR (d)): the key is only ever PRODUCED here (`surfacedKeys`) and compared by
+ *  STRING EQUALITY against the caller's persisted set ({@link LayeredRecallOptions.priorSurfacedKeys}, applied
+ *  at memory-recall.ts via `priorSurfacedKeys.has(encodeSurfacedKey(h.scope, h.id))`). Nothing ever needs the
+ *  `(scope, id)` BACK out of a key, so there is intentionally NO `decodeSurfacedKey` — adding a decode would
+ *  widen the public surface (and invite callers to parse the opaque format) for zero consumer. Treat the key
+ *  as an opaque token: persist it, feed it back, compare for equality — never split it. */
 export declare function encodeSurfacedKey(scope: string, id: string): string;
+/** A manifest header tagged with the scope it came from (design/84 Seam A decision 5). */
 export interface ScopedNoteHeader extends MemoryNoteHeader {
     scope: string;
 }
+/** A full record tagged with its scope (for cross-scope getByIds). */
 export interface ScopedNoteRecord extends MemoryNoteRecord {
     scope: string;
 }
 export interface LayeredRecallOptions {
     store: MemoryStore;
+    /** Ordered scopes (design/84 Seam A): list order = priority; the last is highest. */
     scopes: ReadonlyArray<string>;
     objective: string;
     selector: MemorySelector;
@@ -55,8 +191,13 @@ export interface LayeredRecallOptions {
     maxLinked?: number;
     timeoutMs?: number;
     signal?: AbortSignal;
+    /** CC-parity P1, multi-scope: `(scope,id)` composite keys ({@link encodeSurfacedKey}) already surfaced to
+     *  this logical conversation. Filtered out of the merged manifest BEFORE the selector sees it. */
     priorSurfacedKeys?: ReadonlySet<string>;
 }
+/** Result of a multi-scope (layered) selective-recall pass. `surfacedKeys` are `(scope,id)` composite keys
+ *  ({@link encodeSurfacedKey}) — the caller appends them to its durable set and feeds them back as
+ *  {@link LayeredRecallOptions.priorSurfacedKeys}. Mirrors {@link SelectiveRecallResult}'s three shapes. */
 export type LayeredRecallResult = {
     block: string;
     surfacedKeys: string[];

package/dist/core/memory-vector.d.ts

@@ -1,3 +1,23 @@
+/**
+ * design/81 Slice 5 — the shared distance primitives for the consolidation `searchScored` retrieval, extracted
+ * BYTE-IDENTICAL from the original PgMemoryStore implementation so the File (portable/TOC) and Pg (native/TOB)
+ * backends rank on ONE source of truth and can't drift. The `{@link import("./runner/memory-consolidation.js")}`
+ * band `{0.05, 0.3}` is defined on this cosine-distance scale; the lexical `1 - Jaccard ∈ [0,1] ⊂ [0,2]` is the
+ * same-zero-point stand-in used when no embedding vector is present (fail-open per row).
+ *
+ * The capability LADDER a store reports via {@link import("./memory.js").MemoryStore.vectorMode}:
+ *  - `lexical`  — no embedder: `1 - Jaccard(terms)` everywhere.
+ *  - `portable` — embedder + IN-PROCESS cosine over stored vectors (File jsonl / Pg jsonb / MySQL JSON — ANY
+ *                 backend that can store a float array; O(n) over the scope, no index).
+ *  - `native`   — embedder + a backend index/operator (pgvector `<=>` / TiDB `VEC_COSINE_DISTANCE`).
+ * MySQL is NOT "can't support vectors" — it is `portable`-capable (JSON column + in-process cosine), just not
+ * `native`. A deployment injects an embedder (config-driven); the store then reports the achieved rung.
+ */
+/** Lower-cased alphanumeric term set of a string (for the lexical stand-in distance). */
 export declare function termSet(s: string): Set<string>;
+/** Lexical stand-in distance: `1 - Jaccard(terms)` ∈ [0,1] ⊂ [0,2]; `null` = no overlap (not a candidate). */
 export declare function jaccardDistance(query: Set<string>, text: string): number | null;
+/** Cosine distance ∈ [0,2] (0 = identical), the {@link import("./memory.js").ScoredMemory} contract. Uses
+ *  `Math.min(a.length,b.length)` — a store MUST only call this on dimension-matched vectors (the row-level
+ *  dimension guard lives at the caller; a mismatch falls open to {@link jaccardDistance}). */
 export declare function cosineDistance(a: number[], b: number[]): number;