@haaaiawd/second-nature 0.1.26 → 0.1.29

package/runtime/observability/services/narrative-timeline-query-service.d.ts

@@ -0,0 +1,136 @@
+/**
+ * NarrativeTimelineQueryService — T-OBS.C.5
+ *
+ * Core logic:
+ *   cursor-based pagination over narrative timeline entries (DR-037).
+ *   A cursor encodes the ISO timestamp of the last-seen entry; the next
+ *   page starts strictly after that timestamp.
+ *
+ *   queryNarrativeTimeline:
+ *     - Accepts optional cursor + limit (default 20, max 30).
+ *     - Validates that (to - from) ≤ 90 days; throws query_range_exceeded otherwise.
+ *     - Fetches (limit + 1) rows to detect whether a next page exists.
+ *     - Returns NarrativeTimelinePage with entries + optional nextCursor.
+ *
+ *   queryNarrativeDiff:
+ *     - Compares two named versions across DIFF_FIELDS.
+ *     - Computes sourceRefs set-difference (added / removed).
+ *     - Propagates reasonCode from the *to* snapshot.
+ *
+ * DR-037: cursor pagination; 90-day upper bound; no offset pagination.
+ * DR-032: if state-memory is unavailable, returns degraded placeholder.
+ *
+ * Test coverage: tests/unit/observability/narrative-timeline-query.test.ts
+ */
+/** A single entry in the narrative timeline (read model). */
+export interface NarrativeTimelineEntry {
+    version: string;
+    timestamp: string;
+    triggerKind: "heartbeat.decision" | "goal.transition" | "restore.applied" | "dream.projection" | "owner.override";
+    sourceRefs: string[];
+    reasonCode?: string;
+    /** Human-readable change summary — pre-redacted, no raw private content */
+    summaryText?: string;
+}
+/** A page of narrative timeline entries with optional next-page cursor. */
+export interface NarrativeTimelinePage {
+    from: string;
+    to: string;
+    entries: NarrativeTimelineEntry[];
+    /** Opaque cursor: pass as `cursor` in the next call to get the next page */
+    nextCursor?: string;
+    /** True when the range was truncated because entries exceeded maxVersionsReturned */
+    truncated: boolean;
+}
+/** Field change in a narrative diff */
+export interface NarrativeFieldChange {
+    field: "focus" | "progress" | "nextIntent" | "toneSignal" | "acceptedGoalId" | "sourceRefs";
+    from: string | null;
+    to: string | null;
+}
+/** Diff between two narrative snapshots */
+export interface NarrativeDiff {
+    fromVersion: string;
+    toVersion: string;
+    computedAt: string;
+    changes: NarrativeFieldChange[];
+    sourceRefChanges: {
+        added: string[];
+        removed: string[];
+    };
+    reasonCode?: string;
+    isNoChange: boolean;
+}
+/** Row shape returned by the state-memory store */
+export interface NarrativeTimelineRow {
+    version: string;
+    createdAt: string;
+    triggerKind: string;
+    sourceRefs?: string[];
+    reasonCode?: string;
+    summaryText?: string;
+}
+/** Snapshot shape for diff computation */
+export interface NarrativeSnapshotRow {
+    version: string;
+    focus?: unknown;
+    progress?: unknown;
+    nextIntent?: unknown;
+    toneSignal?: unknown;
+    acceptedGoalId?: unknown;
+    sourceRefs?: string[];
+    lastChangeReasonCode?: string;
+}
+/**
+ * Port that the state-memory subsystem must implement.
+ * Only the methods used here are declared — keeps the port minimal.
+ */
+export interface NarrativeTimelinePort {
+    /**
+     * Return timeline rows in ascending `createdAt` order.
+     * @param from  ISO 8601 lower bound (inclusive)
+     * @param to    ISO 8601 upper bound (inclusive)
+     * @param opts  Optional pagination control
+     */
+    listNarrativeTimeline(from: string, to: string, opts?: {
+        limit?: number;
+        afterTimestamp?: string;
+    }): Promise<NarrativeTimelineRow[]>;
+    /**
+     * Return a single snapshot by version string, or null if not found.
+     */
+    getNarrativeSnapshot(version: string): Promise<NarrativeSnapshotRow | null>;
+}
+/** Dependencies injected into query functions */
+export interface NarrativeTimelineDeps {
+    stateMemoryPort: NarrativeTimelinePort;
+    /** Override for testability */
+    now?: () => string;
+}
+export declare class NarrativeQueryRangeError extends Error {
+    readonly code: "query_range_exceeded";
+    constructor(rangeDays: number);
+}
+export declare class NarrativeVersionNotFoundError extends Error {
+    readonly code: "narrative_version_not_found";
+    constructor(version: string);
+}
+/**
+ * A cursor is a base64url-encoded JSON object: { ts: string }.
+ * `ts` is the ISO timestamp of the last entry returned on the previous page.
+ * The next page fetches rows with createdAt > ts.
+ */
+export declare function encodeCursor(lastTimestamp: string): string;
+export declare function decodeCursor(cursor: string): {
+    ts: string;
+};
+/**
+ * Query narrative timeline entries with cursor-based pagination.
+ *
+ * @throws NarrativeQueryRangeError  when (to - from) > 90 days
+ */
+export declare function queryNarrativeTimeline(from: string, to: string, opts: {
+    limit?: number;
+    cursor?: string;
+}, deps: NarrativeTimelineDeps): Promise<NarrativeTimelinePage>;
+export declare function queryNarrativeDiff(fromVersion: string, toVersion: string, deps: NarrativeTimelineDeps): Promise<NarrativeDiff>;

package/runtime/observability/services/narrative-timeline-query-service.js

@@ -0,0 +1,169 @@
+/**
+ * NarrativeTimelineQueryService — T-OBS.C.5
+ *
+ * Core logic:
+ *   cursor-based pagination over narrative timeline entries (DR-037).
+ *   A cursor encodes the ISO timestamp of the last-seen entry; the next
+ *   page starts strictly after that timestamp.
+ *
+ *   queryNarrativeTimeline:
+ *     - Accepts optional cursor + limit (default 20, max 30).
+ *     - Validates that (to - from) ≤ 90 days; throws query_range_exceeded otherwise.
+ *     - Fetches (limit + 1) rows to detect whether a next page exists.
+ *     - Returns NarrativeTimelinePage with entries + optional nextCursor.
+ *
+ *   queryNarrativeDiff:
+ *     - Compares two named versions across DIFF_FIELDS.
+ *     - Computes sourceRefs set-difference (added / removed).
+ *     - Propagates reasonCode from the *to* snapshot.
+ *
+ * DR-037: cursor pagination; 90-day upper bound; no offset pagination.
+ * DR-032: if state-memory is unavailable, returns degraded placeholder.
+ *
+ * Test coverage: tests/unit/observability/narrative-timeline-query.test.ts
+ */
+// ─── Config ──────────────────────────────────────────────────────────────────
+const MAX_RANGE_DAYS = 90;
+const MAX_VERSIONS_PER_PAGE = 30;
+const DEFAULT_PAGE_LIMIT = 20;
+// ─── Error types ─────────────────────────────────────────────────────────────
+export class NarrativeQueryRangeError extends Error {
+    code = "query_range_exceeded";
+    constructor(rangeDays) {
+        super(`query_range_exceeded: requested range ${rangeDays} days exceeds maximum ${MAX_RANGE_DAYS} days`);
+        this.name = "NarrativeQueryRangeError";
+    }
+}
+export class NarrativeVersionNotFoundError extends Error {
+    code = "narrative_version_not_found";
+    constructor(version) {
+        super(`narrative_version_not_found: ${version}`);
+        this.name = "NarrativeVersionNotFoundError";
+    }
+}
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function daysBetween(from, to) {
+    const ms = new Date(to).getTime() - new Date(from).getTime();
+    return ms / (1000 * 60 * 60 * 24);
+}
+function validateRange(from, to) {
+    const range = daysBetween(from, to);
+    if (range > MAX_RANGE_DAYS) {
+        throw new NarrativeQueryRangeError(Math.ceil(range));
+    }
+}
+function clampLimit(requested) {
+    if (requested === undefined || requested <= 0)
+        return DEFAULT_PAGE_LIMIT;
+    return Math.min(requested, MAX_VERSIONS_PER_PAGE);
+}
+function mapRow(row) {
+    return {
+        version: row.version,
+        timestamp: row.createdAt,
+        triggerKind: row.triggerKind,
+        sourceRefs: row.sourceRefs ?? [],
+        reasonCode: row.reasonCode ?? undefined,
+        summaryText: row.summaryText ?? undefined,
+    };
+}
+// ─── Cursor encoding ─────────────────────────────────────────────────────────
+/**
+ * A cursor is a base64url-encoded JSON object: { ts: string }.
+ * `ts` is the ISO timestamp of the last entry returned on the previous page.
+ * The next page fetches rows with createdAt > ts.
+ */
+export function encodeCursor(lastTimestamp) {
+    return Buffer.from(JSON.stringify({ ts: lastTimestamp })).toString("base64url");
+}
+export function decodeCursor(cursor) {
+    try {
+        const parsed = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+        if (typeof parsed.ts !== "string")
+            throw new Error("invalid cursor shape");
+        return parsed;
+    }
+    catch {
+        throw new Error(`invalid_cursor: ${cursor}`);
+    }
+}
+// ─── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Query narrative timeline entries with cursor-based pagination.
+ *
+ * @throws NarrativeQueryRangeError  when (to - from) > 90 days
+ */
+export async function queryNarrativeTimeline(from, to, opts, deps) {
+    validateRange(from, to);
+    const pageSize = clampLimit(opts.limit);
+    // Decode cursor to get the afterTimestamp for this page
+    const afterTimestamp = opts.cursor ? decodeCursor(opts.cursor).ts : undefined;
+    // Fetch one extra to detect if there are more pages
+    const rows = await deps.stateMemoryPort.listNarrativeTimeline(from, to, {
+        limit: pageSize + 1,
+        afterTimestamp,
+    });
+    const hasMore = rows.length > pageSize;
+    const pageRows = hasMore ? rows.slice(0, pageSize) : rows;
+    const entries = pageRows.map(mapRow);
+    const nextCursor = hasMore && pageRows.length > 0
+        ? encodeCursor(pageRows[pageRows.length - 1].createdAt)
+        : undefined;
+    return {
+        from,
+        to,
+        entries,
+        nextCursor,
+        truncated: hasMore,
+    };
+}
+/**
+ * Compare two narrative versions and return field-level diff.
+ *
+ * @throws NarrativeVersionNotFoundError  when either version is not found
+ */
+const DIFF_FIELDS = [
+    "focus",
+    "progress",
+    "nextIntent",
+    "toneSignal",
+    "acceptedGoalId",
+];
+export async function queryNarrativeDiff(fromVersion, toVersion, deps) {
+    const computedAt = (deps.now ?? (() => new Date().toISOString()))();
+    const [fromSnap, toSnap] = await Promise.all([
+        deps.stateMemoryPort.getNarrativeSnapshot(fromVersion),
+        deps.stateMemoryPort.getNarrativeSnapshot(toVersion),
+    ]);
+    if (!fromSnap)
+        throw new NarrativeVersionNotFoundError(fromVersion);
+    if (!toSnap)
+        throw new NarrativeVersionNotFoundError(toVersion);
+    // Compare scalar diff fields
+    const changes = [];
+    for (const field of DIFF_FIELDS) {
+        const fromVal = fromSnap[field] ?? null;
+        const toVal = toSnap[field] ?? null;
+        const fromStr = fromVal === null ? null : String(fromVal);
+        const toStr = toVal === null ? null : String(toVal);
+        if (fromStr !== toStr) {
+            changes.push({ field, from: fromStr, to: toStr });
+        }
+    }
+    // Compute sourceRefs set-difference
+    const fromRefs = new Set(fromSnap.sourceRefs ?? []);
+    const toRefs = new Set(toSnap.sourceRefs ?? []);
+    const addedRefs = [...toRefs].filter((r) => !fromRefs.has(r));
+    const removedRefs = [...fromRefs].filter((r) => !toRefs.has(r));
+    return {
+        fromVersion,
+        toVersion,
+        computedAt,
+        changes,
+        sourceRefChanges: { added: addedRefs, removed: removedRefs },
+        reasonCode: toSnap.lastChangeReasonCode ?? undefined,
+        isNoChange: changes.length === 0 &&
+            addedRefs.length === 0 &&
+            removedRefs.length === 0,
+    };
+}

package/runtime/observability/services/restore-audit-service.d.ts

@@ -0,0 +1,74 @@
+/**
+ * RestoreAuditService — T-OBS.C.6
+ *
+ * Core logic:
+ *   writeRestoreAudit() writes an audit log entry to AppendOnlyAuditStore
+ *   every time a restore operation is attempted (success OR failure).
+ *
+ *   Audit payload includes:
+ *     - restoreTarget, fromVersion, toVersion, triggeredBy, reason
+ *     - completedEntities: entity kinds that were successfully restored
+ *     - failedEntities: entity kinds that failed (for partial_restore_error)
+ *     - excludedFields: fields NOT restored (credential / key material)
+ *     - restoredFieldCount
+ *   It NEVER includes actual field values or credential plaintext.
+ *
+ *   Atomicity strategy (DR-041):
+ *     - audit write failure is fire-and-forget: state restore already happened,
+ *       so we cannot roll it back. Return { ok: true, warnings: [...] }.
+ *     - partial_restore_error: state-memory partially wrote; audit records
+ *       completedEntities + failedEntities so operator can see what succeeded.
+ *
+ *   Credential exclusion:
+ *     - RestoreAuditEvent.excludedFields lists credential / key fields.
+ *     - Actual values of these fields are NEVER written to audit.
+ *
+ * Test coverage: tests/unit/observability/restore-audit-service.test.ts
+ */
+import type { AppendOnlyAuditStore } from "../audit/append-only-audit-store.js";
+export type RestoreTarget = "goal" | "narrative" | "evidence" | "relationship";
+export type RestoreTrigger = "operator" | "agent";
+export interface RestoreAuditEvent {
+    id: string;
+    restoreTarget: RestoreTarget;
+    fromVersion: string;
+    toVersion: string;
+    triggeredBy: RestoreTrigger;
+    reason: string;
+    /**
+     * Entity kinds that were successfully written back to state.
+     * Used for partial_restore_error traceability.
+     */
+    completedEntities: string[];
+    /**
+     * Entity kinds that failed to write back (partial restore).
+     * Non-empty → partial_restore_error scenario.
+     */
+    failedEntities: string[];
+    /**
+     * Field names explicitly excluded from restore (credential / key fields).
+     * These are listed here for audit trail but their VALUES are never stored.
+     */
+    excludedFields: string[];
+    /** Number of non-excluded fields that were restored */
+    restoredFieldCount: number;
+    createdAt: string;
+    traceId: string;
+}
+export interface WriteRestoreAuditResult {
+    ok: boolean;
+    /** Populated if audit write itself failed (fire-and-forget, state already changed) */
+    warnings: string[];
+}
+/**
+ * Write a restore audit entry to the AppendOnlyAuditStore.
+ *
+ * Must be called during (or immediately after) a restore operation.
+ * Audit write failure is fire-and-forget (DR-041): the function never throws.
+ *
+ * Returns:
+ *   { ok: true, warnings: [] }                    — audit written successfully
+ *   { ok: true, warnings: ["audit_write_failed: restore_audit_missing"] }
+ *                                                  — audit failed, state already changed
+ */
+export declare function writeRestoreAudit(event: RestoreAuditEvent, store: AppendOnlyAuditStore): Promise<WriteRestoreAuditResult>;

package/runtime/observability/services/restore-audit-service.js

@@ -0,0 +1,79 @@
+/**
+ * RestoreAuditService — T-OBS.C.6
+ *
+ * Core logic:
+ *   writeRestoreAudit() writes an audit log entry to AppendOnlyAuditStore
+ *   every time a restore operation is attempted (success OR failure).
+ *
+ *   Audit payload includes:
+ *     - restoreTarget, fromVersion, toVersion, triggeredBy, reason
+ *     - completedEntities: entity kinds that were successfully restored
+ *     - failedEntities: entity kinds that failed (for partial_restore_error)
+ *     - excludedFields: fields NOT restored (credential / key material)
+ *     - restoredFieldCount
+ *   It NEVER includes actual field values or credential plaintext.
+ *
+ *   Atomicity strategy (DR-041):
+ *     - audit write failure is fire-and-forget: state restore already happened,
+ *       so we cannot roll it back. Return { ok: true, warnings: [...] }.
+ *     - partial_restore_error: state-memory partially wrote; audit records
+ *       completedEntities + failedEntities so operator can see what succeeded.
+ *
+ *   Credential exclusion:
+ *     - RestoreAuditEvent.excludedFields lists credential / key fields.
+ *     - Actual values of these fields are NEVER written to audit.
+ *
+ * Test coverage: tests/unit/observability/restore-audit-service.test.ts
+ */
+import { buildAuditEnvelope } from "../audit/audit-envelope.js";
+// ─── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Write a restore audit entry to the AppendOnlyAuditStore.
+ *
+ * Must be called during (or immediately after) a restore operation.
+ * Audit write failure is fire-and-forget (DR-041): the function never throws.
+ *
+ * Returns:
+ *   { ok: true, warnings: [] }                    — audit written successfully
+ *   { ok: true, warnings: ["audit_write_failed: restore_audit_missing"] }
+ *                                                  — audit failed, state already changed
+ */
+export async function writeRestoreAudit(event, store) {
+    // Build safe payload — NO credential values, only metadata
+    const safePayload = {
+        restoreTarget: event.restoreTarget,
+        fromVersion: event.fromVersion,
+        toVersion: event.toVersion,
+        triggeredBy: event.triggeredBy,
+        reason: event.reason,
+        completedEntities: event.completedEntities,
+        failedEntities: event.failedEntities,
+        excludedFields: event.excludedFields,
+        restoredFieldCount: event.restoredFieldCount,
+        isPartialRestore: event.failedEntities.length > 0,
+        createdAt: event.createdAt,
+    };
+    try {
+        const previousHash = store.lastRecordHash("restore.audit");
+        const envelope = buildAuditEnvelope({
+            family: "restore.audit",
+            plane: "governance",
+            traceId: event.traceId,
+            sequence: store.list().length,
+            payload: safePayload,
+            previousHash,
+            eventId: event.id,
+            createdAt: event.createdAt,
+        });
+        store.append(envelope);
+        return { ok: true, warnings: [] };
+    }
+    catch (err) {
+        // Fire-and-forget: state restore already happened — do not re-throw
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            ok: true,
+            warnings: [`audit_write_failed: restore_audit_missing (${message})`],
+        };
+    }
+}

package/runtime/observability/services/runtime-secret-anchor-view.d.ts

@@ -0,0 +1,77 @@
+/**
+ * RuntimeSecretAnchorView — T-OBS.C.7
+ *
+ * Core logic:
+ *   viewSecretAnchor() probes the encryption key anchor and returns a
+ *   RuntimeSecretAnchorView that describes the current health status.
+ *
+ *   Three detection scenarios (DR-034):
+ *     1. Key path missing / env var not set → status "missing"
+ *        reasonCode: "runtime_secret_anchor_missing"
+ *     2. Key path present but sample decrypt fails with wrong-key signal
+ *        reasonCode: "credential_recovery_required"
+ *     3. Key path present but decrypt call throws / unrecoverable error
+ *        reasonCode: "runtime_secret_unavailable"
+ *
+ *   RecoveryStep[] is always inline in the view (DR-034).
+ *   Key plaintext is NEVER stored or returned (ADR-007).
+ *   Only the key path (env var name / file path) is included.
+ *
+ * Test coverage: tests/unit/observability/runtime-secret-anchor-view.test.ts
+ */
+export type SecretAnchorStatus = "ok" | "verified" | "missing" | "wrong_key" | "decryption_failed" | "unknown";
+export type HealthProbeReasonCode = "runtime_secret_unavailable" | "credential_recovery_required" | "runtime_secret_anchor_missing";
+export interface RecoveryStep {
+    step: number;
+    action: string;
+    /** Optional shell command the operator should run */
+    command?: string;
+}
+/** The view object returned by viewSecretAnchor(). Never contains key plaintext. */
+export interface RuntimeSecretAnchorView {
+    anchorId: string;
+    /** Env-var name or file path for the encryption key — NOT the value */
+    keyPath: string;
+    status: SecretAnchorStatus;
+    lastCheckedAt: string;
+    /** Reference to operator recovery documentation */
+    recoveryDocRef: string;
+    /** Optional rotation schedule hint */
+    rotationSchedule?: string;
+    /** IDs of credentials that were sampled during verification (not their values) */
+    checkedCredentialIds?: string[];
+    /** Inline recovery instructions when status is not "verified" (DR-034) */
+    recoverySteps: RecoveryStep[];
+    /** Machine-readable reason code when status is not "verified" */
+    reasonCode?: HealthProbeReasonCode;
+}
+export interface SampleDecryptResult {
+    /** "ok" = decrypt succeeded; "wrong_key" = key mismatch; "error" = other failure */
+    status: "ok" | "wrong_key" | "error";
+    checkedIds: string[];
+}
+export interface SecretAnchorRuntimeOpsPort {
+    /** Returns the key path (env var name or file path), never the key value */
+    getEncryptionKeyPath(): string;
+    /** Returns true if the key path exists and is non-empty */
+    checkKeyPathExists(keyPath: string): Promise<boolean>;
+}
+export interface SecretAnchorCredentialPort {
+    /** Attempts to decrypt a known sample credential; returns status + IDs checked */
+    verifySampleDecrypt(): Promise<SampleDecryptResult>;
+}
+export interface SecretAnchorDeps {
+    runtimeOpsPort: SecretAnchorRuntimeOpsPort;
+    credentialPort: SecretAnchorCredentialPort;
+    /** Override for testability */
+    now?: () => string;
+}
+/**
+ * Probe the encryption key anchor and return a safe view.
+ *
+ * Guarantees:
+ *   - keyPath is a path string (env var name or file path), never a value.
+ *   - No field in the returned object contains the key plaintext.
+ *   - recoverySteps is always populated when status ≠ "verified".
+ */
+export declare function viewSecretAnchor(deps: SecretAnchorDeps): Promise<RuntimeSecretAnchorView>;