@haaaiawd/second-nature 0.1.17 → 0.1.18

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

@@ -1,71 +1,71 @@
-import { integer, sqliteTable, text, uniqueIndex, index } from "drizzle-orm/sqlite-core";
-export const decisionLedger = sqliteTable("decision_ledger", {
-    id: text("id").primaryKey(),
-    tickId: text("tick_id").notNull(),
-    traceId: text("trace_id").notNull(),
-    intentId: text("intent_id"),
-    platformId: text("platform_id"),
-    verdict: text("verdict").notNull(),
-    mode: text("mode").notNull(),
-    reasons: text("reasons").notNull(),
-    reasonCodes: text("reason_codes").notNull(),
-    decisionBasis: text("decision_basis").notNull(),
-    evidenceRefs: text("evidence_refs").notNull(),
-    modelEvalRef: text("model_eval_ref"),
-    createdAt: text("created_at").notNull(),
-}, (table) => [
-    index("decision_tick_idx").on(table.tickId),
-    uniqueIndex("decision_trace_idx").on(table.traceId),
-]);
-export const executionAttempts = sqliteTable("execution_attempts", {
-    id: text("id").primaryKey(),
-    traceId: text("trace_id").notNull(),
-    decisionId: text("decision_id").notNull(),
-    intentId: text("intent_id").notNull(),
-    platformId: text("platform_id").notNull(),
-    capability: text("capability").notNull(),
-    channel: text("channel").notNull(),
-    status: text("status").notNull(),
-    commitState: text("commit_state"),
-    failureClass: text("failure_class"),
-    retryPolicy: text("retry_policy"),
-    idempotencyKey: text("idempotency_key"),
-    startedAt: text("started_at"),
-    finishedAt: text("finished_at"),
-}, (table) => [
-    uniqueIndex("attempt_trace_idx").on(table.traceId),
-    index("attempt_decision_idx").on(table.decisionId),
-    index("attempt_platform_idx").on(table.platformId),
-]);
-export const governanceAudit = sqliteTable("governance_audit", {
-    id: text("id").primaryKey(),
-    eventType: text("event_type").notNull(),
-    proposalId: text("proposal_id"),
-    targetAssetId: text("target_asset_id"),
-    assetPath: text("asset_path"),
-    statusFrom: text("status_from"),
-    statusTo: text("status_to").notNull(),
-    beforeHash: text("before_hash"),
-    afterHash: text("after_hash"),
-    supportingSources: text("supporting_sources"),
-    reason: text("reason"),
-    verificationDeadline: text("verification_deadline"),
-    attemptsRemaining: integer("attempts_remaining"),
-    createdAt: text("created_at").notNull(),
-}, (table) => [
-    index("audit_proposal_idx").on(table.proposalId),
-    index("audit_asset_idx").on(table.targetAssetId),
-    index("audit_event_idx").on(table.eventType),
-]);
-export const redactionManifest = sqliteTable("redaction_manifest", {
-    id: text("id").primaryKey(),
-    eventId: text("event_id").notNull(),
-    eventType: text("event_type").notNull(),
-    fieldName: text("field_name").notNull(),
-    action: text("action").notNull(),
-    originalValueHash: text("original_value_hash"),
-    createdAt: text("created_at").notNull(),
-}, (table) => [
-    index("redact_event_idx").on(table.eventId),
-]);
-export { hostCapabilityReports, } from "./host-capability-reports.js";
+import { integer, sqliteTable, text, uniqueIndex, index } from "drizzle-orm/sqlite-core";
+export const decisionLedger = sqliteTable("decision_ledger", {
+    id: text("id").primaryKey(),
+    tickId: text("tick_id").notNull(),
+    traceId: text("trace_id").notNull(),
+    intentId: text("intent_id"),
+    platformId: text("platform_id"),
+    verdict: text("verdict").notNull(),
+    mode: text("mode").notNull(),
+    reasons: text("reasons").notNull(),
+    reasonCodes: text("reason_codes").notNull(),
+    decisionBasis: text("decision_basis").notNull(),
+    evidenceRefs: text("evidence_refs").notNull(),
+    modelEvalRef: text("model_eval_ref"),
+    createdAt: text("created_at").notNull(),
+}, (table) => [
+    index("decision_tick_idx").on(table.tickId),
+    uniqueIndex("decision_trace_idx").on(table.traceId),
+]);
+export const executionAttempts = sqliteTable("execution_attempts", {
+    id: text("id").primaryKey(),
+    traceId: text("trace_id").notNull(),
+    decisionId: text("decision_id").notNull(),
+    intentId: text("intent_id").notNull(),
+    platformId: text("platform_id").notNull(),
+    capability: text("capability").notNull(),
+    channel: text("channel").notNull(),
+    status: text("status").notNull(),
+    commitState: text("commit_state"),
+    failureClass: text("failure_class"),
+    retryPolicy: text("retry_policy"),
+    idempotencyKey: text("idempotency_key"),
+    startedAt: text("started_at"),
+    finishedAt: text("finished_at"),
+}, (table) => [
+    uniqueIndex("attempt_trace_idx").on(table.traceId),
+    index("attempt_decision_idx").on(table.decisionId),
+    index("attempt_platform_idx").on(table.platformId),
+]);
+export const governanceAudit = sqliteTable("governance_audit", {
+    id: text("id").primaryKey(),
+    eventType: text("event_type").notNull(),
+    proposalId: text("proposal_id"),
+    targetAssetId: text("target_asset_id"),
+    assetPath: text("asset_path"),
+    statusFrom: text("status_from"),
+    statusTo: text("status_to").notNull(),
+    beforeHash: text("before_hash"),
+    afterHash: text("after_hash"),
+    supportingSources: text("supporting_sources"),
+    reason: text("reason"),
+    verificationDeadline: text("verification_deadline"),
+    attemptsRemaining: integer("attempts_remaining"),
+    createdAt: text("created_at").notNull(),
+}, (table) => [
+    index("audit_proposal_idx").on(table.proposalId),
+    index("audit_asset_idx").on(table.targetAssetId),
+    index("audit_event_idx").on(table.eventType),
+]);
+export const redactionManifest = sqliteTable("redaction_manifest", {
+    id: text("id").primaryKey(),
+    eventId: text("event_id").notNull(),
+    eventType: text("event_type").notNull(),
+    fieldName: text("field_name").notNull(),
+    action: text("action").notNull(),
+    originalValueHash: text("original_value_hash"),
+    createdAt: text("created_at").notNull(),
+}, (table) => [
+    index("redact_event_idx").on(table.eventId),
+]);
+export { hostCapabilityReports, } from "./host-capability-reports.js";

package/runtime/observability/index.d.ts

@@ -1,19 +1,20 @@
-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";
-export { projectOutreachQualityAudit, type OutreachQualityAudit, type OutreachQualityProjection, } from "./projections/outreach-quality-audit.js";
-export { projectGuidanceParticipationAudit, type GuidanceParticipationAudit, type GuidanceParticipationProjection, } from "./projections/guidance-audit.js";
+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 { createRuntimeDecisionRecorder, RUNTIME_DECISION_TRACE_PREFIX, RUNTIME_INTERNAL_PLATFORM_ID, type RuntimeDecisionRecorder, type RecordHeartbeatCycleInput, type RecordHeartbeatCycleOutput, } from "./services/runtime-decision-recorder.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";
+export { projectOutreachQualityAudit, type OutreachQualityAudit, type OutreachQualityProjection, } from "./projections/outreach-quality-audit.js";
+export { projectGuidanceParticipationAudit, type GuidanceParticipationAudit, type GuidanceParticipationProjection, } from "./projections/guidance-audit.js";

package/runtime/observability/index.js

@@ -1,18 +1,19 @@
-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";
-export { projectGuidanceParticipationAudit, } from "./projections/guidance-audit.js";
+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 { createRuntimeDecisionRecorder, RUNTIME_DECISION_TRACE_PREFIX, RUNTIME_INTERNAL_PLATFORM_ID, } from "./services/runtime-decision-recorder.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";
+export { projectGuidanceParticipationAudit, } from "./projections/guidance-audit.js";

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

@@ -1,48 +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;
+/**
+ * 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;

package/runtime/observability/query/explain-query.js

@@ -1,114 +1,114 @@
-const NO_USER_VISIBLE = "no_user_visible_contact_claim_prohibited";
-function isNoUserVisibleDelivery(status) {
-    if (!status)
-        return false;
-    return (status === "target_none" ||
-        status === "not_sent_fallback" ||
-        status === "channel_missing" ||
-        status === "host_unsupported" ||
-        status === "failed" ||
-        status === "ack_dropped");
-}
-function payloadDecisionId(payload) {
-    if (!payload || typeof payload !== "object")
-        return undefined;
-    const p = payload;
-    const v = p.decisionId;
-    return typeof v === "string" ? v : undefined;
-}
-function payloadFallbackRef(payload) {
-    if (!payload || typeof payload !== "object")
-        return undefined;
-    const p = payload;
-    const v = p.fallbackRef;
-    return typeof v === "string" ? v : undefined;
-}
-function payloadAuditId(payload) {
-    if (!payload || typeof payload !== "object")
-        return undefined;
-    const p = payload;
-    const a = p.auditId;
-    if (typeof a === "string")
-        return a;
-    return undefined;
-}
-function deliveryStatusFrom(payload) {
-    if (!payload || typeof payload !== "object")
-        return undefined;
-    const p = payload;
-    const s = p.status;
-    return typeof s === "string" ? s : undefined;
-}
-function eventMatchesQuery(envelope, query) {
-    const payload = envelope.payload;
-    switch (query.kind) {
-        case "decision":
-            return payloadDecisionId(payload) === query.decisionId;
-        case "fallback":
-            return payloadFallbackRef(payload) === query.fallbackRef;
-        case "report":
-            return envelope.eventId === query.reportId || payloadAuditId(payload) === query.reportId;
-        case "delivery":
-            return (envelope.family === "delivery" &&
-                (envelope.eventId === query.auditId || payloadAuditId(payload) === query.auditId));
-        case "source_ref": {
-            const needle = query.sourceRefId;
-            try {
-                return JSON.stringify(payload).includes(needle);
-            }
-            catch {
-                return false;
-            }
-        }
-    }
-}
-function summarizeEnvelope(e) {
-    const fam = e.family;
-    if (fam === "delivery") {
-        const st = deliveryStatusFrom(e.payload);
-        return `delivery_audit:${st ?? "unknown"}`;
-    }
-    if (fam === "heartbeat.decision") {
-        const outcome = e.payload?.outcome;
-        return `decision:${typeof outcome === "string" ? outcome : "unknown"}`;
-    }
-    return `${fam}`;
-}
-/**
- * Query explain read model from an in-memory append-only audit slice (tests / local tooling).
- */
-export function queryExplain(query, store) {
-    const matched = store.list().filter((e) => eventMatchesQuery(e, query));
-    const relatedEventIds = matched.map((e) => e.eventId);
-    const warnings = [];
-    let deliveryStatus;
-    for (const e of matched) {
-        if (e.family === "delivery") {
-            const st = deliveryStatusFrom(e.payload);
-            if (st)
-                deliveryStatus = st;
-            if (isNoUserVisibleDelivery(st)) {
-                warnings.push(NO_USER_VISIBLE);
-            }
-        }
-    }
-    const uniqueWarnings = [...new Set(warnings)];
-    const summary = matched.length === 0
-        ? "no_matching_audit_events"
-        : `matched_events=${matched.length};subject=${query.kind}`;
-    const events = matched.map((e) => ({
-        eventId: e.eventId,
-        family: e.family,
-        plane: e.plane,
-        createdAt: e.createdAt,
-        summary: summarizeEnvelope(e),
-    }));
-    return {
-        query,
-        summary,
-        warnings: uniqueWarnings,
-        deliveryStatus,
-        relatedEventIds,
-        events,
-    };
-}
+const NO_USER_VISIBLE = "no_user_visible_contact_claim_prohibited";
+function isNoUserVisibleDelivery(status) {
+    if (!status)
+        return false;
+    return (status === "target_none" ||
+        status === "not_sent_fallback" ||
+        status === "channel_missing" ||
+        status === "host_unsupported" ||
+        status === "failed" ||
+        status === "ack_dropped");
+}
+function payloadDecisionId(payload) {
+    if (!payload || typeof payload !== "object")
+        return undefined;
+    const p = payload;
+    const v = p.decisionId;
+    return typeof v === "string" ? v : undefined;
+}
+function payloadFallbackRef(payload) {
+    if (!payload || typeof payload !== "object")
+        return undefined;
+    const p = payload;
+    const v = p.fallbackRef;
+    return typeof v === "string" ? v : undefined;
+}
+function payloadAuditId(payload) {
+    if (!payload || typeof payload !== "object")
+        return undefined;
+    const p = payload;
+    const a = p.auditId;
+    if (typeof a === "string")
+        return a;
+    return undefined;
+}
+function deliveryStatusFrom(payload) {
+    if (!payload || typeof payload !== "object")
+        return undefined;
+    const p = payload;
+    const s = p.status;
+    return typeof s === "string" ? s : undefined;
+}
+function eventMatchesQuery(envelope, query) {
+    const payload = envelope.payload;
+    switch (query.kind) {
+        case "decision":
+            return payloadDecisionId(payload) === query.decisionId;
+        case "fallback":
+            return payloadFallbackRef(payload) === query.fallbackRef;
+        case "report":
+            return envelope.eventId === query.reportId || payloadAuditId(payload) === query.reportId;
+        case "delivery":
+            return (envelope.family === "delivery" &&
+                (envelope.eventId === query.auditId || payloadAuditId(payload) === query.auditId));
+        case "source_ref": {
+            const needle = query.sourceRefId;
+            try {
+                return JSON.stringify(payload).includes(needle);
+            }
+            catch {
+                return false;
+            }
+        }
+    }
+}
+function summarizeEnvelope(e) {
+    const fam = e.family;
+    if (fam === "delivery") {
+        const st = deliveryStatusFrom(e.payload);
+        return `delivery_audit:${st ?? "unknown"}`;
+    }
+    if (fam === "heartbeat.decision") {
+        const outcome = e.payload?.outcome;
+        return `decision:${typeof outcome === "string" ? outcome : "unknown"}`;
+    }
+    return `${fam}`;
+}
+/**
+ * Query explain read model from an in-memory append-only audit slice (tests / local tooling).
+ */
+export function queryExplain(query, store) {
+    const matched = store.list().filter((e) => eventMatchesQuery(e, query));
+    const relatedEventIds = matched.map((e) => e.eventId);
+    const warnings = [];
+    let deliveryStatus;
+    for (const e of matched) {
+        if (e.family === "delivery") {
+            const st = deliveryStatusFrom(e.payload);
+            if (st)
+                deliveryStatus = st;
+            if (isNoUserVisibleDelivery(st)) {
+                warnings.push(NO_USER_VISIBLE);
+            }
+        }
+    }
+    const uniqueWarnings = [...new Set(warnings)];
+    const summary = matched.length === 0
+        ? "no_matching_audit_events"
+        : `matched_events=${matched.length};subject=${query.kind}`;
+    const events = matched.map((e) => ({
+        eventId: e.eventId,
+        family: e.family,
+        plane: e.plane,
+        createdAt: e.createdAt,
+        summary: summarizeEnvelope(e),
+    }));
+    return {
+        query,
+        summary,
+        warnings: uniqueWarnings,
+        deliveryStatus,
+        relatedEventIds,
+        events,
+    };
+}

package/runtime/observability/query/export-audit-bundle.d.ts

@@ -1,22 +1,22 @@
-import type { AuditEnvelope } from "../audit/audit-envelope.js";
-import type { AuditEventFamily } from "../audit/audit-envelope.js";
-import type { AuditExportRange } from "../audit/verify-audit-hash-chain.js";
-export interface AuditBundleExportRange extends AuditExportRange {
-    /** Reserved for otel_projection / future formats */
-    format?: "json_v1";
-}
-export interface AuditRedactionSummary {
-    eventCount: number;
-    manifestIds: string[];
-}
-export interface AuditBundle {
-    bundleId: string;
-    generatedAt: string;
-    range: AuditBundleExportRange;
-    events: readonly AuditEnvelope<unknown>[];
-    redactionSummary: AuditRedactionSummary;
-}
-export interface ExportAuditBundleDeps {
-    loadRange(from: string, to: string, families?: AuditEventFamily[]): Promise<readonly AuditEnvelope<unknown>[]>;
-}
-export declare function exportAuditBundle(range: AuditBundleExportRange, deps: ExportAuditBundleDeps): Promise<AuditBundle>;
+import type { AuditEnvelope } from "../audit/audit-envelope.js";
+import type { AuditEventFamily } from "../audit/audit-envelope.js";
+import type { AuditExportRange } from "../audit/verify-audit-hash-chain.js";
+export interface AuditBundleExportRange extends AuditExportRange {
+    /** Reserved for otel_projection / future formats */
+    format?: "json_v1";
+}
+export interface AuditRedactionSummary {
+    eventCount: number;
+    manifestIds: string[];
+}
+export interface AuditBundle {
+    bundleId: string;
+    generatedAt: string;
+    range: AuditBundleExportRange;
+    events: readonly AuditEnvelope<unknown>[];
+    redactionSummary: AuditRedactionSummary;
+}
+export interface ExportAuditBundleDeps {
+    loadRange(from: string, to: string, families?: AuditEventFamily[]): Promise<readonly AuditEnvelope<unknown>[]>;
+}
+export declare function exportAuditBundle(range: AuditBundleExportRange, deps: ExportAuditBundleDeps): Promise<AuditBundle>;