akm-cli 0.9.0-rc.0 → 0.9.0-rc.13

package/dist/core/standards/resolve-standards-context.js

@@ -2,86 +2,57 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
- * Dispatch resolver for the standards prompt seam — selects which of the two
- * standards features fires for a given write target, mutually exclusively:
+ * Dispatch resolver for the standards prompt seam.
  *
- *   - **Feature A — wiki schema**: the target is a wiki page (a ref/path under
- *     `wikis/<name>/`, NOT a `raw/` file and NOT a wiki infra file
- *     `schema.md`/`index.md`/`log.md`). Returns that wiki's `schema.md` body.
- *   - **Feature B — stash standards**: the target is any non-wiki asset.
- *     Returns the concatenated `category: convention`/`meta` fact bodies.
- *   - **Neither fires**: a wiki `raw/` file or a wiki infra file. Returns `""`.
- *
- * The two NEVER both fire. Both underlying readers degrade to `""` on
- * missing/malformed input and never throw, so this resolver never throws.
+ * The wiki `schema.md` injection (former "Feature A") was collapsed in chunk 4
+ * with the wiki asset-type death (plan §11 Chunk 4): LLM Wiki content is served
+ * by the `llm-wiki` adapter, which owns its own `schema.md` contract. What
+ * remains is **stash standards**: for any write target, return the concatenated
+ * `category: convention`/`meta` fact bodies plus the per-type SOFT conventions
+ * layer (#646), type-scoped to the write target. The underlying readers degrade
+ * to `""` on missing/malformed input and never throw, so this resolver never
+ * throws.
  */
-import { extractWikiNameFromRef, INDEX_MD, LOG_MD, loadWikiSchema, SCHEMA_MD } from "../../wiki/wiki.js";
+import { typeNameFromConceptId } from "../asset/resolve-ref.js";
 import { resolveStashStandards } from "./resolve-stash-standards.js";
 import { resolveTypeConventions, typeConventionRef } from "./resolve-type-conventions.js";
-/** Wiki infra files that are not authored pages (relative to the wiki root). */
-const WIKI_INFRA_BASENAMES = new Set([SCHEMA_MD, INDEX_MD, LOG_MD]);
 /**
- * Extract the asset type from a canonical ref (`[origin//]type:name`) without
- * throwing. Returns `undefined` for refs that have no `type:` prefix. Kept local
- * and lenient — the per-type resolver validates the result against
- * `getAssetTypes()`, so a bogus prefix here simply yields no convention.
+ * Extract the asset type from a write-target ref without throwing. Returns
+ * `undefined` for refs that carry no recognizable type. Kept local and lenient —
+ * the per-type resolver validates the result against `placementTypes()`, so a
+ * bogus prefix here simply yields no convention.
  */
 function refType(ref) {
     if (!ref)
         return undefined;
     const body = ref.includes("//") ? ref.slice(ref.indexOf("//") + 2) : ref;
-    const colon = body.indexOf(":");
-    if (colon <= 0)
-        return undefined;
-    return body.slice(0, colon).trim() || undefined;
+    // 0.9.0 conceptId `<stash-subdir>/<name>`: delegate to the D-R2 reverse table
+    // so the leading stash subdir maps back to its asset type (the canonical path).
+    return typeNameFromConceptId(body)?.type;
 }
 /**
  * Resolve the standards context for a write target identified by its asset ref.
  *
- * @param ref       Canonical asset ref of the write target (e.g. `skill:foo`,
- *                  `wiki:research/topics/x`). When undefined, the target is a
- *                  non-wiki authoring flow → stash standards.
+ * @param ref       Canonical asset ref of the write target (e.g. `skills/foo`).
+ *                  When undefined, the target is a general authoring flow.
  * @param stashRoot Stash root directory.
  */
 export function resolveStandardsContext(ref, stashRoot) {
-    const wikiName = ref ? extractWikiNameFromRef(ref) : undefined;
-    if (!wikiName) {
-        // Non-wiki asset target → Feature B (general stash standards) plus the
-        // per-type SOFT conventions layer (#646), type-scoped to the write target.
-        const general = resolveStashStandards(stashRoot);
-        const type = refType(ref);
-        // A non-empty body here guarantees `type` is a `getAssetTypes()`-validated
-        // string (the resolver returns "" otherwise).
-        const typeConventions = type ? resolveTypeConventions(stashRoot, type) : "";
-        if (!typeConventions || !type)
-            return general;
-        // Soft, type-scoped guidance — clearly labeled and kept separate from the
-        // HARD (validator-enforced) rules that `authoringRulesForType` injects
-        // downstream. These facts are advice only; they never weaken the gate.
-        const softSection = [
-            `# ${typeConventionRef(type)} (soft per-type conventions — guidance, not enforced)`,
-            typeConventions,
-        ].join("\n");
-        return general ? `${general}\n\n${softSection}` : softSection;
-    }
-    // Wiki target. Extract the page path after `wiki:<name>/`.
-    const prefix = `wiki:${wikiName}/`;
-    const pagePath = ref?.startsWith(prefix) ? ref.slice(prefix.length) : "";
-    // `wiki:<name>` with no page, a `raw/` file, or a wiki infra file → neither
-    // feature fires.
-    if (!pagePath)
-        return "";
-    if (pagePath === "raw" || pagePath.startsWith("raw/"))
-        return "";
-    // Infra files (`schema`/`index`/`log`) are only special at the WIKI ROOT.
-    // A nested page like `wiki:research/analysis/schema` is a genuine page and
-    // must NOT be suppressed, so only check when the page is at root depth.
-    if (!pagePath.includes("/")) {
-        // Refs drop the `.md` extension; compare against both forms defensively.
-        if (WIKI_INFRA_BASENAMES.has(pagePath) || WIKI_INFRA_BASENAMES.has(`${pagePath}.md`)) {
-            return "";
-        }
-    }
-    // A genuine wiki page → Feature A (that wiki's schema body).
-    return loadWikiSchema(stashRoot, wikiName).body;
+    // General stash standards plus the per-type SOFT conventions layer (#646),
+    // type-scoped to the write target.
+    const general = resolveStashStandards(stashRoot);
+    const type = refType(ref);
+    // A non-empty body here guarantees `type` is a `placementTypes()`-validated
+    // string (the resolver returns "" otherwise).
+    const typeConventions = type ? resolveTypeConventions(stashRoot, type) : "";
+    if (!typeConventions || !type)
+        return general;
+    // Soft, type-scoped guidance — clearly labeled and kept separate from the
+    // HARD (validator-enforced) rules that `authoringRulesForType` injects
+    // downstream. These facts are advice only; they never weaken the gate.
+    const softSection = [
+        `# ${typeConventionRef(type)} (soft per-type conventions — guidance, not enforced)`,
+        typeConventions,
+    ].join("\n");
+    return general ? `${general}\n\n${softSection}` : softSection;
 }

package/dist/core/standards/resolve-stash-standards.js

@@ -53,14 +53,14 @@ function collectMarkdownFiles(dir) {
     return results;
 }
 /**
- * Derive a fact ref (`fact:conventions/naming`) from an absolute markdown path
+ * Derive a fact ref (`facts/conventions/naming`) from an absolute markdown path
  * relative to the facts root. Mirrors the canonical-name derivation in
  * `asset-spec.ts` (POSIX separators, `.md` stripped).
  */
 function toFactRef(factsRoot, absPath) {
     const rel = path.relative(factsRoot, absPath).split(path.sep).join("/");
     const name = rel.endsWith(".md") ? rel.slice(0, -3) : rel;
-    return `fact:${name}`;
+    return `${FACTS_SUBDIR}/${name}`;
 }
 export function resolveStashStandards(stashRoot) {
     const factsRoot = path.join(stashRoot, FACTS_SUBDIR);

package/dist/core/standards/resolve-type-conventions.js

@@ -17,20 +17,20 @@
  * hard, validator-rejecting rules: a user editing or deleting one must never be
  * able to weaken the authoring contract the gate enforces (#645 boundary).
  *
- * Selection is by a `getAssetTypes()`-validated basename: only
+ * Selection is by a `placementTypes()`-validated basename: only
  * `facts/conventions/assets/<known-type>.md` resolves. Read directly from disk
  * (no index rebuild); any missing dir/file, unknown type, or read error degrades
  * to `""` and never throws.
  */
 import fs from "node:fs";
 import path from "node:path";
-import { getAssetTypes } from "../asset/asset-spec.js";
+import { placementTypes } from "../asset/asset-placement.js";
 import { parseFrontmatter } from "../asset/frontmatter.js";
 /** Sub-path (under the stash root) for per-type SOFT convention facts. */
 export const TYPE_CONVENTIONS_SUBDIR = path.join("facts", "conventions", "assets");
-/** The `fact:` ref prefix for a per-type convention, e.g. `fact:conventions/assets/skill`. */
+/** The slash conceptId for a per-type convention, e.g. `facts/conventions/assets/skill`. */
 export function typeConventionRef(type) {
-    return `fact:conventions/assets/${type}`;
+    return `facts/conventions/assets/${type}`;
 }
 /**
  * Read the SOFT authoring-convention body for asset type `type`, if a stash
@@ -43,7 +43,7 @@ export function resolveTypeConventions(stashRoot, type) {
     if (!stashRoot || !type)
         return "";
     // Basename MUST be a known asset type — never resolve an arbitrary file.
-    if (!getAssetTypes().includes(type))
+    if (!placementTypes().includes(type))
         return "";
     const abs = path.join(stashRoot, TYPE_CONVENTIONS_SUBDIR, `${type}.md`);
     let raw;

package/dist/core/state/migrations.js

@@ -2,7 +2,7 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { runMigrations as runSqliteMigrations } from "../../storage/engines/sqlite-migrations.js";
-const MIGRATIONS = [
+export const STATE_MIGRATIONS = [
     // ── Migration 001 — initial schema ──────────────────────────────────────────
     {
         id: "001-initial-schema",
@@ -348,12 +348,20 @@ const MIGRATIONS = [
     //
     // One-shot ledger for the legacy filesystem→SQLite proposal import (#578).
     //
-    // Before 0.9.0 the proposal queue lived as per-uuid JSON directories under
-    // `<stashDir>/.akm/proposals/` and the `proposals` table (created in 001) was
-    // dead weight. 0.9.0 makes the table canonical; the first proposal operation
-    // against a stash imports any legacy `proposal.json` files it finds (INSERT
-    // OR IGNORE, so re-runs never duplicate) and records the stash here so later
-    // invocations skip the directory walk entirely.
+    // VESTIGIAL as of the Chunk-8 fold: the legacy `proposal.json` import moved
+    // OUT of the live per-operation path and INTO the one-time migrator
+    // (`scripts/akm-migrate/migrate/legacy/proposal-fs-import.ts`, wired through
+    // `akm-migrate apply`),
+    // whose idempotency is INSERT OR IGNORE on the proposal UUID plus migrate-apply's
+    // own journal — it no longer reads or writes this ledger. The CREATE TABLE
+    // stays because the migration registry is APPEND-ONLY and checksum-sealed:
+    // removing a released fragment would make the schema_migrations ledger of an
+    // already-migrated rc database stop being an exact ordered prefix, and the
+    // runner would refuse to open it. The empty table is harmless.
+    //
+    // Original purpose (pre-fold): the first proposal operation against a stash
+    // imported any legacy `proposal.json` files (INSERT OR IGNORE) and recorded
+    // the stash here so later invocations skipped the directory walk.
     //
     // Indexed (query) columns:
     //   stash_dir    TEXT PK  — absolute stash root the import ran against.
@@ -703,7 +711,7 @@ const MIGRATIONS = [
     // ── Migration 016 — collapse/churn detector (R5) ─────────────────────────────
     //
     // Longitudinal store-health history for the improve pipeline
-    // (docs/design/improve-collapse-churn-detector-design.md).
+    // (docs/architecture/specs/improve-collapse-churn-detector-design.md).
     //
     //   canary_queries — the fixed canary set, minted deterministically from the
     //     live stash on first detector run and NEVER auto-refreshed (silent
@@ -712,7 +720,7 @@ const MIGRATIONS = [
     //     rows stay interpretable. Tens of rows; never purged.
     //
     //   improve_cycle_metrics — one row per qualifying improve cycle (a run where
-    //     consolidate processed ≥1 op or recombine evaluated ≥1 cluster). Every
+    //     consolidate processed ≥1 op). Every
     //     column is a scalar or a size-capped JSON blob (< 2 KB/row by
     //     construction — the result_json lesson applied). Retention: 365 days via
     //     purgeOldCycleMetrics. Trend queries drive the collapse/churn alert
@@ -756,6 +764,226 @@ const MIGRATIONS = [
         ON improve_cycle_metrics(ts);
     `,
     },
+    // Keep the historical profile column untouched. New 0.9 runs identify the
+    // selected improve strategy in this additive column.
+    {
+        id: "017-improve-run-strategy",
+        up: `
+      ALTER TABLE improve_runs ADD COLUMN strategy TEXT;
+      CREATE INDEX IF NOT EXISTS idx_improve_runs_strategy_started ON improve_runs(strategy, started_at);
+    `,
+    },
+    // ── Migration 018 — drop dead-lane schema (Chunk 7, WI-7.3) ──────────────────
+    //
+    // Drops the on-disk schema for three lanes deleted by the 0.9.0 bundle-adapter
+    // refactor. Append-only: migrations 007/010/014 above are left verbatim; this
+    // migration only removes what they created.
+    //
+    //   - recombine_hypotheses (+ its last-seen index) — the whole-corpus
+    //     cross-episodic synthesis pass (migration 014) was deleted in Chunk 7
+    //     WI-7.1 (R28).
+    //   - consolidation_judged — the judged-state cache (#581, migration 007) was
+    //     deleted in Chunk 7 WI-7.3 (plan §5). This is a LIVE behavior change:
+    //     every consolidate run now re-judges unchanged memories (more LLM calls)
+    //     instead of skipping them — see the chunk-7 ledger.
+    //   - asset_outcome.review_pressure (+ its DESC index) — the review-pressure
+    //     lane (#613, migration 010) was deleted in Chunk 7 WI-7.2 (R21); this
+    //     migration finishes the column/index drop the code-side deletion left
+    //     pending. `retrieval_count`/`outcome_score` and their index are untouched.
+    {
+        id: "018-drop-dead-lane-schema",
+        up: `
+      DROP INDEX IF EXISTS idx_recombine_hypotheses_last_seen;
+      DROP TABLE IF EXISTS recombine_hypotheses;
+
+      DROP TABLE IF EXISTS consolidation_judged;
+
+      DROP INDEX IF EXISTS idx_asset_outcome_review_pressure;
+      ALTER TABLE asset_outcome DROP COLUMN review_pressure;
+    `,
+    },
+    // ── Migration 019 — proposal input fingerprints (Chunk 6, WI-6.4) ────────────
+    //
+    // Durable store for the §23.6 input fingerprints that replace the
+    // dedup/cooldown content-hash machinery (plan §4.5): one row per processed
+    // fingerprint (scheme version + source + target ref + target before-hash +
+    // reserved evidence/guidance/evaluator terms + engine/model-id term). A
+    // matching fingerprint skips re-processing the same inputs unless
+    // explicitly forced; rows are pruned with the proposal retention window.
+    // Rejection backoff (the retained cooldown) keeps reading the proposals
+    // table itself and needs no schema.
+    {
+        id: "019-proposal-fingerprints",
+        up: `
+      CREATE TABLE IF NOT EXISTS proposal_fingerprints (
+        stash_dir TEXT NOT NULL,
+        fingerprint TEXT NOT NULL,
+        ref TEXT NOT NULL,
+        source TEXT NOT NULL,
+        model_id TEXT NOT NULL DEFAULT '',
+        proposal_id TEXT,
+        created_at TEXT NOT NULL,
+        PRIMARY KEY (stash_dir, fingerprint)
+      );
+      CREATE INDEX IF NOT EXISTS idx_proposal_fingerprints_ref
+        ON proposal_fingerprints(stash_dir, ref);
+    `,
+    },
+    // ── Migration 020 — three-DB cutover baseline DDL (Chunk 8, WI-8.2) ───────────
+    //
+    // The state.db half of the three-DB merge (plan §3.2/§8, normative §11.4,
+    // chunk-8 cutover design §1). This migration is PURE,
+    // SEALABLE, IDEMPOTENT DDL ONLY — `CREATE TABLE IF NOT EXISTS` (+ indexes),
+    // never a DROP or a data move. The actual data movement (the workflow.db merge,
+    // the usage_events rescue from index.db, the full old-ref→item_ref re-key, and
+    // the workflow.db delete / index.db quarantine) is CODE — a journaled step of
+    // the migrate-apply flow (`scripts/akm-migrate/config-migrate.ts`
+    // `cutover-applied` phase), driven by
+    // `scripts/akm-migrate/migrate/legacy/three-db-cutover.ts`. See the no-DROP
+    // contract carve-out note in `src/core/state-db.ts`.
+    //
+    // The three workflow tables are the 10 pre-cutover workflow migrations
+    // (the frozen `scripts/akm-migrate/migrate/legacy/workflow-migrations-bodies.ts`
+    // base schema + 001–010) folded into one baseline at their FINAL post-010 shape — column
+    // lists, CHECK constraints, and indexes copied verbatim. `usage_events` mirrors
+    // index.db's former `ensureUsageEventsSchema` (`src/indexer/usage/usage-events.ts`),
+    // its new durable home. `legacy_state` mirrors `ensureLegacyStateTable`
+    // (`src/storage/repositories/index-entries-repository.ts`), the orphan
+    // quarantine archive re-homed from index.db (durable, auditable, purgeable).
+    // Nothing else — NO bindings/lifecycle tables (Tier B / deferred, §3.2).
+    {
+        id: "020-three-db-cutover",
+        up: `
+      -- ── workflow_runs (workflows/db.ts base + migrations 001/002/003/006/010) ──
+      CREATE TABLE IF NOT EXISTS workflow_runs (
+        id                  TEXT PRIMARY KEY,
+        workflow_ref        TEXT NOT NULL,
+        workflow_entry_id   INTEGER,
+        workflow_title      TEXT NOT NULL,
+        status              TEXT NOT NULL CHECK (status IN ('active', 'completed', 'blocked', 'failed')),
+        params_json         TEXT NOT NULL DEFAULT '{}',
+        current_step_id     TEXT,
+        created_at          TEXT NOT NULL,
+        updated_at          TEXT NOT NULL,
+        completed_at        TEXT,
+        scope_key           TEXT,
+        agent_harness       TEXT,
+        agent_session_id    TEXT,
+        checkin_armed_at    TEXT,
+        plan_json           TEXT,
+        plan_hash           TEXT,
+        engine_lease_until  TEXT,
+        engine_lease_holder TEXT,
+        plan_ir_version     INTEGER
+      );
+      CREATE INDEX IF NOT EXISTS idx_workflow_runs_ref ON workflow_runs(workflow_ref);
+      CREATE INDEX IF NOT EXISTS idx_workflow_runs_status ON workflow_runs(status);
+      CREATE INDEX IF NOT EXISTS idx_workflow_runs_scope_ref_status
+        ON workflow_runs(scope_key, workflow_ref, status);
+      CREATE INDEX IF NOT EXISTS idx_workflow_runs_agent_session
+        ON workflow_runs(agent_harness, agent_session_id);
+
+      -- ── workflow_run_steps (base + migration 003 summary) ─────────────────────
+      CREATE TABLE IF NOT EXISTS workflow_run_steps (
+        run_id          TEXT NOT NULL,
+        step_id         TEXT NOT NULL,
+        step_title      TEXT NOT NULL,
+        instructions    TEXT NOT NULL,
+        completion_json TEXT,
+        sequence_index  INTEGER NOT NULL,
+        status          TEXT NOT NULL CHECK (status IN ('pending', 'completed', 'blocked', 'failed', 'skipped')),
+        notes           TEXT,
+        evidence_json   TEXT,
+        completed_at    TEXT,
+        summary         TEXT,
+        PRIMARY KEY (run_id, step_id),
+        FOREIGN KEY (run_id) REFERENCES workflow_runs(id) ON DELETE CASCADE
+      );
+      CREATE INDEX IF NOT EXISTS idx_workflow_run_steps_run_sequence
+        ON workflow_run_steps(run_id, sequence_index);
+
+      -- ── workflow_run_units (migration 004 + 005/007/008/009/010 columns) ──────
+      CREATE TABLE IF NOT EXISTS workflow_run_units (
+        run_id           TEXT NOT NULL,
+        unit_id          TEXT NOT NULL,
+        step_id          TEXT,
+        node_id          TEXT NOT NULL,
+        parent_unit_id   TEXT,
+        phase            TEXT,
+        runner           TEXT,
+        model            TEXT,
+        status           TEXT NOT NULL CHECK (status IN ('pending', 'running', 'completed', 'failed', 'skipped')),
+        input_hash       TEXT,
+        result_json      TEXT,
+        tokens           INTEGER,
+        failure_reason   TEXT,
+        worktree_path    TEXT,
+        started_at       TEXT,
+        finished_at      TEXT,
+        session_id       TEXT,
+        last_checkin_at  TEXT,
+        attempts         INTEGER NOT NULL DEFAULT 1,
+        claim_holder     TEXT,
+        claim_expires_at TEXT,
+        engine           TEXT,
+        PRIMARY KEY (run_id, unit_id),
+        FOREIGN KEY (run_id) REFERENCES workflow_runs(id) ON DELETE CASCADE
+      );
+      CREATE INDEX IF NOT EXISTS idx_workflow_run_units_run_step
+        ON workflow_run_units(run_id, step_id);
+
+      -- ── usage_events (index.db ensureUsageEventsSchema — the durable new home) ─
+      CREATE TABLE IF NOT EXISTS usage_events (
+        id         INTEGER PRIMARY KEY AUTOINCREMENT,
+        event_type TEXT NOT NULL,
+        query      TEXT,
+        entry_id   INTEGER,
+        entry_ref  TEXT,
+        signal     TEXT,
+        metadata   TEXT,
+        source     TEXT NOT NULL DEFAULT 'user',
+        created_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+      CREATE INDEX IF NOT EXISTS idx_usage_events_entry ON usage_events(entry_id);
+      CREATE INDEX IF NOT EXISTS idx_usage_events_type ON usage_events(event_type);
+      CREATE INDEX IF NOT EXISTS idx_usage_events_ref ON usage_events(entry_ref);
+      CREATE INDEX IF NOT EXISTS idx_usage_events_source ON usage_events(source);
+
+      -- ── legacy_state (ensureLegacyStateTable — the orphan quarantine archive) ──
+      CREATE TABLE IF NOT EXISTS legacy_state (
+        surface        TEXT NOT NULL,
+        old_ref        TEXT NOT NULL,
+        row_count      INTEGER NOT NULL DEFAULT 0,
+        reason         TEXT NOT NULL,
+        quarantined_at TEXT NOT NULL DEFAULT (datetime('now')),
+        PRIMARY KEY (surface, old_ref)
+      );
+    `,
+    },
+    // ── Migration 021 — asset_salience / asset_outcome: missing_since (#733) ────
+    //
+    // Orphan-GC grace clock (Workstream C / #733,
+    // docs/architecture/specs/0.9.0-close-out-plan.md). Neither table carries a
+    // column that records when a row's ref STOPPED resolving against
+    // `entries.item_ref` — `updated_at` is bumped by improve itself on every
+    // touch, so it cannot double as a "went missing" timestamp.
+    //
+    // `missing_since` is stamped by `runOrphanStateGcPass`
+    // (src/commands/improve/loop-stages.ts) the first time a row's ref fails to
+    // resolve against the live index, cleared the moment the ref resolves
+    // again, and used to gate deletion once `STATE_GC_GRACE_MS` (7 days) has
+    // elapsed — and ONLY when `improve.stateGc.collect` is true (default
+    // false). Mirrors the additive ADD-COLUMN style of migration 011.
+    //
+    // NULL = never missing (the steady-state default for every existing row —
+    // both a fresh row and a pre-migration row read back NULL here).
+    {
+        id: "021-asset-state-missing-since",
+        up: `
+      ALTER TABLE asset_salience ADD COLUMN missing_since INTEGER DEFAULT NULL;
+      ALTER TABLE asset_outcome ADD COLUMN missing_since INTEGER DEFAULT NULL;
+    `,
+    },
 ];
 /**
  * Apply every pending migration in a single transaction per migration.
@@ -765,6 +993,9 @@ const MIGRATIONS = [
  *
  * Called automatically by `openStateDatabase()`.
  */
-export function runMigrations(db) {
-    runSqliteMigrations(db, MIGRATIONS);
+export function runMigrations(db, options) {
+    runSqliteMigrations(db, STATE_MIGRATIONS, {
+        applyPending: options?.applyPending,
+        generationMarker: options?.generationMarker,
+    });
 }

package/dist/core/state-db.js

@@ -8,8 +8,8 @@
  * the managed-db open/loan wrappers, the `BEGIN IMMEDIATE` transaction helper,
  * and schema introspection. The table-specific query helpers live by domain in
  * `src/storage/repositories/*-repository.ts` (events, proposals, task-history,
- * improve-runs, extract-sessions, consolidation, recombine, embeddings,
- * canaries); importers reference those modules directly. The migration engine
+ * improve-runs, extract-sessions, consolidation, embeddings, canaries);
+ * importers reference those modules directly. The migration engine
  * lives in `./state/migrations`.
  *
  * The state DB replaces flat-file storage for data that is NON-REGENERABLE —
@@ -37,6 +37,21 @@
  *   - CREATE INDEX IF NOT EXISTS …
  *   - CREATE TABLE IF NOT EXISTS … (additive new tables)
  *
+ * ## Three-DB cutover carve-out (Chunk 8, migration `020-three-db-cutover`)
+ *
+ * The 0.9.0 three-DB merge folds workflow.db and index.db's durable rows
+ * (`usage_events`, `legacy_state`) into state.db. That migration is still pure
+ * additive DDL and DROPS NOTHING — it only `CREATE TABLE IF NOT EXISTS`es the
+ * merge-target tables at their final shape. The one-time, filesystem-derived,
+ * fail-closed DATA movement (the workflow.db merge, the usage_events rescue, the
+ * full old-ref→item_ref re-key, and the workflow.db unlink / index.db quarantine
+ * rename) is deliberately NOT a sealed SQL migration body: it is a journaled step
+ * of the migrate-apply coordinator (`scripts/akm-migrate/config-migrate.ts`
+ * `cutover-applied` phase →
+ * `scripts/akm-migrate/migrate/legacy/three-db-cutover.ts`). So the no-DROP
+ * contract here is intact — the physical workflow.db deletion happens outside
+ * the ledger DDL, under the backup-verified-restorable fail-closed gate.
+ *
  * ## Schema design: indexed columns vs. metadata_json
  *
  * Each table holds only the columns needed for indexed queries as first-class
@@ -55,9 +70,15 @@
  *
  * @module state-db
  */
+import fs from "node:fs";
 import path from "node:path";
-import { openManagedDatabase, withManagedDb, withManagedDbAsync } from "../storage/managed-db.js";
+import { openDatabase } from "../storage/database.js";
+import { assertCurrentMigrationLedger, assertMigrationLedger } from "../storage/engines/sqlite-migrations.js";
+import { openManagedDatabase, withManagedDb } from "../storage/managed-db.js";
+import { acquireMaintenanceActivitySync } from "./maintenance-barrier.js";
+import { assertNoPendingMigrationOperation } from "./migration-operation.js";
 import { getDataDir } from "./paths.js";
+import { runMigrations, STATE_MIGRATIONS } from "./state/migrations.js";
 // ── Path helper ──────────────────────────────────────────────────────────────
 /**
  * Default path: `<dataDir>/state.db`.
@@ -96,7 +117,61 @@ export function getStateDbPath() {
  *     narrow when a post-inference reindex overlapped a parallel event write.
  */
 export function openStateDatabase(dbPath) {
-    return openManagedDatabase({ path: dbPath ?? getStateDbPath(), init: runMigrations });
+    const canonicalPath = getStateDbPath();
+    const resolvedPath = dbPath ?? canonicalPath;
+    const isCanonical = path.resolve(resolvedPath) === path.resolve(canonicalPath);
+    if (isCanonical)
+        assertNoPendingMigrationOperation();
+    const releaseActivity = isCanonical ? acquireMaintenanceActivitySync("state-db") : undefined;
+    try {
+        if (isCanonical)
+            assertNoPendingMigrationOperation();
+        const existed = fs.existsSync(resolvedPath);
+        if (existed) {
+            const preflight = openDatabase(resolvedPath, { readonly: true });
+            try {
+                preflight.exec("PRAGMA busy_timeout = 30000");
+                if (isCanonical)
+                    assertCurrentMigrationLedger(preflight, STATE_MIGRATIONS);
+                else
+                    assertMigrationLedger(preflight, STATE_MIGRATIONS);
+            }
+            finally {
+                preflight.close();
+            }
+        }
+        const db = openManagedDatabase({
+            path: resolvedPath,
+            init: (db) => runMigrations(db, { applyPending: !(isCanonical && existed) }),
+        });
+        if (!releaseActivity)
+            return db;
+        let closed = false;
+        return {
+            prepare: db.prepare.bind(db),
+            exec: db.exec.bind(db),
+            run: db.run.bind(db),
+            transaction: db.transaction.bind(db),
+            get inTransaction() {
+                return db.inTransaction;
+            },
+            close() {
+                if (closed)
+                    return;
+                closed = true;
+                try {
+                    db.close();
+                }
+                finally {
+                    releaseActivity();
+                }
+            },
+        };
+    }
+    catch (error) {
+        releaseActivity?.();
+        throw error;
+    }
 }
 /**
  * Run `fn` against state.db, owning the handle unless one is borrowed. The loan
@@ -109,19 +184,32 @@ export function withStateDb(fn, opts) {
     return withManagedDb(() => openStateDatabase(opts?.path), fn, opts);
 }
 /**
- * Async sibling of {@link withStateDb} — for `fn`s that hold the handle across
- * an `await` (the sync version would close it too early). Same borrow/own +
- * optional `path` override semantics.
+ * Fire-and-forget telemetry write to state.db (Chunk-8 WI-8.3: usage_events'
+ * durable home). Skips entirely when state.db does not exist yet (never
+ * fabricates an un-migrated DB); otherwise opens the migrated DB and lowers
+ * `busy_timeout` to a short window so a contended state.db (e.g. a reindex
+ * finalize holding the write lock while relinking usage_events) never stalls a
+ * hot path — mirrors `withIndexDb`'s `TELEMETRY_BUSY_TIMEOUT_MS`. WAL mode lets
+ * the read-only migration-preflight run concurrently with a writer, so the open
+ * itself does not block. Callers wrap this in their own try/catch.
  */
-export function withStateDbAsync(fn, opts) {
-    return withManagedDbAsync(() => openStateDatabase(opts?.path), fn, opts);
+export function withStateDbTelemetry(fn, busyTimeoutMs = 250) {
+    if (!fs.existsSync(getStateDbPath()))
+        return;
+    const db = openStateDatabase();
+    try {
+        db.exec(`PRAGMA busy_timeout = ${Math.max(0, Math.floor(busyTimeoutMs))}`);
+        fn(db);
+    }
+    finally {
+        db.close();
+    }
 }
 // ── Migration engine ─────────────────────────────────────────────────────────
 //
 // The MIGRATIONS registry + runMigrations live in ./state/migrations (the single
 // append-only ordered source of truth). Imported for internal use by
 // openStateDatabase.
-import { runMigrations } from "./state/migrations.js";
 // ── BEGIN IMMEDIATE transaction helper ───────────────────────────────────────
 /**
  * Run `fn` inside a `BEGIN IMMEDIATE` transaction.

package/dist/core/structured.js

@@ -15,7 +15,7 @@
  *
  * Layering: this file lives in `core/` — NOT `llm/` — because the agent path
  * must be able to reach it and `agent/ ⇏ llm/` is an enforced invariant
- * (`tests/architecture/agent-no-llm-sdk-guard.test.ts`). The transport is
+ * (`tests/integration/architecture/agent-no-llm-sdk-guard.test.ts`). The transport is
  * always injected; this module never performs IO of its own.
  *
  * Retry semantics: only parse/validation misses are retried (with corrective