@haaaiawd/second-nature 0.1.7 → 0.1.9

package/runtime/storage/delivery/write-delivery-attempt.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Persists delivery attempts with state-system validation (T4.3.1).
+ */
+import type { StateDatabase } from "../db/index.js";
+import type { DeliveryAttemptAck, DeliveryAttemptWrite } from "./types.js";
+export declare function writeDeliveryAttempt(state: StateDatabase, attempt: DeliveryAttemptWrite): Promise<DeliveryAttemptAck>;

package/runtime/storage/delivery/write-delivery-attempt.js

@@ -0,0 +1,36 @@
+import { deliveryAttempts } from "../db/schema/delivery-attempts.js";
+function assertDeliveryAttemptValid(attempt) {
+    if (attempt.status === "sent") {
+        const hasProof = Boolean(attempt.messageId?.trim()) || Boolean(attempt.hostProofRef);
+        if (!hasProof) {
+            throw new Error("delivery_attempt_sent_requires_message_id_or_host_proof_ref");
+        }
+    }
+    if (attempt.status === "failed" || attempt.status === "dropped_by_host_policy") {
+        const hasDiag = Boolean(attempt.errorClass?.trim()) || Boolean(attempt.fallbackRef?.trim());
+        if (!hasDiag) {
+            throw new Error("delivery_attempt_failed_requires_error_class_or_fallback_ref");
+        }
+    }
+}
+export async function writeDeliveryAttempt(state, attempt) {
+    assertDeliveryAttemptValid(attempt);
+    const createdAt = new Date().toISOString();
+    await state.db.insert(deliveryAttempts).values({
+        attemptId: attempt.attemptId,
+        decisionId: attempt.decisionId,
+        target: attempt.target ?? null,
+        channel: attempt.channel ?? null,
+        status: attempt.status,
+        messageId: attempt.messageId ?? null,
+        hostProofRefJson: attempt.hostProofRef ? JSON.stringify(attempt.hostProofRef) : null,
+        errorClass: attempt.errorClass ?? null,
+        fallbackRef: attempt.fallbackRef ?? null,
+        createdAt,
+    });
+    return {
+        attemptId: attempt.attemptId,
+        status: attempt.status,
+        fallbackRef: attempt.fallbackRef,
+    };
+}

package/runtime/storage/fallback/load-operator-fallback.d.ts

@@ -0,0 +1,14 @@
+import type { StateDatabase } from "../db/index.js";
+import type { SourceRef } from "../life-evidence/types.js";
+import type { OperatorFallbackView } from "./operator-fallback-view.js";
+export declare function normalizeFallbackRef(ref: string): string;
+/** Loads persisted operator fallback row; does not coerce status (use `toOperatorFallbackView`). */
+export declare function loadOperatorFallbackRow(state: StateDatabase, fallbackRef: string): Promise<{
+    fallbackRef: string;
+    reason: string;
+    status: string;
+    sourceRefs: SourceRef[];
+    candidateMessage?: string;
+    nextStep: string;
+} | null>;
+export declare function toOperatorFallbackView(row: NonNullable<Awaited<ReturnType<typeof loadOperatorFallbackRow>>>): OperatorFallbackView;

package/runtime/storage/fallback/load-operator-fallback.js

@@ -0,0 +1,47 @@
+import { eq } from "drizzle-orm";
+import { operatorFallbackArtifacts } from "../db/schema/operator-fallback-artifacts.js";
+const REASONS = new Set(["target_none", "channel_missing", "host_unsupported", "delivery_failed"]);
+export function normalizeFallbackRef(ref) {
+    const t = ref.trim();
+    if (!t)
+        return t;
+    return t.startsWith("fallback:") ? t : `fallback:${t}`;
+}
+function parseSourceRefs(json) {
+    try {
+        const parsed = JSON.parse(json);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Loads persisted operator fallback row; does not coerce status (use `toOperatorFallbackView`). */
+export async function loadOperatorFallbackRow(state, fallbackRef) {
+    const key = normalizeFallbackRef(fallbackRef);
+    if (!key)
+        return null;
+    const rows = await state.db.select().from(operatorFallbackArtifacts).where(eq(operatorFallbackArtifacts.fallbackRef, key)).limit(1);
+    const row = rows[0];
+    if (!row)
+        return null;
+    return {
+        fallbackRef: row.fallbackRef,
+        reason: row.reason,
+        status: row.status,
+        sourceRefs: parseSourceRefs(row.sourceRefsJson),
+        candidateMessage: row.candidateMessage ?? undefined,
+        nextStep: row.nextStep,
+    };
+}
+export function toOperatorFallbackView(row) {
+    const reason = REASONS.has(row.reason) ? row.reason : row.reason;
+    return {
+        fallbackRef: row.fallbackRef,
+        reason,
+        status: "not_sent",
+        sourceRefs: row.sourceRefs,
+        candidateMessage: row.candidateMessage,
+        nextStep: row.nextStep,
+    };
+}

package/runtime/storage/fallback/operator-fallback-types.d.ts

@@ -0,0 +1,9 @@
+import type { SourceRef } from "../life-evidence/types.js";
+export type OperatorFallbackReason = "target_none" | "channel_missing" | "host_unsupported" | "delivery_failed";
+export interface OperatorFallbackWrite {
+    reason: OperatorFallbackReason;
+    decisionId: string;
+    sourceRefs: SourceRef[];
+    candidateMessage?: string;
+    nextStep: string;
+}

package/runtime/storage/fallback/operator-fallback-types.js

@@ -0,0 +1 @@
+export {};

package/runtime/storage/fallback/operator-fallback-view.d.ts

@@ -0,0 +1,11 @@
+import type { SourceRef } from "../life-evidence/types.js";
+import type { OperatorFallbackReason } from "./operator-fallback-types.js";
+/** Operator-facing delivery fallback (T1.2.2 / cli-system v5). Status is always not_sent — never sent/delivered. */
+export interface OperatorFallbackView {
+    fallbackRef: string;
+    reason: OperatorFallbackReason | string;
+    status: "not_sent";
+    sourceRefs: SourceRef[];
+    candidateMessage?: string;
+    nextStep: string;
+}

package/runtime/storage/fallback/operator-fallback-view.js

@@ -0,0 +1 @@
+export {};

package/runtime/storage/fallback/write-operator-fallback.d.ts

@@ -0,0 +1,6 @@
+import type { StateDatabase } from "../db/index.js";
+import type { OperatorFallbackWrite } from "./operator-fallback-types.js";
+export interface OperatorFallbackAck {
+    fallbackRef: string;
+}
+export declare function writeOperatorFallback(state: StateDatabase, input: OperatorFallbackWrite): Promise<OperatorFallbackAck>;

package/runtime/storage/fallback/write-operator-fallback.js

@@ -0,0 +1,21 @@
+/**
+ * Persists operator-visible delivery fallback artifacts (T2.3.2 / state-system v5).
+ * status is always not_sent per ADR-007.
+ */
+import * as crypto from "node:crypto";
+import { operatorFallbackArtifacts } from "../db/schema/operator-fallback-artifacts.js";
+export async function writeOperatorFallback(state, input) {
+    const fallbackRef = `fallback:${crypto.randomUUID()}`;
+    const createdAt = new Date().toISOString();
+    await state.db.insert(operatorFallbackArtifacts).values({
+        fallbackRef,
+        decisionId: input.decisionId,
+        status: "not_sent",
+        reason: input.reason,
+        sourceRefsJson: JSON.stringify(input.sourceRefs),
+        candidateMessage: input.candidateMessage ?? null,
+        nextStep: input.nextStep,
+        createdAt,
+    });
+    return { fallbackRef };
+}

package/runtime/storage/index.d.ts

@@ -13,4 +13,25 @@ export { createGovernanceLayer, type GovernanceLayer, type AnchorWriteProposal,
 export { createProvenanceService, type ProvenanceService, type ProvenanceTrace, type ProvenanceDetail } from "./services/provenance-service.js";
 export { createRepairAndBackupService, type RepairAndBackupService, type RepairAndBackupOptions, type RepairAndBackupResult, } from "./services/repair-and-backup.js";
 export { runStartupRepairAndBackup } from "./bootstrap/repair.js";
+export { probeNativeSqliteLoad } from "./bootstrap/native-sqlite-probe.js";
+export { runStorageModeSmoke, type StorageModeSmokeReport, type RunStorageModeSmokeOptions, } from "./bootstrap/storage-mode-smoke.js";
+export { repairStateIndexes, type RepairSummary, type RepairStateIndexesOptions, type RepairGateStatus, } from "./bootstrap/repair-gate.js";
 export { createStateAPI, type StateAPI, type MemoryReadPort, type MemoryWritePort, type CredentialContextPort, type IntentCommitPort, type ProvenancePort } from "./state-api.js";
+export type { LifeEvidence, LifeEvidenceCandidate, LifeEvidenceType, LifeEvidenceWriteAck, Sensitivity, SourceRef, } from "./life-evidence/types.js";
+export { appendLifeEvidence, type AppendLifeEvidenceOptions } from "./life-evidence/append-life-evidence.js";
+export { loadRhythmPolicySnapshot, type RhythmPolicySnapshot } from "./rhythm/rhythm-policy-snapshot.js";
+export type { LifeEvidenceQuery, LifeEvidenceSnapshot, LifeEvidenceReadModel, ContinuitySnapshot, SourceCoverage, } from "./snapshots/types.js";
+export { loadLifeEvidenceSnapshot, type LoadLifeEvidenceSnapshotOptions } from "./snapshots/life-evidence-snapshot.js";
+export { loadContinuitySnapshot, type LoadContinuitySnapshotParams } from "./snapshots/continuity-snapshot.js";
+export type { UserInterestSnapshot, UserInterestSignal, UserInterestStaleness } from "./user-interest/types.js";
+export { loadUserInterestSnapshot } from "./user-interest/load-user-interest-snapshot.js";
+export type { DeliveryAttemptWrite, DeliveryAttemptRecord, DeliveryAttemptAck } from "./delivery/types.js";
+export { writeDeliveryAttempt } from "./delivery/write-delivery-attempt.js";
+export { listDeliveryAttemptsByDecisionId } from "./delivery/query-delivery-attempts.js";
+export type { OperatorFallbackWrite, OperatorFallbackReason } from "./fallback/operator-fallback-types.js";
+export type { OperatorFallbackView } from "./fallback/operator-fallback-view.js";
+export { writeOperatorFallback, type OperatorFallbackAck } from "./fallback/write-operator-fallback.js";
+export { loadOperatorFallbackRow, normalizeFallbackRef, toOperatorFallbackView, } from "./fallback/load-operator-fallback.js";
+export type { QuietArtifactWrite, QuietClaim, QuietArtifactKind } from "./quiet/quiet-artifact-types.js";
+export { writeQuietArtifact, calculateQuietSourceCoverage, evidenceGroundingRatio, type QuietArtifactAck, } from "./quiet/quiet-artifact-writer.js";
+export { persistQuietArtifactToWorkspace, type PersistQuietArtifactResult } from "./quiet/persist-quiet-artifact.js";

package/runtime/storage/index.js

@@ -13,4 +13,18 @@ export { createGovernanceLayer } from "./services/governance-layer.js";
 export { createProvenanceService } from "./services/provenance-service.js";
 export { createRepairAndBackupService, } from "./services/repair-and-backup.js";
 export { runStartupRepairAndBackup } from "./bootstrap/repair.js";
+export { probeNativeSqliteLoad } from "./bootstrap/native-sqlite-probe.js";
+export { runStorageModeSmoke, } from "./bootstrap/storage-mode-smoke.js";
+export { repairStateIndexes, } from "./bootstrap/repair-gate.js";
 export { createStateAPI } from "./state-api.js";
+export { appendLifeEvidence } from "./life-evidence/append-life-evidence.js";
+export { loadRhythmPolicySnapshot } from "./rhythm/rhythm-policy-snapshot.js";
+export { loadLifeEvidenceSnapshot } from "./snapshots/life-evidence-snapshot.js";
+export { loadContinuitySnapshot } from "./snapshots/continuity-snapshot.js";
+export { loadUserInterestSnapshot } from "./user-interest/load-user-interest-snapshot.js";
+export { writeDeliveryAttempt } from "./delivery/write-delivery-attempt.js";
+export { listDeliveryAttemptsByDecisionId } from "./delivery/query-delivery-attempts.js";
+export { writeOperatorFallback } from "./fallback/write-operator-fallback.js";
+export { loadOperatorFallbackRow, normalizeFallbackRef, toOperatorFallbackView, } from "./fallback/load-operator-fallback.js";
+export { writeQuietArtifact, calculateQuietSourceCoverage, evidenceGroundingRatio, } from "./quiet/quiet-artifact-writer.js";
+export { persistQuietArtifactToWorkspace } from "./quiet/persist-quiet-artifact.js";

package/runtime/storage/life-evidence/append-life-evidence.d.ts

@@ -0,0 +1,7 @@
+import type { StateDatabase } from "../db/index.js";
+import type { ProvenanceRepository } from "../repositories/provenance-repository.js";
+import type { LifeEvidenceCandidate, LifeEvidenceWriteAck } from "./types.js";
+export interface AppendLifeEvidenceOptions {
+    provenance?: ProvenanceRepository;
+}
+export declare function appendLifeEvidence(state: StateDatabase, workspaceRoot: string, candidate: LifeEvidenceCandidate, options?: AppendLifeEvidenceOptions): Promise<LifeEvidenceWriteAck>;

package/runtime/storage/life-evidence/append-life-evidence.js

@@ -0,0 +1,64 @@
+/**
+ * Append canonical LifeEvidence artifacts and SQLite index rows (state-system T4.1.1).
+ *
+ * Core logic: reject missing source refs and credential sensitivity; write JSON artifact;
+ * insert life_evidence_index; bump snapshot epoch file for downstream snapshot invalidation.
+ *
+ * Dependencies: StateDatabase drizzle + optional ProvenanceRepository for source edges.
+ *
+ * Boundaries: does not run connector normalization; caller supplies validated candidates.
+ *
+ * Test coverage: tests/unit/storage/life-evidence.test.ts
+ */
+import * as crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { lifeEvidenceIndex } from "../db/schema/life-evidence-index.js";
+export async function appendLifeEvidence(state, workspaceRoot, candidate, options) {
+    if (!candidate.sourceRefs || candidate.sourceRefs.length === 0) {
+        throw new Error("life_evidence_missing_source_refs");
+    }
+    if (candidate.sensitivity === "credential") {
+        throw new Error("life_evidence_credential_rejected");
+    }
+    const evidenceId = candidate.id ?? `lev_${crypto.randomUUID()}`;
+    const artifactRel = path.join(".second-nature", "evidence", `${evidenceId}.json`);
+    const artifactAbs = path.join(workspaceRoot, artifactRel);
+    const artifactRef = {
+        id: `artifact:${evidenceId}`,
+        kind: "workspace_artifact",
+        uri: artifactRel.replace(/\\/g, "/"),
+    };
+    const life = {
+        id: evidenceId,
+        timestamp: candidate.timestamp,
+        evidenceType: candidate.evidenceType,
+        platformId: candidate.platformId,
+        summary: candidate.summary,
+        rawContentRef: candidate.rawContentRef,
+        sourceRefs: candidate.sourceRefs,
+        sensitivity: candidate.sensitivity,
+        confidence: candidate.confidence ?? 1,
+        tags: candidate.tags ?? [],
+        producer: candidate.producer,
+        artifactRef,
+    };
+    fs.mkdirSync(path.dirname(artifactAbs), { recursive: true });
+    fs.writeFileSync(artifactAbs, JSON.stringify(life, null, 2), "utf-8");
+    const epochPath = path.join(workspaceRoot, ".second-nature", "evidence", ".snapshot_epoch");
+    fs.writeFileSync(epochPath, `${Date.now()}\n`, "utf-8");
+    await state.db.insert(lifeEvidenceIndex).values({
+        id: evidenceId,
+        timestamp: candidate.timestamp,
+        evidenceType: candidate.evidenceType,
+        sensitivity: candidate.sensitivity,
+        producer: candidate.producer,
+        artifactPath: artifactRel.replace(/\\/g, "/"),
+        platformId: candidate.platformId ?? null,
+        sourceRefsJson: JSON.stringify(candidate.sourceRefs),
+    });
+    if (options?.provenance) {
+        await options.provenance.linkEntrySources(evidenceId, candidate.sourceRefs.map((ref) => ref.id));
+    }
+    return { evidenceId, artifactRef };
+}

package/runtime/storage/life-evidence/types.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Life evidence contract types (state-system v5 subset for ingest port).
+ *
+ * Test coverage: tests/unit/storage/life-evidence.test.ts
+ */
+export type LifeEvidenceType = "platform_browse" | "platform_interaction" | "work_progress" | "task_discovery" | "user_interaction" | "quiet_reflection" | "delivery_fallback";
+export type Sensitivity = "public" | "private" | "credential" | "sensitive";
+export interface SourceRef {
+    id: string;
+    kind: "platform_item" | "workspace_artifact" | "decision_record" | "user_anchor" | "connector_result" | "host_report" | "fallback_artifact";
+    uri: string;
+    excerptHash?: string;
+    observedAt?: string;
+}
+export interface LifeEvidenceCandidate {
+    id?: string;
+    timestamp: string;
+    evidenceType: LifeEvidenceType;
+    platformId?: string;
+    summary: string;
+    rawContentRef?: string;
+    sourceRefs: SourceRef[];
+    sensitivity: Sensitivity;
+    confidence?: number;
+    tags?: string[];
+    producer: "connector-system" | "control-plane-system" | "observability-system" | "state-system";
+}
+export interface LifeEvidence {
+    id: string;
+    timestamp: string;
+    evidenceType: LifeEvidenceType;
+    platformId?: string;
+    summary: string;
+    rawContentRef?: string;
+    sourceRefs: SourceRef[];
+    sensitivity: Sensitivity;
+    confidence: number;
+    tags: string[];
+    producer: string;
+    artifactRef: SourceRef;
+}
+export interface LifeEvidenceWriteAck {
+    evidenceId: string;
+    artifactRef: SourceRef;
+}

package/runtime/storage/life-evidence/types.js

@@ -0,0 +1,6 @@
+/**
+ * Life evidence contract types (state-system v5 subset for ingest port).
+ *
+ * Test coverage: tests/unit/storage/life-evidence.test.ts
+ */
+export {};

package/runtime/storage/quiet/persist-quiet-artifact.d.ts

@@ -0,0 +1,7 @@
+import type { QuietArtifactWrite } from "./quiet-artifact-types.js";
+import type { QuietArtifactAck } from "./quiet-artifact-writer.js";
+export interface PersistQuietArtifactResult {
+    relativePath: string;
+    absolutePath: string;
+}
+export declare function persistQuietArtifactToWorkspace(workspaceRoot: string, ack: QuietArtifactAck, input: QuietArtifactWrite): Promise<PersistQuietArtifactResult>;

package/runtime/storage/quiet/persist-quiet-artifact.js

@@ -0,0 +1,22 @@
+/**
+ * Writes validated Quiet artifact JSON under workspace `.second-nature/quiet/{day}/` (CR-M3 / T2.3.3).
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+export async function persistQuietArtifactToWorkspace(workspaceRoot, ack, input) {
+    const dir = path.join(workspaceRoot, ".second-nature", "quiet", input.day);
+    await fs.mkdir(dir, { recursive: true });
+    const file = path.join(dir, `${ack.artifactId}.json`);
+    const payload = {
+        artifactId: ack.artifactId,
+        artifactRef: ack.artifactRef,
+        sourceCoverage: ack.sourceCoverage,
+        write: input,
+        persistedAt: new Date().toISOString(),
+    };
+    await fs.writeFile(file, JSON.stringify(payload, null, 2), "utf8");
+    return {
+        relativePath: path.relative(workspaceRoot, file),
+        absolutePath: file,
+    };
+}

package/runtime/storage/quiet/quiet-artifact-types.d.ts

@@ -0,0 +1,18 @@
+import type { SourceRef } from "../life-evidence/types.js";
+export type QuietArtifactKind = "daily_report" | "narrative_reflection" | "curated_memory_candidate" | "empty_state";
+export type QuietClaimType = "fact" | "emotion" | "interpretation" | "next_step";
+export interface QuietClaim {
+    id: string;
+    text: string;
+    sourceRefs: SourceRef[];
+    claimType: QuietClaimType;
+}
+export interface QuietArtifactWrite {
+    day: string;
+    kind: QuietArtifactKind;
+    title: string;
+    body: string;
+    claims: QuietClaim[];
+    sourceRefs: SourceRef[];
+    memoryCandidateRefs?: SourceRef[];
+}

package/runtime/storage/quiet/quiet-artifact-types.js

@@ -0,0 +1 @@
+export {};

package/runtime/storage/quiet/quiet-artifact-writer.d.ts

@@ -0,0 +1,15 @@
+import type { SourceRef } from "../life-evidence/types.js";
+import type { SourceCoverage } from "../snapshots/types.js";
+import type { QuietArtifactWrite } from "./quiet-artifact-types.js";
+import type { QuietClaim } from "./quiet-artifact-types.js";
+export declare function calculateQuietSourceCoverage(claims: QuietClaim[]): SourceCoverage;
+/** Ratio of factual claims whose refs intersect the artifact's evidence bundle (T4.4.1). */
+export declare function evidenceGroundingRatio(input: Pick<QuietArtifactWrite, "claims" | "sourceRefs">): number;
+export interface QuietArtifactAck {
+    artifactId: string;
+    artifactRef: SourceRef;
+    sourceCoverage: SourceCoverage;
+}
+export declare function writeQuietArtifact(input: QuietArtifactWrite, opts?: {
+    minimumCoverageRatio?: number;
+}): QuietArtifactAck;

package/runtime/storage/quiet/quiet-artifact-writer.js

@@ -0,0 +1,56 @@
+/**
+ * Quiet artifact validation + source coverage gate (T4.4.1 / ADR-003).
+ * Returns artifact identity for persistence layers; does not write FS/SQLite here.
+ */
+import * as crypto from "node:crypto";
+const DEFAULT_MIN_COVERAGE_RATIO = 0.51;
+export function calculateQuietSourceCoverage(claims) {
+    const factual = claims.filter((c) => c.claimType === "fact");
+    const claimCoverage = claims.map((c) => {
+        const backed = c.claimType !== "fact" || c.sourceRefs.length > 0;
+        return { claimId: c.id, backed, sourceRefs: [...c.sourceRefs] };
+    });
+    const unsupportedClaims = claimCoverage.filter((x) => !x.backed).map((x) => x.claimId);
+    const coverageRatio = factual.length === 0 ? 1 : factual.filter((c) => c.sourceRefs.length > 0).length / factual.length;
+    return { coverageRatio, unsupportedClaims, claimCoverage };
+}
+/** Ratio of factual claims whose refs intersect the artifact's evidence bundle (T4.4.1). */
+export function evidenceGroundingRatio(input) {
+    const allowedIds = new Set(input.sourceRefs.map((s) => s.id));
+    const facts = input.claims.filter((c) => c.claimType === "fact");
+    if (facts.length === 0)
+        return 1;
+    let grounded = 0;
+    for (const f of facts) {
+        if (f.sourceRefs.length === 0)
+            continue;
+        if (f.sourceRefs.some((r) => allowedIds.has(r.id)))
+            grounded += 1;
+    }
+    return grounded / facts.length;
+}
+export function writeQuietArtifact(input, opts) {
+    const minCov = opts?.minimumCoverageRatio ?? DEFAULT_MIN_COVERAGE_RATIO;
+    if (input.sourceRefs.length === 0 && input.kind !== "empty_state") {
+        throw new Error("quiet_artifact_requires_source_refs");
+    }
+    const localCoverage = calculateQuietSourceCoverage(input.claims);
+    if (input.kind !== "empty_state" && localCoverage.unsupportedClaims.length > 0) {
+        throw new Error("quiet_artifact_unsupported_factual_claim");
+    }
+    const grounding = evidenceGroundingRatio(input);
+    if (input.kind !== "empty_state" && grounding < minCov) {
+        throw new Error("quiet_artifact_source_coverage_too_low");
+    }
+    const artifactId = crypto.randomUUID();
+    const artifactRef = {
+        id: `quiet:${artifactId}`,
+        kind: "workspace_artifact",
+        uri: `urn:second-nature:quiet:${input.day}:${input.kind}:${artifactId}`,
+    };
+    const sourceCoverage = {
+        ...localCoverage,
+        coverageRatio: input.kind === "empty_state" ? 1 : grounding,
+    };
+    return { artifactId, artifactRef, sourceCoverage };
+}

package/runtime/storage/rhythm/rhythm-policy-snapshot.d.ts

@@ -0,0 +1,10 @@
+import type { StateDatabase } from "../db/index.js";
+export interface RhythmPolicySnapshot {
+    snapshotId: string;
+    generatedAt: string;
+    quietEnabled: boolean;
+    socialDailyLimit: number;
+    outreachDailyBudget: number;
+    updatedAt: string;
+}
+export declare function loadRhythmPolicySnapshot(db: StateDatabase): Promise<RhythmPolicySnapshot>;

package/runtime/storage/rhythm/rhythm-policy-snapshot.js

@@ -0,0 +1,34 @@
+/**
+ * Rhythm policy read model: state produces policy fields only (T4.1.2 owner boundary).
+ *
+ * Core logic: load workspace-scoped policy row or defaults; never emit control-plane decision fields.
+ *
+ * Test coverage: tests/unit/storage/rhythm-policy-snapshot.test.ts
+ */
+import * as crypto from "node:crypto";
+import { eq } from "drizzle-orm";
+import { policyRecords } from "../db/schema/policies.js";
+const WORKSPACE_SCOPE = "workspace";
+export async function loadRhythmPolicySnapshot(db) {
+    const scoped = await db.db.select().from(policyRecords).where(eq(policyRecords.platformId, WORKSPACE_SCOPE)).limit(1);
+    const row = scoped[0] ?? (await db.db.select().from(policyRecords).limit(1))[0];
+    const generatedAt = new Date().toISOString();
+    if (!row) {
+        return {
+            snapshotId: crypto.randomUUID(),
+            generatedAt,
+            quietEnabled: true,
+            socialDailyLimit: 5,
+            outreachDailyBudget: 2,
+            updatedAt: generatedAt,
+        };
+    }
+    return {
+        snapshotId: crypto.randomUUID(),
+        generatedAt,
+        quietEnabled: row.quietEnabled,
+        socialDailyLimit: row.socialDailyLimit,
+        outreachDailyBudget: row.outreachDailyBudget ?? 2,
+        updatedAt: row.updatedAt,
+    };
+}

package/runtime/storage/services/credential-vault.d.ts

@@ -1,5 +1,10 @@
 import type { StateDatabase } from "../db/index.js";
 import type { CredentialContextWrite, CredentialContext, CredentialState } from "../../shared/types/index.js";
+/** Three colon-separated hex segments produced by `encryptCredentialAtRest`. */
+export declare function isCredentialCiphertext(value: string): boolean;
+/** Encrypts non-empty plaintext; empty string returns empty. */
+export declare function encryptCredentialAtRest(plaintext: string): string;
+export declare function decryptCredentialAtRest(ciphertext: string): string;
 export interface CredentialVault {
     saveCredentialContext(input: CredentialContextWrite): Promise<void>;
     loadCredentialContext(platformId: string): Promise<CredentialContext | null>;

package/runtime/storage/services/credential-vault.js

@@ -1,32 +1,63 @@
+/**
+ * Credential encryption at rest (AES-256-GCM).
+ *
+ * Key material: `SECOND_NATURE_ENCRYPTION_KEY` (UTF-8, first 32 bytes used). Lazy read so tests can set env before first encrypt.
+ * Test coverage: tests/integration/cli/cli-ops-surface.test.ts (credential save path via state-api).
+ */
 import * as crypto from "crypto";
 import { eq } from "drizzle-orm";
 import { credentialRecords } from "../db/schema/index.js";
-const ENCRYPTION_KEY = process.env.SECOND_NATURE_ENCRYPTION_KEY || crypto.randomBytes(32).toString("hex");
 const ALGORITHM = "aes-256-gcm";
-function encrypt(plaintext) {
+function resolveKeyBuffer() {
+    const raw = process.env.SECOND_NATURE_ENCRYPTION_KEY?.trim();
+    if (!raw || raw.length < 32) {
+        throw new Error("SECOND_NATURE_ENCRYPTION_KEY is required for credential encryption at rest (min 32 UTF-8 characters)");
+    }
+    return Buffer.from(raw.slice(0, 32), "utf8");
+}
+function encryptInternal(plaintext) {
     const iv = crypto.randomBytes(16);
-    const key = Buffer.from(ENCRYPTION_KEY.slice(0, 32), "utf8");
+    const key = resolveKeyBuffer();
     const cipher = crypto.createCipheriv(ALGORITHM, key, iv);
     const encrypted = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
     const authTag = cipher.getAuthTag();
     return iv.toString("hex") + ":" + authTag.toString("hex") + ":" + encrypted.toString("hex");
 }
-function decrypt(ciphertext) {
+function decryptInternal(ciphertext) {
     const parts = ciphertext.split(":");
-    if (parts.length !== 3)
-        return ciphertext;
+    if (parts.length !== 3) {
+        throw new Error("credential_ciphertext_invalid_format");
+    }
     const iv = Buffer.from(parts[0], "hex");
     const authTag = Buffer.from(parts[1], "hex");
     const encrypted = Buffer.from(parts[2], "hex");
-    const key = Buffer.from(ENCRYPTION_KEY.slice(0, 32), "utf8");
+    const key = resolveKeyBuffer();
     const decipher = crypto.createDecipheriv(ALGORITHM, key, iv);
     decipher.setAuthTag(authTag);
     return decipher.update(encrypted) + decipher.final("utf8");
 }
+/** Three colon-separated hex segments produced by `encryptCredentialAtRest`. */
+export function isCredentialCiphertext(value) {
+    const parts = value.split(":");
+    if (parts.length !== 3)
+        return false;
+    return parts.every((p) => /^[0-9a-f]+$/i.test(p));
+}
+/** Encrypts non-empty plaintext; empty string returns empty. */
+export function encryptCredentialAtRest(plaintext) {
+    if (!plaintext)
+        return "";
+    return encryptInternal(plaintext);
+}
+export function decryptCredentialAtRest(ciphertext) {
+    if (!ciphertext)
+        return "";
+    return decryptInternal(ciphertext);
+}
 export function createCredentialVault(db) {
     return {
         async saveCredentialContext(input) {
-            const encrypted = input.encryptedValue ? encrypt(input.encryptedValue) : "";
+            const encrypted = input.encryptedValue ? encryptCredentialAtRest(input.encryptedValue) : "";
             await db.insert(credentialRecords).values({
                 platformId: input.platformId,
                 credentialType: input.credentialType,
@@ -57,11 +88,17 @@ export function createCredentialVault(db) {
             });
             if (!record)
                 return null;
+            let plain;
+            if (record.encryptedValue) {
+                plain = isCredentialCiphertext(record.encryptedValue)
+                    ? decryptCredentialAtRest(record.encryptedValue)
+                    : record.encryptedValue;
+            }
             return {
                 platformId: record.platformId,
                 credentialType: record.credentialType,
                 status: record.status,
-                encryptedValue: record.encryptedValue ? decrypt(record.encryptedValue) : undefined,
+                encryptedValue: plain,
                 verificationCode: record.verificationCode ?? undefined,
                 challengeText: record.challengeText ?? undefined,
                 verificationDeadline: record.expiresAt ?? undefined,

package/runtime/storage/snapshots/continuity-snapshot.d.ts

@@ -0,0 +1,9 @@
+import type { ObservabilityDatabase } from "../../observability/db/index.js";
+import type { StateDatabase } from "../db/index.js";
+import type { ContinuitySnapshot } from "./types.js";
+export interface LoadContinuitySnapshotParams {
+    state: StateDatabase;
+    workspaceRoot: string;
+    observability?: ObservabilityDatabase;
+}
+export declare function loadContinuitySnapshot(params: LoadContinuitySnapshotParams): Promise<ContinuitySnapshot>;