@haaaiawd/second-nature 0.1.8 → 0.1.10

package/runtime/observability/query/explain-query.js

@@ -0,0 +1,114 @@
+const NO_USER_VISIBLE = "no_user_visible_contact_claim_prohibited";
+function isNoUserVisibleDelivery(status) {
+    if (!status)
+        return false;
+    return (status === "target_none" ||
+        status === "not_sent_fallback" ||
+        status === "channel_missing" ||
+        status === "host_unsupported" ||
+        status === "failed" ||
+        status === "ack_dropped");
+}
+function payloadDecisionId(payload) {
+    if (!payload || typeof payload !== "object")
+        return undefined;
+    const p = payload;
+    const v = p.decisionId;
+    return typeof v === "string" ? v : undefined;
+}
+function payloadFallbackRef(payload) {
+    if (!payload || typeof payload !== "object")
+        return undefined;
+    const p = payload;
+    const v = p.fallbackRef;
+    return typeof v === "string" ? v : undefined;
+}
+function payloadAuditId(payload) {
+    if (!payload || typeof payload !== "object")
+        return undefined;
+    const p = payload;
+    const a = p.auditId;
+    if (typeof a === "string")
+        return a;
+    return undefined;
+}
+function deliveryStatusFrom(payload) {
+    if (!payload || typeof payload !== "object")
+        return undefined;
+    const p = payload;
+    const s = p.status;
+    return typeof s === "string" ? s : undefined;
+}
+function eventMatchesQuery(envelope, query) {
+    const payload = envelope.payload;
+    switch (query.kind) {
+        case "decision":
+            return payloadDecisionId(payload) === query.decisionId;
+        case "fallback":
+            return payloadFallbackRef(payload) === query.fallbackRef;
+        case "report":
+            return envelope.eventId === query.reportId || payloadAuditId(payload) === query.reportId;
+        case "delivery":
+            return (envelope.family === "delivery" &&
+                (envelope.eventId === query.auditId || payloadAuditId(payload) === query.auditId));
+        case "source_ref": {
+            const needle = query.sourceRefId;
+            try {
+                return JSON.stringify(payload).includes(needle);
+            }
+            catch {
+                return false;
+            }
+        }
+    }
+}
+function summarizeEnvelope(e) {
+    const fam = e.family;
+    if (fam === "delivery") {
+        const st = deliveryStatusFrom(e.payload);
+        return `delivery_audit:${st ?? "unknown"}`;
+    }
+    if (fam === "heartbeat.decision") {
+        const outcome = e.payload?.outcome;
+        return `decision:${typeof outcome === "string" ? outcome : "unknown"}`;
+    }
+    return `${fam}`;
+}
+/**
+ * Query explain read model from an in-memory append-only audit slice (tests / local tooling).
+ */
+export function queryExplain(query, store) {
+    const matched = store.list().filter((e) => eventMatchesQuery(e, query));
+    const relatedEventIds = matched.map((e) => e.eventId);
+    const warnings = [];
+    let deliveryStatus;
+    for (const e of matched) {
+        if (e.family === "delivery") {
+            const st = deliveryStatusFrom(e.payload);
+            if (st)
+                deliveryStatus = st;
+            if (isNoUserVisibleDelivery(st)) {
+                warnings.push(NO_USER_VISIBLE);
+            }
+        }
+    }
+    const uniqueWarnings = [...new Set(warnings)];
+    const summary = matched.length === 0
+        ? "no_matching_audit_events"
+        : `matched_events=${matched.length};subject=${query.kind}`;
+    const events = matched.map((e) => ({
+        eventId: e.eventId,
+        family: e.family,
+        plane: e.plane,
+        createdAt: e.createdAt,
+        summary: summarizeEnvelope(e),
+    }));
+    return {
+        query,
+        summary,
+        warnings: uniqueWarnings,
+        deliveryStatus,
+        relatedEventIds,
+        events,
+    };
+}

package/runtime/observability/query/export-audit-bundle.d.ts

@@ -0,0 +1,22 @@
+import type { AuditEnvelope } from "../audit/audit-envelope.js";
+import type { AuditEventFamily } from "../audit/audit-envelope.js";
+import type { AuditExportRange } from "../audit/verify-audit-hash-chain.js";
+export interface AuditBundleExportRange extends AuditExportRange {
+    /** Reserved for otel_projection / future formats */
+    format?: "json_v1";
+}
+export interface AuditRedactionSummary {
+    eventCount: number;
+    manifestIds: string[];
+}
+export interface AuditBundle {
+    bundleId: string;
+    generatedAt: string;
+    range: AuditBundleExportRange;
+    events: readonly AuditEnvelope<unknown>[];
+    redactionSummary: AuditRedactionSummary;
+}
+export interface ExportAuditBundleDeps {
+    loadRange(from: string, to: string, families?: AuditEventFamily[]): Promise<readonly AuditEnvelope<unknown>[]>;
+}
+export declare function exportAuditBundle(range: AuditBundleExportRange, deps: ExportAuditBundleDeps): Promise<AuditBundle>;

package/runtime/observability/query/export-audit-bundle.js

@@ -0,0 +1,27 @@
+/**
+ * Redacted audit export bundle for operator / retention tooling (T5.3.1).
+ *
+ * Core logic: load range, attach export metadata; payloads are already redacted at envelope build time.
+ *
+ * Dependencies: same range loader pattern as verifyAuditHashChain.
+ *
+ * Test coverage: tests/integration/observability/explain-query-export.test.ts
+ */
+import * as crypto from "node:crypto";
+function summarize(events) {
+    const ids = new Set();
+    for (const e of events) {
+        ids.add(e.redaction.manifestId);
+    }
+    return { eventCount: events.length, manifestIds: [...ids] };
+}
+export async function exportAuditBundle(range, deps) {
+    const events = [...(await deps.loadRange(range.from, range.to, range.families))].sort((a, b) => a.sequence - b.sequence);
+    return {
+        bundleId: crypto.randomUUID(),
+        generatedAt: new Date().toISOString(),
+        range,
+        events,
+        redactionSummary: summarize(events),
+    };
+}

package/runtime/observability/services/decision-ledger.d.ts

@@ -26,7 +26,7 @@ export interface HeartbeatDecisionEvent {
     traceId: string;
     runtimeScope: "rhythm" | "user_task" | "user_reply";
     triggerSource: "heartbeat_bridge" | "user_task" | "user_reply" | "interrupt" | "resume";
-    decisionStatus: "heartbeat_ok" | "intent_selected" | "denied" | "deferred";
+    decisionStatus: "heartbeat_ok" | "intent_selected" | "denied" | "deferred" | "runtime_carrier_only" | "delivery_unavailable";
     reasons: string[];
     intentId?: string;
     mode: "active" | "quiet" | "maintenance_only" | "paused_for_interrupt";

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

@@ -153,5 +153,9 @@ function mapHeartbeatStatusToVerdict(status) {
             return "defer";
         case "heartbeat_ok":
             return "defer";
+        case "runtime_carrier_only":
+            return "defer";
+        case "delivery_unavailable":
+            return "deny";
     }
 }

package/runtime/observability/services/governance-audit.d.ts

@@ -15,6 +15,20 @@ export declare class GovernanceAudit {
     private db;
     constructor(db: ObservabilityDatabase);
     recordAnchorChangeAudit(event: AnchorChangeAudit): Promise<void>;
+    /**
+     * Generic governance-plane events (T5.1.2): fallback_written, effect_commit_advanced, connector_failure, etc.
+     * traceId is stored on target_asset_id for explain/trace correlation until a dedicated column exists.
+     */
+    recordOperationalGovernanceEvent(input: {
+        id: string;
+        eventType: string;
+        traceId: string;
+        statusTo: string;
+        reason: string;
+        assetPath?: string;
+        supportingSources?: string[];
+        createdAt?: string;
+    }): Promise<void>;
     recordCredentialLifecycle(event: CredentialLifecycleAudit): Promise<void>;
     recordProposalApply(proposalId: string, targetAssetId: string, assetPath: string, beforeHash: string | undefined, afterHash: string | undefined, supportingSources: string[], reason: string): Promise<void>;
     recordProposalReject(proposalId: string, targetAssetId: string, assetPath: string, reason: string): Promise<void>;

package/runtime/observability/services/governance-audit.js

@@ -1,6 +1,6 @@
 import { eq } from "drizzle-orm";
 import { governanceAudit } from "../db/schema/index.js";
-import { redactEvent } from "../redaction/manifest.js";
+import { createEmptyManifest, redactEvent } from "../redaction/manifest.js";
 import { persistRedactionManifest } from "./redaction-store.js";
 export class GovernanceAudit {
     db;
@@ -27,6 +27,30 @@ export class GovernanceAudit {
         });
         await persistRedactionManifest(this.db, redacted.id, "anchor.change", manifest);
     }
+    /**
+     * Generic governance-plane events (T5.1.2): fallback_written, effect_commit_advanced, connector_failure, etc.
+     * traceId is stored on target_asset_id for explain/trace correlation until a dedicated column exists.
+     */
+    async recordOperationalGovernanceEvent(input) {
+        const createdAt = input.createdAt ?? new Date().toISOString();
+        await this.db.db.insert(governanceAudit).values({
+            id: input.id,
+            eventType: input.eventType,
+            proposalId: null,
+            targetAssetId: input.traceId,
+            assetPath: input.assetPath ?? null,
+            statusFrom: null,
+            statusTo: input.statusTo,
+            beforeHash: null,
+            afterHash: null,
+            supportingSources: JSON.stringify(input.supportingSources ?? []),
+            reason: input.reason,
+            verificationDeadline: null,
+            attemptsRemaining: null,
+            createdAt,
+        });
+        await persistRedactionManifest(this.db, input.id, input.eventType, createEmptyManifest());
+    }
     async recordCredentialLifecycle(event) {
         const { redacted, manifest } = redactEvent(event);
         await this.db.db.insert(governanceAudit).values({

package/runtime/observability/services/governance-plane-recorder.d.ts

@@ -0,0 +1,47 @@
+/**
+ * T5.1.2 governance plane: connector attempts + state governance audit append ports.
+ *
+ * Core logic: connector attempts map to executionAttempts telemetry; governance kinds map to
+ * governance_audit rows with traceId on target_asset_id for explain correlation.
+ *
+ * Test coverage: tests/unit/observability/governance-plane-recorder.test.ts
+ */
+import type { ObservabilityDatabase } from "../db/index.js";
+import { ExecutionTelemetry } from "./execution-telemetry.js";
+import { GovernanceAudit } from "./governance-audit.js";
+export interface AuditAppendAck {
+    recordId: string;
+    appendedAt: string;
+}
+export type ConnectorAttemptOutcome = "started" | "succeeded" | "failed" | "sampled_telemetry";
+export interface ConnectorAttemptAudit {
+    traceId: string;
+    decisionId: string;
+    intentId: string;
+    platformId: string;
+    capability: string;
+    channel: string;
+    outcome: ConnectorAttemptOutcome;
+    failureClass?: string;
+    idempotencyKey?: string;
+    metadata?: Record<string, unknown>;
+}
+export type StateGovernanceKind = "fallback_written" | "effect_commit_advanced" | "connector_failure" | "anchor_proposal_received";
+export interface StateGovernanceAudit {
+    id: string;
+    traceId: string;
+    kind: StateGovernanceKind;
+    reason: string;
+    decisionId?: string;
+    artifactPath?: string;
+    supportingSources?: string[];
+    createdAt?: string;
+}
+export declare class GovernancePlaneRecorder {
+    private readonly telemetry;
+    private readonly governance;
+    constructor(telemetry: ExecutionTelemetry, governance: GovernanceAudit);
+    recordConnectorAttempt(audit: ConnectorAttemptAudit): Promise<AuditAppendAck>;
+    recordStateGovernance(event: StateGovernanceAudit): Promise<AuditAppendAck>;
+}
+export declare function createGovernancePlaneRecorder(db: ObservabilityDatabase): GovernancePlaneRecorder;

package/runtime/observability/services/governance-plane-recorder.js

@@ -0,0 +1,55 @@
+import { ExecutionTelemetry } from "./execution-telemetry.js";
+import { GovernanceAudit } from "./governance-audit.js";
+export class GovernancePlaneRecorder {
+    telemetry;
+    governance;
+    constructor(telemetry, governance) {
+        this.telemetry = telemetry;
+        this.governance = governance;
+    }
+    async recordConnectorAttempt(audit) {
+        const id = `ca-${audit.traceId}-${Date.now()}`;
+        const status = audit.outcome === "failed" ? "failed" : audit.outcome === "started" ? "started" : "succeeded";
+        const now = new Date().toISOString();
+        const attempt = {
+            id,
+            traceId: audit.traceId,
+            decisionId: audit.decisionId,
+            intentId: audit.intentId,
+            platformId: audit.platformId,
+            capability: audit.capability,
+            channel: audit.channel,
+            status,
+            failureClass: audit.failureClass,
+            idempotencyKey: audit.idempotencyKey,
+            metadata: {
+                ...(audit.metadata ?? {}),
+                ...(audit.outcome === "sampled_telemetry" ? { sampledTelemetry: true } : {}),
+            },
+            startedAt: now,
+            finishedAt: status === "started" ? undefined : now,
+        };
+        await this.telemetry.recordExecutionAttempt(attempt);
+        return { recordId: id, appendedAt: attempt.finishedAt ?? attempt.startedAt ?? now };
+    }
+    async recordStateGovernance(event) {
+        const createdAt = event.createdAt ?? new Date().toISOString();
+        const reason = event.decisionId !== undefined && event.decisionId.length > 0
+            ? `${event.reason} decisionId=${event.decisionId}`
+            : event.reason;
+        await this.governance.recordOperationalGovernanceEvent({
+            id: event.id,
+            eventType: event.kind,
+            traceId: event.traceId,
+            statusTo: "recorded",
+            reason,
+            assetPath: event.artifactPath,
+            supportingSources: event.supportingSources,
+            createdAt,
+        });
+        return { recordId: event.id, appendedAt: createdAt };
+    }
+}
+export function createGovernancePlaneRecorder(db) {
+    return new GovernancePlaneRecorder(new ExecutionTelemetry(db), new GovernanceAudit(db));
+}

package/runtime/observability/services/lived-experience-audit.d.ts

@@ -0,0 +1,97 @@
+import { AppendOnlyAuditStore } from "../audit/append-only-audit-store.js";
+import type { SourceRef } from "../../storage/life-evidence/types.js";
+export type RuntimeScope = "rhythm" | "user_task" | "user_reply";
+export type HeartbeatOutcome = "heartbeat_ok" | "intent_selected" | "denied" | "deferred" | "runtime_carrier_only" | "delivery_unavailable";
+export type DeliveryAuditStatus = "not_requested" | "target_available" | "target_none" | "channel_missing" | "host_unsupported" | "ack_dropped" | "sent" | "failed" | "not_sent_fallback";
+export type GroundingStatus = "pass" | "degraded" | "blocked";
+export interface DecisionTracePayload {
+    decisionId: string;
+    traceId: string;
+    heartbeatId?: string;
+    runtimeScope: RuntimeScope;
+    outcome: HeartbeatOutcome;
+    selectedIntentId?: string;
+    candidateId?: string;
+    rhythmWindowKind?: string;
+    hardGuardVerdict?: "allow" | "deny" | "defer" | "silent";
+    outreachVerdict?: "allow" | "deny" | "defer";
+    deliveryAuditId?: string;
+    reasonCodes: string[];
+    sourceRefs: SourceRef[];
+    snapshotRef?: SourceRef;
+    createdAt: string;
+}
+export interface DeliveryAuditPayload {
+    auditId: string;
+    decisionId: string;
+    traceId: string;
+    target?: "none" | "last" | "explicit";
+    channel?: string;
+    recipientRef?: string;
+    status: DeliveryAuditStatus;
+    messageId?: string;
+    hostProofRef?: SourceRef;
+    fallbackRef?: string;
+    ackDropMatched?: boolean;
+    hostVersion?: string;
+    reasonCodes: string[];
+    createdAt: string;
+}
+export interface SourceCoverageAuditPayload {
+    auditId: string;
+    traceId: string;
+    /** When set, explain index links this audit to the decision timeline. */
+    decisionId?: string;
+    subjectType: "quiet_artifact" | "outreach_draft" | "guidance_payload" | "decision_trace" | "host_report";
+    subjectRef: string;
+    usedSourceRefs: SourceRef[];
+    unresolvedRefs: SourceRef[];
+    coverageRatio: number;
+    unsupportedClaims: string[];
+    status: GroundingStatus;
+    reasonCodes: string[];
+    createdAt: string;
+}
+export interface GuidanceGroundingAuditPayload {
+    auditId: string;
+    traceId: string;
+    decisionId?: string;
+    requestId: string;
+    draftId?: string;
+    sceneType: "outreach" | "quiet_reflection" | "social" | "explain" | "user_reply_continuity" | "fallback_candidate";
+    groundingStatus: GroundingStatus;
+    usedSourceRefs: SourceRef[];
+    unsupportedClaims: string[];
+    guardViolations: string[];
+    deliveryWording?: "sendable" | "not_sent_fallback_candidate";
+    createdAt: string;
+}
+export interface ExplainLinkageSummary {
+    decisionId: string;
+    summary: string;
+    warnings: string[];
+    deliveryStatus?: DeliveryAuditStatus;
+    relatedEventIds: string[];
+}
+export declare class LivedExperienceAuditRecorder {
+    private readonly store;
+    private seq;
+    private readonly explainIndex;
+    constructor(store: AppendOnlyAuditStore);
+    private bumpSequence;
+    private touchDecision;
+    recordDecisionTrace(payload: DecisionTracePayload): {
+        eventId: string;
+    };
+    recordDeliveryAudit(payload: DeliveryAuditPayload): {
+        eventId: string;
+    };
+    recordSourceCoverage(payload: SourceCoverageAuditPayload): {
+        eventId: string;
+    };
+    recordGuidanceGrounding(payload: GuidanceGroundingAuditPayload): {
+        eventId: string;
+    };
+    explainLinkageForDecision(decisionId: string): ExplainLinkageSummary;
+}
+export declare function createLivedExperienceAuditRecorder(store?: AppendOnlyAuditStore): LivedExperienceAuditRecorder;

package/runtime/observability/services/lived-experience-audit.js

@@ -0,0 +1,162 @@
+/**
+ * Decision trace, delivery audit, source coverage, guidance grounding + explain index (T5.2.1).
+ *
+ * Core logic: append-only envelopes with hash chain; explain index links decisionId to events and
+ * flags when delivery audit indicates no user-visible contact (target_none / not_sent_fallback).
+ * Test coverage: tests/unit/observability/lived-experience-audit.test.ts
+ */
+import * as crypto from "node:crypto";
+import { AppendOnlyAuditStore } from "../audit/append-only-audit-store.js";
+import { buildAuditEnvelope } from "../audit/audit-envelope.js";
+function validateDecisionTrace(t) {
+    if (!t.decisionId?.trim())
+        throw new Error("decision_trace_requires_decision_id");
+    if (!t.traceId?.trim())
+        throw new Error("decision_trace_requires_trace_id");
+    if (!t.outcome)
+        throw new Error("decision_trace_requires_outcome");
+}
+function validateDeliveryAudit(a) {
+    if (!a.auditId?.trim())
+        throw new Error("delivery_audit_requires_audit_id");
+    if (!a.decisionId?.trim())
+        throw new Error("delivery_audit_requires_decision_id");
+    if (a.status === "sent") {
+        const ok = Boolean(a.messageId?.trim()) || Boolean(a.hostProofRef);
+        if (!ok)
+            throw new Error("delivery_audit_sent_requires_message_id_or_host_proof_ref");
+    }
+}
+export class LivedExperienceAuditRecorder {
+    store;
+    seq = 0;
+    explainIndex = new Map();
+    constructor(store) {
+        this.store = store;
+    }
+    bumpSequence() {
+        this.seq += 1;
+        return this.seq;
+    }
+    touchDecision(decisionId, traceId, eventId) {
+        let e = this.explainIndex.get(decisionId);
+        if (!e) {
+            e = { traceIds: new Set(), eventIds: [], deliveryStatuses: [], fallbackRefs: [], noUserVisibleContact: false };
+            this.explainIndex.set(decisionId, e);
+        }
+        e.traceIds.add(traceId);
+        e.eventIds.push(eventId);
+        return e;
+    }
+    recordDecisionTrace(payload) {
+        validateDecisionTrace(payload);
+        const seq = this.bumpSequence();
+        const envelope = buildAuditEnvelope({
+            family: "heartbeat.decision",
+            plane: "decision",
+            traceId: payload.traceId,
+            sequence: seq,
+            payload,
+            previousHash: this.store.lastRecordHash(),
+            eventId: crypto.randomUUID(),
+            createdAt: payload.createdAt,
+        });
+        this.store.append(envelope);
+        const entry = this.touchDecision(payload.decisionId, payload.traceId, envelope.eventId);
+        if (payload.outcome === "heartbeat_ok" &&
+            payload.reasonCodes.some((c) => c.includes("target_none") || c === "target_none")) {
+            entry.noUserVisibleContact = true;
+        }
+        return { eventId: envelope.eventId };
+    }
+    recordDeliveryAudit(payload) {
+        validateDeliveryAudit(payload);
+        const seq = this.bumpSequence();
+        const envelope = buildAuditEnvelope({
+            family: "delivery",
+            plane: "delivery",
+            traceId: payload.traceId,
+            sequence: seq,
+            payload,
+            previousHash: this.store.lastRecordHash(),
+            eventId: payload.auditId,
+            createdAt: payload.createdAt,
+        });
+        this.store.append(envelope);
+        const entry = this.touchDecision(payload.decisionId, payload.traceId, envelope.eventId);
+        entry.deliveryStatuses.push(payload.status);
+        if (payload.fallbackRef)
+            entry.fallbackRefs.push(payload.fallbackRef);
+        if (payload.status === "target_none" ||
+            payload.status === "not_sent_fallback" ||
+            payload.status === "channel_missing" ||
+            payload.status === "host_unsupported" ||
+            payload.status === "failed" ||
+            payload.status === "ack_dropped") {
+            entry.noUserVisibleContact = true;
+        }
+        return { eventId: envelope.eventId };
+    }
+    recordSourceCoverage(payload) {
+        const seq = this.bumpSequence();
+        const envelope = buildAuditEnvelope({
+            family: "source_coverage",
+            plane: "source_coverage",
+            traceId: payload.traceId,
+            sequence: seq,
+            payload,
+            previousHash: this.store.lastRecordHash(),
+            eventId: payload.auditId,
+            createdAt: payload.createdAt,
+        });
+        this.store.append(envelope);
+        if (payload.decisionId) {
+            this.touchDecision(payload.decisionId, payload.traceId, envelope.eventId);
+        }
+        return { eventId: envelope.eventId };
+    }
+    recordGuidanceGrounding(payload) {
+        const seq = this.bumpSequence();
+        const envelope = buildAuditEnvelope({
+            family: "guidance.grounding",
+            plane: "source_coverage",
+            traceId: payload.traceId,
+            sequence: seq,
+            payload,
+            previousHash: this.store.lastRecordHash(),
+            eventId: payload.auditId,
+            createdAt: payload.createdAt,
+        });
+        this.store.append(envelope);
+        if (payload.decisionId) {
+            this.touchDecision(payload.decisionId, payload.traceId, envelope.eventId);
+        }
+        return { eventId: envelope.eventId };
+    }
+    explainLinkageForDecision(decisionId) {
+        const entry = this.explainIndex.get(decisionId);
+        const warnings = [];
+        if (!entry) {
+            return {
+                decisionId,
+                summary: "no_audit_events_indexed_for_decision",
+                warnings: ["no_indexed_events"],
+                relatedEventIds: [],
+            };
+        }
+        if (entry.noUserVisibleContact) {
+            warnings.push("no_user_visible_contact_claim_prohibited");
+        }
+        const lastDelivery = entry.deliveryStatuses[entry.deliveryStatuses.length - 1];
+        return {
+            decisionId,
+            summary: `indexed_events=${entry.eventIds.length};delivery=${lastDelivery ?? "unknown"}`,
+            warnings,
+            deliveryStatus: lastDelivery,
+            relatedEventIds: [...entry.eventIds],
+        };
+    }
+}
+export function createLivedExperienceAuditRecorder(store) {
+    return new LivedExperienceAuditRecorder(store ?? new AppendOnlyAuditStore());
+}

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

@@ -0,0 +1,7 @@
+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

@@ -0,0 +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),
+        };
+    }
+}

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

@@ -0,0 +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>;