comisai 1.0.42 → 1.0.44

package/node_modules/@comis/memory/dist/schema-mental-models.js

@@ -0,0 +1,258 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * The `mental_models` table DDL — the v2.31 Mental Model doc store (generalized
+ * from the v2.26 Verified Learning WS2 / SKILL-01 `learned_skills` procedural
+ * store). Each row is one advisory doc of `kind ∈ {skill, profile, topic}`
+ * (markdown `body`) distilled from successful trajectories; candidates are
+ * admitted here at `trust=learned`, `state=candidate`, and a proof count drives
+ * promote/demote/evict. A `kind='skill'` row materializes byte-identically to the
+ * pre-generalization learned-skill surface (the no-behavior-change guarantee).
+ *
+ * Forward-only, re-run-safe: `CREATE TABLE IF NOT EXISTS` + `CREATE INDEX IF NOT
+ * EXISTS` + `CREATE … VIRTUAL TABLE IF NOT EXISTS` only — no reverse DDL, no
+ * branch on an old shape (design §9, additive) — PLUS a one-time copy-forward
+ * REBUILD from a pre-existing `learned_skills` table (below). Extracted from
+ * `schema.ts` (which is at the 800-line cap), like `schema-outcome-events.ts` /
+ * `schema-video-jobs.ts` — `initSchema` CALLS this so the table exists on every
+ * boot.
+ *
+ * ## The advisory-doc-only shape (no learned code)
+ *
+ * The generalized table DROPS the executable `scripts` column entirely (it was
+ * always the literal NULL in the store's `insertStmt` — a true no-op to drop). A
+ * mental-model doc is READ by the agent, which acts through its already-
+ * permissioned tools; there is no learned-code path. The `required_tools` /
+ * `params_schema` / `mutating` advisory-metadata columns are KEPT (the surface
+ * filter reads `mutating`). The dead `trigger` column is dropped too (zero
+ * readers). The new `structured_body` / `history` JSON columns are provisioned
+ * NULL this phase (Phase 223 populates `structured_body` via typed delta-ops).
+ *
+ * ## SEC-01 trust ceiling (T-201-05) — the keystone
+ *
+ * `trust_level TEXT NOT NULL CHECK (trust_level IN ('learned')) DEFAULT 'learned'`
+ * makes a learned doc STRUCTURALLY incapable of being `system`: the DB REJECTS
+ * any other value at insert time. The store ALSO coerces `trust_level` to
+ * `'learned'` in code (belt-and-suspenders) — a candidate claiming `trust:'system'`
+ * is rejected by the DB AND never even reaches the column.
+ *
+ * ## SEC-01 isolation (T-201-06) — the multi-tenant boundary
+ *
+ * `(tenant_id, agent_id)` are bare `NOT NULL` columns and lead every key/index;
+ * the store filters EVERY statement on them, so a doc under one (tenant, agent)
+ * is never visible to a read under another in the multi-agent DB.
+ * `UNIQUE (tenant_id, agent_id, kind, topic_key, name)` is the lookup key + the
+ * idempotency backstop (the store derives the row id as a deterministic hash of
+ * that tuple).
+ *
+ * ## FTS5 / vec0 / trigram twins
+ *
+ * `mental_models_fts` (external-content FTS5 over `body`, the word lane) mirrors
+ * `memory_fts`; `vec_mental_models` (sqlite-vec, sized from the runtime-probed
+ * embedding dimension) mirrors `vec_memories`; `mental_models_fts_tri` (a
+ * self-contained trigram twin) mirrors `memory_fts_tri` for non-Latin recall.
+ * Each twin is best-effort (wrapped so a host whose better-sqlite3 lacks the FTS5
+ * or trigram tokenizer still boots — the base table is created unconditionally).
+ *
+ * `better-sqlite3` durability is WAL + path-based chmod (never fd-based file
+ * sync), so this DDL is permission-model-safe by construction — no fd-fs guard is
+ * needed ([[node-permission-model-disables-fsync]]).
+ *
+ * @module
+ */
+/**
+ * Create the `mental_models` table + its scope index + the FTS5/vec0/trigram
+ * twins idempotently, and (one-time) copy any pre-existing `learned_skills` rows
+ * forward as `kind='skill'`.
+ *
+ * Safe to call multiple times (all DDL uses IF NOT EXISTS; the copy-forward only
+ * fires while a `learned_skills` table still exists). Called from `initSchema`
+ * right after `ensureOutcomeEventsTable` so the table exists on every daemon
+ * boot. The `CHECK` constraints pin the `trust_level` (the SEC-01 keystone),
+ * `kind`, and `state` closed enums; the `UNIQUE (…)` is the lookup key +
+ * idempotency backstop; the index serves the scoped `list()` read.
+ *
+ * @param db - An open better-sqlite3 Database instance.
+ * @param embeddingDimensions - Vector dimension for `vec_mental_models` (runtime-probed; same value as `vec_memories`).
+ * @param vecAvailable - Whether sqlite-vec loaded (the vec twin is skipped when false, mirroring `vec_memories`).
+ */
+export function ensureMentalModelsTable(db, embeddingDimensions, vecAvailable) {
+    // --- Base table + scope index (forward-only, additive) ---
+    // The generalized doc shape: kind/topic_key/structured_body/history added; the
+    // executable `scripts` column and the dead `trigger` column dropped.
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS mental_models (
+      id               TEXT PRIMARY KEY,
+      tenant_id        TEXT NOT NULL,
+      agent_id         TEXT NOT NULL,
+      kind             TEXT NOT NULL CHECK (kind IN ('skill','profile','topic')) DEFAULT 'skill',
+      topic_key        TEXT NOT NULL DEFAULT '',
+      name             TEXT NOT NULL,
+      description      TEXT NOT NULL DEFAULT '',
+      body             TEXT NOT NULL,
+      structured_body  TEXT,
+      history          TEXT,
+      required_tools   TEXT,
+      params_schema    TEXT,
+      trust_level      TEXT NOT NULL CHECK (trust_level IN ('learned')) DEFAULT 'learned',
+      state            TEXT NOT NULL CHECK (state IN ('candidate','active','stale','archived')) DEFAULT 'candidate',
+      proof_count      INTEGER NOT NULL DEFAULT 0,
+      confidence       REAL NOT NULL DEFAULT 0,
+      strength         REAL NOT NULL DEFAULT 0,
+      source_traj_ids  TEXT,
+      validation_result TEXT,
+      mutating         INTEGER NOT NULL DEFAULT 0,
+      pinned           INTEGER NOT NULL DEFAULT 0,
+      validated_at     INTEGER,
+      created_at       INTEGER NOT NULL,
+      updated_at       INTEGER,
+      evicted_at       INTEGER,
+      UNIQUE (tenant_id, agent_id, kind, topic_key, name)
+    );
+    CREATE INDEX IF NOT EXISTS mental_models_scope ON mental_models(tenant_id, agent_id, kind, state);
+  `);
+    // --- One-time copy-forward REBUILD from a pre-existing `learned_skills` table ---
+    // A FRESH DB skips this (the generalized table above is the only one). A dev/test
+    // DB that admitted under the pre-generalization name copies every row forward as
+    // kind='skill' and DROPS the old table + its orphaned twins/triggers. (The prod
+    // table is empty — synthesis never admitted — so this is the dev/test path.)
+    //
+    // Mirrors the `ensureTunedAlphaIntent` REBUILD shape (detect → fk-toggle → txn →
+    // copy → drop), but detects the OLD TABLE BY NAME (a different table name, not a
+    // column add). This is a forward-only REBUILD / copy-forward (the
+    // `ensureTunedAlphaIntent` vocabulary) — there is no compatibility shim, alias,
+    // or dual-read path: the old table is copied once and dropped in the same txn.
+    //
+    // The copied `id` is the OLD (tenant, agent, name) hash verbatim — SQLite has no
+    // sha256 builtin to recompute the widened (tenant, agent, kind, topic_key, name)
+    // hash inside INSERT…SELECT. A later re-admit of the same skill recomputes the
+    // widened id and upserts; the row-resurrection path (ON CONFLICT … state=
+    // 'candidate', evicted_at=NULL) tolerates the transient. Acceptable because prod
+    // is empty (dev/test-only).
+    const oldExists = db
+        .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='learned_skills'")
+        .get();
+    if (oldExists !== undefined) {
+        const fkWasOn = db.pragma("foreign_keys", { simple: true }) === 1;
+        if (fkWasOn)
+            db.pragma("foreign_keys = OFF"); // pragma OUTSIDE the txn (no-op INSIDE a txn)
+        const copyForward = db.transaction(() => {
+            db.exec(`
+        INSERT OR IGNORE INTO mental_models
+          (id, tenant_id, agent_id, kind, topic_key, name, description, body,
+           required_tools, params_schema, trust_level, state, proof_count, confidence,
+           strength, source_traj_ids, validation_result, mutating, pinned, validated_at,
+           created_at, updated_at, evicted_at)
+          SELECT id, tenant_id, agent_id, 'skill', '', name, description, body,
+                 required_tools, params_schema, 'learned', state, proof_count, confidence,
+                 strength, source_traj_ids, validation_result, mutating, pinned, validated_at,
+                 created_at, updated_at, evicted_at
+          FROM learned_skills;
+        DROP TABLE learned_skills;
+        DROP TABLE IF EXISTS learned_skills_fts;
+        DROP TABLE IF EXISTS learned_skills_fts_tri;
+        DROP TABLE IF EXISTS vec_learned_skills;
+        DROP TRIGGER IF EXISTS learned_skills_ai;
+        DROP TRIGGER IF EXISTS learned_skills_ad;
+        DROP TRIGGER IF EXISTS learned_skills_au;
+        DROP TRIGGER IF EXISTS learned_skills_tri_ad;
+        DROP TRIGGER IF EXISTS learned_skills_tri_au;
+      `);
+        });
+        copyForward();
+        if (fkWasOn)
+            db.pragma("foreign_keys = ON");
+    }
+    // --- Vector search twin (sqlite-vec) — sized from the runtime-probed dim ---
+    // Mirrors `vec_memories` (schema.ts:502-507): skipped wholesale when sqlite-vec
+    // is unavailable (FTS5 still works). Best-effort so a partial-extension host
+    // still boots the base table.
+    if (vecAvailable) {
+        try {
+            db.exec(`
+        CREATE VIRTUAL TABLE IF NOT EXISTS vec_mental_models USING vec0(
+          skill_id TEXT PRIMARY KEY,
+          embedding float[${embeddingDimensions}] distance_metric=cosine
+        );
+      `);
+        }
+        catch {
+            // sqlite-vec present at load but vec0 CREATE failed on this host — degrade
+            // to FTS-only (the base table is already created above).
+        }
+    }
+    // --- FTS5 word-lane twin (external content over `body`) ---
+    // Mirrors `memory_fts` (schema.ts:510-545): external-content config + the
+    // _ai/_ad/_au sync triggers; the `rebuild` is wrapped (safe-no-op on an empty
+    // table). Best-effort so a host without the FTS5 module still boots.
+    //
+    // The FTS column is named `body` to MATCH the real source column on
+    // `mental_models` (the body lives in `body`, there is NO `content` column).
+    // `memory_fts` names its column `content` because `memories.content` exists;
+    // for external-content FTS5, the indexed column name MUST equal the source
+    // column so the `'rebuild'` command (which re-reads the external content table)
+    // can find it — naming it `content` here threw "no such column: content" on
+    // every boot, silently leaving the index reliant on incremental triggers and
+    // never re-derivable after an unclean shutdown (WR-04).
+    try {
+        db.exec(`
+      CREATE VIRTUAL TABLE IF NOT EXISTS mental_models_fts USING fts5(
+        body,
+        content='mental_models',
+        content_rowid='rowid',
+        tokenize='porter unicode61'
+      );
+    `);
+        try {
+            db.exec(`INSERT INTO mental_models_fts(mental_models_fts) VALUES('rebuild')`);
+        }
+        catch {
+            // Rebuild may fail on a freshly-created empty table — safe to ignore.
+        }
+        db.exec(`
+      CREATE TRIGGER IF NOT EXISTS mental_models_ai AFTER INSERT ON mental_models BEGIN
+        INSERT INTO mental_models_fts(rowid, body) VALUES (new.rowid, new.body);
+      END;
+
+      CREATE TRIGGER IF NOT EXISTS mental_models_ad AFTER DELETE ON mental_models BEGIN
+        INSERT INTO mental_models_fts(mental_models_fts, rowid, body) VALUES('delete', old.rowid, old.body);
+      END;
+
+      CREATE TRIGGER IF NOT EXISTS mental_models_au AFTER UPDATE OF body ON mental_models BEGIN
+        INSERT INTO mental_models_fts(mental_models_fts, rowid, body) VALUES('delete', old.rowid, old.body);
+        INSERT INTO mental_models_fts(rowid, body) VALUES (new.rowid, new.body);
+      END;
+    `);
+    }
+    catch {
+        // FTS5 tokenizer not compiled into this host's better-sqlite3 → boot WITHOUT
+        // the word-lane twin (search probes availability and degrades). The triggers
+        // live in the SAME try so a failed FTS CREATE can never orphan a trigger that
+        // would break a base-table INSERT/DELETE.
+    }
+    // --- Trigram twin (self-contained, non-Latin lane) ---
+    // Mirrors `memory_fts_tri` (schema-trigram.ts:136): self-contained (stores its
+    // OWN content — no external `rebuild` that would undo normalization) + a
+    // delete-mirror + a WHEN-guarded body-update trigger. Best-effort: a host
+    // without the trigram tokenizer boots without it.
+    try {
+        db.exec(`
+      CREATE VIRTUAL TABLE IF NOT EXISTS mental_models_fts_tri USING fts5(
+        content,
+        tokenize='trigram'
+      );
+      CREATE TRIGGER IF NOT EXISTS mental_models_tri_ad AFTER DELETE ON mental_models BEGIN
+        DELETE FROM mental_models_fts_tri WHERE rowid = old.rowid;
+      END;
+      CREATE TRIGGER IF NOT EXISTS mental_models_tri_au AFTER UPDATE OF body ON mental_models
+        WHEN old.body IS NOT new.body BEGIN
+        DELETE FROM mental_models_fts_tri WHERE rowid = old.rowid;
+      END;
+    `);
+    }
+    catch {
+        // trigram tokenizer not compiled into this host's better-sqlite3 → boot
+        // WITHOUT the trigram twin (search probes availability and degrades). The
+        // triggers live in the SAME try so a failed CREATE can never orphan a trigger
+        // that would break a base-table DELETE.
+    }
+}

package/node_modules/@comis/memory/dist/schema-obs-token.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Observability-table migrations split out of `schema.ts` (which sits at the
+ * 800-line cap) — the `schema-tuned-alpha.ts` / `schema-outcome-events.ts`
+ * co-location precedent. `initSchema` CALLS these so they run on every boot,
+ * AFTER the base `obs_token_usage` CREATE.
+ *
+ * Two PERSIST-02 / AUDIT-01 migrations:
+ *  - `ensureObsTokenColumns` — the forward-only `obs_token_usage` cost-correctness
+ *    column upgrade + the dead `cache_retention` DROP.
+ *  - `ensureObsAuditTable` — the dedicated `obs_audit_events` table + indexes.
+ *
+ * @module
+ */
+import type Database from "better-sqlite3";
+/**
+ * Forward-only upgrade of `obs_token_usage` for the cost-correctness work
+ * (PERSIST-02 / observability-excellence WS5). Two parts, both idempotent:
+ *
+ * 1. DROP the dead `cache_retention` column (OQ3 ruling = DROP — no event field
+ *    ever populated it; the `retention_changed` cache-break reason is a DIFFERENT
+ *    table). SQLite has no `DROP COLUMN`, so when the column is still present we run
+ *    the standard transactional table-REBUILD (the `memory_usefulness` precedent in
+ *    schema.ts): CREATE a `_new` table without it, `INSERT … SELECT` every other
+ *    column VERBATIM (existing rows survive intact), DROP, RENAME, recreate the 4
+ *    indexes. `obs_token_usage` has NO foreign key, so — unlike the
+ *    `memory_usefulness` rebuild — no `foreign_keys` pragma bracketing is needed.
+ *    Guarded by a presence check, so it is a no-op on an already-migrated DB.
+ *
+ * 2. ADD the 6 new columns via the `ensureMemoryColumns` guarded-ALTER idiom
+ *    (`warmup_turn`/`cache_eligible` as INTEGER 0/1 flags, `cost_correction`/
+ *    `pending_cache_investment_usd` as REAL, `pricing_state` as TEXT, and the
+ *    COST-01 `tool_tag` as TEXT — the JSON distinct-tool array). All nullable
+ *    → O(1), no rewrite, no backfill (existing rows get NULL).
+ *
+ * Net post-condition (fresh OR existing DB): the 6 columns present, `cache_retention`
+ * absent. Called AFTER the `obs_token_usage` CREATE in `initSchema`.
+ *
+ * @param db - An open better-sqlite3 Database whose `obs_token_usage` table exists.
+ */
+export declare function ensureObsTokenColumns(db: Database.Database): void;
+/**
+ * Create the dedicated `obs_audit_events` security-audit table + its two indexes
+ * (AUDIT-01/02). A DEDICATED table (not `obs_diagnostics`) per the §14 ruling —
+ * distinct retention + actor/outcome/severity attribution columns + a regulatory
+ * grep surface. The sink (Plan 03) resolves `tenant_id` from the trace context else
+ * persists the `''` system-scope sentinel (`tenant_id` is NOT NULL); `agent_id`
+ * stays NULL when absent. `refs` is a scrubbed JSON blob. This plan (176-01) owns
+ * the DDL + the `AuditEventRow` type; the insert/query methods + JSONL writer land
+ * in Plan 03. Idempotent (`CREATE … IF NOT EXISTS`).
+ *
+ * @param db - An open better-sqlite3 Database.
+ */
+export declare function ensureObsAuditTable(db: Database.Database): void;

package/node_modules/@comis/memory/dist/schema-obs-token.js

@@ -0,0 +1,142 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Observability-table migrations split out of `schema.ts` (which sits at the
+ * 800-line cap) — the `schema-tuned-alpha.ts` / `schema-outcome-events.ts`
+ * co-location precedent. `initSchema` CALLS these so they run on every boot,
+ * AFTER the base `obs_token_usage` CREATE.
+ *
+ * Two PERSIST-02 / AUDIT-01 migrations:
+ *  - `ensureObsTokenColumns` — the forward-only `obs_token_usage` cost-correctness
+ *    column upgrade + the dead `cache_retention` DROP.
+ *  - `ensureObsAuditTable` — the dedicated `obs_audit_events` table + indexes.
+ *
+ * @module
+ */
+/**
+ * Forward-only upgrade of `obs_token_usage` for the cost-correctness work
+ * (PERSIST-02 / observability-excellence WS5). Two parts, both idempotent:
+ *
+ * 1. DROP the dead `cache_retention` column (OQ3 ruling = DROP — no event field
+ *    ever populated it; the `retention_changed` cache-break reason is a DIFFERENT
+ *    table). SQLite has no `DROP COLUMN`, so when the column is still present we run
+ *    the standard transactional table-REBUILD (the `memory_usefulness` precedent in
+ *    schema.ts): CREATE a `_new` table without it, `INSERT … SELECT` every other
+ *    column VERBATIM (existing rows survive intact), DROP, RENAME, recreate the 4
+ *    indexes. `obs_token_usage` has NO foreign key, so — unlike the
+ *    `memory_usefulness` rebuild — no `foreign_keys` pragma bracketing is needed.
+ *    Guarded by a presence check, so it is a no-op on an already-migrated DB.
+ *
+ * 2. ADD the 6 new columns via the `ensureMemoryColumns` guarded-ALTER idiom
+ *    (`warmup_turn`/`cache_eligible` as INTEGER 0/1 flags, `cost_correction`/
+ *    `pending_cache_investment_usd` as REAL, `pricing_state` as TEXT, and the
+ *    COST-01 `tool_tag` as TEXT — the JSON distinct-tool array). All nullable
+ *    → O(1), no rewrite, no backfill (existing rows get NULL).
+ *
+ * Net post-condition (fresh OR existing DB): the 6 columns present, `cache_retention`
+ * absent. Called AFTER the `obs_token_usage` CREATE in `initSchema`.
+ *
+ * @param db - An open better-sqlite3 Database whose `obs_token_usage` table exists.
+ */
+export function ensureObsTokenColumns(db) {
+    // Object-literal cast — the sanctioned PRAGMA idiom (not `as Foo[]`).
+    const cols = new Set(db.prepare(`PRAGMA table_info(obs_token_usage)`).all().map((r) => r.name));
+    // Part 1 — DROP the dead cache_retention column (rebuild; guarded so re-run-safe).
+    if (cols.has("cache_retention")) {
+        const rebuild = db.transaction(() => {
+            db.exec(`
+        CREATE TABLE obs_token_usage_new (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          timestamp INTEGER NOT NULL,
+          trace_id TEXT NOT NULL,
+          agent_id TEXT NOT NULL,
+          channel_id TEXT DEFAULT '',
+          session_key TEXT DEFAULT '',
+          provider TEXT NOT NULL,
+          model TEXT NOT NULL,
+          prompt_tokens INTEGER NOT NULL,
+          completion_tokens INTEGER NOT NULL,
+          total_tokens INTEGER NOT NULL,
+          cache_read_tokens INTEGER DEFAULT 0,
+          cache_write_tokens INTEGER DEFAULT 0,
+          cost_input REAL NOT NULL,
+          cost_output REAL NOT NULL,
+          cost_total REAL NOT NULL,
+          cost_cache_read REAL NOT NULL DEFAULT 0,
+          cost_cache_write REAL NOT NULL DEFAULT 0,
+          cache_saved REAL NOT NULL DEFAULT 0,
+          latency_ms INTEGER NOT NULL
+        );
+        INSERT INTO obs_token_usage_new (
+          id, timestamp, trace_id, agent_id, channel_id, session_key,
+          provider, model, prompt_tokens, completion_tokens, total_tokens,
+          cache_read_tokens, cache_write_tokens, cost_input, cost_output, cost_total,
+          cost_cache_read, cost_cache_write, cache_saved, latency_ms
+        )
+        SELECT
+          id, timestamp, trace_id, agent_id, channel_id, session_key,
+          provider, model, prompt_tokens, completion_tokens, total_tokens,
+          cache_read_tokens, cache_write_tokens, cost_input, cost_output, cost_total,
+          cost_cache_read, cost_cache_write, cache_saved, latency_ms
+        FROM obs_token_usage;
+        DROP TABLE obs_token_usage;
+        ALTER TABLE obs_token_usage_new RENAME TO obs_token_usage;
+        CREATE INDEX IF NOT EXISTS idx_obs_token_timestamp ON obs_token_usage(timestamp);
+        CREATE INDEX IF NOT EXISTS idx_obs_token_agent ON obs_token_usage(agent_id, timestamp);
+        CREATE INDEX IF NOT EXISTS idx_obs_token_provider ON obs_token_usage(provider, timestamp);
+        CREATE INDEX IF NOT EXISTS idx_obs_token_session ON obs_token_usage(session_key, timestamp);
+      `);
+        });
+        rebuild();
+    }
+    // Part 2 — ADD the 5 cost-correctness columns (guarded, nullable → O(1) ADD).
+    // Re-probe after the rebuild (the rebuilt table has none of them yet).
+    const cols2 = new Set(db.prepare(`PRAGMA table_info(obs_token_usage)`).all().map((r) => r.name));
+    if (!cols2.has("warmup_turn"))
+        db.exec(`ALTER TABLE obs_token_usage ADD COLUMN warmup_turn INTEGER`);
+    if (!cols2.has("cache_eligible"))
+        db.exec(`ALTER TABLE obs_token_usage ADD COLUMN cache_eligible INTEGER`);
+    if (!cols2.has("cost_correction"))
+        db.exec(`ALTER TABLE obs_token_usage ADD COLUMN cost_correction REAL`);
+    if (!cols2.has("pending_cache_investment_usd"))
+        db.exec(`ALTER TABLE obs_token_usage ADD COLUMN pending_cache_investment_usd REAL`);
+    if (!cols2.has("pricing_state"))
+        db.exec(`ALTER TABLE obs_token_usage ADD COLUMN pricing_state TEXT`);
+    // COST-01 (Phase 179): the per-turn tool tag — the IDENTICAL 6th additive,
+    // forward-only, nullable ALTER (no migration framework, no dual-read shim).
+    // Stores the JSON-stringified DISTINCT tool array (content-free names only);
+    // NULL on existing rows (they survive verbatim) and on no-tool turns.
+    if (!cols2.has("tool_tag"))
+        db.exec(`ALTER TABLE obs_token_usage ADD COLUMN tool_tag TEXT`);
+}
+/**
+ * Create the dedicated `obs_audit_events` security-audit table + its two indexes
+ * (AUDIT-01/02). A DEDICATED table (not `obs_diagnostics`) per the §14 ruling —
+ * distinct retention + actor/outcome/severity attribution columns + a regulatory
+ * grep surface. The sink (Plan 03) resolves `tenant_id` from the trace context else
+ * persists the `''` system-scope sentinel (`tenant_id` is NOT NULL); `agent_id`
+ * stays NULL when absent. `refs` is a scrubbed JSON blob. This plan (176-01) owns
+ * the DDL + the `AuditEventRow` type; the insert/query methods + JSONL writer land
+ * in Plan 03. Idempotent (`CREATE … IF NOT EXISTS`).
+ *
+ * @param db - An open better-sqlite3 Database.
+ */
+export function ensureObsAuditTable(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS obs_audit_events (
+      id TEXT PRIMARY KEY,
+      tenant_id TEXT NOT NULL,
+      agent_id TEXT,
+      ts INTEGER NOT NULL,
+      kind TEXT NOT NULL,
+      classification TEXT,
+      action TEXT,
+      actor TEXT,
+      outcome TEXT,
+      severity TEXT,
+      trace_id TEXT,
+      refs TEXT
+    );
+    CREATE INDEX IF NOT EXISTS obs_audit_scope ON obs_audit_events(tenant_id, agent_id, ts);
+    CREATE INDEX IF NOT EXISTS obs_audit_kind  ON obs_audit_events(kind, ts);
+  `);
+}

package/node_modules/@comis/memory/dist/schema-outcome-events.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The `outcome_events` ledger DDL — the v2.26 Verified Learning (WS1) durable
+ * record of a finished trajectory's net task-outcome (OUTCOME-01). Every row is
+ * one raw observation from one signal source (tool / pipeline / correction /
+ * judge / reaction / explicit); `resolve()` fuses all rows for a trajectory into
+ * one verdict (precedence-first then confidence).
+ *
+ * Forward-only, re-run-safe: `CREATE TABLE IF NOT EXISTS` + `CREATE INDEX IF NOT
+ * EXISTS` only — no destructive or reverse DDL, no branch on an old shape (design
+ * §9, additive). Extracted from `schema.ts` (which is at the 800-line cap), like
+ * `schema-video-jobs.ts` — `initSchema` CALLS this so the table exists on every
+ * boot.
+ *
+ * IDEMPOTENCY: the `id` is a deterministic sha256 hash of the UNIQUE tuple
+ * `(tenant_id, agent_id, trajectory_id, source, observed_at)` computed in the
+ * store before insert, AND the table carries a `UNIQUE (…)` backstop on that
+ * tuple — a replayed observation is a no-op at BOTH layers (the store inserts
+ * `ON CONFLICT … DO NOTHING`; OUTCOME-01 / T-198-09).
+ *
+ * SECURITY (SEC-01 / T-198-05): `(tenant_id, agent_id)` are bare `NOT NULL`
+ * columns and lead every key/index — the store filters EVERY statement on them,
+ * so a row under one (tenant, agent) is never visible to a read under another in
+ * the multi-agent DB. No trust column exists (T-198-10): `confidence` /
+ * `sender_trust` are descriptive, never authorization. No message bodies are
+ * stored — ids + closed enums + confidence only (content-free, §V12).
+ *
+ * `better-sqlite3` durability is WAL + path-based chmod (never fd-based file
+ * sync), so this DDL is permission-model-safe by construction — no fd-fs guard is
+ * needed ([[node-permission-model-disables-fsync]]).
+ *
+ * @module
+ */
+import type Database from "better-sqlite3";
+/**
+ * Create the `outcome_events` table + its scope index idempotently.
+ *
+ * Safe to call multiple times (all DDL uses IF NOT EXISTS). Called from
+ * `initSchema` so the table exists on every daemon boot. The `CHECK` constraints
+ * pin the `outcome` / `source` closed enums; the `UNIQUE (…)` is the idempotency
+ * backstop; the index serves the scoped `resolve()` read.
+ *
+ * @param db - An open better-sqlite3 Database instance
+ */
+export declare function ensureOutcomeEventsTable(db: Database.Database): void;

package/node_modules/@comis/memory/dist/schema-outcome-events.js

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * The `outcome_events` ledger DDL — the v2.26 Verified Learning (WS1) durable
+ * record of a finished trajectory's net task-outcome (OUTCOME-01). Every row is
+ * one raw observation from one signal source (tool / pipeline / correction /
+ * judge / reaction / explicit); `resolve()` fuses all rows for a trajectory into
+ * one verdict (precedence-first then confidence).
+ *
+ * Forward-only, re-run-safe: `CREATE TABLE IF NOT EXISTS` + `CREATE INDEX IF NOT
+ * EXISTS` only — no destructive or reverse DDL, no branch on an old shape (design
+ * §9, additive). Extracted from `schema.ts` (which is at the 800-line cap), like
+ * `schema-video-jobs.ts` — `initSchema` CALLS this so the table exists on every
+ * boot.
+ *
+ * IDEMPOTENCY: the `id` is a deterministic sha256 hash of the UNIQUE tuple
+ * `(tenant_id, agent_id, trajectory_id, source, observed_at)` computed in the
+ * store before insert, AND the table carries a `UNIQUE (…)` backstop on that
+ * tuple — a replayed observation is a no-op at BOTH layers (the store inserts
+ * `ON CONFLICT … DO NOTHING`; OUTCOME-01 / T-198-09).
+ *
+ * SECURITY (SEC-01 / T-198-05): `(tenant_id, agent_id)` are bare `NOT NULL`
+ * columns and lead every key/index — the store filters EVERY statement on them,
+ * so a row under one (tenant, agent) is never visible to a read under another in
+ * the multi-agent DB. No trust column exists (T-198-10): `confidence` /
+ * `sender_trust` are descriptive, never authorization. No message bodies are
+ * stored — ids + closed enums + confidence only (content-free, §V12).
+ *
+ * `better-sqlite3` durability is WAL + path-based chmod (never fd-based file
+ * sync), so this DDL is permission-model-safe by construction — no fd-fs guard is
+ * needed ([[node-permission-model-disables-fsync]]).
+ *
+ * @module
+ */
+/**
+ * Create the `outcome_events` table + its scope index idempotently.
+ *
+ * Safe to call multiple times (all DDL uses IF NOT EXISTS). Called from
+ * `initSchema` so the table exists on every daemon boot. The `CHECK` constraints
+ * pin the `outcome` / `source` closed enums; the `UNIQUE (…)` is the idempotency
+ * backstop; the index serves the scoped `resolve()` read.
+ *
+ * @param db - An open better-sqlite3 Database instance
+ */
+export function ensureOutcomeEventsTable(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS outcome_events (
+      id              TEXT PRIMARY KEY,
+      tenant_id       TEXT NOT NULL,
+      agent_id        TEXT NOT NULL,
+      session_id      TEXT NOT NULL,
+      trajectory_id   TEXT NOT NULL,
+      outcome         TEXT NOT NULL CHECK (outcome IN ('success','failure','corrected','unknown')),
+      source          TEXT NOT NULL CHECK (source IN ('tool','pipeline','correction','judge','reaction','explicit')),
+      confidence      REAL NOT NULL DEFAULT 0.5,
+      sender_trust    TEXT,
+      recalled_ids    TEXT,
+      used_skill_ids  TEXT,
+      observed_at     INTEGER NOT NULL,
+      UNIQUE (tenant_id, agent_id, trajectory_id, source, observed_at)
+    );
+    CREATE INDEX IF NOT EXISTS outcome_events_scope ON outcome_events(tenant_id, agent_id, trajectory_id);
+  `);
+}

package/node_modules/@comis/memory/dist/schema-outward-ledger.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The `outward_send_ledger` table DDL — the three-state exactly-once outward-send
+ * ledger the Phase-216 resume engine reconciles on boot (ONCE-01/ONCE-02/ONCE-03).
+ * A send-intent is persisted HERE, on disk in the shared `memory.db`, BEFORE the
+ * irreversible chat-platform call, so a daemon CRASH mid-send leaves a durable,
+ * reconcilable trace rather than a lost message OR a blind replay (a second
+ * 10,000-user DM blast on restart).
+ *
+ * Forward-only, re-run-safe: create-if-not-exists only, no destructive or reverse
+ * DDL (design §9). Extracted from `schema.ts` (which is at the 800-line cap) —
+ * `initSchema` CALLS this so the table exists on every boot (Pitfall 5: a table
+ * defined here but not wired into initSchema is MISSING at runtime).
+ *
+ * THE IDEMPOTENCY KEY (ONCE-02, T-216-10): the UNIQUE index
+ * `idx_osl_idempotency` on `(root_run_id, step_index)` is what makes the send
+ * exactly-once. The `step_index` half is allocated by the durable_runs
+ * `allocateOutwardStep` monotonic counter (HIGH-1), so a REPLAYED step collides
+ * on this index — a second `begin` is an err the wrap site (Plan 05) treats as
+ * "already in flight, do NOT double-send". This store has NO blind
+ * `in_flight → pending` bulk reset (the `delivery-queue-adapter.ts:141-145`
+ * anti-pattern §9 forbids, T-216-09): recovery is PER-ROW via the
+ * `listUnreconciled` scan → the engine asks the platform `reconcileSend?`
+ * (Plan 04), never a blanket UPDATE.
+ *
+ * SECURITY — CONTENT-FREE (T-216-11, mirrors video_jobs T-189-02 / durable_runs
+ * T-216-05): `content_digest` is a sha256 set by the caller and is the ONLY
+ * content trace. There is deliberately NO `body` / `text` / `message` column and
+ * NO secret / token / bearer / api_key column — the reconcile matches on the
+ * digest + a time window, NEVER the message text (§2.7 / §15). A recipient list
+ * is routing only (`channel_id`), never a stored secret.
+ *
+ * `better-sqlite3` durability is WAL + path-based chmod (never fd-based file
+ * sync), so this DDL is permission-model-safe by construction — no fd-fs guard
+ * is needed (mirrors video_jobs / durable_runs / [[node-permission-model-disables-fsync]]).
+ *
+ * @module
+ */
+import type Database from "better-sqlite3";
+/**
+ * Create the `outward_send_ledger` table + its UNIQUE idempotency index and the
+ * partial recovery-scan index idempotently.
+ *
+ * Safe to call multiple times (all DDL uses IF NOT EXISTS). Called from
+ * `initSchema` so the table exists on every daemon boot.
+ *
+ * @param db - An open better-sqlite3 Database instance
+ */
+export declare function ensureOutwardLedgerTable(db: Database.Database): void;