@haaaiawd/second-nature 0.1.18 → 0.1.20

package/runtime/observability/audit/append-only-audit-store.js

@@ -1,21 +1,21 @@
-export class AppendOnlyAuditStore {
-    events = [];
-    append(envelope) {
-        const last = this.events[this.events.length - 1];
-        if (last) {
-            if (envelope.integrity.previousHash !== last.integrity.recordHash) {
-                throw new Error("audit_previous_hash_mismatch");
-            }
-        }
-        else if (envelope.integrity.previousHash !== undefined) {
-            throw new Error("audit_genesis_previous_hash");
-        }
-        this.events.push(envelope);
-    }
-    list() {
-        return this.events;
-    }
-    lastRecordHash() {
-        return this.events[this.events.length - 1]?.integrity.recordHash;
-    }
-}
+export class AppendOnlyAuditStore {
+    events = [];
+    append(envelope) {
+        const last = this.events[this.events.length - 1];
+        if (last) {
+            if (envelope.integrity.previousHash !== last.integrity.recordHash) {
+                throw new Error("audit_previous_hash_mismatch");
+            }
+        }
+        else if (envelope.integrity.previousHash !== undefined) {
+            throw new Error("audit_genesis_previous_hash");
+        }
+        this.events.push(envelope);
+    }
+    list() {
+        return this.events;
+    }
+    lastRecordHash() {
+        return this.events[this.events.length - 1]?.integrity.recordHash;
+    }
+}

package/runtime/observability/audit/audit-envelope.d.ts

@@ -1,51 +1,51 @@
-import { type RedactionManifest as FieldRedactionManifest } from "../redaction/manifest.js";
-export type AuditPlane = "decision" | "delivery" | "source_coverage" | "governance" | "telemetry";
-export type AuditEventFamily = "heartbeat.decision" | "delivery" | "source_coverage" | "guidance.grounding" | "host_capability" | "connector.attempt" | "state.governance";
-export type AuditEnvelopeSensitivity = "public" | "internal" | "private" | "credential" | "sensitive";
-export interface AuditRedactionManifest {
-    manifestId: string;
-    maskedPaths: string[];
-    erasedPaths: string[];
-    hashedPaths: string[];
-    contentRefPaths: string[];
-    sensitivity: AuditEnvelopeSensitivity;
-}
-export interface AuditIntegrity {
-    previousHash?: string;
-    recordHash: string;
-    schemaVersion: "observability.v5";
-}
-export interface AuditEnvelope<TPayload> {
-    eventId: string;
-    family: AuditEventFamily;
-    plane: AuditPlane;
-    traceId: string;
-    sequence: number;
-    createdAt: string;
-    payload: TPayload;
-    redaction: AuditRedactionManifest;
-    integrity: AuditIntegrity;
-}
-export interface RedactAuditEventResult<TPayload> {
-    payload: TPayload;
-    redaction: AuditRedactionManifest;
-}
-/**
- * Apply field redaction rules and lift manifests to audit path vocabulary (observability-system.detail §2).
- */
-export declare function redactAuditEvent<TPayload extends object>(payload: TPayload): RedactAuditEventResult<TPayload>;
-export interface BuildAuditEnvelopeInput<TPayload extends object> {
-    family: AuditEventFamily;
-    plane: AuditPlane;
-    traceId: string;
-    sequence: number;
-    payload: TPayload;
-    previousHash?: string;
-    eventId?: string;
-    createdAt?: string;
-}
-/** Recompute integrity hash for an existing envelope (T5.2.2 / verifyAuditHashChain). */
-export declare function computeAuditRecordHash(envelope: AuditEnvelope<unknown>): string;
-export declare function buildAuditEnvelope<TPayload extends object>(input: BuildAuditEnvelopeInput<TPayload>): AuditEnvelope<TPayload>;
-/** @internal Maps legacy field manifest to audit manifest for persistence helpers. */
-export declare function auditManifestFromFieldManifest(manifest: FieldRedactionManifest): AuditRedactionManifest;
+import { type RedactionManifest as FieldRedactionManifest } from "../redaction/manifest.js";
+export type AuditPlane = "decision" | "delivery" | "source_coverage" | "governance" | "telemetry";
+export type AuditEventFamily = "heartbeat.decision" | "delivery" | "source_coverage" | "guidance.grounding" | "host_capability" | "connector.attempt" | "state.governance";
+export type AuditEnvelopeSensitivity = "public" | "internal" | "private" | "credential" | "sensitive";
+export interface AuditRedactionManifest {
+    manifestId: string;
+    maskedPaths: string[];
+    erasedPaths: string[];
+    hashedPaths: string[];
+    contentRefPaths: string[];
+    sensitivity: AuditEnvelopeSensitivity;
+}
+export interface AuditIntegrity {
+    previousHash?: string;
+    recordHash: string;
+    schemaVersion: "observability.v5";
+}
+export interface AuditEnvelope<TPayload> {
+    eventId: string;
+    family: AuditEventFamily;
+    plane: AuditPlane;
+    traceId: string;
+    sequence: number;
+    createdAt: string;
+    payload: TPayload;
+    redaction: AuditRedactionManifest;
+    integrity: AuditIntegrity;
+}
+export interface RedactAuditEventResult<TPayload> {
+    payload: TPayload;
+    redaction: AuditRedactionManifest;
+}
+/**
+ * Apply field redaction rules and lift manifests to audit path vocabulary (observability-system.detail §2).
+ */
+export declare function redactAuditEvent<TPayload extends object>(payload: TPayload): RedactAuditEventResult<TPayload>;
+export interface BuildAuditEnvelopeInput<TPayload extends object> {
+    family: AuditEventFamily;
+    plane: AuditPlane;
+    traceId: string;
+    sequence: number;
+    payload: TPayload;
+    previousHash?: string;
+    eventId?: string;
+    createdAt?: string;
+}
+/** Recompute integrity hash for an existing envelope (T5.2.2 / verifyAuditHashChain). */
+export declare function computeAuditRecordHash(envelope: AuditEnvelope<unknown>): string;
+export declare function buildAuditEnvelope<TPayload extends object>(input: BuildAuditEnvelopeInput<TPayload>): AuditEnvelope<TPayload>;
+/** @internal Maps legacy field manifest to audit manifest for persistence helpers. */
+export declare function auditManifestFromFieldManifest(manifest: FieldRedactionManifest): AuditRedactionManifest;

package/runtime/observability/audit/audit-envelope.js

@@ -1,130 +1,130 @@
-/**
- * Audit envelope construction + redaction for observability-system v5.
- *
- * Core logic: redact structured payloads, attach RedactionManifest (L0/L1 contract paths),
- * compute hash-chain fields for append-only ledger rows.
- *
- * Dependencies: observability redactEvent (field-level); maps to envelope redaction paths.
- *
- * Boundaries: persistence is delegated to AppendOnlyAuditStore / DB adapters.
- *
- * Test coverage: tests/unit/observability/audit-envelope.test.ts
- */
-import * as crypto from "node:crypto";
-import { redactEvent } from "../redaction/manifest.js";
-function fieldPathToAuditPath(field) {
-    if (field.startsWith("/")) {
-        return field;
-    }
-    return `/payload/${field.replace(/\./g, "/")}`;
-}
-function mapSensitivity(level) {
-    switch (level) {
-        case "public":
-            return "public";
-        case "internal":
-            return "internal";
-        case "confidential":
-            return "private";
-        case "restricted":
-            return "sensitive";
-        default:
-            return "internal";
-    }
-}
-/**
- * Apply field redaction rules and lift manifests to audit path vocabulary (observability-system.detail §2).
- */
-export function redactAuditEvent(payload) {
-    const { redacted, manifest } = redactEvent(payload);
-    const redaction = {
-        manifestId: manifest.id,
-        maskedPaths: manifest.maskedFields.map(fieldPathToAuditPath),
-        erasedPaths: manifest.erasedFields.map(fieldPathToAuditPath),
-        hashedPaths: manifest.hashedFields.map(fieldPathToAuditPath),
-        contentRefPaths: [],
-        sensitivity: mapSensitivity(manifest.sensitivityLevel),
-    };
-    return { payload: redacted, redaction };
-}
-function stableStringify(value) {
-    if (value === null || typeof value !== "object") {
-        return JSON.stringify(value);
-    }
-    if (Array.isArray(value)) {
-        return `[${value.map((v) => stableStringify(v)).join(",")}]`;
-    }
-    const obj = value;
-    const keys = Object.keys(obj).sort();
-    return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`).join(",")}}`;
-}
-function hashRecord(input) {
-    const canonical = stableStringify({
-        eventId: input.eventId,
-        family: input.family,
-        plane: input.plane,
-        traceId: input.traceId,
-        sequence: input.sequence,
-        createdAt: input.createdAt,
-        payload: input.payload,
-        redaction: input.redaction,
-        previousHash: input.previousHash ?? null,
-    });
-    return crypto.createHash("sha256").update(canonical, "utf8").digest("hex");
-}
-/** Recompute integrity hash for an existing envelope (T5.2.2 / verifyAuditHashChain). */
-export function computeAuditRecordHash(envelope) {
-    return hashRecord({
-        eventId: envelope.eventId,
-        family: envelope.family,
-        plane: envelope.plane,
-        traceId: envelope.traceId,
-        sequence: envelope.sequence,
-        createdAt: envelope.createdAt,
-        payload: envelope.payload,
-        redaction: envelope.redaction,
-        previousHash: envelope.integrity.previousHash,
-    });
-}
-export function buildAuditEnvelope(input) {
-    const { payload, redaction } = redactAuditEvent(input.payload);
-    const eventId = input.eventId ?? crypto.randomUUID();
-    const createdAt = input.createdAt ?? new Date().toISOString();
-    const recordHash = hashRecord({
-        eventId,
-        family: input.family,
-        plane: input.plane,
-        traceId: input.traceId,
-        sequence: input.sequence,
-        createdAt,
-        payload,
-        redaction,
-        previousHash: input.previousHash,
-    });
-    return {
-        eventId,
-        family: input.family,
-        plane: input.plane,
-        traceId: input.traceId,
-        sequence: input.sequence,
-        createdAt,
-        payload,
-        redaction,
-        integrity: {
-            previousHash: input.previousHash,
-            recordHash,
-            schemaVersion: "observability.v5",
-        },
-    };
-}
-/** @internal Maps legacy field manifest to audit manifest for persistence helpers. */
-export function auditManifestFromFieldManifest(manifest) {
-    return {
-        manifestId: manifest.id,
-        maskedPaths: manifest.maskedFields.map(fieldPathToAuditPath),
-        erasedPaths: manifest.erasedFields.map(fieldPathToAuditPath),
-        hashedPaths: manifest.hashedFields.map(fieldPathToAuditPath),
-        contentRefPaths: [],
-        sensitivity: mapSensitivity(manifest.sensitivityLevel),
-    };
-}
+/**
+ * Audit envelope construction + redaction for observability-system v5.
+ *
+ * Core logic: redact structured payloads, attach RedactionManifest (L0/L1 contract paths),
+ * compute hash-chain fields for append-only ledger rows.
+ *
+ * Dependencies: observability redactEvent (field-level); maps to envelope redaction paths.
+ *
+ * Boundaries: persistence is delegated to AppendOnlyAuditStore / DB adapters.
+ *
+ * Test coverage: tests/unit/observability/audit-envelope.test.ts
+ */
+import * as crypto from "node:crypto";
+import { redactEvent } from "../redaction/manifest.js";
+function fieldPathToAuditPath(field) {
+    if (field.startsWith("/")) {
+        return field;
+    }
+    return `/payload/${field.replace(/\./g, "/")}`;
+}
+function mapSensitivity(level) {
+    switch (level) {
+        case "public":
+            return "public";
+        case "internal":
+            return "internal";
+        case "confidential":
+            return "private";
+        case "restricted":
+            return "sensitive";
+        default:
+            return "internal";
+    }
+}
+/**
+ * Apply field redaction rules and lift manifests to audit path vocabulary (observability-system.detail §2).
+ */
+export function redactAuditEvent(payload) {
+    const { redacted, manifest } = redactEvent(payload);
+    const redaction = {
+        manifestId: manifest.id,
+        maskedPaths: manifest.maskedFields.map(fieldPathToAuditPath),
+        erasedPaths: manifest.erasedFields.map(fieldPathToAuditPath),
+        hashedPaths: manifest.hashedFields.map(fieldPathToAuditPath),
+        contentRefPaths: [],
+        sensitivity: mapSensitivity(manifest.sensitivityLevel),
+    };
+    return { payload: redacted, redaction };
+}
+function stableStringify(value) {
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((v) => stableStringify(v)).join(",")}]`;
+    }
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`).join(",")}}`;
+}
+function hashRecord(input) {
+    const canonical = stableStringify({
+        eventId: input.eventId,
+        family: input.family,
+        plane: input.plane,
+        traceId: input.traceId,
+        sequence: input.sequence,
+        createdAt: input.createdAt,
+        payload: input.payload,
+        redaction: input.redaction,
+        previousHash: input.previousHash ?? null,
+    });
+    return crypto.createHash("sha256").update(canonical, "utf8").digest("hex");
+}
+/** Recompute integrity hash for an existing envelope (T5.2.2 / verifyAuditHashChain). */
+export function computeAuditRecordHash(envelope) {
+    return hashRecord({
+        eventId: envelope.eventId,
+        family: envelope.family,
+        plane: envelope.plane,
+        traceId: envelope.traceId,
+        sequence: envelope.sequence,
+        createdAt: envelope.createdAt,
+        payload: envelope.payload,
+        redaction: envelope.redaction,
+        previousHash: envelope.integrity.previousHash,
+    });
+}
+export function buildAuditEnvelope(input) {
+    const { payload, redaction } = redactAuditEvent(input.payload);
+    const eventId = input.eventId ?? crypto.randomUUID();
+    const createdAt = input.createdAt ?? new Date().toISOString();
+    const recordHash = hashRecord({
+        eventId,
+        family: input.family,
+        plane: input.plane,
+        traceId: input.traceId,
+        sequence: input.sequence,
+        createdAt,
+        payload,
+        redaction,
+        previousHash: input.previousHash,
+    });
+    return {
+        eventId,
+        family: input.family,
+        plane: input.plane,
+        traceId: input.traceId,
+        sequence: input.sequence,
+        createdAt,
+        payload,
+        redaction,
+        integrity: {
+            previousHash: input.previousHash,
+            recordHash,
+            schemaVersion: "observability.v5",
+        },
+    };
+}
+/** @internal Maps legacy field manifest to audit manifest for persistence helpers. */
+export function auditManifestFromFieldManifest(manifest) {
+    return {
+        manifestId: manifest.id,
+        maskedPaths: manifest.maskedFields.map(fieldPathToAuditPath),
+        erasedPaths: manifest.erasedFields.map(fieldPathToAuditPath),
+        hashedPaths: manifest.hashedFields.map(fieldPathToAuditPath),
+        contentRefPaths: [],
+        sensitivity: mapSensitivity(manifest.sensitivityLevel),
+    };
+}

package/runtime/observability/audit/verify-audit-hash-chain.d.ts

@@ -1,23 +1,23 @@
-import type { AppendOnlyAuditStore } from "./append-only-audit-store.js";
-import { type AuditEnvelope, type AuditEventFamily } from "./audit-envelope.js";
-export interface AuditExportRange {
-    from: string;
-    to: string;
-    families?: AuditEventFamily[];
-}
-export type AuditHashChainVerificationStatus = "pass" | "broken" | "incomplete";
-export interface AuditHashChainVerificationReport {
-    reportId: string;
-    generatedAt: string;
-    range: AuditExportRange;
-    checkedEventCount: number;
-    status: AuditHashChainVerificationStatus;
-    brokenAtEventIds: string[];
-    reasons: string[];
-}
-export interface VerifyAuditHashChainDeps {
-    loadRange(from: string, to: string, families?: AuditEventFamily[]): Promise<readonly AuditEnvelope<unknown>[]>;
-}
-export declare function verifyAuditHashChain(range: AuditExportRange, deps: VerifyAuditHashChainDeps): Promise<AuditHashChainVerificationReport>;
-/** In-memory adapter: filter `AppendOnlyAuditStore.list()` by createdAt + optional families. */
-export declare function createAppendOnlyAuditStoreRangeLoader(store: AppendOnlyAuditStore): VerifyAuditHashChainDeps;
+import type { AppendOnlyAuditStore } from "./append-only-audit-store.js";
+import { type AuditEnvelope, type AuditEventFamily } from "./audit-envelope.js";
+export interface AuditExportRange {
+    from: string;
+    to: string;
+    families?: AuditEventFamily[];
+}
+export type AuditHashChainVerificationStatus = "pass" | "broken" | "incomplete";
+export interface AuditHashChainVerificationReport {
+    reportId: string;
+    generatedAt: string;
+    range: AuditExportRange;
+    checkedEventCount: number;
+    status: AuditHashChainVerificationStatus;
+    brokenAtEventIds: string[];
+    reasons: string[];
+}
+export interface VerifyAuditHashChainDeps {
+    loadRange(from: string, to: string, families?: AuditEventFamily[]): Promise<readonly AuditEnvelope<unknown>[]>;
+}
+export declare function verifyAuditHashChain(range: AuditExportRange, deps: VerifyAuditHashChainDeps): Promise<AuditHashChainVerificationReport>;
+/** In-memory adapter: filter `AppendOnlyAuditStore.list()` by createdAt + optional families. */
+export declare function createAppendOnlyAuditStoreRangeLoader(store: AppendOnlyAuditStore): VerifyAuditHashChainDeps;

package/runtime/observability/audit/verify-audit-hash-chain.js

@@ -1,83 +1,83 @@
-/**
- * Range-based hash-chain verification for append-only audit rows (T5.2.2 / INT-S3).
- *
- * Core logic: load events in [from, to], order by sequence, recompute recordHash and
- * verify previousHash links between consecutive **loaded** rows only (partial ranges
- * may start mid-chain; parent outside the slice is not validated). Empty or invalid
- * ranges yield incomplete (T5.2.2 / task verification plan).
- *
- * Dependencies: computeAuditRecordHash from audit-envelope; callers supply loadRange via deps.
- *
- * Test coverage: tests/unit/observability/verify-audit-hash-chain.test.ts
- */
-import * as crypto from "node:crypto";
-import { computeAuditRecordHash } from "./audit-envelope.js";
-function unique(ids) {
-    return [...new Set(ids)];
-}
-export async function verifyAuditHashChain(range, deps) {
-    const generatedAt = new Date().toISOString();
-    const reportId = crypto.randomUUID();
-    if (range.from > range.to) {
-        return {
-            reportId,
-            generatedAt,
-            range,
-            checkedEventCount: 0,
-            status: "incomplete",
-            brokenAtEventIds: [],
-            reasons: ["invalid_range_from_after_to"],
-        };
-    }
-    const raw = await deps.loadRange(range.from, range.to, range.families);
-    const events = [...raw].sort((a, b) => a.sequence - b.sequence);
-    if (events.length === 0) {
-        return {
-            reportId,
-            generatedAt,
-            range,
-            checkedEventCount: 0,
-            status: "incomplete",
-            brokenAtEventIds: [],
-            reasons: ["range_empty"],
-        };
-    }
-    const brokenAtEventIds = [];
-    for (let i = 0; i < events.length; i += 1) {
-        const event = events[i];
-        const expected = computeAuditRecordHash(event);
-        if (event.integrity.recordHash !== expected) {
-            brokenAtEventIds.push(event.eventId);
-        }
-        const prev = events[i - 1];
-        if (prev && event.integrity.previousHash !== prev.integrity.recordHash) {
-            brokenAtEventIds.push(event.eventId);
-        }
-    }
-    const uniq = unique(brokenAtEventIds);
-    const broken = uniq.length > 0;
-    return {
-        reportId,
-        generatedAt,
-        range,
-        checkedEventCount: events.length,
-        status: broken ? "broken" : "pass",
-        brokenAtEventIds: uniq,
-        reasons: broken ? ["hash_chain_broken"] : ["hash_chain_valid"],
-    };
-}
-/** In-memory adapter: filter `AppendOnlyAuditStore.list()` by createdAt + optional families. */
-export function createAppendOnlyAuditStoreRangeLoader(store) {
-    return {
-        async loadRange(from, to, families) {
-            const fams = families?.length ? new Set(families) : undefined;
-            return store.list().filter((e) => {
-                if (e.createdAt < from || e.createdAt > to)
-                    return false;
-                if (fams && !fams.has(e.family))
-                    return false;
-                return true;
-            });
-        },
-    };
-}
+/**
+ * Range-based hash-chain verification for append-only audit rows (T5.2.2 / INT-S3).
+ *
+ * Core logic: load events in [from, to], order by sequence, recompute recordHash and
+ * verify previousHash links between consecutive **loaded** rows only (partial ranges
+ * may start mid-chain; parent outside the slice is not validated). Empty or invalid
+ * ranges yield incomplete (T5.2.2 / task verification plan).
+ *
+ * Dependencies: computeAuditRecordHash from audit-envelope; callers supply loadRange via deps.
+ *
+ * Test coverage: tests/unit/observability/verify-audit-hash-chain.test.ts
+ */
+import * as crypto from "node:crypto";
+import { computeAuditRecordHash } from "./audit-envelope.js";
+function unique(ids) {
+    return [...new Set(ids)];
+}
+export async function verifyAuditHashChain(range, deps) {
+    const generatedAt = new Date().toISOString();
+    const reportId = crypto.randomUUID();
+    if (range.from > range.to) {
+        return {
+            reportId,
+            generatedAt,
+            range,
+            checkedEventCount: 0,
+            status: "incomplete",
+            brokenAtEventIds: [],
+            reasons: ["invalid_range_from_after_to"],
+        };
+    }
+    const raw = await deps.loadRange(range.from, range.to, range.families);
+    const events = [...raw].sort((a, b) => a.sequence - b.sequence);
+    if (events.length === 0) {
+        return {
+            reportId,
+            generatedAt,
+            range,
+            checkedEventCount: 0,
+            status: "incomplete",
+            brokenAtEventIds: [],
+            reasons: ["range_empty"],
+        };
+    }
+    const brokenAtEventIds = [];
+    for (let i = 0; i < events.length; i += 1) {
+        const event = events[i];
+        const expected = computeAuditRecordHash(event);
+        if (event.integrity.recordHash !== expected) {
+            brokenAtEventIds.push(event.eventId);
+        }
+        const prev = events[i - 1];
+        if (prev && event.integrity.previousHash !== prev.integrity.recordHash) {
+            brokenAtEventIds.push(event.eventId);
+        }
+    }
+    const uniq = unique(brokenAtEventIds);
+    const broken = uniq.length > 0;
+    return {
+        reportId,
+        generatedAt,
+        range,
+        checkedEventCount: events.length,
+        status: broken ? "broken" : "pass",
+        brokenAtEventIds: uniq,
+        reasons: broken ? ["hash_chain_broken"] : ["hash_chain_valid"],
+    };
+}
+/** In-memory adapter: filter `AppendOnlyAuditStore.list()` by createdAt + optional families. */
+export function createAppendOnlyAuditStoreRangeLoader(store) {
+    return {
+        async loadRange(from, to, families) {
+            const fams = families?.length ? new Set(families) : undefined;
+            return store.list().filter((e) => {
+                if (e.createdAt < from || e.createdAt > to)
+                    return false;
+                if (fams && !fams.has(e.family))
+                    return false;
+                return true;
+            });
+        },
+    };
+}