comisai 1.0.42 → 1.0.44

package/node_modules/@comis/memory/dist/types.d.ts

@@ -22,10 +22,35 @@ export interface MemoryRow {
     tags: string;
     /** Unix timestamp in milliseconds */
     created_at: number;
+    /** Unix timestamp in milliseconds, null if the event time is unknown. */
+    occurred_at: number | null;
+    /** Evidence count; null = raw memory, >=1 = observation. */
+    proof_count: number | null;
+    /** JSON-encoded string[] of contributing source ids; null on raw memories. */
+    source_ids: string | null;
+    /** Unix ms; set when folded into an observation. */
+    consolidated_at: number | null;
+    /** Observation confidence 0..1; null on raw memories. */
+    confidence: number | null;
+    /** JSON-encoded audit array of prior contents; null on raw memories. */
+    history: string | null;
+    /** Reasoning-observation kind TEXT; null = "merge". */
+    observation_kind: string | null;
+    /** Inductive pattern class TEXT; null unless observationKind="inductive". */
+    pattern_type: string | null;
+    /** Unix ms; non-destructive demote marker; null = not demoted (DORMANT). */
+    lifecycle_demoted_at: number | null;
+    /** Unix ms; non-destructive evict marker; null = not evicted (DORMANT). */
+    evicted_at: number | null;
+    /** Computed lifecycle strength 0..1; null = not yet computed. */
+    strength: number | null;
     /** Unix timestamp in milliseconds, null if never updated */
     updated_at: number | null;
     /** Unix timestamp in milliseconds, null if no expiry */
     expires_at: number | null;
+    /** Always-inject pin marker. 0 = not pinned, 1 = pinned.
+     *  NOT NULL DEFAULT 0 after ensurePinnedColumn() runs. */
+    pinned: number;
     /** 0 or 1 -- whether vec_memories has an embedding for this entry */
     has_embedding: number;
 }
@@ -46,6 +71,60 @@ export interface SessionRow {
     /** JSON-encoded Record<string, unknown> */
     metadata: string;
 }
+/**
+ * Raw row shape for the `lcd_messages` table (LCD lossless store, Phase 127, F1).
+ *
+ * Snake_case DB-row shape — NOT the public API (consumers use the `LcdMessage`
+ * DTO from `@comis/core`, reconstructed via the parts-codec). Carries the R4
+ * tenant/agent/session isolation columns (`conversation_id` is the composite,
+ * the three broken-out columns let Phase 132 filter on the SAME schema without
+ * a migration — threat T-127-06). Paired 1:1 with `LcdMessageRowSchema` in
+ * `./row-schemas.js` via the `row-schemas.test.ts` drift guard.
+ */
+export interface LcdMessageRow {
+    id: string;
+    /** tenant+agent+session composite scope key (R4; enforced Phase 132). */
+    conversation_id: string;
+    tenant_id: string;
+    agent_id: string;
+    session_key: string;
+    /** Monotonic per conversation. */
+    seq: number;
+    /** pi-ai role string: `user` | `assistant` | `toolResult`. */
+    role: string;
+    /** Pre-computed agent-side; the store never computes tokens. */
+    token_count: number;
+    /** Unix timestamp in milliseconds (caller-supplied; the store does not stamp it). */
+    created_at: number;
+}
+/**
+ * Raw row shape for the `lcd_message_parts` table (LCD lossless store, Phase 127, F1).
+ *
+ * One row per structured block. The typed tool columns are the queryable
+ * projection; the verbatim canonical pi-ai block (plus the F3 reasoning marker
+ * and the F2 message envelope) always lives JSON-encoded in `metadata`. Paired
+ * 1:1 with `LcdMessagePartRowSchema` in `./row-schemas.js` via the drift guard.
+ */
+export interface LcdMessagePartRow {
+    id: string;
+    message_id: string;
+    /** Block order within the message. */
+    ordinal: number;
+    /** Block kind: `text` | `tool_use` | `tool_result` | `reasoning` | `file`. */
+    kind: string;
+    /** Stable tool-call id; null for non-tool blocks. */
+    tool_call_id: string | null;
+    /** Tool name; null for non-tool blocks. */
+    tool_name: string | null;
+    /** JSON-encoded tool arguments; null for non-`tool_use` blocks. */
+    tool_input: string | null;
+    /** JSON-encoded tool output; null for non-`tool_result` blocks. */
+    tool_output: string | null;
+    /** 0/1 tool-result error flag; null for non-`tool_result` blocks. */
+    is_error: number | null;
+    /** JSON-encoded LcdPartMetadata (verbatim `raw` block + `messageEnvelope` + `topLevelReasoningOnly`). */
+    metadata: string;
+}
 /**
  * Row shape returned by sqlite-vec KNN queries.
  */
@@ -76,3 +155,97 @@ export interface NamedGraphRow {
     updated_at: number;
     deleted_at: number | null;
 }
+/**
+ * Raw row shape for the `lcd_summaries` table (LCD compaction store, Phase 129, C3).
+ *
+ * Snake_case DB-row shape — NOT the public API (consumers use the `LcdSummary`
+ * DTO from `@comis/core`). One row per depth-0 LEAF summary; carries the R4
+ * tenant/agent/session isolation columns so Phase 132 filters on the SAME
+ * schema with no migration (threat T-129-04). `taint`/`fallback` are the SQLite
+ * bool 0/1 integers; `file_ids` is JSON-encoded TEXT. Paired 1:1 with
+ * `LcdSummaryRowSchema` in `./row-schemas.js` via the `row-schemas.test.ts`
+ * drift guard.
+ */
+export interface LcdSummaryRow {
+    summary_id: string;
+    /** tenant+agent+session composite scope key (R4; enforced Phase 132). */
+    conversation_id: string;
+    tenant_id: string;
+    agent_id: string;
+    session_key: string;
+    /** Closed union TEXT: `leaf` (depth-0) for 129. */
+    kind: string;
+    /** 0 for 129 (leaf); depth>0 is Phase 130. */
+    depth: number;
+    /** Min `created_at` of the covered messages. */
+    earliest_at: number;
+    /** Max `created_at` of the covered messages. */
+    latest_at: number;
+    /** Count of messages this summary covers. */
+    descendant_count: number;
+    /** Pre-computed agent-side; the store never computes tokens. */
+    token_count: number;
+    /** Leaf summary plaintext (never logged). */
+    content: string;
+    /** JSON-encoded string[] of covered file references. */
+    file_ids: string;
+    /** 0/1 untrusted-content flag (enforcement is Phase 132). */
+    taint: number;
+    /** 0/1 deterministic Level-3-truncation marker. */
+    fallback: number;
+    /** Unix timestamp in milliseconds (caller-supplied; the store does not stamp it). */
+    created_at: number;
+}
+/**
+ * Raw row shape for the `lcd_summary_messages` table (LCD compaction store,
+ * Phase 129, C3).
+ *
+ * The leaf→message link — one row per (summary, covered message). The
+ * `message_id` FK is `ON DELETE RESTRICT` so a summarized `lcd_messages` row can
+ * never be deleted (losslessness; Pitfall 5). Paired 1:1 with
+ * `LcdSummaryMessageRowSchema` via the drift guard.
+ */
+export interface LcdSummaryMessageRow {
+    summary_id: string;
+    message_id: string;
+}
+/**
+ * Raw row shape for the `lcd_summary_parents` table (LCD condensed tier,
+ * Phase 130, C2).
+ *
+ * The condensed→child summary edge — one row per (condensed parent summary,
+ * child summary it links). Mirrors `LcdSummaryMessageRow` but BOTH endpoints
+ * are `lcd_summaries` rows: the `child_summary_id` FK is `ON DELETE RESTRICT`
+ * so a condensed child summary can never be deleted (losslessness for the
+ * multi-tier DAG). Paired 1:1 with `LcdSummaryParentRowSchema` via the drift
+ * guard.
+ */
+export interface LcdSummaryParentRow {
+    parent_summary_id: string;
+    child_summary_id: string;
+}
+/**
+ * Raw row shape for the `lcd_context_items` table (LCD compaction store,
+ * Phase 129, C3).
+ *
+ * One row per item of the ordered model-facing view; carries the R4 scoping
+ * columns. `ordinal` is dense + gap-free per conversation (a UNIQUE
+ * `(conversation_id, ordinal)` index enforces it); `ref_kind` is the closed
+ * `message`|`summary` discriminator; `ref_id` points at the referenced
+ * `lcd_messages.id` or `lcd_summaries.summary_id`. Paired 1:1 with
+ * `LcdContextItemRowSchema` via the drift guard.
+ */
+export interface LcdContextItemRow {
+    id: string;
+    /** tenant+agent+session composite scope key (R4; enforced Phase 132). */
+    conversation_id: string;
+    tenant_id: string;
+    agent_id: string;
+    session_key: string;
+    /** Dense, gap-free position in the model-facing order. */
+    ordinal: number;
+    /** Closed discriminator TEXT: `message` | `summary`. */
+    ref_kind: string;
+    /** `lcd_messages.id` OR `lcd_summaries.summary_id`. */
+    ref_id: string;
+}

package/node_modules/@comis/memory/dist/types.js

@@ -6,10 +6,3 @@
  * the public API. Consumers use the domain types from @comis/core.
  */
 export {};
-// --- Context store row types ---
-//
-// The 9 `Ctx*Row` interfaces previously declared here are now the single
-// source-of-truth in `@comis/core/src/ports/context-store-types.ts`.
-// Memory consumers should import them from `@comis/core` (or transitively
-// re-exported from `@comis/memory`'s public index). Database schema and
-// persisted column layout are unchanged.

package/node_modules/@comis/memory/dist/video-job-row-schema.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Zod row schema for the `video_jobs` table — the durable async VideoJobStore
+ * (Phase 189, JOB-01). SSOT for the file-internal `VideoJobDbRow` interface in
+ * `video-job-store.ts`.
+ *
+ * Lives in its OWN module (NOT `row-schemas.ts`) because that file is at the
+ * 800-line cap; this keeps the additive video schema out of it (no allowlist
+ * bump, no inline). Same conventions as `row-schemas.ts` (header :16-19):
+ *   - `z.strictObject(...)` rejects extra columns (a column drift between the
+ *     schema and the `ensureVideoJobTable` DDL surfaces in the round-trip test).
+ *   - nullable → `z.X.nullable()` (`X | null`) — SQLite NULL ≠ undefined; the
+ *     store's `rowToRecord` maps `?? undefined` at the domain boundary.
+ *   - INTEGER timestamps → `z.number()`; REAL cost/progress → `z.number().nullable()`.
+ *
+ * SECURITY (T-189-02): the column set is the opaque provider jobId + routing +
+ * state + cost + path ONLY — NO key/token/secret/bearer column. The provider
+ * credential is held by the boot-bound adapter and is NEVER persisted here.
+ *
+ * @module
+ */
+import { z } from "zod";
+/**
+ * Schema for the `video_jobs` table.
+ * SSOT for the file-internal `VideoJobDbRow` interface in video-job-store.ts.
+ * Columns MUST match the `ensureVideoJobTable` DDL exactly (strictObject).
+ */
+export declare const VideoJobDbRowSchema: z.ZodObject<{
+    job_id: z.ZodString;
+    provider: z.ZodString;
+    model: z.ZodNullable<z.ZodString>;
+    agent_id: z.ZodString;
+    channel_type: z.ZodNullable<z.ZodString>;
+    channel_id: z.ZodNullable<z.ZodString>;
+    trace_id: z.ZodNullable<z.ZodString>;
+    session_key: z.ZodNullable<z.ZodString>;
+    state: z.ZodString;
+    estimated_cost_usd: z.ZodNullable<z.ZodNumber>;
+    actual_cost_usd: z.ZodNullable<z.ZodNumber>;
+    media_path: z.ZodNullable<z.ZodString>;
+    progress: z.ZodNullable<z.ZodNumber>;
+    last_error: z.ZodNullable<z.ZodString>;
+    deliver_attempts: z.ZodNumber;
+    submitted_at_ms: z.ZodNumber;
+    updated_at_ms: z.ZodNumber;
+}, z.core.$strict>;
+export type VideoJobDbRow = z.infer<typeof VideoJobDbRowSchema>;
+/**
+ * Single-column projection for the CR-01 `incrementDeliveryAttempt` read-back —
+ * the bumped `deliver_attempts` value re-read in the same synchronous turn as the
+ * atomic UPDATE. A dedicated schema (vs. the full-row `VideoJobDbRowSchema`) so
+ * the SELECT can project ONE column and still go through `createRowMapper`
+ * (never an untyped `.get(...) as Type` cast — `untyped-sqlite.test.ts`).
+ */
+export declare const VideoJobAttemptRowSchema: z.ZodObject<{
+    deliver_attempts: z.ZodNumber;
+}, z.core.$strict>;
+export type VideoJobAttemptRow = z.infer<typeof VideoJobAttemptRowSchema>;

package/node_modules/@comis/memory/dist/video-job-row-schema.js

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Zod row schema for the `video_jobs` table — the durable async VideoJobStore
+ * (Phase 189, JOB-01). SSOT for the file-internal `VideoJobDbRow` interface in
+ * `video-job-store.ts`.
+ *
+ * Lives in its OWN module (NOT `row-schemas.ts`) because that file is at the
+ * 800-line cap; this keeps the additive video schema out of it (no allowlist
+ * bump, no inline). Same conventions as `row-schemas.ts` (header :16-19):
+ *   - `z.strictObject(...)` rejects extra columns (a column drift between the
+ *     schema and the `ensureVideoJobTable` DDL surfaces in the round-trip test).
+ *   - nullable → `z.X.nullable()` (`X | null`) — SQLite NULL ≠ undefined; the
+ *     store's `rowToRecord` maps `?? undefined` at the domain boundary.
+ *   - INTEGER timestamps → `z.number()`; REAL cost/progress → `z.number().nullable()`.
+ *
+ * SECURITY (T-189-02): the column set is the opaque provider jobId + routing +
+ * state + cost + path ONLY — NO key/token/secret/bearer column. The provider
+ * credential is held by the boot-bound adapter and is NEVER persisted here.
+ *
+ * @module
+ */
+import { z } from "zod";
+/**
+ * Schema for the `video_jobs` table.
+ * SSOT for the file-internal `VideoJobDbRow` interface in video-job-store.ts.
+ * Columns MUST match the `ensureVideoJobTable` DDL exactly (strictObject).
+ */
+export const VideoJobDbRowSchema = z.strictObject({
+    job_id: z.string(),
+    provider: z.string(),
+    model: z.string().nullable(),
+    agent_id: z.string(),
+    channel_type: z.string().nullable(),
+    channel_id: z.string().nullable(),
+    trace_id: z.string().nullable(),
+    // OBS-04 (Phase 192): the off-turn recorder fold key. Nullable — old rows
+    // (pre-192, or in-flight at upgrade time) are NULL → offline-only
+    // reconstruction. The strictObject above REJECTS a column the DDL adds without
+    // this line, so the schema + the ensureVideoJobTable DDL move in lockstep.
+    session_key: z.string().nullable(),
+    // 'pending' | 'done' | 'failed' — Zod is the domain type; no SQL CHECK
+    // (mirrors the delivery queue's `status` being a plain TEXT, validated in TS).
+    state: z.string(),
+    estimated_cost_usd: z.number().nullable(),
+    actual_cost_usd: z.number().nullable(),
+    media_path: z.string().nullable(),
+    progress: z.number().nullable(),
+    // The markFailed errorKind; the Plan-03 status handler surfaces it as `error`.
+    last_error: z.string().nullable(),
+    // CR-01: persisted redelivery counter. NOT NULL DEFAULT 0 in the DDL, so it is
+    // always a number (never null) — the poller bounds the redelivery loop against
+    // it and dead-letters the row to `failed` once it exceeds maxDeliveryAttempts.
+    deliver_attempts: z.number(),
+    submitted_at_ms: z.number(),
+    updated_at_ms: z.number(),
+});
+/**
+ * Single-column projection for the CR-01 `incrementDeliveryAttempt` read-back —
+ * the bumped `deliver_attempts` value re-read in the same synchronous turn as the
+ * atomic UPDATE. A dedicated schema (vs. the full-row `VideoJobDbRowSchema`) so
+ * the SELECT can project ONE column and still go through `createRowMapper`
+ * (never an untyped `.get(...) as Type` cast — `untyped-sqlite.test.ts`).
+ */
+export const VideoJobAttemptRowSchema = z.strictObject({
+    deliver_attempts: z.number(),
+});

package/node_modules/@comis/memory/dist/video-job-store.d.ts

@@ -0,0 +1,130 @@
+/**
+ * VideoJobStore — SQLite persistence for the Phase-189 durable async video-job
+ * lifecycle (JOB-01/JOB-03/JOB-04).
+ *
+ * Factory-function pattern (modeled on `createSqliteDeliveryQueue`): prepares
+ * fixed SQL statements once in the closure, returns a frozen `VideoJobStore`.
+ * Maps between camelCase domain fields and snake_case database columns via
+ * `createRowMapper(VideoJobDbRowSchema)` so a corrupt row degrades to a
+ * `Result.err`, never a throw.
+ *
+ * The job row is the durable spine the background poller resumes against across
+ * a daemon restart: a row survives the agent turn AND a restart because it lives
+ * on disk in the shared `memory.db` (Q1/O3 LOCKED: shared db, not an own .db).
+ *
+ * WHERE IT DIFFERS FROM THE DELIVERY QUEUE:
+ *  1. `get(jobId, agentId)` is agent-scoped (filters BOTH columns — JOB-04 /
+ *     Pitfall 6). A bare `get(jobId)` is FORBIDDEN: it would leak another
+ *     agent's job. A cross-agent jobId returns not-found (`ok(undefined)`).
+ *  2. Carries a video path + cost + progress columns (the queue carries text).
+ *  3. State domain is `pending | done | failed` (the queue's is broader).
+ *  4. ZERO fd-based fs (no explicit file-sync/chmod-by-fd) — better-sqlite3 +
+ *     the shared `db` are permission-model-safe by construction (Pitfall 2 / A4).
+ *
+ * SECURITY (T-189-02): the persisted columns carry NO secret — the `jobId` is
+ * the opaque provider request id; the credential is held by the boot-bound
+ * adapter and is never written here.
+ *
+ * @module
+ */
+import type Database from "better-sqlite3";
+import type { Result } from "@comis/shared";
+/** The state machine for a video job (JOB-01). */
+export type VideoJobState = "pending" | "done" | "failed";
+/** A persisted video-generation job (camelCase domain view of a `video_jobs` row). */
+export interface VideoJobRecord {
+    /** Opaque, durable provider request id (secret-free — T-189-02). */
+    readonly jobId: string;
+    readonly provider: string;
+    readonly model?: string;
+    readonly agentId: string;
+    readonly channelType?: string;
+    readonly channelId?: string;
+    readonly traceId?: string;
+    /** OBS-04 (Phase 192): the formatted session key — the off-turn poller resolves
+     *  the per-session trajectory recorder by this to stitch a background-completed
+     *  render to its originating turn. Nullable in the row (old rows are NULL). */
+    readonly sessionKey?: string;
+    readonly state: VideoJobState;
+    readonly estimatedCostUsd?: number;
+    readonly actualCostUsd?: number;
+    readonly mediaPath?: string;
+    readonly progress?: number;
+    readonly lastError?: string;
+    /** CR-01: count of delivery/completion attempts; bounds the poller's
+     *  redelivery loop (dead-letter once it exceeds maxDeliveryAttempts). */
+    readonly deliverAttempts: number;
+    readonly submittedAtMs: number;
+    readonly updatedAtMs: number;
+}
+/** Insert payload — the JOB-01 fields recorded at submit. */
+export interface VideoJobInsert {
+    readonly jobId: string;
+    readonly provider: string;
+    readonly model?: string;
+    readonly agentId: string;
+    readonly channelType?: string;
+    readonly channelId?: string;
+    readonly traceId?: string;
+    /** OBS-04 (Phase 192): the formatted session key persisted at submit (the
+     *  off-turn recorder fold key). Optional — `undefined` outside a request scope. */
+    readonly sessionKey?: string;
+    readonly state: VideoJobState;
+    readonly estimatedCostUsd?: number;
+    readonly submittedAtMs: number;
+    readonly updatedAtMs: number;
+}
+/** The completion payload for `markDone` (the poller's `done` tail — JOB-02). */
+export interface VideoJobDoneInput {
+    readonly mediaPath: string;
+    readonly actualCostUsd?: number;
+}
+/**
+ * The persisted video-job store. Every method is `Result`-returning and never
+ * throws (reads degrade via the row mapper). `get` is agent-scoped.
+ */
+export interface VideoJobStore {
+    /** Persist a submitted job (state typically 'pending'). */
+    insert(record: VideoJobInsert): Promise<Result<void, Error>>;
+    /** All rows in state 'pending', oldest first (the poller's boot-resume scan). */
+    listPending(): Promise<Result<VideoJobRecord[], Error>>;
+    /**
+     * Read a job scoped to BOTH jobId AND agentId (JOB-04 / Pitfall 6).
+     * Not-found (no such job for this agent) is `ok(undefined)` — distinct from a
+     * real error, so the status handler can answer "no such job" vs "lookup failed".
+     */
+    get(jobId: string, agentId: string): Promise<Result<VideoJobRecord | undefined, Error>>;
+    /** Transition to 'done' + record the delivered path + actual cost (JOB-02). */
+    markDone(jobId: string, input: VideoJobDoneInput): Promise<Result<void, Error>>;
+    /**
+     * Transition to 'failed' + record `last_error` (JOB-02).
+     *
+     * WR-02 (Phase 190): pass the optional `lastError` to persist an ACTIONABLE
+     * operator hint (what `video.status` returns as `error`) instead of the bare
+     * `errorKind` enum token. When omitted, `errorKind` is written verbatim (the
+     * pre-190 behavior — preserved for callers/tests that pass only the kind).
+     */
+    markFailed(jobId: string, errorKind: string, lastError?: string): Promise<Result<void, Error>>;
+    /** Update the optional progress fraction (JOB-02). */
+    updateProgress(jobId: string, progress: number): Promise<Result<void, Error>>;
+    /**
+     * CR-01: atomically `deliver_attempts = deliver_attempts + 1` and return the
+     * NEW count. The poller calls this on each delivery/completion attempt and
+     * dead-letters the row to `failed` once the count exceeds maxDeliveryAttempts,
+     * so a persistent delivery failure converges instead of re-polling +
+     * re-downloading forever. Returns `0` when the jobId matches no row (e.g. the
+     * handler's insert-failure path tracks an un-persisted job in-memory) so the
+     * caller can still bound that case — never an infinite loop.
+     */
+    incrementDeliveryAttempt(jobId: string): Promise<Result<number, Error>>;
+}
+/**
+ * Create a SQLite-backed `VideoJobStore`.
+ *
+ * Assumes `initSchema()` (which calls `ensureVideoJobTable`) has already been
+ * called — the `video_jobs` table exists. Prepares fixed SQL once.
+ *
+ * @param db - An open better-sqlite3 Database instance
+ * @returns VideoJobStore implementation (frozen)
+ */
+export declare function createVideoJobStore(db: Database.Database): VideoJobStore;

package/node_modules/@comis/memory/dist/video-job-store.js

@@ -0,0 +1,202 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * VideoJobStore — SQLite persistence for the Phase-189 durable async video-job
+ * lifecycle (JOB-01/JOB-03/JOB-04).
+ *
+ * Factory-function pattern (modeled on `createSqliteDeliveryQueue`): prepares
+ * fixed SQL statements once in the closure, returns a frozen `VideoJobStore`.
+ * Maps between camelCase domain fields and snake_case database columns via
+ * `createRowMapper(VideoJobDbRowSchema)` so a corrupt row degrades to a
+ * `Result.err`, never a throw.
+ *
+ * The job row is the durable spine the background poller resumes against across
+ * a daemon restart: a row survives the agent turn AND a restart because it lives
+ * on disk in the shared `memory.db` (Q1/O3 LOCKED: shared db, not an own .db).
+ *
+ * WHERE IT DIFFERS FROM THE DELIVERY QUEUE:
+ *  1. `get(jobId, agentId)` is agent-scoped (filters BOTH columns — JOB-04 /
+ *     Pitfall 6). A bare `get(jobId)` is FORBIDDEN: it would leak another
+ *     agent's job. A cross-agent jobId returns not-found (`ok(undefined)`).
+ *  2. Carries a video path + cost + progress columns (the queue carries text).
+ *  3. State domain is `pending | done | failed` (the queue's is broader).
+ *  4. ZERO fd-based fs (no explicit file-sync/chmod-by-fd) — better-sqlite3 +
+ *     the shared `db` are permission-model-safe by construction (Pitfall 2 / A4).
+ *
+ * SECURITY (T-189-02): the persisted columns carry NO secret — the `jobId` is
+ * the opaque provider request id; the credential is held by the boot-bound
+ * adapter and is never written here.
+ *
+ * @module
+ */
+import { ok, err } from "@comis/shared";
+import { systemNowMs } from "@comis/core";
+import { createRowMapper } from "./row-mapper.js";
+import { VideoJobDbRowSchema, VideoJobAttemptRowSchema, } from "./video-job-row-schema.js";
+// ---------------------------------------------------------------------------
+// Row mapper (snake_case -> camelCase)
+// ---------------------------------------------------------------------------
+const videoJobMapper = createRowMapper(VideoJobDbRowSchema);
+const videoJobAttemptMapper = createRowMapper(VideoJobAttemptRowSchema);
+/** Map a validated DB row to the domain record (nullable → `?? undefined`). */
+function rowToRecord(row) {
+    return {
+        jobId: row.job_id,
+        provider: row.provider,
+        ...(row.model !== null ? { model: row.model } : {}),
+        agentId: row.agent_id,
+        ...(row.channel_type !== null ? { channelType: row.channel_type } : {}),
+        ...(row.channel_id !== null ? { channelId: row.channel_id } : {}),
+        ...(row.trace_id !== null ? { traceId: row.trace_id } : {}),
+        ...(row.session_key !== null ? { sessionKey: row.session_key } : {}),
+        state: row.state,
+        ...(row.estimated_cost_usd !== null ? { estimatedCostUsd: row.estimated_cost_usd } : {}),
+        ...(row.actual_cost_usd !== null ? { actualCostUsd: row.actual_cost_usd } : {}),
+        ...(row.media_path !== null ? { mediaPath: row.media_path } : {}),
+        ...(row.progress !== null ? { progress: row.progress } : {}),
+        ...(row.last_error !== null ? { lastError: row.last_error } : {}),
+        deliverAttempts: row.deliver_attempts,
+        submittedAtMs: row.submitted_at_ms,
+        updatedAtMs: row.updated_at_ms,
+    };
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a SQLite-backed `VideoJobStore`.
+ *
+ * Assumes `initSchema()` (which calls `ensureVideoJobTable`) has already been
+ * called — the `video_jobs` table exists. Prepares fixed SQL once.
+ *
+ * @param db - An open better-sqlite3 Database instance
+ * @returns VideoJobStore implementation (frozen)
+ */
+export function createVideoJobStore(db) {
+    // --- Prepared statements ---
+    const insertStmt = db.prepare(`
+    INSERT INTO video_jobs (
+      job_id, provider, model, agent_id, channel_type, channel_id, trace_id,
+      session_key, state, estimated_cost_usd, actual_cost_usd, media_path,
+      progress, last_error, submitted_at_ms, updated_at_ms
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, NULL, NULL, NULL, ?, ?)
+  `);
+    // Agent-scoped read — filters by BOTH columns (the must-differ point 1;
+    // JOB-04 / Pitfall 6). A cross-agent jobId matches no row → not-found.
+    const getStmt = db.prepare(`
+    SELECT * FROM video_jobs WHERE job_id = ? AND agent_id = ?
+  `);
+    const pendingStmt = db.prepare(`
+    SELECT * FROM video_jobs WHERE state = 'pending' ORDER BY submitted_at_ms ASC
+  `);
+    const markDoneStmt = db.prepare(`
+    UPDATE video_jobs
+    SET state = 'done', media_path = ?, actual_cost_usd = ?, updated_at_ms = ?
+    WHERE job_id = ?
+  `);
+    const markFailedStmt = db.prepare(`
+    UPDATE video_jobs
+    SET state = 'failed', last_error = ?, updated_at_ms = ?
+    WHERE job_id = ?
+  `);
+    const updateProgressStmt = db.prepare(`
+    UPDATE video_jobs SET progress = ?, updated_at_ms = ? WHERE job_id = ?
+  `);
+    // CR-01: atomic redelivery-counter bump. better-sqlite3 is synchronous +
+    // single-connection, so the UPDATE and the paired read below run in the SAME
+    // event-loop turn — no interleaving, so the read sees this UPDATE's value.
+    const incrementAttemptStmt = db.prepare(`
+    UPDATE video_jobs SET deliver_attempts = deliver_attempts + 1, updated_at_ms = ?
+    WHERE job_id = ?
+  `);
+    const readAttemptStmt = db.prepare(`
+    SELECT deliver_attempts FROM video_jobs WHERE job_id = ?
+  `);
+    // --- Store implementation ---
+    const store = {
+        insert(record) {
+            try {
+                insertStmt.run(record.jobId, record.provider, record.model ?? null, record.agentId, record.channelType ?? null, record.channelId ?? null, record.traceId ?? null, record.sessionKey ?? null, record.state, record.estimatedCostUsd ?? null, record.submittedAtMs, record.updatedAtMs);
+                return Promise.resolve(ok(undefined));
+            }
+            catch (e) {
+                return Promise.resolve(err(e instanceof Error ? e : new Error(String(e))));
+            }
+        },
+        listPending() {
+            try {
+                const parsed = videoJobMapper.parseRows(pendingStmt.all());
+                if (!parsed.ok) {
+                    return Promise.resolve(err(new Error(`Row validation failed: ${parsed.error.message}`)));
+                }
+                return Promise.resolve(ok(parsed.value.map(rowToRecord)));
+            }
+            catch (e) {
+                return Promise.resolve(err(e instanceof Error ? e : new Error(String(e))));
+            }
+        },
+        get(jobId, agentId) {
+            try {
+                const parsed = videoJobMapper.parseOptionalRow(getStmt.get(jobId, agentId));
+                if (!parsed.ok) {
+                    return Promise.resolve(err(new Error(`Row validation failed: ${parsed.error.message}`)));
+                }
+                // ok(undefined) when no row matched the (jobId, agentId) pair —
+                // a different agent's jobId is not-found (no cross-agent leak).
+                return Promise.resolve(ok(parsed.value === undefined ? undefined : rowToRecord(parsed.value)));
+            }
+            catch (e) {
+                return Promise.resolve(err(e instanceof Error ? e : new Error(String(e))));
+            }
+        },
+        markDone(jobId, input) {
+            try {
+                markDoneStmt.run(input.mediaPath, input.actualCostUsd ?? null, systemNowMs(), jobId);
+                return Promise.resolve(ok(undefined));
+            }
+            catch (e) {
+                return Promise.resolve(err(e instanceof Error ? e : new Error(String(e))));
+            }
+        },
+        markFailed(jobId, errorKind, lastError) {
+            try {
+                // WR-02: persist the actionable hint when supplied; else the bare kind.
+                markFailedStmt.run(lastError ?? errorKind, systemNowMs(), jobId);
+                return Promise.resolve(ok(undefined));
+            }
+            catch (e) {
+                return Promise.resolve(err(e instanceof Error ? e : new Error(String(e))));
+            }
+        },
+        updateProgress(jobId, progress) {
+            try {
+                updateProgressStmt.run(progress, systemNowMs(), jobId);
+                return Promise.resolve(ok(undefined));
+            }
+            catch (e) {
+                return Promise.resolve(err(e instanceof Error ? e : new Error(String(e))));
+            }
+        },
+        incrementDeliveryAttempt(jobId) {
+            try {
+                // Atomic bump. `.changes === 0` means no such row (e.g. the handler's
+                // insert-failure path tracks an un-persisted job in-memory) — return 0
+                // so the caller bounds that case rather than spinning forever.
+                const info = incrementAttemptStmt.run(systemNowMs(), jobId);
+                if (info.changes === 0)
+                    return Promise.resolve(ok(0));
+                // Same synchronous turn (better-sqlite3 is sync + single-connection), so
+                // this read observes the UPDATE above. Parsed via the mapper — never an
+                // untyped `.get(...) as Type` cast (untyped-sqlite invariant).
+                const parsed = videoJobAttemptMapper.parseOptionalRow(readAttemptStmt.get(jobId));
+                if (!parsed.ok) {
+                    return Promise.resolve(err(new Error(`Row validation failed: ${parsed.error.message}`)));
+                }
+                return Promise.resolve(ok(parsed.value === undefined ? 0 : parsed.value.deliver_attempts));
+            }
+            catch (e) {
+                return Promise.resolve(err(e instanceof Error ? e : new Error(String(e))));
+            }
+        },
+    };
+    return Object.freeze(store);
+}