@volter/world-core 2.0.0

package/dist/src/changeset.d.ts

@@ -0,0 +1,431 @@
+import { type HistoryReference } from './history.js';
+import type { TwinActionRevertSpec } from './actions.js';
+import type { TwinAction, TwinActionPrecondition } from './actions.js';
+/** One twin's action ledger, addressed the way the control plane addresses state:
+ *  `worldPaths(stateService, controlRoot)`. `service` is the caller's label for it (in a world:
+ *  the world service id); `stateService` is the control-plane service whose ledger this is.
+ *  They differ whenever a twin records under a different state name than its world service id. */
+export type LedgerRef = {
+    /** the vendor/twin as the operator names it — what `diff` groups by and `replay` matches on */
+    service: string;
+    /** the control-plane state service whose `actions.jsonl` this is (often === service) */
+    stateService: string;
+    /** control root such that `worldPaths(stateService, controlRoot)` resolves the ledger */
+    controlRoot: string;
+};
+/** One ledger's recorded position inside a marker. `count` is the row count at capture;
+ *  `lastActionId` is the verification anchor (see the marker note above). */
+export type LedgerPosition = {
+    service: string;
+    stateService: string;
+    count: number;
+    lastActionId: string | null;
+};
+export declare const MARKER_KIND = "volter.world.marker.v1";
+export declare const CHANGESET_KIND = "volter.world.changeset.v1";
+/** The base position a diff or changeset is taken against. */
+export type WorldMarker = {
+    kind: typeof MARKER_KIND;
+    id: string;
+    world: string;
+    createdAt: string;
+    /** Every ledger that existed at capture time. A ledger absent here is treated as position 0
+     *  (a twin that recorded its first action AFTER the mark contributes its whole ledger). */
+    ledgers: LedgerPosition[];
+};
+/** The id reserved for the synthetic "everything this world has ever recorded" base. */
+export declare const WORLD_BOOT_MARKER_ID = "world-boot";
+/** An action inside a delta/changeset, bound to the twin whose ledger recorded it. The raw
+ *  `TwinAction` is kept verbatim (provenance); `service`/`stateService` are the binding replay
+ *  needs to route it into the right twin of another world. */
+export type ChangesetAction = {
+    service: string;
+    stateService: string;
+    action: TwinAction;
+};
+/** Per-vendor rollup of a delta, in first-occurrence order — the shape `diff` renders. */
+export type VendorSummary = {
+    service: string;
+    count: number;
+    operations: Array<{
+        operation: string;
+        count: number;
+        subjectIds: string[];
+    }>;
+};
+export type LedgerDelta = {
+    world: string;
+    base: WorldMarker;
+    /** every action after `base`, across every ledger, ordered by `occurredAt` */
+    actions: ChangesetAction[];
+    vendors: VendorSummary[];
+    total: number;
+};
+/** A verifier: one deterministic check against post-replay projected state — the CI assertion
+ *  of the operational PR (docs/concepts/the-model.md v1). The `assert` is the kernel's ONE check
+ *  expression (`TwinActionPrecondition`: subject/field/op/value, evaluated by
+ *  `checkPrecondition`), the same shape write-time preconditions and plan conflicts already
+ *  use — a verifier is that check pointed at a replay target instead of the authoring world. */
+export type ChangesetVerifier = {
+    /** caller-chosen handle, unique within the changeset (results key on it) */
+    id: string;
+    /** the world service (twin) whose post-replay state the assert reads */
+    service: string;
+    assert: TwinActionPrecondition;
+};
+/** One verifier's outcome against a replay target. `assert` is repeated verbatim so the result
+ *  is readable on its own; `actual` is what the projected state held (omitted when undefined —
+ *  which is itself what `exists`/`not_exists` distinguish). */
+export type ChangesetVerifierResult = {
+    id: string;
+    service: string;
+    assert: TwinActionPrecondition;
+    passed: boolean;
+    actual?: unknown;
+};
+/** The recorded outcome of `changeset verify` — ABOUT-the-body metadata, like approvals: it
+ *  lives on the object but is outside `contentHash`, and each verify REPLACES the previous
+ *  record (the provenance fields say exactly which run this is). */
+export type ChangesetVerification = {
+    at: string;
+    /** where the replay landed — a world name, or 'ephemeral' for a throwaway target */
+    into: string;
+    /** the body hash at verification time; a later body edit makes this visibly stale */
+    contentHash: string;
+    /** sha256 over the post-replay projected state of every replay target — two verifies that
+     *  produced the same world state produce the same digest (the determinism receipt) */
+    worldDigest: string;
+    passed: boolean;
+    results: ChangesetVerifierResult[];
+    /** the world's checks (state-system.ts) that refused an entry — CI on deployment, run at verify */
+    refusals?: Array<{
+        actionId: string;
+        service: string;
+        check: string;
+        reason: string;
+    }>;
+};
+/** One signature: who approved, when, against exactly which body hash. The hash-at-signing is
+ *  the point — an approval is meaningless without the bytes it bound to. */
+export type ChangesetApproval = {
+    principal: string;
+    at: string;
+    contentHash: string;
+    note?: string;
+};
+export type Changeset = {
+    kind: typeof CHANGESET_KIND;
+    id: string;
+    name: string;
+    /** the world it was authored in */
+    world: string;
+    /** the marker id it forked from */
+    base: string;
+    createdAt: string;
+    actions: ChangesetAction[];
+    /** deterministic checks that must pass on replay — part of the hashed body when present,
+     *  so an approval also binds to WHAT was checked, not just what was done */
+    verifiers: ChangesetVerifier[];
+    /** latest verify run (replaced, never accumulated) — outside the hash, like approvals */
+    verification: ChangesetVerification | null;
+    /** who signed, against `contentHash` */
+    approvals: ChangesetApproval[];
+    /** the governed push's outcome (v2) — receipts and, on a partial apply, the compensation report; null until applied */
+    applied: ChangesetApplication | null;
+    /** v4 — the CHECKABLE NARRATION: the human summary rendered deterministically from `actions`
+     *  at authoring (`narrateActions`). Outside the hash — it is DERIVED from the hashed actions, so
+     *  an approval already binds to it — and re-rendered on every read: a hand-edited narration no
+     *  longer equals its re-render, and the object is neither approvable nor applicable until
+     *  re-authored. Absent on objects authored before v4. */
+    narration?: string;
+    /** The author's own words for the changeset (git's commit message) — what `volter changeset -m`
+     *  records. Outside the hash, like the narration; a reviewer reads both. */
+    message?: string;
+    /** v3 — set by `rebaseChangeset`: the hash this object was rebased from, and when. Outside the hash. */
+    rebasedFrom?: {
+        contentHash: string;
+        at: string;
+    };
+    /** PROTOCOL 2 — where the parent log stood when this was cut, per state service (its entry count):
+     *  a rebase reads the parent's entries since here to name what moved under the changeset. Outside
+     *  the hash (metadata of the cut, not of the change). */
+    cut?: Record<string, HistoryReference>;
+    /** sha256 over the canonical JSON of `{id, world, base, actions}` (+ `verifiers` when any) */
+    contentHash: string;
+};
+export declare function assertSafeChangesetName(name: string, what?: string): string;
+/** The "everything ever recorded in this world" base: zero ledgers, so every ledger diffs from
+ *  position 0. Used when a world has no marks yet — `diff` must still answer, not refuse. */
+export declare function worldBootMarker(world: string, createdAt: string): WorldMarker;
+/** Capture the current position of every ledger — the cross-service base marker. */
+export declare function captureMarker(opts: {
+    id: string;
+    world: string;
+    ledgers: LedgerRef[];
+    createdAt?: string;
+}): WorldMarker;
+/** A marker taken in world A says nothing about world B's ledgers — comparing them would
+ *  produce a confident, wrong delta. Refuse. */
+export declare function assertMarkerBelongsTo(marker: WorldMarker, world: string): void;
+/**
+ * Every action appended after `base`, across `ledgers`, in `occurredAt` order.
+ *
+ * A ledger is verified against its recorded position before any of it is reported: fewer rows
+ * than the marker counted, or a different action id at that position, means the ledger was
+ * rewritten (scrub/purge/rebuild) and the marker no longer addresses anything real. That is a
+ * loud error — quietly re-basing on a rewritten ledger is how a diff lies.
+ */
+export declare function diffLedgers(opts: {
+    world: string;
+    ledgers: LedgerRef[];
+    base: WorldMarker;
+}): LedgerDelta;
+/** Group a delta by vendor, then by operation — both in FIRST-OCCURRENCE order, so the rollup
+ *  reads in the same causal order as the actions themselves. */
+export declare function summarizeByVendor(actions: ChangesetAction[]): VendorSummary[];
+/** The human rendering of a delta — one line per vendor plus a total. Shared by `diff` and
+ *  `changeset show` so a frozen changeset reads exactly like the diff it was cut from. */
+export declare function formatLedgerDelta(delta: LedgerDelta, opts?: {
+    title?: string;
+}): string;
+/** What `changesetContentHash` needs to see — the immutable fields, with `verifiers` optional
+ *  so a v0 object (authored before verifiers existed) hashes exactly as it always did. */
+export type ChangesetHashable = Pick<Changeset, 'id' | 'world' | 'base' | 'actions'> & Partial<Pick<Changeset, 'verifiers' | 'cut'>>;
+export declare function changesetContentHash(changeset: ChangesetHashable): string;
+/** A verifier that cannot be evaluated deterministically is refused at authoring time, not
+ *  discovered at verify time. */
+export declare function assertValidVerifiers(verifiers: ChangesetVerifier[]): ChangesetVerifier[];
+/**
+ * Parse the CLI spelling of a verifier: `<service> <type>:<id> <field> <op> [<value>]`, e.g.
+ * `stripe price:price_annual unit_amount eq 47000`. The value is JSON when it parses as JSON
+ * (numbers, booleans, quoted strings) and a bare string otherwise, so `eq active` and
+ * `eq "active"` mean the same thing.
+ */
+export declare function parseVerifierExpression(expression: string, id: string): ChangesetVerifier;
+/** Freeze a delta into a named, content-addressed changeset. */
+export declare function buildChangeset(opts: {
+    name: string;
+    world: string;
+    base: string;
+    actions: ChangesetAction[];
+    verifiers?: ChangesetVerifier[];
+    createdAt?: string;
+    message?: string;
+    cut?: Record<string, HistoryReference>;
+}): Changeset;
+/** Fill the lifecycle fields a changeset authored before v1 lacks on disk, without touching
+ *  its hash (absent and empty `verifiers` hash identically by construction). */
+export declare function normalizeChangeset(changeset: Changeset): Changeset;
+/** Recompute and compare — a changeset whose bytes were edited after authoring is not the
+ *  object anyone approved. Callers render this as a warning or a hard failure as suits. */
+export declare function changesetHashMatches(changeset: Changeset): boolean;
+/** Render a changeset exactly like the diff it was cut from. */
+export declare function formatChangeset(changeset: Changeset): string;
+export type ReplayTarget = {
+    /** the changeset service this target satisfies */
+    service: string;
+    /** the state service to write into (may differ from the source's) */
+    stateService: string;
+    controlRoot: string;
+};
+export type ReplayActionResult = {
+    service: string;
+    sourceActionId: string;
+    /** the action id in the TARGET ledger — identical to `sourceActionId` whenever the target
+     *  state service matches the source's, which is what makes replay verifiable */
+    actionId: string;
+    /** 'write' = through `applyTwinWrite` (the kernel write path); 'append' = recorded verbatim */
+    via: 'write' | 'append';
+    status: 'performed' | 'replayed';
+};
+export type ReplayReport = {
+    changeset: string;
+    contentHash: string;
+    /** the authoring world */
+    world: string;
+    into: string;
+    total: number;
+    performed: number;
+    replayed: number;
+    services: string[];
+    actions: ReplayActionResult[];
+};
+/**
+ * Recover the `uniqueness` value `applyTwinWrite` folded into an action id, or report that the
+ * id is not twin-write-shaped at all (a hand-written or pack-appended action).
+ *
+ * The id format is `twin:<service>:<operation>:<subjectId>:<occurredAt>:<contentHash>[:<uniqueness>]`
+ * and both `operation` and `subjectId` may themselves contain ':', so the id cannot be split
+ * field-wise. A repeated write additionally carries an occurrence ordinal (`…#1`), stripped below. Instead the deterministic prefix is REBUILT from the action's own recorded parts —
+ * if it matches, whatever follows is exactly the uniqueness seam. Getting this right is what
+ * keeps billable occurrences (two identical AI completions in one millisecond) from collapsing
+ * into one action on replay.
+ */
+export declare function twinWriteShape(action: TwinAction): {
+    uniqueness?: string;
+} | null;
+/**
+ * Replay a changeset's actions, in order, into `targets`.
+ *
+ * Two paths, and the split is about EXPRESSIVENESS, not preference:
+ *   - `write`  — the default and the point: back through `applyTwinWrite`, the same kernel entry
+ *     an SDK call lands on. The target re-derives the action id from content, so it matches the
+ *     source id and a second replay is a total no-op.
+ *   - `append` — the honest fallback for actions the write path cannot express: multi-resource
+ *     `projection` transactions (applyTwinWrite carries only flat `fields`, so routing them
+ *     through it would silently DROP the creates/deletes/emits) and `revert`/`confirm`
+ *     bookkeeping rows. These are appended verbatim under `appendActionIfAbsent`, which is
+ *     id-keyed — so they are idempotent on re-replay too.
+ *
+ * `preconditions` are deliberately NOT replayed. They were evaluated against the authoring
+ * world's state at author time; re-evaluating them against a different base would fail replays
+ * that are perfectly valid recordings. Verifying a changeset against a target's state is v1's
+ * job (verifiers), not a silent side effect of replay. Dropping them cannot change any action
+ * id — preconditions are not part of the content hash.
+ */
+export declare function replayChangeset(changeset: Changeset, opts: {
+    into: string;
+    targets: ReplayTarget[];
+    available?: string[];
+}): Promise<ReplayReport>;
+export declare function formatReplayReport(report: ReplayReport): string;
+/**
+ * Run a changeset's verifiers against post-replay state. Deterministic on purpose: each assert
+ * reads the target's PROJECTED state (`projectResources` — the same projection the kernel's
+ * preconditions and plan conflicts read) and is evaluated by `checkPrecondition` — the same
+ * evaluator, so a verifier means exactly what a precondition means. The `worldDigest` is a
+ * receipt over everything the verifiers could have seen: two runs that produced the same
+ * post-replay state produce the same digest.
+ *
+ * `targets` are the same references replay wrote through — a verifier is only honest against
+ * the ledgers the replay actually landed in. A verifier naming a service with no target is a
+ * loud error (there is nothing real to check it against), never a silent pass.
+ */
+export declare function runChangesetVerifiers(changeset: Changeset, targets: ReplayTarget[], opts: {
+    at: string;
+    into: string;
+}): ChangesetVerification;
+/** Record `verification` on the object — REPLACING any prior run (the provenance fields carry
+ *  which run this is), never touching the hash the body is addressed by. */
+export declare function withVerification(changeset: Changeset, verification: ChangesetVerification): Changeset;
+/**
+ * Append an approval bound to the changeset's CURRENT body hash. Refuses when the stored
+ * `contentHash` no longer matches the body: an object whose bytes moved after authoring is not
+ * the object anyone reviewed, and signing it would launder the drift. Loud, never silent.
+ */
+export declare function approveChangeset(changeset: Changeset, opts: {
+    principal: string;
+    at?: string;
+    note?: string;
+}): {
+    changeset: Changeset;
+    approval: ChangesetApproval;
+};
+/** Everything `changeset status` reports — recomputed from the object, never trusted off
+ *  stored booleans (the same rule `planRequiresApproval` follows). */
+export type ChangesetReadiness = {
+    name: string;
+    world: string;
+    contentHash: string;
+    /** stored hash matches the body */
+    hashOk: boolean;
+    /** a verification exists, binds to the current hash, and every verifier passed */
+    verified: boolean;
+    verification: ChangesetVerification | null;
+    /** every approval on the object */
+    approvals: number;
+    /** approvals whose hash-at-signing is the current body hash — the only ones that count */
+    bindingApprovals: number;
+    ready: boolean;
+    /** empty exactly when ready */
+    reasons: string[];
+};
+export declare function changesetReadiness(changeset: Changeset): ChangesetReadiness;
+/** The single honest line `changeset status` prints. No push here — v2's job; this line only
+ *  tells the truth about the object. */
+export declare function formatChangesetStatus(readiness: ChangesetReadiness): string;
+/** The verify verb's report — the verification plus the replay that produced it. */
+export declare function formatVerification(name: string, verification: ChangesetVerification, report: ReplayReport): string;
+/** The object with its application recorded — `applied` is outside the hash. */
+export declare function withApplication(changeset: Changeset, application: ChangesetApplication): Changeset;
+export declare function formatApplication(name: string, application: ChangesetApplication): string;
+/** One deterministic paragraph per twin, one sentence per operation, in first-occurrence order. */
+export declare function narrateActions(actions: ChangesetAction[]): string;
+/** The recorded narration against its re-render — null when they agree or when the object carries none. */
+export declare function narrationDrift(changeset: Pick<Changeset, 'actions'> & Partial<Pick<Changeset, 'narration'>>): {
+    recorded: string;
+    expected: string;
+} | null;
+export type ApplyReceipt = {
+    actionId: string;
+    service: string;
+    stateService: string;
+    status: 'confirmed' | 'replayed' | 'failed' | 'skipped';
+    pushId?: string;
+    externalId?: string;
+    url?: string;
+    error?: string;
+};
+export type CompensationEntry = {
+    service: string;
+    actionId: string;
+    subject: {
+        type: string;
+        id: string;
+    };
+    externalId?: string;
+    /** the action's own revert spec when it carries one, else the inverse on the vendor id */
+    revert: TwinActionRevertSpec | {
+        strategy: 'inverse';
+    };
+};
+/** How a push went: the receipts origin answered, recorded on the changeset object. */
+export type ChangesetApplication = {
+    at: string;
+    contentHash: string;
+    outcome: 'applied' | 'partial' | 'refused';
+    forced?: boolean;
+    refusal?: string[];
+    receipts: ApplyReceipt[];
+    compensation: CompensationEntry[];
+};
+export type RebaseTarget = {
+    service: string;
+    stateService: string;
+    controlRoot: string;
+};
+export type RebaseActionResult = {
+    actionId: string;
+    service: string;
+    status: 'unchanged' | 'rebased' | 'rebased-blind' | 'conflict';
+    moved?: Record<string, {
+        base: string | null;
+        current: string | null;
+    }>;
+    conflicts?: Array<{
+        subject: {
+            type: string;
+            id: string;
+        };
+        field: string;
+        op: string;
+        expected?: unknown;
+        actual: unknown;
+    }>;
+};
+export type RebaseReport = {
+    changeset: string;
+    from: string;
+    to: string | null;
+    at: string;
+    outcome: 'unchanged' | 'rebased' | 'conflict';
+    actions: RebaseActionResult[];
+};
+export declare function rebaseChangeset(changeset: Changeset, opts: {
+    targets: RebaseTarget[];
+    at?: string;
+}): {
+    changeset: Changeset;
+    report: RebaseReport;
+};
+export declare function formatRebaseReport(report: RebaseReport): string;

package/dist/src/client-bundle.d.ts

@@ -0,0 +1 @@
+export declare function bundleClient(entry: string): Promise<string>;

package/dist/src/client-bundle.js

@@ -0,0 +1,28 @@
+// A mirror's browser client from its `client/<name>.tsx` entry, runtime-neutral (the serve seam's helpers,
+// docs/contributing/architecture.md#the-serve-seam): under Bun the same `Bun.build` every mirror ran at
+// serve time; under Node the PREBUILT `<name>.bundle.js` beside the entry, written at pack time
+// by scripts/publish/build.mjs into dist/client/. Built once per process and kept; a failed build
+// is retried on the next call. Nothing here runs at module scope.
+import { existsSync, readFileSync } from 'node:fs';
+const bundles = new Map();
+export function bundleClient(entry) {
+    let pending = bundles.get(entry);
+    if (!pending) {
+        const bun = globalThis.Bun;
+        pending = (bun && typeof bun.build === 'function'
+            ? bun.build({ entrypoints: [entry], target: 'browser', minify: true }).then(async (result) => {
+                if (!result.success)
+                    throw new Error(result.logs.map((l) => l.message).join('\n') || `client build failed: ${entry}`);
+                return result.outputs[0].text();
+            })
+            : Promise.resolve().then(() => {
+                const prebuilt = entry.replace(/\.tsx?$/, '.bundle.js');
+                if (!existsSync(prebuilt))
+                    throw new Error(`client bundle missing at ${prebuilt} — the package's \`build\` writes it (scripts/publish/build.mjs); Node serves the prebuilt client`);
+                return readFileSync(prebuilt, 'utf8');
+            }))
+            .catch((error) => { bundles.delete(entry); throw error; });
+        bundles.set(entry, pending);
+    }
+    return pending;
+}

package/dist/src/credential.d.ts

@@ -0,0 +1,38 @@
+export type CredentialPayload = {
+    headers: Record<string, string>;
+    secret?: string;
+    keyId?: string;
+} & Record<string, unknown>;
+/** The at-rest form. All byte fields base64. The fingerprint is a short SHA-256 prefix
+ *  of the payload — enough for an operator to recognize "the key ending a1b2…", never
+ *  enough to recover anything. */
+export type SealedCredential = {
+    v: 1;
+    dekIv: string;
+    wrappedDek: string;
+    iv: string;
+    ciphertext: string;
+    placedAt: string;
+    fingerprint: string;
+    /** when a vendor last rotated a field of it (an OAuth refresh token): placedAt and fingerprint stay the credential's
+     *  identity across rotations, the ledgers keyed by the fingerprint with them */
+    rotatedAt?: string;
+};
+export interface CredentialStorage {
+    getSealed(namespace: string, vendor: string): Promise<SealedCredential | null>;
+    putSealed(namespace: string, vendor: string, sealed: SealedCredential): Promise<void>;
+    deleteSealed(namespace: string, vendor: string): Promise<void>;
+    /** Purge every vendor's sealed record for the namespace — the lifecycle DELETE calls
+     *  this: a deleted namespace's credentials must not survive to be inherited by
+     *  whoever re-provisions the name (review B1: the resurrection theft chain). */
+    deleteNamespace(namespace: string): Promise<void>;
+}
+export declare class MemoryCredentialStorage implements CredentialStorage {
+    readonly records: Map<string, SealedCredential>;
+    getSealed(namespace: string, vendor: string): Promise<SealedCredential | null>;
+    putSealed(namespace: string, vendor: string, sealed: SealedCredential): Promise<void>;
+    deleteSealed(namespace: string, vendor: string): Promise<void>;
+    deleteNamespace(namespace: string): Promise<void>;
+}
+export declare function sealCredential(kekSecret: string, payload: CredentialPayload, placedAt: string, slot?: string): Promise<SealedCredential>;
+export declare function openSealedCredential(kekSecret: string, sealed: SealedCredential, slot?: string): Promise<CredentialPayload>;

package/dist/src/credential.js

@@ -0,0 +1,114 @@
+// THE SEALED CREDENTIAL STORE (docs/concepts/the-model.md, rule 5; custody ruled 2026-09-01:
+// lives in core since v2 — a world that wraps reality seals its credential beside itself, and the
+// kernel executor is the only reader). Originally the twins host's; the host re-exports it.
+// cloud-side, idiomatic — like any web service). Real vendor credentials are:
+//   • WRITE-ONLY through the API: placement and deletion are the tenant's act; reads
+//     return metadata (placedAt, a fingerprint) and NEVER the secret — there is no
+//     read-back door, and none may ever be added.
+//   • ENVELOPE-ENCRYPTED: each credential gets its own random 256-bit DEK (AES-GCM);
+//     the DEK is wrapped by the deployment KEK, which lives in the platform's secret
+//     store (wrangler secret TWINS_CRED_KEK) and never in any bucket. KEK rotation is
+//     a re-wrap of DEKs, not a re-encryption of payloads.
+//   • OUTSIDE every namespace tree (beside keys and links, under '-/creds/'), so no
+//     flush, snapshot, or door can ever carry one.
+//   • CONSUMED only by the remote backing arm and the sync plane, through
+//     `openSealedCredential` — an in-process seam, never an HTTP surface.
+//
+// The payload is a JSON object; the convention the forward arm consumes is
+// `{ headers: { authorization: "Bearer …", … } }` — credential APPLICATION is a value
+// (which headers), never a per-vendor mechanism. WebCrypto only: workerd-clean.
+//
+// `secret` is the RAW material for the strategies that cannot be expressed as a header: a vendor
+// that reads its key from a query parameter, or one that wants a signature computed per request
+// (docs/concepts/the-model.md#the-rules, rule 5, "applies the credential by strategy"). It is optional and unread unless
+// the pack declares such a strategy, so a header-authenticated vendor seals exactly what it sealed
+// before. It is never logged and never enters pack code — the executor is the only reader.
+export class MemoryCredentialStorage {
+    records = new Map();
+    async getSealed(namespace, vendor) {
+        return this.records.get(`${namespace}/${vendor}`) ?? null;
+    }
+    async putSealed(namespace, vendor, sealed) {
+        this.records.set(`${namespace}/${vendor}`, sealed);
+    }
+    async deleteSealed(namespace, vendor) {
+        this.records.delete(`${namespace}/${vendor}`);
+    }
+    async deleteNamespace(namespace) {
+        for (const key of [...this.records.keys()])
+            if (key.startsWith(`${namespace}/`))
+                this.records.delete(key);
+    }
+}
+const toB64 = (bytes) => {
+    // Chunked (review B3): a spread of the whole payload blows the arg-count stack well
+    // below the 4 MB body cap (verified ~1 MB on Bun, tens of KB on V8).
+    let bin = '';
+    for (let i = 0; i < bytes.length; i += 0x1000)
+        bin += String.fromCharCode(...bytes.subarray(i, i + 0x1000));
+    return btoa(bin);
+};
+const fromB64 = (b64) => {
+    const bin = atob(b64);
+    const bytes = new Uint8Array(new ArrayBuffer(bin.length));
+    for (let i = 0; i < bin.length; i += 1)
+        bytes[i] = bin.charCodeAt(i);
+    return bytes;
+};
+/** The KEK secret string (any length ≥ 16) normalizes to 32 key bytes via SHA-256 —
+ *  operators paste one strong secret; the digest is the AES key material. */
+async function importKek(secret) {
+    // ≥32 chars (review M3): SHA-256 with no stretching is fine for MACHINE secrets
+    // (`openssl rand -base64 32`) and hopeless against a short human passphrase — the
+    // floor forces the former.
+    if (secret.length < 32)
+        throw new Error('credential KEK must be at least 32 characters (generate with: openssl rand -base64 32)');
+    const material = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(secret));
+    return await crypto.subtle.importKey('raw', material, { name: 'AES-GCM' }, false, ['encrypt', 'decrypt']);
+}
+export async function sealCredential(kekSecret, payload, placedAt, slot = '') {
+    const kek = await importKek(kekSecret);
+    const plaintext = new TextEncoder().encode(JSON.stringify(payload));
+    const dekBytes = crypto.getRandomValues(new Uint8Array(32));
+    const dek = await crypto.subtle.importKey('raw', dekBytes, { name: 'AES-GCM' }, false, ['encrypt']);
+    const iv = crypto.getRandomValues(new Uint8Array(12));
+    const dekIv = crypto.getRandomValues(new Uint8Array(12));
+    // The SLOT ('{namespace}/{vendor}') rides as AAD (audit L16): a sealed record
+    // transplanted to another slot by a bucket-level writer refuses to open there.
+    const aad = new TextEncoder().encode(slot);
+    const ciphertext = new Uint8Array(await crypto.subtle.encrypt({ name: 'AES-GCM', iv, additionalData: aad }, dek, plaintext));
+    const wrappedDek = new Uint8Array(await crypto.subtle.encrypt({ name: 'AES-GCM', iv: dekIv }, kek, dekBytes));
+    // KEYED fingerprint (review m1): an unsalted hash prefix is an offline oracle for
+    // low-entropy payloads; HMAC under KEK-derived material keeps the operator UX
+    // (recognizable short id) with no oracle.
+    const macMaterial = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(`fingerprint:${kekSecret}`));
+    const macKey = await crypto.subtle.importKey('raw', macMaterial, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const digest = new Uint8Array(await crypto.subtle.sign('HMAC', macKey, plaintext));
+    return {
+        v: 1,
+        dekIv: toB64(dekIv),
+        wrappedDek: toB64(wrappedDek),
+        iv: toB64(iv),
+        ciphertext: toB64(ciphertext),
+        placedAt,
+        fingerprint: [...digest.slice(0, 6)].map((b) => b.toString(16).padStart(2, '0')).join(''),
+    };
+}
+export async function openSealedCredential(kekSecret, sealed, slot = '') {
+    const kek = await importKek(kekSecret);
+    let dekBytes;
+    try {
+        dekBytes = await crypto.subtle.decrypt({ name: 'AES-GCM', iv: fromB64(sealed.dekIv) }, kek, fromB64(sealed.wrappedDek));
+    }
+    catch {
+        throw new Error('credential unseal failed: wrong KEK or corrupted record');
+    }
+    const dek = await crypto.subtle.importKey('raw', dekBytes, { name: 'AES-GCM' }, false, ['decrypt']);
+    try {
+        const plaintext = new Uint8Array(await crypto.subtle.decrypt({ name: 'AES-GCM', iv: fromB64(sealed.iv), additionalData: new TextEncoder().encode(slot) }, dek, fromB64(sealed.ciphertext)));
+        return JSON.parse(new TextDecoder().decode(plaintext));
+    }
+    catch {
+        throw new Error('credential unseal failed: wrong KEK or corrupted record');
+    }
+}