wicked-crew 0.7.28 → 0.7.30

package/dist/core/governance-store.d.ts

@@ -0,0 +1,219 @@
+/**
+ * WHERE THE GOVERNANCE STORE LIVES — and where its dead letters go (crew#495, acceptance
+ * finding F-022). One pure resolution the CLI, the adapter, the diagnostics route and the tests
+ * share, in the shape of `interactive/bus-location.ts`.
+ *
+ * # The defect
+ *
+ * The engine's emit seam (`wicked-apps-core::emit::emit_event`) publishes every cross-product
+ * `wicked.*` event — the conformance claims and decisions the acceptance gate reads back
+ * (`wicked.crew.governance.conformance_recorded`), phase transitions, the steering-rule lifecycle
+ * (`wicked.estate.rule.ingested` / `.retired`), council traffic — as an EVENT node on the shared
+ * estate store named by `WICKED_ESTATE_DB`. `serve` never set that variable, so on EVERY default
+ * install EVERY such event dead-lettered: appended to an NDJSON outbox under the operator's HOME
+ * (`~/.something-wicked/wicked-apps/emit-outbox.ndjson`), shared by every daemon on the host, with
+ * no timestamp, no origin, and nothing on `/diagnostics` or the console to say so — 3,400+ entries
+ * on one host while the home board asserted "Governed 100%".
+ *
+ * # Resolution, in order
+ *
+ *  1. `--governance-db` / `WICKED_CREW_GOVERNANCE_DB` — the operator's explicit choice;
+ *  2. an inherited `WICKED_ESTATE_DB` — the engine's own variable, honoured as-is (pointing several
+ *     daemons, or the estate MCP, at ONE shared store is exactly what it exists for);
+ *  3. `<core db>.governance/governance.db` — a SIDECAR of the core db, the default. Why a sidecar
+ *     and not `<state home>/governance.db`: wicked-core embeds crew's state-home registry
+ *     (`tests/fixtures/state-home-subtrees.json`, core `src/state_home.rs`) as the worker Read
+ *     fence and REFUSES every launch that meets a top-level entry the registry does not classify.
+ *     The registry's `core.db` entry is a PREFIX claim (`file-with-sidecars`) that already covers a
+ *     `core.db.governance/` directory, exactly as it covers core's own `core.db.events/` and crew's
+ *     `core.db.bus/` (F-043). A new top-level name would need a byte-identical registry change in
+ *     BOTH repos and a core release before one governed run could start beside it; the sidecar
+ *     needs neither, and `GET /diagnostics.stores` lists it for free. The prefix claim is spelled
+ *     for the DEFAULT basename: a `--db` named anything but `core.db` already puts the db itself,
+ *     its `-wal`/`-shm`, core's own `<db>.events/` and crew's `<db>.bus/` outside the registry —
+ *     this sidecar is no different, so a daemon that hosts governed runs keeps the default
+ *     basename (the same residual `interactive/bus-location.ts` documents).
+ *
+ * Why NOT the core db itself: the single-writer actor holds `core.db` open, and the emit seam opens
+ * its OWN connection per emit — pointing it at `core.db` would put a second writer on the actor's
+ * store, the one race the single-writer design exists to rule out.
+ *
+ * # The dead-letter outbox
+ *
+ * When the store cannot be written (unopenable path, a write error) the engine spools the event to
+ * the NDJSON outbox named by `WICKED_APPS_EMIT_DEADLETTER`. An explicit value in the daemon's
+ * environment is honoured — it is the engine's own override, and the hermetic test harness relies
+ * on it (`tests/setup/hermetic-home.ts`); otherwise the outbox is `<core db>.governance/
+ * emit-outbox.ndjson` — under the state home, never under HOME, never shared by two daemons —
+ * whichever store won. `GET /diagnostics` folds it (`governance.deadletters`) and raises a
+ * `governance.deadletter` finding whenever it holds an entry; `wicked-crew governance replay`
+ * drains it back into the store.
+ *
+ * # Why exporting `WICKED_ESTATE_DB` process-wide is safe
+ *
+ * The napi engine runs in this process and reads the variable at emit time, so `process.env` is
+ * the only channel. The ONLY in-process reader is the emit seam — the actor opens its store by the
+ * explicit `--db` path, every governance binding takes its path as an argument. Governed workers
+ * never inherit it: core strips it from every spawn (`spawn.rs` `hardened()`, FINDING-067) and
+ * re-points a worker's estate channel at the repo's OWN graph (`execute_wrapped.rs`). Crew's own
+ * children that would resolve a store from it get the BOOT-TIME value back
+ * ({@link childEnvWithBootEstateDb}) — the operator's instruction, not the daemon's sidecar.
+ */
+/** The `serve` / `governance` flag naming the store explicitly. */
+export declare const GOVERNANCE_DB_FLAG = "--governance-db";
+/** The crew-side env override — the flag's environment spelling. */
+export declare const GOVERNANCE_DB_ENV = "WICKED_CREW_GOVERNANCE_DB";
+/** The ENGINE's variable: the shared estate store `wicked-apps-core::emit::emit_event` writes to
+ *  (`wicked_apps_core::ESTATE_DB_ENV`). Exported by the daemon; never typed out elsewhere. */
+export declare const ESTATE_DB_ENGINE_ENV = "WICKED_ESTATE_DB";
+/** The ENGINE's dead-letter outbox override (`wicked_apps_core::emit::DEADLETTER_ENV`). */
+export declare const EMIT_DEADLETTER_ENGINE_ENV = "WICKED_APPS_EMIT_DEADLETTER";
+/** The ENGINE's optional origin stamp for spooled entries (`wicked_apps_core::emit::ORIGIN_ENV`,
+ *  wicked-core ≥ the release carrying crew#495's companion): copied verbatim onto every
+ *  dead-letter record as `origin`, beside the engine's own `ts` (epoch ms) and `pid`. An older
+ *  engine ignores it — entries then carry no timestamp, which the fold reports honestly. */
+export declare const EMIT_ORIGIN_ENGINE_ENV = "WICKED_APPS_EMIT_ORIGIN";
+/** The sidecar directory's suffix and the two files it holds. */
+export declare const GOVERNANCE_SIDECAR_SUFFIX = ".governance";
+export declare const GOVERNANCE_DB_FILENAME = "governance.db";
+export declare const EMIT_OUTBOX_FILENAME = "emit-outbox.ndjson";
+/**
+ * The value of the engine's store variable when THIS PROCESS booted — the operator's instruction,
+ * captured before the daemon exports its own resolution over it. Children that resolve a store from
+ * the variable are handed this back ({@link childEnvWithBootEstateDb}).
+ */
+export declare const BOOT_ESTATE_DB: string | undefined;
+/** What decided the store — logged at boot and reported on `/diagnostics` so an operator can see which rule won. */
+export type GovernanceStoreSource = 'flag' | 'env-crew' | 'env-estate' | 'core-db-sidecar';
+/** What decided the outbox: the engine's own override in the environment, or the sidecar default. */
+export type GovernanceOutboxSource = 'env' | 'core-db-sidecar';
+export interface GovernanceStoreLocation {
+    /** The estate store the engine's emit seam writes to — exported as `WICKED_ESTATE_DB`. An
+     *  absolute SQLite path, or `:memory:` (the engine's "no shared store"). The emit seam is
+     *  SQLite-only (`wicked-apps-core::emit::emit_event` → `open_store` → `SqliteStore::open`), so a
+     *  URL spec is REFUSED at resolution ({@link GovernanceStoreError}) — never handed to an engine
+     *  that would dead-letter every event and print the spec, credentials included, on stderr. */
+    dbPath: string;
+    /** What operator-facing surfaces print — the boot log, the readiness line,
+     *  `/diagnostics.governance.store.path`, `governance replay` output. Equal to `dbPath` for every
+     *  value the resolver admits; the userinfo redaction ({@link redactStoreSpec}) is defence in depth. */
+    displayPath: string;
+    source: GovernanceStoreSource;
+    /** The dead-letter outbox — exported as `WICKED_APPS_EMIT_DEADLETTER`. */
+    outboxPath: string;
+    outboxSource: GovernanceOutboxSource;
+    /** `<core db>.governance` — created at boot so the engine's first write never fails on a missing parent. */
+    sidecarDir: string;
+    /** The daemon's core db, absolute — what `governance replay --db` names to reach the SAME sidecar. */
+    coreDbPath: string;
+}
+export interface GovernanceStoreInput {
+    /** `--governance-db` (flag), or undefined. */
+    flagDb?: string | undefined;
+    /** `WICKED_CREW_GOVERNANCE_DB`, or undefined/empty. */
+    envCrewDb?: string | undefined;
+    /** An inherited `WICKED_ESTATE_DB`, or undefined/empty. */
+    envEstateDb?: string | undefined;
+    /** An inherited `WICKED_APPS_EMIT_DEADLETTER`, or undefined/empty. */
+    envOutbox?: string | undefined;
+    /** The daemon's core db path (`--db`, or the default under the state home). */
+    coreDbPath: string;
+    /** The daemon's cross-product bus db (`resolveCrewBus().dbPath`) — refused as a governance store too. */
+    busDbPath?: string | undefined;
+}
+/** A governance store the engine could not honour — a boot error, not a warning: the alternative is a
+ *  daemon that dead-letters 100 % of its governance events (a URL spec on the SQLite-only emit seam)
+ *  or a second writer on the actor's `core.db` / the bus db (the race the single-writer design
+ *  exists to rule out). Same shape as `interactive/bus-location.ts`'s `CrewBusError`. */
+export declare class GovernanceStoreError extends Error {
+    constructor(message: string);
+}
+/** The sidecar directory the daemon's governance store and outbox live in: `<core db>.governance`. */
+export declare function governanceSidecarDir(coreDbPath: string): string;
+/** The default store: `<core db>.governance/governance.db`. */
+export declare function governanceSidecarDb(coreDbPath: string): string;
+/** The default outbox: `<core db>.governance/emit-outbox.ndjson`. */
+export declare function governanceSidecarOutbox(coreDbPath: string): string;
+/** Whether a store value is a URL spec (`postgres://…`) — something the emit seam cannot open. */
+export declare function isUrlSpec(value: string): boolean;
+/** A store spec the engine parses itself rather than a filesystem path — `:memory:`, and nothing
+ *  else: the emit seam is SQLite-only, so a URL spec is refused before it gets this far. Left
+ *  exactly as written, never resolved, never `mkdir`ed for. */
+export declare function isStoreSpec(value: string): boolean;
+/** DEFENCE IN DEPTH: a value safe to print — a URL's credentials become `***` (`postgres://u:p@h/db`
+ *  → `postgres://***@h/db`); `:memory:` and filesystem paths are returned unchanged. URL specs are
+ *  refused at resolution, so in practice this is the identity; it stays so that no future rung can
+ *  print a credential by accident (the refusal message itself uses it). */
+export declare function redactStoreSpec(value: string): string;
+/**
+ * The CANONICAL spelling of a path that may not exist yet: the real path of its nearest existing
+ * ancestor plus the remaining segments — so a symlink to `core.db` (or to its directory) compares
+ * equal to `core.db` itself, which `resolve()` alone (lexical `..` folding) cannot see. Fails
+ * closed: anything but "does not exist" while walking up is a {@link GovernanceStoreError}.
+ */
+export declare function canonicalPath(p: string): string;
+/** Resolve the governance store and its outbox for one daemon — pure, so two `--db` inputs can be compared. */
+export declare function resolveGovernanceStore(input: GovernanceStoreInput): GovernanceStoreLocation;
+/**
+ * Hand the resolved location to the engine: export the two engine variables into `env` and create
+ * the sidecar directory (the engine's SQLite open does not create a missing parent, and a spool
+ * into a missing directory is a dead letter that itself fails). Called ONCE per daemon, before the
+ * engine exists (`CoreAdapter`'s constructor) — the emit seam reads the variables at emit time,
+ * so nothing needs a restart. A library boot that never resolves a location exports nothing, and
+ * the hermetic test arming stays exactly as it was.
+ */
+export declare function applyGovernanceStoreEnv(location: GovernanceStoreLocation, env?: NodeJS.ProcessEnv): void;
+/**
+ * The origin stamp the engine copies onto every dead-letter record — WHICH daemon spooled it, so a
+ * record read months later in a drained outbox still says where it came from. Human-readable on
+ * purpose; the port is appended once the daemon has bound (the engine reads the variable at emit
+ * time, so the update is seen by the next spool).
+ */
+export declare function emitOrigin(fields: {
+    version: string;
+    pid: number;
+    coreDbPath: string;
+    port?: number | undefined;
+}): string;
+/** Export the origin stamp for the engine. */
+export declare function applyEmitOrigin(origin: string, env?: NodeJS.ProcessEnv): void;
+/**
+ * The environment for EVERY child crew spawns (git, uv, the estate CLI and MCP, the deliver shell,
+ * the interactive bridge, the OS opener, `ps`/`lsof`): the daemon's exported governance store is the
+ * in-process engine's business and nobody else's. `WICKED_ESTATE_DB` goes back to whatever the
+ * process booted with — the operator's explicit store, or nothing (a newer estate binary handed the
+ * daemon's `governance.db` as its graph store could migrate the file's schema past what the engine's
+ * vendored store opens) — and crew's own override `WICKED_CREW_GOVERNANCE_DB`, needed only at
+ * resolution, is dropped outright. Governed workers are covered separately by core's `hardened()`.
+ */
+export declare function childEnvWithBootEstateDb(env?: NodeJS.ProcessEnv, bootValue?: string | undefined): NodeJS.ProcessEnv;
+/**
+ * Where a PRE-FIX engine dead-lettered under HOME — `<HOME | USERPROFILE>/.something-wicked/
+ * wicked-apps/emit-outbox.ndjson`, the engine's own default (`emit.rs` `deadletter_path()`), spelled
+ * here only so the daemon can TELL the operator it exists (a boot warning and a `/diagnostics`
+ * finding with the replay command). Crew never writes it. `null` when no home resolves.
+ */
+export declare function legacyHomeOutboxPath(env?: NodeJS.ProcessEnv): string | null;
+/**
+ * Whose dead letters the HOME outbox holds, as far as THIS daemon can tell (F-2R2-006).
+ *
+ *  - `'own'`  — this daemon runs in the DEFAULT state home of the HOME the outbox was found under
+ *               (`<HOME>/.wicked-crew`), so the pre-fix daemons that spooled there were its own
+ *               earlier versions: the outbox is its prior outbox, and replaying it into this
+ *               daemon's store is the repair.
+ *  - `'host'` — this daemon runs in an ISOLATED state home (`--db` elsewhere, a fresh rig, a test
+ *               harness). A pre-fix engine wrote under HOME regardless of which daemon it served,
+ *               so the file is shared by every daemon on the host and CANNOT be attributed to this
+ *               one — it may hold other daemons' dead letters, or (for an isolated daemon that ran
+ *               since before the fix) some of its own, and nothing in the file says which (the
+ *               post-fix `origin` stamp, `emitOrigin`, would — a fold over it is the follow-up).
+ *               Reporting it as a warning with a replay recipe would import a stranger's governance
+ *               events into this store; it is reported at info with the read-only inspect recipe.
+ *
+ * `coreDbPath` `null` (no store resolved) is `'host'`: with no state home there is nothing to
+ * attribute the file to. Pure — the HOME is read off the outbox path itself
+ * (`<HOME>/.something-wicked/wicked-apps/<file>`), never off the process environment.
+ */
+export type LegacyOutboxScope = 'own' | 'host';
+export declare function legacyOutboxScope(coreDbPath: string | null, legacyOutboxPath: string): LegacyOutboxScope;
+//# sourceMappingURL=governance-store.d.ts.map

package/dist/core/governance-store.d.ts.map

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

package/dist/core/governance-store.js

@@ -0,0 +1,290 @@
+/**
+ * WHERE THE GOVERNANCE STORE LIVES — and where its dead letters go (crew#495, acceptance
+ * finding F-022). One pure resolution the CLI, the adapter, the diagnostics route and the tests
+ * share, in the shape of `interactive/bus-location.ts`.
+ *
+ * # The defect
+ *
+ * The engine's emit seam (`wicked-apps-core::emit::emit_event`) publishes every cross-product
+ * `wicked.*` event — the conformance claims and decisions the acceptance gate reads back
+ * (`wicked.crew.governance.conformance_recorded`), phase transitions, the steering-rule lifecycle
+ * (`wicked.estate.rule.ingested` / `.retired`), council traffic — as an EVENT node on the shared
+ * estate store named by `WICKED_ESTATE_DB`. `serve` never set that variable, so on EVERY default
+ * install EVERY such event dead-lettered: appended to an NDJSON outbox under the operator's HOME
+ * (`~/.something-wicked/wicked-apps/emit-outbox.ndjson`), shared by every daemon on the host, with
+ * no timestamp, no origin, and nothing on `/diagnostics` or the console to say so — 3,400+ entries
+ * on one host while the home board asserted "Governed 100%".
+ *
+ * # Resolution, in order
+ *
+ *  1. `--governance-db` / `WICKED_CREW_GOVERNANCE_DB` — the operator's explicit choice;
+ *  2. an inherited `WICKED_ESTATE_DB` — the engine's own variable, honoured as-is (pointing several
+ *     daemons, or the estate MCP, at ONE shared store is exactly what it exists for);
+ *  3. `<core db>.governance/governance.db` — a SIDECAR of the core db, the default. Why a sidecar
+ *     and not `<state home>/governance.db`: wicked-core embeds crew's state-home registry
+ *     (`tests/fixtures/state-home-subtrees.json`, core `src/state_home.rs`) as the worker Read
+ *     fence and REFUSES every launch that meets a top-level entry the registry does not classify.
+ *     The registry's `core.db` entry is a PREFIX claim (`file-with-sidecars`) that already covers a
+ *     `core.db.governance/` directory, exactly as it covers core's own `core.db.events/` and crew's
+ *     `core.db.bus/` (F-043). A new top-level name would need a byte-identical registry change in
+ *     BOTH repos and a core release before one governed run could start beside it; the sidecar
+ *     needs neither, and `GET /diagnostics.stores` lists it for free. The prefix claim is spelled
+ *     for the DEFAULT basename: a `--db` named anything but `core.db` already puts the db itself,
+ *     its `-wal`/`-shm`, core's own `<db>.events/` and crew's `<db>.bus/` outside the registry —
+ *     this sidecar is no different, so a daemon that hosts governed runs keeps the default
+ *     basename (the same residual `interactive/bus-location.ts` documents).
+ *
+ * Why NOT the core db itself: the single-writer actor holds `core.db` open, and the emit seam opens
+ * its OWN connection per emit — pointing it at `core.db` would put a second writer on the actor's
+ * store, the one race the single-writer design exists to rule out.
+ *
+ * # The dead-letter outbox
+ *
+ * When the store cannot be written (unopenable path, a write error) the engine spools the event to
+ * the NDJSON outbox named by `WICKED_APPS_EMIT_DEADLETTER`. An explicit value in the daemon's
+ * environment is honoured — it is the engine's own override, and the hermetic test harness relies
+ * on it (`tests/setup/hermetic-home.ts`); otherwise the outbox is `<core db>.governance/
+ * emit-outbox.ndjson` — under the state home, never under HOME, never shared by two daemons —
+ * whichever store won. `GET /diagnostics` folds it (`governance.deadletters`) and raises a
+ * `governance.deadletter` finding whenever it holds an entry; `wicked-crew governance replay`
+ * drains it back into the store.
+ *
+ * # Why exporting `WICKED_ESTATE_DB` process-wide is safe
+ *
+ * The napi engine runs in this process and reads the variable at emit time, so `process.env` is
+ * the only channel. The ONLY in-process reader is the emit seam — the actor opens its store by the
+ * explicit `--db` path, every governance binding takes its path as an argument. Governed workers
+ * never inherit it: core strips it from every spawn (`spawn.rs` `hardened()`, FINDING-067) and
+ * re-points a worker's estate channel at the repo's OWN graph (`execute_wrapped.rs`). Crew's own
+ * children that would resolve a store from it get the BOOT-TIME value back
+ * ({@link childEnvWithBootEstateDb}) — the operator's instruction, not the daemon's sidecar.
+ */
+import { mkdirSync, realpathSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { defaultStateHome } from '../projects/state-home.js';
+/** The `serve` / `governance` flag naming the store explicitly. */
+export const GOVERNANCE_DB_FLAG = '--governance-db';
+/** The crew-side env override — the flag's environment spelling. */
+export const GOVERNANCE_DB_ENV = 'WICKED_CREW_GOVERNANCE_DB';
+/** The ENGINE's variable: the shared estate store `wicked-apps-core::emit::emit_event` writes to
+ *  (`wicked_apps_core::ESTATE_DB_ENV`). Exported by the daemon; never typed out elsewhere. */
+export const ESTATE_DB_ENGINE_ENV = 'WICKED_ESTATE_DB';
+/** The ENGINE's dead-letter outbox override (`wicked_apps_core::emit::DEADLETTER_ENV`). */
+export const EMIT_DEADLETTER_ENGINE_ENV = 'WICKED_APPS_EMIT_DEADLETTER';
+/** The ENGINE's optional origin stamp for spooled entries (`wicked_apps_core::emit::ORIGIN_ENV`,
+ *  wicked-core ≥ the release carrying crew#495's companion): copied verbatim onto every
+ *  dead-letter record as `origin`, beside the engine's own `ts` (epoch ms) and `pid`. An older
+ *  engine ignores it — entries then carry no timestamp, which the fold reports honestly. */
+export const EMIT_ORIGIN_ENGINE_ENV = 'WICKED_APPS_EMIT_ORIGIN';
+/** The sidecar directory's suffix and the two files it holds. */
+export const GOVERNANCE_SIDECAR_SUFFIX = '.governance';
+export const GOVERNANCE_DB_FILENAME = 'governance.db';
+export const EMIT_OUTBOX_FILENAME = 'emit-outbox.ndjson';
+/**
+ * The value of the engine's store variable when THIS PROCESS booted — the operator's instruction,
+ * captured before the daemon exports its own resolution over it. Children that resolve a store from
+ * the variable are handed this back ({@link childEnvWithBootEstateDb}).
+ */
+export const BOOT_ESTATE_DB = process.env[ESTATE_DB_ENGINE_ENV];
+/** A governance store the engine could not honour — a boot error, not a warning: the alternative is a
+ *  daemon that dead-letters 100 % of its governance events (a URL spec on the SQLite-only emit seam)
+ *  or a second writer on the actor's `core.db` / the bus db (the race the single-writer design
+ *  exists to rule out). Same shape as `interactive/bus-location.ts`'s `CrewBusError`. */
+export class GovernanceStoreError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'GovernanceStoreError';
+    }
+}
+/** The sidecar directory the daemon's governance store and outbox live in: `<core db>.governance`. */
+export function governanceSidecarDir(coreDbPath) {
+    return `${resolve(coreDbPath)}${GOVERNANCE_SIDECAR_SUFFIX}`;
+}
+/** The default store: `<core db>.governance/governance.db`. */
+export function governanceSidecarDb(coreDbPath) {
+    return join(governanceSidecarDir(coreDbPath), GOVERNANCE_DB_FILENAME);
+}
+/** The default outbox: `<core db>.governance/emit-outbox.ndjson`. */
+export function governanceSidecarOutbox(coreDbPath) {
+    return join(governanceSidecarDir(coreDbPath), EMIT_OUTBOX_FILENAME);
+}
+/** A URL scheme of two or more characters followed by `://` — `postgres://`, `postgresql://`. A
+ *  single letter before `://` is a Windows drive written with forward slashes (`C://tmp/gov.db`),
+ *  which is a PATH. */
+const URL_SCHEME_RE = /^[A-Za-z][A-Za-z0-9+.-]+:\/\//;
+/** Whether a store value is a URL spec (`postgres://…`) — something the emit seam cannot open. */
+export function isUrlSpec(value) {
+    return URL_SCHEME_RE.test(value);
+}
+/** A store spec the engine parses itself rather than a filesystem path — `:memory:`, and nothing
+ *  else: the emit seam is SQLite-only, so a URL spec is refused before it gets this far. Left
+ *  exactly as written, never resolved, never `mkdir`ed for. */
+export function isStoreSpec(value) {
+    return value === ':memory:';
+}
+/** The userinfo of a URL spec — everything between `scheme://` and the first `@` before a `/`. */
+const URL_USERINFO_RE = /^([A-Za-z][A-Za-z0-9+.-]+:\/\/)[^/@]*@/;
+/** DEFENCE IN DEPTH: a value safe to print — a URL's credentials become `***` (`postgres://u:p@h/db`
+ *  → `postgres://***@h/db`); `:memory:` and filesystem paths are returned unchanged. URL specs are
+ *  refused at resolution, so in practice this is the identity; it stays so that no future rung can
+ *  print a credential by accident (the refusal message itself uses it). */
+export function redactStoreSpec(value) {
+    return isUrlSpec(value) ? value.replace(URL_USERINFO_RE, '$1***@') : value;
+}
+function present(value) {
+    if (value === undefined)
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed === '' ? undefined : trimmed;
+}
+/** Spell an explicit store absolute AND normalized (`resolve` also folds `..` segments); relative
+ *  flags land next to the cwd the operator typed them in, not wherever a later `join` happens to
+ *  run. `:memory:` is untouched. */
+function absoluteStore(value) {
+    return isStoreSpec(value) ? value : resolve(value);
+}
+/**
+ * The CANONICAL spelling of a path that may not exist yet: the real path of its nearest existing
+ * ancestor plus the remaining segments — so a symlink to `core.db` (or to its directory) compares
+ * equal to `core.db` itself, which `resolve()` alone (lexical `..` folding) cannot see. Fails
+ * closed: anything but "does not exist" while walking up is a {@link GovernanceStoreError}.
+ */
+export function canonicalPath(p) {
+    const abs = resolve(p);
+    let existing = abs;
+    const tail = [];
+    for (;;) {
+        try {
+            const real = realpathSync.native(existing);
+            return tail.length === 0 ? real : join(real, ...tail);
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== 'ENOENT' && code !== 'ENOTDIR') {
+                throw new GovernanceStoreError(`cannot canonicalize ${abs} to check it against the daemon's own stores: ${err.message}`);
+            }
+            const parent = dirname(existing);
+            if (parent === existing)
+                return abs; // nothing on the way to the root exists yet
+            tail.unshift(basename(existing));
+            existing = parent;
+        }
+    }
+}
+/** Resolve the governance store and its outbox for one daemon — pure, so two `--db` inputs can be compared. */
+export function resolveGovernanceStore(input) {
+    const sidecarDir = governanceSidecarDir(input.coreDbPath);
+    const envOutbox = present(input.envOutbox);
+    const outbox = envOutbox !== undefined
+        ? { outboxPath: resolve(envOutbox), outboxSource: 'env' }
+        : { outboxPath: join(sidecarDir, EMIT_OUTBOX_FILENAME), outboxSource: 'core-db-sidecar' };
+    const coreDbPath = resolve(input.coreDbPath);
+    const busDbPath = present(input.busDbPath) !== undefined ? resolve(input.busDbPath) : undefined;
+    const at = (dbPath, source) => ({
+        dbPath,
+        displayPath: redactStoreSpec(dbPath),
+        source,
+        sidecarDir,
+        coreDbPath,
+        ...outbox,
+    });
+    /** An explicit store (flag / env) must be one the engine can honour and must not be a store
+     *  another writer already owns — refused loudly at boot, never silently dead-lettered. */
+    const explicit = (raw, source, how) => {
+        if (isUrlSpec(raw)) {
+            throw new GovernanceStoreError(`${how} names ${redactStoreSpec(raw)}, but the engine's emit seam stores to SQLite (wicked-apps-core ` +
+                '`open_store` → `SqliteStore::open`); a `postgres://` (or any URL) governance store is not supported — ' +
+                'every governance event would dead-letter. Name a SQLite file (default: <core db>.governance/governance.db) or `:memory:`.');
+        }
+        const dbPath = absoluteStore(raw);
+        // Compared CANONICALLY (symlinks resolved), so an alias of the core db or the bus db is caught.
+        const canonical = canonicalPath(dbPath);
+        if (canonical === canonicalPath(coreDbPath)) {
+            throw new GovernanceStoreError(`${how} names the daemon's own core db (${coreDbPath}); the single-writer actor holds that store and the emit ` +
+                'seam opens its own connection per emit — a second writer there is the race the design rules out. ' +
+                'Name a separate SQLite file (default: <core db>.governance/governance.db).');
+        }
+        if (busDbPath !== undefined && canonical === canonicalPath(busDbPath)) {
+            throw new GovernanceStoreError(`${how} names the cross-product bus db (${busDbPath}), which wicked-bus owns; name a separate SQLite file ` +
+                '(default: <core db>.governance/governance.db).');
+        }
+        return at(dbPath, source);
+    };
+    const flagDb = present(input.flagDb);
+    if (flagDb !== undefined)
+        return explicit(flagDb, 'flag', GOVERNANCE_DB_FLAG);
+    const envCrewDb = present(input.envCrewDb);
+    if (envCrewDb !== undefined)
+        return explicit(envCrewDb, 'env-crew', GOVERNANCE_DB_ENV);
+    const envEstateDb = present(input.envEstateDb);
+    if (envEstateDb !== undefined)
+        return explicit(envEstateDb, 'env-estate', `an inherited ${ESTATE_DB_ENGINE_ENV}`);
+    return at(join(sidecarDir, GOVERNANCE_DB_FILENAME), 'core-db-sidecar');
+}
+/**
+ * Hand the resolved location to the engine: export the two engine variables into `env` and create
+ * the sidecar directory (the engine's SQLite open does not create a missing parent, and a spool
+ * into a missing directory is a dead letter that itself fails). Called ONCE per daemon, before the
+ * engine exists (`CoreAdapter`'s constructor) — the emit seam reads the variables at emit time,
+ * so nothing needs a restart. A library boot that never resolves a location exports nothing, and
+ * the hermetic test arming stays exactly as it was.
+ */
+export function applyGovernanceStoreEnv(location, env = process.env) {
+    mkdirSync(location.sidecarDir, { recursive: true });
+    if (!isStoreSpec(location.dbPath))
+        mkdirSync(dirname(location.dbPath), { recursive: true });
+    mkdirSync(dirname(location.outboxPath), { recursive: true });
+    env[ESTATE_DB_ENGINE_ENV] = location.dbPath;
+    env[EMIT_DEADLETTER_ENGINE_ENV] = location.outboxPath;
+}
+/**
+ * The origin stamp the engine copies onto every dead-letter record — WHICH daemon spooled it, so a
+ * record read months later in a drained outbox still says where it came from. Human-readable on
+ * purpose; the port is appended once the daemon has bound (the engine reads the variable at emit
+ * time, so the update is seen by the next spool).
+ */
+export function emitOrigin(fields) {
+    const port = fields.port !== undefined ? ` port=${fields.port}` : '';
+    return `wicked-crew@${fields.version} serve pid=${fields.pid}${port} db=${resolve(fields.coreDbPath)}`;
+}
+/** Export the origin stamp for the engine. */
+export function applyEmitOrigin(origin, env = process.env) {
+    env[EMIT_ORIGIN_ENGINE_ENV] = origin;
+}
+/**
+ * The environment for EVERY child crew spawns (git, uv, the estate CLI and MCP, the deliver shell,
+ * the interactive bridge, the OS opener, `ps`/`lsof`): the daemon's exported governance store is the
+ * in-process engine's business and nobody else's. `WICKED_ESTATE_DB` goes back to whatever the
+ * process booted with — the operator's explicit store, or nothing (a newer estate binary handed the
+ * daemon's `governance.db` as its graph store could migrate the file's schema past what the engine's
+ * vendored store opens) — and crew's own override `WICKED_CREW_GOVERNANCE_DB`, needed only at
+ * resolution, is dropped outright. Governed workers are covered separately by core's `hardened()`.
+ */
+export function childEnvWithBootEstateDb(env = process.env, bootValue = BOOT_ESTATE_DB) {
+    const out = { ...env };
+    if (bootValue === undefined)
+        delete out[ESTATE_DB_ENGINE_ENV];
+    else
+        out[ESTATE_DB_ENGINE_ENV] = bootValue;
+    delete out[GOVERNANCE_DB_ENV];
+    return out;
+}
+/**
+ * Where a PRE-FIX engine dead-lettered under HOME — `<HOME | USERPROFILE>/.something-wicked/
+ * wicked-apps/emit-outbox.ndjson`, the engine's own default (`emit.rs` `deadletter_path()`), spelled
+ * here only so the daemon can TELL the operator it exists (a boot warning and a `/diagnostics`
+ * finding with the replay command). Crew never writes it. `null` when no home resolves.
+ */
+export function legacyHomeOutboxPath(env = process.env) {
+    const home = present(env['HOME']) ?? present(env['USERPROFILE']);
+    if (home === undefined)
+        return null;
+    return join(home, '.something-wicked', 'wicked-apps', EMIT_OUTBOX_FILENAME);
+}
+export function legacyOutboxScope(coreDbPath, legacyOutboxPath) {
+    if (coreDbPath === null)
+        return 'host';
+    const home = dirname(dirname(dirname(resolve(legacyOutboxPath))));
+    return dirname(resolve(coreDbPath)) === resolve(defaultStateHome(home)) ? 'own' : 'host';
+}
+//# sourceMappingURL=governance-store.js.map

package/dist/core/governance-store.js.map

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

package/dist/core/repoPaths.d.ts

@@ -14,16 +14,47 @@
  * repo record that this package already reads, and this module is the only thing that touches that
  * field. One producer, one consumer, nothing to keep in step.
  */
-import type { RepoEntry } from './types.js';
+import type { RepoEntry, RepoFinding } from './types.js';
 /**
  * The ABSOLUTE path of a repo's code graph, as resolved by the engine.
  *
- * Throws when the field is absent, which means the running `wicked-core` addon predates the field. A
- * fallback to the old hand-join is what this module exists to delete — it would restore the exact
- * divergence above and hide it behind a path that looks plausible. Loud is correct: the operator's
- * addon is stale and every graph-backed surface would otherwise report an empty repo.
+ * Throws — never falls back to the old hand-join, which is what this module exists to delete (it
+ * would restore the exact divergence above and hide it behind a path that looks plausible) — in two
+ * DISTINCT situations with different remedies, told apart by the error class:
+ *
+ * - {@link CodeGraphRootUnresolvableError}: the engine is CURRENT and resolved no repo-graph root
+ *   (no `WICKED_ESTATE_REPO_GRAPH_ROOT`, no state home, no `HOME`/`USERPROFILE`), so it published an
+ *   EMPTY `code_graph_db` together with a `code_graph_root_unresolvable` finding (wicked-core#406).
+ *   The remedy is the daemon's environment; the finding's message says so. Callers that classify
+ *   "engine too old" must let this one through (`projects/graph.ts assertEngineFresh`).
+ * - a plain `Error` naming wicked-core#170: the field is ABSENT (or empty with no such finding),
+ *   which means the running `wicked-core` addon predates it. The remedy is a rebuild/reinstall.
+ *
+ * Loud is correct in both: every graph-backed surface would otherwise report an empty repo.
  */
 export declare function codeGraphDb(repo: RepoEntry): string;
+/** The engine's finding code for "no repo-graph root resolves" (`RepoEntry.findings[]`, wicked-core#406). */
+export declare const CODE_GRAPH_ROOT_UNRESOLVABLE = "code_graph_root_unresolvable";
+/**
+ * The ONE HTTP mapping every code-graph consumer shares for a `codeGraphDb()` failure this daemon
+ * can classify: **503** for {@link CodeGraphRootUnresolvableError} — a CURRENT engine resolved no
+ * repo-graph root, a daemon-environment fault (neither a bad request nor Fastify's generic 500) —
+ * and `null` for anything else, which the caller maps itself (501 for the stale-addon case on the
+ * project routes; the default elsewhere). Applied on the project-graph routes, the repo surfaces
+ * (`/repos/:id/{graph,graph/blast-radius,domain-graph,requirements…}`) and nowhere else.
+ */
+export declare function codeGraphErrorStatus(err: unknown): number | null;
+/**
+ * A CURRENT engine resolved no repo-graph root for this repo (wicked-core#406) — see
+ * {@link codeGraphDb}. Distinct from the stale-addon `Error` on purpose: `projects/graph.ts` turns
+ * every other `codeGraphDb` throw into `ProjectGraphEngineTooOldError` (501, "reinstall the
+ * addon"), which is the wrong remedy here; this class is what lets it tell the two apart.
+ */
+export declare class CodeGraphRootUnresolvableError extends Error {
+    readonly repoId: string;
+    readonly finding: RepoFinding;
+    constructor(repoId: string, finding: RepoFinding);
+}
 /**
  * The requirements artifacts a repo's domain extraction writes.
  *

package/dist/core/repoPaths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"repoPaths.d.ts","sourceRoot":"","sources":["../../src/core/repoPaths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CASnD;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAEzD;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAE7D"}
+{"version":3,"file":"repoPaths.d.ts","sourceRoot":"","sources":["../../src/core/repoPaths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAanD;AAED,6GAA6G;AAC7G,eAAO,MAAM,4BAA4B,iCAAiC,CAAC;AAE3E;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAEhE;AAED;;;;;GAKG;AACH,qBAAa,8BAA+B,SAAQ,KAAK;IAErD,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,OAAO,EAAE,WAAW;gBADpB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,WAAW;CAKhC;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAEzD;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAE7D"}