comisai 1.0.42 → 1.0.45

package/node_modules/@comis/core/dist/api-contracts/memory.js

@@ -1,17 +1,19 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Memory + context-domain RPC contracts. Mirrors the two daemon handler
- * factory files that share the `MemoryApiDeps` cluster slice:
+ * Memory-domain RPC contracts. Mirrors the daemon handler factory file that
+ * owns the `MemoryApiDeps` cluster slice:
  *
  *   - `packages/daemon/src/api/memory-handlers.ts`  (8 methods)
- *   - `packages/daemon/src/api/context-handlers.ts` (7 methods)
  *
- * Both handler files map to the SAME ApiDeps slice (`MemoryApiDeps`) and
- * so share one contract file (one contract file per logical domain
- * mirroring the `*ApiDeps` slices). The aggregator below preserves
- * per-handler grouping via `// --- xxx-handlers.ts ---` comment blocks;
- * the order within the array is documentation-only (the bidirectional
- * 1:1 test treats it as an unordered set).
+ * NOTE (v2.12, Phase 126): the sibling `context-handlers.ts` (7 `context.*`
+ * methods) and its 7 `Context*Contract` definitions were REMOVED with the DAG
+ * context engine. The governed context-expansion RPC surface is reintroduced
+ * fresh by the LCD engine (Phase 131).
+ *
+ * The aggregator below preserves per-handler grouping via
+ * `// --- xxx-handlers.ts ---` comment blocks; the order within the array is
+ * documentation-only (the bidirectional 1:1 test treats it as an unordered
+ * set).
  *
  * **Scope assignments** (mirror `setup-gateway-api.ts` registrations):
  *
@@ -24,28 +26,18 @@
  *                                     intended trust model.
  *   - `memory.get_file`     (rpc) — agent-level file read via safePath.
  *                                     Registered via agent tool dispatch.
- *   - `memory.store`        (admin) — setup-gateway-api.ts line 235.
- *                                      Handler ADDITIONALLY supports a
- *                                      non-admin agent path (defaults to
- *                                      `learned` trust level + agent
- *                                      attribution); the contract scope
- *                                      documents the registered gateway
- *                                      route.
+ *   - `memory.store`        (rpc) — AGENT-REACHABLE (MD-02): the agent
+ *                                      `memory_store` tool is the primary caller.
+ *                                      The handler routes on `_trustLevel` — admin
+ *                                      (operator) vs the agent path (defaults to
+ *                                      `learned` trust + agent attribution).
+ *                                      (Was `admin`, which deny-by-origin blocked.)
  *   - `memory.stats`        (admin) — setup-gateway-api.ts line 234.
  *   - `memory.browse`       (admin) — setup-gateway-api.ts line 234.
  *   - `memory.delete`       (admin) — setup-gateway-api.ts line 234.
  *   - `memory.flush`        (admin) — setup-gateway-api.ts line 235.
  *   - `memory.export`       (admin) — setup-gateway-api.ts line 235.
  *
- *   context-handlers.ts:
- *   - `context.search`               (rpc)   — setup-gateway-api.ts:164.
- *   - `context.inspect`              (rpc)   — setup-gateway-api.ts:164.
- *   - `context.recall`               (rpc)   — setup-gateway-api.ts:164.
- *   - `context.expand`               (rpc)   — setup-gateway-api.ts:164.
- *   - `context.conversations`        (admin) — setup-gateway-api.ts:169.
- *   - `context.tree`                 (admin) — setup-gateway-api.ts:169.
- *   - `context.searchByConversation` (admin) — setup-gateway-api.ts:169.
- *
  * **Loose-record use.** Multiple response shapes carry deeply nested
  * fields with `Record<string, unknown>` or `JSON.parse(...)`-typed
  * payloads where modelling them tighter would pin the underlying wire
@@ -59,35 +51,32 @@
  *     the full row carries unknown fields per memory adapter.
  *   - `memory.export.response.entries[]` — similar nested-record shape;
  *     `source` is `Record<string, unknown>` at the leaf.
- *   - `context.inspect.response` — discriminated by ID prefix (`sum_` vs
- *     `file_`); the two variants carry different field sets. Modelled as
- *     a loose record at the top level + tight inner typing for the known
- *     fields.
- *   - `context.recall.response` — `{ answer, citations[], grantId?,
- *     tokensConsumed? }` is mostly primitive; `answer` is the
- *     unconstrained sub-agent output (loose-modelled internal).
- *   - `context.tree.response.nodes[]` — has nested `childIds[]` and
- *     `parentIds[]` per node.
- *   - `context.searchByConversation.response.results[]` — discriminated
- *     by `type: "message" | "summary"`; the two variants carry the same
- *     wire shape per handler.
  *
- * **Gateway-adapter shim caveat.** The CLI's `packages/cli/src/commands/memory.ts`
- * contains raw `client.call(...)` sites for `memory.search`,
- * `memory.inspect`, and `config.set`. These are NOT memory-handlers.ts or
- * context-handlers.ts methods — they are gateway-adapter shims registered
- * in `packages/gateway/src/rpc/rpc-adapters.ts:171-249` that bypass the
- * daemon handler-factory layer. Those methods have no contract in this
- * file (and no daemon-handler-factory entry to map against, per the
- * bidirectional 1:1 architecture test scope). The CLI retarget here is
- * scoped to `client.call("memory.search_files"|"memory.get_file"|
- * "memory.store"|"memory.stats"|"memory.browse"|"memory.delete"|
- * "memory.flush"|"memory.export"|"context.*", ...)` sites only.
+ * **CLI memory search/inspect (v2.12).** The CLI's
+ * `packages/cli/src/commands/memory.ts` previously borrowed the (now-removed)
+ * `context.search` / `context.inspect` RPCs for its `memory search` /
+ * `memory inspect` subcommands. With the DAG context engine demolished those
+ * commands fail closed (explicit not-available message + non-zero exit) — there
+ * is no `memory.search` / `memory.inspect` handler. Full-text context search +
+ * entry inspection return with the LCD engine (Phase 131).
  *
  * @module
  */
 import { z } from "zod";
 import { defineContract } from "./types.js";
+// Value import for the `...MEMORY_DIAGNOSTIC_CONTRACTS` spread into
+// MEMORY_CONTRACTS below (the `export { ... } from` re-export further down is
+// type/barrel-only and does not create a usable local value binding).
+import { MEMORY_DIAGNOSTIC_CONTRACTS } from "./memory-diagnostics.js";
+// Portability contracts extracted to keep this file within the 800-line cap.
+export { MemoryPortabilityExportContract, MemoryPortabilityImportContract, MEMORY_PORTABILITY_CONTRACTS, } from "./memory-portability.js";
+// Only the array is needed as a local value (spread into MEMORY_CONTRACTS below);
+// the two contract objects are re-exported via the `export { ... } from` above.
+import { MEMORY_PORTABILITY_CONTRACTS } from "./memory-portability.js";
+// Pinning contracts extracted to memory-pinning.ts (file-size cap §4.1).
+// @contract-deferred-handler annotations removed in plan 03-03 (same diff as handler creation).
+export { MemoryPinContract, MemoryUnpinContract, MEMORY_PINNING_CONTRACTS, } from "./memory-pinning.js";
+import { MEMORY_PINNING_CONTRACTS } from "./memory-pinning.js";
 // ===========================================================================
 // --- memory-handlers.ts ---
 // ===========================================================================
@@ -120,6 +109,71 @@ export const MemorySearchFilesContract = defineContract({
     scopes: ["rpc"],
 });
 // ---------------------------------------------------------------------------
+// memory.ask  (the dialectic grounded-Q&A surface)
+// ---------------------------------------------------------------------------
+/**
+ * `memory.ask` — the dialectic: a grounded, cited NL answer over the agent's
+ * LLM-free recall pipeline. The handler runs `createMemoryRecall` for the
+ * question (the SAME trust-filtered + redacted recall the prompt path uses),
+ * then synthesizes the answer via the ONE allowed query-time LLM seam, and
+ * returns it WITH citations.
+ *
+ * Request: `{ question, limit? }` — `question` is the (untrusted) NL query;
+ * `limit` optionally caps the grounding-set size.
+ *
+ * Response: `{ answer, citations, abstained }`.
+ *   - `citations` are recalled memory IDS (the entry id is a `z.guid()` at the
+ *     source, but the contract types it as opaque `string` — citations are ids,
+ *     never free text). The cited ids traverse `sourceIds` in the
+ *     recall-trace.
+ *   - `abstained` is the EXPLICIT mandatory-abstention signal — a
+ *     required boolean, never inferred from an empty `answer`. Insufficient
+ *     grounding ⇒ `{ answer: "", citations: [], abstained: true }`, never a
+ *     fabricated answer.
+ *   - the `answer` text is built ONLY from the trust-filtered + redacted recall
+ *     output (enforced in the handler), with the higher-trust source
+ *     winning on conflict (trust-first, a HARD boundary).
+ *
+ * Registered via agent tool dispatch (the `memory_ask` tool); contract scope
+ * `["rpc"]` documents the intended trust model.
+ *
+ * CROSS-WAVE SEAM (now closed): the contract SHAPE shipped first with a
+ * deferred-handler annotation and was kept OUT of `MEMORY_CONTRACTS` until its
+ * daemon handler existed (registering it before the handler would RED-gate
+ * contract-handler-parity + bidirectional 1:1). The
+ * `[MemoryAskContract.method]:` handler later landed in `memory-handlers.ts` and,
+ * in the SAME diff, this contract was spread into `MEMORY_CONTRACTS`
+ * (8 + 4 + 7 + 1 = 20) and that annotation removed — so the registry ↔ handler
+ * set is 1:1 by construction. (Mirrors the diagnostic cross-wave seam closed
+ * earlier.)
+ */
+export const MemoryAskContract = defineContract({
+    method: "memory.ask",
+    request: z.object({
+        question: z.string(),
+        // A positive integer — the grounding-set size the caller may request. The handler
+        // additionally clamps it DOWN to the per-agent `dialectic.maxRecall` DoS ceiling; this
+        // contract bound rejects the negative / non-integer / huge cases at the parse boundary so
+        // the DoS / negative-slice path cannot reach the handler in the first place.
+        limit: z.number().int().positive().optional(),
+    }),
+    response: z.object({
+        answer: z.string(),
+        citations: z.array(z.string()),
+        abstained: z.boolean(),
+        // Live finding 2026-06-11: every abstain branch (dialectic not wired,
+        // empty recall, synthesis abstain) returned the IDENTICAL bare sentinel —
+        // an infrastructure absence was indistinguishable from a genuine "no
+        // data" answer. Present ONLY when abstained:true. Values:
+        //   "dialectic_unavailable" — seam/recall factory not wired (config/key)
+        //   "no_agent_scope"        — no caller agent scope and no default agent
+        //   "empty_recall"          — recall ran and returned nothing
+        //   "synthesis_abstained"   — grounded synthesis declined to answer
+        reason: z.string().optional(),
+    }),
+    scopes: ["rpc"],
+});
+// ---------------------------------------------------------------------------
 // memory.get_file
 // ---------------------------------------------------------------------------
 /**
@@ -150,12 +204,18 @@ export const MemoryGetFileContract = defineContract({
 // memory.store
 // ---------------------------------------------------------------------------
 /**
- * `memory.store` — write a memory entry. Admin via gateway route
- * (setup-gateway-api.ts:235); ALSO usable from the agent in-process tool
- * path where the trust level defaults to `learned`. The handler routes
- * on the dispatcher-injected `_trustLevel`:
- *   - `_trustLevel === "admin"`: operator-attributed (channel: web-console).
- *   - Otherwise: agent-attributed (channel: agent-tool).
+ * `memory.store` — write a memory entry. `scopes:["rpc"]` — AGENT-REACHABLE:
+ * the agent `memory_store` tool is the primary caller, where the trust level
+ * defaults to `learned`. (Was `scopes:["admin"]`, the MD-02 deny-by-origin
+ * regression: `["admin"]` put it in `ADMIN_METHODS` so the `assertNotAgentOrigin`
+ * chokepoint threw "Control-plane method memory.store is not reachable from an
+ * agent origin" for the agent's `_agentId`-bearing call — the `memory_store`
+ * tool could not store anything. Re-scoped admin→rpc 2026-06-24, matching the
+ * earlier `message.send`/`skills.*`/`session.list` fixes; guarded by
+ * `test/architecture/agent-memory-tools-deny-by-origin.test.ts`.) The handler
+ * still routes on the dispatcher-injected `_trustLevel`:
+ *   - `_trustLevel === "admin"` (operator path): operator-attributed (channel: web-console), may override trust to learned/external.
+ *   - Otherwise (agent path): agent-attributed (channel: agent-tool), trust defaults to `learned` (never `system`).
  *
  * Bespoke pre-Zod validation: `content` is required + non-empty (the
  * handler raises `"Missing required parameter: content"`), and the
@@ -177,7 +237,7 @@ export const MemoryStoreContract = defineContract({
         stored: z.literal(true),
         id: z.string(),
     }),
-    scopes: ["admin"],
+    scopes: ["rpc"],
 });
 // ---------------------------------------------------------------------------
 // memory.stats
@@ -331,269 +391,37 @@ export const MemoryExportContract = defineContract({
     scopes: ["admin"],
 });
 // ===========================================================================
-// --- context-handlers.ts ---
+// --- context-handlers.ts (REMOVED in v2.12) ---
+//
+// The 7 `Context*Contract` definitions (context.search / .inspect / .recall /
+// .expand / .conversations / .tree / .searchByConversation) were removed in
+// v2.12 (Phase 126) along with the DAG context engine + its daemon handlers
+// (Plan 03) + the CLI memory search/inspect rewire (fail-closed, this plan).
+// The governed context-expansion RPC surface is reintroduced fresh by the LCD
+// engine (Phase 131).
 // ===========================================================================
-// ---------------------------------------------------------------------------
-// context.search
-// ---------------------------------------------------------------------------
-/**
- * `context.search` — FTS5 / regex search across messages and summaries
- * within the caller's active DAG conversation. Resolved from the
- * dispatcher-injected `_callerSessionKey`.
- *
- * Bespoke pre-Zod validation:
- *   - No active DAG conversation → `"No active DAG conversation for
- *     this session"`.
- *   - `query` missing → `"Missing required parameter: query"`.
- *
- * Request fields: `query` (required), `mode` (default `"fts"`), `scope`
- * (default `"both"`), `limit` (max 100).
- *
- * Response: `{ results: SearchResultRow[], total }`. Each row carries
- * `id` (stringified message-id or summaryId), `content` (truncated to
- * 500 chars), `type: "message" | "summary"`, and optional `rank` (FTS5
- * rank — lower is better; absent for regex mode).
- */
-export const ContextSearchContract = defineContract({
-    method: "context.search",
-    request: z.object({
-        query: z.string().min(1),
-        mode: z.enum(["fts", "regex"]).optional(),
-        scope: z.enum(["both", "messages", "summaries"]).optional(),
-        limit: z.number().optional(),
-    }),
-    response: z.object({
-        results: z.array(z.object({
-            id: z.string(),
-            content: z.string(),
-            type: z.enum(["message", "summary"]),
-            rank: z.number().optional(),
-        })),
-        total: z.number(),
-    }),
-    scopes: ["rpc"],
-});
-// ---------------------------------------------------------------------------
-// context.inspect
-// ---------------------------------------------------------------------------
-/**
- * `context.inspect` — fetch full content of a summary or file by ID. The
- * ID prefix discriminates the variant: `sum_*` returns a summary row +
- * lineage; `file_*` returns large-file metadata + on-disk content
- * (capped at 100,000 chars).
- *
- * Bespoke pre-Zod validation:
- *   - `id` missing → `"Missing required parameter: id"`.
- *   - Summary not found → `"Summary not found: <id>"`.
- *   - File not found → `"File not found: <id>"`.
- *   - Unknown prefix → `"Unknown ID prefix. Expected 'sum_' or 'file_'..."`.
- *
- * Response: LOOSE RECORD. The two variants carry overlapping but
- * distinct field sets:
- *   - summary: `{ type: "summary", summaryId, content, depth, kind,
- *     tokenCount, earliestAt?, latestAt?, descendantCount, parentIds[],
- *     childIds[], sourceMessageCount }`.
- *   - file:    `{ type: "file", fileId, fileName?, mimeType?, byteSize?,
- *     explorationSummary?, content (capped at 100k) }`.
- *
- * Modelling the discriminated union tightly would require pinning the
- * `kind` enum (varies per compaction strategy) and the per-field
- * nullability (depends on memory-adapter implementation). The loose
- * record preserves the variant discrimination via `type` + lets the
- * underlying types stay authoritative.
- */
-export const ContextInspectContract = defineContract({
-    method: "context.inspect",
-    request: z.object({
-        id: z.string().min(1),
-    }),
-    response: z.record(z.string(), z.unknown()),
-    scopes: ["rpc"],
-});
-// ---------------------------------------------------------------------------
-// context.recall
-// ---------------------------------------------------------------------------
-/**
- * `context.recall` — deep recall via bounded sub-agent spawning. Creates
- * an expansion grant (configurable token cap + expiry), spawns a sub-
- * agent with `context_expand` tool group, and returns the sub-agent's
- * answer + citation summaryIds.
- *
- * Bespoke pre-Zod validation:
- *   - No active DAG conversation → `"No active DAG conversation for
- *     this session"`.
- *   - Daily quota exceeded → `"Daily recall quota exceeded
- *     (<N>/day)..."`.
- *   - `prompt` missing → `"Missing required parameter: prompt"`.
- *
- * Request: `{ prompt, query?, summary_ids?, max_tokens? }`. Either
- * `query` (auto-search for candidates) OR `summary_ids` (explicit
- * candidate set) drives the sub-agent's working set.
- *
- * Response: `{ answer, citations: string[], grantId?, tokensConsumed? }`.
- * `grantId` + `tokensConsumed` are absent when zero candidates were
- * found.
- */
-export const ContextRecallContract = defineContract({
-    method: "context.recall",
-    request: z.object({
-        prompt: z.string().min(1),
-        query: z.string().optional(),
-        summary_ids: z.array(z.string()).optional(),
-        max_tokens: z.number().optional(),
-    }),
-    response: z.object({
-        answer: z.string(),
-        citations: z.array(z.string()),
-        grantId: z.string().optional(),
-        tokensConsumed: z.number().optional(),
-    }),
-    scopes: ["rpc"],
-});
-// ---------------------------------------------------------------------------
-// context.expand
-// ---------------------------------------------------------------------------
-/**
- * `context.expand` — walk deeper into the DAG with a grant. Used by the
- * sub-agent spawned from `context.recall` to traverse summaries down to
- * source messages, bounded by the grant's token cap + conversation
- * allowlist + expiry.
- *
- * Bespoke pre-Zod validation:
- *   - `grant_id` missing → `"Missing required parameter: grant_id"`.
- *   - `summary_id` missing → `"Missing required parameter: summary_id"`.
- *   - Grant not found / revoked / expired → corresponding error message.
- *   - Token cap reached → `"Token cap reached (<consumed>/<cap>)..."`.
- *   - Summary not found → `"Summary not found: <id>"`.
- *   - Summary outside grant's conversation allowlist → `"Summary does
- *     not belong to an authorized conversation"`.
- *
- * Response: `{ summaryId, depth, kind, children[], tokensExpanded,
- * tokenBudgetRemaining }`. Each child is either a summary (when
- * expanding a condensed summary) or a source message (when expanding a
- * leaf summary).
- */
-export const ContextExpandContract = defineContract({
-    method: "context.expand",
-    request: z.object({
-        grant_id: z.string().min(1),
-        summary_id: z.string().min(1),
-    }),
-    response: z.object({
-        summaryId: z.string(),
-        depth: z.number(),
-        kind: z.string(),
-        children: z.array(z.object({
-            type: z.enum(["summary", "message"]),
-            id: z.union([z.string(), z.number()]),
-            content: z.string(),
-            tokenCount: z.number(),
-        })),
-        tokensExpanded: z.number(),
-        tokenBudgetRemaining: z.number(),
-    }),
-    scopes: ["rpc"],
-});
-// ---------------------------------------------------------------------------
-// context.conversations
-// ---------------------------------------------------------------------------
-/**
- * `context.conversations` — list ALL DAG conversations for the tenant
- * (operator view). Admin-only.
- *
- * Bespoke pre-Zod validation:
- *   - `_trustLevel !== "admin"` → `"Admin access required"`.
- *
- * Response: `{ conversations[], total }`. Each conversation row is the
- * raw `CtxConversationRow` from the context store (loose-record —
- * modelling the row shape tightly would pin the persistence schema).
- */
-export const ContextConversationsContract = defineContract({
-    method: "context.conversations",
-    request: z.object({
-        limit: z.number().optional(),
-        offset: z.number().optional(),
-    }),
-    response: z.object({
-        conversations: z.array(z.record(z.string(), z.unknown())),
-        total: z.number(),
-    }),
-    scopes: ["admin"],
-});
-// ---------------------------------------------------------------------------
-// context.tree
-// ---------------------------------------------------------------------------
-/**
- * `context.tree` — summary-tree for a given DAG conversation (operator
- * view). Admin-only.
- *
- * Bespoke pre-Zod validation:
- *   - `_trustLevel !== "admin"` → `"Admin access required"`.
- *   - `conversation_id` missing → `"Missing required parameter:
- *     conversation_id"`.
- *   - Conversation not found → `"Conversation not found"`.
- *
- * Response: `{ conversationId, nodes[], messageCount }`. Each node
- * carries `summaryId, kind, depth, tokenCount, contentPreview` (first
- * 200 chars), `childIds[]`, `parentIds[]`, `createdAt`. `kind` is a
- * loose-string (compaction strategies evolve over time).
- */
-export const ContextTreeContract = defineContract({
-    method: "context.tree",
-    request: z.object({
-        conversation_id: z.string().min(1),
-    }),
-    response: z.object({
-        conversationId: z.string(),
-        nodes: z.array(z.object({
-            summaryId: z.string(),
-            kind: z.string(),
-            depth: z.number(),
-            tokenCount: z.number(),
-            contentPreview: z.string(),
-            childIds: z.array(z.string()),
-            parentIds: z.array(z.string()),
-            createdAt: z.string(),
-        })),
-        messageCount: z.number(),
-    }),
-    scopes: ["admin"],
-});
-// ---------------------------------------------------------------------------
-// context.searchByConversation
-// ---------------------------------------------------------------------------
-/**
- * `context.searchByConversation` — FTS5 search within a SPECIFIC DAG
- * conversation (operator view; bypasses the caller's active session).
- * Admin-only.
- *
- * Bespoke pre-Zod validation:
- *   - `_trustLevel !== "admin"` → `"Admin access required"`.
- *   - `conversation_id` missing → `"Missing required parameter:
- *     conversation_id"`.
- *   - `query` missing → `"Missing required parameter: query"`.
- *
- * Response: `{ results[] }`. Each row carries `id`, `type: "message" |
- * "summary"`, `content` (FULL content — no truncation, unlike
- * `context.search`), and optional FTS5 `rank`.
- */
-export const ContextSearchByConversationContract = defineContract({
-    method: "context.searchByConversation",
-    request: z.object({
-        conversation_id: z.string().min(1),
-        query: z.string().min(1),
-        limit: z.number().optional(),
-    }),
-    response: z.object({
-        results: z.array(z.object({
-            id: z.string(),
-            type: z.enum(["message", "summary"]),
-            content: z.string(),
-            rank: z.number().optional(),
-        })),
-    }),
-    scopes: ["admin"],
-});
+// ===========================================================================
+// --- memory-handlers.ts (diagnostic surface) ---
+//
+// The four admin-scoped memory-diagnostic contracts (memory.recall_trace /
+// .observations / .entities / .recall_stats) and their
+// `MEMORY_DIAGNOSTIC_CONTRACTS` array were EXTRACTED to the sibling file
+// `./memory-diagnostics.ts` purely to keep this file under the 800-line
+// architecture cap (file-size.test.ts). They are re-exported below so every
+// existing `from "./memory.js"` import — and the api-contracts barrel — still
+// resolves, and so they remain part of the memory domain's public surface.
+//
+// CROSS-WAVE SEAM (now closed): the four contracts are now spread into
+// `MEMORY_CONTRACTS` below (`...MEMORY_DIAGNOSTIC_CONTRACTS`), in the SAME wave
+// that landed their daemon handlers in `memory-handlers.ts`, and the
+// `@contract-deferred-handler` annotations were removed from
+// `./memory-diagnostics.ts`. The bidirectional 1:1 + contract-handler-parity
+// gates remain green by construction (registry ↔ handler set is 1:1).
+// ===========================================================================
+export { MemoryRecallTraceContract, MemoryObservationsContract, MemoryEntitiesContract, MemoryRecallStatsContract, } from "./memory-diagnostics.js";
+// Re-export the locally-imported (for the spread below) diagnostics array so
+// the public barrel surface is unchanged.
+export { MEMORY_DIAGNOSTIC_CONTRACTS };
 // ===========================================================================
 // Domain array — registered into API_CONTRACTS_ORDERED in index.ts.
 // ===========================================================================
@@ -603,10 +431,23 @@ export const ContextSearchByConversationContract = defineContract({
  *
  * The grouping below is documentation-only (the bidirectional 1:1 test
  * treats the tuple as an unordered set).
+ *
+ * `MEMORY_DIAGNOSTIC_CONTRACTS` (the four diagnostic
+ * contracts) is now spread in — in the SAME wave that landed the matching
+ * `[Contract.method]:` daemon handlers in `memory-handlers.ts` — so the
+ * `API_CONTRACTS` registry ↔ handler set stays 1:1 (the cross-wave seam is
+ * closed; the `@contract-deferred-handler` annotations were
+ * removed in the same diff).
+ *
+ * `MemoryAskContract` (the dialectic memory.ask surface) is
+ * now spread in — in the SAME diff that landed its `[MemoryAskContract.method]:`
+ * handler in `memory-handlers.ts` — so the registry ↔ handler set stays 1:1 and
+ * the `@contract-deferred-handler` tag was removed in the same diff.
  */
 export const MEMORY_CONTRACTS = [
     // --- memory-handlers.ts ---
     MemorySearchFilesContract,
+    MemoryAskContract,
     MemoryGetFileContract,
     MemoryStoreContract,
     MemoryStatsContract,
@@ -614,12 +455,12 @@ export const MEMORY_CONTRACTS = [
     MemoryDeleteContract,
     MemoryFlushContract,
     MemoryExportContract,
-    // --- context-handlers.ts ---
-    ContextSearchContract,
-    ContextInspectContract,
-    ContextRecallContract,
-    ContextExpandContract,
-    ContextConversationsContract,
-    ContextTreeContract,
-    ContextSearchByConversationContract,
+    // Portability contracts extracted to memory-portability.ts.
+    ...MEMORY_PORTABILITY_CONTRACTS,
+    // Pinning contracts extracted to memory-pinning.ts.
+    ...MEMORY_PINNING_CONTRACTS,
+    // --- memory-handlers.ts (diagnostic surface) ---
+    ...MEMORY_DIAGNOSTIC_CONTRACTS,
+    // NOTE: the 7 context.* contracts (context-handlers.ts) were removed in v2.12
+    // (Phase 126) with the DAG context engine; reintroduced fresh by LCD (Phase 131).
 ];