@aiwg/cli 2026.9.20 → 2026.9.21

package/dist/src/effects/keys.js

@@ -0,0 +1,130 @@
+/**
+ * The dedicated Ed25519 ledger signing key and its pluggable providers.
+ *
+ * The private key lives only inside a `LedgerSigningKey` private field. It has
+ * no accessor, and JSON serialization and inspection show the public key only,
+ * so it cannot reach records, errors or output by accident.
+ *
+ * Providers:
+ * - `credentialStoreKeyProvider`: the host secret service through the
+ *   configurable credential store (`src/auth/credential-store.ts`). This is the
+ *   production provider.
+ * - `environmentTestKeyProvider`: a key injected through
+ *   `AIWG_EFFECT_LEDGER_TEST_KEY`, honoured only under a test runner or CI.
+ * - `staticKeyProvider`: an in-process key object, for embedding hosts and tests.
+ */
+import { createPrivateKey, createPublicKey, generateKeyPairSync } from 'node:crypto';
+import { inspect } from 'node:util';
+import { createSecretStore } from '../auth/credential-store.js';
+import { signDsseEnvelope } from '../security/signing.js';
+import { EffectLedgerError } from './errors.js';
+import { sha256Digest } from './identity.js';
+const PKCS8_ED25519_PREFIX = Buffer.from('302e020100300506032b657004220420', 'hex');
+export const DEFAULT_LEDGER_KEY_SERVICE = 'effects.aiwg.io';
+export const LEDGER_TEST_KEY_ENV = 'AIWG_EFFECT_LEDGER_TEST_KEY';
+const keyUnavailable = (message = 'Effect ledger signing key is unavailable') => new EffectLedgerError('key-unavailable', message, 'key-unavailable');
+export class LedgerSigningKey {
+    keyid;
+    /** Standard base64 of the DER SubjectPublicKeyInfo. */
+    publicKey;
+    #privateKey;
+    constructor(privateKey) {
+        if (privateKey.type !== 'private' || privateKey.asymmetricKeyType !== 'ed25519')
+            throw keyUnavailable('Effect ledger signing key must be an Ed25519 private key');
+        this.#privateKey = privateKey;
+        const der = createPublicKey(privateKey).export({ format: 'der', type: 'spki' });
+        this.publicKey = der.toString('base64');
+        this.keyid = sha256Digest(der);
+    }
+    /** Signature (standard padded base64) over the DSSE PAE of `payloadType` and `payload`. */
+    signPae(payloadType, payload) {
+        const envelope = signDsseEnvelope(payloadType, payload, this.#privateKey);
+        return envelope.signatures[0].sig;
+    }
+    toJSON() { return { keyid: this.keyid, publicKey: this.publicKey }; }
+    [inspect.custom]() { return `LedgerSigningKey(${this.keyid})`; }
+}
+/** Parse a PKCS#8 PEM, base64 PKCS#8 DER, or 32-byte hex seed into an Ed25519 key. */
+export function parseLedgerPrivateKey(secret) {
+    const value = secret.trim();
+    try {
+        if (value.includes('-----BEGIN'))
+            return createPrivateKey(value);
+        if (/^[a-f0-9]{64}$/i.test(value)) {
+            return createPrivateKey({ key: Buffer.concat([PKCS8_ED25519_PREFIX, Buffer.from(value, 'hex')]), format: 'der', type: 'pkcs8' });
+        }
+        return createPrivateKey({ key: Buffer.from(value, 'base64'), format: 'der', type: 'pkcs8' });
+    }
+    catch {
+        throw keyUnavailable('Effect ledger signing key material is not a valid Ed25519 private key');
+    }
+}
+/** Generate a fresh Ed25519 ledger key, serialized as base64 PKCS#8 DER for a secret store. */
+export function generateLedgerKeySecret() {
+    const { privateKey } = generateKeyPairSync('ed25519');
+    return privateKey.export({ format: 'der', type: 'pkcs8' }).toString('base64');
+}
+export function staticKeyProvider(privateKey, name = 'static') {
+    const key = new LedgerSigningKey(typeof privateKey === 'string' ? parseLedgerPrivateKey(privateKey) : privateKey);
+    return { name, load: async () => key };
+}
+/** The production provider: the host secret service through the configurable credential store. */
+export function credentialStoreKeyProvider(options) {
+    const service = options.service ?? DEFAULT_LEDGER_KEY_SERVICE;
+    let cached;
+    return {
+        name: 'credential-store',
+        async load() {
+            if (cached)
+                return cached;
+            let store;
+            try {
+                store = options.store ?? createSecretStore({
+                    service, account: options.account, platform: options.platform, runner: options.runner,
+                    useFile: options.useFile, allowFile: options.allowFile, pathname: options.pathname,
+                });
+            }
+            catch {
+                throw keyUnavailable('Effect ledger key store is unavailable on this host');
+            }
+            let secret;
+            try {
+                secret = await store.loadSecret();
+            }
+            catch {
+                throw keyUnavailable('Effect ledger key could not be read from the host secret service');
+            }
+            if (!secret) {
+                if (!options.provisionIfMissing)
+                    throw keyUnavailable('Effect ledger key is not provisioned in the host secret service');
+                secret = generateLedgerKeySecret();
+                try {
+                    await store.saveSecret(secret);
+                }
+                catch {
+                    throw keyUnavailable('Effect ledger key could not be stored in the host secret service');
+                }
+            }
+            cached = new LedgerSigningKey(parseLedgerPrivateKey(secret));
+            return cached;
+        },
+    };
+}
+function testContext(env) {
+    return env.VITEST === 'true' || env.NODE_ENV === 'test' || env.CI === 'true' || env.CI === '1';
+}
+/** Tests and CI only: a key injected through `AIWG_EFFECT_LEDGER_TEST_KEY`. */
+export function environmentTestKeyProvider(env = process.env) {
+    return {
+        name: 'environment-test-key',
+        async load() {
+            if (!testContext(env))
+                throw keyUnavailable(`${LEDGER_TEST_KEY_ENV} is honoured only under a test runner or CI`);
+            const value = env[LEDGER_TEST_KEY_ENV];
+            if (!value)
+                throw keyUnavailable(`${LEDGER_TEST_KEY_ENV} is not set`);
+            return new LedgerSigningKey(parseLedgerPrivateKey(value));
+        },
+    };
+}
+//# sourceMappingURL=keys.js.map

package/dist/src/effects/ledger.js

@@ -0,0 +1,435 @@
+/**
+ * The effect ledger: intent, outcome, reconcile and lookup over per-writer
+ * signed segments, with exclusive-create index files for cross-writer
+ * idempotency (first writer wins).
+ *
+ * The ledger proves what AIWG recorded; it never authorizes or replays an
+ * effect. A missing entry is not evidence that the effect did not happen.
+ *
+ * @see docs/contracts/effect-ledger.v1.md
+ * @see docs/architecture/adr-effect-ledger.md
+ */
+import { canonicalJson } from '../security/artifact-trust.js';
+import { gitRefCheckpointSink } from './checkpoint-sinks.js';
+import { conflictError, EFFECT_EXIT_CODES, EffectLedgerError, integrityError, usageError } from './errors.js';
+import { assertEffectId, assertEffectScope, assertPayloadDigest, assertWriterId, effectId as deriveEffectId, defaultDerivationFor, } from './identity.js';
+import { activeKey, assertKeyring, createGenesisKeyring, keyValidAt, rotateKeyring } from './keyring.js';
+import { lineFailures, mergeOrder, readAllSegments, readKeyring, readWriterSegment } from './reader.js';
+import { decodeSegmentLine, signSegmentLine, statementFor } from './records.js';
+import { assertEffectSchema } from './schema.js';
+import { appendSegmentLine, claimIndex, clearPending, ensureLedgerDirectories, indexName, loadIndexKey, readIndexEntry, readPending, readSegment, replaceFile, resolveLedgerPaths, withLedgerLock, writePending, } from './store.js';
+import { publishExclusive } from '../storage/protected-files.js';
+import { createVerifierRegistry, runVerifier } from './verifiers/registry.js';
+import { INDEX_SCHEMA_VERSION, RECORD_SCHEMA_VERSION, VERIFIER_RESULT_SCHEMA_VERSION, } from './types.js';
+// ---------------------------------------------------------------------------
+// Verifier interface (src/effects/verifiers; re-exported for compatibility)
+// ---------------------------------------------------------------------------
+export { createVerifierRegistry } from './verifiers/registry.js';
+export class EffectLedger {
+    projectDir;
+    scope;
+    writer;
+    sink;
+    verifiers;
+    lockTimeoutMs;
+    keyProvider;
+    clock;
+    constructor(options) {
+        if (!options || typeof options.projectDir !== 'string' || !options.projectDir)
+            throw usageError('Effect ledger needs a project directory', 'invalid-project');
+        assertEffectScope(options.scope);
+        assertWriterId(options.writer);
+        this.projectDir = options.projectDir;
+        this.scope = structuredClone(options.scope);
+        this.writer = options.writer;
+        this.keyProvider = options.keyProvider;
+        this.clock = options.clock ?? Date.now;
+        this.sink = options.sink ?? gitRefCheckpointSink({ repoDir: options.projectDir, subsystem: options.scope.subsystem });
+        this.verifiers = options.verifiers ?? createVerifierRegistry();
+        this.lockTimeoutMs = options.lockTimeoutMs ?? 30_000;
+    }
+    /** Resolved on every call, so an artifact root that goes away fails closed (exit 7). */
+    paths() { return resolveLedgerPaths(this.projectDir, this.scope.subsystem); }
+    now() {
+        const value = this.clock();
+        if (!Number.isFinite(value))
+            throw new EffectLedgerError('internal', 'Effect ledger clock returned an invalid time');
+        return new Date(value).toISOString();
+    }
+    async signingKey() {
+        if (!this.keyProvider)
+            throw new EffectLedgerError('key-unavailable', 'Effect ledger writes need a key provider', 'key-unavailable');
+        return this.keyProvider.load();
+    }
+    /** Switch to another key provider, for example after `rotateKey`. */
+    useKeyProvider(provider) { this.keyProvider = provider; }
+    toJSON() { return { scope: this.scope, writer: this.writer }; }
+}
+export function openEffectLedger(options) {
+    return new EffectLedger(options);
+}
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+async function prepareWrite(ledger) {
+    const paths = ledger.paths();
+    await ensureLedgerDirectories(paths);
+    return { paths, indexKey: await loadIndexKey(paths) };
+}
+/** Load the keyring, creating the genesis keyring for this key on first use. */
+async function ensureKeyring(ledger, paths, key, at) {
+    let stored = await readKeyring(paths);
+    if (stored === null) {
+        const genesis = createGenesisKeyring(ledger.scope, key, at);
+        assertEffectSchema('keyring', genesis);
+        await publishExclusive(paths.root, paths.keyring, `${JSON.stringify(genesis, null, 2)}\n`, 'keyring');
+        stored = await readKeyring(paths);
+    }
+    assertKeyring(stored, ledger.scope);
+    return stored;
+}
+function assertSigningKeyActive(keyring, key, at) {
+    const active = activeKey(keyring);
+    if (active.keyid !== key.keyid || !keyValidAt(active, at)) {
+        throw new EffectLedgerError('key-unavailable', 'The loaded signing key is not the active ledger key at this time', 'key-not-active');
+    }
+}
+async function segmentHead(paths, writer) {
+    const segment = await readSegment(paths, writer);
+    if (!segment)
+        return { count: 0, hash: null };
+    if (segment.torn)
+        throw integrityError('segment-torn', 'Effect ledger segment has a torn tail; run verify');
+    if (!segment.lines.length)
+        return { count: 0, hash: null };
+    const last = decodeSegmentLine(segment.lines.at(-1));
+    if ('failure' in last)
+        throw integrityError(last.failure, 'Effect ledger segment head is malformed; run verify');
+    return { count: segment.lines.length, hash: last.line.recordHash };
+}
+/** Finish an append that crashed between its index claim and the segment write. */
+async function repairPending(paths, writer) {
+    const pending = await readPending(paths, writer);
+    if (!pending)
+        return;
+    const line = pending.line;
+    const head = await segmentHead(paths, writer);
+    const entry = await readIndexEntry(paths, pending.indexName).catch(() => null);
+    const decoded = decodeSegmentLine(JSON.stringify(line));
+    if (!('failure' in decoded) && entry && entry.recordHash === line.recordHash && entry.writer === writer
+        && line.seq === head.count && decoded.statement.predicate.prev === head.hash) {
+        await appendSegmentLine(paths, writer, line);
+    }
+    await clearPending(paths, writer);
+}
+/**
+ * Sign and append one record under this writer's lock. With a `role`, the
+ * record is appended only after its exclusive index claim wins; a lost claim
+ * returns the winning index entry instead.
+ */
+async function appendRecord(ledger, plan, effectIdValue) {
+    const { paths, indexKey } = await prepareWrite(ledger);
+    const key = await ledger.signingKey();
+    return withLedgerLock(paths, `writer-${ledger.writer}`, ledger.lockTimeoutMs, async () => {
+        // Read the clock after the keyring exists, so a genesis keyring published by
+        // a concurrent process is never newer than this record.
+        const keyring = await ensureKeyring(ledger, paths, key, ledger.now());
+        const recordedAt = ledger.now();
+        assertSigningKeyActive(keyring, key, recordedAt);
+        await repairPending(paths, ledger.writer);
+        const head = await segmentHead(paths, ledger.writer);
+        const predicate = plan.build(head.count, head.hash, recordedAt);
+        const line = signSegmentLine(statementFor(predicate), key);
+        if (plan.role) {
+            const name = indexName(indexKey, ledger.scope, effectIdValue, plan.role);
+            const entry = {
+                schemaVersion: INDEX_SCHEMA_VERSION, role: plan.role, effectId: effectIdValue, payloadDigest: predicate.payloadDigest,
+                phase: predicate.phase, writer: ledger.writer, seq: predicate.seq, recordHash: line.recordHash,
+            };
+            await writePending(paths, ledger.writer, { indexName: name, line });
+            if (!(await claimIndex(paths, name, entry))) {
+                await clearPending(paths, ledger.writer);
+                const winner = await readIndexEntry(paths, name);
+                if (!winner)
+                    throw new EffectLedgerError('internal', 'Effect index claim was lost but no winner is readable');
+                return { line, lost: winner };
+            }
+            await appendSegmentLine(paths, ledger.writer, line);
+            await clearPending(paths, ledger.writer);
+        }
+        else {
+            await appendSegmentLine(paths, ledger.writer, line);
+        }
+        return { line };
+    });
+}
+function receiptFromEntry(entry, idDerivation, idempotent) {
+    return {
+        effectId: entry.effectId, idDerivation, phase: entry.phase, payloadDigest: entry.payloadDigest,
+        writer: entry.writer, seq: entry.seq, recordHash: entry.recordHash, idempotent, exitCode: EFFECT_EXIT_CODES.ok,
+    };
+}
+function receiptFromLine(line, predicate) {
+    return {
+        effectId: predicate.effectId, idDerivation: predicate.idDerivation, phase: predicate.phase,
+        payloadDigest: predicate.payloadDigest, writer: line.writer, seq: line.seq, recordHash: line.recordHash,
+        idempotent: false, exitCode: EFFECT_EXIT_CODES.ok,
+    };
+}
+/** Decode and verify the intent record an index entry points at. */
+async function intentRecord(ledger, paths, entry) {
+    const segment = await readWriterSegment(paths, entry.writer);
+    const read = segment?.lines[entry.seq];
+    if (!read?.decoded)
+        throw integrityError('index-dangling', 'The effect index points at a missing intent record; run verify');
+    const keyring = await readKeyring(paths);
+    assertKeyring(keyring, ledger.scope);
+    const previous = entry.seq === 0 ? null : segment.lines[entry.seq - 1]?.decoded?.line.recordHash ?? null;
+    const failures = lineFailures(keyring, ledger.scope, entry.writer, entry.seq, read.decoded, previous);
+    if (failures.length || read.decoded.line.recordHash !== entry.recordHash || read.decoded.statement.predicate.effectId !== entry.effectId) {
+        throw integrityError(failures[0] ?? 'index-segment-mismatch');
+    }
+    return read.decoded;
+}
+async function requireIntent(ledger, id) {
+    assertEffectId(id);
+    const { paths, indexKey } = await prepareWrite(ledger);
+    const entry = await readIndexEntry(paths, indexName(indexKey, ledger.scope, id, 'intent'));
+    if (!entry)
+        throw usageError('No intent is recorded for this effect ID', 'intent-missing');
+    const intent = (await intentRecord(ledger, paths, entry)).statement.predicate;
+    if (intent.phase === 'tombstone')
+        throw usageError('The intent for this effect ID has been purged', 'intent-purged');
+    return { paths, indexKey, entry, intent };
+}
+function basePredicate(intent, phase, payloadDigest, links, writer, seq, prev, recordedAt) {
+    return {
+        schemaVersion: RECORD_SCHEMA_VERSION, effectId: intent.effectId, idDerivation: intent.idDerivation,
+        scope: intent.scope, kind: intent.kind, target: intent.target, context: intent.context, phase,
+        payloadDigest, writer, seq, prev, recordedAt, links: structuredClone(links ?? {}),
+    };
+}
+/**
+ * Append a signed `intent` before the effect. The same ID with the same payload
+ * digest returns the first receipt (`idempotent: true`); a different digest is
+ * a conflict (exit 5). Nothing is appended in either case.
+ */
+export async function recordIntent(ledger, input) {
+    const derivation = input?.derivation ?? defaultDerivationFor(input?.kind);
+    const id = deriveEffectId({ scope: ledger.scope, kind: input.kind, target: input.target, context: input.context }, derivation);
+    assertPayloadDigest(input.payloadDigest);
+    const { paths, indexKey } = await prepareWrite(ledger);
+    const existing = await readIndexEntry(paths, indexName(indexKey, ledger.scope, id, 'intent'));
+    const settle = (entry) => {
+        if (entry.payloadDigest !== input.payloadDigest)
+            throw conflictError();
+        return receiptFromEntry(entry, derivation, true);
+    };
+    if (existing)
+        return settle(existing);
+    const { line, lost } = await appendRecord(ledger, {
+        role: 'intent',
+        build: (seq, prev, recordedAt) => ({
+            schemaVersion: RECORD_SCHEMA_VERSION, effectId: id, idDerivation: derivation, scope: ledger.scope,
+            kind: input.kind, target: input.target, context: structuredClone(input.context), phase: 'intent',
+            payloadDigest: input.payloadDigest, writer: ledger.writer, seq, prev, recordedAt, links: structuredClone(input.links ?? {}),
+        }),
+    }, id);
+    if (lost)
+        return settle(lost);
+    return receiptFromLine(line, JSON.parse(Buffer.from(line.envelope.payload, 'base64').toString('utf8')).predicate);
+}
+/**
+ * Append the terminal outcome. The first outcome for an ID wins across writers;
+ * repeating it returns the existing receipt, and a different terminal outcome
+ * or payload digest is a conflict.
+ */
+export async function recordOutcome(ledger, id, input) {
+    if (input?.phase !== 'completed' && input?.phase !== 'failed')
+        throw usageError('Outcome phase must be completed or failed', 'invalid-phase');
+    assertPayloadDigest(input.payloadDigest);
+    if (input.phase === 'completed' && input.verification?.result !== 'present')
+        throw usageError('A completed outcome needs a present verification', 'completed-without-present');
+    if (input.phase === 'failed' && !input.failure)
+        throw usageError('A failed outcome needs a failure reason', 'failed-without-reason');
+    const { paths, indexKey, entry, intent } = await requireIntent(ledger, id);
+    if (entry.payloadDigest !== input.payloadDigest)
+        throw conflictError();
+    const outcomeName = indexName(indexKey, ledger.scope, id, 'outcome');
+    const settle = (winner) => {
+        if (winner.phase !== input.phase || winner.payloadDigest !== input.payloadDigest) {
+            throw new EffectLedgerError('conflict', 'A different outcome is already recorded for this effect ID', 'outcome-conflict');
+        }
+        return receiptFromEntry(winner, intent.idDerivation, true);
+    };
+    const existing = await readIndexEntry(paths, outcomeName);
+    if (existing)
+        return settle(existing);
+    const { line, lost } = await appendRecord(ledger, {
+        role: 'outcome',
+        build: (seq, prev, recordedAt) => ({
+            ...basePredicate(intent, input.phase, input.payloadDigest, input.links, ledger.writer, seq, prev, recordedAt),
+            ...(input.phase === 'completed' ? { verification: structuredClone(input.verification) } : { failure: structuredClone(input.failure) }),
+        }),
+    }, id);
+    if (lost)
+        return settle(lost);
+    return receiptFromLine(line, { ...intent, phase: input.phase, writer: line.writer, seq: line.seq });
+}
+/** Append one `reconciled` record for one verifier attempt. History is never mutated. */
+export async function recordReconciled(ledger, id, verification, links) {
+    const { intent, entry } = await requireIntent(ledger, id);
+    const { line } = await appendRecord(ledger, {
+        build: (seq, prev, recordedAt) => ({
+            ...basePredicate(intent, 'reconciled', entry.payloadDigest, links, ledger.writer, seq, prev, recordedAt),
+            verification: structuredClone(verification),
+        }),
+    }, id);
+    return receiptFromLine(line, { ...intent, phase: 'reconciled', writer: line.writer, seq: line.seq });
+}
+const EXIT_FOR_RESULT = { present: 0, absent: 3, unknown: 4 };
+/**
+ * Reconcile one effect through its kind's verifier. Every call appends one
+ * signed `reconciled` record; a `present` result also records `completed`
+ * (first outcome wins). Earlier records are never mutated and the effect is
+ * never replayed. With no registered verifier the result is `unknown` /
+ * `verifier-missing`.
+ */
+export async function reconcileEffect(ledger, id, options = {}) {
+    const { intent, entry } = await requireIntent(ledger, id);
+    const registry = options.verifiers ?? ledger.verifiers;
+    const run = await runVerifier(registry.get(intent.kind), {
+        effectId: intent.effectId, scope: structuredClone(intent.scope), kind: intent.kind, target: intent.target,
+        context: structuredClone(intent.context), payloadDigest: entry.payloadDigest, intentRecordedAt: intent.recordedAt,
+        expected: structuredClone(options.expected ?? {}),
+    }, options);
+    const verification = { verifier: run.verifier, ...run.observation, checkedAt: ledger.now() };
+    const receipt = await recordReconciled(ledger, id, verification, options.links);
+    const result = {
+        schemaVersion: VERIFIER_RESULT_SCHEMA_VERSION, effectId: intent.effectId, kind: intent.kind,
+        verification, exitCode: EXIT_FOR_RESULT[verification.result],
+    };
+    assertEffectSchema('verifierResult', result);
+    let completed = null;
+    if (verification.result === 'present') {
+        try {
+            completed = await recordOutcome(ledger, id, { phase: 'completed', payloadDigest: entry.payloadDigest, verification, links: options.links });
+        }
+        catch (error) {
+            if (!(error instanceof EffectLedgerError) || error.reason !== 'outcome-conflict')
+                throw error;
+        }
+    }
+    return { result, receipt: { ...receipt, exitCode: result.exitCode }, completed, ...(run.evidence ? { evidence: run.evidence } : {}) };
+}
+function summarize(decoded) {
+    const predicate = decoded.statement.predicate;
+    return {
+        phase: predicate.phase, writer: decoded.line.writer, seq: decoded.line.seq, recordHash: decoded.line.recordHash,
+        recordedAt: predicate.recordedAt, payloadDigest: predicate.payloadDigest, keyid: decoded.line.envelope.signatures[0].keyid,
+        ...(predicate.verification ? { verification: structuredClone(predicate.verification) } : {}),
+        ...(predicate.failure ? { failure: structuredClone(predicate.failure) } : {}),
+        ...(predicate.tombstone ? { tombstone: structuredClone(predicate.tombstone) } : {}),
+    };
+}
+/**
+ * Look up everything recorded for an effect ID, merged across writers. Every
+ * returned record is signature- and chain-checked; a failure is exit 6.
+ * A tombstoned record is returned without its target, context or outcome body.
+ */
+export async function lookupEffect(ledger, id) {
+    assertEffectId(id);
+    const paths = ledger.paths();
+    const keyring = await readKeyring(paths);
+    const none = { effectId: id, found: false, status: 'none', tombstoned: false, records: [], exitCode: EFFECT_EXIT_CODES.absent };
+    if (keyring === null)
+        return none;
+    assertKeyring(keyring, ledger.scope);
+    const matches = [];
+    for (const segment of await readAllSegments(paths)) {
+        let previous = null;
+        for (const read of segment.lines) {
+            if (!read.decoded)
+                throw integrityError(read.failure);
+            if (read.decoded.statement.predicate.effectId === id) {
+                const failures = lineFailures(keyring, ledger.scope, segment.writer, read.index, read.decoded, previous);
+                if (failures.length)
+                    throw integrityError(failures[0]);
+                matches.push(read.decoded);
+            }
+            previous = read.decoded.line.recordHash;
+        }
+    }
+    if (!matches.length)
+        return none;
+    matches.sort(mergeOrder);
+    const records = matches.map(summarize);
+    const live = matches.map(item => item.statement.predicate).filter(predicate => predicate.phase !== 'tombstone');
+    const tombstoned = records.some(record => record.phase === 'tombstone');
+    const identity = live[0];
+    const base = { effectId: id, found: true, tombstoned, records, kind: matches[0].statement.predicate.kind, ...(identity?.target ? { target: identity.target } : {}) };
+    const outcomes = records.filter(record => record.phase === 'completed' || record.phase === 'failed' || record.phase === 'reconciled');
+    const latest = outcomes.at(-1);
+    if (!latest) {
+        if (!live.length) {
+            const phases = records.map(record => record.tombstone.originalPhase);
+            const exitCode = phases.includes('completed') ? EFFECT_EXIT_CODES.ok : phases.includes('failed') ? EFFECT_EXIT_CODES.absent : EFFECT_EXIT_CODES.unknown;
+            return { ...base, status: 'tombstoned', exitCode };
+        }
+        return { ...base, status: 'intent', exitCode: EFFECT_EXIT_CODES.unknown };
+    }
+    if (latest.phase === 'completed')
+        return { ...base, status: 'completed', result: 'present', exitCode: EFFECT_EXIT_CODES.ok };
+    if (latest.phase === 'failed')
+        return { ...base, status: 'failed', exitCode: EFFECT_EXIT_CODES.absent };
+    const result = latest.verification.result;
+    return { ...base, status: 'reconciled', result, exitCode: EXIT_FOR_RESULT[result] };
+}
+/**
+ * Create the genesis keyring for the loaded signing key when the ledger has
+ * none, and return the keyring. Fails when the loaded key is not the active key.
+ * Used by `aiwg effect keys init`; ordinary writes create it on first use.
+ */
+export async function initLedgerKeyring(ledger) {
+    const { paths } = await prepareWrite(ledger);
+    const key = await ledger.signingKey();
+    return withLedgerLock(paths, 'keyring', ledger.lockTimeoutMs, async () => {
+        const at = ledger.now();
+        const keyring = await ensureKeyring(ledger, paths, key, at);
+        assertSigningKeyActive(keyring, key, ledger.now());
+        return keyring;
+    });
+}
+/** The stored keyring (public keys only), or null when the ledger has none. Never needs a signing key. */
+export async function readLedgerKeyring(ledger) {
+    const stored = await readKeyring(ledger.paths());
+    if (stored === null)
+        return null;
+    assertKeyring(stored, ledger.scope);
+    return stored;
+}
+/**
+ * Rotate the ledger key. The rotation is signed by the active (prior) key and
+ * by the successor key; the prior key's window closes at `effectiveAt`. The
+ * ledger handle switches to the successor provider.
+ */
+export async function rotateKey(ledger, successorProvider, options = {}) {
+    const { paths } = await prepareWrite(ledger);
+    const prior = await ledger.signingKey();
+    const successor = await successorProvider.load();
+    const effectiveAt = options.effectiveAt ?? ledger.now();
+    const keyring = await withLedgerLock(paths, 'keyring', ledger.lockTimeoutMs, async () => {
+        const current = await ensureKeyring(ledger, paths, prior, effectiveAt);
+        const next = rotateKeyring(current, prior, successor, effectiveAt, options.reason ?? 'scheduled');
+        assertEffectSchema('keyring', next);
+        await replaceFile(paths.root, paths.keyring, `${JSON.stringify(next, null, 2)}\n`);
+        return next;
+    });
+    ledger.useKeyProvider(successorProvider);
+    return keyring;
+}
+/** Stable JSON for CLI and API output; never contains key material. */
+export function effectOutputJson(value) {
+    return canonicalJson(JSON.parse(JSON.stringify(value)));
+}
+//# sourceMappingURL=ledger.js.map

package/dist/src/effects/lifecycle.js

@@ -0,0 +1,110 @@
+/**
+ * D10 retention for effect records. A purge replaces each record's envelope
+ * with a signed tombstone that keeps the effect ID, kind, payload digest, chain
+ * position, links and subject digest, and names the original record hash and
+ * keyid, so the chain still verifies. Target, context and outcome bodies are
+ * dropped. The effect-ID index is never deleted, so a purged ID cannot be
+ * replayed as new.
+ *
+ * @see docs/contracts/effect-ledger.v1.md "Retention and tombstones"
+ */
+import { validateDecisionLifecyclePolicy } from '../decision/lifecycle.js';
+import { EffectLedgerError, integrityError, usageError } from './errors.js';
+import { assertEffectId } from './identity.js';
+import { activeKey, assertKeyring, keyValidAt } from './keyring.js';
+import { lookupEffect } from './ledger.js';
+import { lineFailures, readKeyring, readWriterSegment } from './reader.js';
+import { signSegmentLine } from './records.js';
+import { ensureLedgerDirectories, replaceSegment, withLedgerLock } from './store.js';
+import { EFFECT_PREDICATE_TYPE, IN_TOTO_STATEMENT_TYPE } from './types.js';
+/** Ledger records bind the D10 `receipt` surface until a dedicated surface exists. */
+export const EFFECT_RETENTION_POLICY = 'decision-lifecycle/v1#receipt';
+const refused = (reason, message) => new EffectLedgerError('purge-refused', message, reason);
+/**
+ * Purge one effect's records to tombstones. Refused while a legal hold applies,
+ * before the D10 receipt retention has elapsed, and while the intent has no
+ * definitive outcome (completed, failed, or a present/absent reconcile).
+ */
+export async function purgeEffect(ledger, id, options) {
+    assertEffectId(id);
+    try {
+        validateDecisionLifecyclePolicy(options?.lifecycle);
+    }
+    catch {
+        throw usageError('Purge needs a complete decision-lifecycle/v1 policy', 'lifecycle-invalid');
+    }
+    const rule = options.lifecycle.surfaces.receipt;
+    if (options.legalHold)
+        throw refused('legal-hold', 'A legal hold blocks purging this effect');
+    const found = await lookupEffect(ledger, id);
+    if (!found.found)
+        throw usageError('No records exist for this effect ID', 'effect-not-found');
+    const live = found.records.filter(record => record.phase !== 'tombstone');
+    const result = { effectId: id, tombstoned: 0, alreadyTombstoned: found.records.length - live.length, retentionPolicy: EFFECT_RETENTION_POLICY };
+    if (!live.length)
+        return result;
+    const definitive = found.records.some(record => record.phase === 'completed' || record.phase === 'failed'
+        || (record.phase === 'reconciled' && record.verification?.result !== 'unknown')
+        || (record.phase === 'tombstone' && (record.tombstone.originalPhase === 'completed' || record.tombstone.originalPhase === 'failed')));
+    if (!definitive)
+        throw refused('unreconciled-intent', 'An intent without a definitive outcome is never purged; reconcile it first');
+    const purgedAt = ledger.now();
+    const newest = Math.max(...live.map(record => Date.parse(record.recordedAt)));
+    if (Date.parse(purgedAt) - newest < rule.retentionMs)
+        throw refused('retention-not-elapsed', 'The D10 receipt retention period has not elapsed for this effect');
+    const paths = ledger.paths();
+    await ensureLedgerDirectories(paths);
+    const key = await ledger.signingKey();
+    const writers = [...new Set(live.map(record => record.writer))].sort();
+    for (const writer of writers) {
+        await withLedgerLock(paths, `writer-${writer}`, ledger.lockTimeoutMs, async () => {
+            const keyring = await readKeyring(paths);
+            assertKeyring(keyring, ledger.scope);
+            const active = activeKey(keyring);
+            if (active.keyid !== key.keyid || !keyValidAt(active, purgedAt)) {
+                throw new EffectLedgerError('key-unavailable', 'The loaded signing key is not the active ledger key at this time', 'key-not-active');
+            }
+            const segment = await readWriterSegment(paths, writer);
+            if (!segment || segment.torn)
+                throw integrityError('segment-torn');
+            let previous = null;
+            let changed = false;
+            const lines = segment.lines.map((read) => {
+                if (!read.decoded)
+                    throw integrityError(read.failure);
+                const failures = lineFailures(keyring, ledger.scope, writer, read.index, read.decoded, previous);
+                if (failures.length)
+                    throw integrityError(failures[0]);
+                previous = read.decoded.line.recordHash;
+                const original = read.decoded.statement;
+                if (original.predicate.effectId !== id || original.predicate.phase === 'tombstone')
+                    return read.text;
+                const { target: _target, context: _context, verification: _verification, failure: _failure, ...kept } = original.predicate;
+                const predicate = {
+                    ...kept,
+                    phase: 'tombstone',
+                    tombstone: {
+                        originalRecordHash: read.decoded.line.recordHash,
+                        originalKeyid: read.decoded.line.envelope.signatures[0].keyid,
+                        originalPhase: original.predicate.phase,
+                        purgedAt,
+                        retentionPolicy: EFFECT_RETENTION_POLICY,
+                    },
+                };
+                const statement = {
+                    _type: IN_TOTO_STATEMENT_TYPE,
+                    subject: [{ name: `aiwg-effect:${id}`, digest: structuredClone(original.subject[0].digest) }],
+                    predicateType: EFFECT_PREDICATE_TYPE,
+                    predicate,
+                };
+                changed = true;
+                result.tombstoned += 1;
+                return JSON.stringify(signSegmentLine(statement, key, read.decoded.line.recordHash));
+            });
+            if (changed)
+                await replaceSegment(paths, writer, lines);
+        });
+    }
+    return result;
+}
+//# sourceMappingURL=lifecycle.js.map