wicked-crew 0.7.28 → 0.7.29

package/dist/cli/governance.d.ts

@@ -0,0 +1,131 @@
+/**
+ * `wicked-crew governance replay <outbox> [--governance-db <path> | --db <core db>] [--dry-run]`
+ * (crew#495, F-022): drain a dead-letter outbox back into the governance store.
+ *
+ * The engine spools every `wicked.*` event it could not store as one NDJSON line (`emit.rs`
+ * `spool_record`: the envelope plus `deadletter_reason`, and — on engines carrying crew#495's
+ * companion — `ts`, `pid`, `origin`). This command hands that file to the engine, which writes
+ * each record as the EVENT node it should have been, restoring the original `ts` where the record
+ * carries one so an id-ordered scan of the store is still chronological.
+ *
+ * Drain order matters, because the daemon may be appending to the SAME file while this runs:
+ *   1. RENAME the outbox to `<outbox>.replayed-<ISO>` first — atomic, so the daemon's next spool
+ *      recreates a fresh file and no entry is lost between the read and the archive;
+ *   2. replay from the archived file;
+ *   3. APPEND the entries that failed to land back onto the live outbox — they stay dead letters,
+ *      visible on `/diagnostics`, and the archive keeps the full record of what was attempted.
+ * `--dry-run` folds the outbox in place (count, types, reasons, timestamp range) and moves nothing.
+ *
+ * Target store resolution is `serve`'s (`core/governance-store.ts`): `--governance-db` ›
+ * `WICKED_CREW_GOVERNANCE_DB` › an inherited `WICKED_ESTATE_DB` › `<core db>.governance/
+ * governance.db`, with `--db` naming the core db (default: the state home's `core.db`).
+ *
+ * Exit codes: 0 every entry landed (or dry run); 1 some entries failed (they are back on the
+ * outbox); 2 the installed engine cannot replay (`Core.replayEmitOutbox` absent — upgrade
+ * wicked-core-ts), or the arguments are wrong.
+ */
+import { Transform, type TransformCallback } from 'node:stream';
+import { type GovernanceStoreLocation } from '../core/governance-store.js';
+import { foldDeadletters, type DeadletterFold } from '../api/governance-health.js';
+export declare const GOVERNANCE_USAGE: string;
+/** crew's own package version, for the origin stamp the engine copies onto dead-letter records. */
+export declare function crewPackageVersion(): string;
+export declare class UsageError extends Error {
+    constructor(message: string);
+}
+/** The non-flag arguments, in order (`--dry-run` takes no value; `--db` / `--governance-db` do). */
+export declare function positionalArgs(args: string[]): string[];
+/** Resolve the target store for a replay — `serve`'s rule, over the core db named (or defaulted),
+ *  with the cross-product bus resolved the way `serve` resolves it (`WICKED_BUS_DB` ›
+ *  `WICKED_BUS_DATA_DIR` › `<core db>.bus/bus.db`) so the bus db is refused as a target here too. */
+export declare function replayTarget(args: string[], env?: NodeJS.ProcessEnv): GovernanceStoreLocation;
+/** The archive name a drained outbox is renamed to: timestamp + pid + a random nonce, so two replays
+ *  of the same outbox in the same millisecond (or two processes) can never pick one name and have a
+ *  later rename replace the earlier archive — the full recovery/audit copy. */
+export declare function archiveNameFor(outbox: string, now?: Date, nonce?: string): string;
+/**
+ * Put the lines that did not land back onto the live outbox — and if THAT write fails (permissions,
+ * a full disk), say exactly where they are: the archive is retained (nothing is lost on disk), but
+ * `/diagnostics` folds only the live path, so without this the operator would see fewer dead letters
+ * than exist.
+ */
+export declare function appendFailedLines(outbox: string, archive: string, lines: string[]): void;
+/**
+ * The caveat a replay that found entries `already_present` must state when the outbox holds
+ * UNTIMESTAMPED (pre-stamp) entries: replay ids are content-addressed, and with no stamp to tell
+ * them apart, byte-identical unstamped lines share one id — two dead letters of the same event land
+ * once. `null` when there is nothing to say.
+ */
+export declare function conflationNote(alreadyPresent: number, fold: Pick<DeadletterFold, 'untimestamped'>): string | null;
+/**
+ * Keep every NDJSON record whole while streaming one file onto another that a concurrent writer may
+ * also be appending to. Every chunk this transform emits is a whole number of records — it buffers
+ * up to the last `\n` it has seen and holds the partial tail until more arrives — so an `O_APPEND`
+ * write from the other writer landing between two of our writes can only ever sit BETWEEN records,
+ * never inside one (read-stream chunks are 64 KiB and not line-aligned; forwarding them raw would
+ * let a fresh record be spliced into the middle of an archived one). Two repairs ride INSIDE the
+ * data writes, never as separate writes a concurrent spool could slip in front of: a leading `\n`
+ * always opens the first emitted chunk (the live file may gain a torn tail between any look and
+ * our first write — a check-then-write cannot close that, an unconditional separator does; an
+ * empty NDJSON line is skipped by every reader), and a source whose last record lacks its newline
+ * gets one appended to that same final write.
+ */
+export declare class LineBoundaryGuard extends Transform {
+    private readonly leading;
+    private carry;
+    private first;
+    constructor(leading: boolean);
+    /** Push one chunk of whole records, opening the very first with the leading separator. */
+    private pushRecords;
+    _transform(chunk: Buffer | string, _enc: BufferEncoding, cb: TransformCallback): void;
+    _flush(cb: TransformCallback): void;
+}
+/**
+ * Append NDJSON lines to a live outbox a daemon may be writing — ONE `write()`, ALWAYS behind a
+ * `\n`: the file may be absent, at a boundary, or mid-record at the instant of the write, and no
+ * look beforehand can know which (the engine writes a record and its newline as two syscalls), so
+ * an unconditional separator is the only race-free choice. At worst it is an empty line, which
+ * every reader — the fold, the engine's replay — skips.
+ */
+export declare function appendLines(outbox: string, lines: string[]): void;
+/**
+ * Put an archived outbox back after a replay that threw — APPEND-ONLY, never a rename over the
+ * live path: a daemon can create a fresh outbox at any instant, and an `exists`-then-`rename` would
+ * replace it and lose what it had just spooled. Appending (`O_APPEND`, so a concurrent spool is
+ * never clobbered — the file is created if absent) is loss-free in every interleaving; the cost is
+ * the two batches' relative order when the daemon did spool meanwhile (each entry carries its own
+ * `ts` on a stamping engine). Streamed, never the whole archive in memory, through
+ * {@link LineBoundaryGuard}: whole records per write, the live tail separated first, a torn last
+ * record terminated in its own write. The archive is removed only after its last byte is on the
+ * live outbox.
+ */
+export declare function restoreOutbox(outbox: string, archive: string): Promise<void>;
+export interface ReplayOutcome {
+    outbox: string;
+    store: {
+        path: string;
+        source: string;
+    };
+    archive: string | null;
+    read: number;
+    replayed: number;
+    /** Entries an earlier replay had already landed (a re-replay is a no-op); `null` on an engine that does not report it. */
+    alreadyPresent: number | null;
+    failed: number;
+    dryRun: boolean;
+    /** The conflation caveat (see `conflationNote`), or `null`. */
+    note: string | null;
+    fold?: Awaited<ReturnType<typeof foldDeadletters>>;
+}
+/**
+ * The command body, separated from process I/O so a test can drive it. Returns the outcome and the
+ * exit code; throws {@link UsageError} for bad arguments and {@link GovernanceReplayUnsupportedError}
+ * on an addon without the binding (the CLI maps both to exit 2).
+ */
+export declare function replayOutbox(args: string[], env?: NodeJS.ProcessEnv): Promise<{
+    outcome: ReplayOutcome;
+    exitCode: 0 | 1;
+}>;
+/** The `wicked-crew governance …` entry: prints a JSON outcome and exits with the documented code. */
+export declare function runGovernance(argv: string[]): Promise<void>;
+//# sourceMappingURL=governance.d.ts.map

package/dist/cli/governance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"governance.d.ts","sourceRoot":"","sources":["../../src/cli/governance.ts"],"names":[],"mappings":"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"}

package/dist/cli/governance.js

@@ -0,0 +1,354 @@
+/**
+ * `wicked-crew governance replay <outbox> [--governance-db <path> | --db <core db>] [--dry-run]`
+ * (crew#495, F-022): drain a dead-letter outbox back into the governance store.
+ *
+ * The engine spools every `wicked.*` event it could not store as one NDJSON line (`emit.rs`
+ * `spool_record`: the envelope plus `deadletter_reason`, and — on engines carrying crew#495's
+ * companion — `ts`, `pid`, `origin`). This command hands that file to the engine, which writes
+ * each record as the EVENT node it should have been, restoring the original `ts` where the record
+ * carries one so an id-ordered scan of the store is still chronological.
+ *
+ * Drain order matters, because the daemon may be appending to the SAME file while this runs:
+ *   1. RENAME the outbox to `<outbox>.replayed-<ISO>` first — atomic, so the daemon's next spool
+ *      recreates a fresh file and no entry is lost between the read and the archive;
+ *   2. replay from the archived file;
+ *   3. APPEND the entries that failed to land back onto the live outbox — they stay dead letters,
+ *      visible on `/diagnostics`, and the archive keeps the full record of what was attempted.
+ * `--dry-run` folds the outbox in place (count, types, reasons, timestamp range) and moves nothing.
+ *
+ * Target store resolution is `serve`'s (`core/governance-store.ts`): `--governance-db` ›
+ * `WICKED_CREW_GOVERNANCE_DB` › an inherited `WICKED_ESTATE_DB` › `<core db>.governance/
+ * governance.db`, with `--db` naming the core db (default: the state home's `core.db`).
+ *
+ * Exit codes: 0 every entry landed (or dry run); 1 some entries failed (they are back on the
+ * outbox); 2 the installed engine cannot replay (`Core.replayEmitOutbox` absent — upgrade
+ * wicked-core-ts), or the arguments are wrong.
+ */
+import { appendFileSync, createReadStream, createWriteStream, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { fileURLToPath } from 'node:url';
+import { randomBytes } from 'node:crypto';
+import { CoreAdapter, GovernanceReplayUnsupportedError } from '../core/adapter.js';
+import { CrewBusError, resolveCrewBus } from '../interactive/bus-location.js';
+import { EMIT_DEADLETTER_ENGINE_ENV, ESTATE_DB_ENGINE_ENV, GOVERNANCE_DB_ENV, GOVERNANCE_DB_FLAG, GovernanceStoreError, isStoreSpec, resolveGovernanceStore, } from '../core/governance-store.js';
+import { foldDeadletters } from '../api/governance-health.js';
+import { crewStateHome } from '../projects/state-home.js';
+export const GOVERNANCE_USAGE = 'Usage: wicked-crew governance replay <outbox.ndjson> [--governance-db <path> | --db <core db>] [--dry-run]\n' +
+    '\n' +
+    'Replay a dead-letter outbox (the engine\'s NDJSON spool of governance events it could not store)\n' +
+    'into the governance store. Resolution of the store matches `serve`:\n' +
+    `  ${GOVERNANCE_DB_FLAG} <path>  explicit store (env: ${GOVERNANCE_DB_ENV}; an inherited ${ESTATE_DB_ENGINE_ENV} is honoured next)\n` +
+    '  --db <path>              the core db whose sidecar store is the default target (<core db>.governance/governance.db;\n' +
+    '                           default core db: ~/.wicked-crew/core.db)\n' +
+    '  --dry-run                fold the outbox (count, types, reasons, timestamp range) and move nothing\n' +
+    '\n' +
+    'The outbox is archived to <outbox>.replayed-<timestamp> BEFORE replay (so a running daemon\'s next\n' +
+    'spool starts a fresh file); entries that fail to land are appended back onto the outbox.\n' +
+    `A daemon's own outbox is <core db>.governance/emit-outbox.ndjson (env: ${EMIT_DEADLETTER_ENGINE_ENV});\n` +
+    'a pre-fix engine wrote ~/.something-wicked/wicked-apps/emit-outbox.ndjson.';
+/** crew's own package version, for the origin stamp the engine copies onto dead-letter records. */
+export function crewPackageVersion() {
+    try {
+        const raw = readFileSync(fileURLToPath(new URL('../../package.json', import.meta.url)), 'utf8');
+        return JSON.parse(raw).version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+function flag(args, name) {
+    const i = args.indexOf(name);
+    return i >= 0 ? args[i + 1] : undefined;
+}
+/** A flag that was given must carry a value, and the value must not be another flag. */
+function flagValue(args, name) {
+    if (!args.includes(name))
+        return undefined;
+    const value = flag(args, name);
+    if (value === undefined || value.startsWith('-')) {
+        throw new UsageError(`${name} requires a value (got: ${value ?? '(missing)'})`);
+    }
+    return value;
+}
+export class UsageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'UsageError';
+    }
+}
+/** The flags that take a value — their value is never a positional. */
+const VALUE_FLAGS = new Set(['--db', GOVERNANCE_DB_FLAG]);
+/** The non-flag arguments, in order (`--dry-run` takes no value; `--db` / `--governance-db` do). */
+export function positionalArgs(args) {
+    const out = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const a = args[i];
+        if (VALUE_FLAGS.has(a)) {
+            i += 1; // skip the flag's value
+            continue;
+        }
+        if (a.startsWith('-'))
+            continue;
+        out.push(a);
+    }
+    return out;
+}
+/** Resolve the target store for a replay — `serve`'s rule, over the core db named (or defaulted),
+ *  with the cross-product bus resolved the way `serve` resolves it (`WICKED_BUS_DB` ›
+ *  `WICKED_BUS_DATA_DIR` › `<core db>.bus/bus.db`) so the bus db is refused as a target here too. */
+export function replayTarget(args, env = process.env) {
+    const coreDbPath = flagValue(args, '--db') ?? join(crewStateHome(), 'core.db');
+    const bus = resolveCrewBus({ explicitDb: env['WICKED_BUS_DB'], envDataDir: env['WICKED_BUS_DATA_DIR'], coreDbPath });
+    return resolveGovernanceStore({
+        flagDb: flagValue(args, GOVERNANCE_DB_FLAG),
+        envCrewDb: env[GOVERNANCE_DB_ENV],
+        envEstateDb: env[ESTATE_DB_ENGINE_ENV],
+        coreDbPath,
+        busDbPath: bus.dbPath,
+    });
+}
+/** The archive name a drained outbox is renamed to: timestamp + pid + a random nonce, so two replays
+ *  of the same outbox in the same millisecond (or two processes) can never pick one name and have a
+ *  later rename replace the earlier archive — the full recovery/audit copy. */
+export function archiveNameFor(outbox, now = new Date(), nonce = randomBytes(3).toString('hex')) {
+    return `${outbox}.replayed-${now.toISOString().replace(/[:.]/g, '-')}-${process.pid}-${nonce}`;
+}
+/** A fresh archive name that does not exist yet (the nonce makes a collision astronomically
+ *  unlikely; the check makes it impossible to rename over an existing archive). */
+function reserveArchiveName(outbox) {
+    for (;;) {
+        const candidate = archiveNameFor(outbox);
+        if (!existsSync(candidate))
+            return candidate;
+    }
+}
+/**
+ * Put the lines that did not land back onto the live outbox — and if THAT write fails (permissions,
+ * a full disk), say exactly where they are: the archive is retained (nothing is lost on disk), but
+ * `/diagnostics` folds only the live path, so without this the operator would see fewer dead letters
+ * than exist.
+ */
+export function appendFailedLines(outbox, archive, lines) {
+    try {
+        appendLines(outbox, lines);
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        throw new Error(`${lines.length} line(s) that failed to replay could not be written back to ${outbox} — they remain in the ` +
+            `retained archive ${archive} (nothing is lost; /diagnostics does not fold the archive): ${reason}`);
+    }
+}
+/**
+ * The caveat a replay that found entries `already_present` must state when the outbox holds
+ * UNTIMESTAMPED (pre-stamp) entries: replay ids are content-addressed, and with no stamp to tell
+ * them apart, byte-identical unstamped lines share one id — two dead letters of the same event land
+ * once. `null` when there is nothing to say.
+ */
+export function conflationNote(alreadyPresent, fold) {
+    if (alreadyPresent <= 0 || fold.untimestamped <= 0)
+        return null;
+    return (`${alreadyPresent} entr${alreadyPresent === 1 ? 'y was' : 'ies were'} already on the store. This outbox holds ` +
+        `${fold.untimestamped} untimestamped (pre-stamp) entr${fold.untimestamped === 1 ? 'y' : 'ies'}: byte-identical ` +
+        'unstamped lines share one replay id, so two dead letters of the same event land once (stamped lines never conflate ' +
+        'unless their ts and content both match).');
+}
+const NL = 0x0a;
+/**
+ * Keep every NDJSON record whole while streaming one file onto another that a concurrent writer may
+ * also be appending to. Every chunk this transform emits is a whole number of records — it buffers
+ * up to the last `\n` it has seen and holds the partial tail until more arrives — so an `O_APPEND`
+ * write from the other writer landing between two of our writes can only ever sit BETWEEN records,
+ * never inside one (read-stream chunks are 64 KiB and not line-aligned; forwarding them raw would
+ * let a fresh record be spliced into the middle of an archived one). Two repairs ride INSIDE the
+ * data writes, never as separate writes a concurrent spool could slip in front of: a leading `\n`
+ * always opens the first emitted chunk (the live file may gain a torn tail between any look and
+ * our first write — a check-then-write cannot close that, an unconditional separator does; an
+ * empty NDJSON line is skipped by every reader), and a source whose last record lacks its newline
+ * gets one appended to that same final write.
+ */
+export class LineBoundaryGuard extends Transform {
+    leading;
+    carry = Buffer.alloc(0);
+    first = true;
+    constructor(leading) {
+        super();
+        this.leading = leading;
+    }
+    /** Push one chunk of whole records, opening the very first with the leading separator. */
+    pushRecords(data) {
+        let out = data;
+        if (this.first) {
+            this.first = false;
+            if (this.leading)
+                out = Buffer.concat([Buffer.from('\n'), out]);
+        }
+        this.push(out);
+    }
+    _transform(chunk, _enc, cb) {
+        const data = Buffer.concat([this.carry, Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)]);
+        const lastNl = data.lastIndexOf(NL);
+        if (lastNl < 0) {
+            this.carry = data; // no complete record yet — hold everything
+        }
+        else {
+            this.pushRecords(data.subarray(0, lastNl + 1)); // whole records only
+            this.carry = data.subarray(lastNl + 1); // the partial tail, if any
+        }
+        cb();
+    }
+    _flush(cb) {
+        if (this.carry.length > 0) {
+            this.pushRecords(Buffer.concat([this.carry, Buffer.from('\n')])); // the torn last record, terminated in the same write
+            this.carry = Buffer.alloc(0);
+        }
+        cb();
+    }
+}
+/**
+ * Append NDJSON lines to a live outbox a daemon may be writing — ONE `write()`, ALWAYS behind a
+ * `\n`: the file may be absent, at a boundary, or mid-record at the instant of the write, and no
+ * look beforehand can know which (the engine writes a record and its newline as two syscalls), so
+ * an unconditional separator is the only race-free choice. At worst it is an empty line, which
+ * every reader — the fold, the engine's replay — skips.
+ */
+export function appendLines(outbox, lines) {
+    if (lines.length === 0)
+        return;
+    appendFileSync(outbox, `\n${lines.join('\n')}\n`, 'utf8');
+}
+/**
+ * Put an archived outbox back after a replay that threw — APPEND-ONLY, never a rename over the
+ * live path: a daemon can create a fresh outbox at any instant, and an `exists`-then-`rename` would
+ * replace it and lose what it had just spooled. Appending (`O_APPEND`, so a concurrent spool is
+ * never clobbered — the file is created if absent) is loss-free in every interleaving; the cost is
+ * the two batches' relative order when the daemon did spool meanwhile (each entry carries its own
+ * `ts` on a stamping engine). Streamed, never the whole archive in memory, through
+ * {@link LineBoundaryGuard}: whole records per write, the live tail separated first, a torn last
+ * record terminated in its own write. The archive is removed only after its last byte is on the
+ * live outbox.
+ */
+export async function restoreOutbox(outbox, archive) {
+    if (statSync(archive).size > 0) {
+        await pipeline(createReadStream(archive), new LineBoundaryGuard(true), createWriteStream(outbox, { flags: 'a' }));
+    }
+    rmSync(archive);
+}
+/**
+ * The command body, separated from process I/O so a test can drive it. Returns the outcome and the
+ * exit code; throws {@link UsageError} for bad arguments and {@link GovernanceReplayUnsupportedError}
+ * on an addon without the binding (the CLI maps both to exit 2).
+ */
+export async function replayOutbox(args, env = process.env) {
+    const outboxArg = positionalArgs(args)[0];
+    if (outboxArg === undefined)
+        throw new UsageError('missing <outbox.ndjson>');
+    const outbox = resolve(outboxArg);
+    if (!existsSync(outbox))
+        throw new UsageError(`outbox not found: ${outbox}`);
+    const dryRun = args.includes('--dry-run');
+    const store = replayTarget(args, env);
+    if (dryRun) {
+        // A dry run folds the FILE and touches no store — so the same target configuration a daemon
+        // runs with (`:memory:` included) is inspectable; the refusal below guards only a real replay.
+        const fold = await foldDeadletters(outbox);
+        return {
+            outcome: {
+                outbox,
+                store: { path: store.displayPath, source: store.source },
+                archive: null,
+                read: fold.count,
+                replayed: 0,
+                alreadyPresent: null,
+                failed: 0,
+                dryRun: true,
+                note: null,
+                fold,
+            },
+            exitCode: 0,
+        };
+    }
+    if (store.dbPath === ':memory:') {
+        throw new UsageError('refusing to replay into :memory: — name a durable store with --governance-db or --db');
+    }
+    if (!CoreAdapter.replayEmitOutboxSupported()) {
+        throw new GovernanceReplayUnsupportedError('Replaying a dead-letter outbox');
+    }
+    // The sidecar (or whatever directory the store lives in) must exist before the engine opens it
+    // — for a filesystem path, never for an engine spec (`postgres://…`; `:memory:` was refused above).
+    if (!isStoreSpec(store.dbPath))
+        mkdirSync(dirname(store.dbPath), { recursive: true });
+    // 1. Archive first — atomic, so nothing the daemon appends from here on is lost; the name is
+    //    fresh (timestamp + pid + nonce, checked), so no earlier archive is ever renamed over.
+    const archive = reserveArchiveName(outbox);
+    renameSync(outbox, archive);
+    // 2. Replay from the archive. If the engine THROWS (a store it cannot open, an I/O error
+    //    mid-file, a permission problem) the archive goes back where the daemon spools and
+    //    `/diagnostics` looks — an exception must never turn "not replayed" into "0 dead letters".
+    //    Restored WHOLE: the engine may have landed some records before it threw; a later replay of
+    //    those is a no-op (replay ids are deterministic per spool line), so nothing is duplicated and
+    //    nothing is lost.
+    let report;
+    try {
+        report = await CoreAdapter.replayEmitOutbox(archive, store.dbPath);
+    }
+    catch (err) {
+        await restoreOutbox(outbox, archive);
+        const reason = err instanceof Error ? err.message : String(err);
+        throw new Error(`replay failed and the outbox was restored to ${outbox} (nothing is lost): ${reason}`);
+    }
+    // 3. What did not land stays a dead letter on the live outbox (append: the daemon may have
+    //    started a fresh file already — and may be mid-record on it, hence the boundary-safe append);
+    //    a failed write-back names the archive the lines are still in.
+    if (report.failed.length > 0) {
+        appendFailedLines(outbox, archive, report.failed.map((f) => f.line));
+    }
+    const alreadyPresent = report.already_present ?? null;
+    const note = alreadyPresent !== null && alreadyPresent > 0 ? conflationNote(alreadyPresent, await foldDeadletters(archive)) : null;
+    return {
+        outcome: {
+            outbox,
+            store: { path: store.displayPath, source: store.source },
+            archive,
+            read: report.read,
+            replayed: report.replayed,
+            alreadyPresent,
+            failed: report.failed.length,
+            dryRun: false,
+            note,
+        },
+        exitCode: report.failed.length > 0 ? 1 : 0,
+    };
+}
+/** The `wicked-crew governance …` entry: prints a JSON outcome and exits with the documented code. */
+export async function runGovernance(argv) {
+    const [sub, ...rest] = argv;
+    if (sub !== 'replay' || rest.includes('--help') || rest.includes('-h')) {
+        console.error(GOVERNANCE_USAGE);
+        process.exit(sub === 'replay' ? 0 : 2);
+    }
+    try {
+        const { outcome, exitCode } = await replayOutbox(rest);
+        console.log(JSON.stringify(outcome, null, 2));
+        if (outcome.note !== null)
+            console.error(`[governance] ${outcome.note}`);
+        if (!outcome.dryRun && outcome.failed > 0) {
+            console.error(`[governance] ${outcome.failed} entr${outcome.failed === 1 ? 'y' : 'ies'} did not land and were appended back onto ${outcome.outbox}`);
+        }
+        process.exit(exitCode);
+    }
+    catch (err) {
+        if (err instanceof UsageError || err instanceof GovernanceStoreError || err instanceof CrewBusError) {
+            console.error(`[governance] ${err.message}\n\n${GOVERNANCE_USAGE}`);
+            process.exit(2);
+        }
+        if (err instanceof GovernanceReplayUnsupportedError) {
+            console.error(`[governance] ${err.message}\n` +
+                'Nothing was moved. Inspect the outbox with --dry-run; replay once the engine is upgraded.');
+            process.exit(2);
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=governance.js.map

package/dist/cli/governance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"governance.js","sourceRoot":"","sources":["../../src/cli/governance.ts"],"names":[],"mappings":"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"}

package/dist/cli/index.js

@@ -11,6 +11,9 @@ import { startServer } from '../api/server.js';
 import { resolveAuthMode } from '../api/auth.js';
 import { crewStateHome, setCrewStateHome, stateHomeOfDb } from '../projects/state-home.js';
 import { CrewBusError, resolveCrewBus } from '../interactive/bus-location.js';
+import { applyEmitOrigin, emitOrigin, EMIT_DEADLETTER_ENGINE_ENV, ESTATE_DB_ENGINE_ENV, GOVERNANCE_DB_ENV, GOVERNANCE_DB_FLAG, GovernanceStoreError, legacyHomeOutboxPath, resolveGovernanceStore, } from '../core/governance-store.js';
+import { probeLegacyOutbox, replayCommand } from '../api/governance-health.js';
+import { crewPackageVersion, runGovernance } from './governance.js';
 import { runMcpServer } from './mcp.js';
 const [, , command, ...argv] = process.argv;
 function flag(args, name) {
@@ -90,6 +93,39 @@ function parseBootstrap(args) {
         console.error(`[crew] ${err.message}`);
         process.exit(1);
     }
+    // The governance store (crew#495 / F-022). The engine's emit seam writes every `wicked.*`
+    // governance event — conformance claims, phase transitions, rule lifecycle — to the estate store
+    // named by WICKED_ESTATE_DB, and `serve` never set it: on every default install EVERY such event
+    // dead-lettered to an outbox under the operator's HOME, silently. Resolution: an explicit
+    // --governance-db / WICKED_CREW_GOVERNANCE_DB, else an inherited WICKED_ESTATE_DB (the engine's
+    // own variable, honoured), else the daemon's OWN `<core db>.governance/governance.db` — a sidecar
+    // for the same fence reason as the bus above. The dead-letter outbox lives in that sidecar too
+    // (an explicit WICKED_APPS_EMIT_DEADLETTER wins), never under HOME.
+    const governanceDbFlag = flag(args, GOVERNANCE_DB_FLAG);
+    if (hasFlag(args, GOVERNANCE_DB_FLAG) && (governanceDbFlag === undefined || governanceDbFlag.startsWith('-'))) {
+        console.error(`${GOVERNANCE_DB_FLAG} requires a value (got: ${governanceDbFlag ?? '(missing)'})`);
+        process.exit(1);
+    }
+    let governanceStore;
+    try {
+        governanceStore = resolveGovernanceStore({
+            flagDb: governanceDbFlag,
+            envCrewDb: process.env[GOVERNANCE_DB_ENV],
+            envEstateDb: process.env[ESTATE_DB_ENGINE_ENV],
+            envOutbox: process.env[EMIT_DEADLETTER_ENGINE_ENV],
+            coreDbPath: dbPath,
+            busDbPath: crewBus.dbPath,
+        });
+    }
+    catch (err) {
+        // A store the engine cannot honour (a URL spec on the SQLite-only emit seam) or must not share
+        // (the core db, the bus db) is a CONFIG error — refuse to boot rather than run a daemon that
+        // dead-letters every governance event or puts a second writer on the actor's store.
+        if (!(err instanceof GovernanceStoreError))
+            throw err;
+        console.error(`[crew] ${err.message}`);
+        process.exit(1);
+    }
     // DEFAULT ON (closes #261): answer wicked-interactive's `doc.created` (kind:source) with a
     // governed `interactive-draft` run. The bus is already required for the project bridge.
     // Project-bound docs launch FILED runs; unbound (Unfiled) docs launch unfiled governed runs
@@ -121,7 +157,7 @@ function parseBootstrap(args) {
     // Deterministic-worker override for harnesses (a JSON AgenticCli array); unset = the roster.
     const interactiveSeats = process.env['WICKED_INTERACTIVE_SEATS'];
     return {
-        dbPath, port, stub, engineExec, busDbPath, qeGateEvents, qeBusDbPath, crewBus,
+        dbPath, port, stub, engineExec, busDbPath, qeGateEvents, qeBusDbPath, crewBus, governanceStore,
         interactiveDraftEvents, interactiveEditEvents, interactiveChatEvents, interactiveDemoEvents,
         interactiveSeats,
     };
@@ -145,11 +181,26 @@ async function bootstrap(opts) {
     // wicked-bus (better-sqlite3 underneath) does not create a missing parent: the sidecar dir —
     // or an explicit dir — must exist before the seams open the db, or every seam disables itself.
     mkdirSync(dirname(crewBus.dbPath), { recursive: true });
+    // The governance store (crew#495): say which rule won, stamp the origin the engine copies onto
+    // any dead letter it spools, and point at a pre-fix outbox under HOME if one is still sitting
+    // there — the adapter exports the store/outbox variables to the engine before it spawns.
+    const { governanceStore } = opts;
+    console.error(`[crew] governance store: ${governanceStore.displayPath} (${governanceStore.source}); ` +
+        `dead letters: ${governanceStore.outboxPath} (${governanceStore.outboxSource})`);
+    const crewVersion = crewPackageVersion();
+    applyEmitOrigin(emitOrigin({ version: crewVersion, pid: process.pid, coreDbPath: opts.dbPath }));
+    const legacyOutbox = await probeLegacyOutbox(legacyHomeOutboxPath());
+    if (legacyOutbox !== null && legacyOutbox.path !== governanceStore.outboxPath) {
+        console.warn(`[crew] a pre-fix dead-letter outbox exists under HOME at ${legacyOutbox.path} (${legacyOutbox.bytes} bytes) — ` +
+            `governance events earlier daemons could not store; inspect with ${replayCommand(legacyOutbox.path, governanceStore)} --dry-run, ` +
+            'then replay it into this daemon\'s store with the same command');
+    }
     const adapter = new CoreAdapter({
         dbPath: opts.dbPath,
         stub: opts.stub,
         engineExec: opts.engineExec,
         busDbPath: opts.busDbPath,
+        governanceStore,
     });
     adapterRef = adapter;
     const serverOptions = {
@@ -209,6 +260,8 @@ async function bootstrap(opts) {
         interactiveBridge: { busDataDir: crewBus.dataDir },
     };
     const { port } = await startServer(adapter, opts.port, undefined, Object.keys(serverOptions).length > 0 ? serverOptions : undefined);
+    // Now that the port is known, complete the origin stamp (the engine reads it at emit time).
+    applyEmitOrigin(emitOrigin({ version: crewVersion, pid: process.pid, coreDbPath: opts.dbPath, port }));
     installShutdownHandlers();
     return { adapter, port };
 }
@@ -279,6 +332,14 @@ async function main() {
                 '  --bus-db <path>                 Bus database path (env: WICKED_BUS_DB) for the interactive/project seams,\n' +
                 '                                  the /ws relay and the bridge crew spawns (default: $WICKED_BUS_DATA_DIR/bus.db,\n' +
                 '                                  else <core db>.bus/bus.db); --engine-exec defaults to <state home>/bus.db\n' +
+                '  --governance-db <path>          Governance store the engine writes conformance claims, phase transitions and\n' +
+                '                                  rule-lifecycle events to (env: WICKED_CREW_GOVERNANCE_DB; an inherited\n' +
+                '                                  WICKED_ESTATE_DB is honoured next; default <core db>.governance/governance.db).\n' +
+                '                                  The emit seam stores to SQLite only: a URL-form WICKED_ESTATE_DB (postgres://…)\n' +
+                '                                  in the shell refuses boot until --governance-db names a SQLite file.\n' +
+                '                                  Dead letters spool to <core db>.governance/emit-outbox.ndjson by default — under the\n' +
+                '                                  state home, not HOME (an explicit WICKED_APPS_EMIT_DEADLETTER is honoured);\n' +
+                '                                  see `wicked-crew governance replay`\n' +
                 '  --stub                          Use stub engine (env: WICKED_CORE_STUB=1)\n' +
                 '  --engine-exec                   Arm event-driven execution seam (env: WICKED_BUS_EXEC)\n' +
                 '  --qe-gate-events                Consume QE gate bus events (env: WICKED_QE_GATE_EVENTS)\n' +
@@ -306,6 +367,9 @@ async function main() {
             mode: 'serve',
             port,
             db: opts.dbPath,
+            // Where the engine's governance events land (crew#495) — an evidence harness can open it
+            // (a URL spec's credentials redacted; the raw value went to the engine only).
+            governanceDb: opts.governanceStore.displayPath,
             stub: opts.stub,
             // The identity seam's resolved mode (task #88): `required` under
             // WICKED_RUNTIME=team / WICKED_CREW_AUTH=required, else `off` (local).
@@ -378,9 +442,12 @@ async function main() {
         }
         await runMcpServer(port);
     }
+    else if (command === 'governance') {
+        await runGovernance(argv);
+    }
     else {
         console.error(`Unknown command: ${command ?? '(none)'}`);
-        console.error('Usage: wicked-crew serve|start|resume|gate|status|mcp');
+        console.error('Usage: wicked-crew serve|start|resume|gate|status|mcp|governance');
         process.exit(1);
     }
 }