@haaaiawd/second-nature 0.1.18 → 0.1.19

package/runtime/observability/services/runtime-decision-recorder.js

@@ -1,94 +1,94 @@
-/**
- * Runtime Decision Recorder (T1.2.3).
- *
- * Core logic: after a workspace `runHeartbeatCycle` completes, persist two rows that
- * `loadStatus` already filters on, so operator status stops returning `unknown` for
- * `rhythm.mode` / `runtime.serviceStatus` once the runtime has executed at least once.
- *  - `decision_ledger` row via `DecisionLedger.recordHeartbeatDecision()` with
- *    `traceId` prefix `sn-runtime-` (matches `INTERNAL_RUNTIME_TRACE_PREFIX`).
- *  - `execution_attempts` row via `ExecutionTelemetry.startAttempt` +
- *    `completeAttempt` with `platformId === "second-nature-runtime"` (matches
- *    `INTERNAL_RUNTIME_PLATFORM_ID`).
- *
- * Boundaries:
- *  - Recorder failure must NOT break the heartbeat surface response — caller wraps with try/catch.
- *  - Carrier-only / probe-only / runtime-unavailable paths do NOT invoke this recorder
- *    (their semantics intentionally remain "unknown" until a full-runtime turn happens).
- *  - This is a derived observability writer; it is not the canonical decision producer
- *    (control-plane keeps that contract). It exists to close the read-side aggregation gap.
- */
-import { randomUUID } from "node:crypto";
-import { DecisionLedger } from "./decision-ledger.js";
-import { ExecutionTelemetry } from "./execution-telemetry.js";
-export const RUNTIME_DECISION_TRACE_PREFIX = "sn-runtime-";
-export const RUNTIME_INTERNAL_PLATFORM_ID = "second-nature-runtime";
-const RUNTIME_INTERNAL_CAPABILITY = "runtime.heartbeat";
-const RUNTIME_INTERNAL_CHANNEL = "internal";
-export function createRuntimeDecisionRecorder(observabilityDb, overrides = {}) {
-    const ledger = overrides.ledger ?? new DecisionLedger(observabilityDb);
-    const telemetry = overrides.telemetry ?? new ExecutionTelemetry(observabilityDb);
-    return {
-        async recordHeartbeatCycle({ cycle, signal, rhythmMode }) {
-            const timestamp = typeof signal.payload.timestamp === "string" && signal.payload.timestamp.trim().length > 0
-                ? signal.payload.timestamp
-                : new Date().toISOString();
-            const uniqueId = randomUUID();
-            const traceId = `${RUNTIME_DECISION_TRACE_PREFIX}${cycle.scope}-${cycle.status}-${uniqueId}`;
-            const decisionId = `decision-runtime-${uniqueId}`;
-            const tickId = `tick-runtime-${uniqueId}`;
-            const event = {
-                id: decisionId,
-                tickId,
-                traceId,
-                runtimeScope: cycle.scope,
-                triggerSource: signal.trigger,
-                decisionStatus: mapCycleStatus(cycle.status),
-                reasons: cycle.reasons,
-                intentId: cycle.selectedIntentId,
-                mode: rhythmMode ?? "active",
-                createdAt: timestamp,
-            };
-            await ledger.recordHeartbeatDecision(event);
-            const attemptId = await telemetry.startAttempt({
-                traceId,
-                decisionId,
-                intentId: cycle.selectedIntentId ?? `${RUNTIME_INTERNAL_PLATFORM_ID}-tick`,
-                platformId: RUNTIME_INTERNAL_PLATFORM_ID,
-                capability: RUNTIME_INTERNAL_CAPABILITY,
-                channel: RUNTIME_INTERNAL_CHANNEL,
-                startedAt: timestamp,
-            });
-            const status = isFailureCycle(cycle.status) ? "failed" : "succeeded";
-            const failureClass = status === "failed" ? cycleStatusFailureClass(cycle.status) : undefined;
-            await telemetry.completeAttempt(traceId, status, undefined, failureClass);
-            return { traceId, decisionId, attemptId };
-        },
-    };
-}
-function mapCycleStatus(status) {
-    switch (status) {
-        case "intent_selected":
-            return "intent_selected";
-        case "denied":
-            return "denied";
-        case "deferred":
-            return "deferred";
-        case "delivery_unavailable":
-            return "delivery_unavailable";
-        case "runtime_carrier_only":
-            return "runtime_carrier_only";
-        case "heartbeat_ok":
-        default:
-            return "heartbeat_ok";
-    }
-}
-function isFailureCycle(status) {
-    return status === "delivery_unavailable" || status === "denied";
-}
-function cycleStatusFailureClass(status) {
-    if (status === "delivery_unavailable")
-        return "delivery_unavailable";
-    if (status === "denied")
-        return "decision_denied";
-    return undefined;
-}
+/**
+ * Runtime Decision Recorder (T1.2.3).
+ *
+ * Core logic: after a workspace `runHeartbeatCycle` completes, persist two rows that
+ * `loadStatus` already filters on, so operator status stops returning `unknown` for
+ * `rhythm.mode` / `runtime.serviceStatus` once the runtime has executed at least once.
+ *  - `decision_ledger` row via `DecisionLedger.recordHeartbeatDecision()` with
+ *    `traceId` prefix `sn-runtime-` (matches `INTERNAL_RUNTIME_TRACE_PREFIX`).
+ *  - `execution_attempts` row via `ExecutionTelemetry.startAttempt` +
+ *    `completeAttempt` with `platformId === "second-nature-runtime"` (matches
+ *    `INTERNAL_RUNTIME_PLATFORM_ID`).
+ *
+ * Boundaries:
+ *  - Recorder failure must NOT break the heartbeat surface response — caller wraps with try/catch.
+ *  - Carrier-only / probe-only / runtime-unavailable paths do NOT invoke this recorder
+ *    (their semantics intentionally remain "unknown" until a full-runtime turn happens).
+ *  - This is a derived observability writer; it is not the canonical decision producer
+ *    (control-plane keeps that contract). It exists to close the read-side aggregation gap.
+ */
+import { randomUUID } from "node:crypto";
+import { DecisionLedger } from "./decision-ledger.js";
+import { ExecutionTelemetry } from "./execution-telemetry.js";
+export const RUNTIME_DECISION_TRACE_PREFIX = "sn-runtime-";
+export const RUNTIME_INTERNAL_PLATFORM_ID = "second-nature-runtime";
+const RUNTIME_INTERNAL_CAPABILITY = "runtime.heartbeat";
+const RUNTIME_INTERNAL_CHANNEL = "internal";
+export function createRuntimeDecisionRecorder(observabilityDb, overrides = {}) {
+    const ledger = overrides.ledger ?? new DecisionLedger(observabilityDb);
+    const telemetry = overrides.telemetry ?? new ExecutionTelemetry(observabilityDb);
+    return {
+        async recordHeartbeatCycle({ cycle, signal, rhythmMode }) {
+            const timestamp = typeof signal.payload.timestamp === "string" && signal.payload.timestamp.trim().length > 0
+                ? signal.payload.timestamp
+                : new Date().toISOString();
+            const uniqueId = randomUUID();
+            const traceId = `${RUNTIME_DECISION_TRACE_PREFIX}${cycle.scope}-${cycle.status}-${uniqueId}`;
+            const decisionId = `decision-runtime-${uniqueId}`;
+            const tickId = `tick-runtime-${uniqueId}`;
+            const event = {
+                id: decisionId,
+                tickId,
+                traceId,
+                runtimeScope: cycle.scope,
+                triggerSource: signal.trigger,
+                decisionStatus: mapCycleStatus(cycle.status),
+                reasons: cycle.reasons,
+                intentId: cycle.selectedIntentId,
+                mode: rhythmMode ?? "active",
+                createdAt: timestamp,
+            };
+            await ledger.recordHeartbeatDecision(event);
+            const attemptId = await telemetry.startAttempt({
+                traceId,
+                decisionId,
+                intentId: cycle.selectedIntentId ?? `${RUNTIME_INTERNAL_PLATFORM_ID}-tick`,
+                platformId: RUNTIME_INTERNAL_PLATFORM_ID,
+                capability: RUNTIME_INTERNAL_CAPABILITY,
+                channel: RUNTIME_INTERNAL_CHANNEL,
+                startedAt: timestamp,
+            });
+            const status = isFailureCycle(cycle.status) ? "failed" : "succeeded";
+            const failureClass = status === "failed" ? cycleStatusFailureClass(cycle.status) : undefined;
+            await telemetry.completeAttempt(traceId, status, undefined, failureClass);
+            return { traceId, decisionId, attemptId };
+        },
+    };
+}
+function mapCycleStatus(status) {
+    switch (status) {
+        case "intent_selected":
+            return "intent_selected";
+        case "denied":
+            return "denied";
+        case "deferred":
+            return "deferred";
+        case "delivery_unavailable":
+            return "delivery_unavailable";
+        case "runtime_carrier_only":
+            return "runtime_carrier_only";
+        case "heartbeat_ok":
+        default:
+            return "heartbeat_ok";
+    }
+}
+function isFailureCycle(status) {
+    return status === "delivery_unavailable" || status === "denied";
+}
+function cycleStatusFailureClass(status) {
+    if (status === "delivery_unavailable")
+        return "delivery_unavailable";
+    if (status === "denied")
+        return "decision_denied";
+    return undefined;
+}

package/runtime/storage/bootstrap/native-sqlite-probe.d.ts

@@ -1,7 +1,7 @@
-export interface NativeSqliteProbeResult {
-    moduleLoadOk: boolean;
-    /** package version when load succeeds */
-    version?: string;
-    errorMessage?: string;
-}
-export declare function probeNativeSqliteLoad(): NativeSqliteProbeResult;
+export interface NativeSqliteProbeResult {
+    moduleLoadOk: boolean;
+    /** package version when load succeeds */
+    version?: string;
+    errorMessage?: string;
+}
+export declare function probeNativeSqliteLoad(): NativeSqliteProbeResult;

package/runtime/storage/bootstrap/native-sqlite-probe.js

@@ -1,28 +1,28 @@
-/**
- * Optional better-sqlite3 load probe (T4.1.4). Second Nature state DB currently uses sql.js only;
- * this probe records whether the native module can load for packaging / host diagnostics.
- */
-import { createRequire } from "node:module";
-const require = createRequire(import.meta.url);
-export function probeNativeSqliteLoad() {
-    try {
-        const Database = require("better-sqlite3");
-        const db = new Database(":memory:");
-        db.close();
-        let version;
-        try {
-            const pkg = require("better-sqlite3/package.json");
-            version = pkg.version;
-        }
-        catch {
-            version = undefined;
-        }
-        return { moduleLoadOk: true, version };
-    }
-    catch (error) {
-        return {
-            moduleLoadOk: false,
-            errorMessage: error instanceof Error ? error.message : String(error),
-        };
-    }
-}
+/**
+ * Optional better-sqlite3 load probe (T4.1.4). Second Nature state DB currently uses sql.js only;
+ * this probe records whether the native module can load for packaging / host diagnostics.
+ */
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+export function probeNativeSqliteLoad() {
+    try {
+        const Database = require("better-sqlite3");
+        const db = new Database(":memory:");
+        db.close();
+        let version;
+        try {
+            const pkg = require("better-sqlite3/package.json");
+            version = pkg.version;
+        }
+        catch {
+            version = undefined;
+        }
+        return { moduleLoadOk: true, version };
+    }
+    catch (error) {
+        return {
+            moduleLoadOk: false,
+            errorMessage: error instanceof Error ? error.message : String(error),
+        };
+    }
+}

package/runtime/storage/bootstrap/repair-gate.d.ts

@@ -1,17 +1,17 @@
-import type { StateDatabase } from "../db/index.js";
-import { createRepairAndBackupService, type RepairAndBackupOptions } from "../services/repair-and-backup.js";
-export interface RepairStateIndexesOptions {
-    startupGate?: boolean;
-    workspaceRoot: string;
-    /** When true, also runs asset registry repair + backup (existing repair service) */
-    reconcileAssets?: boolean;
-    assetRepairOptions?: RepairAndBackupOptions;
-}
-export type RepairGateStatus = "ok" | "repair_required";
-export interface RepairSummary {
-    status: RepairGateStatus;
-    repairedEvidenceIndexRows: number;
-    repairNotes: string[];
-    assetRepair?: Awaited<ReturnType<ReturnType<typeof createRepairAndBackupService>["runStartupRepair"]>>;
-}
-export declare function repairStateIndexes(state: StateDatabase, options: RepairStateIndexesOptions): Promise<RepairSummary>;
+import type { StateDatabase } from "../db/index.js";
+import { createRepairAndBackupService, type RepairAndBackupOptions } from "../services/repair-and-backup.js";
+export interface RepairStateIndexesOptions {
+    startupGate?: boolean;
+    workspaceRoot: string;
+    /** When true, also runs asset registry repair + backup (existing repair service) */
+    reconcileAssets?: boolean;
+    assetRepairOptions?: RepairAndBackupOptions;
+}
+export type RepairGateStatus = "ok" | "repair_required";
+export interface RepairSummary {
+    status: RepairGateStatus;
+    repairedEvidenceIndexRows: number;
+    repairNotes: string[];
+    assetRepair?: Awaited<ReturnType<ReturnType<typeof createRepairAndBackupService>["runStartupRepair"]>>;
+}
+export declare function repairStateIndexes(state: StateDatabase, options: RepairStateIndexesOptions): Promise<RepairSummary>;

package/runtime/storage/bootstrap/repair-gate.js

@@ -1,71 +1,71 @@
-/**
- * Startup repair gate for state indexes (T4.1.3) — reconciles life evidence filesystem vs SQLite index.
- *
- * Core logic: scan `.second-nature/evidence/*.json`; on startupGate, corrupt JSON fails closed with repair_required;
- * otherwise backfill missing `life_evidence_index` rows from parsed artifacts.
- *
- * Test coverage: tests/unit/storage/repair-gate.test.ts
- */
-import fs from "node:fs";
-import path from "node:path";
-import { eq } from "drizzle-orm";
-import { lifeEvidenceIndex } from "../db/schema/life-evidence-index.js";
-import { createRepairAndBackupService, } from "../services/repair-and-backup.js";
-export async function repairStateIndexes(state, options) {
-    const notes = [];
-    let repaired = 0;
-    const evidenceDir = path.join(options.workspaceRoot, ".second-nature", "evidence");
-    if (!fs.existsSync(evidenceDir)) {
-        notes.push("no_evidence_dir");
-    }
-    else {
-        const entries = fs.readdirSync(evidenceDir);
-        for (const name of entries) {
-            if (!name.endsWith(".json") || name.startsWith(".")) {
-                continue;
-            }
-            const abs = path.join(evidenceDir, name);
-            let parsed;
-            try {
-                parsed = JSON.parse(fs.readFileSync(abs, "utf-8"));
-            }
-            catch {
-                if (options.startupGate) {
-                    return {
-                        status: "repair_required",
-                        repairedEvidenceIndexRows: repaired,
-                        repairNotes: [...notes, `corrupt_evidence_json:${name}`],
-                    };
-                }
-                notes.push(`skip_corrupt:${name}`);
-                continue;
-            }
-            const existing = await state.db.select().from(lifeEvidenceIndex).where(eq(lifeEvidenceIndex.id, parsed.id)).limit(1);
-            if (existing.length === 0) {
-                await state.db.insert(lifeEvidenceIndex).values({
-                    id: parsed.id,
-                    timestamp: parsed.timestamp,
-                    evidenceType: parsed.evidenceType,
-                    sensitivity: parsed.sensitivity,
-                    producer: parsed.producer,
-                    artifactPath: path.join(".second-nature", "evidence", `${parsed.id}.json`).replace(/\\/g, "/"),
-                    platformId: parsed.platformId ?? null,
-                    sourceRefsJson: JSON.stringify(parsed.sourceRefs),
-                });
-                repaired += 1;
-                notes.push(`reindexed:${parsed.id}`);
-            }
-        }
-    }
-    let assetRepair;
-    if (options.reconcileAssets) {
-        const svc = createRepairAndBackupService(state);
-        assetRepair = await svc.runStartupRepair(options.assetRepairOptions ?? {});
-    }
-    return {
-        status: "ok",
-        repairedEvidenceIndexRows: repaired,
-        repairNotes: notes,
-        assetRepair,
-    };
-}
+/**
+ * Startup repair gate for state indexes (T4.1.3) — reconciles life evidence filesystem vs SQLite index.
+ *
+ * Core logic: scan `.second-nature/evidence/*.json`; on startupGate, corrupt JSON fails closed with repair_required;
+ * otherwise backfill missing `life_evidence_index` rows from parsed artifacts.
+ *
+ * Test coverage: tests/unit/storage/repair-gate.test.ts
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { eq } from "drizzle-orm";
+import { lifeEvidenceIndex } from "../db/schema/life-evidence-index.js";
+import { createRepairAndBackupService, } from "../services/repair-and-backup.js";
+export async function repairStateIndexes(state, options) {
+    const notes = [];
+    let repaired = 0;
+    const evidenceDir = path.join(options.workspaceRoot, ".second-nature", "evidence");
+    if (!fs.existsSync(evidenceDir)) {
+        notes.push("no_evidence_dir");
+    }
+    else {
+        const entries = fs.readdirSync(evidenceDir);
+        for (const name of entries) {
+            if (!name.endsWith(".json") || name.startsWith(".")) {
+                continue;
+            }
+            const abs = path.join(evidenceDir, name);
+            let parsed;
+            try {
+                parsed = JSON.parse(fs.readFileSync(abs, "utf-8"));
+            }
+            catch {
+                if (options.startupGate) {
+                    return {
+                        status: "repair_required",
+                        repairedEvidenceIndexRows: repaired,
+                        repairNotes: [...notes, `corrupt_evidence_json:${name}`],
+                    };
+                }
+                notes.push(`skip_corrupt:${name}`);
+                continue;
+            }
+            const existing = await state.db.select().from(lifeEvidenceIndex).where(eq(lifeEvidenceIndex.id, parsed.id)).limit(1);
+            if (existing.length === 0) {
+                await state.db.insert(lifeEvidenceIndex).values({
+                    id: parsed.id,
+                    timestamp: parsed.timestamp,
+                    evidenceType: parsed.evidenceType,
+                    sensitivity: parsed.sensitivity,
+                    producer: parsed.producer,
+                    artifactPath: path.join(".second-nature", "evidence", `${parsed.id}.json`).replace(/\\/g, "/"),
+                    platformId: parsed.platformId ?? null,
+                    sourceRefsJson: JSON.stringify(parsed.sourceRefs),
+                });
+                repaired += 1;
+                notes.push(`reindexed:${parsed.id}`);
+            }
+        }
+    }
+    let assetRepair;
+    if (options.reconcileAssets) {
+        const svc = createRepairAndBackupService(state);
+        assetRepair = await svc.runStartupRepair(options.assetRepairOptions ?? {});
+    }
+    return {
+        status: "ok",
+        repairedEvidenceIndexRows: repaired,
+        repairNotes: notes,
+        assetRepair,
+    };
+}

package/runtime/storage/bootstrap/storage-mode-smoke.d.ts

@@ -1,38 +1,38 @@
-import { probeNativeSqliteLoad } from "./native-sqlite-probe.js";
-export interface StorageModeSmokeSemantics {
-    sqlJs: {
-        walAssumed: false;
-        journalConcurrencyNotes: string;
-        backupNotes: string;
-        repairNotes: string;
-    };
-    nativeSqliteWhenAvailable: {
-        journalConcurrencyNotes: string;
-        backupNotes: string;
-    };
-}
-export interface StorageModeSmokeRepairFixtureResult {
-    ran: boolean;
-    workspaceRoot?: string;
-    repairStatus?: "ok" | "repair_required";
-    repairedEvidenceIndexRows?: number;
-    repairNotes?: string[];
-}
-export interface StorageModeSmokeReport {
-    generatedAt: string;
-    /** Implementation backing `createStateDatabase` today — wasm sql.js, not native WAL */
-    runtimeIndexDriver: "sql_js";
-    nativeSqliteProbe: ReturnType<typeof probeNativeSqliteLoad> & {
-        /** Current code path does not use native driver even when load succeeds */
-        runtimeUsesNativeDriver: false;
-    };
-    semantics: StorageModeSmokeSemantics;
-    repairFromArtifactsFixture?: StorageModeSmokeRepairFixtureResult;
-}
-export interface RunStorageModeSmokeOptions {
-    /** Required when runRepairFixture is true — temp dir created if omitted */
-    workspaceRoot?: string;
-    /** Run artifact→index backfill smoke (sql.js path); uses temp workspace when workspaceRoot unset */
-    runRepairFixture?: boolean;
-}
-export declare function runStorageModeSmoke(options?: RunStorageModeSmokeOptions): Promise<StorageModeSmokeReport>;
+import { probeNativeSqliteLoad } from "./native-sqlite-probe.js";
+export interface StorageModeSmokeSemantics {
+    sqlJs: {
+        walAssumed: false;
+        journalConcurrencyNotes: string;
+        backupNotes: string;
+        repairNotes: string;
+    };
+    nativeSqliteWhenAvailable: {
+        journalConcurrencyNotes: string;
+        backupNotes: string;
+    };
+}
+export interface StorageModeSmokeRepairFixtureResult {
+    ran: boolean;
+    workspaceRoot?: string;
+    repairStatus?: "ok" | "repair_required";
+    repairedEvidenceIndexRows?: number;
+    repairNotes?: string[];
+}
+export interface StorageModeSmokeReport {
+    generatedAt: string;
+    /** Implementation backing `createStateDatabase` today — wasm sql.js, not native WAL */
+    runtimeIndexDriver: "sql_js";
+    nativeSqliteProbe: ReturnType<typeof probeNativeSqliteLoad> & {
+        /** Current code path does not use native driver even when load succeeds */
+        runtimeUsesNativeDriver: false;
+    };
+    semantics: StorageModeSmokeSemantics;
+    repairFromArtifactsFixture?: StorageModeSmokeRepairFixtureResult;
+}
+export interface RunStorageModeSmokeOptions {
+    /** Required when runRepairFixture is true — temp dir created if omitted */
+    workspaceRoot?: string;
+    /** Run artifact→index backfill smoke (sql.js path); uses temp workspace when workspaceRoot unset */
+    runRepairFixture?: boolean;
+}
+export declare function runStorageModeSmoke(options?: RunStorageModeSmokeOptions): Promise<StorageModeSmokeReport>;