@haaaiawd/second-nature 0.1.8 → 0.1.10

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

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

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

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

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

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

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

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

package/runtime/observability/db/index.js

@@ -72,6 +72,17 @@ const OBSERVABILITY_SCHEMA_SQL = `
     created_at TEXT NOT NULL
   );
   CREATE INDEX IF NOT EXISTS redact_event_idx ON redaction_manifest(event_id);
+  CREATE TABLE IF NOT EXISTS host_capability_reports (
+    report_id TEXT PRIMARY KEY,
+    generated_at TEXT NOT NULL,
+    host_version TEXT,
+    observed_version TEXT,
+    doc_checked_at TEXT NOT NULL,
+    doc_links_json TEXT NOT NULL,
+    delivery_target TEXT NOT NULL,
+    conflict_records_json TEXT NOT NULL,
+    full_report_json TEXT NOT NULL
+  );
 `;
 function resolveDbPath(filename) {
     if (path.isAbsolute(filename) || filename === ":memory:") {

package/runtime/observability/db/schema/host-capability-reports.d.ts

@@ -0,0 +1,180 @@
+export declare const hostCapabilityReports: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+    name: "host_capability_reports";
+    schema: undefined;
+    columns: {
+        reportId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "report_id";
+            tableName: "host_capability_reports";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        generatedAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "generated_at";
+            tableName: "host_capability_reports";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        hostVersion: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "host_version";
+            tableName: "host_capability_reports";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        observedVersion: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "observed_version";
+            tableName: "host_capability_reports";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        docCheckedAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "doc_checked_at";
+            tableName: "host_capability_reports";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        docLinksJson: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "doc_links_json";
+            tableName: "host_capability_reports";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        deliveryTarget: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "delivery_target";
+            tableName: "host_capability_reports";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        conflictRecordsJson: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "conflict_records_json";
+            tableName: "host_capability_reports";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        fullReportJson: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "full_report_json";
+            tableName: "host_capability_reports";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+    };
+    dialect: "sqlite";
+}>;
+export type HostCapabilityReportRow = typeof hostCapabilityReports.$inferSelect;
+export type NewHostCapabilityReportRow = typeof hostCapabilityReports.$inferInsert;

package/runtime/observability/db/schema/host-capability-reports.js

@@ -0,0 +1,12 @@
+import { sqliteTable, text } from "drizzle-orm/sqlite-core";
+export const hostCapabilityReports = sqliteTable("host_capability_reports", {
+    reportId: text("report_id").primaryKey(),
+    generatedAt: text("generated_at").notNull(),
+    hostVersion: text("host_version"),
+    observedVersion: text("observed_version"),
+    docCheckedAt: text("doc_checked_at").notNull(),
+    docLinksJson: text("doc_links_json").notNull(),
+    deliveryTarget: text("delivery_target").notNull(),
+    conflictRecordsJson: text("conflict_records_json").notNull(),
+    fullReportJson: text("full_report_json").notNull(),
+});

package/runtime/observability/db/schema/index.d.ts

@@ -944,3 +944,4 @@ export type GovernanceAuditDb = typeof governanceAudit.$inferSelect;
 export type NewGovernanceAuditDb = typeof governanceAudit.$inferInsert;
 export type RedactionManifestDb = typeof redactionManifest.$inferSelect;
 export type NewRedactionManifestDb = typeof redactionManifest.$inferInsert;
+export { hostCapabilityReports, type HostCapabilityReportRow, type NewHostCapabilityReportRow, } from "./host-capability-reports.js";

package/runtime/observability/db/schema/index.js

@@ -68,3 +68,4 @@ export const redactionManifest = sqliteTable("redaction_manifest", {
 }, (table) => [
     index("redact_event_idx").on(table.eventId),
 ]);
+export { hostCapabilityReports, } from "./host-capability-reports.js";

package/runtime/observability/index.d.ts

@@ -1,10 +1,17 @@
 export { createObservabilityDatabase, type ObservabilityDatabase } from "./db/index.js";
 export * as obsSchema from "./db/schema/index.js";
+export { buildAuditEnvelope, computeAuditRecordHash, redactAuditEvent, auditManifestFromFieldManifest, type AuditEnvelope, type AuditEnvelopeSensitivity, type AuditEventFamily, type AuditPlane, type AuditRedactionManifest, type AuditIntegrity, type BuildAuditEnvelopeInput, type RedactAuditEventResult, } from "./audit/audit-envelope.js";
+export { AppendOnlyAuditStore } from "./audit/append-only-audit-store.js";
+export { verifyAuditHashChain, createAppendOnlyAuditStoreRangeLoader, type AuditExportRange, type AuditHashChainVerificationReport, type AuditHashChainVerificationStatus, type VerifyAuditHashChainDeps, } from "./audit/verify-audit-hash-chain.js";
 export { REDACTION_CONFIG, DEFAULT_REDACTION_POLICY, getFieldRedactionRule, type RedactionPolicy, type RedactionRule, type SensitivityLevel, } from "./redaction/policy.js";
 export { redactEvent, createEmptyManifest, mergeManifests, type RedactionManifest, type RedactionResult, } from "./redaction/manifest.js";
 export { DecisionLedger, type QuietLifecycleEvent, type OutreachDecision, type HeartbeatDecisionEvent } from "./services/decision-ledger.js";
 export { GovernanceAudit, type CredentialLifecycleAudit } from "./services/governance-audit.js";
 export { ExecutionTelemetry, type ExecutionAttemptInput } from "./services/execution-telemetry.js";
+export { LivedExperienceAuditRecorder, createLivedExperienceAuditRecorder, type DecisionTracePayload, type DeliveryAuditPayload, type DeliveryAuditStatus, type ExplainLinkageSummary, type GuidanceGroundingAuditPayload, type SourceCoverageAuditPayload, } from "./services/lived-experience-audit.js";
+export { GovernancePlaneRecorder, createGovernancePlaneRecorder, type AuditAppendAck, type ConnectorAttemptAudit, type ConnectorAttemptOutcome, type StateGovernanceAudit, type StateGovernanceKind, } from "./services/governance-plane-recorder.js";
+export { queryExplain, type ExplainQuery, type OperatorExplainReadModel, type RedactedExplainEvent, } from "./query/explain-query.js";
+export { exportAuditBundle, type AuditBundle, type AuditBundleExportRange, type AuditRedactionSummary, type ExportAuditBundleDeps } from "./query/export-audit-bundle.js";
 export { EvidenceQueryEngine, } from "./query/evidence-query-engine.js";
 export type { EvidenceQuery, EvidenceBundle, EvidenceResolutionPlan, GovernanceEvidenceRecord, ResolvedContentRef, ExplanationCapsule, } from "./query/compose-evidence.js";
 export { projectReflectionAudit, type ReflectionAudit, type ReflectionAuditProjection, } from "./projections/reflection-audit.js";

package/runtime/observability/index.js

@@ -1,10 +1,17 @@
 export { createObservabilityDatabase } from "./db/index.js";
 export * as obsSchema from "./db/schema/index.js";
+export { buildAuditEnvelope, computeAuditRecordHash, redactAuditEvent, auditManifestFromFieldManifest, } from "./audit/audit-envelope.js";
+export { AppendOnlyAuditStore } from "./audit/append-only-audit-store.js";
+export { verifyAuditHashChain, createAppendOnlyAuditStoreRangeLoader, } from "./audit/verify-audit-hash-chain.js";
 export { REDACTION_CONFIG, DEFAULT_REDACTION_POLICY, getFieldRedactionRule, } from "./redaction/policy.js";
 export { redactEvent, createEmptyManifest, mergeManifests, } from "./redaction/manifest.js";
 export { DecisionLedger } from "./services/decision-ledger.js";
 export { GovernanceAudit } from "./services/governance-audit.js";
 export { ExecutionTelemetry } from "./services/execution-telemetry.js";
+export { LivedExperienceAuditRecorder, createLivedExperienceAuditRecorder, } from "./services/lived-experience-audit.js";
+export { GovernancePlaneRecorder, createGovernancePlaneRecorder, } from "./services/governance-plane-recorder.js";
+export { queryExplain, } from "./query/explain-query.js";
+export { exportAuditBundle } from "./query/export-audit-bundle.js";
 export { EvidenceQueryEngine, } from "./query/evidence-query-engine.js";
 export { projectReflectionAudit, } from "./projections/reflection-audit.js";
 export { projectOutreachQualityAudit, } from "./projections/outreach-quality-audit.js";

package/runtime/observability/query/explain-query.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Operator explain query over append-only audit envelopes (T5.3.1).
+ *
+ * Core logic: resolve subject to matching envelopes, compose summary + no-user-visible-contact warnings,
+ * expose minimal redacted event list for JSON-first read models.
+ *
+ * Dependencies: AppendOnlyAuditStore list; audit-envelope types; delivery audit payload shape from lived-experience-audit.
+ *
+ * Test coverage: tests/integration/observability/explain-query-export.test.ts
+ */
+import type { AppendOnlyAuditStore } from "../audit/append-only-audit-store.js";
+import type { DeliveryAuditPayload } from "../services/lived-experience-audit.js";
+export type ExplainQuery = {
+    kind: "decision";
+    decisionId: string;
+} | {
+    kind: "fallback";
+    fallbackRef: string;
+} | {
+    kind: "report";
+    reportId: string;
+} | {
+    kind: "delivery";
+    auditId: string;
+} | {
+    kind: "source_ref";
+    sourceRefId: string;
+};
+export interface RedactedExplainEvent {
+    eventId: string;
+    family: string;
+    plane: string;
+    createdAt: string;
+    /** Minimal safe summary — no raw recipient / tokens */
+    summary: string;
+}
+export interface OperatorExplainReadModel {
+    query: ExplainQuery;
+    summary: string;
+    warnings: string[];
+    deliveryStatus?: DeliveryAuditPayload["status"];
+    relatedEventIds: string[];
+    events: RedactedExplainEvent[];
+}
+/**
+ * Query explain read model from an in-memory append-only audit slice (tests / local tooling).
+ */
+export declare function queryExplain(query: ExplainQuery, store: AppendOnlyAuditStore): OperatorExplainReadModel;