@sema-agent/core 5.38.0 → 5.40.0

package/dist/core/mailbox-store.js

@@ -1,4 +1,13 @@
 import { assertRetentionPolicy } from "./retention-policy.js";
+export const MAILBOX_TOMBSTONED_RECIPIENT_CODE = "mailbox.recipient_tombstoned";
+export class MailboxStoreError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "MailboxStoreError";
+    }
+}
 export function newestSentAt(messages) {
     let newest;
     for (const m of messages) {

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

@@ -1,4 +1,5 @@
 import { type CommittedBinding, type EraseMemoryEntriesInput, type MemoryErasureAttestation, type TransferEvidence } from "./file-backend.js";
+import { type MemoryExportBundle, type MemoryImportReport } from "./export-bundle.js";
 import { type ChallengeAssignment, type ChallengeEvent, type ControlPlaneRebuildReceipt, type StrictControlPlaneLedger, type ChallengedHistoryRow, type LineagePendingTxn, type LineagePromotion, type MemoryPartitionIncidentSink, type RetrievedAccountRow, type SessionPollutionRecord } from "./layout.js";
 import type { HarvestReport, MemoryAnnouncement, MemoryBackend, MemorySessionHandle, ScanFinding } from "./types.js";
 /**
@@ -438,6 +439,32 @@ export declare class MemoryEngine {
      * reported honestly, never fabricated and never a throw (#196 absence-reports-not-silent-green).
      */
     provenanceOf(entryId: string): Promise<EntryProvenanceAccount>;
+    /**
+     * Export the requested scopes as a GOVERNANCE-COMPLETE bundle (design/178 v2 §4.3 + v2-c):
+     * committed entries (audit-snapshot semantics — shadow-backed rows a disk scan would miss are
+     * in; unavailable content is enumerated, never dressed), the scope-sliced custody chain, the
+     * exported entries' unresolved challenge events and lineage rows, and the named sessions'
+     * pollution markers — all read inside the backend's single-lock export composite, so a bundle is
+     * never a mixed-epoch scene. Refusals are loud and total (`memory.export_incomplete`): there is
+     * no degraded/partial bundle shape — "a truncated package that looks complete" is the one
+     * deliverable this API is forbidden to produce.
+     */
+    exportMemoryScopes(scopes: readonly string[]): Promise<MemoryExportBundle>;
+    /**
+     * Import a bundle (design/178 v2-c §1/§7). Validation is TOTAL and lands nothing on failure
+     * (`memory.import_rejected`): integrity (fixed section-hash key set, per-entry content-rev
+     * recomputation, batch-unique ids/event ids), structure (the governance section is REQUIRED —
+     * there is no entries-only escape hatch), and — when `opts.expectedScopes` is present (a service
+     * endpoint pins its principal's grant set here) — the scope authorization envelope. Everything
+     * after validation runs inside the backend's import composite: the synthetic latch (imported ids
+     * stay withheld from every model-visible read face until governance fully lands), the five
+     * import judgments IN-LOCK, entry landing through the one transaction skeleton, the governance
+     * legs, and the receipt-gated latch release. A crash anywhere converges by re-importing the SAME
+     * bundle; a completed import answers its recorded report idempotently.
+     */
+    importMemoryBundle(bundle: MemoryExportBundle, opts?: {
+        expectedScopes?: readonly string[];
+    }): Promise<MemoryImportReport>;
     /** Host API: challenge every entry the lineage ledger attributes to `sessionId` (post-hoc source
      *  falsification — trustedTools misconfigured, a tool re-classified, late delegation evidence).
      *  Same requestId contract as {@link challengeEntries}. */

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

@@ -6,6 +6,7 @@ import { inlineUntrusted } from "../untrusted-text.js";
 import { formatMemoryAge } from "../memory-recall.js";
 import { computeEntryRev, parseEntryFile, serializeEntryFile } from "./frontmatter.js";
 import { DEFAULT_MAX_ENTRY_DEPTH, MEMORY_INDEX_FILENAME, canonicalJsonStringify, captureErasureInput, erasureRequestInvalid, erasureSelectHash, scanEntryFiles, } from "./file-backend.js";
+import { assembleMemoryExportBundle, computeMemoryBundleHash, memoryBundleInvalid, } from "./export-bundle.js";
 import { QUARANTINE_DIR, SCAN_FUSE_THRESHOLD, quarantineAndTombstone, readIndexRevs, writeIndexRevs, bumpScanFuse, canonicalize, claimRootScope, clearScanFuse, adoptCanonicalKeyedControlDir, deriveControlPlaneDir, drainMemoryAnnouncements, enqueueMemoryAnnouncement, ensureDirExists, isContainedIn, markSessionPolluted, readSessionPollution, recordRetrievedAccount, writeFileNoFollow, readRetrievedAccount, registerScope, registeredScopes, resolveMemoryEngineRoot, scopeDirFor, appendChallengeEvents, appendLineageAudit, rebuildStrictControlPlaneLedger, isStrictControlPlaneLedgerCorrupt, CHALLENGE_LEDGER_MAX_EVENTS, adjudicateLineagePending, challengedEntryIds, clearLineageForEntries, discardLineagePending, lineageAccountOfEntry, lineageContributionsOfSession, lineageLatchedIds, promoteLineagePending, readChallengeEvents, readChallengedHistory, readLineageRecord, recordChallengedHistory, recordLineageCredential, reconcileLineage, resolveChallengeEvent, stageLineagePending, } from "./layout.js";
 import { scanMemoryFileName, scanMemoryWrite, scanRemediation } from "./scan.js";
 export const MEMORY_INSTRUCTION_TEMPLATE = `# Memory
@@ -521,6 +522,105 @@ export class MemoryEngine {
             return { v: 1, id: entryId, binding, contributors: plane.contributors, ...(plane.exclusion !== undefined ? { exclusion: plane.exclusion } : {}), contentState, ...(ingest !== undefined ? { ingest } : {}), custody };
         }
     }
+    async exportMemoryScopes(scopes) {
+        if (!Array.isArray(scopes) || scopes.length === 0 || scopes.some((s) => typeof s !== "string" || s.length === 0) || new Set(scopes).size !== scopes.length) {
+            const e = new Error("exportMemoryScopes: scopes must be a non-empty array of unique non-empty scope names");
+            e.code = "config.memory_export_request";
+            throw e;
+        }
+        const requested = [...scopes];
+        const face = this.backend.exportSnapshotOf;
+        if (typeof face !== "function") {
+            const e = new Error("exportMemoryScopes: this backend has no export-snapshot capability (exportSnapshotOf) — a governance-complete bundle cannot be assembled from the generic read faces (they cannot fence the five store faces into one epoch), and a governance-less export is the laundering shape this API refuses by design.");
+            e.code = "memory.export_incomplete";
+            throw e;
+        }
+        const snap = await face.call(this.backend, requested);
+        const exportedIds = new Set([...snap.entries.map((e) => e.id), ...snap.contentUnavailable.map((r) => r.id)]);
+        const resolvedGenerations = new Set();
+        for (const e of snap.challenges)
+            if (e.kind === "resolve")
+                resolvedGenerations.add(`${e.entryId}#${e.generation}`);
+        const challenges = [];
+        for (const e of snap.challenges) {
+            if (e.kind !== "challenge" || !exportedIds.has(e.entryId) || resolvedGenerations.has(`${e.entryId}#${e.generation}`))
+                continue;
+            challenges.push({ eventId: e.eventId, entryId: e.entryId, reason: e.reason, at: e.at, ...(e.challengedRev !== undefined ? { challengedRev: e.challengedRev } : {}) });
+        }
+        const lineage = snap.lineage.filter((r) => exportedIds.has(r.entryId));
+        const namedSessions = new Set(lineage.map((r) => r.sessionId));
+        for (const row of snap.custody) {
+            const sessions = row.sessions;
+            if (Array.isArray(sessions))
+                for (const s of sessions)
+                    if (typeof s === "string")
+                        namedSessions.add(s);
+        }
+        const pollutedSessions = snap.pollutedSessions.filter((p) => namedSessions.has(p.sessionId));
+        return assembleMemoryExportBundle({
+            at: this.now(),
+            scopes: requested,
+            storeId: snap.storeId,
+            entries: snap.entries,
+            challenges,
+            pollutedSessions,
+            lineage,
+            custody: snap.custody,
+            residuals: {
+                quarantined: snap.quarantined,
+                unbound: snap.fullStore ? snap.unbound : [],
+                pendingLatch: snap.fullStore ? snap.pendingLatch : [],
+                contentUnavailable: snap.contentUnavailable,
+                quarantineOpaque: snap.quarantineOpaque,
+                unsliceableCustody: snap.unsliceableCustody,
+                unboundCount: snap.unbound.length,
+                pendingLatchCount: snap.pendingLatch.length,
+            },
+        });
+    }
+    async importMemoryBundle(bundle, opts) {
+        let inert;
+        try {
+            inert = JSON.parse(JSON.stringify(bundle));
+        }
+        catch (err) {
+            const e = new Error(`importMemoryBundle: the bundle is not JSON-serializable (${err instanceof Error ? err.message : String(err)})`);
+            e.code = "config.memory_import_request";
+            throw e;
+        }
+        const bad = memoryBundleInvalid(inert, { ...(opts?.expectedScopes !== undefined ? { expectedScopes: opts.expectedScopes } : {}) });
+        if (bad !== undefined) {
+            const e = new Error(`importMemoryBundle: ${bad} — the whole package is refused, nothing landed`);
+            e.code = "memory.import_rejected";
+            throw e;
+        }
+        const b = inert;
+        const face = this.backend.importBundleCommit;
+        if (typeof face !== "function") {
+            const e = new Error("importMemoryBundle: this backend has no bundle-import capability (importBundleCommit) — the import latch/receipt transaction requires it, and an unlatched import would serve entries before their governance lands; nothing was imported.");
+            e.code = "memory.import_rejected";
+            throw e;
+        }
+        const bundleHash = computeMemoryBundleHash(b.integrity.sectionHashes);
+        const custody = [];
+        const seenEv = new Set();
+        for (const row of b.governance.custody) {
+            if (seenEv.has(row.ev))
+                continue;
+            seenEv.add(row.ev);
+            custody.push(row);
+        }
+        const plan = {
+            bundleHash,
+            sourceStoreId: b.storeId,
+            entries: b.entries,
+            challenges: b.governance.challenges,
+            pollutedSessions: b.governance.pollutedSessions,
+            lineage: b.governance.lineage,
+            custody,
+        };
+        return face.call(this.backend, plan);
+    }
     challengeSession(sessionId, reason, requestId) {
         if (typeof requestId !== "string" || requestId === "") {
             const e = new Error("challengeSession: requestId is required (idempotency identity — retries must reuse it; the engine does not mint one)");
@@ -822,7 +922,9 @@ export class MemoryEngine {
             const rec = reconcileLineage(this.controlDir, this.now);
             this.settlePromotions(rec.promoted);
             for (const u of rec.undecidable) {
-                report.warnings.push(`memory lineage transaction ${u.txnId} is unsettled (a crash landed between commit and its durable credential) — ${u.entryIds.length} entr${u.entryIds.length === 1 ? "y is" : "ies are"} latched (memory reads refuse them) until the host adjudicates it (adjudicatePendingLineage)`);
+                report.warnings.push(u.kind === "latch-only"
+                    ? `memory bundle-import latch ${u.txnId} is unsettled (an import did not run to completion) — ${u.entryIds.length} entr${u.entryIds.length === 1 ? "y is" : "ies are"} latched (memory reads refuse them) until the SAME bundle is imported again to completion (importMemoryBundle; adjudication is refused on import latches)`
+                    : `memory lineage transaction ${u.txnId} is unsettled (a crash landed between commit and its durable credential) — ${u.entryIds.length} entr${u.entryIds.length === 1 ? "y is" : "ies are"} latched (memory reads refuse them) until the host adjudicates it (adjudicatePendingLineage)`);
             }
             if (pollutedReason !== undefined && lineageSessionId !== undefined) {
                 const rec2 = this.sessionPollution(lineageSessionId);

package/dist/core/memory-engine/export-bundle.d.ts

@@ -0,0 +1,192 @@
+import { type TransferEvidence } from "./file-backend.js";
+import type { MemoryEntry } from "./types.js";
+/** One exported challenge event (unresolved generations only). Generations are DESTINATION-minted:
+ *  the bundle deliberately carries no generation number — the importing store re-mints events under
+ *  its own idempotent namespace and allocates generations there. */
+export interface BundleChallengeRow {
+    eventId: string;
+    entryId: string;
+    reason: string;
+    at: number;
+    challengedRev?: string;
+}
+/** One exported durable pollution marker (verbatim source record). */
+export interface BundlePollutedSession {
+    sessionId: string;
+    at: number;
+    reason: string;
+}
+/** One exported committed lineage contribution (verbatim `lastRev`/`lastAt`). */
+export interface BundleLineageRow {
+    entryId: string;
+    sessionId: string;
+    lastRev: string;
+    lastAt: number;
+}
+/**
+ * design/178 v2 §4.3 + v2-c §6 — the governance-complete export bundle. The governance section is
+ * STRUCTURALLY REQUIRED (a bundle without it is a bad package — there is no "entries-only import"
+ * escape hatch: an optional hatch is a laundering channel, and the fixed section-hash key set makes
+ * a stripped section fail integrity outright). `doc` is human-readable disclosure text OUTSIDE the
+ * hashed sections (documentation, not governance data); unknown root keys are read-tolerated and
+ * never re-export-preserved (a re-export always mints a fresh bundle from store state).
+ */
+export interface MemoryExportBundle {
+    /** Envelope version — a reader meeting `bundle > 1` must refuse, never reinterpret. */
+    bundle: 1;
+    at: number;
+    scopes: string[];
+    /** The source store's durable identity (control-plane `store-identity.json`, minted at the first
+     *  export) — the import side's `origin` stamp for custody rows that carry none. */
+    storeId: string;
+    /** Full-fidelity entries (provenance/trust/extra verbatim). A duplicate id is a bad package. */
+    entries: MemoryEntry[];
+    governance: {
+        challenges: BundleChallengeRow[];
+        pollutedSessions: BundlePollutedSession[];
+        lineage: BundleLineageRow[];
+        /** Evidence-chain rows sliced to the exported scopes (v2-c §2 table): open form — a consumer
+         *  tolerates unknown keys; unknown CHANNELS never leave the exporter (they refuse the export). */
+        custody: TransferEvidence[];
+    };
+    /** Honest enumeration of what the bundle does NOT carry. The `unbound`/`pendingLatch` name lists
+     *  are populated on a FULL-STORE export only (one trust domain); a subset export ships empty
+     *  lists and the counts (an id list would leak another tenant's identifiers). The counts are
+     *  always present and always equal the honest total, so a consumer reads ONE seat either way. */
+    residuals: {
+        quarantined: string[];
+        unbound: string[];
+        pendingLatch: string[];
+        contentUnavailable: Array<{
+            id: string;
+            scope: string;
+            slug: string;
+            rev: string;
+            reason: string;
+        }>;
+        quarantineOpaque: number;
+        /** Custody rows a SUBSET export could not slice (no scope to slice by — unbound-deletion
+         *  history among them): the anti-resurrection guarantee for those ids does not travel. */
+        unsliceableCustody: number;
+        unboundCount: number;
+        pendingLatchCount: number;
+    };
+    /** Accident detection, not forgery-proofing (see module note). `sectionHashes` carries EXACTLY
+     *  the four fixed keys (meta/entries/governance/residuals); `revs` and `entries` are mutually
+     *  pointing (same id set, verbatim revs, `entryCount` ≡ both cardinalities). */
+    integrity: {
+        entryCount: number;
+        revs: Record<string, string>;
+        sectionHashes: Record<string, string>;
+    };
+    /** Human-readable disclosure sentences (free-string carriage, subset residuals). Outside the
+     *  hashed sections by design — documentation, not governance data. */
+    doc: string[];
+}
+/** design/178 v2-c §7 — the import answer (the parent-design draft fields plus the v2-c report
+ *  seats). Every negative disposition is REPORTED, never silent. */
+export interface MemoryImportReport {
+    v: 1;
+    /** The bundle identity (sha256 over the canonical section-hash map) — the latch/remint salt. */
+    bundleHash: string;
+    sourceStoreId: string;
+    landed: Array<{
+        id: string;
+        scope: string;
+        slug: string;
+    }>;
+    /** id+rev+scope three-way idempotent skips (slug tolerates the deterministic `-n` suffix). */
+    alreadyPresent: string[];
+    /** The destination chain carries a delete row for the id and no live row survives — resurrection
+     *  refused (no override; a legitimately re-created id has a live row and takes the ordinary
+     *  CAS/conflict path instead). */
+    refusedErased: string[];
+    /** Fresh add of a `repo_file`-provenance entry with no `trust` marker — whitewash refused. */
+    refusedUntrusted: string[];
+    conflicts: Array<{
+        id: string;
+        reason: string;
+    }>;
+    /** Entry-attached governance (challenges/lineage) withheld because its entry neither landed nor
+     *  matched already-present-at-the-same-rev — misattribution is worse than omission. */
+    governanceWithheld: string[];
+    /** Source chain carries a delete row while the destination holds a LIVE entry for the id: named
+     *  for deployment adjudication, never deleted on the import's behalf. */
+    erasedAtSource: string[];
+    pollutionDivergence: Array<{
+        sessionId: string;
+        kept: "destination";
+    }>;
+    /** Governance rows pointing at ids outside entries ∪ the destination account (custody rows are
+     *  exempt — an absent-id delete row is exactly the anti-resurrection payload). */
+    referentialOrphans: string[];
+    lineageDivergence: Array<{
+        entryId: string;
+        sessionId: string;
+        kept: "destination";
+    }>;
+    /** Custody rows withheld unappended: unknown channel, or a known-channel row failing the store's
+     *  own validation — reported per row, never a whole-package refusal (a newer exporter must not
+     *  brick an older importer) and never a verbatim append (an unvalidatable row would poison the
+     *  fail-closed chain). `srcEv` is the row's source identity (its own `srcEv` when it carries one,
+     *  else its `ev`). */
+    custodyWithheld: Array<{
+        srcEv: string;
+        channel: string;
+    }>;
+    /** Custody rows submitted to the destination chain under this bundle's namespace (idempotent
+     *  re-imports answer the same number — the reconciliation handle). */
+    custodyAppended: number;
+}
+/** What the engine hands the File backend's `importBundleCommit` face after the pure validation
+ *  pass: the bundle's governed content plus its computed identity. Everything here is inert plain
+ *  data (the engine clones the caller's bundle through a JSON round-trip before validating). */
+export interface MemoryBundleImportPlan {
+    bundleHash: string;
+    sourceStoreId: string;
+    entries: MemoryEntry[];
+    challenges: BundleChallengeRow[];
+    pollutedSessions: BundlePollutedSession[];
+    lineage: BundleLineageRow[];
+    /** Open custody rows (byte-equal duplicates already collapsed by validation). */
+    custody: Array<Record<string, unknown>>;
+}
+/** The four fixed integrity section keys (§6.3) — missing OR extra keys are a bad package. */
+export declare const BUNDLE_SECTION_KEYS: readonly ["meta", "entries", "governance", "residuals"];
+/** The canonical per-section hashes of a bundle's four sections (meta = the bundle/at/scopes/
+ *  storeId scalars). Canonical JSON (recursively sorted keys) + LF, sha256 hex. */
+export declare function computeBundleSectionHashes(bundle: Pick<MemoryExportBundle, "bundle" | "at" | "scopes" | "storeId" | "entries" | "governance" | "residuals">): Record<string, string>;
+/**
+ * The bundle IDENTITY: sha256 over the canonical JSON of `integrity.sectionHashes` (full 64-hex —
+ * the import latch id, the challenge/custody remint salt, and the report echo all share it). The
+ * section hashes already seal the section contents, so their sorted map IS the package identity;
+ * a tampered package fails integrity before its hash ever matters.
+ */
+export declare function computeMemoryBundleHash(sectionHashes: Record<string, string>): string;
+/**
+ * design/178 v2-c §1-2① — the PURE bundle validation (integrity/structure/self-consistency; zero
+ * store reads, zero side effects). Returns the FIRST violation, or undefined (valid). Every
+ * violation is a whole-package refusal at the caller — nothing lands, no latch is set.
+ */
+export declare function memoryBundleInvalid(raw: unknown, opts?: {
+    expectedScopes?: readonly string[];
+}): string | undefined;
+/** What the exporter feeds {@link assembleMemoryExportBundle} — the store-consistent snapshot plus
+ *  the already-sliced governance pieces (pure data; the snapshot fence lives in the backend). */
+export interface MemoryExportBundleInput {
+    at: number;
+    scopes: string[];
+    storeId: string;
+    entries: MemoryEntry[];
+    challenges: BundleChallengeRow[];
+    pollutedSessions: BundlePollutedSession[];
+    lineage: BundleLineageRow[];
+    custody: TransferEvidence[];
+    residuals: MemoryExportBundle["residuals"];
+}
+/** The C-1 disclosure sentence (recommended-arm ruling posture: free strings ride verbatim and the
+ *  bundle SAYS so — coding them away would destroy the identity/attribution keys idempotency and
+ *  the remint namespaces depend on). */
+export declare 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.";
+/** Assemble the bundle: deterministic ordering, section hashes, disclosure doc. Pure. */
+export declare function assembleMemoryExportBundle(input: MemoryExportBundleInput): MemoryExportBundle;