@haaaiawd/second-nature 0.1.42 → 0.1.50

package/dist/tests/unit/observability/restore-audit-service.test.js

@@ -0,0 +1,186 @@
+/**
+ * Tests for RestoreAuditService — T-OBS.C.6
+ *
+ * Verification plan §t-obs-c-6:
+ *   1. Successful restore → audit entry with fromVersion / toVersion / reason
+ *   2. Partial restore → isPartialRestore=true + completedEntities + failedEntities
+ *   3. Credential entity excluded → excludedFields listed; credential values absent from payload
+ *   4. Audit write failure → fire-and-forget: result.ok=true + warning; no throw
+ *   5. Hash chain: second audit entry links previousHash to first entry
+ *   6. Audit family is "restore.audit"
+ *   7. completedEntities / failedEntities arrays are faithfully recorded
+ *   8. Credential values never appear in audit store
+ *   9. Audit payload does NOT include actual field values (only metadata)
+ *  10. traceId is propagated into envelope
+ */
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { writeRestoreAudit, } from "../../../src/observability/services/restore-audit-service.js";
+import { AppendOnlyAuditStore } from "../../../src/observability/audit/append-only-audit-store.js";
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function makeEvent(overrides = {}) {
+    return {
+        id: "evt-restore-001",
+        restoreTarget: "narrative",
+        fromVersion: "v1",
+        toVersion: "v2",
+        triggeredBy: "operator",
+        reason: "manual recovery after drift",
+        completedEntities: ["NarrativeState"],
+        failedEntities: [],
+        excludedFields: [],
+        restoredFieldCount: 5,
+        createdAt: "2026-05-01T10:00:00.000Z",
+        traceId: "trace-abc-001",
+        ...overrides,
+    };
+}
+// ─── Tests ───────────────────────────────────────────────────────────────────
+describe("writeRestoreAudit — successful restore", () => {
+    it("writes audit entry with fromVersion / toVersion / reason", async () => {
+        const store = new AppendOnlyAuditStore();
+        const event = makeEvent();
+        const result = await writeRestoreAudit(event, store);
+        assert.equal(result.ok, true);
+        assert.deepEqual(result.warnings, []);
+        const entries = store.list();
+        assert.equal(entries.length, 1);
+        const payload = entries[0].payload;
+        assert.equal(payload.fromVersion, "v1");
+        assert.equal(payload.toVersion, "v2");
+        assert.equal(payload.reason, "manual recovery after drift");
+        assert.equal(payload.restoreTarget, "narrative");
+        assert.equal(payload.triggeredBy, "operator");
+    });
+    it("audit family is 'restore.audit'", async () => {
+        const store = new AppendOnlyAuditStore();
+        await writeRestoreAudit(makeEvent(), store);
+        const entries = store.list();
+        assert.equal(entries[0].family, "restore.audit");
+    });
+    it("audit plane is 'governance'", async () => {
+        const store = new AppendOnlyAuditStore();
+        await writeRestoreAudit(makeEvent(), store);
+        assert.equal(store.list()[0].plane, "governance");
+    });
+    it("traceId is propagated into envelope", async () => {
+        const store = new AppendOnlyAuditStore();
+        await writeRestoreAudit(makeEvent({ traceId: "trace-xyz-999" }), store);
+        assert.equal(store.list()[0].traceId, "trace-xyz-999");
+    });
+    it("restoredFieldCount is included in payload", async () => {
+        const store = new AppendOnlyAuditStore();
+        await writeRestoreAudit(makeEvent({ restoredFieldCount: 7 }), store);
+        const payload = store.list()[0].payload;
+        assert.equal(payload.restoredFieldCount, 7);
+    });
+});
+describe("writeRestoreAudit — partial restore", () => {
+    it("partial restore → isPartialRestore=true + completedEntities + failedEntities", async () => {
+        const store = new AppendOnlyAuditStore();
+        const event = makeEvent({
+            completedEntities: ["NarrativeState", "GoalLifecycle"],
+            failedEntities: ["IdentityProfile"],
+        });
+        const result = await writeRestoreAudit(event, store);
+        assert.equal(result.ok, true);
+        const payload = store.list()[0].payload;
+        assert.equal(payload.isPartialRestore, true);
+        assert.deepEqual(payload.completedEntities, ["NarrativeState", "GoalLifecycle"]);
+        assert.deepEqual(payload.failedEntities, ["IdentityProfile"]);
+    });
+    it("full restore → isPartialRestore=false", async () => {
+        const store = new AppendOnlyAuditStore();
+        await writeRestoreAudit(makeEvent({ completedEntities: ["NarrativeState"], failedEntities: [] }), store);
+        const payload = store.list()[0].payload;
+        assert.equal(payload.isPartialRestore, false);
+    });
+    it("completedEntities / failedEntities arrays faithfully recorded", async () => {
+        const store = new AppendOnlyAuditStore();
+        await writeRestoreAudit(makeEvent({
+            completedEntities: ["A", "B", "C"],
+            failedEntities: ["D", "E"],
+        }), store);
+        const payload = store.list()[0].payload;
+        assert.deepEqual(payload.completedEntities, ["A", "B", "C"]);
+        assert.deepEqual(payload.failedEntities, ["D", "E"]);
+    });
+});
+describe("writeRestoreAudit — credential exclusion", () => {
+    it("excludedFields listed in audit; credential values absent from payload", async () => {
+        const store = new AppendOnlyAuditStore();
+        const event = makeEvent({
+            excludedFields: ["encryption_key", "credential_value", "token"],
+        });
+        await writeRestoreAudit(event, store);
+        const payload = store.list()[0].payload;
+        // Field names should be listed
+        assert.deepEqual(payload.excludedFields, [
+            "encryption_key",
+            "credential_value",
+            "token",
+        ]);
+        // The actual values should NOT appear
+        const payloadStr = JSON.stringify(payload).toLowerCase();
+        const forbidden = ["secret", "password", "key_value", "raw_key"];
+        for (const f of forbidden) {
+            assert.ok(!payloadStr.includes(f), `payload must not contain "${f}"`);
+        }
+    });
+    it("audit payload has no actual field values — only metadata", async () => {
+        const store = new AppendOnlyAuditStore();
+        await writeRestoreAudit(makeEvent({
+            excludedFields: ["secret_key"],
+            completedEntities: ["NarrativeState"],
+        }), store);
+        const payload = store.list()[0].payload;
+        // Allowed metadata keys in payload
+        const allowedKeys = [
+            "restoreTarget",
+            "fromVersion",
+            "toVersion",
+            "triggeredBy",
+            "reason",
+            "completedEntities",
+            "failedEntities",
+            "excludedFields",
+            "restoredFieldCount",
+            "isPartialRestore",
+            "createdAt",
+        ];
+        const payloadKeys = Object.keys(payload);
+        for (const key of payloadKeys) {
+            assert.ok(allowedKeys.includes(key), `unexpected payload key "${key}" — actual field values must not be stored`);
+        }
+    });
+});
+describe("writeRestoreAudit — fire-and-forget failure", () => {
+    it("audit store append failure → ok=true + warning; no throw", async () => {
+        // Create a store with a broken append that throws
+        const store = new AppendOnlyAuditStore();
+        // Inject a first entry then seed a different hash to cause mismatch
+        // (simulates hash chain corruption)
+        const brokenStore = {
+            list: () => [],
+            lastRecordHash: () => "nonexistent_hash",
+            append: () => { throw new Error("audit_previous_hash_mismatch"); },
+            seedFamilyHash: () => { },
+        };
+        const result = await writeRestoreAudit(makeEvent(), brokenStore);
+        assert.equal(result.ok, true, "ok must be true even when audit fails");
+        assert.equal(result.warnings.length, 1);
+        assert.ok(result.warnings[0].startsWith("audit_write_failed:"), `warning should start with 'audit_write_failed:', got: ${result.warnings[0]}`);
+    });
+});
+describe("writeRestoreAudit — hash chain", () => {
+    it("second audit entry previousHash links to first entry", async () => {
+        const store = new AppendOnlyAuditStore();
+        await writeRestoreAudit(makeEvent({ id: "evt-001", traceId: "trace-1" }), store);
+        await writeRestoreAudit(makeEvent({ id: "evt-002", traceId: "trace-2", createdAt: "2026-05-01T10:01:00.000Z" }), store);
+        const entries = store.list();
+        assert.equal(entries.length, 2);
+        const firstHash = entries[0].integrity.recordHash;
+        const secondPreviousHash = entries[1].integrity.previousHash;
+        assert.equal(secondPreviousHash, firstHash, "second entry previousHash must equal first entry recordHash");
+    });
+});

package/dist/tests/unit/observability/runtime-decision-recorder.test.d.ts

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

package/dist/tests/unit/observability/runtime-decision-recorder.test.js

@@ -0,0 +1,66 @@
+/**
+ * Unit coverage for `createRuntimeDecisionRecorder` (T1.2.3).
+ *
+ * Verifies trace prefix, platformId, mode default, and failure mapping for the
+ * observability writeback path that powers `loadStatus` aggregation.
+ */
+import test from "node:test";
+import assert from "node:assert/strict";
+import { desc, eq } from "drizzle-orm";
+import { createObservabilityDatabase } from "../../../src/observability/db/index.js";
+import { createRuntimeDecisionRecorder, RUNTIME_DECISION_TRACE_PREFIX, RUNTIME_INTERNAL_PLATFORM_ID, } from "../../../src/observability/services/runtime-decision-recorder.js";
+import { decisionLedger, executionAttempts } from "../../../src/observability/db/schema/index.js";
+function makeSignal(timestamp = "2026-05-09T10:00:00.000Z") {
+    return {
+        trigger: "heartbeat_bridge",
+        payload: { timestamp },
+    };
+}
+test("T1.2.3 recorder writes sn-runtime trace + second-nature-runtime attempt with succeeded status", async () => {
+    const db = createObservabilityDatabase(":memory:");
+    const recorder = createRuntimeDecisionRecorder(db);
+    const cycle = {
+        scope: "rhythm",
+        status: "heartbeat_ok",
+        reasons: ["silent_no_candidates"],
+    };
+    const out = await recorder.recordHeartbeatCycle({ cycle, signal: makeSignal() });
+    assert.ok(out.traceId.startsWith(RUNTIME_DECISION_TRACE_PREFIX));
+    const ledgerRow = (await db.db.select().from(decisionLedger).where(eq(decisionLedger.traceId, out.traceId)).limit(1))[0];
+    assert.ok(ledgerRow, "ledger row must exist");
+    assert.equal(ledgerRow.mode, "active", "default mode must be active so loadStatus exits unknown for rhythm");
+    const attemptRow = (await db.db.select().from(executionAttempts).where(eq(executionAttempts.traceId, out.traceId)).limit(1))[0];
+    assert.ok(attemptRow, "execution_attempts row must exist");
+    assert.equal(attemptRow.platformId, RUNTIME_INTERNAL_PLATFORM_ID);
+    assert.equal(attemptRow.status, "succeeded", "non-failure cycle must produce succeeded attempt");
+    assert.equal(attemptRow.failureClass, null);
+});
+test("T1.2.3 recorder marks delivery_unavailable cycles as failed with delivery_unavailable failureClass", async () => {
+    const db = createObservabilityDatabase(":memory:");
+    const recorder = createRuntimeDecisionRecorder(db);
+    const cycle = {
+        scope: "rhythm",
+        status: "delivery_unavailable",
+        reasons: ["delivery_target_none"],
+    };
+    const out = await recorder.recordHeartbeatCycle({ cycle, signal: makeSignal() });
+    const attemptRow = (await db.db.select().from(executionAttempts).where(eq(executionAttempts.traceId, out.traceId)).limit(1))[0];
+    assert.equal(attemptRow.status, "failed");
+    assert.equal(attemptRow.failureClass, "delivery_unavailable");
+});
+test("T1.2.3 recorder respects rhythmMode override (Quiet semantics propagate to status.quiet)", async () => {
+    const db = createObservabilityDatabase(":memory:");
+    const recorder = createRuntimeDecisionRecorder(db);
+    const cycle = {
+        scope: "rhythm",
+        status: "heartbeat_ok",
+        reasons: ["quiet_window"],
+    };
+    await recorder.recordHeartbeatCycle({
+        cycle,
+        signal: makeSignal(),
+        rhythmMode: "quiet",
+    });
+    const latest = (await db.db.select().from(decisionLedger).orderBy(desc(decisionLedger.createdAt)).limit(1))[0];
+    assert.equal(latest.mode, "quiet");
+});

package/dist/tests/unit/observability/runtime-secret-anchor-view.test.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Tests for RuntimeSecretAnchorView — T-OBS.C.7
+ *
+ * Verification plan §t-obs-c-7:
+ *   1. wrong key → status=wrong_key, reasonCode=credential_recovery_required, recoverySteps populated
+ *   2. new workspace (no key anchor) → status=missing, reasonCode=runtime_secret_anchor_missing
+ *   3. key exists + decrypt ok → status=verified, no reasonCode
+ *   4. decrypt throws → status=decryption_failed, reasonCode=runtime_secret_unavailable
+ *   5. decrypt returns error status → status=decryption_failed, reasonCode=runtime_secret_unavailable
+ *   6. return value NEVER contains plaintext key fields (field enumeration check — ADR-007)
+ *   7. checkedCredentialIds present and NOT containing key values (structural check)
+ *   8. recoverySteps is non-empty array when status ≠ verified
+ *   9. recoverySteps is empty array when status = verified
+ *  10. keyPath echoes port value (path only, not value)
+ *  11. lastCheckedAt uses injected now()
+ *  12. checkKeyPathExists throws → treated as missing
+ */
+export {};

package/dist/tests/unit/observability/runtime-secret-anchor-view.test.js

@@ -0,0 +1,209 @@
+/**
+ * Tests for RuntimeSecretAnchorView — T-OBS.C.7
+ *
+ * Verification plan §t-obs-c-7:
+ *   1. wrong key → status=wrong_key, reasonCode=credential_recovery_required, recoverySteps populated
+ *   2. new workspace (no key anchor) → status=missing, reasonCode=runtime_secret_anchor_missing
+ *   3. key exists + decrypt ok → status=verified, no reasonCode
+ *   4. decrypt throws → status=decryption_failed, reasonCode=runtime_secret_unavailable
+ *   5. decrypt returns error status → status=decryption_failed, reasonCode=runtime_secret_unavailable
+ *   6. return value NEVER contains plaintext key fields (field enumeration check — ADR-007)
+ *   7. checkedCredentialIds present and NOT containing key values (structural check)
+ *   8. recoverySteps is non-empty array when status ≠ verified
+ *   9. recoverySteps is empty array when status = verified
+ *  10. keyPath echoes port value (path only, not value)
+ *  11. lastCheckedAt uses injected now()
+ *  12. checkKeyPathExists throws → treated as missing
+ */
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { viewSecretAnchor, } from "../../../src/observability/services/runtime-secret-anchor-view.js";
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+const FIXED_NOW = "2026-05-01T00:00:00.000Z";
+const FAKE_KEY_PATH = "SECOND_NATURE_ENCRYPTION_KEY";
+function makeDeps(opts) {
+    return {
+        runtimeOpsPort: {
+            getEncryptionKeyPath: () => FAKE_KEY_PATH,
+            checkKeyPathExists: async () => {
+                if (opts.keyPathThrows)
+                    throw new Error("checkKeyPathExists_failed");
+                return opts.keyExists;
+            },
+        },
+        credentialPort: {
+            verifySampleDecrypt: async () => {
+                if (!opts.sampleDecrypt) {
+                    return { status: "ok", checkedIds: ["cred-1"] };
+                }
+                if (typeof opts.sampleDecrypt === "function") {
+                    return opts.sampleDecrypt();
+                }
+                return opts.sampleDecrypt;
+            },
+        },
+        now: () => FIXED_NOW,
+    };
+}
+// ─── Tests ───────────────────────────────────────────────────────────────────
+describe("viewSecretAnchor — happy path", () => {
+    it("key exists + decrypt ok → status=verified, no reasonCode", async () => {
+        const deps = makeDeps({
+            keyExists: true,
+            sampleDecrypt: { status: "ok", checkedIds: ["cred-1", "cred-2"] },
+        });
+        const view = await viewSecretAnchor(deps);
+        assert.equal(view.status, "verified");
+        assert.equal(view.reasonCode, undefined);
+        assert.deepEqual(view.checkedCredentialIds, ["cred-1", "cred-2"]);
+        assert.deepEqual(view.recoverySteps, []);
+    });
+});
+describe("viewSecretAnchor — missing key scenarios", () => {
+    it("keyExists=false → status=missing, reasonCode=runtime_secret_anchor_missing", async () => {
+        const deps = makeDeps({ keyExists: false });
+        const view = await viewSecretAnchor(deps);
+        assert.equal(view.status, "missing");
+        assert.equal(view.reasonCode, "runtime_secret_anchor_missing");
+        assert.ok(view.recoverySteps.length > 0, "should have recovery steps");
+        // recoverySteps should guide setting the env var
+        const actions = view.recoverySteps.map((s) => s.action).join(" ");
+        assert.ok(actions.toLowerCase().includes("key") ||
+            actions.toLowerCase().includes("environment") ||
+            actions.toLowerCase().includes("bootstrap"), "recovery steps should mention key or environment setup");
+    });
+    it("checkKeyPathExists throws → treated as missing", async () => {
+        const deps = makeDeps({ keyExists: false, keyPathThrows: true });
+        const view = await viewSecretAnchor(deps);
+        assert.equal(view.status, "missing");
+        assert.equal(view.reasonCode, "runtime_secret_anchor_missing");
+    });
+});
+describe("viewSecretAnchor — wrong key", () => {
+    it("wrong key → status=wrong_key, reasonCode=credential_recovery_required", async () => {
+        const deps = makeDeps({
+            keyExists: true,
+            sampleDecrypt: { status: "wrong_key", checkedIds: ["cred-1"] },
+        });
+        const view = await viewSecretAnchor(deps);
+        assert.equal(view.status, "wrong_key");
+        assert.equal(view.reasonCode, "credential_recovery_required");
+        assert.ok(view.recoverySteps.length > 0, "should have recovery steps");
+        assert.deepEqual(view.checkedCredentialIds, ["cred-1"]);
+    });
+});
+describe("viewSecretAnchor — unavailable / error scenarios", () => {
+    it("verifySampleDecrypt throws → status=decryption_failed, reasonCode=runtime_secret_unavailable", async () => {
+        const deps = {
+            runtimeOpsPort: {
+                getEncryptionKeyPath: () => FAKE_KEY_PATH,
+                checkKeyPathExists: async () => true,
+            },
+            credentialPort: {
+                verifySampleDecrypt: async () => {
+                    throw new Error("decrypt_subsystem_crashed");
+                },
+            },
+            now: () => FIXED_NOW,
+        };
+        const view = await viewSecretAnchor(deps);
+        assert.equal(view.status, "decryption_failed");
+        assert.equal(view.reasonCode, "runtime_secret_unavailable");
+        assert.ok(view.recoverySteps.length > 0);
+    });
+    it("sampleDecrypt returns error status → status=decryption_failed, reasonCode=runtime_secret_unavailable", async () => {
+        const deps = makeDeps({
+            keyExists: true,
+            sampleDecrypt: { status: "error", checkedIds: [] },
+        });
+        const view = await viewSecretAnchor(deps);
+        assert.equal(view.status, "decryption_failed");
+        assert.equal(view.reasonCode, "runtime_secret_unavailable");
+    });
+});
+describe("viewSecretAnchor — security invariants (ADR-007)", () => {
+    const FORBIDDEN_FIELD_NAMES = [
+        "key",
+        "secret",
+        "token",
+        "password",
+        "value",
+        "plaintext",
+        "keyValue",
+        "rawKey",
+        "encryptionKey",
+        "keyMaterial",
+    ];
+    it("return value NEVER contains plaintext key fields", async () => {
+        const deps = makeDeps({
+            keyExists: true,
+            sampleDecrypt: { status: "ok", checkedIds: ["cred-1"] },
+        });
+        const view = await viewSecretAnchor(deps);
+        // Enumerate all keys in the returned object — none should be forbidden field names
+        const allKeys = Object.keys(view).map((k) => k.toLowerCase());
+        for (const forbidden of FORBIDDEN_FIELD_NAMES) {
+            assert.ok(!allKeys.includes(forbidden), `view must not contain field "${forbidden}"`);
+        }
+    });
+    it("missing key view also has no forbidden fields", async () => {
+        const deps = makeDeps({ keyExists: false });
+        const view = await viewSecretAnchor(deps);
+        const allKeys = Object.keys(view).map((k) => k.toLowerCase());
+        for (const forbidden of FORBIDDEN_FIELD_NAMES) {
+            assert.ok(!allKeys.includes(forbidden), `view must not contain field "${forbidden}"`);
+        }
+    });
+    it("keyPath is the path string, not a value (structural check)", async () => {
+        const deps = makeDeps({ keyExists: false });
+        const view = await viewSecretAnchor(deps);
+        // Should be the key path (env var name), which is short and does not look like a secret
+        assert.equal(view.keyPath, FAKE_KEY_PATH);
+        // Must not be a long random-looking string (like a real key)
+        assert.ok(view.keyPath.length < 100, "keyPath should be a short env var name, not a long key value");
+    });
+});
+describe("viewSecretAnchor — recovery steps", () => {
+    it("recoverySteps is non-empty when status is missing", async () => {
+        const view = await viewSecretAnchor(makeDeps({ keyExists: false }));
+        assert.ok(view.recoverySteps.length > 0);
+        assert.ok(view.recoverySteps.every((s) => typeof s.step === "number" && typeof s.action === "string"), "each recovery step must have step number and action string");
+    });
+    it("recoverySteps is non-empty when status is wrong_key", async () => {
+        const view = await viewSecretAnchor(makeDeps({ keyExists: true, sampleDecrypt: { status: "wrong_key", checkedIds: [] } }));
+        assert.ok(view.recoverySteps.length > 0);
+    });
+    it("recoverySteps is empty array when status is verified", async () => {
+        const view = await viewSecretAnchor(makeDeps({ keyExists: true, sampleDecrypt: { status: "ok", checkedIds: ["c1"] } }));
+        assert.deepEqual(view.recoverySteps, []);
+    });
+    it("recovery steps are ordered by step number", async () => {
+        const view = await viewSecretAnchor(makeDeps({ keyExists: false }));
+        const steps = view.recoverySteps;
+        for (let i = 0; i < steps.length - 1; i++) {
+            assert.ok(steps[i].step < steps[i + 1].step, "recovery steps should be in ascending step order");
+        }
+    });
+});
+describe("viewSecretAnchor — metadata", () => {
+    it("uses injected now() for lastCheckedAt", async () => {
+        const deps = makeDeps({ keyExists: false });
+        const view = await viewSecretAnchor(deps);
+        assert.equal(view.lastCheckedAt, FIXED_NOW);
+    });
+    it("keyPath matches value returned by getEncryptionKeyPath()", async () => {
+        const deps = makeDeps({ keyExists: true });
+        const view = await viewSecretAnchor(deps);
+        assert.equal(view.keyPath, FAKE_KEY_PATH);
+    });
+    it("recoveryDocRef is always set", async () => {
+        const view1 = await viewSecretAnchor(makeDeps({ keyExists: false }));
+        const view2 = await viewSecretAnchor(makeDeps({ keyExists: true, sampleDecrypt: { status: "ok", checkedIds: [] } }));
+        assert.ok(view1.recoveryDocRef.length > 0);
+        assert.ok(view2.recoveryDocRef.length > 0);
+    });
+    it("anchorId is always 'primary'", async () => {
+        const view = await viewSecretAnchor(makeDeps({ keyExists: false }));
+        assert.equal(view.anchorId, "primary");
+    });
+});

package/dist/tests/unit/observability/self-health-snapshot.test.d.ts

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