@aiwg/cli 2026.9.19 → 2026.9.21

package/dist/src/effects/store.js

@@ -0,0 +1,239 @@
+/**
+ * Effect ledger storage under the artifact store.
+ *
+ *   effects/<subsystem>/
+ *     segments/<writer-id>.jsonl   one hash-chained segment per writer
+ *     segments/<writer-id>.pending a signed line awaiting append after its index claim
+ *     index/<keyed-name>.json      exclusive-create, one per effect ID (and one per outcome)
+ *     checkpoints/<sequence>.json  EffectCheckpoint.v1
+ *     keyring.json                 EffectKeyring.v1
+ *     index.key                    per-ledger key for index file names
+ *     locks/                       same-host directory locks
+ *
+ * The root resolves only through `projectAiwgWritePath`, which fails closed when
+ * a configured external artifact root is unavailable. Directories are 0700 and
+ * files 0600.
+ */
+import { randomBytes } from 'node:crypto';
+import { lstat, open, readFile, readdir, rename, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { acquireDirectoryLock } from '../artifacts/prebuilt-build-lock.js';
+import { projectAiwgWritePath } from '../config/project-artifacts.js';
+import { canonicalJson } from '../security/artifact-trust.js';
+import { ensurePrivateDirectory, exists, keyedName, publishExclusive, syncDirectory, } from '../storage/protected-files.js';
+import { EffectLedgerError, integrityError } from './errors.js';
+import { assertWriterId, SHA256_DIGEST_PATTERN, WRITER_ID_PATTERN } from './identity.js';
+import { INDEX_SCHEMA_VERSION } from './types.js';
+/** Resolve the ledger root for one subsystem. Throws exit 7 when the artifact root is unavailable. */
+export function resolveLedgerPaths(projectDir, subsystem) {
+    let root;
+    try {
+        root = projectAiwgWritePath(projectDir, 'effects', subsystem);
+    }
+    catch (error) {
+        throw new EffectLedgerError('artifact-root-unavailable', `${error.message} (effect ledger)`, 'artifact-root-unavailable');
+    }
+    return {
+        root,
+        segments: join(root, 'segments'),
+        index: join(root, 'index'),
+        checkpoints: join(root, 'checkpoints'),
+        locks: join(root, 'locks'),
+        keyring: join(root, 'keyring.json'),
+        indexKey: join(root, 'index.key'),
+    };
+}
+const PERMISSIONS_MESSAGE = 'Effect ledger directories must be owner-only (0700)';
+const permissionError = (message) => new EffectLedgerError('integrity', message ?? PERMISSIONS_MESSAGE, 'ledger-permissions');
+export async function ensureLedgerDirectories(paths) {
+    for (const directory of [paths.root, paths.segments, paths.index, paths.checkpoints, paths.locks]) {
+        await ensurePrivateDirectory(directory, PERMISSIONS_MESSAGE, permissionError);
+    }
+}
+export const segmentFile = (paths, writer) => join(paths.segments, `${writer}.jsonl`);
+const pendingFile = (paths, writer) => join(paths.segments, `${writer}.pending`);
+/** Serialize work for one lock name across processes on this host. */
+export async function withLedgerLock(paths, name, timeoutMs, work) {
+    let release;
+    try {
+        release = await acquireDirectoryLock(join(paths.locks, `${name}.lock`), { timeoutMs, pollMs: 20 });
+    }
+    catch {
+        throw new EffectLedgerError('lock-timeout', 'Timed out waiting for the effect ledger lock', 'lock-timeout');
+    }
+    try {
+        return await work();
+    }
+    finally {
+        await release();
+    }
+}
+/** Writers with a segment file, sorted by writer ID. */
+export async function listWriters(paths) {
+    let names;
+    try {
+        names = await readdir(paths.segments);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    return names.filter(name => name.endsWith('.jsonl')).map(name => name.slice(0, -'.jsonl'.length))
+        .filter(writer => WRITER_ID_PATTERN.test(writer)).sort();
+}
+/**
+ * Raw lines of one writer's segment, or null when the segment does not exist.
+ * `torn` is true when the file does not end with a newline.
+ */
+export async function readSegment(paths, writer) {
+    let raw;
+    try {
+        raw = await readFile(segmentFile(paths, writer), 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    if (raw === '')
+        return { lines: [], torn: false };
+    const torn = !raw.endsWith('\n');
+    const lines = raw.split('\n');
+    if (!torn)
+        lines.pop();
+    return { lines, torn };
+}
+/** Append one serialized line and fsync. The caller holds the writer lock. */
+export async function appendSegmentLine(paths, writer, line) {
+    assertWriterId(writer);
+    const file = segmentFile(paths, writer);
+    const created = !(await exists(file));
+    const handle = await open(file, 'a', 0o600);
+    try {
+        await handle.appendFile(`${JSON.stringify(line)}\n`, 'utf8');
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    if (created)
+        await syncDirectory(paths.segments);
+}
+/** Atomically replace a whole segment (purge only). The caller holds the writer lock. */
+export async function replaceSegment(paths, writer, lines) {
+    await replaceFile(paths.segments, segmentFile(paths, writer), lines.map(line => `${line}\n`).join(''));
+}
+/** Write a 0600 file through a temporary name, fsync and rename. */
+export async function replaceFile(directory, file, contents) {
+    const temporary = `${file}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`;
+    const handle = await open(temporary, 'wx', 0o600);
+    try {
+        await handle.writeFile(contents, 'utf8');
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    try {
+        await rename(temporary, file);
+    }
+    catch (error) {
+        await rm(temporary, { force: true });
+        throw error;
+    }
+    await syncDirectory(directory);
+}
+/** The per-ledger index-naming key, created once with an exclusive publish. */
+export async function loadIndexKey(paths) {
+    if (!(await exists(paths.indexKey))) {
+        await publishExclusive(paths.root, paths.indexKey, `${randomBytes(32).toString('hex')}\n`, 'index-key');
+    }
+    const stat = await lstat(paths.indexKey);
+    if (!stat.isFile() || (stat.mode & 0o077) !== 0)
+        throw integrityError('index-key-permissions');
+    const value = (await readFile(paths.indexKey, 'utf8')).trim();
+    if (!/^[a-f0-9]{64}$/.test(value))
+        throw integrityError('index-key-malformed');
+    return Buffer.from(value, 'hex');
+}
+/** Keyed file name, so plaintext effect IDs never appear in directory listings. */
+export function indexName(key, scope, effectId, role) {
+    return `${keyedName(key, `aiwg.effect.index/v1/${role}`, [canonicalJson(scope), effectId])}.json`;
+}
+function isIndexEntry(value) {
+    const entry = value;
+    return !!entry && entry.schemaVersion === INDEX_SCHEMA_VERSION && (entry.role === 'intent' || entry.role === 'outcome')
+        && typeof entry.effectId === 'string' && SHA256_DIGEST_PATTERN.test(entry.payloadDigest)
+        && ['intent', 'completed', 'failed', 'reconciled'].includes(entry.phase)
+        && WRITER_ID_PATTERN.test(entry.writer) && Number.isSafeInteger(entry.seq) && entry.seq >= 0
+        && SHA256_DIGEST_PATTERN.test(entry.recordHash);
+}
+export async function readIndexEntry(paths, name) {
+    let raw;
+    try {
+        raw = await readFile(join(paths.index, name), 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        throw integrityError('index-entry-malformed');
+    }
+    if (!isIndexEntry(value) || `${canonicalJson(value)}\n` !== raw)
+        throw integrityError('index-entry-malformed');
+    return value;
+}
+export async function listIndexEntries(paths) {
+    let names;
+    try {
+        names = await readdir(paths.index);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    const out = [];
+    for (const name of names.filter(file => /^[a-f0-9]{64}\.json$/.test(file)).sort()) {
+        const entry = await readIndexEntry(paths, name);
+        if (entry)
+            out.push({ name, entry });
+    }
+    return out;
+}
+/** Exclusive create. Returns false when another writer already claimed the name. */
+export async function claimIndex(paths, name, entry) {
+    return publishExclusive(paths.index, join(paths.index, name), `${canonicalJson(entry)}\n`, 'index');
+}
+export async function writePending(paths, writer, pending) {
+    await replaceFile(paths.segments, pendingFile(paths, writer), `${canonicalJson(pending)}\n`);
+}
+export async function readPending(paths, writer) {
+    let raw;
+    try {
+        raw = await readFile(pendingFile(paths, writer), 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    try {
+        const value = JSON.parse(raw);
+        return typeof value?.indexName === 'string' && value.line && typeof value.line === 'object' ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function clearPending(paths, writer) {
+    await rm(pendingFile(paths, writer), { force: true });
+}
+//# sourceMappingURL=store.js.map

package/dist/src/effects/types.js

@@ -0,0 +1,49 @@
+/**
+ * Effect ledger v1 vocabulary: the identifiers, phases, kinds and reason codes
+ * pinned by `docs/contracts/effect-ledger.v1.md` and `schemas/effects/*`.
+ */
+export const EFFECT_PREDICATE_TYPE = 'https://aiwg.io/attestations/effect/v1';
+export const IN_TOTO_STATEMENT_TYPE = 'https://in-toto.io/Statement/v1';
+export const STATEMENT_PAYLOAD_TYPE = 'application/vnd.in-toto+json';
+export const CHECKPOINT_PAYLOAD_TYPE = 'application/vnd.aiwg.effect-checkpoint.v1+json';
+export const ROTATION_PAYLOAD_TYPE = 'application/vnd.aiwg.effect-key-rotation.v1+json';
+export const RECORD_SCHEMA_VERSION = 'aiwg.effect.record.v1';
+export const SEGMENT_LINE_SCHEMA_VERSION = 'aiwg.effect.segment-line.v1';
+export const CHECKPOINT_SCHEMA_VERSION = 'aiwg.effect.checkpoint.v1';
+export const KEYRING_SCHEMA_VERSION = 'aiwg.effect.keyring.v1';
+export const ROTATION_SCHEMA_VERSION = 'aiwg.effect.key-rotation.v1';
+export const VERIFIER_RESULT_SCHEMA_VERSION = 'aiwg.effect.verifier-result.v1';
+export const INDEX_SCHEMA_VERSION = 'aiwg.effect.index.v1';
+export const EFFECT_SUBSYSTEMS = ['review', 'job', 'delivery', 'custom'];
+export const EFFECT_PHASES = ['intent', 'completed', 'failed', 'reconciled', 'tombstone'];
+export const CORE_EFFECT_KINDS = [
+    'git.commit',
+    'git.tag',
+    'file.digest',
+    'decision.receipt',
+    'decision.review.continuation',
+    'tracker.comment',
+    'tracker.issue.closed',
+    'tracker.pr.merged',
+];
+export const EFFECT_ID_DERIVATION_NAMES = ['aiwg.effect/v1', 'd13.review/v1'];
+export const PRESENT_REASONS = ['marker-match', 'state-match', 'digest-match', 'heuristic-match'];
+export const ABSENT_REASONS = ['complete-query-no-match'];
+export const UNKNOWN_REASONS = [
+    'verifier-missing',
+    'verifier-version-mismatch',
+    'verifier-cannot-report-absent',
+    'network-error',
+    'timeout',
+    'auth-denied',
+    'rate-limited',
+    'server-error',
+    'container-unreadable',
+    'paging-incomplete',
+    'consistency-lag',
+    'tracker-blocked',
+    'malformed-response',
+    'evidence-conflict',
+];
+export const FAILURE_REASONS = ['target-rejected', 'precondition-failed', 'cancelled-before-dispatch'];
+//# sourceMappingURL=types.js.map

package/dist/src/effects/verifiers/decision.js

@@ -0,0 +1,168 @@
+/**
+ * Built-in `decision.receipt` verifier over the D03 receipt stores and D16 job
+ * items. The `decision.review.continuation` verifier lives in `./review.ts`.
+ *
+ * Target forms (`decision:<receipt-id>`):
+ *
+ * | Target | Source | Store scope from |
+ * |---|---|---|
+ * | `decision:invocation/<invocationId>` | D03 `DecisionReceiptStore.read` | `projectId` |
+ * | `decision:batch/<batchId>` | D03 `BatchReceiptStore.read` | `tenantId`, `projectId` |
+ * | `decision:job/<jobId>/<itemId>` | D16 `JobStore.read`, then the D03 receipt of the item's latest attempt | `tenantId`, `projectId`, `workspaceId`, `principalId` |
+ *
+ * Scope members come from the effect context, falling back to the verifier
+ * options. The expected receipt digest (`artifactDigest` of the receipt) comes
+ * from `expected.digest`, then `context.receiptDigest`; for a job item the
+ * attempt's recorded `receiptDigest` wins.
+ *
+ * @see docs/contracts/effect-ledger.v1.md "Built-in verifiers"
+ */
+import { DecisionReceiptAccessError } from '../../decision/receipts.js';
+import { artifactDigest } from '../../decision/validate.js';
+export const DECISION_RECEIPT_VERIFIER_VERSION = '1.0.0';
+export const REVIEW_CONTINUATION_PLACEHOLDER_VERSION = '0.1.0';
+const DIGEST = /^sha256:[a-f0-9]{64}$/;
+const SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/;
+const unknown = (reason, evidence) => ({ result: 'unknown', reason, complete: false, ...(evidence ? { evidence } : {}) });
+const absent = (evidence) => ({ result: 'absent', reason: 'complete-query-no-match', complete: true, evidence });
+function member(request, options, name) {
+    const value = request.context[name] ?? options[name];
+    return typeof value === 'string' && value ? value : undefined;
+}
+function expectedDigest(request) {
+    const value = request.expected.digest ?? request.context.receiptDigest;
+    if (value === undefined)
+        return undefined;
+    return typeof value === 'string' && DIGEST.test(value) ? value : null;
+}
+/** Store failures are never `absent`: denial is `auth-denied`, anything else (MAC, corruption, I/O) `container-unreadable`. */
+function storeFailure(error) {
+    if (error instanceof DecisionReceiptAccessError)
+        return unknown('auth-denied');
+    return unknown('container-unreadable');
+}
+async function read(load) {
+    try {
+        return { value: await load() };
+    }
+    catch (error) {
+        return { failure: storeFailure(error) };
+    }
+}
+function digestOf(value) {
+    try {
+        return artifactDigest(value);
+    }
+    catch {
+        return null;
+    }
+}
+/** Settle a D03 state machine: completed is present, failed is absent, anything else is unsettled. */
+function settle(state, receipt, expected, base) {
+    if (state === 'completed') {
+        const actual = digestOf(receipt);
+        if (!actual)
+            return unknown('malformed-response');
+        const evidence = { ...base, state, receiptDigest: actual, expectedDigest: expected ?? null };
+        if (expected === undefined)
+            return { result: 'present', reason: 'state-match', complete: true, evidence };
+        return actual === expected
+            ? { result: 'present', reason: 'digest-match', complete: true, evidence }
+            : unknown('evidence-conflict', evidence);
+    }
+    if (state === 'failed')
+        return absent({ ...base, state });
+    return unknown('consistency-lag', { ...base, state });
+}
+/** `decision.receipt`: D03 invocation and batch receipts, and D16 job items. */
+export function decisionReceiptVerifier(options = {}) {
+    return {
+        kind: 'decision.receipt',
+        version: DECISION_RECEIPT_VERIFIER_VERSION,
+        canReportAbsent: true,
+        async verify(request) {
+            if (!request.target.startsWith('decision:'))
+                return unknown('malformed-response');
+            const parts = request.target.slice('decision:'.length).split('/');
+            const expected = expectedDigest(request);
+            if (expected === null)
+                return unknown('malformed-response');
+            if (!parts.slice(1).every(part => SEGMENT.test(part)))
+                return unknown('malformed-response');
+            if (parts[0] === 'invocation' && parts.length === 2) {
+                const projectId = member(request, options, 'projectId');
+                if (!options.receipts || !projectId)
+                    return unknown('container-unreadable');
+                const loaded = await read(() => options.receipts.read(parts[1], projectId));
+                if ('failure' in loaded)
+                    return loaded.failure;
+                const base = { source: 'd03-invocation', invocationId: parts[1] };
+                if (!loaded.value)
+                    return absent({ ...base, found: false });
+                const fingerprint = request.context.fingerprint;
+                if (typeof fingerprint === 'string' && fingerprint !== loaded.value.fingerprint)
+                    return unknown('evidence-conflict', { ...base, found: true });
+                return settle(loaded.value.state, loaded.value, expected, base);
+            }
+            if (parts[0] === 'batch' && parts.length === 2) {
+                const tenantId = member(request, options, 'tenantId');
+                const projectId = member(request, options, 'projectId');
+                if (!options.batches || !tenantId || !projectId)
+                    return unknown('container-unreadable');
+                const loaded = await read(() => options.batches.read(parts[1], tenantId, projectId));
+                if ('failure' in loaded)
+                    return loaded.failure;
+                const base = { source: 'd03-batch', batchId: parts[1] };
+                if (!loaded.value)
+                    return absent({ ...base, found: false });
+                return settle(loaded.value.status, loaded.value, expected, base);
+            }
+            if (parts[0] === 'job' && parts.length === 3) {
+                const scope = {
+                    tenantId: member(request, options, 'tenantId'), projectId: member(request, options, 'projectId'),
+                    workspaceId: member(request, options, 'workspaceId'), principalId: member(request, options, 'principalId'),
+                };
+                if (!options.jobs || !options.receipts || Object.values(scope).some(value => value === undefined))
+                    return unknown('container-unreadable');
+                const [, jobId, itemId] = parts;
+                const base = { source: 'd16-job-item', jobId, itemId };
+                const job = await read(() => options.jobs.read(scope, jobId));
+                if ('failure' in job)
+                    return job.failure;
+                if (!job.value)
+                    return absent({ ...base, found: false });
+                // A deleted (D10-tombstoned) job cannot speak for its items.
+                if (job.value.deleted)
+                    return unknown('container-unreadable', { ...base, deleted: true });
+                const item = job.value.job.items.find(candidate => candidate.id === itemId);
+                if (!item)
+                    return absent({ ...base, found: false });
+                const attempt = item.attempts.at(-1);
+                if (!attempt)
+                    return absent({ ...base, itemState: item.state, attempts: 0 });
+                const receipt = await read(() => options.receipts.read(attempt.id, scope.projectId));
+                if ('failure' in receipt)
+                    return receipt.failure;
+                const attemptBase = { ...base, itemState: item.state, attemptId: attempt.id, attemptOutcome: attempt.outcome };
+                if (!receipt.value)
+                    return absent({ ...attemptBase, found: false });
+                return settle(receipt.value.state, receipt.value, attempt.receiptDigest ?? expected, attemptBase);
+            }
+            return unknown('malformed-response');
+        },
+    };
+}
+/**
+ * @deprecated Replaced by `reviewContinuationVerifier` (#2721) and no longer a
+ * built-in. It always returns `unknown` / `verifier-missing` and can never
+ * report `absent`; kept only so existing imports keep compiling.
+ */
+export function reviewContinuationPlaceholderVerifier() {
+    return {
+        kind: 'decision.review.continuation',
+        version: REVIEW_CONTINUATION_PLACEHOLDER_VERSION,
+        canReportAbsent: false,
+        async verify() { return unknown('verifier-missing'); },
+    };
+}
+//# sourceMappingURL=decision.js.map

package/dist/src/effects/verifiers/file.js

@@ -0,0 +1,106 @@
+/**
+ * Built-in `file.digest` verifier: a realpath-contained regular file exists
+ * with the expected SHA-256.
+ *
+ * Target `file:<path>@sha256:<hex>`; `<path>` is relative to the configured
+ * root (an absolute path must lie inside it). A lexical or symlink escape from
+ * the root is `unknown` / `container-unreadable`, never `absent`.
+ *
+ * @see docs/contracts/effect-ledger.v1.md "Built-in verifiers"
+ */
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { lstat, realpath } from 'node:fs/promises';
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+export const FILE_DIGEST_VERIFIER_VERSION = '1.0.0';
+const TARGET = /^file:(.+)@(sha256:[a-f0-9]{64})$/;
+const unknown = (reason) => ({ result: 'unknown', reason, complete: false });
+function inside(root, candidate) {
+    const rel = relative(root, candidate);
+    return rel === '' ? false : !rel.startsWith(`..${sep}`) && rel !== '..' && !isAbsolute(rel);
+}
+const errno = (error) => error?.code;
+async function sha256File(path, signal) {
+    const hash = createHash('sha256');
+    for await (const chunk of createReadStream(path, { signal }))
+        hash.update(chunk);
+    return `sha256:${hash.digest('hex')}`;
+}
+export function fileDigestVerifier(options) {
+    if (!options || typeof options.root !== 'string' || !options.root)
+        throw new TypeError('file.digest verifier needs a root');
+    const configuredRoot = resolve(options.root);
+    return {
+        kind: 'file.digest',
+        version: FILE_DIGEST_VERIFIER_VERSION,
+        canReportAbsent: true,
+        async verify(request) {
+            const match = TARGET.exec(request.target);
+            if (!match)
+                return unknown('malformed-response');
+            const [, path, digest] = match;
+            const expected = request.expected.digest ?? request.context.digest;
+            if (expected !== undefined && expected !== digest)
+                return unknown('evidence-conflict');
+            let root;
+            try {
+                root = await realpath(configuredRoot);
+            }
+            catch {
+                return unknown('container-unreadable');
+            }
+            // An absolute path spelled under the configured (non-canonical) root is rebased onto its realpath.
+            const lexical = isAbsolute(path) && inside(configuredRoot, resolve(path))
+                ? resolve(root, relative(configuredRoot, resolve(path)))
+                : resolve(root, path);
+            if (!inside(root, lexical))
+                return unknown('container-unreadable');
+            let real;
+            try {
+                real = await realpath(lexical);
+            }
+            catch (error) {
+                if (errno(error) !== 'ENOENT' && errno(error) !== 'ENOTDIR')
+                    return unknown('container-unreadable');
+                // Missing: `absent` only when the nearest existing ancestor is itself contained.
+                let parent = dirname(lexical);
+                for (;;) {
+                    try {
+                        const realParent = await realpath(parent);
+                        if (realParent !== root && !inside(root, realParent))
+                            return unknown('container-unreadable');
+                        break;
+                    }
+                    catch (inner) {
+                        if (errno(inner) !== 'ENOENT' && errno(inner) !== 'ENOTDIR')
+                            return unknown('container-unreadable');
+                        if (parent === dirname(parent))
+                            return unknown('container-unreadable');
+                        parent = dirname(parent);
+                    }
+                }
+                const evidence = { path, expectedDigest: digest, found: false };
+                return { result: 'absent', reason: 'complete-query-no-match', complete: true, evidence };
+            }
+            if (!inside(root, real))
+                return unknown('container-unreadable');
+            let actual;
+            try {
+                const stats = await lstat(real);
+                if (!stats.isFile())
+                    return unknown('evidence-conflict');
+                actual = await sha256File(real, request.signal);
+            }
+            catch (error) {
+                if (request.signal.aborted)
+                    throw error;
+                return unknown('container-unreadable');
+            }
+            const evidence = { path, expectedDigest: digest, actualDigest: actual, found: true };
+            return actual === digest
+                ? { result: 'present', reason: 'digest-match', complete: true, evidence }
+                : { result: 'absent', reason: 'complete-query-no-match', complete: true, evidence };
+        },
+    };
+}
+//# sourceMappingURL=file.js.map