@aiwg/cli 2026.9.20 → 2026.9.24

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

@@ -0,0 +1,299 @@
+/**
+ * Tracker verifiers (#2719): `tracker.comment`, `tracker.issue.closed` and
+ * `tracker.pr.merged` for Gitea and GitHub.
+ *
+ * - **Authority.** The tracker comes from `resolveTrackerAuthority` over the
+ *   project config and git remote URLs. A target whose forge is neither the
+ *   internal nor the customer tracker, or whose repository differs from that
+ *   tracker remote, is `unknown` / `tracker-blocked`. The API base is derived
+ *   from the selected remote URL; no host is assumed.
+ * - **Access order.** `chooseTrackerAccess` over the probes a CLI process can
+ *   offer: the tracker HTTP API (with credentials from the existing tracker
+ *   token path, `resolveToken`), then the forge CLI (`gh`, GitHub only). MCP
+ *   is never offered. A blocker is `unknown` / `tracker-blocked`.
+ * - **Matching.** A comment matches exactly when it carries the
+ *   `<!-- aiwg-effect: <id> -->` marker and was written by the pinned tracker
+ *   actor; a merged PR matches its merge commit's `Effect-Id:` trailer.
+ *   Author and time-window matches give `heuristic-match` and never `absent`.
+ * - **Absent.** Only after an authenticated, complete query (every comment
+ *   page read, or an authoritative issue/PR state read) and once the intent is
+ *   older than `minAbsentAgeMs`; a younger intent is `unknown` /
+ *   `consistency-lag`.
+ *
+ * Access material stays inside the transport: evidence carries IDs, SHAs and
+ * digests only, and errors carry fixed messages.
+ *
+ * @see docs/contracts/effect-ledger.v1.md "Tracker verifiers"
+ */
+import { accessSync, constants as fsConstants } from 'node:fs';
+import { delimiter, join } from 'node:path';
+import { resolveToken } from '../../issues/live.js';
+import { chooseTrackerAccess, resolveTrackerAuthority, } from '../../tracker/capability-protocol.js';
+import { ForgeReadError, cliForgeTransport, createForgeReader, forgeEndpointFromRemote, httpForgeTransport, } from '../../tracker/forge-http.js';
+import { sha256Digest } from '../identity.js';
+import { EffectVerifierError } from './types.js';
+export const TRACKER_VERIFIER_VERSION = '1.0.0';
+/** Default minimum intent age before a tracker verifier may answer `absent`. */
+export const DEFAULT_MIN_ABSENT_AGE_MS = 60_000;
+/** Default page bound for a comment scan; more pages is `unknown` / `paging-incomplete`. */
+export const DEFAULT_MAX_COMMENT_PAGES = 100;
+const TARGET = /^(gitea|github):([\w.-]+\/[\w.-]+)#([1-9][0-9]{0,9})$/;
+const OBJECT_ID = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
+const DIGEST = /^sha256:[a-f0-9]{64}$/;
+const MARKER = /<!--\s*aiwg-effect:\s*([^\s<>]+)\s*-->/g;
+const HEURISTIC_SKEW_MS = 60_000;
+/** The hidden marker line a writer embeds in a tracker comment so the verifier can match it exactly. */
+export function renderEffectMarker(effectId) {
+    if (typeof effectId !== 'string' || !/^[A-Za-z0-9_:-]{1,128}$/.test(effectId))
+        throw new TypeError('Effect ID is required');
+    return `<!-- aiwg-effect: ${effectId} -->`;
+}
+/** Effect IDs named by `aiwg-effect` markers in a comment body. */
+export function parseEffectMarkers(body) {
+    return [...String(body ?? '').matchAll(MARKER)].map(match => match[1]);
+}
+/** Values of `Effect-Id:` trailer lines in a commit message. */
+export function parseEffectIdTrailers(message) {
+    return String(message ?? '').split(/\r?\n/).map(line => /^Effect-Id:\s*(\S+)\s*$/i.exec(line)?.[1]).filter((id) => Boolean(id));
+}
+const FAILURE_REASON = {
+    'auth-denied': 'auth-denied',
+    'not-found': 'container-unreadable',
+    'rate-limited': 'rate-limited',
+    'server-error': 'server-error',
+    'network-error': 'network-error',
+    timeout: 'timeout',
+    oversized: 'malformed-response',
+    malformed: 'malformed-response',
+    'unexpected-status': 'server-error',
+};
+async function read(operation) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        if (error instanceof ForgeReadError)
+            throw new EffectVerifierError(FAILURE_REASON[error.code]);
+        if (error instanceof EffectVerifierError)
+            throw error;
+        throw new EffectVerifierError('network-error');
+    }
+}
+function onPath(binary) {
+    const dirs = (process.env.PATH ?? '').split(delimiter).filter(Boolean);
+    const names = process.platform === 'win32' ? [`${binary}.exe`, `${binary}.cmd`, binary] : [binary];
+    return dirs.some(dir => names.some(name => {
+        try {
+            accessSync(join(dir, name), fsConstants.X_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }));
+}
+/** Resolve the tracker lane for a target: authority, remote, access path and reader. Throws `tracker-blocked`. */
+function resolveLane(options, target) {
+    const parsed = TARGET.exec(target);
+    if (!parsed)
+        throw new EffectVerifierError('malformed-response', 'Tracker target must be gitea:owner/repo#N or github:owner/repo#N');
+    const provider = parsed[1];
+    const number = Number(parsed[3]);
+    const authority = resolveTrackerAuthority(options.config, options.remoteUrls);
+    const remotes = options.config?.remotes;
+    let lane = null;
+    if (authority.provider === provider) {
+        lane = { remote: authority.issueTrackerRemote, url: authority.issueTrackerUrl, actor: remotes?.tracker_actor };
+    }
+    else if (authority.customerIssueTrackerRemote && authority.customerProvider === provider) {
+        lane = { remote: authority.customerIssueTrackerRemote, url: authority.customerIssueTrackerUrl, actor: remotes?.customer_tracker_actor };
+    }
+    if (!lane)
+        throw new EffectVerifierError('tracker-blocked');
+    const endpoint = forgeEndpointFromRemote(provider, lane.url);
+    if (!endpoint || endpoint.repository.toLowerCase() !== parsed[2].toLowerCase())
+        throw new EffectVerifierError('tracker-blocked');
+    const laneAuthority = { ...authority, provider, issueTrackerRemote: lane.remote, issueTrackerUrl: lane.url };
+    const token = resolveToken(provider, options.env ?? process.env);
+    const cli = options.cli === false ? null : options.cli ?? {};
+    const cliAvailable = provider === 'github' && cli !== null && (cli.available ?? onPath(cli.binary ?? 'gh'));
+    const probes = [
+        { kind: 'http-api', provider, remoteName: lane.remote, available: Boolean(token), authenticated: Boolean(token) },
+        { kind: 'cli', provider, remoteName: lane.remote, cli: cli?.binary ?? 'gh', available: cliAvailable, ...(cli?.authenticated !== undefined ? { authenticated: cli.authenticated } : {}) },
+    ];
+    const decision = chooseTrackerAccess(laneAuthority, probes);
+    const readerOptions = options.pageSize ? { pageSize: options.pageSize } : {};
+    if (decision.kind === 'http-api' && token) {
+        const transport = httpForgeTransport({ provider, apiBaseUrl: endpoint.apiBaseUrl, token, fetchImpl: options.fetchImpl, maxResponseBytes: options.maxResponseBytes });
+        return { provider, repository: endpoint.repository, number, access: 'http-api', reader: createForgeReader(provider, transport, readerOptions), actor: lane.actor };
+    }
+    if (decision.kind === 'cli' && cli) {
+        const transport = cliForgeTransport({ provider, hostname: endpoint.host, runner: cli.runner, binary: cli.binary, maxResponseBytes: options.maxResponseBytes });
+        return { provider, repository: endpoint.repository, number, access: 'cli', reader: createForgeReader(provider, transport, readerOptions), actor: lane.actor };
+    }
+    throw new EffectVerifierError('tracker-blocked');
+}
+const unknown = (reason, evidence) => ({ result: 'unknown', reason, complete: false, ...(evidence ? { evidence } : {}) });
+/** `absent` once the intent is old enough, else `unknown` / `consistency-lag`. */
+function absentOrLag(options, request, evidence) {
+    const recorded = Date.parse(request.intentRecordedAt);
+    if (!Number.isFinite(recorded))
+        return unknown('malformed-response');
+    const now = (options.now ?? Date.now)();
+    if (now - recorded < (options.minAbsentAgeMs ?? DEFAULT_MIN_ABSENT_AGE_MS))
+        return unknown('consistency-lag', evidence);
+    return { result: 'absent', reason: 'complete-query-no-match', complete: true, evidence };
+}
+const sameLogin = (a, b) => Boolean(a && b && a.toLowerCase() === b.toLowerCase());
+function expectedString(request, name) {
+    const value = request.expected[name] ?? request.context[name];
+    return typeof value === 'string' ? value : undefined;
+}
+function laneEvidence(lane) {
+    return { tracker: lane.provider, repository: lane.repository, number: lane.number, access: lane.access };
+}
+/** `tracker.comment`: target `gitea:owner/repo#N` or `github:owner/repo#N` (an issue or PR). */
+export function trackerCommentVerifier(options) {
+    return {
+        kind: 'tracker.comment',
+        version: TRACKER_VERIFIER_VERSION,
+        canReportAbsent: true,
+        async verify(request) {
+            const lane = resolveLane(options, request.target);
+            const expectedDigest = expectedString(request, 'digest');
+            if (expectedDigest !== undefined && !DIGEST.test(expectedDigest))
+                return unknown('malformed-response');
+            const pinned = lane.actor?.login;
+            const forbidden = lane.actor?.forbid_actors ?? [];
+            const recorded = Date.parse(request.intentRecordedAt);
+            const windowMs = options.heuristicWindowMs ?? 0;
+            const maxPages = options.maxPages ?? DEFAULT_MAX_COMMENT_PAGES;
+            const base = laneEvidence(lane);
+            let foreignMarker = false;
+            let digestMatch = null;
+            let heuristic = null;
+            let scanned = 0;
+            let complete = false;
+            let pages = 0;
+            for (let page = 1; page !== null;) {
+                if (pages >= maxPages)
+                    break;
+                const current = page;
+                const result = await read(() => lane.reader.listIssueComments(lane.repository, lane.number, current, request.signal));
+                pages += 1;
+                for (const comment of result.items) {
+                    scanned += 1;
+                    const authorIsPinned = Boolean(pinned) && sameLogin(comment.author, pinned) && !forbidden.some(name => sameLogin(name, comment.author));
+                    const bodyDigest = sha256Digest(comment.body);
+                    if (parseEffectMarkers(comment.body).includes(request.effectId)) {
+                        if (!authorIsPinned) {
+                            foreignMarker = true;
+                            continue;
+                        }
+                        const evidence = { ...base, commentId: comment.id, bodyDigest, pages, scanned, confidence: 'exact' };
+                        if (expectedDigest !== undefined) {
+                            return bodyDigest === expectedDigest
+                                ? { result: 'present', reason: 'digest-match', complete: true, evidence }
+                                : unknown('evidence-conflict', evidence);
+                        }
+                        return { result: 'present', reason: bodyDigest === request.payloadDigest ? 'digest-match' : 'marker-match', complete: true, evidence };
+                    }
+                    if (!authorIsPinned)
+                        continue;
+                    if (!digestMatch && bodyDigest === (expectedDigest ?? request.payloadDigest))
+                        digestMatch = { id: comment.id, bodyDigest };
+                    const created = comment.createdAt ? Date.parse(comment.createdAt) : Number.NaN;
+                    if (!heuristic && windowMs > 0 && Number.isFinite(recorded) && Number.isFinite(created)
+                        && created >= recorded - HEURISTIC_SKEW_MS && created <= recorded + windowMs)
+                        heuristic = { id: comment.id, bodyDigest };
+                }
+                if (result.nextPage === null) {
+                    complete = result.complete;
+                    page = null;
+                }
+                else if (result.nextPage <= current) {
+                    page = null;
+                }
+                else
+                    page = result.nextPage;
+            }
+            const summary = { ...base, pages, scanned };
+            // A marker for this effect under another author is never ours; escalate instead of replaying.
+            if (foreignMarker)
+                return unknown('evidence-conflict', { ...summary, foreignMarker: true });
+            if (digestMatch) {
+                return { result: 'present', reason: 'digest-match', complete, evidence: { ...summary, commentId: digestMatch.id, bodyDigest: digestMatch.bodyDigest, confidence: 'exact' } };
+            }
+            if (heuristic) {
+                return { result: 'present', reason: 'heuristic-match', complete: false, evidence: { ...summary, commentId: heuristic.id, bodyDigest: heuristic.bodyDigest, confidence: 'heuristic' } };
+            }
+            if (!complete)
+                return unknown('paging-incomplete', summary);
+            return absentOrLag(options, request, { ...summary, found: false });
+        },
+    };
+}
+/** `tracker.issue.closed`: target `gitea:owner/repo#N` or `github:owner/repo#N`. */
+export function trackerIssueClosedVerifier(options) {
+    return {
+        kind: 'tracker.issue.closed',
+        version: TRACKER_VERIFIER_VERSION,
+        canReportAbsent: true,
+        async verify(request) {
+            const lane = resolveLane(options, request.target);
+            const issue = await read(() => lane.reader.getIssue(lane.repository, lane.number, request.signal));
+            const evidence = { ...laneEvidence(lane), state: issue.state, closedAt: issue.closedAt };
+            if (issue.state === 'closed')
+                return { result: 'present', reason: 'state-match', complete: true, evidence };
+            return absentOrLag(options, request, evidence);
+        },
+    };
+}
+/**
+ * `tracker.pr.merged`: target `gitea:owner/repo#N` or `github:owner/repo#N`.
+ * The expected merge commit comes from `expected.object` or `context.object`.
+ */
+export function trackerPrMergedVerifier(options) {
+    return {
+        kind: 'tracker.pr.merged',
+        version: TRACKER_VERIFIER_VERSION,
+        canReportAbsent: true,
+        async verify(request) {
+            const expectedSha = expectedString(request, 'object');
+            if (expectedSha !== undefined && !OBJECT_ID.test(expectedSha))
+                return unknown('malformed-response');
+            const lane = resolveLane(options, request.target);
+            const pr = await read(() => lane.reader.getPullState(lane.repository, lane.number, request.signal));
+            const evidence = {
+                ...laneEvidence(lane), state: pr.state, merged: pr.merged, mergedAt: pr.mergedAt,
+                mergeCommit: pr.mergeCommitSha, expectedMergeCommit: expectedSha ?? null, baseSha: pr.baseSha,
+            };
+            if (!pr.merged)
+                return absentOrLag(options, request, evidence);
+            if (!pr.mergeCommitSha)
+                return unknown(expectedSha ? 'malformed-response' : 'consistency-lag', evidence);
+            if (expectedSha !== undefined && pr.mergeCommitSha !== expectedSha) {
+                // Merged, but not as this effect expected: the expected merge did not happen.
+                return absentOrLag(options, request, { ...evidence, mergeCommitMatch: false });
+            }
+            // The merge commit trailer is a second, exact check; the PR state stays authoritative without it.
+            let marker = null;
+            try {
+                const message = await lane.reader.getCommitMessage(lane.repository, pr.mergeCommitSha, request.signal);
+                marker = message === null ? null : parseEffectIdTrailers(message).includes(request.effectId);
+            }
+            catch {
+                marker = null;
+            }
+            return {
+                result: 'present', reason: marker ? 'marker-match' : 'state-match', complete: true,
+                evidence: { ...evidence, mergeCommitMatch: expectedSha !== undefined ? true : null, marker },
+            };
+        },
+    };
+}
+/** The three tracker verifiers, for `createBuiltinVerifierRegistry(options, createTrackerVerifiers(...))`. */
+export function createTrackerVerifiers(options) {
+    return [trackerCommentVerifier(options), trackerIssueClosedVerifier(options), trackerPrMergedVerifier(options)];
+}
+//# sourceMappingURL=tracker.js.map

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

@@ -0,0 +1,21 @@
+/**
+ * The effect verifier interface (#2718). This is the stable plugin contract
+ * that tracker verifiers (#2719), the `aiwg effect` CLI (#2720) and D13
+ * adoption (#2721) build on. Keep it minimal: additions must be optional.
+ *
+ * @see docs/contracts/effect-ledger.v1.md "Verifier interface"
+ */
+/**
+ * Throw from `verify` to report a classified `unknown`. Any other throw maps to
+ * `unknown` / `server-error`; an abort after the timeout maps to `timeout`.
+ * The message is never recorded.
+ */
+export class EffectVerifierError extends Error {
+    reason;
+    constructor(reason, message = 'Effect verifier could not settle the target') {
+        super(message);
+        this.reason = reason;
+        this.name = 'EffectVerifierError';
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/src/effects/verify.js

@@ -0,0 +1,295 @@
+/**
+ * Whole-ledger verification: keyring, every segment line (signature, key
+ * window, writer and seq binding, chain, record hash, scope, identity), the
+ * index/segment agreement, the local checkpoint chain, and the latest
+ * checkpoint from the independent sink (truncation and deletion).
+ *
+ * @see docs/contracts/effect-ledger.v1.md
+ */
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { canonicalJson } from '../security/artifact-trust.js';
+import { exists } from '../storage/protected-files.js';
+import { EFFECT_EXIT_CODES } from './errors.js';
+import { sha256Digest } from './identity.js';
+import { checkSignature, keyringFailure } from './keyring.js';
+import { lineFailures, readAllSegments, readKeyring } from './reader.js';
+import { isEffectSchemaValid } from './schema.js';
+import { indexName, listIndexEntries, loadIndexKey, readPending } from './store.js';
+import { CHECKPOINT_PAYLOAD_TYPE, } from './types.js';
+/** `"sha256:"` plus hex SHA-256 of `canonicalJson(checkpoint)`, as used by `previousCheckpoint`. */
+export function checkpointDigest(checkpoint) {
+    return sha256Digest(canonicalJson(checkpoint));
+}
+export function checkpointBody(checkpoint) {
+    const { signatures: _signatures, ...body } = checkpoint;
+    return body;
+}
+/**
+ * Digests of the keyring as it stood after each rotation (0..n). A checkpoint's
+ * `keyringDigest` must equal one of them, so a later keyring can only extend
+ * the one the checkpoint anchored, never replace or re-window it.
+ */
+export function keyringPrefixDigests(keyring) {
+    const chain = [keyring.keys.find(key => !keyring.rotations.some(rotation => rotation.to === key.keyid)),
+        ...keyring.rotations.map(rotation => keyring.keys.find(key => key.keyid === rotation.to))];
+    return chain.map((_key, count) => {
+        const keys = chain.slice(0, count + 1).map(key => structuredClone(key));
+        const last = keys[count];
+        if (count < keyring.rotations.length && last.status !== 'revoked') {
+            delete last.validUntil;
+            last.status = 'active';
+        }
+        return sha256Digest(canonicalJson({ ...keyring, keys, rotations: keyring.rotations.slice(0, count) }));
+    });
+}
+/** Schema, scope, root, keyring lineage and signature checks for one checkpoint. Returns a failure reason or null. */
+export function checkpointFailure(checkpoint, keyring, scope) {
+    if (!isEffectSchemaValid('checkpoint', checkpoint))
+        return 'checkpoint-schema-invalid';
+    const value = checkpoint;
+    if (canonicalJson(value.scope) !== canonicalJson(scope))
+        return 'checkpoint-scope-mismatch';
+    const writers = value.writers.map(entry => entry.writer);
+    if (writers.some((writer, index) => index > 0 && writers[index - 1] >= writer))
+        return 'checkpoint-writers-unsorted';
+    if (value.writers.some(entry => entry.segment !== `segments/${entry.writer}.jsonl`))
+        return 'checkpoint-segment-path';
+    if (value.root !== sha256Digest(canonicalJson(value.writers)))
+        return 'checkpoint-root-mismatch';
+    if (!keyringPrefixDigests(keyring).includes(value.keyringDigest))
+        return 'checkpoint-keyring-mismatch';
+    const payload = Buffer.from(canonicalJson(checkpointBody(value)), 'utf8');
+    for (const signature of value.signatures) {
+        const check = checkSignature(keyring, signature.keyid, signature.sig, CHECKPOINT_PAYLOAD_TYPE, payload, value.createdAt);
+        if (check !== 'ok')
+            return `checkpoint-${check}`;
+    }
+    return null;
+}
+export async function readLocalCheckpoints(paths) {
+    let names;
+    try {
+        names = await readdir(paths.checkpoints);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    const out = [];
+    for (const name of names) {
+        const match = /^(0|[1-9][0-9]*)\.json$/.exec(name);
+        if (!match)
+            continue;
+        let value;
+        try {
+            value = JSON.parse(await readFile(join(paths.checkpoints, name), 'utf8'));
+        }
+        catch {
+            value = null;
+        }
+        out.push({ sequence: Number(match[1]), value });
+    }
+    return out.sort((a, b) => a.sequence - b.sequence);
+}
+function verifySegments(segments, keyring, scope, failures) {
+    let records = 0;
+    for (const segment of segments) {
+        if (segment.torn)
+            failures.push({ reason: 'segment-torn', writer: segment.writer, seq: segment.lines.length - 1 });
+        let previous = null;
+        for (const read of segment.lines) {
+            records += 1;
+            if (!read.decoded) {
+                failures.push({ reason: read.failure, writer: segment.writer, seq: read.index });
+                previous = null;
+                continue;
+            }
+            for (const reason of lineFailures(keyring, scope, segment.writer, read.index, read.decoded, previous)) {
+                failures.push({ reason, writer: segment.writer, seq: read.index });
+            }
+            previous = read.decoded.line.recordHash;
+        }
+    }
+    return records;
+}
+async function verifyIndex(paths, segments, scope, failures, warnings) {
+    const hasRecords = segments.some(segment => segment.lines.length > 0);
+    if (!(await exists(paths.indexKey))) {
+        if (hasRecords)
+            failures.push({ reason: 'index-key-missing' });
+        return;
+    }
+    let key;
+    try {
+        key = await loadIndexKey(paths);
+    }
+    catch {
+        failures.push({ reason: 'index-key-malformed' });
+        return;
+    }
+    let entries;
+    try {
+        entries = await listIndexEntries(paths);
+    }
+    catch {
+        failures.push({ reason: 'index-entry-malformed' });
+        return;
+    }
+    const byWriter = new Map(segments.map(segment => [segment.writer, segment]));
+    const claimed = new Set();
+    for (const { name, entry } of entries) {
+        if (name !== indexName(key, scope, entry.effectId, entry.role)) {
+            failures.push({ reason: 'index-name-mismatch', writer: entry.writer, seq: entry.seq });
+            continue;
+        }
+        const read = byWriter.get(entry.writer)?.lines[entry.seq];
+        if (!read) {
+            const pending = await readPending(paths, entry.writer);
+            if (pending?.indexName === name)
+                warnings.push(`pending-append:${entry.writer}:${entry.seq}`);
+            else
+                failures.push({ reason: 'index-dangling', writer: entry.writer, seq: entry.seq });
+            continue;
+        }
+        const predicate = read.decoded?.statement.predicate;
+        const phase = predicate?.phase === 'tombstone' ? predicate.tombstone.originalPhase : predicate?.phase;
+        if (!predicate || predicate.effectId !== entry.effectId || read.decoded.line.recordHash !== entry.recordHash
+            || predicate.payloadDigest !== entry.payloadDigest || phase !== entry.phase
+            || (entry.role === 'intent') !== (phase === 'intent')) {
+            failures.push({ reason: 'index-segment-mismatch', writer: entry.writer, seq: entry.seq });
+            continue;
+        }
+        claimed.add(`${entry.writer}\0${entry.seq}`);
+    }
+    for (const segment of segments) {
+        for (const read of segment.lines) {
+            const predicate = read.decoded?.statement.predicate;
+            if (!predicate)
+                continue;
+            const phase = predicate.phase === 'tombstone' ? predicate.tombstone.originalPhase : predicate.phase;
+            if ((phase === 'intent' || phase === 'completed' || phase === 'failed') && !claimed.has(`${segment.writer}\0${read.index}`)) {
+                failures.push({ reason: 'index-missing', writer: segment.writer, seq: read.index });
+            }
+        }
+    }
+}
+/**
+ * Verify the whole ledger for this scope. Integrity failures are reported, not
+ * thrown (exit 6); an unavailable artifact root still throws (exit 7).
+ */
+export async function verifyLedger(ledger, options = {}) {
+    const paths = ledger.paths();
+    const scope = ledger.scope;
+    const failures = [];
+    const warnings = [];
+    const segments = await readAllSegments(paths);
+    const writers = segments.map(segment => ({
+        writer: segment.writer, count: segment.lines.length, headHash: segment.lines.at(-1)?.decoded?.line.recordHash ?? null,
+    }));
+    const result = (records, checkpoint) => ({
+        ok: failures.length === 0,
+        exitCode: failures.length === 0 ? EFFECT_EXIT_CODES.ok : EFFECT_EXIT_CODES.integrity,
+        scope, records, writers, checkpoint, failures, warnings,
+    });
+    const stored = await readKeyring(paths).catch(() => 'malformed');
+    const localCheckpoints = await readLocalCheckpoints(paths);
+    if (stored === null) {
+        if (segments.some(segment => segment.lines.length) || localCheckpoints.length)
+            failures.push({ reason: 'keyring-missing' });
+        else
+            warnings.push('ledger-empty');
+        return result(0, null);
+    }
+    const ringFailure = stored === 'malformed' ? 'keyring-malformed' : keyringFailure(stored, scope);
+    if (ringFailure) {
+        failures.push({ reason: ringFailure });
+        return result(0, null);
+    }
+    const keyring = stored;
+    if (options.trustedKeyids && !options.trustedKeyids.includes(keyring.keys.find(key => !keyring.rotations.some(rotation => rotation.to === key.keyid)).keyid)) {
+        failures.push({ reason: 'keyring-untrusted' });
+    }
+    const records = verifySegments(segments, keyring, scope, failures);
+    if (options.checkIndex !== false)
+        await verifyIndex(paths, segments, scope, failures, warnings);
+    // Local checkpoint chain.
+    let local = null;
+    for (const [position, entry] of localCheckpoints.entries()) {
+        const failure = checkpointFailure(entry.value, keyring, scope);
+        if (failure) {
+            failures.push({ reason: failure, checkpoint: entry.sequence });
+            local = null;
+            continue;
+        }
+        const value = entry.value;
+        if (value.sequence !== entry.sequence || entry.sequence !== position)
+            failures.push({ reason: 'checkpoint-sequence-gap', checkpoint: entry.sequence });
+        const expectedPrevious = position === 0 ? null : localCheckpoints[position - 1].value;
+        if ((expectedPrevious ? checkpointDigest(expectedPrevious) : null) !== value.previousCheckpoint)
+            failures.push({ reason: 'checkpoint-chain-broken', checkpoint: entry.sequence });
+        local = value;
+    }
+    // Independent sink.
+    const sink = options.sink === undefined ? ledger.sink : options.sink;
+    let anchor = local ? { value: local, source: 'local' } : null;
+    if (sink) {
+        let remote = null;
+        let readable = true;
+        try {
+            remote = await sink.latest(scope);
+        }
+        catch {
+            readable = false;
+            warnings.push('checkpoint-sink-unreadable');
+        }
+        if (readable) {
+            if (remote) {
+                const failure = checkpointFailure(remote, keyring, scope);
+                if (failure)
+                    failures.push({ reason: `sink-${failure}`, checkpoint: remote.sequence });
+                else {
+                    const sameLocal = localCheckpoints.find(entry => entry.sequence === remote.sequence)?.value;
+                    if (sameLocal && checkpointDigest(sameLocal) !== checkpointDigest(remote))
+                        failures.push({ reason: 'checkpoint-divergence', checkpoint: remote.sequence });
+                    if (local && remote.sequence < local.sequence)
+                        failures.push({ reason: 'checkpoint-sink-behind', checkpoint: remote.sequence });
+                    if (!local || remote.sequence > local.sequence) {
+                        if (!sameLocal)
+                            warnings.push('local-checkpoint-behind');
+                        anchor = { value: remote, source: 'sink' };
+                    }
+                    else if (remote.sequence === local.sequence) {
+                        anchor = { value: remote, source: 'sink' };
+                    }
+                }
+            }
+            else if (localCheckpoints.length) {
+                failures.push({ reason: 'checkpoint-sink-missing' });
+            }
+        }
+    }
+    if (!anchor)
+        warnings.push('no-checkpoint');
+    else {
+        const bySegment = new Map(segments.map(segment => [segment.writer, segment]));
+        for (const entry of anchor.value.writers) {
+            const segment = bySegment.get(entry.writer);
+            if (!segment) {
+                failures.push({ reason: 'segment-missing', writer: entry.writer, checkpoint: anchor.value.sequence });
+                continue;
+            }
+            const complete = segment.torn ? segment.lines.length - 1 : segment.lines.length;
+            if (complete < entry.count) {
+                failures.push({ reason: 'segment-truncated', writer: entry.writer, checkpoint: anchor.value.sequence });
+                continue;
+            }
+            if (segment.lines[entry.count - 1].decoded?.line.recordHash !== entry.headHash) {
+                failures.push({ reason: 'checkpoint-head-mismatch', writer: entry.writer, checkpoint: anchor.value.sequence });
+            }
+        }
+    }
+    return result(records, anchor ? { sequence: anchor.value.sequence, source: anchor.source, digest: checkpointDigest(anchor.value) } : null);
+}
+//# sourceMappingURL=verify.js.map

package/dist/src/evidence/bundle.js

@@ -4,6 +4,8 @@ import { promises as fs } from 'node:fs';
 import path from 'node:path';
 const SCHEMA_VERSION = 'aiwg.evidence.bundle/v1';
 const RESTRICTED_KEY = /(?:^|_)(?:content|terminal|prompt|environment|env|credential|secret|password|authorization|bearer|token|private_key|certificate|restricted_(?:url|uri|link))(?:$|_)/i;
+/** Restricted evidence member names; the effect ledger digest-only guard applies the same pattern. */
+export const EVIDENCE_RESTRICTED_KEY = RESTRICTED_KEY;
 const ALLOWED_POLICY_KEYS = new Set(['restricted_content_grants']);
 const EVIDENCE_ROLES = new Set(['activity-export', 'report', 'source', 'eval-config', 'provenance']);
 function sha256(value) {

package/dist/src/extensions/commands/definitions.js

@@ -1468,6 +1468,33 @@ export const artifactsCommand = {
         },
     },
 };
+export const effectCommand = {
+    id: 'effect',
+    type: 'skill',
+    name: 'Effect Ledger',
+    description: 'Record, look up, reconcile and verify side effects in the signed effect ledger',
+    version: '1.0.0',
+    capabilities: ['cli', 'effects', 'idempotency', 'verification', 'signing', 'provenance'],
+    keywords: ['effect', 'aiwg effect', 'effect ledger', 'record an effect', 'sign an effect', 'reconcile effect', 'did this PR merge', 'idempotent side effect', 'effect id', 'stale ledger lock'],
+    category: 'utility',
+    platforms: {
+        claude: 'full',
+        generic: 'full',
+    },
+    deployment: {
+        pathTemplate: '.{platform}/commands/{id}.md',
+        core: true,
+    },
+    metadata: {
+        type: 'skill',
+        triggerPhrases: ['record an effect', 'sign an effect', 'reconcile effect', 'did this PR merge', 'effect ledger', 'idempotent side effect', 'look up an effect', 'verify the effect ledger'],
+        commandHint: {
+            template: 'utility',
+            argumentHint: 'id|intent|record|lookup|reconcile|verify|checkpoint|kinds|keys|recover-lock [options]',
+            allowedTools: ['Read', 'Bash'],
+        },
+    },
+};
 // Research-corpus tools — radar/freshness subsystem (#1498)
 export const corpusCommand = {
     id: 'corpus',
@@ -3789,6 +3816,7 @@ export const commandDefinitions = [
     // Index + Discovery
     indexCommand,
     artifactsCommand,
+    effectCommand,
     corpusCommand,
     researchQueryCommand,
     discoverCommand,