@sema-agent/core 5.20.0 → 5.21.0

package/dist/core/memory-engine/scope-contract.d.ts

@@ -1,5 +1,21 @@
+/** Per-segment cap, measured AFTER encoding. A conservative portability policy adopted as contract
+ *  (research (d) recommendation — NOT a verified third-party hard limit; uuidv7 = 36 chars fits). */
 export declare const SCOPE_SEGMENT_MAX_ENCODED = 64;
+/**
+ * Canonical injective encoding for a raw identifier entering a scope key: everything outside
+ * `[A-Za-z0-9._-]` becomes `%XX` (UTF-8 bytes), INCLUDING `%` itself (that self-encoding is what
+ * makes the map injective — no `__`-style collidable escapes). Throws when the encoded segment
+ * exceeds {@link SCOPE_SEGMENT_MAX_ENCODED} (an over-long principal is a deployment config error)
+ * or when the raw value is empty.
+ */
 export declare function encodeScopeSegment(raw: string): string;
+/**
+ * Inverse of {@link encodeScopeSegment}, CANONICAL-FORM ONLY (codex 复审 B6): the input must be
+ * exactly what the encoder produces — safe chars stay bare (so `%41` for `A` is refused: two
+ * spellings of one identity must not mint two keys), `%XX` sequences must decode as valid UTF-8
+ * (fatal decoder — no U+FFFD smoothing), and the 64-char cap holds here too (parse side enforces
+ * what the format side promised).
+ */
 export declare function decodeScopeSegment(encoded: string): string;
 export type ParsedScopeKey = {
     kind: "user";
@@ -15,7 +31,9 @@ export type ParsedScopeKey = {
     kind: "userproj";
     principal: string;
     projectId: string;
-} | {
+}
+/** No recognized v2 prefix: an opaque legacy scope (fully valid under the v2 contract too). */
+ | {
     kind: "legacy";
     raw: string;
 };
@@ -23,20 +41,62 @@ export declare function formatUserScope(principal: string): string;
 export declare function formatOrgScope(tenant: string): string;
 export declare function formatProjScope(tenant: string, projectId: string): string;
 export declare function formatUserProjScope(principal: string, projectId: string): string;
+/**
+ * Parse a scope key under the v2 contract. A key carrying a recognized prefix MUST be well-formed
+ * (fail-loud — a malformed `proj:` key under an explicit opt-in is a config error, not an opaque
+ * scope); anything without a recognized prefix parses as `{ kind: "legacy" }` and keeps today's
+ * opaque behavior. NEVER call this on a deployment that has not opted in (see module header).
+ */
 export declare function parseScopeKey(key: string): ParsedScopeKey;
+/** True when a v2-parsed key belongs to a PERSONAL plane (`user:` / `userproj:`). */
 export declare function isPersonalScope(parsed: ParsedScopeKey): boolean;
+/** True when the key's AUTHORITY is central (design/142 §2 表: user/userproj/org rows) — these keys
+ *  must never project into an in-repo memory dir (they would leak to every collaborator AND enter
+ *  commit history; codex 复审 B1 extended the F9 gate from personal to org). `proj:`/legacy stay
+ *  repo-planed. */
 export declare function isCentralAuthorityScope(parsed: ParsedScopeKey): boolean;
+/**
+ * design/142 §7 S1 hard gate (复审 F9): until S1b per-scope physical roots land, ALL scopes of a
+ * session materialize under ONE root — so a v2 session mixing `user:*`/`userproj:*` keys with an
+ * IN-REPO memory dir would project personal memory into the repo (the exact §2.7 leak shape:
+ * personal notes committed to a shared/open repo). Fail-loud, never fail-open: this throws a
+ * `config.`-coded error the prepare path must NOT swallow.
+ */
 export declare function assertScopeContractPlacement(args: {
     parsedScopes: readonly ParsedScopeKey[];
     memoryDir: string;
+    /** The repo/workspace root the session works in (undefined = no repo context, gate passes). */
     repoRoot: string | undefined;
 }): void;
+/** Repo-root marker file: minted once (by scaffold/deployment, NEVER by the engine), committed, and
+ *  from then on the project's identity survives clone/copy/rename/machine/cloud-sandbox. */
 export declare const PROJECT_MARKER_PATH = ".sema/project";
+/** projectId 格式单源([637]① 承诺):generic UUID,version nibble 不收紧——宽读严写(读面认外部/
+ *  历史 v4;铸造面 formatProjectMarker / center mint 统一产 uuidv7)。center 侧自持镜像+dev-only
+ *  drift 锁对着这条(registry-core coreTypes 先例)。 */
 export declare const PROJECT_ID_REGEX: RegExp;
+/** Serialize a marker file body (scaffold-side helper; the engine itself never writes one). */
 export declare function formatProjectMarker(projectId: string): string;
+/** Parse a marker body: TOML-subset `key = value` lines, `#` comments and blank lines ignored,
+ *  optional quotes around the value. Unknown keys are ignored (forward-compatible). codex 复审 H7:
+ *  ANY line that starts a `projectId` assignment but is not one canonical UUID assignment is a
+ *  CORRUPT marker (fail-loud, `config.memory_project_marker`) — an empty value, an unclosed quote,
+ *  a non-UUID, or a DUPLICATE projectId line must never degrade to "no marker" (that would be a
+ *  silent identity change back to the path key). Returns null only when NO projectId line exists. */
 export declare function parseProjectMarker(body: string): {
     projectId: string;
 } | null;
+/**
+ * design/142 §1.1 — resolve a project's identity. READS ONLY THE MARKER (复审 F2: never derives an
+ * identity from a git remote; remote-URL normalization is a scaffold-side minting heuristic, not an
+ * identity source). v1 scope (复审 F10): ONE marker at the project root —
+ *  - inside a git repo, the root is the REPO root; a marker at a nested directory that is not the
+ *    repo root is fail-loud (`config.memory_project_marker_nested`) — monorepo sub-project identity
+ *    is a future need-signal, not a silent second identity;
+ *  - outside git, the given rootDir IS the project root (path-form local projects).
+ * Returns null when no marker exists (callers fall through the resolution ladder: explicit
+ * declaration → path fallback with a warning).
+ */
 export declare function resolveProjectId(rootDir: string): {
     projectId: string;
     markerDir: string;

package/dist/core/memory-engine/sync-client.d.ts

@@ -1,35 +1,72 @@
 import { type MemorySyncCursor } from "./sync.js";
 import type { MemoryBackend, MemoryEntry, PatchReport } from "./types.js";
+/** The injected HTTP seam — core never bundles a fetch. The deployment maps `path` (e.g.
+ *  `/v1/memory/sync/user%3Aalice`) onto its server base URL, attaches auth, and returns the
+ *  DECODED JSON body of a 2xx response; any non-2xx / network failure should THROW (the round then
+ *  aborts with zero local side effects — the transport runs before any local write). */
 export type MemorySyncTransport = (path: string, body: unknown) => Promise<unknown>;
+/** The wire REQUEST of one round (the server's `parseMemorySyncRequest` twin — [671]①): the push
+ *  half as computed against the client's own cursor. `deletes` ⊆ `Object.keys(baseRevs)` by
+ *  construction (a delete is CAS'd on its baseline; an id never synced cannot be delete-propagated). */
 export interface MemorySyncRequestBody {
     peer: string;
+    /** id → rev at the last completed round (the cursor's baseRevs; empty = first round). */
     baseRevs: Record<string, string>;
+    /** Full state of every entry new/changed here since the baseline. When
+     *  {@link SyncMemoryScopeOptions.maxPushEntries} is set this is the id-ascending PREFIX of the
+     *  full push set ([767]③ batching — the remainder rides later rounds). */
     entries: MemoryEntry[];
+    /** Ids deleted here since the baseline (tombstoned or gone from the local plane). Deletes are
+     *  NEVER batched/split — they are id+baseRev pairs, weightless next to entry bodies ([767]③). */
     deletes: string[];
+    /** [767]③ pull-half batching (wire contract; server implements the response side): ask the
+     *  server to cap this round's pull half at `limit` items. Absent ⇔ unbatched (the pre-[767]③
+     *  wire shape byte-for-byte — old servers never see the key). */
     pull?: {
         limit?: number;
     };
 }
+/** The wire RESPONSE of one round (server `MemorySyncResponse` twin — [671]①: one RTT, both
+ *  directions; `serverDeletes` is the delete-propagation leg [codex B4 — without it a central
+ *  removal never crosses = livelock]; `cursor` is the server-computed next baseline with the
+ *  retention discipline ALREADY applied to the pull half). */
 export interface MemorySyncResponseBody {
+    /** Ops the server actually landed from our push (empty on an idempotent replay). */
     applied: PatchReport["applied"];
+    /** Server-side rejections/divergences: inbound-gate rejects, rev lies, CAS losses, both-sides
+     *  divergence (resolve via the §3 ladder — loser minted as a sibling, never dropped). */
     conflicts: Array<{
         id: string;
         reason: string;
         baseRev?: string;
         currentRev?: string;
     }>;
+    /** The pull half: entries new/changed centrally since our baseline. */
     serverEntries: MemoryEntry[];
+    /** The pull half's delete leg: centrally deleted, unchanged here since baseline (CAS baseRev). */
     serverDeletes: Array<{
         id: string;
         baseRev: string;
     }>;
+    /** The next baseline to persist AFTER the pull half lands (the client cannot compute it — it
+     *  does not hold the central set). Pull-half ids are retained at the OLD baseline inside; the
+     *  client advances the LANDED ones to their landed state before persisting (see ⑤ — otherwise
+     *  every landed pull echoes back next round and a central delete can be resurrected). */
     cursor: {
         peer: string;
         baseRevs: Record<string, string>;
         updatedAtMs: number;
     };
+    /** [767]③ pull-half batching (wire contract; server sets it): true ⇔ the server withheld part
+     *  of the pull half under the requested `pull.limit` — the caller should run another round.
+     *  The server MUST retain every withheld id at the OLD baseline inside `cursor` (the client
+     *  refuses prefilled undelivered revs — see ⑤ defense — so violating this only costs the
+     *  server an ignored advance plus a disclosed warning, never a permanently-missed pull). */
     pullTruncated?: true;
 }
+/** One aggregated conflict: `server` = reported by the central half (its gate/CAS/divergence),
+ *  `local` = produced landing the pull half here (our CAS refusals, inbound-gate rejects, rev
+ *  lies). Nothing is hidden; the caller resolves via the §3 ladder (loser-as-sibling). */
 export interface MemorySyncClientConflict {
     side: "server" | "local";
     id: string;
@@ -38,29 +75,79 @@ export interface MemorySyncClientConflict {
     currentRev?: string;
 }
 export interface SyncMemoryScopeOptions {
+    /** The LOCAL authority plane (TOC: the File backend). */
     backend: MemoryBackend;
+    /** The scope this round syncs (one round = one scope, mirroring the server route). */
     scope: string;
+    /** The injected HTTP seam. */
     transport: MemorySyncTransport;
+    /** The persisted cursor from the last completed round with this peer; absent = first round. */
     cursor?: MemorySyncCursor;
+    /** Peer name for the cursor partition (defaults to the cursor's peer, else "central"). */
     peer?: string;
+    /** Caller-injected clock (engine precedent) — stamps the returned cursor's updatedAtMs. */
     now?: () => number;
+    /** [767]③ push-half batching: cap the number of push-half ENTRIES sent this round. The full
+     *  push set is put in STABLE order (id ascending — deterministic across rounds/replicas) and the
+     *  first `maxPushEntries` ride the wire; a cut round reports `pushTruncated: true`. Deletes are
+     *  never split (id+baseRev pairs are weightless next to bodies). CALLER CONTRACT: on
+     *  `pushTruncated`/`pullTruncated`, persist the returned cursor and run ANOTHER round until both
+     *  flags clear — core deliberately never loops internally (the runner loop is the deployment's,
+     *  server-side semantics per [767]③); bound your loop (e.g. a fixed max-rounds cap ≥
+     *  ⌈expected entries / limit⌉ + slack) so a misbehaving peer cannot spin it forever. Must be a
+     *  POSITIVE integer (≥ 1 — C5: a 0 cap would flag pushTruncated forever and livelock the caller
+     *  loop); absent ⇔ unbatched (pre-[767]③ behavior byte-for-byte). */
     maxPushEntries?: number;
+    /** [767]③ pull-half batching: forwarded verbatim as the wire request's `pull.limit`; a server
+     *  that withholds part of its pull half answers `pullTruncated`, passed through on the result.
+     *  Same caller contract as {@link maxPushEntries}: continue rounds (bounded) until it clears.
+     *  Must be a POSITIVE integer (≥ 1 — C5, same livelock gate); absent ⇔ the request carries NO
+     *  `pull` key (old-server compatible, pre-[767]③ wire bytes). */
     maxPullEntries?: number;
+    /** design/178 §3 — per-entry byte bound for the PUSH gate, matched against the entry's serialized
+     *  file form (the same domain the harvest gate measures). Defaults to {@link MAX_MEMORY_BYTES},
+     *  the engine's own per-file cap, so the wire cannot carry an entry the local gate would have
+     *  refused: `scanMemoryWrite`'s size rung only runs when it is given a bound, and an entry that
+     *  reached the backend out of band is exactly the population this gate exists for. */
     maxEntryBytes?: number;
 }
 export interface MemorySyncClientResult {
+    /** True ⇔ the round was fully clean: cursor advanced AND zero conflicts on either side. */
     ok: boolean;
+    /** What the push half contained (ids only — the bodies already went over the wire). */
     pushed: {
         entries: string[];
         deletes: string[];
     };
+    /** Ops the server landed from our push (response `applied` verbatim). */
     serverApplied: PatchReport["applied"];
+    /** Ops we landed locally from the pull half. */
     localApplied: PatchReport["applied"];
+    /** Aggregated server-reported + local conflicts (never hidden). */
     conflicts: MemorySyncClientConflict[];
+    /** True ⇔ every pull-half item landed cleanly, so `cursor` is the NEW baseline to persist. */
     cursorAdvanced: boolean;
+    /** The cursor the caller should now persist: advanced on full success, otherwise the INPUT
+     *  cursor unchanged (undefined on a failed first round) — the retention discipline. */
     cursor: MemorySyncCursor | undefined;
+    /** [767]③: present (true) ⇔ `maxPushEntries` cut this round's push set — run another round off
+     *  the persisted cursor until it clears (see the {@link SyncMemoryScopeOptions.maxPushEntries}
+     *  caller contract). Never present on an uncut round (additive: old callers see no new key). */
     pushTruncated?: true;
+    /** [767]③: present (true) ⇔ the server reported its pull half was cut under `pull.limit` —
+     *  same continue-until-clear caller contract. */
     pullTruncated?: true;
+    /** Honest-disclosure channel for tolerated protocol violations (present only when non-empty).
+     *  Today's single producer is the ⑤ cursor-prefill defense: a server that advances a
+     *  NOT-DELIVERED-HERE id's rev inside the response cursor gets that advance REFUSED (old
+     *  baseline kept / unknown id dropped) and disclosed here — silently swallowing it would turn
+     *  the next round's pull judgment into a permanent miss (baseline == central rev ⇒ never
+     *  pulled) or, for an unknown id, a spurious push-half DELETE of an entry never seen here. */
     warnings?: string[];
 }
+/**
+ * One full CLIENT sync round for one (scope, peer) against the [671]① central sync API — see the
+ * module header for the ①-⑤ flow and the cursor retention discipline. Pure orchestration: all I/O
+ * rides the injected backend/transport; the caller persists the returned cursor.
+ */
 export declare function syncMemoryScope(opts: SyncMemoryScopeOptions): Promise<MemorySyncClientResult>;

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

@@ -1,36 +1,96 @@
 import type { MemoryEntry, ScoredMemoryEntry } from "./types.js";
+/**
+ * design/142 §3 — the per-replica per-scope sync cursor: the COMMON BASELINE a reconciliation run
+ * judges divergence against (`id → rev` as of the last completed sync round). This is a NEW
+ * persistence face — deliberately NOT revs.json (that is the local disk-vs-committed ledger): File
+ * plane = a control-plane sidecar, DB plane = a service-owned table (PG+TiDB, [628] dual-dialect).
+ * Serializable by construction.
+ */
 export interface MemorySyncCursor {
     scope: string;
+    /** The PEER this cursor tracks (e.g. "central", a repo remote name) — one cursor per peer. */
     peer: string;
+    /** id → rev at the last completed sync round with this peer. */
     baseRevs: Record<string, string>;
+    /** Caller-injected clock (never Date.now inside the engine — clock-injection precedent). */
     updatedAtMs: number;
 }
 export interface MemorySyncConflict {
     id: string;
+    /** Present when the side still has the entry (absent = deleted on that side). */
     local?: MemoryEntry;
     remote?: MemoryEntry;
     baseRev?: string;
 }
 export interface MemorySyncPlan {
+    /** Entries the LOCAL side should send to the peer (new here or changed-here-only). 独立轨 F8 —
+     *  CAS discipline for the peer write: a push item exists ONLY when the peer is still at the
+     *  baseline, so the peer-side conditional write uses `baseRevs[id]` as its baseRev (absent from
+     *  the baseline ⇒ the peer has no such entry ⇒ plain add). Never write the peer unconditionally. */
     push: MemoryEntry[];
+    /** Entries the LOCAL side should adopt from the peer (new there or changed-there-only). Same CAS
+     *  discipline as {@link push}, mirrored: local conditional write with `baseRevs[id]`. */
     pull: MemoryEntry[];
+    /** codex 复审 B4 — DELETE propagation (without these the removal never crosses and every round
+     *  re-plans the same state = livelock): the peer removed an entry the local side left UNCHANGED
+     *  since baseline ⇒ delete locally (CAS on baseRev — a local edit racing in makes the delete a
+     *  conflict on the next round instead of silent loss). */
     deleteLocal: Array<{
         id: string;
         baseRev: string;
     }>;
+    /** Symmetric: locally removed, peer unchanged since baseline ⇒ delete on the peer. */
     deleteRemote: Array<{
         id: string;
         baseRev: string;
     }>;
+    /** Both sides diverged from the baseline (or delete-vs-edit races): the caller resolves via the
+     *  §3 ladder — winner by the caller's policy, LOSER MINTED AS A SIBLING entry (never dropped),
+     *  the pair recorded so a three-way exchange cannot rebuild the same conflict forever. */
     conflicts: MemorySyncConflict[];
+    /** Ids deleted on BOTH sides since the baseline (pure cursor cleanup, no data movement). */
     cleared: string[];
 }
+/**
+ * Pure three-way set reconciliation over one scope. `baseRevs` = the persisted common baseline
+ * (empty object = first sync round: everything present is "new" on its side; identical revs on
+ * both sides collapse to no-op).
+ *
+ * Judgment per id (rev lineage, mtime never consulted):
+ *  - both sides at baseline rev → no-op;  identical revs (any lineage) → no-op + baseline advance;
+ *  - changed on exactly ONE side → push/pull;
+ *  - changed on BOTH sides, or delete-on-one × edit-on-the-other → conflict (caller's ladder);
+ *  - deleted on one side × UNCHANGED on the other → the delete propagates (deleteLocal/deleteRemote,
+ *    CAS on baseRev — codex B4: without this leg removals never cross and the plan livelocks);
+ *  - present only on one side with NO baseline → new entry → propagate;
+ *  - absent on both but present in baseline → cleared (cursor cleanup).
+ */
 export declare function reconcileMemoryEntries(baseRevs: Readonly<Record<string, string>>, local: readonly MemoryEntry[], remote: readonly MemoryEntry[]): MemorySyncPlan;
+/** The baseline to persist AFTER a sync round completes: every id both sides now agree on. The
+ *  caller passes the POST-round entry sets (after applying push/pull and resolving conflicts). */
 export declare function nextSyncBaseline(local: readonly MemoryEntry[], remote: readonly MemoryEntry[]): Record<string, string>;
+/**
+ * A third-party semantic recall side-channel (Mem0/Zep/Cognee/… adapters — research 2026-07-12:
+ * all five surveyed engines fit THIS seat; none fits the authority seat). STRICTLY READ-ONLY by
+ * construction: a RecallSource feeds candidate hits into injection-time recall; it never sees the
+ * write path, never participates in harvest, and the system runs identically without it.
+ *
+ * Score contract: DISTANCE in [0, 2] (0 = identical, 2 = orthogonal — the vector-rung convention);
+ * adapters normalize their similarity/relevance scores into this scale. Returned entries may be
+ * the third party's RE-STATEMENTS (extractive engines rewrite) — that is acceptable HERE precisely
+ * because the seat is advisory: the authoritative body is re-read from the real backend by id/slug
+ * when a hit is followed. Mount point: a deployment composes its RecallSource(s) inside its recall
+ * select hook (the design/65 selective-recall trust seat) or pre-queries before prepare; core adds
+ * no RunnerDeps seat until a real integration signals the need (YAGNI, [622]③ two-lane ruling).
+ */
 export interface RecallSource {
+    /** Stable adapter name (diagnostics/attribution: hits are labeled, never silently mixed). */
     name: string;
     search(query: string, scopes: readonly string[], opts?: {
         limit?: number;
     }): Promise<ScoredMemoryEntry[]>;
 }
+/** Merge recall hits from multiple sources with the authority backend's own results: id-deduped
+ *  (FIRST occurrence wins — callers order sources by trust, authority first), ascending by score
+ *  (distance), capped at `limit`. Pure — no I/O, no source calls. */
 export declare function mergeRecallHits(hitLists: ReadonlyArray<readonly ScoredMemoryEntry[]>, limit: number): ScoredMemoryEntry[];

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

@@ -1,14 +1,49 @@
+/**
+ * design/178 v1 — the two engine-memory retrieval tools (`memory_search` / `memory_get`).
+ *
+ * These are the first runner-wired consumers of the `MemoryBackend.search()`/`getByIds()` contract:
+ * a deterministic keyword lookup over the session's mounted scopes plus a paged full-content read.
+ * Zero contract changes — the tools sit entirely ON TOP of the backend seam.
+ *
+ * READ-ONLY BY STRUCTURE. Neither tool can write; the write path stays the file channel + harvest
+ * gate. Entry content returned to the model is DATA, not instructions: every body fragment rides an
+ * untrusted fence (`delimitUntrusted`) and every header field a model could have authored
+ * (name/description/slug/scope) is neutralized inline. Results are byte-bounded.
+ *
+ * THE PAIR IS ATOMIC. Each tool names the other in its description, so a half-mount would teach a
+ * tool that is not there — the mount site (runner/prepare-task.ts) mounts both or neither.
+ *
+ * RESULT ORDER IS THE BACKEND CONTRACT ORDER (v1 pinned): ascending cosine-distance score with the
+ * deterministic id tie-break, exactly what `MemoryBackend.search()` promises. Multi-plane sessions
+ * merge by the same comparator, so a single-plane session's order is byte-equal to the backend's.
+ * No other signal participates — in particular the retrieved account is WRITTEN here and never read.
+ *
+ * REFUSALS ARE VALUES (shared-memory tools precedent): every negative outcome is a structured result
+ * with a machine reason; exceptions are reserved for defects and for cancellation, which is re-thrown
+ * so the engine's abort path stays the abort path.
+ */
 import type { ToolSpec } from "../types.js";
 import type { MemoryBackend } from "./types.js";
 export declare const MEMORY_SEARCH_TOOL_NAME = "memory_search";
 export declare const MEMORY_GET_TOOL_NAME = "memory_get";
+/** The atomic pair, in mount order (same shape as SHARED_MEMORY_TOOL_NAMES). */
 export declare const MEMORY_ENGINE_TOOL_NAMES: readonly ["memory_search", "memory_get"];
+/** Default / maximum hit counts for one search call. */
 export declare const MEMORY_SEARCH_DEFAULT_LIMIT = 8;
 export declare const MEMORY_SEARCH_MAX_LIMIT = 20;
+/** Per-hit body-fragment bound (code points, enforced by the fence itself). */
 export declare const MEMORY_SEARCH_SNIPPET_CAP = 600;
+/** Default / maximum lines of one memory_get page. */
 export declare const MEMORY_GET_PAGE_LINES = 200;
 export declare const MEMORY_GET_MAX_PAGE_LINES = 1000;
+/** Byte bound of one memory_get page body (lines past it defer to the next page). */
 export declare const MEMORY_GET_PAGE_CAP_BYTES: number;
+/**
+ * One retrieval plane: a backend plus the scopes THIS SESSION mounted on it (dual-root sessions have
+ * two, single-root sessions one). `scopes` is the containment boundary — `getByIds` is id-keyed
+ * across every scope the backend knows, so results are filtered back to the mounted set here.
+ * `recordRetrieved` feeds the plane's control-plane retrieved account (collect-only, never throws).
+ */
 export interface MemoryEnginePlane {
     backend: MemoryBackend;
     scopes: readonly string[];
@@ -16,6 +51,7 @@ export interface MemoryEnginePlane {
 }
 export interface MemoryEngineToolsOptions {
     planes: ReadonlyArray<MemoryEnginePlane>;
+    /** Clock (tests); default Date.now. Drives the natural-language age rendering only. */
     now?: () => number;
 }
 export interface MemorySearchHit {
@@ -24,6 +60,7 @@ export interface MemorySearchHit {
     slug: string;
     name?: string;
     description?: string;
+    /** Cosine-distance ∈ [0,2], 0 best — the backend contract's score, untransformed (v1). */
     score: number;
     mtimeMs: number;
     sizeBytes: number;
@@ -39,6 +76,7 @@ export interface MemoryGetDetails {
     id?: string;
     scope?: string;
     slug?: string;
+    /** Candidates of an ambiguous bare-slug lookup — scope-qualified, never silently picked from. */
     candidates?: Array<{
         scope: string;
         slug: string;
@@ -48,6 +86,9 @@ export interface MemoryGetDetails {
     lines?: number;
     totalLines?: number;
 }
+/** Cut `text` to at most `maxBytes` UTF-8 bytes on a CODE POINT boundary (a byte-wise slice would
+ *  strand half a character), reporting how many bytes were dropped. Unchanged text reports 0.
+ *  Exported for the truncation-invariant registry — a bound-taking function has to be provable. */
 export declare function cutToBytes(text: string, maxBytes: number): {
     text: string;
     omittedBytes: number;