@opengeni/observability 0.8.29 → 0.8.30

package/dist/export-queue.d.ts

@@ -0,0 +1,13 @@
+/** One bounded lane per observer. A hung custom transport holds one slot, not an unbounded retry fanout. */
+export declare class ExportQueue {
+    private readonly observer;
+    private readonly capacity;
+    private readonly queue;
+    private running;
+    constructor(observer: (outcome: "exported" | "retried" | "failed" | "dropped") => void, capacity?: number);
+    private observe;
+    enqueue(send: () => Promise<void>): void;
+    private start;
+    private drain;
+    flush(timeoutMs?: number): Promise<void>;
+}

package/dist/failure-diagnostic.d.ts

@@ -0,0 +1,50 @@
+declare const CODES: readonly ["api_startup_failed", "api_unhandled_rejection", "api_uncaught_exception", "db_deadlock", "db_serialization_failure", "db_failure", "retained_process_fenced", "retained_process_proof_failed"];
+declare const STAGES: readonly ["startup", "running", "session_events.append_generic", "session_events.append_for_turn_attempt", "preclaim", "session_attempts.claim", "failure_settlement", "sandbox_retained_processes.proof"];
+declare const RETRIES: readonly ["not_retryable", "exhausted", "unknown"];
+export declare const DIAGNOSTIC_SOURCE_FILES: readonly ["apps/api/src/index.ts", "apps/api/src/app.ts", "apps/api/src/fatal-process-boundary.ts", "apps/api/dist/process/index.js", "apps/worker/src/activities/agent-turn/run.ts", "apps/worker/src/activities/agent-turn/claim.ts", "apps/worker/src/activities/agent-turn/failure-settlement.ts", "apps/worker/src/activities/sandbox-lease.ts", "apps/worker/dist/process/index.js", "packages/db/src/index.ts", "packages/db/src/persistence-errors.ts", "packages/storage/src/index.ts", "packages/observability/src/index.ts"];
+export declare const DIAGNOSTIC_POSTGRES_FUNCTIONS: readonly ["admit_session_attempt_personal_resources"];
+export type FailureDiagnosticInput = {
+    code: (typeof CODES)[number];
+    stage: (typeof STAGES)[number];
+    retryDecision?: (typeof RETRIES)[number];
+    error: unknown;
+    attemptId?: string;
+    sessionId?: string;
+    processId?: string;
+    turnId?: string;
+    attempts?: number;
+    sqlState?: string | null;
+    constraint?: string;
+    eventTypes?: readonly string[];
+};
+/** No arbitrary property reads, Error.toJSON, messages, SQL, parameters or function names. */
+export declare function failureDiagnostic(input: FailureDiagnosticInput, revision?: string): {
+    schema: string;
+    diagnosticId: `${string}-${string}-${string}-${string}-${string}`;
+    code: "api_startup_failed" | "api_uncaught_exception" | "api_unhandled_rejection" | "db_deadlock" | "db_failure" | "db_serialization_failure" | "retained_process_fenced" | "retained_process_proof_failed";
+    stage: "failure_settlement" | "preclaim" | "running" | "sandbox_retained_processes.proof" | "session_attempts.claim" | "session_events.append_for_turn_attempt" | "session_events.append_generic" | "startup";
+    retryDecision: "exhausted" | "not_retryable" | "unknown";
+    attemptId: string | undefined;
+    sessionId: string | undefined;
+    processId: string | undefined;
+    turnId: string | undefined;
+    attempts: number | undefined;
+    sqlState: string | undefined;
+    constraint: string | undefined;
+    deploymentRevision: string | undefined;
+    causes: {
+        kind: string;
+        frames: Array<{
+            locationHash: string;
+            source?: string;
+            line: number;
+            column: number;
+        }>;
+    }[];
+    postgresContext: {
+        functionName: string;
+        line: number;
+    }[];
+    eventTypes: string[];
+};
+export {};

package/dist/index.d.ts

@@ -1,3 +1,7 @@
+import { type TraceContext } from "./trace-context.js";
+import { type FailureDiagnosticInput } from "./failure-diagnostic.js";
+export type { FailureDiagnosticInput } from "./failure-diagnostic.js";
+export { currentTraceContext, withTraceContext, parseTraceparent, traceparent, admissionTraceContext, linkCurrentSpanToAdmission, type TraceContext, } from "./trace-context.js";
 export type AttributeValue = string | number | boolean | null | undefined;
 export type Attributes = Record<string, AttributeValue>;
 export type ObservabilitySettings = {
@@ -8,6 +12,9 @@ export type ObservabilitySettings = {
     observabilityMetricsEnabled: boolean;
     observabilityOtlpEndpoint?: string | undefined;
     observabilityOtlpHeaders: string;
+    /** Explicit restricted OTLP logs destination; never falls back to the public exporter. */
+    observabilityDiagnosticsEndpoint?: string | undefined;
+    observabilityDiagnosticsHeaders?: string | undefined;
     sandboxOwnershipEnabled?: boolean | undefined;
     sandboxLazyProvisionEnabled?: boolean | undefined;
     rigVerificationLeaseOwnershipEnabled?: boolean | undefined;
@@ -20,6 +27,7 @@ export type ObservabilityOptions = {
 export type Span = {
     traceId: string;
     spanId: string;
+    addLink?: (context: TraceContext) => void;
     end: (input?: {
         attributes?: Attributes;
         error?: unknown;
@@ -34,6 +42,10 @@ export type MetricLabels = Record<string, AttributeValue>;
  * digest.
  */
 export declare function sandboxLeaseTelemetryKey(workspaceId: string, sandboxGroupId: string): string;
+/** Content-free lookup key for a worker execution attempt, never a metric label.
+ * Operators derive it from authorized session/attempt records to find a trace
+ * without publishing raw tenancy or conversation identifiers to telemetry. */
+export declare function turnExecutionTelemetryKey(workspaceId: string, sessionId: string, attemptId: string): string;
 /**
  * Stable selectors shared by OpenGeni's runtime metrics and optional
  * Prometheus/Grafana distribution. Operators can use these values for custom
@@ -68,26 +80,6 @@ export declare const OPENGENI_OBSERVABILITY_DISTRIBUTION: {
  * credential, name, or content, may ever become a label here.
  */
 export declare const TENANCY_COMPATIBILITY_LANES: readonly [
-/**
- * A provider connection carrying `authority_scope = 'legacy_user'` was
- * resolved for accepted use: a personal row with no common authority or
- * grant, admitted through `legacy_user_compatibility` provenance instead of
- * an explicit delegation. Migration 0256 backfilled the existing rows, but
- * its `bind_connection_authority` trigger still classifies a NEW personal
- * connection this way whenever the inserting subject has no active
- * organization membership, so this counter is expected to stay above zero
- * until that classification changes. That is the finding, not a defect.
- */
-"connection_legacy_user", 
-/**
- * A workspace-scope connection ref carried no connection id, so the
- * accepted-use authority (migration 0279) could not identify the exact row
- * and the request fell back to the unprivileged pre-snapshot resolution.
- * This lane writes no `connection_use_audit_facts` row and leaves no durable
- * trace of any kind, so a use counter is the only possible evidence it was
- * taken at all.
- */
-"connection_pre_snapshot_ref", 
 /**
  * A NEW persistable `/workspace` mutation was refused because the writer
  * behind it has no recorded authority (`authority_unattributed`): either a
@@ -111,17 +103,21 @@ export type SandboxOperationMetricObservation = {
     op: string;
     outcome: "ok" | "not_found" | "failed";
     durationMs: number;
+    materializationFailureReason?: string;
 };
 export declare function createObservability(settings: ObservabilitySettings, options: ObservabilityOptions): Observability;
 export declare class Observability {
     private readonly settings;
     private readonly options;
+    private spanBatch;
+    private spanBatchScheduled;
+    private readonly diagnosticQueue;
     private readonly registry;
     private readonly counters;
     private readonly gauges;
     private readonly histograms;
     private readonly registrations;
-    private readonly pendingExports;
+    private readonly exportQueue;
     private readonly now;
     private readonly exporter;
     private readonly resourceAttributes;
@@ -139,7 +135,11 @@ export declare class Observability {
     warn(message: string, attributes?: Attributes): void;
     error(message: string, attributes?: Attributes): void;
     log(level: "debug" | "info" | "warn" | "error", message: string, attributes?: Attributes): void;
-    startSpan(name: string, attributes?: Attributes): Span;
+    startSpan(name: string, attributes?: Attributes, options?: {
+        parent?: TraceContext | null;
+        links?: TraceContext[];
+        startTimeMs?: number;
+    }): Span;
     recordHttpRequest(input: {
         method: string;
         route: string;
@@ -177,14 +177,19 @@ export declare class Observability {
         buckets?: number[];
     }): void;
     prometheusMetrics(): Promise<string>;
-    /** Wait for every OTLP export accepted before or during this drain. */
-    flush(): Promise<void>;
+    /** Emit a content-free anchor after successful, non-replayed admission. */
+    recordAdmissionTrace(eventId: string): void;
+    /** Emit a closed protected record independently of application persistence. */
+    recordFailureDiagnostic(input: FailureDiagnosticInput): string;
+    /** Best-effort bounded drain, including when a custom transport never settles. */
+    flush(timeoutMs?: number): Promise<void>;
     private counter;
     private gauge;
     private histogram;
     private register;
     private assertRegistration;
     private exportSpan;
+    private submitSpanBatch;
 }
 /**
  * Convert routed sandbox-provider observations into one bounded Prometheus
@@ -198,6 +203,14 @@ export declare class Observability {
  * then swallowed at this telemetry boundary.
  */
 export declare function sandboxOperationMetricObserver(observability: Observability): (observation: SandboxOperationMetricObservation) => void;
+/** Capture waits remain separate from physical provider-call accounting. */
+export declare function sandboxCaptureWaitMetricObserver(observability: Observability): (observation: {
+    backend: string;
+    op: string;
+    outcome: "ok" | "failed";
+    durationMs: number;
+    captureWaitStage: "admission" | "provider";
+}) => void;
 export type InteractionOperationMetricObservation = {
     resource: string;
     operation: string;
@@ -236,6 +249,16 @@ export type WorkspaceInsightsMetricObservation = {
  * tenant ids and caller-supplied provider/model values out of telemetry.
  */
 export declare function workspaceInsightsMetricObserver(observability: Observability | null | undefined): (observation: WorkspaceInsightsMetricObservation) => void;
+/** Dispatcher observations count attempts, including repeated observations of
+ * the same revision. Transport acceptance is never an admission receipt. */
+export declare function recordWorkflowWakeReconciliation(observability: Observability, result: {
+    signaled: number;
+    delivered: number;
+    pendingAdmission: number;
+    unconfirmed: number;
+    failed: number;
+    pendingAdmissionBlockers: Record<string, number | undefined>;
+}): void;
 export type StartupDependencyRetryEvent = {
     label: string;
     attempt: number;