@crouton-kit/crouter 0.3.40 → 0.3.42

package/dist/hearth/control-plane/db.d.ts

@@ -1,30 +0,0 @@
-import { DatabaseSync } from 'node:sqlite';
-/** Resolve the CP SQLite db file path: an explicit `CRTR_HEARTH_CP_DB_PATH`
- *  override, else `<dataDir>/control-plane.db` where `dataDir` follows the
- *  same `CRTR_HEARTH_CP_DATA_DIR` convention `secrets.ts` uses. Deliberately
- *  independent of `canvasDbPath()` / `CRTR_HOME` — the control plane is not a
- *  canvas node and must not share or collide with a home's canvas db. */
-export declare function controlPlaneDbPath(env?: NodeJS.ProcessEnv): string;
-/** The ordered migration list. Index `i` is migration version `i + 1`; the
- *  db's `user_version` tracks how many have been applied. Append only. */
-export declare const MIGRATIONS: ReadonlyArray<(db: DatabaseSync) => void>;
-/** Bring `db` up to the latest schema version. Reads `user_version`, runs
- *  each pending migration in order, and bumps `user_version` after each so
- *  the work is gated and idempotent: re-running is a no-op once
- *  `user_version` reaches `MIGRATIONS.length`. Forward-only. */
-export declare function migrate(db: DatabaseSync): void;
-/** Open (or reuse) the CP db at `path`, initializing WAL + schema on first
- *  open. This is the SOLE function in the codebase that may construct a
- *  `DatabaseSync` against the CP db file — every CP store goes through this
- *  (directly or via `getControlPlaneDb()`) and never opens its own
- *  connection. Keyed by path so tests with distinct temp dbs get independent
- *  handles, exactly like `src/core/canvas/db.ts`'s `openDb()`. */
-export declare function openControlPlaneDb(path: string): DatabaseSync;
-/** The cached handle accessor every CP store (registry, scheduler, ingress)
- *  imports — resolves the db path the standard way and opens/reuses the one
- *  connection for it. Never construct a second `DatabaseSync` against the CP
- *  db elsewhere in the codebase. */
-export declare function getControlPlaneDb(env?: NodeJS.ProcessEnv): DatabaseSync;
-/** Close and forget the handle for `path` (defaults to the standard
- *  resolved path). Mainly for tests. */
-export declare function closeControlPlaneDb(path?: string): void;

package/dist/hearth/control-plane/db.js

@@ -1,561 +0,0 @@
-// control-plane.db — the CP's own SQLite store, separate from canvas.db. This
-// module is the SOLE owner of the cached `DatabaseSync` connection and the
-// migration gate: every other CP store (registry, scheduler, ingress) imports
-// `getControlPlaneDb()` from here rather than opening a second connection
-// (master plan decision 9 / orchestration brief non-negotiable). It lives on
-// the CP's own data volume — NOT canvas home, NOT `canvasDbPath()` — because
-// the control plane is a separate always-on process from any home/node.
-//
-// Mirrors `src/core/canvas/db.ts` exactly: `DatabaseSync` + WAL, schema
-// expressed as a forward-only `MIGRATIONS` list gated by `PRAGMA user_version`.
-// Migrations are append-only — never edit a shipped step.
-import { DatabaseSync } from 'node:sqlite';
-import { existsSync, mkdirSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-const ENV = {
-    // Same data-dir convention `secrets.ts` (P1.3) uses, so the CP's SQLite db
-    // and its secrets file default to living side by side on one data volume.
-    dataDir: 'CRTR_HEARTH_CP_DATA_DIR',
-    // Explicit override for the db file itself, for deployments that want the
-    // db on a different mount than the rest of the CP data dir.
-    dbPath: 'CRTR_HEARTH_CP_DB_PATH',
-};
-const DB_FILE_NAME = 'control-plane.db';
-function expandHomePath(input) {
-    if (input.startsWith('~'))
-        return join(homedir(), input.slice(1));
-    return resolve(input);
-}
-function defaultDataDir(env) {
-    const dataDir = env[ENV.dataDir]?.trim();
-    return dataDir !== undefined && dataDir !== ''
-        ? expandHomePath(dataDir)
-        : expandHomePath('~/.crouter/hearth-control-plane');
-}
-/** Resolve the CP SQLite db file path: an explicit `CRTR_HEARTH_CP_DB_PATH`
- *  override, else `<dataDir>/control-plane.db` where `dataDir` follows the
- *  same `CRTR_HEARTH_CP_DATA_DIR` convention `secrets.ts` uses. Deliberately
- *  independent of `canvasDbPath()` / `CRTR_HOME` — the control plane is not a
- *  canvas node and must not share or collide with a home's canvas db. */
-export function controlPlaneDbPath(env = process.env) {
-    const override = env[ENV.dbPath]?.trim();
-    if (override !== undefined && override !== '')
-        return expandHomePath(override);
-    return join(defaultDataDir(env), DB_FILE_NAME);
-}
-// --- Schema as a forward-only migration list ------------------------------
-/** v1 — the `home` registry table (design.md §5.1). `home_id` is the stable
- *  PK, independent of provider sandbox/node churn; `schedule` and
- *  `ingress_route` (added by later sibling migrations against this same
- *  handle) FK to it. Every secret is stored as a HANDLE
- *  (`relay_auth_ref`) — never a model credential, never an inline value
- *  (R-REG-3 / R-CP-8). `IF NOT EXISTS` makes this a no-op on re-open. */
-function homeTable(db) {
-    db.exec(`
-CREATE TABLE IF NOT EXISTS home (
-  home_id                 TEXT PRIMARY KEY,
-  tenant_id               TEXT NOT NULL,
-  user_id                 TEXT NOT NULL,
-  provider                TEXT NOT NULL DEFAULT 'blaxel',
-  provider_sandbox_id     TEXT,
-  provider_volume_id      TEXT,
-  preview_endpoint        TEXT,
-  home_agent_target       TEXT,
-  relay_auth_ref          TEXT,
-  status                  TEXT NOT NULL DEFAULT 'provisioning',
-  template_version        TEXT,
-  last_ready_at           TEXT,
-  last_wake_at            TEXT,
-  last_suspend_at         TEXT,
-  last_wake_latency_ms    INTEGER,
-  health_verdict          TEXT NOT NULL DEFAULT 'unknown',
-  created_at              TEXT NOT NULL,
-  updated_at              TEXT NOT NULL
-);
-
-CREATE INDEX IF NOT EXISTS idx_home_tenant_user ON home(tenant_id, user_id);
-CREATE INDEX IF NOT EXISTS idx_home_provider_sandbox ON home(provider_sandbox_id);
-`);
-}
-/** v2 — cron schedule definitions. `next_fire_at` is the durable timer the CP
- *  scan loop selects on; home agents keep no cron scheduler state. */
-function scheduleTable(db) {
-    db.exec(`
-CREATE TABLE IF NOT EXISTS schedule (
-  schedule_id       TEXT PRIMARY KEY,
-  tenant_id         TEXT NOT NULL,
-  user_id           TEXT NOT NULL,
-  home_id           TEXT NOT NULL,
-  label             TEXT NOT NULL,
-  recurrence        TEXT NOT NULL,
-  timezone          TEXT NOT NULL,
-  delivery_payload  TEXT NOT NULL,
-  next_fire_at      TEXT NOT NULL,
-  last_fired_at     TEXT,
-  enabled           INTEGER NOT NULL DEFAULT 1,
-  created_at        TEXT NOT NULL,
-  updated_at        TEXT NOT NULL,
-  FOREIGN KEY (home_id) REFERENCES home(home_id) ON DELETE CASCADE,
-  CHECK (enabled IN (0, 1))
-);
-
-CREATE INDEX IF NOT EXISTS idx_schedule_next_fire_at ON schedule(next_fire_at);
-CREATE INDEX IF NOT EXISTS idx_schedule_tenant_user ON schedule(tenant_id, user_id);
-CREATE INDEX IF NOT EXISTS idx_schedule_home ON schedule(home_id);
-`);
-}
-/** v3 — cron fire idempotency ledger. The unique slot key is the load-bearing
- *  restart/double-scan guard: one schedule can own only one fire per instant. */
-function scheduleFireTable(db) {
-    db.exec(`
-CREATE TABLE IF NOT EXISTS schedule_fire (
-  fire_id        TEXT PRIMARY KEY,
-  schedule_id    TEXT NOT NULL,
-  home_id        TEXT NOT NULL,
-  tenant_id      TEXT NOT NULL,
-  user_id        TEXT NOT NULL,
-  scheduled_for  TEXT NOT NULL,
-  state          TEXT NOT NULL DEFAULT 'pending',
-  attempts       INTEGER NOT NULL DEFAULT 0,
-  last_error     TEXT,
-  delivered_at   TEXT,
-  created_at     TEXT NOT NULL,
-  updated_at     TEXT NOT NULL,
-  FOREIGN KEY (schedule_id) REFERENCES schedule(schedule_id) ON DELETE CASCADE,
-  FOREIGN KEY (home_id) REFERENCES home(home_id) ON DELETE CASCADE,
-  UNIQUE (schedule_id, scheduled_for),
-  CHECK (state IN ('pending', 'waking', 'delivered', 'failed')),
-  CHECK (attempts >= 0)
-);
-
-CREATE INDEX IF NOT EXISTS idx_schedule_fire_schedule ON schedule_fire(schedule_id);
-CREATE INDEX IF NOT EXISTS idx_schedule_fire_home ON schedule_fire(home_id);
-CREATE INDEX IF NOT EXISTS idx_schedule_fire_resumable ON schedule_fire(state, scheduled_for);
-CREATE INDEX IF NOT EXISTS idx_schedule_fire_tenant_user ON schedule_fire(tenant_id, user_id);
-`);
-}
-/** v4 — public ingress demux routes. `(channel, routing_key)` is deliberately
- *  globally unique because public webhook/phone/email addresses are global. */
-function ingressRouteTable(db) {
-    db.exec(`
-CREATE TABLE IF NOT EXISTS ingress_route (
-  route_id            TEXT PRIMARY KEY,
-  tenant_id           TEXT NOT NULL,
-  user_id             TEXT NOT NULL,
-  home_id             TEXT NOT NULL,
-  channel             TEXT NOT NULL,
-  routing_key         TEXT NOT NULL,
-  routing_key_kind    TEXT NOT NULL,
-  channel_secret_ref  TEXT,
-  delivery_template   TEXT NOT NULL,
-  enabled             INTEGER NOT NULL DEFAULT 1,
-  created_at          TEXT NOT NULL,
-  updated_at          TEXT NOT NULL,
-  FOREIGN KEY (home_id) REFERENCES home(home_id) ON DELETE CASCADE,
-  UNIQUE (channel, routing_key),
-  CHECK (enabled IN (0, 1))
-);
-
-CREATE INDEX IF NOT EXISTS idx_ingress_route_lookup ON ingress_route(channel, routing_key);
-CREATE INDEX IF NOT EXISTS idx_ingress_route_tenant_user ON ingress_route(tenant_id, user_id);
-CREATE INDEX IF NOT EXISTS idx_ingress_route_home ON ingress_route(home_id);
-`);
-}
-/** v5 — webhook replay/idempotency ledger. Stores delivery identity and hashes
- *  only; raw public webhook bodies belong in the transient request path. */
-function webhookDeliveryTable(db) {
-    db.exec(`
-CREATE TABLE IF NOT EXISTS webhook_delivery (
-  delivery_id          TEXT PRIMARY KEY,
-  route_id             TEXT NOT NULL,
-  tenant_id            TEXT NOT NULL,
-  user_id              TEXT NOT NULL,
-  home_id              TEXT NOT NULL,
-  replay_key           TEXT NOT NULL,
-  replay_window_start  TEXT NOT NULL,
-  payload_sha256       TEXT,
-  signature_sha256     TEXT,
-  state                TEXT NOT NULL DEFAULT 'received',
-  received_at          TEXT NOT NULL,
-  delivered_at         TEXT,
-  last_error           TEXT,
-  created_at           TEXT NOT NULL,
-  updated_at           TEXT NOT NULL,
-  FOREIGN KEY (route_id) REFERENCES ingress_route(route_id) ON DELETE CASCADE,
-  FOREIGN KEY (home_id) REFERENCES home(home_id) ON DELETE CASCADE,
-  UNIQUE (route_id, replay_key, replay_window_start),
-  CHECK (state IN ('received', 'delivered', 'rejected', 'failed'))
-);
-
-CREATE INDEX IF NOT EXISTS idx_webhook_delivery_route ON webhook_delivery(route_id, received_at);
-CREATE INDEX IF NOT EXISTS idx_webhook_delivery_home ON webhook_delivery(home_id, received_at);
-CREATE INDEX IF NOT EXISTS idx_webhook_delivery_tenant_user ON webhook_delivery(tenant_id, user_id);
-`);
-}
-/** v6 — append-only trigger delivery audit. Stores operational metadata and
- *  content hashes; no public payload body and no secret literal columns. */
-function triggerAuditTable(db) {
-    db.exec(`
-CREATE TABLE IF NOT EXISTS trigger_audit (
-  audit_id        TEXT PRIMARY KEY,
-  tenant_id       TEXT NOT NULL,
-  user_id         TEXT NOT NULL,
-  home_id         TEXT NOT NULL,
-  source          TEXT NOT NULL,
-  source_ref      TEXT NOT NULL,
-  trigger_id      TEXT NOT NULL,
-  tier            TEXT NOT NULL,
-  outcome         TEXT NOT NULL,
-  reason          TEXT,
-  payload_sha256  TEXT,
-  metadata_json   TEXT,
-  at              TEXT NOT NULL,
-  FOREIGN KEY (home_id) REFERENCES home(home_id) ON DELETE CASCADE,
-  CHECK (source IN ('cron', 'webhook')),
-  CHECK (tier IN ('critical', 'urgent', 'normal', 'deferred')),
-  CHECK (outcome IN ('delivered', 'rejected', 'failed'))
-);
-
-CREATE INDEX IF NOT EXISTS idx_trigger_audit_home_at ON trigger_audit(home_id, at);
-CREATE INDEX IF NOT EXISTS idx_trigger_audit_tenant_user_at ON trigger_audit(tenant_id, user_id, at);
-CREATE INDEX IF NOT EXISTS idx_trigger_audit_trigger ON trigger_audit(trigger_id);
-`);
-}
-/** v7 — DB-level consistency guards for denormalized tenant/user/home keys.
- *  Stores derive these values from parents; these triggers keep direct SQL from
- *  making tenant/user columns untrustworthy query or security boundaries. */
-function tenantIdentityTriggers(db) {
-    db.exec(`
-CREATE TRIGGER IF NOT EXISTS trg_schedule_identity_insert
-BEFORE INSERT ON schedule
-FOR EACH ROW
-WHEN NOT EXISTS (
-  SELECT 1 FROM home
-  WHERE home_id = NEW.home_id AND tenant_id = NEW.tenant_id AND user_id = NEW.user_id
-)
-BEGIN
-  SELECT RAISE(ABORT, 'schedule tenant/user/home mismatch');
-END;
-
-CREATE TRIGGER IF NOT EXISTS trg_schedule_identity_update
-BEFORE UPDATE OF home_id, tenant_id, user_id ON schedule
-FOR EACH ROW
-WHEN NOT EXISTS (
-  SELECT 1 FROM home
-  WHERE home_id = NEW.home_id AND tenant_id = NEW.tenant_id AND user_id = NEW.user_id
-)
-BEGIN
-  SELECT RAISE(ABORT, 'schedule tenant/user/home mismatch');
-END;
-
-CREATE TRIGGER IF NOT EXISTS trg_schedule_fire_identity_insert
-BEFORE INSERT ON schedule_fire
-FOR EACH ROW
-WHEN NOT EXISTS (
-  SELECT 1 FROM schedule
-  WHERE schedule_id = NEW.schedule_id
-    AND home_id = NEW.home_id
-    AND tenant_id = NEW.tenant_id
-    AND user_id = NEW.user_id
-)
-BEGIN
-  SELECT RAISE(ABORT, 'schedule_fire schedule identity mismatch');
-END;
-
-CREATE TRIGGER IF NOT EXISTS trg_schedule_fire_identity_update
-BEFORE UPDATE OF schedule_id, home_id, tenant_id, user_id ON schedule_fire
-FOR EACH ROW
-WHEN NOT EXISTS (
-  SELECT 1 FROM schedule
-  WHERE schedule_id = NEW.schedule_id
-    AND home_id = NEW.home_id
-    AND tenant_id = NEW.tenant_id
-    AND user_id = NEW.user_id
-)
-BEGIN
-  SELECT RAISE(ABORT, 'schedule_fire schedule identity mismatch');
-END;
-
-CREATE TRIGGER IF NOT EXISTS trg_ingress_route_identity_insert
-BEFORE INSERT ON ingress_route
-FOR EACH ROW
-WHEN NOT EXISTS (
-  SELECT 1 FROM home
-  WHERE home_id = NEW.home_id AND tenant_id = NEW.tenant_id AND user_id = NEW.user_id
-)
-BEGIN
-  SELECT RAISE(ABORT, 'ingress_route tenant/user/home mismatch');
-END;
-
-CREATE TRIGGER IF NOT EXISTS trg_ingress_route_identity_update
-BEFORE UPDATE OF home_id, tenant_id, user_id ON ingress_route
-FOR EACH ROW
-WHEN NOT EXISTS (
-  SELECT 1 FROM home
-  WHERE home_id = NEW.home_id AND tenant_id = NEW.tenant_id AND user_id = NEW.user_id
-)
-BEGIN
-  SELECT RAISE(ABORT, 'ingress_route tenant/user/home mismatch');
-END;
-
-CREATE TRIGGER IF NOT EXISTS trg_webhook_delivery_identity_insert
-BEFORE INSERT ON webhook_delivery
-FOR EACH ROW
-WHEN NOT EXISTS (
-  SELECT 1 FROM ingress_route
-  WHERE route_id = NEW.route_id
-    AND home_id = NEW.home_id
-    AND tenant_id = NEW.tenant_id
-    AND user_id = NEW.user_id
-)
-BEGIN
-  SELECT RAISE(ABORT, 'webhook_delivery route identity mismatch');
-END;
-
-CREATE TRIGGER IF NOT EXISTS trg_webhook_delivery_identity_update
-BEFORE UPDATE OF route_id, home_id, tenant_id, user_id ON webhook_delivery
-FOR EACH ROW
-WHEN NOT EXISTS (
-  SELECT 1 FROM ingress_route
-  WHERE route_id = NEW.route_id
-    AND home_id = NEW.home_id
-    AND tenant_id = NEW.tenant_id
-    AND user_id = NEW.user_id
-)
-BEGIN
-  SELECT RAISE(ABORT, 'webhook_delivery route identity mismatch');
-END;
-
-CREATE TRIGGER IF NOT EXISTS trg_trigger_audit_identity_insert
-BEFORE INSERT ON trigger_audit
-FOR EACH ROW
-WHEN (
-  NEW.source = 'cron'
-  AND NOT EXISTS (
-    SELECT 1 FROM schedule_fire
-    WHERE fire_id = NEW.source_ref
-      AND home_id = NEW.home_id
-      AND tenant_id = NEW.tenant_id
-      AND user_id = NEW.user_id
-  )
-) OR (
-  NEW.source = 'webhook'
-  AND NOT EXISTS (
-    SELECT 1 FROM ingress_route
-    WHERE route_id = NEW.source_ref
-      AND home_id = NEW.home_id
-      AND tenant_id = NEW.tenant_id
-      AND user_id = NEW.user_id
-  )
-)
-BEGIN
-  SELECT RAISE(ABORT, 'trigger_audit source identity mismatch');
-END;
-
-CREATE TRIGGER IF NOT EXISTS trg_trigger_audit_identity_update
-BEFORE UPDATE OF source, source_ref, home_id, tenant_id, user_id ON trigger_audit
-FOR EACH ROW
-WHEN (
-  NEW.source = 'cron'
-  AND NOT EXISTS (
-    SELECT 1 FROM schedule_fire
-    WHERE fire_id = NEW.source_ref
-      AND home_id = NEW.home_id
-      AND tenant_id = NEW.tenant_id
-      AND user_id = NEW.user_id
-  )
-) OR (
-  NEW.source = 'webhook'
-  AND NOT EXISTS (
-    SELECT 1 FROM ingress_route
-    WHERE route_id = NEW.source_ref
-      AND home_id = NEW.home_id
-      AND tenant_id = NEW.tenant_id
-      AND user_id = NEW.user_id
-  )
-)
-BEGIN
-  SELECT RAISE(ABORT, 'trigger_audit source identity mismatch');
-END;
-`);
-}
-/** v8 — parent-identity update guards. v7 validates a child row's own
- *  denormalized tenant/user/home tuple against its immediate parent on
- *  INSERT/UPDATE, but said nothing about editing the PARENT side: nothing
- *  stopped `UPDATE home SET tenant_id = ...` (or schedule/ingress_route/
- *  schedule_fire identity columns) out from under existing children, which
- *  would strand them with stale denormalized keys without tripping any
- *  v7 check (those only fire on the child table). These triggers reject an
- *  identity-column update on a parent row whenever a dependent child row
- *  already exists, so identity is write-once after first child creation;
- *  non-identity columns (status, timestamps, next_fire_at, metadata, etc.)
- *  are untouched by these triggers and remain freely updatable. Each guard
- *  checks only its immediate denormalizing child(ren) — sufficient because
- *  v7 already keeps every deeper descendant's copy in lockstep with that
- *  immediate child for as long as the immediate child row exists. */
-function parentIdentityUpdateGuards(db) {
-    db.exec(`
-CREATE TRIGGER IF NOT EXISTS trg_home_identity_update_guard
-BEFORE UPDATE OF tenant_id, user_id ON home
-FOR EACH ROW
-WHEN (NEW.tenant_id IS NOT OLD.tenant_id OR NEW.user_id IS NOT OLD.user_id)
-  AND (
-    EXISTS (SELECT 1 FROM schedule WHERE home_id = OLD.home_id)
-    OR EXISTS (SELECT 1 FROM ingress_route WHERE home_id = OLD.home_id)
-    OR EXISTS (SELECT 1 FROM trigger_audit WHERE home_id = OLD.home_id)
-  )
-BEGIN
-  SELECT RAISE(ABORT, 'home identity update blocked: dependent schedule/ingress_route/trigger_audit rows exist');
-END;
-
-CREATE TRIGGER IF NOT EXISTS trg_schedule_identity_update_guard
-BEFORE UPDATE OF home_id, tenant_id, user_id ON schedule
-FOR EACH ROW
-WHEN (
-    NEW.home_id IS NOT OLD.home_id
-    OR NEW.tenant_id IS NOT OLD.tenant_id
-    OR NEW.user_id IS NOT OLD.user_id
-  )
-  AND EXISTS (SELECT 1 FROM schedule_fire WHERE schedule_id = OLD.schedule_id)
-BEGIN
-  SELECT RAISE(ABORT, 'schedule identity update blocked: dependent schedule_fire rows exist');
-END;
-
-CREATE TRIGGER IF NOT EXISTS trg_ingress_route_identity_update_guard
-BEFORE UPDATE OF home_id, tenant_id, user_id ON ingress_route
-FOR EACH ROW
-WHEN (
-    NEW.home_id IS NOT OLD.home_id
-    OR NEW.tenant_id IS NOT OLD.tenant_id
-    OR NEW.user_id IS NOT OLD.user_id
-  )
-  AND (
-    EXISTS (SELECT 1 FROM webhook_delivery WHERE route_id = OLD.route_id)
-    OR EXISTS (
-      SELECT 1 FROM trigger_audit WHERE source = 'webhook' AND source_ref = OLD.route_id
-    )
-  )
-BEGIN
-  SELECT RAISE(ABORT, 'ingress_route identity update blocked: dependent webhook_delivery/trigger_audit rows exist');
-END;
-
-CREATE TRIGGER IF NOT EXISTS trg_schedule_fire_identity_update_guard
-BEFORE UPDATE OF schedule_id, home_id, tenant_id, user_id ON schedule_fire
-FOR EACH ROW
-WHEN (
-    NEW.schedule_id IS NOT OLD.schedule_id
-    OR NEW.home_id IS NOT OLD.home_id
-    OR NEW.tenant_id IS NOT OLD.tenant_id
-    OR NEW.user_id IS NOT OLD.user_id
-  )
-  AND EXISTS (
-    SELECT 1 FROM trigger_audit WHERE source = 'cron' AND source_ref = OLD.fire_id
-  )
-BEGIN
-  SELECT RAISE(ABORT, 'schedule_fire identity update blocked: dependent trigger_audit rows exist');
-END;
-`);
-}
-/** v9 — the single global auto-upgrade target (design.md §2/§9). ONE row,
- *  `channel = 'home'`, holding the DESIRED crtr image line every home rolls
- *  onto: `target_template_version` is the semver the fleet should be running,
- *  `target_image_ref` its immutable Blaxel image name (must equal
- *  `hearthHomeImageRefForVersion(target_template_version)` — the admin route
- *  enforces that). `last_bad_target_version` is the ONLY brake in the
- *  zero-touch loop: a version recorded here already failed a live roll for
- *  the fleet, so the wake-path stale predicate excludes it until the target
- *  advances to a newer release. There is deliberately NO `roll_armed` column
- *  — the loop is full zero-touch (§9.1), so there is no per-release human arm
- *  gate to persist. `home.template_version` stays the ACTUAL running version;
- *  this row is the target. Single-tenant: one image line for all homes, so no
- *  per-home target column. */
-function hearthTargetTable(db) {
-    db.exec(`
-CREATE TABLE IF NOT EXISTS hearth_target (
-  channel                  TEXT PRIMARY KEY DEFAULT 'home',
-  target_template_version  TEXT NOT NULL,
-  target_image_ref         TEXT NOT NULL,
-  published_at             TEXT NOT NULL,
-  source                   TEXT NOT NULL,
-  last_bad_target_version  TEXT,
-  CHECK (channel = 'home')
-);
-`);
-}
-/** The ordered migration list. Index `i` is migration version `i + 1`; the
- *  db's `user_version` tracks how many have been applied. Append only. */
-export const MIGRATIONS = [
-    /* v1 */ homeTable,
-    /* v2 */ scheduleTable,
-    /* v3 */ scheduleFireTable,
-    /* v4 */ ingressRouteTable,
-    /* v5 */ webhookDeliveryTable,
-    /* v6 */ triggerAuditTable,
-    /* v7 */ tenantIdentityTriggers,
-    /* v8 */ parentIdentityUpdateGuards,
-    /* v9 */ hearthTargetTable,
-];
-/** Bring `db` up to the latest schema version. Reads `user_version`, runs
- *  each pending migration in order, and bumps `user_version` after each so
- *  the work is gated and idempotent: re-running is a no-op once
- *  `user_version` reaches `MIGRATIONS.length`. Forward-only. */
-export function migrate(db) {
-    let v = db.prepare('PRAGMA user_version').get().user_version;
-    for (; v < MIGRATIONS.length; v++) {
-        MIGRATIONS[v](db);
-        // `user_version` takes no bound parameters; v is a controlled integer.
-        db.exec(`PRAGMA user_version = ${v + 1}`);
-    }
-}
-const handles = new Map();
-/** Open (or reuse) the CP db at `path`, initializing WAL + schema on first
- *  open. This is the SOLE function in the codebase that may construct a
- *  `DatabaseSync` against the CP db file — every CP store goes through this
- *  (directly or via `getControlPlaneDb()`) and never opens its own
- *  connection. Keyed by path so tests with distinct temp dbs get independent
- *  handles, exactly like `src/core/canvas/db.ts`'s `openDb()`. */
-export function openControlPlaneDb(path) {
-    const existing = handles.get(path);
-    if (existing) {
-        try {
-            existing.prepare('PRAGMA database_list').all();
-            return existing;
-        }
-        catch {
-            try {
-                existing.close();
-            }
-            catch {
-                /* ignore */
-            }
-            handles.delete(path);
-        }
-    }
-    const dir = dirname(path);
-    if (!existsSync(dir))
-        mkdirSync(dir, { recursive: true });
-    const db = new DatabaseSync(path);
-    db.exec('PRAGMA journal_mode = WAL;');
-    db.exec('PRAGMA foreign_keys = ON;');
-    db.exec('PRAGMA busy_timeout = 5000;');
-    migrate(db);
-    handles.set(path, db);
-    return db;
-}
-/** The cached handle accessor every CP store (registry, scheduler, ingress)
- *  imports — resolves the db path the standard way and opens/reuses the one
- *  connection for it. Never construct a second `DatabaseSync` against the CP
- *  db elsewhere in the codebase. */
-export function getControlPlaneDb(env = process.env) {
-    return openControlPlaneDb(controlPlaneDbPath(env));
-}
-/** Close and forget the handle for `path` (defaults to the standard
- *  resolved path). Mainly for tests. */
-export function closeControlPlaneDb(path = controlPlaneDbPath()) {
-    const db = handles.get(path);
-    if (db) {
-        db.close();
-        handles.delete(path);
-    }
-}

package/dist/hearth/control-plane/hearth-target.d.ts

@@ -1,23 +0,0 @@
-import { DatabaseSync } from 'node:sqlite';
-import type { HearthTarget, SetHearthTargetInput } from './types.js';
-/** Read the single global target row, or `null` when no image has ever been
- *  registered (fresh CP). A `null` means the wake path treats every home as
- *  up to date (nothing to roll onto yet). */
-export declare function getHearthTarget(db?: DatabaseSync): HearthTarget | null;
-/** Upsert the global target to a newly-registered image. IDEMPOTENT: a
- *  re-post of the version already recorded is a no-op (the row, including its
- *  `published_at` and any `last_bad_target_version` brake, is left exactly as
- *  is) — the image workflow can fire the notify more than once for one
- *  release without churning state. Advancing to a DIFFERENT version rewrites
- *  the target/image/published_at/source but deliberately preserves
- *  `last_bad_target_version` (a brake recorded for an older release is
- *  historical and harmless once the target has moved past it; the wake
- *  predicate keys off `target !== last_bad`). */
-export declare function setHearthTarget(input: SetHearthTargetInput, db?: DatabaseSync): HearthTarget;
-/** Record a version whose live roll failed for the fleet (§5.4). After this,
- *  the wake-path stale predicate excludes the current target (target ===
- *  last_bad_target_version → no home rolls) until a NEW release advances the
- *  target past it. This is the ONLY brake in the zero-touch loop (roadmap
- *  decision 1: never auto-advance onto a release that already failed a roll).
- *  Returns `null` if no target row exists (nothing to brake). */
-export declare function recordBadTarget(badVersion: string, db?: DatabaseSync): HearthTarget | null;

package/dist/hearth/control-plane/hearth-target.js

@@ -1,68 +0,0 @@
-// control-plane/hearth-target.ts — the CP store for the single global
-// auto-upgrade target row (`hearth_target`, db.ts v9). One row, `channel =
-// 'home'`. This module is the ONLY reader/writer of that row; the admin
-// notify route (server.ts) upserts it, the wake path (wake.ts) reads it to
-// decide whether a home is stale, and the rollback path records a bad target
-// through it. It goes through the shared CP db handle (`getControlPlaneDb`)
-// exactly like `registry.ts` — never a second connection.
-import { getControlPlaneDb } from './db.js';
-const TARGET_COLUMNS = [
-    'channel',
-    'target_template_version',
-    'target_image_ref',
-    'published_at',
-    'source',
-    'last_bad_target_version',
-];
-const SELECT_TARGET = `SELECT ${TARGET_COLUMNS.join(', ')} FROM hearth_target WHERE channel = 'home'`;
-function nowIso() {
-    return new Date().toISOString();
-}
-/** Read the single global target row, or `null` when no image has ever been
- *  registered (fresh CP). A `null` means the wake path treats every home as
- *  up to date (nothing to roll onto yet). */
-export function getHearthTarget(db = getControlPlaneDb()) {
-    const row = db.prepare(SELECT_TARGET).get();
-    if (row === undefined || row === null)
-        return null;
-    return row;
-}
-/** Upsert the global target to a newly-registered image. IDEMPOTENT: a
- *  re-post of the version already recorded is a no-op (the row, including its
- *  `published_at` and any `last_bad_target_version` brake, is left exactly as
- *  is) — the image workflow can fire the notify more than once for one
- *  release without churning state. Advancing to a DIFFERENT version rewrites
- *  the target/image/published_at/source but deliberately preserves
- *  `last_bad_target_version` (a brake recorded for an older release is
- *  historical and harmless once the target has moved past it; the wake
- *  predicate keys off `target !== last_bad`). */
-export function setHearthTarget(input, db = getControlPlaneDb()) {
-    const existing = getHearthTarget(db);
-    if (existing !== null && existing.target_template_version === input.target_template_version) {
-        return existing;
-    }
-    const published_at = input.published_at ?? nowIso();
-    db.prepare(`
-INSERT INTO hearth_target (channel, target_template_version, target_image_ref, published_at, source, last_bad_target_version)
-VALUES ('home', ?, ?, ?, ?, NULL)
-ON CONFLICT(channel) DO UPDATE SET
-  target_template_version = excluded.target_template_version,
-  target_image_ref = excluded.target_image_ref,
-  published_at = excluded.published_at,
-  source = excluded.source
-`).run(input.target_template_version, input.target_image_ref, published_at, input.source);
-    return getHearthTarget(db);
-}
-/** Record a version whose live roll failed for the fleet (§5.4). After this,
- *  the wake-path stale predicate excludes the current target (target ===
- *  last_bad_target_version → no home rolls) until a NEW release advances the
- *  target past it. This is the ONLY brake in the zero-touch loop (roadmap
- *  decision 1: never auto-advance onto a release that already failed a roll).
- *  Returns `null` if no target row exists (nothing to brake). */
-export function recordBadTarget(badVersion, db = getControlPlaneDb()) {
-    const existing = getHearthTarget(db);
-    if (existing === null)
-        return null;
-    db.prepare(`UPDATE hearth_target SET last_bad_target_version = ? WHERE channel = 'home'`).run(badVersion);
-    return getHearthTarget(db);
-}