@sema-agent/server 1.323.0 → 2.0.0

package/dist/plugins/memory-run-store.js

@@ -1,10 +1,27 @@
+/**
+ * In-memory async run registry + replayable event log — the LOCAL (DB-less) twin of {@link TiDBRunStore}/
+ * {@link PgRunStore} (clay 2026-06-25: the seamless local↔cloud switch — a locally-run HTTP service must serve the
+ * SAME contract a cloud worker does, incl. `/v1/runs` async runs + the trace event log). Behaviourally identical to
+ * the SQL twins (the shared `storeBehaviorSuite` keeps them in lock-step), but process-local + ephemeral: a restart
+ * loses run history (file-backed durability is the immediate follow-on; the conversation HISTORY + checkpoints DO
+ * persist via core's FileStorageBackend). Single-process, so the cross-replica/durable reapers degrade — see below.
+ *
+ * Mirrors the SQL semantics exactly: the `task_active` single-active-run claim (a Map keyed by sessionId), the
+ * NON-terminal suspend/needs_review parks that KEEP the claim, the markResuming CAS that resets cancel/preempt, the
+ * owner null-safe guard on the flag/heartbeat paths (`<=>` → JS `(a??null)===(b??null)`), and the keyset list order.
+ */
 import { projectUsageStats, USAGE_SCAN_LIMIT } from "../usage-analytics.js";
+/** Null-safe owner equality — the JS twin of the SQL `owner <=> ?` guard (a legacy null-owner run matches owner=null). */
 const ownerEq = (a, b) => (a ?? null) === (b ?? null);
 export class MemoryRunStore {
     runs = new Map();
+    /** sessionId → taskId — the single-active-run claim (the `task_active` table). */
     active = new Map();
+    /** taskId → events (kept seq-sorted on read). */
     events = new Map();
+    /** [868] the checkpoint-table stand-in (see {@link RunStoreCheckpointProbe}); absent ⇒ reapers NO-OP. */
     checkpointProbe;
+    /** [868] wire the checkpoint probe (backend assembly, where checkpoint + run store are built together). */
     setCheckpointProbe(probe) {
         this.checkpointProbe = probe;
     }
@@ -25,6 +42,7 @@ export class MemoryRunStore {
             updatedAt: r.updatedAt.toISOString(),
         };
     }
+    /** Create a run iff the session has no active run (the task_active unique-key claim). */
     async createRun(taskId, sessionId, owner, instanceId, meta = {}) {
         const claimed = this.active.get(sessionId);
         if (claimed !== undefined)
@@ -79,8 +97,12 @@ export class MemoryRunStore {
     }
     async appendEvent(taskId, seq, type, data) {
         const list = this.events.get(taskId) ?? [];
+        // Mirror the (task_id, seq) PK: a duplicate seq is a caller bug (callers use ++seq); ignore a re-append of the
+        // same seq rather than corrupt the log (the SQL twin would throw ER_DUP_ENTRY — callers never hit it).
         if (list.some((e) => e.seq === seq))
             return;
+        // Deep-clone `data` on WRITE so the stored event is isolated from later caller mutation — the SQL twin
+        // JSON.stringify's it into the column, giving the same write-isolation (parity oracle).
         list.push({ seq, type, data: data == null ? null : structuredClone(data), ts: new Date().toISOString() });
         this.events.set(taskId, list);
     }
@@ -94,11 +116,15 @@ export class MemoryRunStore {
     }
     async getEvents(taskId, afterSeq) {
         const list = this.events.get(taskId) ?? [];
+        // Deep-clone `data` on READ so each call yields a fresh, mutation-isolated object — the SQL twin re-parses the
+        // JSON column per read (parity oracle); a shallow `{...e}` would alias `data` into the stored Map (review footgun).
         return list
             .filter((e) => e.seq > afterSeq)
             .sort((a, b) => a.seq - b.seq)
             .map((e) => ({ ...e, data: e.data == null ? null : structuredClone(e.data) }));
     }
+    /** [888] FIRST terminal writer wins(SQL 孪生同款正向 CAS on running/suspended/needs_review,
+     *  [1.207 codex M1] 负向形漏 blocked/timeout);claim 释放保持无条件(幂等)。 */
     async setTerminal(taskId, status, result, error) {
         const r = this.runs.get(taskId);
         if (!r)
@@ -110,9 +136,11 @@ export class MemoryRunStore {
             r.errorCode = result?.errorCode ?? null;
             r.updatedAt = new Date();
         }
+        // Release the single-active-run claim (DELETE FROM task_active WHERE task_id = ?).
         if (this.active.get(r.sessionId) === taskId)
             this.active.delete(r.sessionId);
     }
+    /** Durable F4: park NON-terminal `suspended`, KEEP the task_active claim. CAS on running/suspended (reaper-revert guard). */
     async setSuspended(taskId) {
         const r = this.runs.get(taskId);
         if (r && (r.status === "running" || r.status === "suspended")) {
@@ -120,6 +148,7 @@ export class MemoryRunStore {
             r.updatedAt = new Date();
         }
     }
+    /** design/80 D-B: park NON-terminal `needs_review`, KEEP the claim. CAS on running/needs_review. */
     async setNeedsReview(taskId) {
         const r = this.runs.get(taskId);
         if (r && (r.status === "running" || r.status === "needs_review")) {
@@ -127,6 +156,7 @@ export class MemoryRunStore {
             r.updatedAt = new Date();
         }
     }
+    /** Durable F4 resume: flip suspended/needs_review → running (CAS) + reset cancel/preempt flags. */
     async markResuming(taskId) {
         const r = this.runs.get(taskId);
         if (!r || (r.status !== "suspended" && r.status !== "needs_review"))
@@ -144,7 +174,11 @@ export class MemoryRunStore {
         const r = this.runs.get(taskId);
         return r ? this.toRecord(r) : undefined;
     }
+    /** Runs newest-first, keyset on (createdAt, taskId) DESC; optional exact-match filters (owner is exact, like the SQL). */
     async listRuns(opts) {
+        // 夜测 N1(2026-07-09,LOW):a non-date cursor.createdAt made the four backends diverge (PG threw a raw
+        // DB error; the other three returned an empty page). HTTP's decodeCursor pre-validates, so this is
+        // defence-in-depth for direct store callers — normalize ALL backends to the empty page.
         if (opts.cursor && Number.isNaN(Date.parse(opts.cursor.createdAt)))
             return [];
         const cursorAt = opts.cursor ? Date.parse(opts.cursor.createdAt) : undefined;
@@ -152,31 +186,33 @@ export class MemoryRunStore {
             .filter((r) => (opts.status ? r.status === opts.status : true))
             .filter((r) => (opts.jobId ? r.jobId === opts.jobId : true))
             .filter((r) => (opts.source ? r.source === opts.source : true))
-            .filter((r) => (opts.owner ? r.owner === opts.owner : true))
+            .filter((r) => (opts.owner ? r.owner === opts.owner : true)) // exact (SQL `owner = ?`): a set owner excludes null-owner rows
             .filter((r) => {
             if (cursorAt === undefined)
                 return true;
             const t = r.createdAt.getTime();
-            return t < cursorAt || (t === cursorAt && r.taskId < opts.cursor.taskId);
+            return t < cursorAt || (t === cursorAt && r.taskId < opts.cursor.taskId); // keyset: strictly older, ties by taskId
         })
             .sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime() || (a.taskId < b.taskId ? 1 : a.taskId > b.taskId ? -1 : 0));
         return rows.slice(0, opts.limit).map((r) => this.toRecord(r));
     }
+    /** DISTINCT sessions newest-first by last activity (the CC /resume picker): latest run's preview/status + first/last/count. */
     async listSessions(opts) {
         const bySession = new Map();
         for (const r of this.runs.values()) {
             if (opts.owner && r.owner !== opts.owner)
-                continue;
+                continue; // exact owner filter (SQL `owner = ?`)
             const arr = bySession.get(r.sessionId) ?? [];
             arr.push(r);
             bySession.set(r.sessionId, arr);
         }
         const cursorAt = opts.cursor ? Date.parse(opts.cursor.lastActivityAt) : undefined;
-        const qlc = opts.q?.toLowerCase();
+        const qlc = opts.q?.toLowerCase(); // ?q= search: any-run preview match (the in-memory twin of the SQL EXISTS)
         const summaries = [];
         for (const [sessionId, arr] of bySession) {
             if (qlc && !arr.some((r) => r.objectivePreview?.toLowerCase().includes(qlc)))
                 continue;
+            // rn=1 = latest run (createdAt DESC, taskId DESC) → preview/status/owner.
             const sorted = [...arr].sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime() || (a.taskId < b.taskId ? 1 : a.taskId > b.taskId ? -1 : 0));
             const latest = sorted[0];
             const times = arr.map((r) => r.createdAt.getTime());
@@ -190,8 +226,8 @@ export class MemoryRunStore {
                 runCount: arr.length,
                 objectivePreview: latest.objectivePreview,
                 lastStatus: latest.status,
-                lastRunId: latest.taskId,
-                title: null,
+                lastRunId: latest.taskId, // K-5c: latest run id = the live-tail re-attach anchor
+                title: null, // honest degrade (no session_meta on the memory twin)
             });
         }
         return summaries
@@ -204,6 +240,7 @@ export class MemoryRunStore {
             .sort((a, b) => Date.parse(b.lastActivityAt) - Date.parse(a.lastActivityAt) || (a.sessionId < b.sessionId ? 1 : a.sessionId > b.sessionId ? -1 : 0))
             .slice(0, opts.limit);
     }
+    /** E21 (§0.5 delete) — purge the runs ledger for one session, owner-guarded; aborts (returns {active}) if a run is live. */
     async deleteBySession(sessionId, owner) {
         const claimed = this.active.get(sessionId);
         if (claimed !== undefined)
@@ -218,6 +255,7 @@ export class MemoryRunStore {
         }
         return { removed };
     }
+    /** 用量扫窗——in-memory 腿:遍历窗内行,投影同 usage-analytics 纯函数(SQL 孪生 parity)。 */
     async usageScan(fromMs, toMs, opts) {
         const limit = Math.min(opts?.limit ?? USAGE_SCAN_LIMIT, USAGE_SCAN_LIMIT);
         const all = [];
@@ -238,13 +276,14 @@ export class MemoryRunStore {
         for (const r of this.runs.values()) {
             if (r.createdAt.getTime() < sinceMs)
                 continue;
-            const key = JSON.stringify([r.source, r.status]);
+            const key = JSON.stringify([r.source, r.status]); // collision-proof + keeps NULL distinct from "" (SQL GROUP BY parity)
             const cur = counts.get(key) ?? { source: r.source, status: r.status, count: 0 };
             cur.count += 1;
             counts.set(key, cur);
         }
         return [...counts.values()];
     }
+    /** Fail stale `running` rows (crashed-run backstop) + release task_active for any now-terminal row. */
     async reapStale(olderThanMs) {
         const cutoff = Date.now() - olderThanMs;
         let reaped = 0;
@@ -256,15 +295,20 @@ export class MemoryRunStore {
                 reaped += 1;
             }
         }
+        // Release the claim for TERMINAL rows only (suspended/needs_review intentionally keep it).
         this.releaseTerminalClaims();
         return reaped;
     }
+    /** [868] shared tail of both suspended-run reapers: flip one parked row → failed('approval.expired'), the
+     *  in-memory twin of the SQL UPDATE (`error`/`error_code` set directly — no result blob to derive from). */
     failExpiredPark(r) {
         r.status = "failed";
         r.error = "approval expired before decision";
         r.errorCode = "approval.expired";
         r.updatedAt = new Date();
     }
+    /** Release the claim for TERMINAL rows only — suspended/needs_review keep it (the `DELETE ta … WHERE tr.status
+     *  NOT IN ('running','suspended','needs_review')` twin, shared by reapStale + the [868] suspended reapers). */
     releaseTerminalClaims() {
         for (const [sessionId, taskId] of [...this.active]) {
             const r = this.runs.get(taskId);
@@ -272,6 +316,16 @@ export class MemoryRunStore {
                 this.active.delete(sessionId);
         }
     }
+    /**
+     * [868] Durable F4 expiry — the local twin of TiDBRunStore.reapSuspended, driven by the injected checkpoint
+     * probe instead of a SQL JOIN (formerly a NO-OP, which was one of the five closed doors in the "suspended run
+     * locks the session forever" incident). Semantics verbatim from the SQL twin: suspended ∧ updatedAt < cutoff
+     * ∧ NOT probe.hasPending(session) → failed 'approval expired before decision' / error_code 'approval.expired'
+     * + release the task_active claim. The NOT-pending clause is the design/80 D-D adversarial-blocker guard
+     * (see tidb-run-store.ts:577-583): a row whose checkpoint is STILL pending belongs to the checkpoint-state
+     * sweeps (SLA deny-sweep / failSuspendedWithExpiredCheckpoint) — time-reaping it here would orphan a model
+     * leg on a now-unlocked session. Probe absent ⇒ honest NO-OP (never kill a park without the guard).
+     */
     async reapSuspended(olderThanMs) {
         const probe = this.checkpointProbe;
         if (!probe)
@@ -283,7 +337,10 @@ export class MemoryRunStore {
                 continue;
             const snap = r.updatedAt.getTime();
             if (await probe.hasPending(r.sessionId))
-                continue;
+                continue; // D-D guard: a still-pending checkpoint owns this row
+            // codex H2:probe 的 await 让出事件循环——markResuming(approve 恢复)/cancel/新一轮 park 可能已改行。
+            // 复核与改写之间无 await(Node 单线程 ⇒ 原子);状态或 updatedAt 变了就放手,绝不覆盖一条已被别腿
+            // 认领的行(SQL 孪生靠单条条件 UPDATE 天然原子,这里的 snap 复核就是它的本地等价)。
             if (r.status !== "suspended" || r.updatedAt.getTime() !== snap)
                 continue;
             this.failExpiredPark(r);
@@ -292,6 +349,13 @@ export class MemoryRunStore {
         this.releaseTerminalClaims();
         return reaped;
     }
+    /**
+     * [868] design/80 §3 inv#3 crash-safe backstop — the local twin of TiDBRunStore.failSuspendedWithExpiredCheckpoint
+     * (checkpoint-STATE-driven, not time-driven; runs UNCONDITIONALLY every reaper tick, no APPROVAL_TIMEOUT_SEC gate).
+     * Semantics verbatim from the SQL twin: (suspended ∨ needs_review) ∧ probe.hasExpired(session) ∧ NOT
+     * probe.hasPending(session) → same fail + claim release. The NOT-pending clause covers a re-suspended session
+     * that minted a NEW pending gate (wq64gmm5e: an abandoned needs_review park leaks exactly like a suspended one).
+     */
     async failSuspendedWithExpiredCheckpoint() {
         const probe = this.checkpointProbe;
         if (!probe)
@@ -306,6 +370,7 @@ export class MemoryRunStore {
                 continue;
             if (await probe.hasPending(r.sessionId))
                 continue;
+            // codex H2 同款 snap 复核(两个 await 窗都盖住):行被别腿改过就放手。
             if (r.status !== parkedAs || r.updatedAt.getTime() !== snap)
                 continue;
             this.failExpiredPark(r);

package/dist/plugins/memory-session-policy-store.d.ts

@@ -1,3 +1,17 @@
+/**
+ * In-memory SessionPolicyStore + the service's `deleteBySession` extension (E21 purge / 2c overwrite-dst wipe).
+ *
+ * WHY THIS EXISTS (and not core's `InMemorySessionPolicyStore`): core's in-memory/file policy stores implement only
+ * the core interface (getRules/putRules/listBySession) — they have NO deletion seam, so neither the E21 session purge
+ * nor the 2c `overwrite-dst` subsystem wipe can remove policy rows on a backend that uses them (the SQL twins carry
+ * `deleteBySession` as a service extension; see tidb/pg-session-policy-store.ts). This store is the delete-capable
+ * in-memory twin. The seam itself is also requested upstream (core: optional `deleteBySession?` on the interface +
+ * the File/InMemory impls) — if core lands it, this class can retire in favor of core's.
+ *
+ * BYTE-MATCH DISCIPLINE: getRules/putRules/listBySession replicate core's `InMemorySessionPolicyStore` semantics
+ * exactly (same key shape, same CAS `conflict` on expectedRev mismatch, same tighten-only `loosen_forbidden` gate via
+ * core's exported `normalizeRules`/`loosenReasons`/`stripRev`, same rev start/bump). Any divergence is a bug here.
+ */
 import { type PutRulesOptions, type SessionPermissionRules, type SessionPolicyStore, type SessionRulesRecord, type StoredSessionRules } from "@sema-agent/core";
 export declare class MemorySessionPolicyStore implements SessionPolicyStore {
     private readonly map;
@@ -5,6 +19,9 @@ export declare class MemorySessionPolicyStore implements SessionPolicyStore {
     getRules(sessionId: string, principal?: string): Promise<StoredSessionRules | null>;
     putRules(sessionId: string, principal: string | undefined, rules: SessionPermissionRules, opts?: PutRulesOptions): Promise<StoredSessionRules>;
     listBySession(sessionId: string): Promise<SessionRulesRecord[]>;
+    /** Purge ALL policy rows for a session, across every principal. Scoped by session_id alone — the caller
+     *  (E21 route / importSession overwrite-dst) already proved ownership. Shape = core 1.423's optional
+     *  `SessionPolicyStore.deleteBySession?` seam (`Promise<void>` — the count was incidental; nothing consumed it). */
     deleteBySession(sessionId: string): Promise<void>;
 }
 //# sourceMappingURL=memory-session-policy-store.d.ts.map

package/dist/plugins/memory-session-policy-store.js

@@ -1,3 +1,17 @@
+/**
+ * In-memory SessionPolicyStore + the service's `deleteBySession` extension (E21 purge / 2c overwrite-dst wipe).
+ *
+ * WHY THIS EXISTS (and not core's `InMemorySessionPolicyStore`): core's in-memory/file policy stores implement only
+ * the core interface (getRules/putRules/listBySession) — they have NO deletion seam, so neither the E21 session purge
+ * nor the 2c `overwrite-dst` subsystem wipe can remove policy rows on a backend that uses them (the SQL twins carry
+ * `deleteBySession` as a service extension; see tidb/pg-session-policy-store.ts). This store is the delete-capable
+ * in-memory twin. The seam itself is also requested upstream (core: optional `deleteBySession?` on the interface +
+ * the File/InMemory impls) — if core lands it, this class can retire in favor of core's.
+ *
+ * BYTE-MATCH DISCIPLINE: getRules/putRules/listBySession replicate core's `InMemorySessionPolicyStore` semantics
+ * exactly (same key shape, same CAS `conflict` on expectedRev mismatch, same tighten-only `loosen_forbidden` gate via
+ * core's exported `normalizeRules`/`loosenReasons`/`stripRev`, same rev start/bump). Any divergence is a bug here.
+ */
 import { normalizeRules, loosenReasons, stripRev, SessionPolicyError, } from "@sema-agent/core";
 export class MemorySessionPolicyStore {
     map = new Map();
@@ -34,6 +48,9 @@ export class MemorySessionPolicyStore {
         }
         return out;
     }
+    /** Purge ALL policy rows for a session, across every principal. Scoped by session_id alone — the caller
+     *  (E21 route / importSession overwrite-dst) already proved ownership. Shape = core 1.423's optional
+     *  `SessionPolicyStore.deleteBySession?` seam (`Promise<void>` — the count was incidental; nothing consumed it). */
     async deleteBySession(sessionId) {
         for (const k of [...this.map.keys()]) {
             const [sid] = JSON.parse(k);

package/dist/plugins/memory-sync-store-pg.d.ts

@@ -1,17 +1,25 @@
 import type { MemorySyncCursor } from "@sema-agent/core";
 import type { PgQueryFn } from "./pg-query.js";
+/** Table names (single source). SAME names as the TiDB twin (the two dialects never share one DB). */
 export declare const PG_MEMORY_SYNC_TABLES: {
     readonly syncCursors: "agent_memory_engine_sync_cursors";
     readonly pushQueue: "agent_memory_engine_push_queue";
     readonly history: "agent_memory_engine_history";
 };
+/** What the caller hands `enqueue` — the transport-neutral unit (§3 传输中立包:payload = the full
+ *  entry, opaque to this store; this queue never interprets it). */
 export interface PushQueueItem {
+    /** uuidv7 minted by the caller (time-ordered id = queue order tiebreak). */
     id: string;
     scope: string;
     entryId: string;
+    /** JSON-serializable entry payload — stored verbatim, returned parsed. */
     payload: unknown;
+    /** Epoch ms at/after which the item is due (caller-injected clock, core precedent). */
     nextAttemptAtMs: number;
 }
+/** A row handed back by `claimDue` — `attempts`/`lastError` reflect the state BEFORE this claim
+ *  (`fail` is what increments), so the consumer can enforce its attempt cap fail-loud. */
 export interface ClaimedPushQueueItem {
     id: string;
     scope: string;
@@ -19,18 +27,30 @@ export interface ClaimedPushQueueItem {
     payload: unknown;
     attempts: number;
     lastError: string | null;
+    /** The lease deadline this claim holds the row until (nowMs + claimLeaseMs). */
     leasedUntilMs: number;
 }
+/** The dialect-neutral contract both twins implement (anti-drift: one shared integration suite,
+ *  test/memory-sync-store-db-integration.test.ts, runs the SAME scenarios against BOTH engines). */
 export interface MemorySyncStore {
     getCursor(scope: string, peer: string): Promise<MemorySyncCursor | undefined>;
+    /** Whole-row replace (round semantics — baseRevs is swapped as one map, never merged). */
     putCursor(cursor: MemorySyncCursor): Promise<void>;
     enqueue(item: PushQueueItem): Promise<void>;
+    /** Lease-claim up to `limit` due rows (next_attempt_at <= nowMs), oldest-due first. Claimed rows
+     *  are invisible to other claimers until `complete`/`fail` or lease expiry (crash self-heal). */
     claimDue(nowMs: number, limit: number): Promise<ClaimedPushQueueItem[]>;
+    /** Success = delete the row (outbox posture: the queue only holds outstanding work). */
     complete(id: string): Promise<void>;
+    /** Transient failure: attempts+1 (SQL-atomic), record the error, schedule the next attempt. */
     fail(id: string, error: string, nextAttemptAtMs: number): Promise<void>;
 }
+/** Idempotent DDL for the sync plane (PG dialect). Call once at startup. */
 export declare function ensurePgMemorySyncSchema(query: PgQueryFn): Promise<void>;
+/** Options for {@link PgMemorySyncStore}. */
 export interface PgMemorySyncStoreOptions {
+    /** How long a `claimDue` lease holds a row invisible before a crashed worker's claim self-heals.
+     *  Must exceed the consumer's worst-case push round-trip. Default 60s. */
     claimLeaseMs?: number;
 }
 export declare class PgMemorySyncStore implements MemorySyncStore {
@@ -44,15 +64,26 @@ export declare class PgMemorySyncStore implements MemorySyncStore {
     complete(id: string): Promise<void>;
     fail(id: string, error: string, nextAttemptAtMs: number): Promise<void>;
 }
+/** One committed entry version, as the caller hands it to `appendHistory`. `prevRev` links the rev
+ *  chain (chain head = absent); a `delete` row is the tombstone (no snapshot). */
 export interface MemoryHistoryAppendRow {
+    /** Entry id (NOT unique alone — one id has many versions; PK is (id, rev)). */
     id: string;
+    /** This version's committed rev (content hash — the same rev the entry plane CAS'd on). */
     rev: string;
+    /** The rev this version replaced; absent on the chain head (first add). */
     prevRev?: string;
     op: "add" | "update" | "delete";
+    /** ⚠️ DESIGN-DOC AMENDMENT (142-S4 §1.3 has no scope column): the §1.4 export face and the
+     *  countByScope ops read NEED per-scope addressing, so the column is added here — denormalized
+     *  from the entry at write time (a deleted entry's row can't be joined back to the entries table). */
     scope: string;
+    /** Full entry snapshot for add/update; absent (→ SQL NULL) on delete tombstones. */
     snapshot?: unknown;
+    /** Caller-injected clock (core precedent) — the append point stamps the commit time. */
     writtenAtMs: number;
 }
+/** A history row read back (`historyOf`) — same shape with SQL NULLs made explicit. */
 export interface MemoryHistoryRow {
     id: string;
     rev: string;
@@ -62,11 +93,21 @@ export interface MemoryHistoryRow {
     snapshot: unknown | null;
     writtenAtMs: number;
 }
+/** The dialect-neutral history contract both twins implement (append-only: no update/delete face). */
 export interface MemoryHistoryStore {
+    /** Batch append. A duplicate (id, rev) is IGNORED idempotently (PG ON CONFLICT DO NOTHING /
+     *  TiDB no-op ON DUPLICATE KEY) — replaying a batch after a partial failure must not error and
+     *  must not rewrite committed history rows. Empty input = no-op. */
     appendHistory(rows: readonly MemoryHistoryAppendRow[]): Promise<void>;
+    /** All versions of one entry, oldest-first (written_at_ms; the authoritative ORDER within a same-ms
+     *  burst is the prev_rev chain itself — the sort is the read convenience, rev tie-break keeps it
+     *  deterministic). */
     historyOf(id: string): Promise<MemoryHistoryRow[]>;
+    /** Ops read face (§1.3 保留策略: v1 无界 + 运维计数 — quota/pruning waits for a demand signal). */
     countByScope(scope: string): Promise<number>;
 }
+/** Idempotent DDL for the history table (PG dialect). Separate from the sync-plane ensure so S5.1
+ *  can wire the write point independently of the S4 sync wiring. */
 export declare function ensurePgMemoryHistorySchema(query: PgQueryFn): Promise<void>;
 export declare class PgMemoryHistoryStore implements MemoryHistoryStore {
     private readonly query;
@@ -75,5 +116,6 @@ export declare class PgMemoryHistoryStore implements MemoryHistoryStore {
     historyOf(id: string): Promise<MemoryHistoryRow[]>;
     countByScope(scope: string): Promise<number>;
 }
+/** Shared row mapper (both dialects' SELECTs project the same column set). */
 export declare function historyRowFrom(r: Record<string, unknown>): MemoryHistoryRow;
 //# sourceMappingURL=memory-sync-store-pg.d.ts.map

package/dist/plugins/memory-sync-store-pg.js

@@ -1,9 +1,11 @@
 import { pgSafeJsonStringify, pgProtocolJsonStringify } from "./pg-safe-json.js";
+/** Table names (single source). SAME names as the TiDB twin (the two dialects never share one DB). */
 export const PG_MEMORY_SYNC_TABLES = {
     syncCursors: "agent_memory_engine_sync_cursors",
     pushQueue: "agent_memory_engine_push_queue",
     history: "agent_memory_engine_history",
 };
+/** Idempotent DDL for the sync plane (PG dialect). Call once at startup. */
 export async function ensurePgMemorySyncSchema(query) {
     await query(`CREATE TABLE IF NOT EXISTS ${PG_MEMORY_SYNC_TABLES.syncCursors} (
     scope         varchar(190) NOT NULL,
@@ -21,13 +23,18 @@ export async function ensurePgMemorySyncSchema(query) {
     next_attempt_at bigint       NOT NULL,
     last_error      text         NULL
   )`);
+    // Scan face (§1.2): the reaper/consumer sweeps by due time. Perf add-on, never correctness.
     await query(`CREATE INDEX IF NOT EXISTS ${PG_MEMORY_SYNC_TABLES.pushQueue}_next_attempt_idx ON ${PG_MEMORY_SYNC_TABLES.pushQueue} (next_attempt_at)`);
 }
+/** jsonb defense: node-pg hands back parsed objects, but a text-typed round-trip (or a foreign
+ *  writer) may yield a string — same posture as parseJson in pg-run-store.ts. */
 function fromJsonb(v) {
     if (typeof v === "string")
         return JSON.parse(v);
     return v;
 }
+/** node-pg returns bigint columns as strings (int8 overflows JS numbers in general; ours are epoch
+ *  ms, safely within 2^53) — normalize defensively. */
 function toMs(v) {
     return typeof v === "number" ? v : Number(v);
 }
@@ -42,6 +49,7 @@ export class PgMemorySyncStore {
         }
         this.claimLeaseMs = lease;
     }
+    // ── cursors ────────────────────────────────────────────────────────────────
     async getCursor(scope, peer) {
         const res = await this.query(`SELECT base_revs, updated_at_ms FROM ${PG_MEMORY_SYNC_TABLES.syncCursors} WHERE scope = $1 AND peer = $2`, [scope, peer]);
         const row = res.rows[0];
@@ -55,18 +63,40 @@ export class PgMemorySyncStore {
         };
     }
     async putCursor(cursor) {
+        // PK (scope,peer) is the table's ONLY unique key ⇒ ON CONFLICT has exactly one target, no
+        // hijack face (纪律:the entries-table ban on blind upserts does NOT apply here).
         await this.query(`INSERT INTO ${PG_MEMORY_SYNC_TABLES.syncCursors} (scope, peer, base_revs, updated_at_ms)
        VALUES ($1, $2, $3::jsonb, $4)
-       ON CONFLICT (scope, peer) DO UPDATE SET base_revs = EXCLUDED.base_revs, updated_at_ms = EXCLUDED.updated_at_ms`, [cursor.scope, cursor.peer, pgProtocolJsonStringify(cursor.baseRevs, "memory sync cursor baseRevs"), cursor.updatedAtMs]);
+       ON CONFLICT (scope, peer) DO UPDATE SET base_revs = EXCLUDED.base_revs, updated_at_ms = EXCLUDED.updated_at_ms`, 
+        // codex R11:baseRevs=对账基线(entry id→rev,协议数据)——有损改写=peer 收到的与库里存的
+        // 是两份 map,对账决策对着被改写的身份/rev 做。拒绝式(与 outbox/add/update 同族)。
+        [cursor.scope, cursor.peer, pgProtocolJsonStringify(cursor.baseRevs, "memory sync cursor baseRevs"), cursor.updatedAtMs]);
     }
+    // ── push queue ─────────────────────────────────────────────────────────────
     async enqueue(item) {
+        // Plain INSERT, fail-loud on a duplicate id: the caller mints uuidv7 per enqueue, so a dup is a
+        // caller bug (or a replay the caller must decide about) — never silently absorbed here.
         await this.query(`INSERT INTO ${PG_MEMORY_SYNC_TABLES.pushQueue} (id, scope, entry_id, payload, attempts, next_attempt_at, last_error)
-       VALUES ($1, $2, $3, $4::jsonb, 0, $5, NULL)`, [item.id, item.scope, item.entryId, pgProtocolJsonStringify(item.payload, "memory outbox payload"), item.nextAttemptAtMs]);
+       VALUES ($1, $2, $3, $4::jsonb, 0, $5, NULL)`, 
+        // codex R10:payload=协议数据(文档明言 verbatim;rev=内容哈希)——jsonb 列存不了脏值,但有损
+        // 改写=payload 与 rev 内部矛盾(消费端永拒/应用脏内容)。协议纪律:拒绝式(与 memory add/update
+        // 的 unstorable_bytes 同族;上游 add/update 已拒,此处=纵深防御)。
+        [item.id, item.scope, item.entryId, pgProtocolJsonStringify(item.payload, "memory outbox payload"), item.nextAttemptAtMs]);
     }
     async claimDue(nowMs, limit) {
         if (limit <= 0)
             return [];
         const leasedUntilMs = nowMs + this.claimLeaseMs;
+        // ONE statement = one implicit transaction: SKIP LOCKED excludes claimers overlapping in time,
+        // the next_attempt_at bump (lease) excludes everyone arriving after we commit. RETURNING gives
+        // the post-update row, so attempts/last_error are the pre-claim values (fail() is the only
+        // incrementer) and next_attempt_at is the lease we just wrote.
+        // ⚠️ MATERIALIZED CTE, NOT `WHERE id IN (SELECT … LIMIT n FOR UPDATE SKIP LOCKED)`: the IN-subquery
+        // form lets the planner RESCAN the locking subquery (e.g. as a rescanned semi-join inner), and each
+        // rescan skips the rows the previous pass locked and picks the NEXT due ones — an over-claim beyond
+        // LIMIT. Plan-dependent ⇒ intermittent: caught live on the build-host test DB (claimDue(limit=2) returned
+        // 3 rows, serial single-claimer run — the "sync-store env flake" real root cause). AS MATERIALIZED
+        // (PG12+) pins one evaluation; UPDATE … FROM joins the pinned id set.
         const res = await this.query(`WITH due AS MATERIALIZED (
          SELECT id FROM ${PG_MEMORY_SYNC_TABLES.pushQueue}
          WHERE next_attempt_at <= $1
@@ -91,12 +121,19 @@ export class PgMemorySyncStore {
         await this.query(`DELETE FROM ${PG_MEMORY_SYNC_TABLES.pushQueue} WHERE id = $1`, [id]);
     }
     async fail(id, error, nextAttemptAtMs) {
+        // attempts = attempts + 1 is SQL-atomic — a read-modify-write in JS would race a concurrent
+        // failer and lose increments (the attempt cap is the fail-loud stop, it must count honestly).
         await this.query(`UPDATE ${PG_MEMORY_SYNC_TABLES.pushQueue}
        SET attempts = attempts + 1, last_error = $2, next_attempt_at = $3
        WHERE id = $1`, [id, error, nextAttemptAtMs]);
     }
 }
+/** Idempotent DDL for the history table (PG dialect). Separate from the sync-plane ensure so S5.1
+ *  can wire the write point independently of the S4 sync wiring. */
 export async function ensurePgMemoryHistorySchema(query) {
+    // scope column = design-doc amendment (see MemoryHistoryAppendRow.scope). written_at_ms BIGINT
+    // (caller-injected epoch ms) instead of the draft's TIMESTAMP — the family's clock discipline
+    // (sync_cursors.updated_at_ms precedent; DB clocks never judge anything).
     await query(`CREATE TABLE IF NOT EXISTS ${PG_MEMORY_SYNC_TABLES.history} (
     id            char(36)     NOT NULL,
     rev           varchar(128) NOT NULL,
@@ -107,6 +144,7 @@ export async function ensurePgMemoryHistorySchema(query) {
     written_at_ms bigint       NOT NULL,
     PRIMARY KEY (id, rev)
   )`);
+    // countByScope / future per-scope export-with-history scan face. Perf add-on, never correctness.
     await query(`CREATE INDEX IF NOT EXISTS ${PG_MEMORY_SYNC_TABLES.history}_scope_idx ON ${PG_MEMORY_SYNC_TABLES.history} (scope)`);
 }
 export class PgMemoryHistoryStore {
@@ -117,6 +155,9 @@ export class PgMemoryHistoryStore {
     async appendHistory(rows) {
         if (rows.length === 0)
             return;
+        // ONE multi-row INSERT (the batch is "one applyPatches commit's worth" — small). ON CONFLICT
+        // (id, rev) DO NOTHING = idempotent replay; PK is the table's ONLY unique key, so the conflict
+        // target is unambiguous (no hijack face — append-only, nothing is ever updated).
         const params = [];
         const tuples = rows.map((r, i) => {
             params.push(r.id, r.rev, r.prevRev ?? null, r.op, r.scope, r.snapshot === undefined || r.snapshot === null ? null : pgSafeJsonStringify(r.snapshot), r.writtenAtMs);
@@ -135,10 +176,12 @@ export class PgMemoryHistoryStore {
         return res.rows.map((r) => historyRowFrom(r));
     }
     async countByScope(scope) {
+        // COUNT(*) comes back as a bigint-string from node-pg — normalize (toMs posture).
         const res = await this.query(`SELECT COUNT(*) AS n FROM ${PG_MEMORY_SYNC_TABLES.history} WHERE scope = $1`, [scope]);
         return toMs(res.rows[0]?.n ?? 0);
     }
 }
+/** Shared row mapper (both dialects' SELECTs project the same column set). */
 export function historyRowFrom(r) {
     return {
         id: String(r.id),

package/dist/plugins/memory-sync-store-tidb.d.ts

@@ -1,13 +1,20 @@
 import type { ClaimedPushQueueItem, MemoryHistoryAppendRow, MemoryHistoryRow, MemoryHistoryStore, MemorySyncStore, PushQueueItem } from "./memory-sync-store-pg.js";
 import type { MemorySyncCursor } from "@sema-agent/core";
 import type { Pool } from "mysql2/promise";
+/** Table names (single source) — SAME names as PG_MEMORY_SYNC_TABLES (the two dialects never share
+ *  one database). */
 export declare const TIDB_MEMORY_SYNC_TABLES: {
     readonly syncCursors: "agent_memory_engine_sync_cursors";
     readonly pushQueue: "agent_memory_engine_push_queue";
     readonly history: "agent_memory_engine_history";
 };
+/** Idempotent DDL for the sync plane (TiDB dialect). Call once at startup.
+ *  Key budget: utf8mb4 = 4 bytes/char, index cap 3072 bytes ⇒ PK(scope,peer) = 380 chars = 1520 B ✓. */
 export declare function ensureTiDBMemorySyncSchema(pool: Pool): Promise<void>;
+/** Options for {@link TiDBMemorySyncStore} — signature parity with the PG twin. */
 export interface TiDBMemorySyncStoreOptions {
+    /** How long a `claimDue` claim holds a row invisible before a crashed worker's claim self-heals.
+     *  Must exceed the consumer's worst-case push round-trip. Default 60s. */
     claimLeaseMs?: number;
 }
 export declare class TiDBMemorySyncStore implements MemorySyncStore {
@@ -21,6 +28,8 @@ export declare class TiDBMemorySyncStore implements MemorySyncStore {
     complete(id: string): Promise<void>;
     fail(id: string, error: string, nextAttemptAtMs: number): Promise<void>;
 }
+/** Idempotent DDL for the history table (TiDB dialect). Key budget: PK(id,rev) = CHAR(36)+
+ *  VARCHAR(128) = 164 chars ≤ 3072-byte utf8mb4 index cap ✓; KEY(scope) = 190 chars ✓. */
 export declare function ensureTiDBMemoryHistorySchema(pool: Pool): Promise<void>;
 export declare class TiDBMemoryHistoryStore implements MemoryHistoryStore {
     private readonly pool;