@haaaiawd/second-nature 0.1.8 → 0.1.9

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;

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

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

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

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

package/runtime/observability/query/export-audit-bundle.js

@@ -0,0 +1,27 @@
+/**
+ * Redacted audit export bundle for operator / retention tooling (T5.3.1).
+ *
+ * Core logic: load range, attach export metadata; payloads are already redacted at envelope build time.
+ *
+ * Dependencies: same range loader pattern as verifyAuditHashChain.
+ *
+ * Test coverage: tests/integration/observability/explain-query-export.test.ts
+ */
+import * as crypto from "node:crypto";
+function summarize(events) {
+    const ids = new Set();
+    for (const e of events) {
+        ids.add(e.redaction.manifestId);
+    }
+    return { eventCount: events.length, manifestIds: [...ids] };
+}
+export async function exportAuditBundle(range, deps) {
+    const events = [...(await deps.loadRange(range.from, range.to, range.families))].sort((a, b) => a.sequence - b.sequence);
+    return {
+        bundleId: crypto.randomUUID(),
+        generatedAt: new Date().toISOString(),
+        range,
+        events,
+        redactionSummary: summarize(events),
+    };
+}

package/runtime/observability/services/decision-ledger.d.ts

@@ -26,7 +26,7 @@ export interface HeartbeatDecisionEvent {
     traceId: string;
     runtimeScope: "rhythm" | "user_task" | "user_reply";
     triggerSource: "heartbeat_bridge" | "user_task" | "user_reply" | "interrupt" | "resume";
-    decisionStatus: "heartbeat_ok" | "intent_selected" | "denied" | "deferred";
+    decisionStatus: "heartbeat_ok" | "intent_selected" | "denied" | "deferred" | "runtime_carrier_only" | "delivery_unavailable";
     reasons: string[];
     intentId?: string;
     mode: "active" | "quiet" | "maintenance_only" | "paused_for_interrupt";

package/runtime/observability/services/decision-ledger.js

@@ -153,5 +153,9 @@ function mapHeartbeatStatusToVerdict(status) {
             return "defer";
         case "heartbeat_ok":
             return "defer";
+        case "runtime_carrier_only":
+            return "defer";
+        case "delivery_unavailable":
+            return "deny";
     }
 }

package/runtime/observability/services/governance-audit.d.ts

@@ -15,6 +15,20 @@ export declare class GovernanceAudit {
     private db;
     constructor(db: ObservabilityDatabase);
     recordAnchorChangeAudit(event: AnchorChangeAudit): Promise<void>;
+    /**
+     * Generic governance-plane events (T5.1.2): fallback_written, effect_commit_advanced, connector_failure, etc.
+     * traceId is stored on target_asset_id for explain/trace correlation until a dedicated column exists.
+     */
+    recordOperationalGovernanceEvent(input: {
+        id: string;
+        eventType: string;
+        traceId: string;
+        statusTo: string;
+        reason: string;
+        assetPath?: string;
+        supportingSources?: string[];
+        createdAt?: string;
+    }): Promise<void>;
     recordCredentialLifecycle(event: CredentialLifecycleAudit): Promise<void>;
     recordProposalApply(proposalId: string, targetAssetId: string, assetPath: string, beforeHash: string | undefined, afterHash: string | undefined, supportingSources: string[], reason: string): Promise<void>;
     recordProposalReject(proposalId: string, targetAssetId: string, assetPath: string, reason: string): Promise<void>;

package/runtime/observability/services/governance-audit.js

@@ -1,6 +1,6 @@
 import { eq } from "drizzle-orm";
 import { governanceAudit } from "../db/schema/index.js";
-import { redactEvent } from "../redaction/manifest.js";
+import { createEmptyManifest, redactEvent } from "../redaction/manifest.js";
 import { persistRedactionManifest } from "./redaction-store.js";
 export class GovernanceAudit {
     db;
@@ -27,6 +27,30 @@ export class GovernanceAudit {
         });
         await persistRedactionManifest(this.db, redacted.id, "anchor.change", manifest);
     }
+    /**
+     * Generic governance-plane events (T5.1.2): fallback_written, effect_commit_advanced, connector_failure, etc.
+     * traceId is stored on target_asset_id for explain/trace correlation until a dedicated column exists.
+     */
+    async recordOperationalGovernanceEvent(input) {
+        const createdAt = input.createdAt ?? new Date().toISOString();
+        await this.db.db.insert(governanceAudit).values({
+            id: input.id,
+            eventType: input.eventType,
+            proposalId: null,
+            targetAssetId: input.traceId,
+            assetPath: input.assetPath ?? null,
+            statusFrom: null,
+            statusTo: input.statusTo,
+            beforeHash: null,
+            afterHash: null,
+            supportingSources: JSON.stringify(input.supportingSources ?? []),
+            reason: input.reason,
+            verificationDeadline: null,
+            attemptsRemaining: null,
+            createdAt,
+        });
+        await persistRedactionManifest(this.db, input.id, input.eventType, createEmptyManifest());
+    }
     async recordCredentialLifecycle(event) {
         const { redacted, manifest } = redactEvent(event);
         await this.db.db.insert(governanceAudit).values({

package/runtime/observability/services/governance-plane-recorder.d.ts

@@ -0,0 +1,47 @@
+/**
+ * T5.1.2 governance plane: connector attempts + state governance audit append ports.
+ *
+ * Core logic: connector attempts map to executionAttempts telemetry; governance kinds map to
+ * governance_audit rows with traceId on target_asset_id for explain correlation.
+ *
+ * Test coverage: tests/unit/observability/governance-plane-recorder.test.ts
+ */
+import type { ObservabilityDatabase } from "../db/index.js";
+import { ExecutionTelemetry } from "./execution-telemetry.js";
+import { GovernanceAudit } from "./governance-audit.js";
+export interface AuditAppendAck {
+    recordId: string;
+    appendedAt: string;
+}
+export type ConnectorAttemptOutcome = "started" | "succeeded" | "failed" | "sampled_telemetry";
+export interface ConnectorAttemptAudit {
+    traceId: string;
+    decisionId: string;
+    intentId: string;
+    platformId: string;
+    capability: string;
+    channel: string;
+    outcome: ConnectorAttemptOutcome;
+    failureClass?: string;
+    idempotencyKey?: string;
+    metadata?: Record<string, unknown>;
+}
+export type StateGovernanceKind = "fallback_written" | "effect_commit_advanced" | "connector_failure" | "anchor_proposal_received";
+export interface StateGovernanceAudit {
+    id: string;
+    traceId: string;
+    kind: StateGovernanceKind;
+    reason: string;
+    decisionId?: string;
+    artifactPath?: string;
+    supportingSources?: string[];
+    createdAt?: string;
+}
+export declare class GovernancePlaneRecorder {
+    private readonly telemetry;
+    private readonly governance;
+    constructor(telemetry: ExecutionTelemetry, governance: GovernanceAudit);
+    recordConnectorAttempt(audit: ConnectorAttemptAudit): Promise<AuditAppendAck>;
+    recordStateGovernance(event: StateGovernanceAudit): Promise<AuditAppendAck>;
+}
+export declare function createGovernancePlaneRecorder(db: ObservabilityDatabase): GovernancePlaneRecorder;

package/runtime/observability/services/governance-plane-recorder.js

@@ -0,0 +1,55 @@
+import { ExecutionTelemetry } from "./execution-telemetry.js";
+import { GovernanceAudit } from "./governance-audit.js";
+export class GovernancePlaneRecorder {
+    telemetry;
+    governance;
+    constructor(telemetry, governance) {
+        this.telemetry = telemetry;
+        this.governance = governance;
+    }
+    async recordConnectorAttempt(audit) {
+        const id = `ca-${audit.traceId}-${Date.now()}`;
+        const status = audit.outcome === "failed" ? "failed" : audit.outcome === "started" ? "started" : "succeeded";
+        const now = new Date().toISOString();
+        const attempt = {
+            id,
+            traceId: audit.traceId,
+            decisionId: audit.decisionId,
+            intentId: audit.intentId,
+            platformId: audit.platformId,
+            capability: audit.capability,
+            channel: audit.channel,
+            status,
+            failureClass: audit.failureClass,
+            idempotencyKey: audit.idempotencyKey,
+            metadata: {
+                ...(audit.metadata ?? {}),
+                ...(audit.outcome === "sampled_telemetry" ? { sampledTelemetry: true } : {}),
+            },
+            startedAt: now,
+            finishedAt: status === "started" ? undefined : now,
+        };
+        await this.telemetry.recordExecutionAttempt(attempt);
+        return { recordId: id, appendedAt: attempt.finishedAt ?? attempt.startedAt ?? now };
+    }
+    async recordStateGovernance(event) {
+        const createdAt = event.createdAt ?? new Date().toISOString();
+        const reason = event.decisionId !== undefined && event.decisionId.length > 0
+            ? `${event.reason} decisionId=${event.decisionId}`
+            : event.reason;
+        await this.governance.recordOperationalGovernanceEvent({
+            id: event.id,
+            eventType: event.kind,
+            traceId: event.traceId,
+            statusTo: "recorded",
+            reason,
+            assetPath: event.artifactPath,
+            supportingSources: event.supportingSources,
+            createdAt,
+        });
+        return { recordId: event.id, appendedAt: createdAt };
+    }
+}
+export function createGovernancePlaneRecorder(db) {
+    return new GovernancePlaneRecorder(new ExecutionTelemetry(db), new GovernanceAudit(db));
+}