@maolon/pi-watcher 0.0.0-stage → 0.1.0

package/dist/storage/schema.sql

@@ -0,0 +1,166 @@
+-- pi-watcher WatchStore schema (schema_version 1).
+-- Applied only when creating a NEW database; it is not a migration script.
+
+PRAGMA foreign_keys = ON;
+PRAGMA journal_mode = WAL;
+PRAGMA synchronous = FULL;
+CREATE TABLE runtime_meta (
+  singleton INTEGER PRIMARY KEY CHECK(singleton=1),
+  schema_version INTEGER NOT NULL CHECK(schema_version=1),
+  runtime_epoch INTEGER NOT NULL CHECK(runtime_epoch>0),
+  mode TEXT NOT NULL CHECK(mode IN ('embedded','service')),
+  recovery_attention_hold INTEGER NOT NULL DEFAULT 1 CHECK(recovery_attention_hold IN (0,1))
+);
+CREATE TABLE watches (
+  watch_id TEXT PRIMARY KEY,
+  generation INTEGER NOT NULL CHECK(generation>0),
+  mission_revision INTEGER NOT NULL CHECK(mission_revision>0),
+  control_revision INTEGER NOT NULL CHECK(control_revision>0),
+  lifecycle TEXT NOT NULL CHECK(lifecycle IN ('draft','active','paused','closed','expired')),
+  health TEXT NOT NULL CHECK(health IN ('healthy','degraded','blind')),
+  owner_session TEXT NOT NULL,
+  owner_binding_epoch INTEGER NOT NULL CHECK(owner_binding_epoch>0),
+  spec_json TEXT NOT NULL CHECK(json_valid(spec_json)),
+  snapshot_json TEXT NOT NULL DEFAULT '{}' CHECK(json_valid(snapshot_json)),
+  observation_seq INTEGER NOT NULL DEFAULT 0 CHECK(observation_seq>=0),
+  next_due_at INTEGER,
+  updated_at INTEGER NOT NULL
+);
+CREATE TABLE evidence (
+  evidence_id TEXT PRIMARY KEY,
+  watch_id TEXT NOT NULL REFERENCES watches(watch_id),
+  sha256 TEXT NOT NULL CHECK(length(sha256)=64),
+  byte_count INTEGER NOT NULL CHECK(byte_count>=0),
+  relative_locator TEXT NOT NULL,
+  captured_at INTEGER NOT NULL,
+  pinned INTEGER NOT NULL DEFAULT 0 CHECK(pinned IN (0,1))
+);
+CREATE TABLE observations (
+  observation_id TEXT PRIMARY KEY,
+  watch_id TEXT NOT NULL REFERENCES watches(watch_id),
+  generation INTEGER NOT NULL,
+  source_id TEXT NOT NULL,
+  attempt_id TEXT NOT NULL,
+  source_seq INTEGER NOT NULL CHECK(source_seq>=0),
+  local_seq INTEGER NOT NULL CHECK(local_seq>0),
+  observed_at INTEGER NOT NULL,
+  digest TEXT NOT NULL,
+  payload_json TEXT NOT NULL CHECK(json_valid(payload_json)),
+  UNIQUE(watch_id,generation,source_id,attempt_id,source_seq),
+  UNIQUE(watch_id,local_seq)
+);
+CREATE TABLE cursors (
+  watch_id TEXT NOT NULL REFERENCES watches(watch_id),
+  source_id TEXT NOT NULL,
+  generation INTEGER NOT NULL,
+  cursor_json TEXT NOT NULL CHECK(json_valid(cursor_json)),
+  PRIMARY KEY(watch_id,source_id,generation)
+);
+CREATE TABLE episodes (
+  episode_id TEXT PRIMARY KEY,
+  watch_id TEXT NOT NULL REFERENCES watches(watch_id),
+  generation INTEGER NOT NULL,
+  kind TEXT NOT NULL,
+  checkpoint_id TEXT NOT NULL,
+  ordinal INTEGER NOT NULL CHECK(ordinal>0),
+  revision INTEGER NOT NULL CHECK(revision>0),
+  state TEXT NOT NULL CHECK(state IN ('open','snoozed','acknowledged','resolved','superseded')),
+  body_json TEXT NOT NULL CHECK(json_valid(body_json)),
+  snooze_until INTEGER,
+  updated_at INTEGER NOT NULL,
+  UNIQUE(watch_id,generation,kind,checkpoint_id,ordinal)
+);
+CREATE UNIQUE INDEX one_active_episode_per_slot ON episodes(watch_id,generation,kind,checkpoint_id)
+  WHERE state IN ('open','snoozed','acknowledged');
+CREATE TABLE judgments (
+  judgment_id TEXT PRIMARY KEY,
+  watch_id TEXT NOT NULL REFERENCES watches(watch_id),
+  generation INTEGER NOT NULL,
+  mission_revision INTEGER NOT NULL,
+  control_revision INTEGER NOT NULL,
+  window_digest TEXT NOT NULL,
+  model TEXT NOT NULL,
+  question_set TEXT NOT NULL,
+  status TEXT NOT NULL CHECK(status IN ('pending','inflight','accepted','discarded','failed')),
+  data_json TEXT NOT NULL CHECK(json_valid(data_json)),
+  created_at INTEGER NOT NULL
+);
+CREATE TABLE probe_runs (
+  probe_run_id TEXT PRIMARY KEY,
+  watch_id TEXT NOT NULL REFERENCES watches(watch_id),
+  episode_id TEXT REFERENCES episodes(episode_id),
+  generation INTEGER NOT NULL,
+  control_revision INTEGER NOT NULL,
+  probe_id TEXT NOT NULL,
+  status TEXT NOT NULL CHECK(status IN ('pending','inflight','done','discarded','failed')),
+  data_json TEXT NOT NULL CHECK(json_valid(data_json)),
+  created_at INTEGER NOT NULL
+);
+CREATE TABLE outbox (
+  event_id TEXT PRIMARY KEY,
+  watch_id TEXT NOT NULL REFERENCES watches(watch_id),
+  episode_id TEXT REFERENCES episodes(episode_id),
+  generation INTEGER NOT NULL,
+  event_type TEXT NOT NULL,
+  event_bytes BLOB NOT NULL,
+  event_digest TEXT NOT NULL,
+  valid_until INTEGER NOT NULL,
+  admission TEXT NOT NULL CHECK(admission IN ('pending','publishing','source-staged','empty-audience','unknown','rejected','expired')),
+  admission_json TEXT NOT NULL DEFAULT '{}' CHECK(json_valid(admission_json)),
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+CREATE TRIGGER outbox_identity_immutable BEFORE UPDATE OF event_id,event_bytes,event_digest,valid_until ON outbox
+WHEN OLD.event_id IS NOT NEW.event_id OR OLD.event_bytes IS NOT NEW.event_bytes
+ OR OLD.event_digest IS NOT NEW.event_digest OR OLD.valid_until IS NOT NEW.valid_until
+BEGIN SELECT RAISE(ABORT,'immutable outbox identity'); END;
+CREATE TABLE host_acks (
+  request_id TEXT PRIMARY KEY,
+  episode_id TEXT NOT NULL REFERENCES episodes(episode_id),
+  expected_revision INTEGER NOT NULL,
+  action TEXT NOT NULL CHECK(action IN ('received','investigating','defer','resolved','dismiss')),
+  actor_binding_epoch INTEGER NOT NULL,
+  digest TEXT NOT NULL,
+  response_json TEXT NOT NULL CHECK(json_valid(response_json)),
+  created_at INTEGER NOT NULL
+);
+CREATE TABLE commands (
+  request_id TEXT NOT NULL,
+  actor_id TEXT NOT NULL,
+  digest TEXT NOT NULL,
+  response_json TEXT NOT NULL CHECK(json_valid(response_json)),
+  committed_at INTEGER NOT NULL,
+  PRIMARY KEY(actor_id,request_id)
+);
+CREATE TABLE budget_reservations (
+  reservation_id TEXT PRIMARY KEY,
+  watch_id TEXT NOT NULL REFERENCES watches(watch_id),
+  category TEXT NOT NULL CHECK(category IN ('judge','probe','attention')),
+  period_key TEXT NOT NULL,
+  units INTEGER NOT NULL CHECK(units>0),
+  state TEXT NOT NULL CHECK(state IN ('reserved','spent','unknown-cost','released')),
+  created_at INTEGER NOT NULL
+);
+CREATE INDEX due_watches ON watches(next_due_at) WHERE lifecycle='active';
+CREATE TABLE control_outbox (
+  operation_id TEXT PRIMARY KEY, watch_id TEXT NOT NULL REFERENCES watches(watch_id),
+  scope_id TEXT NOT NULL, expected_revision INTEGER NOT NULL, next_revision INTEGER NOT NULL,
+  requested_state TEXT NOT NULL CHECK(requested_state IN ('active','paused','closed')),
+  status TEXT NOT NULL CHECK(status IN ('pending','sending','source-applied','complete','unknown','rejected')),
+  result_json TEXT NOT NULL DEFAULT '{}' CHECK(json_valid(result_json)), created_at INTEGER NOT NULL,
+  CHECK(next_revision=expected_revision+1)
+);
+CREATE TABLE applied_responses (
+  response_id TEXT PRIMARY KEY, watch_id TEXT NOT NULL REFERENCES watches(watch_id),
+  episode_id TEXT NOT NULL REFERENCES episodes(episode_id), delivery_ref TEXT NOT NULL,
+  digest TEXT NOT NULL, result_json TEXT NOT NULL CHECK(json_valid(result_json)), applied_at INTEGER NOT NULL
+);
+CREATE TABLE applied_confirmation_outbox (
+  operation_id TEXT PRIMARY KEY, response_id TEXT NOT NULL UNIQUE REFERENCES applied_responses(response_id),
+  status TEXT NOT NULL CHECK(status IN ('pending','sending','confirmed','unknown')), result_json TEXT NOT NULL CHECK(json_valid(result_json))
+);
+CREATE TABLE relay_projections (
+  event_id TEXT PRIMARY KEY REFERENCES outbox(event_id), source_cursor INTEGER NOT NULL,
+  snapshot_json TEXT NOT NULL CHECK(json_valid(snapshot_json)), observed_at INTEGER NOT NULL
+);
+CREATE TABLE relay_cursors (stream_id TEXT PRIMARY KEY, cursor INTEGER NOT NULL CHECK(cursor>=0));

package/dist/storage/store.d.ts

@@ -0,0 +1,352 @@
+/**
+ * WatchStore: local truth store (design 07).
+ * - SQLite WAL / synchronous=FULL / foreign_keys=ON
+ * - Each process holds the root flock (fixed inode); runtimeEpoch increments on every open
+ * - transaction(): synchronous, bounded transaction body (external I/O is forbidden inside)
+ */
+import type { Json, WatchSpec, Basis } from '../contracts/interfaces.js';
+export interface WatchSnapshot {
+    taskState: 'unknown' | 'queued' | 'running' | 'blocked' | 'succeeded' | 'failed' | 'cancelled';
+    stage?: string | null;
+    exitCode?: number | null;
+    summary?: string | null;
+    checks?: Array<{
+        checkId: string;
+        outcome: string;
+        artifactDigest: string | null;
+    }>;
+    artifactIds?: string[];
+    lastObservedAtMs?: number;
+    lastSourceSeq?: number;
+    lastResultId?: string | null;
+    coverage: {
+        truncated: boolean;
+        sourceGap: boolean;
+    };
+    degradedReason?: string | null;
+    /** Legacy local counter (pre-2026-10-07); superseded by relayScope. */
+    scopeRevision: number;
+    /**
+     * Per-watch relay scope (design 9.6): one scope per watch generation + owner bindingEpoch,
+     * created lazily on the first managed attention. revision is the latest intended revision;
+     * an open control_outbox row means the relay has not confirmed it yet (design 7.7).
+     */
+    relayScope?: {
+        scopeId: string;
+        revision: number;
+        state: 'active' | 'paused' | 'closed';
+    };
+    backoffMs: number;
+    terminalAt?: number | null;
+    tailLines?: string[];
+    /** Source evidence: the process has exited (even if the result is unknown) -- outcome-unknown terminal-state signal */
+    exited?: boolean;
+    /** V3 group-task projection: member state and readiness time */
+    members?: Array<{
+        watchId: string;
+        taskState: string;
+        lifecycle: string;
+    }>;
+    groupReadyAt?: number | null;
+    /** V2 semantic-layer projection (design 5.5/5.6): shadow only records candidates */
+    semantic?: {
+        mode: 'shadow' | 'active';
+        lastWindowDigest?: string | null;
+        lastJudgedAtMs?: number | null;
+        lastJudgedSourceSeq?: number | null;
+        /** Local observationSeq high-water mark ("window with new observations", design 5.5) */
+        lastJudgedObservationSeq?: number | null;
+        repeatingStreak: number;
+        meaningfulProgress?: number | null;
+        candidates?: Record<string, Json>;
+        consentMissing?: boolean;
+        budgetExhausted?: boolean;
+        error?: string | null;
+    };
+}
+export declare function emptySnapshot(): WatchSnapshot;
+export interface WatchRow {
+    watchId: string;
+    generation: number;
+    missionRevision: number;
+    controlRevision: number;
+    lifecycle: 'draft' | 'active' | 'paused' | 'closed' | 'expired';
+    health: 'healthy' | 'degraded' | 'blind';
+    ownerSession: string;
+    ownerBindingEpoch: number;
+    spec: WatchSpec;
+    snapshot: WatchSnapshot;
+    observationSeq: number;
+    nextDueAt: number | null;
+    updatedAt: number;
+}
+export interface EpisodeRow {
+    episodeId: string;
+    watchId: string;
+    generation: number;
+    kind: string;
+    checkpointId: string;
+    ordinal: number;
+    revision: number;
+    state: 'open' | 'snoozed' | 'acknowledged' | 'resolved' | 'superseded';
+    body: Record<string, Json>;
+    snoozeUntil: number | null;
+    updatedAt: number;
+}
+export interface OutboxRow {
+    eventId: string;
+    watchId: string;
+    episodeId: string | null;
+    generation: number;
+    eventType: string;
+    eventBytes: Buffer;
+    eventDigest: string;
+    validUntil: number;
+    admission: string;
+    admissionJson: Record<string, Json>;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface ControlOutboxRow {
+    operationId: string;
+    watchId: string;
+    scopeId: string;
+    expectedRevision: number;
+    nextRevision: number;
+    requestedState: 'active' | 'paused' | 'closed';
+    status: string;
+    createdAt: number;
+}
+export interface StoreTx {
+    meta(): {
+        schemaVersion: number;
+        runtimeEpoch: number;
+        mode: string;
+        recoveryAttentionHold: boolean;
+    };
+    clearRecoveryHold(): void;
+    getWatchRow(watchId: string): WatchRow | undefined;
+    getWatch(watchId: string): WatchSpec | undefined;
+    compareRevision(basis: Basis): boolean;
+    persistCommandResult(actorId: string, requestId: string, digest: string, result: Json): {
+        duplicate: boolean;
+        previous?: Json;
+    };
+    getCommand(actorId: string, requestId: string): {
+        digest: string;
+        response: Json;
+    } | undefined;
+    insertWatch(row: {
+        watchId: string;
+        generation: number;
+        missionRevision: number;
+        controlRevision: number;
+        lifecycle: WatchRow['lifecycle'];
+        health: WatchRow['health'];
+        ownerSession: string;
+        ownerBindingEpoch: number;
+        spec: WatchSpec;
+        snapshot: WatchSnapshot;
+        nextDueAt: number | null;
+        now: number;
+    }): void;
+    updateWatch(watchId: string, patch: {
+        lifecycle?: WatchRow['lifecycle'];
+        health?: WatchRow['health'];
+        controlRevision?: number;
+        missionRevision?: number;
+        snapshot?: WatchSnapshot;
+        observationSeq?: number;
+        nextDueAt?: number | null;
+    }, now: number): void;
+    bumpObservationSeq(watchId: string): number;
+    insertObservation(input: {
+        observationId: string;
+        watchId: string;
+        generation: number;
+        sourceId: string;
+        attemptId: string;
+        sourceSeq: number;
+        localSeq: number;
+        observedAt: number;
+        digest: string;
+        payload: Json;
+    }): boolean;
+    getCursor(watchId: string, sourceId: string, generation: number): Json | undefined;
+    putCursor(watchId: string, sourceId: string, generation: number, cursor: Json): void;
+    nextEpisodeOrdinal(watchId: string, generation: number, kind: string, checkpointId: string): number;
+    insertEpisode(input: {
+        episodeId: string;
+        watchId: string;
+        generation: number;
+        kind: string;
+        checkpointId: string;
+        ordinal: number;
+        body: Record<string, Json>;
+        now: number;
+    }): void;
+    getEpisode(episodeId: string): EpisodeRow | undefined;
+    getActiveEpisodeBySlot(watchId: string, generation: number, kind: string, checkpointId: string): EpisodeRow | undefined;
+    updateEpisode(episodeId: string, expectedRevision: number, patch: {
+        state?: EpisodeRow['state'];
+        body?: Record<string, Json>;
+        snoozeUntil?: number | null;
+    }, now: number): number | null;
+    listEpisodes(watchId: string, limit: number): EpisodeRow[];
+    /** When closing a watch, fold its unresolved episodes (-> superseded); returns the number of affected rows */
+    supersedeEpisodesOfWatch(watchId: string, now: number): number;
+    /** Sweep: watch is already closed/expired but episode is still open/snoozed/acknowledged -> superseded */
+    supersedeEpisodesOfInactiveWatches(now: number): number;
+    /** Sweep: attention envelope is past validUntil and still pending/publishing -> expired */
+    expireStaleAttentions(now: number): number;
+    insertOutbox(input: {
+        eventId: string;
+        watchId: string;
+        episodeId: string | null;
+        generation: number;
+        eventType: string;
+        eventBytes: Buffer;
+        eventDigest: string;
+        validUntil: number;
+        admissionJson?: Record<string, Json>;
+        admission?: string;
+        now: number;
+    }): void;
+    setOutboxAdmission(eventId: string, admission: string, admissionJson: Record<string, Json>, now: number): void;
+    getOutbox(eventId: string): OutboxRow | undefined;
+    listOutboxByWatch(watchId: string, limit: number): OutboxRow[];
+    insertControlOutbox(input: {
+        operationId: string;
+        watchId: string;
+        scopeId: string;
+        expectedRevision: number;
+        nextRevision: number;
+        requestedState: 'active' | 'paused' | 'closed';
+        now: number;
+    }): void;
+    completeControlOutbox(operationId: string, status: 'source-applied' | 'complete' | 'unknown' | 'rejected', result?: Record<string, Json>): void;
+    getControlOutboxStatus(operationId: string): string | null;
+    /** Unconfirmed control ops (pending/sending/unknown), FIFO; optionally for one watch. */
+    listOpenControlOutbox(watchId?: string): ControlOutboxRow[];
+    /** Shallow-merges keys into an outbox row's admission_json (identity columns stay immutable). */
+    mergeOutboxAdmissionJson(eventId: string, patch: Record<string, Json>, now: number): void;
+    /** Attention rows whose durable withdraw intent has no recorded relay result yet. */
+    listOutboxAwaitingWithdraw(limit: number): OutboxRow[];
+    insertAppliedResponse(input: {
+        responseId: string;
+        watchId: string;
+        episodeId: string;
+        deliveryRef: string;
+        digest: string;
+        result: Record<string, Json>;
+        now: number;
+    }): void;
+    getAppliedResponse(responseId: string): {
+        responseId: string;
+        result: Record<string, Json>;
+    } | undefined;
+    insertAppliedConfirmOutbox(operationId: string, responseId: string): void;
+    listObservations(watchId: string, limit: number): Array<{
+        observationId: string;
+        sourceSeq: number;
+        localSeq: number;
+        observedAt: number;
+        digest: string;
+        payload: Json;
+    }>;
+    listWatches(ownerSession: string, cursor: string | undefined, limit: number, lifecycles?: Array<WatchRow['lifecycle']>): WatchRow[];
+    listAllWatches(limit: number): WatchRow[];
+    /** Count by lifecycle (terminal summary of the list projection); no filter = all watches of that owner */
+    countWatches(ownerSession: string, lifecycles?: Array<WatchRow['lifecycle']>): number;
+    countOpenEpisodes(watchId: string): number;
+    /** Count of unresolved episodes across the whole DB or by ownerSession (widget projection) */
+    countUnresolvedEpisodes(ownerSession?: string): number;
+    /** Count of attention events whose episode is not yet acknowledged by the host (open/snoozed) and whose envelope is still within its validity period (widget projection, optionally filtered by ownerSession) */
+    countPendingAttentions(now: number, ownerSession?: string): number;
+    insertJudgment(input: {
+        judgmentId: string;
+        watchId: string;
+        generation: number;
+        missionRevision: number;
+        controlRevision: number;
+        windowDigest: string;
+        model: string;
+        questionSet: string;
+        status: 'pending' | 'inflight' | 'accepted' | 'discarded' | 'failed';
+        data: Record<string, Json>;
+        createdAt: number;
+    }): void;
+    getJudgmentByWindow(watchId: string, generation: number, windowDigest: string, model: string, questionSet: string): {
+        judgmentId: string;
+        status: string;
+        data: Record<string, Json>;
+    } | undefined;
+    listJudgments(watchId: string, limit: number): Array<{
+        judgmentId: string;
+        windowDigest: string;
+        model: string;
+        questionSet: string;
+        status: string;
+        data: Record<string, Json>;
+        createdAt: number;
+    }>;
+    insertProbeRun(input: {
+        probeRunId: string;
+        watchId: string;
+        episodeId: string | null;
+        generation: number;
+        controlRevision: number;
+        probeId: string;
+        status: 'pending' | 'inflight' | 'done' | 'discarded' | 'failed';
+        data: Record<string, Json>;
+        createdAt: number;
+    }): void;
+    setProbeRunStatus(probeRunId: string, status: 'pending' | 'inflight' | 'done' | 'discarded' | 'failed', data: Record<string, Json>): void;
+    countBudgetReservations(category: 'judge' | 'probe' | 'attention', periodKey: string, watchId?: string): number;
+    insertBudgetReservation(input: {
+        reservationId: string;
+        watchId: string;
+        category: 'judge' | 'probe' | 'attention';
+        periodKey: string;
+        units: number;
+        state: 'reserved' | 'spent' | 'unknown-cost' | 'released';
+        createdAt: number;
+    }): void;
+    setBudgetReservationState(reservationId: string, state: 'reserved' | 'spent' | 'unknown-cost' | 'released'): void;
+    getRelayCursor(streamId: string): number | undefined;
+    putRelayCursor(streamId: string, cursor: number): void;
+}
+export interface WatchStoreOptions {
+    mode?: 'embedded' | 'service';
+    /** Skip flock (single-process tests may pass false to open a second view). */
+    noLock?: boolean;
+}
+export declare class WatchStore {
+    readonly rootDir: string;
+    readonly dbPath: string;
+    readonly evidenceDir: string;
+    readonly resultsDir: string;
+    readonly runtimeEpoch: number;
+    private readonly db;
+    private readonly lock;
+    private closed;
+    private constructor();
+    static open(rootDir: string, options?: WatchStoreOptions): Promise<WatchStore>;
+    transaction<T>(body: (tx: StoreTx) => T): T;
+    get isClosed(): boolean;
+    /** Connection-level pragma diagnostics (WAL persists; synchronous/foreign_keys are connection-level). */
+    pragmaReport(): {
+        journalMode: unknown;
+        synchronous: unknown;
+        foreignKeys: unknown;
+    };
+    close(): void;
+    writeEvidenceBlock(content: string): {
+        sha256: string;
+        relativeLocator: string;
+        bytes: number;
+    };
+    writeResultCard(watchId: string, resultId: string, card: Json): string;
+    listResultCards(watchId: string): Json[];
+    private makeTx;
+}