@sekiban/dcb-runtime 0.2.0

package/dist/trace/CommitTrace.d.ts

@@ -0,0 +1,405 @@
+import { type UnattributedRatio } from "./AttributionRatio";
+import type { DurableObjectHandlerObservation } from "./ObservationStream";
+/**
+ * Trace-only commit attribution support.
+ *
+ * This module deliberately has no dependency on the commit protocol or on
+ * Durable Object storage. It turns the host-owned manifest into the runtime
+ * vocabulary and delegates real parentage to Cloudflare's active async
+ * tracing context. The in-memory records are an observation adapter used by
+ * unit tests and the B0 evidence tooling; they never cross a public wire.
+ */
+export type CommitTraceSchema = "sdt.commit/v1" | "sdt.commit/v2" | "sdt.commit.reconcile/v1" | "sdt.commit.repair/v1";
+export type CommitTraceFace = "pre-admission" | "accepted" | "reconcile-root" | "repair-root";
+export type CommitTraceActorClass = "ROOT" | "BOOTSTRAP" | "JOURNAL" | "ALLOCATOR" | "TAG" | "REPAIR";
+export type TraceAttributeValue = string | number | boolean;
+export interface CommitTraceProviderAdapter {
+    readonly scriptVersion?: string;
+    readonly colo?: string;
+    /** Observed only. G30 must never use this in a control branch. */
+    readonly placement?: string;
+    readonly cpuTimeMs?: number;
+    readonly wallTimeMs?: number;
+}
+export interface NativeTraceSpan {
+    readonly isTraced?: boolean;
+    setAttribute(key: string, value: TraceAttributeValue | undefined): unknown;
+}
+export interface NativeTracing {
+    enterSpan<T, A extends unknown[]>(name: string, callback: (span: NativeTraceSpan, ...args: A) => T, ...args: A): T;
+}
+/**
+ * The portable runtime must remain importable from Node-side provider and
+ * contract tooling.  Cloudflare-only entrypoints inject the real tracer;
+ * this adapter preserves the trace-only, fail-open contract everywhere else.
+ */
+export declare const noOpNativeTracing: NativeTracing;
+/**
+ * A request handler can use the platform context without importing the
+ * Cloudflare-only module into the portable Node/provider graph.
+ */
+export declare function nativeTracingFromContext(context?: Pick<ExecutionContext, "tracing">): NativeTracing;
+export interface CommitTraceClock {
+    now(): number;
+}
+export interface CommitTraceSpan {
+    readonly rowId: string;
+    readonly schema: CommitTraceSchema;
+    readonly face: CommitTraceFace;
+    readonly span: string;
+    readonly emitter: string;
+    readonly logicalParent: string | null;
+    readonly rootId: string;
+    readonly clockDomain: "caller" | "callee";
+    readonly startMs: number;
+    readonly endMs: number;
+    readonly present: true;
+    readonly attributes: Readonly<Record<string, TraceAttributeValue>>;
+    readonly zeroDurationPlatformLimited: boolean;
+}
+export interface CommitTraceSnapshot {
+    readonly schema: CommitTraceSchema;
+    readonly rootId: string;
+    readonly correlationId: string;
+    readonly serviceId: string;
+    readonly spans: readonly CommitTraceSpan[];
+    readonly provider: CommitTraceProviderAdapter;
+    readonly diagnostics: Readonly<Record<string, TraceAttributeValue>>;
+    /** Private evidence/export field; never a public V1 response member. */
+    readonly unattributed?: UnattributedRatio;
+    readonly attributionGatePassed?: boolean;
+    /**
+     * In-process verifier result. This is an observation adapter for a trace
+     * sink/exporter only; it is never copied onto a Response or a native span.
+     * A verifier finding is deliberately fail-open so measurement cannot alter
+     * the commit protocol it observes.
+     */
+    readonly runtimeVerification?: Readonly<{
+        readonly passed: boolean;
+        readonly code?: string;
+    }>;
+}
+export interface CommitTraceSink {
+    record(snapshot: CommitTraceSnapshot): void;
+}
+/** Structural verifier hook supplied by the owning runtime module. */
+export interface CommitTraceRuntimeVerifier {
+    verify(snapshot: CommitTraceSnapshot): void;
+}
+export interface CommitTraceOptions {
+    readonly schema: CommitTraceSchema;
+    readonly correlationId: string;
+    readonly serviceId: string;
+    readonly provider?: CommitTraceProviderAdapter;
+    readonly nativeTracing?: NativeTracing;
+    readonly sink?: CommitTraceSink;
+    readonly clock?: CommitTraceClock;
+    readonly diagnostics?: Readonly<Record<string, TraceAttributeValue>>;
+    readonly runtimeVerifier?: CommitTraceRuntimeVerifier;
+    /**
+     * Optional observation-only work scheduled after the response object has
+     * been assembled but before the root callback unwinds.  Production's
+     * `waitUntil` integration is deliberately outside this trace model: the
+     * returned promise is detached, so it can neither extend S00 nor alter the
+     * commit result.  The seam lets the runtime oracle prove that boundary
+     * without adding an ExecutionContext or a V1 wire field to CommitWorker.
+     */
+    readonly scheduleDetachedObservation?: () => Promise<void> | void;
+    /**
+     * Attribution observes an existing protocol.  Production callers keep this
+     * enabled so a tracing/exporter defect can never reject, retry, or replay a
+     * commit.  Focused unit or mutation tests may opt into strict behavior to
+     * assert a local schema guard directly.
+     */
+    readonly failOpen?: boolean;
+}
+interface ManifestRow {
+    readonly rowId: string;
+    readonly span: string;
+    readonly emitter: string;
+    readonly logicalParent: string | null;
+    readonly coverage: boolean;
+    readonly kind: string;
+}
+interface ManifestAttribute {
+    readonly type: string;
+    readonly values?: readonly string[];
+    readonly faces: Readonly<Record<CommitTraceFace, "required" | "optional" | "forbidden">>;
+    /** Optional row-level scope layered on top of the schema face. */
+    readonly rowScope?: readonly string[];
+    /** A fact that is only available while its still-open root is active. */
+    readonly factDerived?: boolean;
+}
+interface ManifestBoundary {
+    readonly name: string;
+    readonly requiredRows: readonly string[];
+    readonly conditionalRows: readonly unknown[];
+    readonly forbiddenRows: readonly string[];
+}
+interface TraceManifest {
+    readonly schemas: Readonly<Record<CommitTraceSchema, {
+        readonly rows: readonly ManifestRow[];
+        readonly boundaries?: readonly ManifestBoundary[];
+        readonly recoveryDag?: Readonly<Record<string, unknown>>;
+        readonly terminalAtEntryBoundary?: Readonly<{
+            name?: string;
+        }>;
+    }>>;
+    readonly attributeMatrix: {
+        readonly faces: readonly CommitTraceFace[];
+        readonly states: readonly string[];
+        readonly attributes: Readonly<Record<string, ManifestAttribute>>;
+    };
+}
+/**
+ * Stable, non-authoritative, non-cryptographic observation key. Four
+ * independent FNV-1a lanes yield the lower-case 64-hex spelling mandated by
+ * the trace schema without making the key a protocol or storage authority.
+ */
+export declare function stableTraceHash(value: string): string;
+/**
+ * The DO request bodies already carry attemptId, while G30 cannot add a
+ * correlation wire field. This deterministic, distinct observation key lets
+ * independently exported caller/callee spans be joined without treating
+ * attempt.id and correlation.id as the same attribute.
+ */
+export declare function correlationIdForAttempt(attemptId: string): string;
+export declare function createTraceCorrelationId(): string;
+export declare function traceManifest(): TraceManifest;
+export interface CommitTraceSpanOptions {
+    readonly face: CommitTraceFace;
+    readonly actorClass: CommitTraceActorClass;
+    readonly actorKey?: string;
+    readonly attemptId?: string;
+    readonly outcome?: string;
+    readonly httpStatus?: number;
+    readonly phaseOrdinal?: number;
+    readonly retryIndex?: number;
+    readonly memberIndex?: number;
+    readonly tag?: string;
+    readonly attributes?: Readonly<Record<string, TraceAttributeValue>>;
+    readonly zeroDurationPlatformLimited?: boolean;
+    readonly clockDomain?: "caller" | "callee";
+}
+interface ScopeState {
+    readonly rootId: string;
+    readonly currentRowId: string | null;
+    readonly face: CommitTraceFace;
+    readonly actorClass: CommitTraceActorClass;
+    readonly actorKey?: string;
+    readonly attemptId?: string;
+    readonly clockDomain: "caller" | "callee";
+    /** A failed observation subtree invokes application work without tracing. */
+    readonly observationDisabled?: boolean;
+}
+/**
+ * A scope is the test/evidence adapter's reflection of callback nesting. It
+ * does not accept a native span context or a parent span ID; Cloudflare owns
+ * real parentage through enterSpan's active async context.
+ */
+export declare class CommitTraceScope {
+    private readonly trace;
+    private readonly state;
+    constructor(trace: CommitTrace, state: ScopeState);
+    accepted(attemptId: string): CommitTraceScope;
+    withActor(actorClass: CommitTraceActorClass, actorKey: string, clockDomain?: "caller" | "callee"): CommitTraceScope;
+    fork(): CommitTraceScope;
+    span<T>(rowId: string, options: Omit<CommitTraceSpanOptions, "face" | "actorClass" | "actorKey" | "attemptId" | "clockDomain"> & {
+        readonly face?: CommitTraceFace;
+        readonly actorClass?: CommitTraceActorClass;
+        readonly actorKey?: string;
+        readonly attemptId?: string;
+        readonly clockDomain?: "caller" | "callee";
+    }, callback: (scope: CommitTraceScope) => T | Promise<T>): Promise<T>;
+}
+export declare class CommitTrace {
+    private readonly options;
+    private readonly spans;
+    private readonly emittedWorkerRows;
+    private readonly provider;
+    private readonly diagnostics;
+    private correlationId;
+    private activeRootId;
+    private activeRootRecord;
+    private activeRootNative;
+    private nextRootIndex;
+    private runtimeVerification;
+    private observationFailureCode;
+    constructor(options: CommitTraceOptions);
+    root<T>(rowId: string, options: Omit<CommitTraceSpanOptions, "face" | "actorClass"> & {
+        readonly face?: CommitTraceFace;
+        readonly actorClass?: CommitTraceActorClass;
+    }, callback: (scope: CommitTraceScope) => T | Promise<T>): Promise<T>;
+    /**
+     * Returns the Worker-local rows for which a native tracing callback was
+     * actually entered on this request. This private-in-effect observation is
+     * copied only into sdt.observe/v1 by CommitWorker; it never changes the
+     * sealed trace schema, verifier, public response, or a control branch.
+     */
+    emittedWorkerRowIds(): readonly string[];
+    snapshot(): CommitTraceSnapshot;
+    /**
+     * A request becomes accepted after admission. Updating the still-active root
+     * preserves the single root correlation while S01 remains an honest
+     * pre-admission record with no attempt.id.
+     */
+    markAccepted(attemptId: string): void;
+    /**
+     * Observation-only consumers can read the post-admission correlation after
+     * it has been written to S00. This exposes no wire field and never controls
+     * a commit decision or native-parent relationship.
+     */
+    observationCorrelationId(): string;
+    span<T>(state: ScopeState, rowId: string, options: CommitTraceSpanOptions, callback: (scope: CommitTraceScope) => T | Promise<T>): Promise<T>;
+    private finish;
+    private recordEmittedWorkerRow;
+    private attributesFor;
+    private setNativeAttributes;
+    private outcomeFromResult;
+    private clock;
+    private now;
+    private publishSnapshot;
+    /**
+     * A telemetry/export failure is retained as an observation failure, but a
+     * detached task is never allowed to hold the root open or replace the
+     * application's Response.  Keeping this as a method makes the exact
+     * `void` call at root finalization mutation-testable.
+     */
+    private scheduleDetachedObservation;
+    private isFailOpen;
+    private observationVerification;
+    private noteObservationFailure;
+    /**
+     * If a platform tracer declines a span before invoking its callback, run
+     * the application callback once without a span.  Once the callback has
+     * started, its own error remains authoritative and is never replayed.
+     */
+    private enterNativeSpan;
+}
+export interface DurableObjectActivationObservation {
+    readonly activationId: string;
+    readonly first: boolean;
+    /** Monotonic-in-practice wall-clock observation; never persisted. */
+    readonly handlerStartedAtMs: number;
+    readonly constructorToHandlerMs: number;
+}
+/**
+ * Constructor-only activation observation. It never touches Durable Object
+ * storage and callers must invoke beginHandler synchronously before awaiting.
+ */
+export declare class DurableObjectActivation {
+    readonly activationId: `${string}-${string}-${string}-${string}-${string}`;
+    private readonly constructedAtMs;
+    private first;
+    beginHandler(): DurableObjectActivationObservation;
+}
+export declare function beginWorkerInvocationObservation(): Readonly<{
+    isolateInstanceId: string;
+    firstInvocation: boolean;
+}>;
+export interface IdleLedgerEntry {
+    readonly actorKeyHash: string;
+    readonly endMs: number;
+    readonly complete: boolean;
+}
+/**
+ * This deliberately accepts only an externally collected complete ledger.
+ * The DO runtime never records timestamps or idle observations in storage.
+ */
+export declare function observedIdleGapLowerBoundMs(previous: IdleLedgerEntry | undefined, currentStartMs: number): number | null;
+export declare const IDLE_EXPERIMENT_SCHEDULE_MS: readonly [2000, 15000, 180000];
+/**
+ * G30 intentionally does not infer a Durable Object reactivation cause from
+ * elapsed time.  Idle eviction timings are only loose platform behaviour and
+ * are not a durable fact.  The evidence runner may classify a constructor
+ * observation only from a deployed-version change or explicit platform
+ * evidence; otherwise it remains honestly unknown.
+ */
+export type ReactivationCause = "deployment-correlated" | "platform-evidenced" | "unknown";
+export interface ReactivationEvidence {
+    readonly deployedVersionChanged: boolean;
+    readonly platformEvidence?: string;
+    /**
+     * Retained as a measured axis only.  It must never decide a reactivation
+     * cause: Cloudflare may hibernate/evict at variable times.
+     */
+    readonly elapsedMs?: number;
+}
+export declare function classifyReactivationCause(evidence: ReactivationEvidence): ReactivationCause;
+export interface NativeCommitSpanInput {
+    readonly schema: CommitTraceSchema;
+    /** The manifest face governs the complete emitted attribute set. */
+    readonly face: CommitTraceFace;
+    /** Exact host-manifest row emitted by this callback boundary. */
+    readonly rowId: string;
+    readonly correlationId: string;
+    /** Repair roots may cover more than one attempt. */
+    readonly attemptId?: string;
+    readonly serviceId: string;
+    readonly actorClass: CommitTraceActorClass;
+    readonly actorKey: string;
+    readonly activation: DurableObjectActivationObservation;
+    readonly operation: string;
+    readonly kind: "root" | "nested" | "callee" | "direct" | "fanout-stage" | "fanout-member" | "sequential-stage" | "sequential-member";
+    readonly attributes?: Readonly<Record<string, TraceAttributeValue>>;
+}
+export interface NativeActorHandleIdentity {
+    readonly attemptId: string;
+    readonly serviceId: string;
+    /** Optional durable actor identity resolved with the attempt context. */
+    readonly actorKey?: string;
+}
+export interface NativeActorHandleInput {
+    readonly actorClass: CommitTraceActorClass;
+    readonly actorKey: string;
+    readonly activation: DurableObjectActivationObservation;
+    /** Separate sdt.observe/v1 log stream; never a commit-span attribute. */
+    readonly observation?: DurableObjectHandlerObservation;
+}
+/**
+ * Alarm identity is intentionally supplied by the Journal's durable facts,
+ * never guessed from a timestamp or a platform automatic attribute.  The
+ * helper starts the custom span before those facts are read, then annotates
+ * that already-active callback context once the Journal has decoded them.
+ */
+export interface NativeReconcileRootIdentity {
+    readonly attemptId: string;
+    readonly serviceId: string;
+    readonly actorKey: string;
+    readonly activation: DurableObjectActivationObservation;
+    readonly alarmEventId: string;
+    readonly invocationId: string;
+    readonly retryCount: number;
+    readonly isRetry: boolean;
+    readonly prefixAtEntry: string;
+}
+/**
+ * A reconciliation fact becomes available only after durable recovery reads.
+ * R00 remains open for the handler's whole callback, so it is the sole span
+ * to which the host contract permits this late attribute.
+ */
+export interface NativeReconcileRootFacts {
+    setRecoveryKind(kind: string): void;
+}
+/**
+ * Emit a real Cloudflare custom span in the currently active async context.
+ * There is intentionally no parent argument: Worker/DO parentage is the
+ * platform's concern, and this function only supplies manifest attributes.
+ */
+export declare function enterNativeCommitSpan<T>(nativeTracing: NativeTracing, name: string, input: NativeCommitSpanInput, callback: () => T | Promise<T>): Promise<T>;
+/**
+ * Emits S16 at the Durable Object handler boundary. Identity may only become
+ * available after a clone of the internal request body is decoded, but the
+ * custom span itself begins synchronously at handler entry. Failure to derive
+ * an internal identity merely leaves that non-commit actor invocation outside
+ * the sdt.commit universe; it never changes the request's control path.
+ */
+export declare function enterNativeActorHandleSpan<T>(nativeTracing: NativeTracing, input: NativeActorHandleInput, resolveIdentity: () => Promise<NativeActorHandleIdentity | undefined>, callback: () => T | Promise<T>): Promise<T>;
+/**
+ * Emit R00 at actual alarm-handler entry.  The Journal must read the durable
+ * record to discover the generation/attempt identity, so resolving it inside
+ * the active callback is the only way to keep both the entry boundary and
+ * Cloudflare-owned parentage without synthetic parent IDs.
+ */
+export declare function enterNativeReconcileRootSpan<T>(nativeTracing: NativeTracing, resolveIdentity: () => Promise<NativeReconcileRootIdentity | undefined>, callback: (identity: NativeReconcileRootIdentity | undefined, facts: NativeReconcileRootFacts) => T | Promise<T>): Promise<T>;
+export {};