create-principles-disciple 1.121.7 → 1.121.9

package/host-runtime/dist/governance-observation-store.js

@@ -0,0 +1,649 @@
+/**
+ * Governance Observation Store — Codex Governance Closure Slice A (PRI-622).
+ *
+ * Host-neutral storage seam for bounded Governance Observations, per Codex
+ * Governance Closure SPEC rev 2 §6/§7/§10/§11 and the Slice A Implementation
+ * SPEC (2026-08-29). The Codex adapter decodes host transcripts and calls
+ * {@link ingestGovernanceObservations}; this module owns everything below the
+ * seam: sanitization at the persistence boundary, logical/physical identity
+ * upsert and convergence, the transcript checkpoint, bounded retention
+ * (latest ≤32 visible turns per rollout AND ≤7 days, whichever expires
+ * sooner), compaction/rollback tombstones, and the promotion substrate
+ * (≤12 preceding turns + trigger + next completed assistant turn with a
+ * durable pending tail) that Slice B will drive after pain admission.
+ *
+ * Slice A creates NO pain identity: promotion accepts a caller-provided
+ * pain reference only (SPEC §18).
+ *
+ * Storage authority: the existing Workspace trajectory store
+ * `{workspace}/.state/trajectory.db`. The baseline schema is owned by
+ * openclaw-plugin's `applyTrajectorySchema` (mirrored in core's
+ * `ensureTrajectorySchema` for the pain tables). The `governance_*` tables
+ * below are written and read ONLY by this module, so their DDL lives here —
+ * idempotent, versioned by `governance_observation_schema_version`, and
+ * additive to any existing trajectory.db (unknown tables are untouched by
+ * the other owners). No raw transcript bytes, no second pain authority.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import Database from 'better-sqlite3';
+import { sanitizeString, sanitizeValue } from '@principles/core/runtime-v2';
+// ─── Retention policy constants (Owner-approved, SPEC rev 2 §11) ────────────
+export const GOVERNANCE_RETENTION_MAX_TURNS = 32;
+export const GOVERNANCE_RETENTION_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+export const GOVERNANCE_PROMOTION_PRECEDING_TURNS = 12;
+export const GOVERNANCE_PENDING_TAIL_STALE_MS = 7 * 24 * 60 * 60 * 1000;
+const GOVERNANCE_OBSERVATION_SCHEMA_VERSION = 2;
+const MAX_TEXT_BOUND = 200; // matches MAX_EVIDENCE_VALUE_CHARS; guards stored identity fields
+const MAX_JSON_COLUMN = 8_000;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function own(value, key) {
+    return Object.hasOwn(value, key) ? Object.getOwnPropertyDescriptor(value, key)?.value : undefined;
+}
+function boundedString(value, max) {
+    if (value === null || value === undefined)
+        return null;
+    return value.length > max ? value.slice(0, max) : value;
+}
+function safeJson(value) {
+    try {
+        const text = JSON.stringify(value);
+        if (typeof text !== 'string')
+            return null;
+        if (text.length <= MAX_JSON_COLUMN)
+            return text;
+        // Truncating a serialized JSON document mid-value yields INVALID JSON.
+        // Keep the column bound while staying parseable: store an ESCAPED
+        // fragment inside a small wrapper object, shrinking until the wrapper
+        // itself fits (escaping can expand the fragment, so verify each round).
+        let keep = text.length;
+        while (keep > 0) {
+            keep = Math.max(0, keep - Math.max(200, Math.floor(keep / 4)));
+            const wrapped = JSON.stringify({ truncated: true, preview: text.slice(0, keep) });
+            if (wrapped.length <= MAX_JSON_COLUMN)
+                return wrapped;
+        }
+        return '{"truncated":true,"preview":""}';
+    }
+    catch {
+        return null;
+    }
+}
+const CREATE_STATEMENTS = [
+    `CREATE TABLE IF NOT EXISTS governance_observation_schema_version (version INTEGER NOT NULL)`,
+    `CREATE TABLE IF NOT EXISTS governance_rollouts (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    host_kind TEXT NOT NULL,
+    rollout_identity TEXT NOT NULL,
+    root_session_id TEXT NOT NULL,
+    parent_rollout_id TEXT,
+    agent_identity TEXT,
+    agent_depth INTEGER,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    UNIQUE(host_kind, rollout_identity)
+  )`,
+    `CREATE TABLE IF NOT EXISTS governance_observations (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    rollout_row_id INTEGER NOT NULL,
+    host_kind TEXT NOT NULL,
+    rollout_identity TEXT NOT NULL,
+    root_session_id TEXT NOT NULL,
+    host_turn_id TEXT NOT NULL,
+    kind TEXT NOT NULL,
+    logical_key TEXT NOT NULL,
+    transcript_record_key TEXT,
+    source_order INTEGER,
+    source_ordinal INTEGER,
+    assistant_item_id TEXT,
+    phase TEXT,
+    tool_use_id TEXT,
+    transcript_tool_call_id TEXT,
+    visible_text TEXT,
+    sanitized_tool_facts_json TEXT,
+    source TEXT NOT NULL,
+    completeness TEXT NOT NULL,
+    retention_class TEXT NOT NULL DEFAULT 'operational',
+    observed_at TEXT NOT NULL,
+    promoted_at TEXT,
+    promotion_ref TEXT,
+    expired_at TEXT,
+    UNIQUE(logical_key)
+  )`,
+    `CREATE INDEX IF NOT EXISTS idx_governance_observations_source_order
+     ON governance_observations(rollout_row_id, source_order)`,
+    `CREATE UNIQUE INDEX IF NOT EXISTS idx_governance_observations_physical
+     ON governance_observations(transcript_record_key) WHERE transcript_record_key IS NOT NULL`,
+    `CREATE INDEX IF NOT EXISTS idx_governance_observations_rollout_turn
+     ON governance_observations(rollout_row_id, host_turn_id)`,
+    `CREATE INDEX IF NOT EXISTS idx_governance_observations_retention
+     ON governance_observations(retention_class, observed_at)`,
+    `CREATE TABLE IF NOT EXISTS governance_transcript_checkpoints (
+    host_kind TEXT NOT NULL,
+    rollout_identity TEXT NOT NULL,
+    byte_offset INTEGER NOT NULL,
+    last_ordinal INTEGER NOT NULL,
+    cli_version TEXT,
+    root_session_id TEXT NOT NULL,
+    incomplete_tail INTEGER NOT NULL DEFAULT 0,
+    last_degradation_reason TEXT,
+    last_degradation_ordinal INTEGER,
+    updated_at TEXT NOT NULL,
+    PRIMARY KEY (host_kind, rollout_identity)
+  )`,
+    `CREATE TABLE IF NOT EXISTS governance_pending_promotion_tails (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    rollout_row_id INTEGER NOT NULL,
+    host_kind TEXT NOT NULL,
+    rollout_identity TEXT NOT NULL,
+    trigger_logical_key TEXT NOT NULL,
+    pain_ref TEXT NOT NULL,
+    state TEXT NOT NULL,
+    created_at TEXT NOT NULL,
+    completed_at TEXT,
+    stale_at TEXT,
+    UNIQUE(rollout_row_id, trigger_logical_key, pain_ref)
+  )`,
+    `CREATE INDEX IF NOT EXISTS idx_governance_pending_tails_state
+     ON governance_pending_promotion_tails(state, created_at)`,
+];
+/** Column additions after v1 (dev databases created before the source-order fix). */
+const V2_ADDED_COLUMNS = [
+    { table: 'governance_observations', name: 'source_order', type: 'INTEGER' },
+    { table: 'governance_observations', name: 'source_ordinal', type: 'INTEGER' },
+];
+function ensureGovernanceObservationSchema(db) {
+    db.transaction(() => {
+        for (const statement of CREATE_STATEMENTS)
+            db.exec(statement);
+        for (const column of V2_ADDED_COLUMNS) {
+            try {
+                db.exec(`ALTER TABLE ${column.table} ADD COLUMN ${column.name} ${column.type}`);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                if (!message.includes('duplicate column name'))
+                    throw error;
+            }
+        }
+        const row = db.prepare('SELECT version FROM governance_observation_schema_version LIMIT 1').get();
+        const current = isRecord(row) ? own(row, 'version') : undefined;
+        if (typeof current !== 'number') {
+            db.prepare('INSERT INTO governance_observation_schema_version (version) VALUES (?)').run(GOVERNANCE_OBSERVATION_SCHEMA_VERSION);
+        }
+        else if (current < GOVERNANCE_OBSERVATION_SCHEMA_VERSION) {
+            db.prepare('UPDATE governance_observation_schema_version SET version = ?').run(GOVERNANCE_OBSERVATION_SCHEMA_VERSION);
+        }
+    })();
+}
+function openStore(workspaceDir, factory) {
+    const dbPath = path.join(workspaceDir, '.state', 'trajectory.db');
+    if (!fs.existsSync(dbPath)) {
+        return { ok: false, reason: 'trajectory_db_not_found', nextAction: 'initialize the selected PD workspace (pd runtime init) before enabling conversation ingestion' };
+    }
+    try {
+        const db = factory ? factory(dbPath) : new Database(dbPath);
+        db.pragma('busy_timeout = 5000');
+        db.pragma('journal_mode = WAL');
+        ensureGovernanceObservationSchema(db);
+        return { db, close: () => { try {
+                db.close();
+            }
+            catch { /* write result already determined */ } } };
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message.slice(0, 200) : String(error).slice(0, 200);
+        return { ok: false, reason: `trajectory_database_unavailable:${detail}`, nextAction: 'inspect or repair the selected PD trajectory database' };
+    }
+}
+function rowField(row, key) {
+    return isRecord(row) ? own(row, key) : undefined;
+}
+function upsertRollout(db, input, now) {
+    const existing = db.prepare('SELECT id FROM governance_rollouts WHERE host_kind = ? AND rollout_identity = ?').get(input.hostKind, input.rolloutIdentity);
+    const existingId = rowField(existing, 'id');
+    if (typeof existingId === 'number') {
+        db.prepare('UPDATE governance_rollouts SET root_session_id = ?, parent_rollout_id = COALESCE(?, parent_rollout_id), agent_identity = COALESCE(?, agent_identity), agent_depth = COALESCE(?, agent_depth), updated_at = ? WHERE id = ?')
+            .run(input.rootSessionId, input.parentRolloutIdentity ?? null, input.agentIdentity ?? null, input.agentDepth ?? null, now, existingId);
+        return existingId;
+    }
+    const result = db.prepare('INSERT INTO governance_rollouts (host_kind, rollout_identity, root_session_id, parent_rollout_id, agent_identity, agent_depth, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)')
+        .run(input.hostKind, input.rolloutIdentity, input.rootSessionId, input.parentRolloutIdentity ?? null, boundedString(input.agentIdentity, MAX_TEXT_BOUND), input.agentDepth ?? null, now, now);
+    return Number(result.lastInsertRowid);
+}
+function applyObservation({ db, rolloutRowId, input, workspaceDir }) {
+    const existing = db.prepare('SELECT * FROM governance_observations WHERE logical_key = ?').get(input.logicalObservationKey);
+    if (!isRecord(existing)) {
+        // Physical replay guard: the same transcript record decoded twice (crash
+        // before checkpoint, or a re-invoked hook) must not contribute twice.
+        if (input.transcriptRecordKey !== undefined) {
+            const physical = db.prepare('SELECT id FROM governance_observations WHERE transcript_record_key = ?').get(input.transcriptRecordKey);
+            if (isRecord(physical))
+                return { disposition: 'duplicate' };
+        }
+        const sanitizedText = input.visibleText !== undefined ? sanitizeString(input.visibleText, workspaceDir) : null;
+        const facts = input.toolFacts !== undefined ? safeJson({ facts: sanitizeValue(input.toolFacts, 0, workspaceDir) }) : null;
+        db.prepare(`INSERT INTO governance_observations
+      (rollout_row_id, host_kind, rollout_identity, root_session_id, host_turn_id, kind, logical_key, transcript_record_key, source_order, source_ordinal, assistant_item_id, phase, tool_use_id, transcript_tool_call_id, visible_text, sanitized_tool_facts_json, source, completeness, retention_class, observed_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'operational', ?)`)
+            .run(rolloutRowId, input.hostKind, input.rolloutIdentity, input.rootSessionId, input.hostTurnId, input.kind, input.logicalObservationKey, input.transcriptRecordKey ?? null, input.recordByteStart ?? null, input.recordOrdinal ?? null, boundedString(input.assistantItemId, MAX_TEXT_BOUND), boundedString(input.phase, MAX_TEXT_BOUND) ?? null, boundedString(input.toolUseId, MAX_TEXT_BOUND), boundedString(input.transcriptToolCallId, MAX_TEXT_BOUND), sanitizedText, facts, input.source, input.completeness, input.observedAt);
+        return { disposition: 'inserted' };
+    }
+    const existingId = rowField(existing, 'id');
+    const existingText = rowField(existing, 'visible_text');
+    // Source precedence (SPEC §10): user rows created live are enriched by the
+    // transcript with identity/ordering; tool rows created live are enriched or
+    // no-op'd by tool_use_id; assistant content comes only from the transcript.
+    // A user content mismatch for one logical key is a lineage conflict: keep
+    // the first committed content, mark partial, and stop checkpoint advance at
+    // the conflicting record — never overwrite silently.
+    if (input.kind === 'user_turn'
+        && input.source === 'transcript'
+        && input.visibleText !== undefined
+        && typeof existingText === 'string'
+        && sanitizeString(input.visibleText, workspaceDir) !== existingText) {
+        db.prepare("UPDATE governance_observations SET completeness = 'partial' WHERE id = ?").run(existingId);
+        return { disposition: 'conflict', stopByteStart: input.recordByteStart };
+    }
+    const updates = [];
+    const values = [];
+    const fill = (column, value) => {
+        const current = rowField(existing, column);
+        if ((current === null || current === undefined) && value !== null && value !== undefined) {
+            updates.push(`${column} = ?`);
+            values.push(value);
+        }
+    };
+    fill('transcript_record_key', input.transcriptRecordKey ?? null);
+    // Transcript replay enriches the live row with its real transcript position
+    // (PR #1455 review P1): all ordering logic reads source_order, so a live row
+    // must gain it the moment the transcript catch-up converges the same event.
+    fill('source_order', input.recordByteStart);
+    fill('source_ordinal', input.recordOrdinal);
+    fill('assistant_item_id', boundedString(input.assistantItemId, MAX_TEXT_BOUND));
+    fill('phase', boundedString(input.phase, MAX_TEXT_BOUND));
+    fill('tool_use_id', boundedString(input.toolUseId, MAX_TEXT_BOUND));
+    fill('transcript_tool_call_id', boundedString(input.transcriptToolCallId, MAX_TEXT_BOUND));
+    fill('visible_text', input.visibleText !== undefined ? sanitizeString(input.visibleText, workspaceDir) : null);
+    fill('sanitized_tool_facts_json', input.toolFacts !== undefined ? safeJson({ facts: sanitizeValue(input.toolFacts, 0, workspaceDir) }) : null);
+    const existingCompleteness = rowField(existing, 'completeness');
+    if (existingCompleteness === 'partial' && input.completeness === 'complete') {
+        updates.push('completeness = ?');
+        values.push('complete');
+    }
+    if (updates.length === 0)
+        return { disposition: 'duplicate' };
+    updates.push('source = ?');
+    values.push(input.source);
+    values.push(existingId);
+    db.prepare(`UPDATE governance_observations SET ${updates.join(', ')} WHERE id = ?`).run(...values);
+    return { disposition: 'enriched' };
+}
+function expireRows(db, ids, expiry) {
+    const { now, klass } = expiry;
+    if (ids.length === 0)
+        return;
+    const chunks = [];
+    for (let index = 0; index < ids.length; index += 200)
+        chunks.push(ids.slice(index, index + 200));
+    for (const chunk of chunks) {
+        const placeholders = chunk.map(() => '?').join(',');
+        db.prepare(`UPDATE governance_observations SET visible_text = NULL, sanitized_tool_facts_json = NULL, retention_class = ?, expired_at = ? WHERE id IN (${placeholders}) AND retention_class = 'operational'`)
+            .run(klass, now, ...chunk);
+    }
+}
+function listTurnsInSourceOrder(db, rolloutRowId) {
+    const rows = db.prepare(`SELECT host_turn_id, MIN(source_order) AS turn_order, MIN(id) AS arrival
+    FROM governance_observations
+    WHERE rollout_row_id = ? AND retention_class = 'operational'
+    GROUP BY host_turn_id
+    ORDER BY (MIN(source_order) IS NULL) ASC, MIN(source_order) ASC, MIN(id) ASC`).all(rolloutRowId);
+    return rows.map((row) => ({
+        hostTurnId: String(rowField(row, 'host_turn_id')),
+        turnOrder: typeof rowField(row, 'turn_order') === 'number' ? rowField(row, 'turn_order') : null,
+    }));
+}
+function turnObservationIds(db, rolloutRowId, hostTurnId) {
+    const rows = db.prepare("SELECT id FROM governance_observations WHERE rollout_row_id = ? AND host_turn_id = ? AND retention_class = 'operational'")
+        .all(rolloutRowId, hostTurnId);
+    return rows.map((row) => Number(rowField(row, 'id'))).filter((id) => Number.isInteger(id));
+}
+function pruneRetention(db, rolloutRowId, now) {
+    const nowIso = now.toISOString();
+    // Age bound: global, bounded single statements over the retention index.
+    db.prepare(`UPDATE governance_observations SET visible_text = NULL, sanitized_tool_facts_json = NULL, retention_class = 'expired', expired_at = ?
+    WHERE retention_class = 'operational' AND observed_at < ?`)
+        .run(nowIso, new Date(now.getTime() - GOVERNANCE_RETENTION_MAX_AGE_MS).toISOString());
+    // Turn bound: per ingested rollout, keep the latest N conversational turns
+    // in canonical source order (live-only turns count as newest).
+    if (rolloutRowId === null)
+        return;
+    const turns = listTurnsInSourceOrder(db, rolloutRowId);
+    if (turns.length <= GOVERNANCE_RETENTION_MAX_TURNS)
+        return;
+    const expiredIds = [];
+    for (const turn of turns.slice(0, turns.length - GOVERNANCE_RETENTION_MAX_TURNS)) {
+        expiredIds.push(...turnObservationIds(db, rolloutRowId, turn.hostTurnId));
+    }
+    expireRows(db, expiredIds, { now: nowIso, klass: 'expired' });
+}
+function completePendingTails(db, rolloutRowId, now) {
+    const pending = db.prepare("SELECT * FROM governance_pending_promotion_tails WHERE rollout_row_id = ? AND state = 'pending'").all(rolloutRowId);
+    let completed = 0;
+    for (const tail of pending) {
+        const triggerKey = rowField(tail, 'trigger_logical_key');
+        if (typeof triggerKey !== 'string')
+            continue;
+        const triggerRow = db.prepare('SELECT * FROM governance_observations WHERE logical_key = ?').get(triggerKey);
+        if (!isRecord(triggerRow))
+            continue;
+        const triggerOrder = rowField(triggerRow, 'source_order');
+        if (typeof triggerOrder !== 'number')
+            continue; // not yet positioned by the transcript replay
+        // The next completed assistant turn: the earliest final-answer assistant
+        // observation AFTER the trigger in transcript source order.
+        const next = db.prepare(`SELECT id FROM governance_observations
+      WHERE rollout_row_id = ? AND kind = 'assistant_turn' AND phase = 'final_answer' AND completeness = 'complete' AND source_order > ?
+      ORDER BY source_order LIMIT 1`).get(rolloutRowId, triggerOrder);
+        const nextId = rowField(next, 'id');
+        if (typeof nextId !== 'number')
+            continue;
+        db.prepare("UPDATE governance_observations SET retention_class = 'promoted', promoted_at = ?, promotion_ref = COALESCE(promotion_ref, ?) WHERE id = ? AND retention_class != 'promoted'")
+            .run(now, rowField(tail, 'pain_ref'), nextId);
+        db.prepare("UPDATE governance_pending_promotion_tails SET state = 'completed', completed_at = ? WHERE id = ?").run(now, rowField(tail, 'id'));
+        completed += 1;
+    }
+    return completed;
+}
+function expireStalePendingTails(db, now) {
+    db.prepare("UPDATE governance_pending_promotion_tails SET state = 'stale', stale_at = ? WHERE state = 'pending' AND created_at < ?")
+        .run(now.toISOString(), new Date(now.getTime() - GOVERNANCE_PENDING_TAIL_STALE_MS).toISOString());
+}
+export function ingestGovernanceObservations(input) {
+    const opened = openStore(input.workspaceDir, input.databaseFactory);
+    if (!('db' in opened))
+        return { ok: false, reason: opened.reason, nextAction: opened.nextAction, inserted: 0, enriched: 0, duplicates: 0, checkpointCommitted: false, warnings: [] };
+    const { db, close } = opened;
+    const now = (input.now ?? new Date()).toISOString();
+    const warnings = [];
+    try {
+        let inserted = 0;
+        let enriched = 0;
+        let duplicates = 0;
+        let conflictStop;
+        let conflictKey = '';
+        const result = db.transaction(() => {
+            let rolloutRowId = null;
+            if (input.rollout !== undefined) {
+                rolloutRowId = upsertRollout(db, input.rollout, now);
+            }
+            for (const observation of input.observations) {
+                rolloutRowId = upsertRollout(db, observation, now);
+                const outcome = applyObservation({ db, rolloutRowId, input: observation, workspaceDir: input.workspaceDir });
+                if (outcome.disposition === 'inserted')
+                    inserted += 1;
+                else if (outcome.disposition === 'enriched')
+                    enriched += 1;
+                else if (outcome.disposition === 'duplicate')
+                    duplicates += 1;
+                else if (outcome.disposition === 'conflict') {
+                    conflictStop = outcome.stopByteStart;
+                    conflictKey = observation.logicalObservationKey;
+                    return 'conflict';
+                }
+            }
+            // Durable checkpoint: advances only in the transaction that commits its
+            // decoded observations (SPEC §8) — including deltas that contained only
+            // skipped or unknown records. A conflict or malformed record stops the
+            // advance at the offending record so it is re-examined, never skipped.
+            if (input.checkpoint !== undefined) {
+                const degradations = input.degradations ?? [];
+                const [firstDegradation] = degradations;
+                const stopOffset = conflictStop;
+                const byteOffset = stopOffset !== undefined && stopOffset < input.checkpoint.byteOffset ? stopOffset : input.checkpoint.byteOffset;
+                const lastDegradation = conflictKey
+                    ? { reason: 'logical_key_content_conflict', ordinal: null }
+                    : firstDegradation
+                        ? { reason: firstDegradation.reason, ordinal: firstDegradation.ordinal ?? null }
+                        : null;
+                db.prepare(`INSERT INTO governance_transcript_checkpoints
+            (host_kind, rollout_identity, byte_offset, last_ordinal, cli_version, root_session_id, incomplete_tail, last_degradation_reason, last_degradation_ordinal, updated_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            ON CONFLICT(host_kind, rollout_identity) DO UPDATE SET
+              byte_offset = excluded.byte_offset, last_ordinal = excluded.last_ordinal, cli_version = COALESCE(excluded.cli_version, cli_version),
+              root_session_id = excluded.root_session_id, incomplete_tail = excluded.incomplete_tail,
+              last_degradation_reason = excluded.last_degradation_reason, last_degradation_ordinal = excluded.last_degradation_ordinal, updated_at = excluded.updated_at`)
+                    .run(input.checkpoint.hostKind, input.checkpoint.rolloutIdentity, byteOffset, input.checkpoint.lastOrdinal, input.checkpoint.cliVersion ?? null, input.checkpoint.rootSessionId, input.checkpoint.incompleteTail ? 1 : 0, lastDegradation?.reason ?? null, lastDegradation?.ordinal ?? null, now);
+            }
+            // Marker semantics: compaction replaces logical history (tombstone every
+            // unpromoted observation recorded before the marker); rollback truncates
+            // the last N logical turns. Physical records remain; bodies must not.
+            if (input.compactionTimestamp && rolloutRowId !== null) {
+                const stale = db.prepare(`SELECT id FROM governance_observations WHERE rollout_row_id = ? AND retention_class = 'operational' AND observed_at <= ?`)
+                    .all(rolloutRowId, input.compactionTimestamp);
+                expireRows(db, stale.map((row) => Number(rowField(row, 'id'))).filter((id) => Number.isInteger(id)), { now, klass: 'rolled_back' });
+                warnings.push('compaction_marker_applied');
+            }
+            if (Array.isArray(input.rollbackTurns) && input.rollbackTurns.length > 0 && rolloutRowId !== null) {
+                let rolledBackTurns = 0;
+                for (const markerTurns of input.rollbackTurns) {
+                    if (typeof markerTurns !== 'number' || markerTurns <= 0)
+                        continue;
+                    // The LAST N logical turns in canonical source order (live-only
+                    // turns are the newest; replayed turns order by transcript bytes).
+                    const turns = listTurnsInSourceOrder(db, rolloutRowId).slice(-markerTurns);
+                    const ids = [];
+                    for (const turn of turns) {
+                        ids.push(...turnObservationIds(db, rolloutRowId, turn.hostTurnId));
+                    }
+                    expireRows(db, ids, { now, klass: 'rolled_back' });
+                    rolledBackTurns += markerTurns;
+                }
+                warnings.push(`rollback_marker_applied:${rolledBackTurns}`);
+            }
+            if (rolloutRowId !== null)
+                completePendingTails(db, rolloutRowId, now);
+            expireStalePendingTails(db, new Date(now));
+            pruneRetention(db, rolloutRowId, new Date(now));
+            return 'committed';
+        })();
+        if (result === 'conflict') {
+            return {
+                ok: false, reason: 'logical_key_content_conflict', nextAction: 'the first committed content was preserved and the observation is marked partial; run the audited quarantine/recovery command once available (Slice D) or re-ingest from a fresh rollout',
+                inserted, enriched, duplicates, checkpointCommitted: false, warnings: [`conflict:${conflictKey}`],
+            };
+        }
+        return { ok: true, inserted, enriched, duplicates, checkpointCommitted: input.checkpoint !== undefined, warnings };
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message.slice(0, 200) : String(error).slice(0, 200);
+        return { ok: false, reason: `governance_write_failed:${detail}`, nextAction: 'inspect the workspace trajectory database and retry; nothing was partially committed', inserted: 0, enriched: 0, duplicates: 0, checkpointCommitted: false, warnings: [] };
+    }
+    finally {
+        close();
+    }
+}
+export function readGovernanceCheckpoint(args) {
+    const { workspaceDir, hostKind, rolloutIdentity, databaseFactory } = args;
+    const opened = openStore(workspaceDir, databaseFactory);
+    if (!('db' in opened))
+        return opened;
+    const { db, close } = opened;
+    try {
+        const row = db.prepare('SELECT * FROM governance_transcript_checkpoints WHERE host_kind = ? AND rollout_identity = ?').get(hostKind, rolloutIdentity);
+        if (!isRecord(row))
+            return null;
+        return {
+            hostKind: String(rowField(row, 'host_kind')),
+            rolloutIdentity: String(rowField(row, 'rollout_identity')),
+            byteOffset: Number(rowField(row, 'byte_offset')),
+            lastOrdinal: Number(rowField(row, 'last_ordinal')),
+            cliVersion: typeof rowField(row, 'cli_version') === 'string' ? rowField(row, 'cli_version') : null,
+            rootSessionId: String(rowField(row, 'root_session_id')),
+            incompleteTail: rowField(row, 'incomplete_tail') === 1,
+            lastDegradationReason: typeof rowField(row, 'last_degradation_reason') === 'string' ? rowField(row, 'last_degradation_reason') : null,
+            lastDegradationOrdinal: typeof rowField(row, 'last_degradation_ordinal') === 'number' ? rowField(row, 'last_degradation_ordinal') : null,
+            updatedAt: String(rowField(row, 'updated_at')),
+        };
+    }
+    finally {
+        close();
+    }
+}
+export function listGovernanceObservations(input) {
+    const opened = openStore(input.workspaceDir, input.databaseFactory);
+    if (!('db' in opened))
+        return opened;
+    const { db, close } = opened;
+    try {
+        const conditions = [];
+        const values = [];
+        if (input.rolloutIdentity !== undefined) {
+            conditions.push('rollout_identity = ?');
+            values.push(input.rolloutIdentity);
+        }
+        if (input.retentionClass !== undefined) {
+            conditions.push('retention_class = ?');
+            values.push(input.retentionClass);
+        }
+        const where = conditions.length > 0 ? ` WHERE ${conditions.join(' AND ')}` : '';
+        const limit = Math.min(Math.max(input.limit ?? 500, 1), 2000);
+        const rows = db.prepare(`SELECT * FROM governance_observations${where} ORDER BY id LIMIT ?`).all(...values, limit);
+        const observations = rows.map((row) => ({
+            id: Number(rowField(row, 'id')),
+            rolloutIdentity: String(rowField(row, 'rollout_identity')),
+            rootSessionId: String(rowField(row, 'root_session_id')),
+            hostTurnId: String(rowField(row, 'host_turn_id')),
+            kind: rowField(row, 'kind'),
+            logicalKey: String(rowField(row, 'logical_key')),
+            transcriptRecordKey: typeof rowField(row, 'transcript_record_key') === 'string' ? rowField(row, 'transcript_record_key') : null,
+            sourceOrder: typeof rowField(row, 'source_order') === 'number' ? rowField(row, 'source_order') : null,
+            sourceOrdinal: typeof rowField(row, 'source_ordinal') === 'number' ? rowField(row, 'source_ordinal') : null,
+            assistantItemId: typeof rowField(row, 'assistant_item_id') === 'string' ? rowField(row, 'assistant_item_id') : null,
+            phase: typeof rowField(row, 'phase') === 'string' ? rowField(row, 'phase') : null,
+            toolUseId: typeof rowField(row, 'tool_use_id') === 'string' ? rowField(row, 'tool_use_id') : null,
+            transcriptToolCallId: typeof rowField(row, 'transcript_tool_call_id') === 'string' ? rowField(row, 'transcript_tool_call_id') : null,
+            visibleText: typeof rowField(row, 'visible_text') === 'string' ? rowField(row, 'visible_text') : null,
+            sanitizedToolFactsJson: typeof rowField(row, 'sanitized_tool_facts_json') === 'string' ? rowField(row, 'sanitized_tool_facts_json') : null,
+            source: rowField(row, 'source'),
+            completeness: rowField(row, 'completeness'),
+            retentionClass: rowField(row, 'retention_class'),
+            observedAt: String(rowField(row, 'observed_at')),
+            promotionRef: typeof rowField(row, 'promotion_ref') === 'string' ? rowField(row, 'promotion_ref') : null,
+        }));
+        return { ok: true, observations };
+    }
+    finally {
+        close();
+    }
+}
+class PromotionMissingError extends Error {
+    reason;
+    nextAction;
+    constructor(reason, nextAction) {
+        super(reason);
+        this.reason = reason;
+        this.nextAction = nextAction;
+        this.name = 'PromotionMissingError';
+    }
+}
+export function promoteGovernanceEvidence(input) {
+    const opened = openStore(input.workspaceDir, input.databaseFactory);
+    if (!('db' in opened))
+        return { ok: false, reason: opened.reason, nextAction: opened.nextAction };
+    const { db, close } = opened;
+    const now = (input.now ?? new Date()).toISOString();
+    const warnings = [];
+    try {
+        let promoted = 0;
+        let tailState = 'pending';
+        db.transaction(() => {
+            const rollout = db.prepare('SELECT id FROM governance_rollouts WHERE host_kind = ? AND rollout_identity = ?').get(input.hostKind, input.rolloutIdentity);
+            const rolloutRowId = rowField(rollout, 'id');
+            if (typeof rolloutRowId !== 'number')
+                throw new PromotionMissingError('rollout_not_found', 'ingest the rollout before promoting evidence around it');
+            // Idempotency: a completed or still-pending tail for the same trigger +
+            // pain reference is a no-op replay (crash, restart, duplicate delivery).
+            const existingTail = db.prepare('SELECT * FROM governance_pending_promotion_tails WHERE rollout_row_id = ? AND trigger_logical_key = ? AND pain_ref = ?')
+                .get(rolloutRowId, input.triggerLogicalKey, input.painRef);
+            if (isRecord(existingTail)) {
+                const state = rowField(existingTail, 'state');
+                if (state === 'completed') {
+                    tailState = 'completed';
+                    return;
+                }
+                if (state === 'pending') {
+                    // Recovery invariant: the tail may already be satisfiable now.
+                    const completedNow = completePendingTails(db, rolloutRowId, now);
+                    if (completedNow > 0)
+                        tailState = 'completed';
+                    return;
+                }
+                // state === 'stale': a diagnosable terminal state — do not silently
+                // re-arm; the caller must start a new promotion with a new reference.
+                throw new PromotionMissingError('promotion_tail_stale', 'the pending promotion tail expired; create a new promotion with a new pain reference');
+            }
+            const triggerRow = db.prepare('SELECT * FROM governance_observations WHERE logical_key = ? AND rollout_row_id = ?').get(input.triggerLogicalKey, rolloutRowId);
+            if (!isRecord(triggerRow))
+                throw new PromotionMissingError('trigger_not_found', 'the triggering observation must be ingested before promotion');
+            const triggerId = rowField(triggerRow, 'id');
+            const triggerOrder = typeof rowField(triggerRow, 'source_order') === 'number' ? rowField(triggerRow, 'source_order') : null;
+            const promoteIds = (ids) => {
+                for (const id of ids) {
+                    db.prepare("UPDATE governance_observations SET retention_class = 'promoted', promoted_at = ?, promotion_ref = COALESCE(promotion_ref, ?) WHERE id = ? AND retention_class != 'promoted'")
+                        .run(now, input.painRef, id);
+                    promoted += 1;
+                }
+            };
+            // ≤12 preceding visible turns: the turns immediately BEFORE the
+            // trigger's own turn in canonical source order (transcript byte order;
+            // a live trigger not yet replayed positions after everything observed
+            // so far, which is exactly its real position — nothing newer exists).
+            const turns = listTurnsInSourceOrder(db, rolloutRowId);
+            const triggerTurnIndex = turns.findIndex((turn) => {
+                const ids = db.prepare('SELECT id FROM governance_observations WHERE rollout_row_id = ? AND host_turn_id = ? AND logical_key = ?')
+                    .all(rolloutRowId, turn.hostTurnId, input.triggerLogicalKey);
+                return ids.length > 0;
+            });
+            const precedingStart = triggerTurnIndex > 0 ? Math.max(0, triggerTurnIndex - GOVERNANCE_PROMOTION_PRECEDING_TURNS) : -1;
+            const preceding = triggerTurnIndex > 0 ? turns.slice(precedingStart, triggerTurnIndex) : [];
+            for (const turn of preceding) {
+                promoteIds(turnObservationIds(db, rolloutRowId, turn.hostTurnId));
+            }
+            promoteIds([Number(triggerId)]);
+            if (triggerOrder !== null) {
+                // Next completed assistant turn: the earliest final-answer assistant
+                // AFTER the trigger in transcript source order. When the trigger has
+                // no transcript position yet, the durable pending tail below resolves
+                // once the replay enriches it (completePendingTails re-checks).
+                const next = db.prepare(`SELECT id FROM governance_observations
+          WHERE rollout_row_id = ? AND kind = 'assistant_turn' AND phase = 'final_answer' AND completeness = 'complete' AND source_order > ?
+          ORDER BY source_order LIMIT 1`).get(rolloutRowId, triggerOrder);
+                const nextId = rowField(next, 'id');
+                if (typeof nextId === 'number') {
+                    promoteIds([nextId]);
+                    tailState = 'completed';
+                }
+            }
+            if (tailState !== 'completed') {
+                db.prepare(`INSERT INTO governance_pending_promotion_tails (rollout_row_id, host_kind, rollout_identity, trigger_logical_key, pain_ref, state, created_at)
+          VALUES (?, ?, ?, ?, ?, 'pending', ?)`)
+                    .run(rolloutRowId, input.hostKind, input.rolloutIdentity, input.triggerLogicalKey, input.painRef, now);
+                tailState = 'pending';
+                warnings.push('pending_next_assistant_tail');
+            }
+        })();
+        return { ok: true, promoted, tailState, warnings };
+    }
+    catch (error) {
+        if (error instanceof PromotionMissingError)
+            return { ok: false, reason: error.reason, nextAction: error.nextAction };
+        const detail = error instanceof Error ? error.message.slice(0, 200) : String(error).slice(0, 200);
+        return { ok: false, reason: `governance_write_failed:${detail}`, nextAction: 'inspect the workspace trajectory database and retry; nothing was partially committed' };
+    }
+    finally {
+        close();
+    }
+}

package/host-runtime/dist/index.d.ts

@@ -8,7 +8,13 @@ export * from './pd-config.js';
 export * from './production-rulehost-gate.js';
 export * from './rule-implementation-runtime.js';
 export * from './production-pain-evidence.js';
+export * from './governance-observation-store.js';
 export * from './host-liveness-contract.js';
+export * from './product-telemetry/consent-store.js';
+export * from './product-telemetry/eligibility.js';
+export * from './product-telemetry/exporter.js';
+export * from './product-telemetry/milestone-readers.js';
+export * from './product-telemetry/service.js';
 export declare const HOST_RUNTIME_ROUTES: readonly ['before_prompt_build', 'before_tool_call', 'after_tool_call'];
 export type HostRuntimeRoute = (typeof HOST_RUNTIME_ROUTES)[number];
 export type HostRuntimePort = (event: HostEvent) => HostEventResult | Promise<HostEventResult>;