@sema-agent/core 5.38.0 → 5.40.0

package/dist/core/memory-engine/export-bundle.js

@@ -0,0 +1,306 @@
+import { createHash } from "node:crypto";
+import { canonicalJsonStringify } from "./file-backend.js";
+import { computeEntryRev } from "./frontmatter.js";
+export const BUNDLE_SECTION_KEYS = ["meta", "entries", "governance", "residuals"];
+function sha256Line(text) {
+    return createHash("sha256").update(`${text}\n`, "utf8").digest("hex");
+}
+export function computeBundleSectionHashes(bundle) {
+    return {
+        meta: sha256Line(canonicalJsonStringify({ bundle: bundle.bundle, at: bundle.at, scopes: bundle.scopes, storeId: bundle.storeId })),
+        entries: sha256Line(canonicalJsonStringify(bundle.entries)),
+        governance: sha256Line(canonicalJsonStringify(bundle.governance)),
+        residuals: sha256Line(canonicalJsonStringify(bundle.residuals)),
+    };
+}
+export function computeMemoryBundleHash(sectionHashes) {
+    return sha256Line(canonicalJsonStringify(sectionHashes));
+}
+const HEX64_RE = /^[0-9a-f]{64}$/;
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function stringArrayInvalid(v, what) {
+    if (!Array.isArray(v))
+        return `${what} is not an array`;
+    for (const s of v)
+        if (typeof s !== "string")
+            return `${what} carries a non-string member`;
+    return undefined;
+}
+function countInvalid(v, what) {
+    return typeof v === "number" && Number.isInteger(v) && v >= 0 ? undefined : `${what} is not a non-negative integer`;
+}
+function entryInvalid(raw, scopes) {
+    if (!isRecord(raw))
+        return "entry is not an object";
+    const e = raw;
+    if (typeof e.id !== "string" || e.id.length === 0)
+        return "entry has no id";
+    if (typeof e.slug !== "string" || e.slug.length === 0)
+        return `entry ${JSON.stringify(e.id)} has no slug`;
+    if (typeof e.scope !== "string" || e.scope.length === 0)
+        return `entry ${JSON.stringify(e.id)} has no scope`;
+    if (!scopes.has(e.scope))
+        return `entry ${JSON.stringify(e.id)} carries scope ${JSON.stringify(e.scope)} outside bundle.scopes (self-consistency)`;
+    if (typeof e.body !== "string")
+        return `entry ${JSON.stringify(e.id)} has no string body`;
+    if (typeof e.rev !== "string" || e.rev.length === 0)
+        return `entry ${JSON.stringify(e.id)} has no rev`;
+    const fm = e.frontmatter;
+    if (!isRecord(fm))
+        return `entry ${JSON.stringify(e.id)} has no frontmatter object`;
+    for (const key of ["name", "description", "type"]) {
+        if (fm[key] !== undefined && typeof fm[key] !== "string")
+            return `entry ${JSON.stringify(e.id)} frontmatter.${key} is not a string`;
+    }
+    if (fm.deleted !== undefined && typeof fm.deleted !== "boolean")
+        return `entry ${JSON.stringify(e.id)} frontmatter.deleted is not a boolean`;
+    if (fm.extra !== undefined) {
+        const bad = stringArrayInvalid(fm.extra, `entry ${JSON.stringify(e.id)} frontmatter.extra`);
+        if (bad !== undefined)
+            return bad;
+    }
+    if (fm.trust !== undefined && fm.trust !== "untrusted")
+        return `entry ${JSON.stringify(e.id)} frontmatter.trust is not "untrusted"`;
+    if (fm.provenance !== undefined) {
+        const p = fm.provenance;
+        if (!isRecord(p) || p.kind !== "repo_file" || typeof p.path !== "string" || typeof p.contentHash !== "string" || typeof p.ingestedAt !== "number") {
+            return `entry ${JSON.stringify(e.id)} frontmatter.provenance is malformed`;
+        }
+    }
+    const recomputed = computeEntryRev({ id: e.id, frontmatter: fm, body: e.body });
+    if (recomputed !== e.rev)
+        return `entry ${JSON.stringify(e.id)} rev ${JSON.stringify(e.rev)} does not equal its recomputed content rev ${JSON.stringify(recomputed)} (forged or corrupted package)`;
+    return undefined;
+}
+export function memoryBundleInvalid(raw, opts = {}) {
+    if (!isRecord(raw))
+        return "bundle is not an object";
+    const b = raw;
+    if (typeof b.bundle !== "number")
+        return "bundle envelope version is missing";
+    if (b.bundle > 1)
+        return `bundle envelope version ${String(b.bundle)} is newer than this engine supports — refusing to reinterpret it`;
+    if (b.bundle !== 1)
+        return `bundle envelope version ${String(b.bundle)} is not recognized`;
+    if (typeof b.at !== "number" || !Number.isInteger(b.at))
+        return "bundle.at is not an integer";
+    const scopesBad = stringArrayInvalid(b.scopes, "bundle.scopes");
+    if (scopesBad !== undefined)
+        return scopesBad;
+    const scopes = b.scopes;
+    if (scopes.length === 0)
+        return "bundle.scopes is empty";
+    if (scopes.some((s) => s.length === 0))
+        return "bundle.scopes carries an empty scope";
+    if (new Set(scopes).size !== scopes.length)
+        return "bundle.scopes carries a duplicate scope";
+    if (typeof b.storeId !== "string" || b.storeId.length === 0)
+        return "bundle.storeId is missing";
+    if (opts.expectedScopes !== undefined) {
+        const allowed = new Set(opts.expectedScopes);
+        const outside = scopes.find((s) => !allowed.has(s));
+        if (outside !== undefined)
+            return `bundle scope ${JSON.stringify(outside)} is outside the expected scope set — whole package refused`;
+    }
+    const entriesArr = Array.isArray(b.entries) && b.entries;
+    if (entriesArr === false)
+        return "bundle.entries is not an array";
+    const scopeSet = new Set(scopes);
+    const entryIds = new Set();
+    for (const raw2 of entriesArr) {
+        const bad = entryInvalid(raw2, scopeSet);
+        if (bad !== undefined)
+            return bad;
+        const id = raw2.id;
+        if (entryIds.has(id))
+            return `bundle.entries carries id ${JSON.stringify(id)} twice (bad package)`;
+        entryIds.add(id);
+    }
+    const gov = b.governance;
+    if (!isRecord(gov))
+        return "bundle.governance is missing (the governance section is a structural requirement, not an attachment)";
+    const challengesArr = Array.isArray(gov.challenges) && gov.challenges;
+    if (challengesArr === false)
+        return "bundle.governance.challenges is not an array";
+    const challengeEventIds = new Set();
+    for (const raw2 of challengesArr) {
+        if (!isRecord(raw2))
+            return "challenge row is not an object";
+        const c = raw2;
+        if (typeof c.eventId !== "string" || c.eventId.length === 0)
+            return "challenge row has no eventId";
+        if (typeof c.entryId !== "string" || c.entryId.length === 0)
+            return "challenge row has no entryId";
+        if (typeof c.reason !== "string")
+            return "challenge row has no reason";
+        if (typeof c.at !== "number" || !Number.isInteger(c.at))
+            return "challenge row has no integer at";
+        if (c.challengedRev !== undefined && typeof c.challengedRev !== "string")
+            return "challenge row challengedRev is not a string";
+        if (challengeEventIds.has(c.eventId))
+            return `bundle.governance.challenges carries eventId ${JSON.stringify(c.eventId)} twice (bad package)`;
+        challengeEventIds.add(c.eventId);
+    }
+    const pollutedSessionsArr = Array.isArray(gov.pollutedSessions) && gov.pollutedSessions;
+    if (pollutedSessionsArr === false)
+        return "bundle.governance.pollutedSessions is not an array";
+    const pollutedIds = new Set();
+    for (const raw2 of pollutedSessionsArr) {
+        if (!isRecord(raw2))
+            return "polluted-session row is not an object";
+        if (typeof raw2.sessionId !== "string" || raw2.sessionId.length === 0)
+            return "polluted-session row has no sessionId";
+        if (typeof raw2.at !== "number")
+            return "polluted-session row has no at";
+        if (typeof raw2.reason !== "string")
+            return "polluted-session row has no reason";
+        if (pollutedIds.has(raw2.sessionId))
+            return `bundle.governance.pollutedSessions carries sessionId ${JSON.stringify(raw2.sessionId)} twice (bad package)`;
+        pollutedIds.add(raw2.sessionId);
+    }
+    const lineageArr = Array.isArray(gov.lineage) && gov.lineage;
+    if (lineageArr === false)
+        return "bundle.governance.lineage is not an array";
+    const lineagePairs = new Set();
+    for (const raw2 of lineageArr) {
+        if (!isRecord(raw2))
+            return "lineage row is not an object";
+        if (typeof raw2.entryId !== "string" || raw2.entryId.length === 0)
+            return "lineage row has no entryId";
+        if (typeof raw2.sessionId !== "string" || raw2.sessionId.length === 0)
+            return "lineage row has no sessionId";
+        if (typeof raw2.lastRev !== "string" || raw2.lastRev.length === 0)
+            return "lineage row has no lastRev";
+        if (typeof raw2.lastAt !== "number")
+            return "lineage row has no lastAt";
+        const key = `${raw2.entryId}\u0000${raw2.sessionId}`;
+        if (lineagePairs.has(key))
+            return `bundle.governance.lineage carries (${raw2.entryId}, ${raw2.sessionId}) twice (bad package)`;
+        lineagePairs.add(key);
+    }
+    const custodyArr = Array.isArray(gov.custody) && gov.custody;
+    if (custodyArr === false)
+        return "bundle.governance.custody is not an array";
+    const custodyByEv = new Map();
+    const scopeLiteralOutside = (row) => {
+        const sideScope = (v) => {
+            if (!isRecord(v))
+                return undefined;
+            return typeof v.scope === "string" ? v.scope : undefined;
+        };
+        const literals = [
+            sideScope(row.from),
+            sideScope(row.to),
+            typeof row.scope === "string" ? row.scope : undefined,
+            sideScope(row.select),
+        ];
+        return literals.find((s) => s !== undefined && !scopeSet.has(s));
+    };
+    for (const raw2 of custodyArr) {
+        if (!isRecord(raw2))
+            return "custody row is not an object";
+        if (typeof raw2.ev !== "string" || raw2.ev.length === 0)
+            return "custody row has no ev";
+        if (typeof raw2.channel !== "string" || raw2.channel.length === 0)
+            return "custody row has no channel";
+        if (typeof raw2.at !== "number" || !Number.isInteger(raw2.at))
+            return "custody row has no integer at";
+        const outside = scopeLiteralOutside(raw2);
+        if (outside !== undefined)
+            return `custody row ${JSON.stringify(raw2.ev)} names scope ${JSON.stringify(outside)} outside bundle.scopes (self-consistency: every in-package scope literal ⊆ bundle.scopes)`;
+        const canonical = canonicalJsonStringify(raw2);
+        const prior = custodyByEv.get(raw2.ev);
+        if (prior !== undefined && prior !== canonical)
+            return `bundle.governance.custody carries ev ${JSON.stringify(raw2.ev)} twice with DIFFERENT payloads (bad package)`;
+        custodyByEv.set(raw2.ev, canonical);
+    }
+    const res = b.residuals;
+    if (!isRecord(res))
+        return "bundle.residuals is missing";
+    for (const key of ["quarantined", "unbound", "pendingLatch"]) {
+        const bad = stringArrayInvalid(res[key], `bundle.residuals.${key}`);
+        if (bad !== undefined)
+            return bad;
+    }
+    const contentUnavailableArr = Array.isArray(res.contentUnavailable) && res.contentUnavailable;
+    if (contentUnavailableArr === false)
+        return "bundle.residuals.contentUnavailable is not an array";
+    for (const raw2 of contentUnavailableArr) {
+        if (!isRecord(raw2) || typeof raw2.id !== "string" || typeof raw2.scope !== "string" || typeof raw2.slug !== "string" || typeof raw2.rev !== "string" || typeof raw2.reason !== "string") {
+            return "bundle.residuals.contentUnavailable carries a malformed row";
+        }
+        if (!scopeSet.has(raw2.scope))
+            return `bundle.residuals.contentUnavailable row ${JSON.stringify(raw2.id)} names scope ${JSON.stringify(raw2.scope)} outside bundle.scopes (self-consistency)`;
+    }
+    for (const key of ["quarantineOpaque", "unsliceableCustody", "unboundCount", "pendingLatchCount"]) {
+        const bad = countInvalid(res[key], `bundle.residuals.${key}`);
+        if (bad !== undefined)
+            return bad;
+    }
+    const integrity = b.integrity;
+    if (!isRecord(integrity))
+        return "bundle.integrity is missing";
+    const sh = integrity.sectionHashes;
+    if (!isRecord(sh))
+        return "bundle.integrity.sectionHashes is missing";
+    const shKeys = Object.keys(sh).sort();
+    if (shKeys.length !== BUNDLE_SECTION_KEYS.length || BUNDLE_SECTION_KEYS.some((k) => !Object.prototype.hasOwnProperty.call(sh, k))) {
+        return `bundle.integrity.sectionHashes must carry exactly the keys ${BUNDLE_SECTION_KEYS.join("/")} (a stripped or padded section set is a bad package)`;
+    }
+    for (const k of BUNDLE_SECTION_KEYS) {
+        if (typeof sh[k] !== "string" || !HEX64_RE.test(sh[k]))
+            return `bundle.integrity.sectionHashes.${k} is not a sha256 hex`;
+    }
+    const recomputed = computeBundleSectionHashes(b);
+    for (const k of BUNDLE_SECTION_KEYS) {
+        if (recomputed[k] !== sh[k])
+            return `bundle.integrity.sectionHashes.${k} does not match the section's canonical content (damaged or tampered package)`;
+    }
+    const entryCount = integrity.entryCount;
+    if (typeof entryCount !== "number" || entryCount !== entriesArr.length)
+        return "bundle.integrity.entryCount does not equal entries.length";
+    const revs = integrity.revs;
+    if (!isRecord(revs))
+        return "bundle.integrity.revs is missing";
+    const revKeys = Object.keys(revs);
+    if (revKeys.length !== entryIds.size)
+        return "bundle.integrity.revs cardinality does not equal the entry id set";
+    for (const e of b.entries) {
+        if (revs[e.id] !== e.rev)
+            return `bundle.integrity.revs[${JSON.stringify(e.id)}] does not equal the entry's rev`;
+    }
+    return undefined;
+}
+export const BUNDLE_FREE_TEXT_DISCLOSURE = "Free-string fields in this bundle (pollution/challenge reasons, challenge event ids, custody request ids, session ids) are carried verbatim and may contain text the exporting deployment put there; subset-export tenant isolation does not extend to those literals.";
+export function assembleMemoryExportBundle(input) {
+    const sections = {
+        bundle: 1,
+        at: input.at,
+        scopes: [...input.scopes].sort(),
+        storeId: input.storeId,
+        entries: [...input.entries].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)),
+        governance: {
+            challenges: input.challenges,
+            pollutedSessions: [...input.pollutedSessions].sort((a, b) => (a.sessionId < b.sessionId ? -1 : a.sessionId > b.sessionId ? 1 : 0)),
+            lineage: [...input.lineage].sort((a, b) => (a.entryId < b.entryId ? -1 : a.entryId > b.entryId ? 1 : 0) || (a.sessionId < b.sessionId ? -1 : a.sessionId > b.sessionId ? 1 : 0)),
+            custody: input.custody,
+        },
+        residuals: input.residuals,
+    };
+    const sectionHashes = computeBundleSectionHashes(sections);
+    const doc = [BUNDLE_FREE_TEXT_DISCLOSURE];
+    if (input.residuals.unsliceableCustody > 0) {
+        doc.push(`This subset export could not carry ${input.residuals.unsliceableCustody} custody row(s) that have no scope to slice by (unbound-deletion history among them): the anti-resurrection guarantee for those ids does not travel with this bundle — a full-store export carries them.`);
+    }
+    return {
+        ...sections,
+        integrity: {
+            entryCount: sections.entries.length,
+            revs: Object.fromEntries(sections.entries.map((e) => [e.id, e.rev])),
+            sectionHashes,
+        },
+        doc,
+    };
+}

package/dist/core/memory-engine/file-backend.d.ts

@@ -1,4 +1,5 @@
-import { scopeDirName, type MemoryPartitionIncidentSink } from "./layout.js";
+import { scopeDirName, type ChallengeEvent, type MemoryPartitionIncidentSink } from "./layout.js";
+import type { MemoryBundleImportPlan, MemoryImportReport } from "./export-bundle.js";
 import type { HarvestRejection, MemoryBackend, MemoryEntry, MemoryEntryHeader, NotePatch, PatchReport, ScoredMemoryEntry } from "./types.js";
 /** Files/dirs the entry scan never treats as entries: the derived index, dotfiles (`.hydrate`,
  *  transaction staging files), and anything not `.md`. */
@@ -288,6 +289,55 @@ export interface EntryCustodyReport {
     events: TransferEvidence[];
     reason?: string;
 }
+/**
+ * design/178 v2-c §3 — what the ONE-LOCK export composite ({@link FileMemoryEngineBackend.exportSnapshotOf})
+ * answers: every face of the store the bundle needs, read inside a single txn-mutex hold (see the
+ * method doc for the fence law). Entries carry committed content only; a bound row whose committed
+ * carrier cannot be served is enumerated under `contentUnavailable` instead (never silently
+ * dropped, never dressed as content). `unbound`/`pendingLatch` are STORE-LEVEL residual sets (no
+ * tenant to belong to); the bundle assembly decides whether their id lists travel (full-store
+ * export) or only their counts (subset export). `challenges`/`lineage`/`pollutedSessions` are the
+ * RAW governance faces — the (pure) bundle assembly slices them to the exported entry/session
+ * sets; `custody` is already sliced (the slicing consumes row-level scope fields this module owns).
+ */
+export interface MemoryExportSnapshot {
+    storeId: string;
+    /** True ⇔ the requested scopes cover every registered scope (one trust domain — the residual id
+     *  lists and unbound-deletion custody rows may travel). */
+    fullStore: boolean;
+    entries: MemoryEntry[];
+    contentUnavailable: Array<{
+        id: string;
+        scope: string;
+        slug: string;
+        rev: string;
+        reason: string;
+    }>;
+    unbound: string[];
+    pendingLatch: string[];
+    custody: TransferEvidence[];
+    unsliceableCustody: number;
+    challenges: ChallengeEvent[];
+    lineage: Array<{
+        entryId: string;
+        sessionId: string;
+        lastRev: string;
+        lastAt: number;
+    }>;
+    pollutedSessions: Array<{
+        sessionId: string;
+        at: number;
+        reason: string;
+    }>;
+    quarantined: string[];
+    quarantineOpaque: number;
+}
+/** Test hook (证伪式复审 L3): small constants so the crash-window leg does not really wait 15-30s. */
+interface TxnLockTimings {
+    staleMs?: number;
+    waitMs?: number;
+    stealGraceMs?: number;
+}
 /** Construction options for {@link FileMemoryEngineBackend}. */
 export interface FileMemoryEngineBackendOptions {
     /** ⚠️ 分家坑(service 报告 2026-07-09):不显式传时,控制平面按无参 `resolveMemoryEngineRoot()`
@@ -369,6 +419,10 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
     private adoptionNoticeKeys;
     /** Test seam (§7.4 r4-④ arm): force a post-commit-point transfer-append failure. */
     private transfersAppendFault?;
+    /** Test seam (v2-c §3-2 fence pins): runs INSIDE the export composite's mutex hold, after the
+     *  data reads and before the second fingerprint — a test injects a governance-face write here to
+     *  exercise the drift-retry and the three-round refusal. Production leaves it unset. */
+    private exportFaceProbe?;
     /** v2-b §3-4 — the resurrection backstop's chain digest, keyed by the evidence log's stat
      *  fingerprint (size + mtimeMs — append-only growth and a torn-tail shrink both move `size`).
      *  NEVER a mount-lifetime cache: the fingerprint is re-verified under the txn mutex on every
@@ -972,6 +1026,129 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
     /** The pure open-form evidence read behind {@link custodyOf} (no healing, no writes). `raw` is
      *  the caller's already-fenced read of the log (undefined = absent). */
     private custodyReadPure;
+    /** design/178 v2-c §4 — the export/import refusal code (engine coded-error family, deliberately
+     *  outside the governance registry: a store-state refusal, not a per-principal verdict). */
+    private static readonly EXPORT_INCOMPLETE;
+    /** The durable store identity (§6.2): read it, or mint it (`wx`) on first need — the txn mutex is
+     *  held by every caller, so the exclusive create cannot race in-process; a cross-process EEXIST
+     *  loser adopts the winner's identity. Corrupt/unreadable identity is fail-closed. */
+    private storeIdentityLocked;
+    /** One consistency fingerprint over the three ENGINE governance faces (challenge ledger, lineage
+     *  ledger, pollution markers) — raw bytes, journal included. The two strict sidecars' JOURNAL
+     *  reads are wrapped FAIL-CLOSED here (§4-6): the shared strict reader folds a journal read
+     *  error into absence, and an export that read a stale main file over an unreadable journal
+     *  would seal stale governance under an honest hash. Marker files that exist but cannot be read
+     *  fingerprint their error code (a stable fault stays stable; a flapping one drifts the fence). */
+    private exportGovernanceFingerprint;
+    /**
+     * The export chain read: PURE INSPECTION (never heals, never quarantines, never truncates — C-8
+     * pins the file byte-identical across a refused export). A torn tail refuses the export
+     * (`memory.export_incomplete`; the deployment heals it by running any locked mutation entry,
+     * then re-exports); an unknown channel refuses too (T-14: a row whose slicing rules this build
+     * does not know can neither be carried — possible cross-tenant leak — nor silently dropped —
+     * lost mandatory governance); one ev under two different payloads refuses (spliced chain);
+     * non-tail corruption stays the fail-closed {@link ControlPlaneCorruptError}. Byte-equal
+     * duplicates collapse (append-idempotency residue).
+     */
+    private readExportChainRowsPure;
+    /**
+     * v2-c §2 — the tenant-slicing table over validated chain rows (T-6..T-11; T-9/T-10 refusals,
+     * T-14 already refused by the reader). `storeId` is a thunk so the identity mints only when a
+     * redaction actually needs the provenance stamp.
+     */
+    private sliceCustodyForScopes;
+    /** T-12 — quarantine residual enumeration for an id set (names for attributable hits, an opaque
+     *  count for the rest — same honest bound the erasure attestation uses). */
+    private enumerateQuarantineFor;
+    /**
+     * design/178 v2-c §3 — the ONE-LOCK export composite (capability face; probe with
+     * `typeof backend.exportSnapshotOf === "function"`). All five reads — entries (ledger-driven,
+     * committed content), custody chain, challenge ledger, lineage ledger, pollution markers — happen
+     * inside a single txn-mutex hold: the two backend faces are writer-serialized by the mutex
+     * itself; the three engine faces (written under their own sidecar locks, not the mutex) are
+     * fenced by a byte-level double fingerprint around the reads (≤3 rounds, then a loud refusal —
+     * a store too hot to snapshot answers `memory.export_incomplete`, never a mixed-epoch bundle).
+     * The terminal ownership assertion turns a stolen lock (stale-steal past the 30s line during a
+     * long assembly) into a refusal: an unstolen lock means no writer entered, which IS the
+     * consistency proof — no lease machinery needed. The chain read is pure inspection (a torn tail
+     * refuses with the file byte-untouched); `complete:false`-class scenes all refuse loudly — there
+     * is no degraded bundle shape, by design (§4).
+     */
+    exportSnapshotOf(scopes: readonly string[], timings?: TxnLockTimings): Promise<MemoryExportSnapshot>;
+    /**
+     * design/178 v2 §4.3 — the single-item governance slice face (parent-design form, kept for
+     * NON-export consumers: erasure resolution, per-id inspection tooling). Answers
+     * `complete: false` + reason instead of a bundle-shaped refusal (its callers fail closed on the
+     * flag); definite corruption still throws. The export path deliberately does NOT use this face —
+     * two independently-locked single faces are exactly the cross-face tear the composite closes.
+     */
+    governanceExport(scopes: readonly string[], timings?: TxnLockTimings): Promise<{
+        custody: TransferEvidence[];
+        unbound: string[];
+        complete: boolean;
+        unsliceableCustody: number;
+        reason?: string;
+    }>;
+    /**
+     * design/178 v2-c §5.4 — custody carriage onto THIS chain (capability face). Rows land under the
+     * import namespace — `ev = imp:<bundleHash>:<source ev>` (full-hash salt: deterministic per
+     * bundle, chain-deterministic across hops — a re-exported imported row salts its CURRENT ev
+     * next hop), `origin` kept when present (multi-hop provenance) else stamped with the source
+     * store's identity, `srcEv` kept else stamped with the source ev — so an imported row is ALWAYS
+     * origin-bearing and the local replay/anchor judgments structurally never read it. Unknown
+     * channels and rows failing this store's own validation are WITHHELD and reported (never
+     * appended verbatim — an unvalidatable row would poison the fail-closed chain — and never a
+     * whole-package refusal — a newer exporter must not brick an older importer). Appends are
+     * idempotent by ev with canonical-payload comparison (same-bundle re-import converges; a
+     * different payload under an existing ev is fail-closed corruption). Direct chain append, no
+     * journal: custody carriage is not a ledger mutation, and origin-bearing rows are forbidden in
+     * journals by the recovery leg's own validation.
+     */
+    custodyImport(rows: ReadonlyArray<Record<string, unknown>>, opts: {
+        bundleHash: string;
+        sourceStoreId: string;
+    }, timings?: TxnLockTimings): Promise<{
+        appended: number;
+        withheld: Array<{
+            srcEv: string;
+            channel: string;
+        }>;
+    }>;
+    /** The in-lock custody carriage body ({@link custodyImport}'s and the import composite's shared
+     *  leg — the composite already holds the mutex and must not re-enter the acquisition). */
+    private custodyImportLocked;
+    /** Append import-namespace challenge events and VERIFY every key-idempotent replay by reading
+     *  the full payload back (§5.2 defense ③): `appendChallengeEvents` is key-idempotent, not
+     *  payload-idempotent — a pre-planted same-key event (a resolve, or a same-entry different-
+     *  reason challenge) would silently swallow the imported challenge while the return echoes a
+     *  plausible assignment. A mismatch ABORTS the import (the latch stays; the account is not
+     *  silently short). */
+    private appendImportChallengesVerified;
+    /**
+     * design/178 v2-c §1 — the IMPORT COMPOSITE (capability face; the engine's `importMemoryBundle`
+     * is its validating membrane). One txn-mutex hold end to end:
+     *  ①b destination-chain completeness precheck (torn/degraded ⇒ whole package refused with ZERO
+     *     side effects — before the latch, "reject before landing" made literal);
+     *  ②  the synthetic latch (durable pending lineage txn over every bundle entry id — from here
+     *     to release, those ids are withheld on every model-visible read face; crash-safe);
+     *  ③  authoritative in-lock judgment (the five import rules — a pre-lock classification would
+     *     only be advisory, so there is none: the lock-held pass IS the classification);
+     *  ④  entry landing through {@link applyPatchesLocked} (same skeleton, same lock, same recovery
+     *     leg — never a second transaction protocol; `guard:"absent"` adjudicates the residual
+     *     same-id arms);
+     *  ⑤  governance legs, custody FIRST unconditionally (chain facts are exempt from the
+     *     entry-eligibility rule — an absent-id delete row is exactly the anti-resurrection
+     *     payload), then entry-attached lineage/challenges for landed ∪ already-present ids only,
+     *     then pollution (retroactive sweep DURABLE BEFORE the marker — the crash between them
+     *     leaves contributions challenged and the marker converging on re-import, never the
+     *     reverse);
+     *  ⑥  the durable completion receipt (`wx`, carrying the report) and the latch release —
+     *     receipt-gated, the ONLY release channel.
+     * Any failure past ② leaves the latch standing: re-importing the SAME bundle converges every
+     * crash window (idempotent latch, idempotent judgments, ev/key-idempotent governance legs,
+     * receipt short-circuit).
+     */
+    importBundleCommit(plan: MemoryBundleImportPlan, timings?: TxnLockTimings): Promise<MemoryImportReport>;
     getConsolidationCursor(scope: string): Promise<string | undefined>;
     setConsolidationCursor(scope: string, cursor: string): Promise<void>;
     private readCursors;