@aiwg/cli 2026.9.19 → 2026.9.21

package/dist/src/effects/lock-recovery.js

@@ -0,0 +1,269 @@
+/**
+ * Operator-authorized recovery of a stale effect ledger lock.
+ *
+ * Ledger locks (`locks/<name>.lock`) are same-host directory locks whose
+ * `owner` file holds `<pid>:<uuid>`. A crashed writer leaves its lock behind,
+ * and every later writer then times out rather than steal it. This module is
+ * the only supported way to clear such a lock. It is modelled on the D16 quota
+ * lock recovery (`recoverStaleJobQuotaLock`, `src/decision/job-quota.ts`):
+ *
+ * - it refuses a live owner, a PID that has been reused by a newer process,
+ *   and any owner it cannot verify (malformed owner file, permission denied);
+ * - it needs an explicit authorization callback, which must approve the exact
+ *   inspected owner;
+ * - it re-checks the owner after authorization and removes the lock only when
+ *   the same dead owner still holds it;
+ * - it records the recovery in the ledger as a signed, verified effect of kind
+ *   `x.aiwg.ledger-lock-recovery` (intent before the removal, completed after
+ *   the lock-state verifier confirms it).
+ *
+ * @see docs/contracts/effect-ledger.v1.md "Stale lock recovery"
+ */
+import { lstat, mkdir, readdir, readFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { EFFECT_EXIT_CODES, EffectLedgerError, usageError } from './errors.js';
+import { payloadDigest, sha256Digest } from './identity.js';
+import { EffectLedger, lookupEffect, recordIntent, recordOutcome, recordReconciled } from './ledger.js';
+import { resolveLedgerPaths } from './store.js';
+import { createVerifierRegistry, runVerifier } from './verifiers/registry.js';
+import { EffectVerifierError } from './verifiers/types.js';
+export const LOCK_RECOVERY_KIND = 'x.aiwg.ledger-lock-recovery';
+export const LOCK_RECOVERY_VERIFIER_VERSION = '1.0.0';
+/** Lock names the ledger creates: one per writer, plus the checkpoint and keyring locks. */
+export const LEDGER_LOCK_NAME_PATTERN = /^(?:writer-[a-z0-9][a-z0-9-]{0,63}|checkpoint|keyring)$/;
+const OWNER_PATTERN = /^([1-9][0-9]{0,9}):([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/;
+const RECOVERY_GUARD = '.recover.guard';
+/** A process that started this long after the owner file was written cannot be its owner. */
+const PID_REUSE_TOLERANCE_MS = 2_000;
+export function lockRecoveryTarget(scope, lock) {
+    return `x-aiwg:effects/${scope.subsystem}/locks/${lock}`;
+}
+function assertLockName(lock) {
+    if (typeof lock !== 'string' || !LEDGER_LOCK_NAME_PATTERN.test(lock))
+        throw usageError('Unknown effect ledger lock name', 'invalid-lock-name');
+}
+const lockDir = (paths, lock) => join(paths.locks, `${lock}.lock`);
+/** Linux only: the process start time in epoch ms, or null when it cannot be read. */
+async function processStartMs(pid) {
+    if (process.platform !== 'linux')
+        return null;
+    try {
+        const stat = await readFile(`/proc/${pid}/stat`, 'utf8');
+        const fields = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
+        const startTicks = Number(fields[19]);
+        const bootLine = (await readFile('/proc/stat', 'utf8')).split('\n').find(line => line.startsWith('btime '));
+        const bootSeconds = Number(bootLine?.split(/\s+/)[1]);
+        if (!Number.isFinite(startTicks) || !Number.isFinite(bootSeconds))
+            return null;
+        // /proc reports start time in USER_HZ, which is 100 on Linux.
+        return bootSeconds * 1000 + (startTicks / 100) * 1000;
+    }
+    catch {
+        return null;
+    }
+}
+async function ownerState(pid, lockedAtMs) {
+    try {
+        process.kill(pid, 0);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ESRCH')
+            return { state: 'dead', reason: 'owner-dead' };
+        return { state: 'unverifiable', reason: code === 'EPERM' ? 'owner-permission-denied' : 'owner-unreadable' };
+    }
+    const started = await processStartMs(pid);
+    if (started !== null && started > lockedAtMs + PID_REUSE_TOLERANCE_MS)
+        return { state: 'reused', reason: 'owner-pid-reused' };
+    return { state: 'live', reason: 'owner-live' };
+}
+async function inspectAt(paths, lock) {
+    const dir = lockDir(paths, lock);
+    let info;
+    try {
+        info = await lstat(dir);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { lock, held: false, reason: 'not-held' };
+        return { lock, held: true, state: 'unverifiable', reason: 'owner-unreadable' };
+    }
+    if (!info.isDirectory() || info.isSymbolicLink())
+        return { lock, held: true, state: 'unverifiable', reason: 'owner-malformed' };
+    const ownerFile = join(dir, 'owner');
+    let token;
+    let ownerInfo;
+    try {
+        ownerInfo = await lstat(ownerFile);
+        if (!ownerInfo.isFile() || ownerInfo.isSymbolicLink() || (ownerInfo.mode & 0o077) !== 0) {
+            return { lock, held: true, state: 'unverifiable', reason: 'owner-malformed' };
+        }
+        token = (await readFile(ownerFile, 'utf8')).trim();
+    }
+    catch {
+        return { lock, held: true, state: 'unverifiable', reason: 'owner-unreadable' };
+    }
+    const match = OWNER_PATTERN.exec(token);
+    if (!match || !Number.isSafeInteger(Number(match[1]))) {
+        return { lock, held: true, state: 'unverifiable', reason: 'owner-malformed', lockedAt: ownerInfo.mtime.toISOString() };
+    }
+    const pid = Number(match[1]);
+    const lockedAtMs = ownerInfo.mtimeMs;
+    const state = pid === process.pid ? { state: 'live', reason: 'owner-live' } : await ownerState(pid, lockedAtMs);
+    return { lock, held: true, ...state, pid, ownerDigest: sha256Digest(token), lockedAt: new Date(lockedAtMs).toISOString(), token };
+}
+function publicInspection(inspection) {
+    const { token: _token, ...rest } = inspection;
+    return rest;
+}
+/** Inspect one ledger lock. Read-only. */
+export async function inspectLedgerLock(ledger, lock) {
+    assertLockName(lock);
+    return publicInspection(await inspectAt(ledger.paths(), lock));
+}
+/** Inspect every lock currently present in the ledger. Read-only. */
+export async function inspectLedgerLocks(ledger) {
+    const paths = ledger.paths();
+    let names;
+    try {
+        names = await readdir(paths.locks);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    const locks = names.filter(name => name.endsWith('.lock')).map(name => name.slice(0, -'.lock'.length))
+        .filter(name => LEDGER_LOCK_NAME_PATTERN.test(name)).sort();
+    const out = [];
+    for (const lock of locks)
+        out.push(publicInspection(await inspectAt(paths, lock)));
+    return out;
+}
+/**
+ * The lock-state verifier for recovery effects. `present` when the recovered
+ * owner no longer holds the lock, `absent` when it still does.
+ */
+export function ledgerLockRecoveryVerifier(options) {
+    return {
+        kind: LOCK_RECOVERY_KIND,
+        version: LOCK_RECOVERY_VERIFIER_VERSION,
+        canReportAbsent: true,
+        async verify(request) {
+            const lock = request.context.lock;
+            const ownerDigest = request.context.ownerDigest;
+            if (typeof lock !== 'string' || !LEDGER_LOCK_NAME_PATTERN.test(lock) || typeof ownerDigest !== 'string'
+                || request.target !== lockRecoveryTarget(request.scope, lock)) {
+                throw new EffectVerifierError('malformed-response', 'Lock recovery effect has an unexpected target or context');
+            }
+            let paths;
+            try {
+                paths = resolveLedgerPaths(options.projectDir, request.scope.subsystem);
+            }
+            catch {
+                throw new EffectVerifierError('container-unreadable', 'Effect ledger root is unavailable');
+            }
+            const current = await inspectAt(paths, lock);
+            if (current.held && current.reason === 'owner-unreadable')
+                throw new EffectVerifierError('container-unreadable', 'Lock owner is unreadable');
+            if (current.held && current.ownerDigest === ownerDigest) {
+                return { result: 'absent', reason: 'complete-query-no-match', complete: true, evidence: { lock, held: true } };
+            }
+            return { result: 'present', reason: 'state-match', complete: true, evidence: { lock, held: current.held } };
+        },
+    };
+}
+/** A handle on the same ledger that appends under another writer, so recovering our own writer lock never deadlocks. */
+function recoveryWriter(ledger, lock) {
+    if (lock !== `writer-${ledger.writer}`)
+        return ledger;
+    const writer = ledger.writer === 'lock-recovery' ? 'lock-recovery-alt' : 'lock-recovery';
+    return new EffectLedger({
+        projectDir: ledger.projectDir, scope: ledger.scope, writer,
+        keyProvider: { name: 'delegated', load: () => ledger.signingKey() },
+        clock: () => Date.parse(ledger.now()), sink: ledger.sink, verifiers: ledger.verifiers, lockTimeoutMs: ledger.lockTimeoutMs,
+    });
+}
+/**
+ * Remove a stale ledger lock after explicit authorization and record the
+ * recovery in the ledger. A live, reused or unverifiable owner is refused and
+ * nothing is removed or recorded.
+ */
+export async function recoverStaleLedgerLock(ledger, lock, options) {
+    assertLockName(lock);
+    if (!options || typeof options.authorize !== 'function')
+        throw usageError('Lock recovery requires an explicit authorization', 'authorization-required');
+    const paths = ledger.paths();
+    const refuse = (outcome, inspection, exitCode) => ({
+        outcome, lock, inspection: publicInspection(inspection), exitCode,
+    });
+    const first = await inspectAt(paths, lock);
+    if (!first.held)
+        return refuse('not-held', first, EFFECT_EXIT_CODES.absent);
+    const guard = join(paths.locks, RECOVERY_GUARD);
+    try {
+        await mkdir(guard, { mode: 0o700 });
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            return refuse('recovery-in-progress', first, EFFECT_EXIT_CODES.conflict);
+        throw error;
+    }
+    try {
+        const inspection = await inspectAt(paths, lock);
+        if (!inspection.held)
+            return refuse('not-held', inspection, EFFECT_EXIT_CODES.absent);
+        if (inspection.state !== 'dead') {
+            return refuse('refused', inspection, inspection.state === 'unverifiable' ? EFFECT_EXIT_CODES.unknown : EFFECT_EXIT_CODES.conflict);
+        }
+        let approved = false;
+        try {
+            approved = (await options.authorize(publicInspection(inspection))) === true;
+        }
+        catch {
+            approved = false;
+        }
+        if (!approved)
+            return refuse('not-authorized', inspection, EFFECT_EXIT_CODES.usage);
+        const recorder = recoveryWriter(ledger, lock);
+        await recorder.signingKey();
+        const context = { lock, ownerPid: inspection.pid, ownerDigest: inspection.ownerDigest };
+        const digest = payloadDigest({ schemaVersion: 'aiwg.effect.lock-recovery.v1', ...context, authorizedBy: 'operator' });
+        const identity = { kind: LOCK_RECOVERY_KIND, target: lockRecoveryTarget(ledger.scope, lock), context };
+        const intent = await recordIntent(recorder, { ...identity, payloadDigest: digest, links: options.links });
+        const recheck = await inspectAt(paths, lock);
+        if (recheck.held && (recheck.state !== 'dead' || recheck.ownerDigest !== inspection.ownerDigest)) {
+            return { ...refuse('refused', recheck, EFFECT_EXIT_CODES.conflict), effectId: intent.effectId, intent };
+        }
+        if (recheck.held)
+            await rm(lockDir(paths, lock), { recursive: true });
+        const found = await lookupEffect(recorder, intent.effectId);
+        const intentAt = found.records.find(record => record.phase === 'intent')?.recordedAt ?? recorder.now();
+        const run = await runVerifier(createVerifierRegistry([ledgerLockRecoveryVerifier({ projectDir: ledger.projectDir })]).get(LOCK_RECOVERY_KIND), {
+            effectId: intent.effectId, scope: structuredClone(ledger.scope), kind: LOCK_RECOVERY_KIND, target: identity.target,
+            context, payloadDigest: digest, intentRecordedAt: intentAt, expected: {},
+        });
+        const verification = { verifier: run.verifier, ...run.observation, checkedAt: recorder.now() };
+        let completed = null;
+        if (verification.result === 'present') {
+            completed = await recordOutcome(recorder, intent.effectId, { phase: 'completed', payloadDigest: digest, verification, links: options.links });
+        }
+        else {
+            await recordReconciled(recorder, intent.effectId, verification, options.links);
+        }
+        const exitCode = verification.result === 'present' ? EFFECT_EXIT_CODES.ok : verification.result === 'absent' ? EFFECT_EXIT_CODES.absent : EFFECT_EXIT_CODES.unknown;
+        return {
+            outcome: verification.result === 'present' ? 'recovered' : 'refused', lock, inspection: publicInspection(inspection),
+            effectId: intent.effectId, intent, completed, verification, exitCode,
+        };
+    }
+    catch (error) {
+        if (error instanceof EffectLedgerError)
+            throw error;
+        throw new EffectLedgerError('internal', 'Effect ledger lock recovery failed', 'lock-recovery-failed');
+    }
+    finally {
+        await rm(guard, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=lock-recovery.js.map

package/dist/src/effects/reader.js

@@ -0,0 +1,103 @@
+/**
+ * Read-side helpers shared by lookup, verification and purge: the keyring,
+ * decoded segments, and the per-line checks that bind a signed record to its
+ * segment position, chain, scope, identity and key window.
+ */
+import { readFile } from 'node:fs/promises';
+import { canonicalJson } from '../security/artifact-trust.js';
+import { integrityError } from './errors.js';
+import { checkSignature } from './keyring.js';
+import { decodeSegmentLine, effectIdBindingHolds, recordHashFor, signedAt, subjectBindingHolds, } from './records.js';
+import { listWriters, readSegment } from './store.js';
+import { STATEMENT_PAYLOAD_TYPE } from './types.js';
+/** The stored keyring, or null before the first write. Not verified here. */
+export async function readKeyring(paths) {
+    let raw;
+    try {
+        raw = await readFile(paths.keyring, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw integrityError('keyring-malformed');
+    }
+}
+export async function readWriterSegment(paths, writer) {
+    const segment = await readSegment(paths, writer);
+    if (!segment)
+        return null;
+    return {
+        writer,
+        torn: segment.torn,
+        lines: segment.lines.map((text, index) => {
+            const decoded = decodeSegmentLine(text);
+            return 'failure' in decoded ? { writer, index, text, failure: decoded.failure } : { writer, index, text, decoded };
+        }),
+    };
+}
+export async function readAllSegments(paths) {
+    const out = [];
+    for (const writer of await listWriters(paths)) {
+        const segment = await readWriterSegment(paths, writer);
+        if (segment)
+            out.push(segment);
+    }
+    return out;
+}
+/**
+ * Every check that binds one decoded line to its place. Returns the failure
+ * reasons (empty when the line verifies).
+ */
+export function lineFailures(keyring, scope, writer, index, decoded, previousHash) {
+    const failures = [];
+    const { line, payload, statement } = decoded;
+    const predicate = statement.predicate;
+    if (line.writer !== writer || predicate.writer !== writer)
+        failures.push('writer-mismatch');
+    if (line.seq !== index || predicate.seq !== index)
+        failures.push('seq-mismatch');
+    if (predicate.prev !== previousHash)
+        failures.push('chain-broken');
+    if (canonicalJson(predicate.scope) !== canonicalJson(scope))
+        failures.push('scope-mismatch');
+    if (!subjectBindingHolds(statement))
+        failures.push('subject-mismatch');
+    if (!effectIdBindingHolds(predicate))
+        failures.push('effect-id-mismatch');
+    if (predicate.phase === 'tombstone') {
+        if (predicate.tombstone.originalRecordHash !== line.recordHash)
+            failures.push('record-hash-mismatch');
+        if (!keyring.keys.some(key => key.keyid === predicate.tombstone.originalKeyid))
+            failures.push('unknown-keyid');
+    }
+    else if (recordHashFor(payload) !== line.recordHash) {
+        failures.push('record-hash-mismatch');
+    }
+    const at = signedAt(predicate);
+    for (const signature of line.envelope.signatures) {
+        const check = checkSignature(keyring, signature.keyid, signature.sig, STATEMENT_PAYLOAD_TYPE, payload, at);
+        if (check !== 'ok') {
+            failures.push(check);
+            break;
+        }
+    }
+    return [...new Set(failures)];
+}
+/** Merge order for readers: `(recordedAt, writer, seq)`. */
+export function mergeOrder(a, b) {
+    const left = a.statement.predicate;
+    const right = b.statement.predicate;
+    const time = Date.parse(left.recordedAt) - Date.parse(right.recordedAt);
+    if (time !== 0)
+        return time;
+    if (left.writer !== right.writer)
+        return left.writer < right.writer ? -1 : 1;
+    return left.seq - right.seq;
+}
+//# sourceMappingURL=reader.js.map

package/dist/src/effects/records.js

@@ -0,0 +1,114 @@
+/**
+ * Effect record construction and decoding: in-toto Statement v1 predicates,
+ * DSSE envelopes, segment lines and record hashes.
+ *
+ * Verifiers check the exact decoded payload bytes; they never reserialize a
+ * statement before signature verification.
+ *
+ * @see docs/contracts/effect-ledger.v1.md "Envelope and record"
+ */
+import { canonicalJson, decodeBase64, dssePae } from '../security/artifact-trust.js';
+import { integrityError } from './errors.js';
+import { effectIdDerivation, sha256Digest } from './identity.js';
+import { assertDigestOnly } from './redaction.js';
+import { assertEffectSchema, isEffectSchemaValid } from './schema.js';
+import { EFFECT_PREDICATE_TYPE, IN_TOTO_STATEMENT_TYPE, SEGMENT_LINE_SCHEMA_VERSION, STATEMENT_PAYLOAD_TYPE, } from './types.js';
+const sha256Hex = (value) => sha256Digest(value).slice('sha256:'.length);
+/** Wrap a predicate in a Statement whose single subject is the target reference and its digest. */
+export function statementFor(predicate) {
+    const target = predicate.target;
+    if (typeof target !== 'string')
+        throw integrityError('statement-target-missing');
+    return {
+        _type: IN_TOTO_STATEMENT_TYPE,
+        subject: [{ name: target, digest: { sha256: sha256Hex(target) } }],
+        predicateType: EFFECT_PREDICATE_TYPE,
+        predicate,
+    };
+}
+/** `"sha256:"` plus hex SHA-256 of the DSSE PAE of exact payload bytes. */
+export function recordHashFor(payload) {
+    return sha256Digest(dssePae(STATEMENT_PAYLOAD_TYPE, payload));
+}
+/**
+ * Validate, scan and sign a statement into a segment line. `recordHash` is the
+ * PAE hash of the payload, except for a tombstone, which keeps the original.
+ */
+export function signSegmentLine(statement, key, recordHash) {
+    assertDigestOnly(statement);
+    assertEffectSchema('record', statement);
+    const payload = Buffer.from(canonicalJson(statement), 'utf8');
+    const line = {
+        schemaVersion: SEGMENT_LINE_SCHEMA_VERSION,
+        writer: statement.predicate.writer,
+        seq: statement.predicate.seq,
+        recordHash: recordHash ?? recordHashFor(payload),
+        envelope: {
+            payloadType: STATEMENT_PAYLOAD_TYPE,
+            payload: payload.toString('base64'),
+            signatures: [{ keyid: key.keyid, sig: key.signPae(STATEMENT_PAYLOAD_TYPE, payload) }],
+        },
+    };
+    assertEffectSchema('record', line);
+    return line;
+}
+/**
+ * Parse one segment line and its statement. Returns a failure reason instead of
+ * throwing so the verifier can report every broken line.
+ */
+export function decodeSegmentLine(text) {
+    let line;
+    try {
+        line = JSON.parse(text);
+    }
+    catch {
+        return { failure: 'segment-line-malformed' };
+    }
+    if (!isEffectSchemaValid('record', line) || line.envelope === undefined)
+        return { failure: 'segment-line-schema-invalid' };
+    const typed = line;
+    let payload;
+    try {
+        payload = decodeBase64(typed.envelope.payload, 'payload');
+    }
+    catch {
+        return { failure: 'segment-line-malformed' };
+    }
+    let statement;
+    try {
+        statement = JSON.parse(payload.toString('utf8'));
+    }
+    catch {
+        return { failure: 'statement-malformed' };
+    }
+    if (canonicalJson(statement) !== payload.toString('utf8'))
+        return { failure: 'statement-not-canonical' };
+    if (!isEffectSchemaValid('record', statement) || statement.predicate === undefined)
+        return { failure: 'statement-schema-invalid' };
+    return { line: typed, payload, statement: statement };
+}
+/** Recompute a non-tombstone record's ID from its signed identity fields. */
+export function effectIdBindingHolds(predicate) {
+    if (predicate.phase === 'tombstone')
+        return true;
+    try {
+        return effectIdDerivation(predicate.idDerivation).derive({
+            scope: predicate.scope, kind: predicate.kind, target: predicate.target, context: predicate.context,
+        }) === predicate.effectId;
+    }
+    catch {
+        return false;
+    }
+}
+/** The subject binds the target (or, for a tombstone, the effect ID) to its digest. */
+export function subjectBindingHolds(statement) {
+    const [subject] = statement.subject;
+    if (statement.predicate.phase === 'tombstone')
+        return subject.name === `aiwg-effect:${statement.predicate.effectId}`;
+    return subject.name === statement.predicate.target && subject.digest.sha256 === sha256Hex(subject.name);
+}
+/** The time a record's signature must fall inside its key window. */
+export function signedAt(predicate) {
+    return predicate.phase === 'tombstone' ? predicate.tombstone.purgedAt : predicate.recordedAt;
+}
+//# sourceMappingURL=records.js.map

package/dist/src/effects/redaction.js

@@ -0,0 +1,51 @@
+/**
+ * Digest-only guard applied to every effect ledger document before it is
+ * signed or written.
+ *
+ * It composes the D13 restricted-material scan (`assertReviewProjection`,
+ * `src/decision/review/validate.ts`) with the evidence-bundle restricted member
+ * names (`src/evidence/bundle.ts`), plus private-key and token material and the
+ * raw-payload member names the contract forbids. Rejected material is never
+ * echoed.
+ */
+import { assertReviewProjection } from '../decision/review/validate.js';
+import { EVIDENCE_RESTRICTED_KEY } from '../evidence/bundle.js';
+import { EffectLedgerError } from './errors.js';
+/** Raw effect payload members. `payload` is allowed only as the DSSE envelope member. */
+const RAW_PAYLOAD_KEY = /^(?:body|rawBody|raw_body|content|text|request|response|payload)$/;
+/** PEM blocks, base64 PKCS#8 Ed25519 private keys, and common token shapes. */
+const RESTRICTED_MATERIAL = /(?:-----BEGIN [A-Z ]*PRIVATE KEY-----|MC4CAQAwBQYDK2Vw|\b(?:aiwg_(?:at|rt)_[A-Za-z0-9_-]{6,}|gh[opsu]_[A-Za-z0-9]{12,}|github_pat_[A-Za-z0-9_]{12,}|xox[abprs]-[A-Za-z0-9-]{10,}|AKIA[0-9A-Z]{16})\b|\bBearer\s+[A-Za-z0-9._~+/-]{12,})/;
+const restricted = () => new EffectLedgerError('usage', 'Effect ledger documents are digest-only; restricted material was refused', 'restricted-material');
+function visit(value, parentKey) {
+    if (typeof value === 'string') {
+        if (RESTRICTED_MATERIAL.test(value))
+            throw restricted();
+    }
+    else if (Array.isArray(value)) {
+        for (const item of value)
+            visit(item, parentKey);
+    }
+    else if (value && typeof value === 'object') {
+        for (const [key, child] of Object.entries(value)) {
+            const envelopePayload = key === 'payload' && parentKey === 'envelope';
+            if (EVIDENCE_RESTRICTED_KEY.test(key) || (!envelopePayload && RAW_PAYLOAD_KEY.test(key)))
+                throw restricted();
+            visit(child, key);
+        }
+    }
+}
+/** Throw a usage error (exit 2) when `value` carries restricted material or raw payload members. */
+export function assertDigestOnly(value) {
+    try {
+        assertReviewProjection(value);
+    }
+    catch {
+        throw restricted();
+    }
+    visit(value, undefined);
+}
+/** True when `text` contains private-key or token-shaped material. For output canary scans. */
+export function containsRestrictedMaterial(text) {
+    return RESTRICTED_MATERIAL.test(text) || /vault:\/\//i.test(text);
+}
+//# sourceMappingURL=redaction.js.map

package/dist/src/effects/schema.js

@@ -0,0 +1,73 @@
+/**
+ * Runtime validation of every effect ledger document against the committed
+ * v1 schemas (`schemas/effects/*`). Compiled lazily, once per process.
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import { integrityError } from './errors.js';
+export const EFFECT_SCHEMA_IDS = Object.freeze({
+    record: 'https://aiwg.io/schemas/effects/EffectRecord.v1.schema.json',
+    checkpoint: 'https://aiwg.io/schemas/effects/EffectCheckpoint.v1.schema.json',
+    keyring: 'https://aiwg.io/schemas/effects/EffectKeyring.v1.schema.json',
+    verifierResult: 'https://aiwg.io/schemas/effects/EffectVerifierResult.v1.schema.json',
+});
+const SCHEMA_FILES = {
+    record: 'EffectRecord.v1.schema.json',
+    checkpoint: 'EffectCheckpoint.v1.schema.json',
+    keyring: 'EffectKeyring.v1.schema.json',
+    verifierResult: 'EffectVerifierResult.v1.schema.json',
+};
+function packageRoot(start) {
+    let current = resolve(start);
+    for (;;) {
+        try {
+            const pkg = JSON.parse(readFileSync(join(current, 'package.json'), 'utf8'));
+            // The release packager renames the installed package to `@aiwg/cli`.
+            if (pkg.name === 'aiwg' || pkg.name === '@aiwg/cli')
+                return current;
+        }
+        catch { /* keep walking */ }
+        const parent = dirname(current);
+        if (parent === current)
+            throw new Error('effect ledger: could not locate the package root for schemas/effects');
+        current = parent;
+    }
+}
+let validators;
+function compiled() {
+    if (validators)
+        return validators;
+    const directory = join(packageRoot(dirname(fileURLToPath(import.meta.url))), 'schemas', 'effects');
+    const ajv = new Ajv2020({ strict: true, allErrors: true });
+    addFormats(ajv);
+    for (const file of Object.values(SCHEMA_FILES))
+        ajv.addSchema(JSON.parse(readFileSync(join(directory, file), 'utf8')));
+    const entries = Object.keys(EFFECT_SCHEMA_IDS).map((name) => {
+        const validate = ajv.getSchema(EFFECT_SCHEMA_IDS[name]);
+        if (!validate)
+            throw new Error(`effect ledger: schema ${name} did not compile`);
+        return [name, validate];
+    });
+    validators = Object.fromEntries(entries);
+    return validators;
+}
+/** True when `value` conforms to the named v1 schema. */
+export function isEffectSchemaValid(name, value) {
+    return compiled()[name](value) === true;
+}
+/** Instance paths of schema violations, without echoing instance values. */
+export function effectSchemaErrors(name, value) {
+    const validate = compiled()[name];
+    if (validate(value))
+        return [];
+    return (validate.errors ?? []).map(error => `${error.instancePath || '/'} ${error.keyword}`);
+}
+/** Refuse a document that does not conform; the reason names the schema only. */
+export function assertEffectSchema(name, value) {
+    if (!isEffectSchemaValid(name, value))
+        throw integrityError(`schema-invalid:${name}`, `Effect ledger ${name} document does not conform to its v1 schema`);
+}
+//# sourceMappingURL=schema.js.map