@sekiban/dcb-runtime 0.2.0

package/dist/trace/CommitTrace.js

@@ -0,0 +1,1008 @@
+import commitTraceManifestJson from "../../../../contracts/commit-trace-manifest.json";
+import { calculateUnattributedRatio } from "./AttributionRatio";
+const NOOP_NATIVE_TRACE_SPAN = Object.freeze({
+    isTraced: false,
+    setAttribute: () => undefined,
+});
+/**
+ * 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 const noOpNativeTracing = Object.freeze({
+    enterSpan(_name, callback, ...args) {
+        return callback(NOOP_NATIVE_TRACE_SPAN, ...args);
+    },
+});
+/**
+ * A request handler can use the platform context without importing the
+ * Cloudflare-only module into the portable Node/provider graph.
+ */
+export function nativeTracingFromContext(context) {
+    const native = context?.tracing;
+    return native ?? noOpNativeTracing;
+}
+const manifest = commitTraceManifestJson;
+const DEFAULT_CLOCK = { now: () => Date.now() };
+const RAW_TAG_KEY = /(^|[._])tag($|[._])/i;
+const HEX64 = /^[0-9a-f]{64}$/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const NATIVE_ROW_ID_ATTRIBUTE = "sdt.row.id";
+function hasOwn(value, key) {
+    return Object.prototype.hasOwnProperty.call(value, key);
+}
+function rowFor(schema, rowId) {
+    const schemaRows = manifest.schemas[schema]?.rows;
+    const row = schemaRows?.find((entry) => entry.rowId === rowId);
+    if (row === undefined) {
+        throw new Error(`Commit trace row ${rowId} is not defined by ${schema}`);
+    }
+    return row;
+}
+/**
+ * G30's emitted-row inventory is deliberately limited to rows emitted from
+ * the primary Worker process. It is an observation-side discriminator, not a
+ * new trace attribute or a cross-actor propagation mechanism.
+ */
+function isWorkerLocalEmitter(row) {
+    return row.emitter === "root-worker" || row.emitter === "caller-worker";
+}
+function faceState(attribute, face) {
+    const matrix = manifest.attributeMatrix.attributes[attribute];
+    if (matrix === undefined) {
+        throw new Error(`Commit trace attribute ${attribute} is not declared by the authority matrix`);
+    }
+    const state = matrix.faces[face];
+    if (state !== "required" && state !== "optional" && state !== "forbidden") {
+        throw new Error(`Commit trace matrix omits face ${face} for ${attribute}`);
+    }
+    return state;
+}
+function rowScopedState(declaration, face, rowId) {
+    if (declaration.rowScope !== undefined && !declaration.rowScope.includes(rowId))
+        return "forbidden";
+    return declaration.faces[face];
+}
+function asTraceValue(value, name) {
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean")
+        return value;
+    throw new Error(`Commit trace attribute ${name} must be scalar`);
+}
+/**
+ * Keep the callback-boundary emission path subject to the same typed matrix
+ * as the in-memory/export verifiers. A malformed observation remains
+ * fail-open for the commit itself, but it must never be emitted as a
+ * schema-conformant custom span.
+ */
+function assertAttributeValue(value, declaration, key) {
+    const type = declaration.type;
+    if (type === "hex64") {
+        if (typeof value !== "string" || !HEX64.test(value))
+            throw new Error(`Commit trace attribute ${key} must be lower-case 64-hex`);
+        return;
+    }
+    if (type === "uuid") {
+        if (typeof value !== "string" || !UUID.test(value))
+            throw new Error(`Commit trace attribute ${key} must be a UUID`);
+        return;
+    }
+    if (type === "boolean") {
+        if (typeof value !== "boolean")
+            throw new Error(`Commit trace attribute ${key} must be boolean`);
+        return;
+    }
+    if (type === "integer" || type === "non-negative-integer") {
+        if (typeof value !== "number" || !Number.isInteger(value) || (type === "non-negative-integer" && value < 0)) {
+            throw new Error(`Commit trace attribute ${key} must be ${type}`);
+        }
+        return;
+    }
+    if (typeof value !== "string")
+        throw new Error(`Commit trace attribute ${key} must be a string`);
+    if (type === "enum-from-manifest-recovery") {
+        const reconcile = manifest.schemas["sdt.commit.reconcile/v1"];
+        const recoveryKinds = Object.keys(reconcile.recoveryDag ?? {});
+        const terminalAtEntry = reconcile.terminalAtEntryBoundary?.name;
+        if (!recoveryKinds.includes(value) && value !== terminalAtEntry) {
+            throw new Error(`Commit trace attribute ${key} is not a manifest recovery kind`);
+        }
+        return;
+    }
+    if (declaration.values !== undefined && !declaration.values.includes(value)) {
+        throw new Error(`Commit trace attribute ${key} is not manifest-declared`);
+    }
+}
+function assertAttributeTypes(attributes) {
+    for (const [key, value] of Object.entries(attributes)) {
+        const declaration = manifest.attributeMatrix.attributes[key];
+        if (declaration === undefined)
+            continue;
+        assertAttributeValue(value, declaration, key);
+    }
+}
+function assertNoRawTagAttributes(attributes) {
+    for (const [key, value] of Object.entries(attributes)) {
+        if (key === "tag.key_hash")
+            continue;
+        if (RAW_TAG_KEY.test(key)) {
+            throw new Error(`Commit trace forbids raw tag attribute ${key}=${String(value)}`);
+        }
+    }
+}
+/**
+ * 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 function stableTraceHash(value) {
+    const masks = [
+        0xcbf29ce484222325n,
+        0x9e3779b185ebca87n,
+        0x84222325cbf29ce4n,
+        0x100000001b3n,
+    ];
+    const prime = 0x100000001b3n;
+    const modulus = (1n << 64n) - 1n;
+    return masks.map((seed, index) => {
+        let hash = seed;
+        for (let offset = 0; offset < value.length; offset += 1) {
+            hash ^= BigInt(value.charCodeAt(offset) + index);
+            hash = (hash * prime) & modulus;
+        }
+        return hash.toString(16).padStart(16, "0");
+    }).join("");
+}
+/**
+ * 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 function correlationIdForAttempt(attemptId) {
+    return `corr-${stableTraceHash(`sdt.commit/v1:${attemptId}`)}`;
+}
+export function createTraceCorrelationId() {
+    return crypto.randomUUID();
+}
+export function traceManifest() {
+    return manifest;
+}
+/**
+ * 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 class CommitTraceScope {
+    trace;
+    state;
+    constructor(trace, state) {
+        this.trace = trace;
+        this.state = state;
+    }
+    accepted(attemptId) {
+        return new CommitTraceScope(this.trace, {
+            ...this.state,
+            face: "accepted",
+            attemptId,
+        });
+    }
+    withActor(actorClass, actorKey, clockDomain = this.state.clockDomain) {
+        return new CommitTraceScope(this.trace, {
+            ...this.state,
+            actorClass,
+            actorKey,
+            clockDomain,
+        });
+    }
+    fork() {
+        return new CommitTraceScope(this.trace, { ...this.state });
+    }
+    async span(rowId, options, callback) {
+        return this.trace.span(this.state, rowId, {
+            face: options.face ?? this.state.face,
+            actorClass: options.actorClass ?? this.state.actorClass,
+            ...(options.actorKey === undefined && this.state.actorKey === undefined ? {} : { actorKey: options.actorKey ?? this.state.actorKey }),
+            ...(options.attemptId === undefined && this.state.attemptId === undefined ? {} : { attemptId: options.attemptId ?? this.state.attemptId }),
+            clockDomain: options.clockDomain ?? this.state.clockDomain,
+            ...(options.outcome === undefined ? {} : { outcome: options.outcome }),
+            ...(options.httpStatus === undefined ? {} : { httpStatus: options.httpStatus }),
+            ...(options.phaseOrdinal === undefined ? {} : { phaseOrdinal: options.phaseOrdinal }),
+            ...(options.retryIndex === undefined ? {} : { retryIndex: options.retryIndex }),
+            ...(options.memberIndex === undefined ? {} : { memberIndex: options.memberIndex }),
+            ...(options.tag === undefined ? {} : { tag: options.tag }),
+            ...(options.attributes === undefined ? {} : { attributes: options.attributes }),
+            ...(options.zeroDurationPlatformLimited === undefined ? {} : { zeroDurationPlatformLimited: options.zeroDurationPlatformLimited }),
+        }, callback);
+    }
+}
+export class CommitTrace {
+    options;
+    spans = [];
+    emittedWorkerRows = new Set();
+    provider;
+    diagnostics;
+    correlationId;
+    activeRootId;
+    activeRootRecord;
+    activeRootNative;
+    nextRootIndex = 0;
+    runtimeVerification;
+    observationFailureCode;
+    constructor(options) {
+        this.options = options;
+        this.provider = Object.freeze({ ...(options.provider ?? {}) });
+        this.diagnostics = Object.freeze({ ...(options.diagnostics ?? {}) });
+        this.correlationId = options.correlationId;
+    }
+    async root(rowId, options, callback) {
+        if (this.activeRootId !== undefined) {
+            throw new Error("Commit trace root is already active");
+        }
+        const rootId = `${this.options.correlationId}:${this.nextRootIndex++}`;
+        const state = {
+            rootId,
+            currentRowId: null,
+            face: options.face ?? "pre-admission",
+            actorClass: options.actorClass ?? "ROOT",
+            ...(options.actorKey === undefined ? {} : { actorKey: options.actorKey }),
+            ...(options.attemptId === undefined ? {} : { attemptId: options.attemptId }),
+            clockDomain: options.clockDomain ?? "caller",
+        };
+        this.activeRootId = rootId;
+        try {
+            return await this.span(state, rowId, {
+                face: state.face,
+                actorClass: state.actorClass,
+                ...(state.actorKey === undefined ? {} : { actorKey: state.actorKey }),
+                ...(state.attemptId === undefined ? {} : { attemptId: state.attemptId }),
+                clockDomain: state.clockDomain,
+                ...(options.outcome === undefined ? {} : { outcome: options.outcome }),
+                ...(options.httpStatus === undefined ? {} : { httpStatus: options.httpStatus }),
+                ...(options.phaseOrdinal === undefined ? {} : { phaseOrdinal: options.phaseOrdinal }),
+                ...(options.retryIndex === undefined ? {} : { retryIndex: options.retryIndex }),
+                ...(options.memberIndex === undefined ? {} : { memberIndex: options.memberIndex }),
+                ...(options.tag === undefined ? {} : { tag: options.tag }),
+                ...(options.attributes === undefined ? {} : { attributes: options.attributes }),
+                ...(options.zeroDurationPlatformLimited === undefined ? {} : { zeroDurationPlatformLimited: options.zeroDurationPlatformLimited }),
+            }, async (scope) => {
+                const result = await callback(scope);
+                // This has the same containment rule as a Worker waitUntil task: it
+                // is spawned while the response is being finalized, but is never
+                // awaited by S00.  The production entrypoint intentionally supplies
+                // no callback here; exporters may use it without touching protocol.
+                void this.scheduleDetachedObservation();
+                return result;
+            });
+        }
+        finally {
+            this.activeRootId = undefined;
+            this.activeRootRecord = undefined;
+            this.activeRootNative = undefined;
+            // A sink/exporter error is observation-only.  It must not replace the
+            // response or durable outcome produced by the callback above.
+            this.publishSnapshot();
+        }
+    }
+    /**
+     * 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() {
+        return Object.freeze([...this.emittedWorkerRows]);
+    }
+    snapshot() {
+        const rootId = this.spans.find((span) => span.logicalParent === null)?.rootId ?? `${this.correlationId}:none`;
+        const spans = Object.freeze(this.spans.map((span) => Object.freeze({
+            ...span,
+            attributes: Object.freeze({ ...span.attributes }),
+        })));
+        const accepted = this.options.schema === "sdt.commit/v1" && spans.some((span) => typeof span.attributes["attempt.id"] === "string");
+        const base = {
+            schema: this.options.schema,
+            rootId,
+            correlationId: this.correlationId,
+            serviceId: this.options.serviceId,
+            spans,
+            provider: this.provider,
+            diagnostics: this.diagnostics,
+            ...(this.runtimeVerification === undefined ? {} : { runtimeVerification: this.runtimeVerification }),
+        };
+        if (!accepted)
+            return Object.freeze(base);
+        try {
+            const unattributed = calculateUnattributedRatio(base);
+            return Object.freeze({
+                ...base,
+                unattributed,
+                attributionGatePassed: unattributed.unattributedRatio <= 0.05,
+            });
+        }
+        catch (error) {
+            // A malformed observation must be visible to evidence consumers, but
+            // its calculation cannot become a new commit failure.
+            this.noteObservationFailure(error);
+            return Object.freeze({
+                ...base,
+                runtimeVerification: this.observationVerification(),
+            });
+        }
+    }
+    /**
+     * 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) {
+        if (this.activeRootRecord === undefined)
+            return;
+        const correlationId = correlationIdForAttempt(attemptId);
+        // S00 begins before admission, but the accepted trace's root is the
+        // accepted face: S01 is the separately retained pre-admission row.  Keep
+        // the two phases distinct rather than leaking an attempt ID into a
+        // pre-admission record (or leaving the accepted root without one).
+        const attributes = {
+            ...this.activeRootRecord.attributes,
+            "correlation.id": correlationId,
+            "attempt.id": attemptId,
+            outcome: "accepted",
+        };
+        const record = Object.freeze({
+            ...this.activeRootRecord,
+            face: "accepted",
+            attributes: Object.freeze(attributes),
+        });
+        const index = this.spans.indexOf(this.activeRootRecord);
+        if (index >= 0)
+            this.spans[index] = record;
+        this.activeRootRecord = record;
+        this.correlationId = correlationId;
+        this.setNativeAttributes(this.activeRootNative, {
+            "correlation.id": correlationId,
+            "attempt.id": attemptId,
+            outcome: "accepted",
+        });
+    }
+    /**
+     * 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() {
+        return this.correlationId;
+    }
+    async span(state, rowId, options, callback) {
+        const disabledChild = () => new CommitTraceScope(this, {
+            rootId: state.rootId,
+            currentRowId: rowId,
+            face: options.face,
+            actorClass: options.actorClass,
+            ...(options.actorKey === undefined ? {} : { actorKey: options.actorKey }),
+            ...(options.attemptId === undefined ? {} : { attemptId: options.attemptId }),
+            clockDomain: options.clockDomain ?? state.clockDomain,
+            observationDisabled: true,
+        });
+        if (state.observationDisabled === true)
+            return callback(disabledChild());
+        let row;
+        let attributes;
+        try {
+            row = rowFor(this.options.schema, rowId);
+            if (row.logicalParent !== state.currentRowId) {
+                throw new Error(`Commit trace row ${rowId} must run under ${row.logicalParent ?? "a root"}, observed ${state.currentRowId ?? "a root"}`);
+            }
+            if (row.logicalParent === null && this.activeRootId !== state.rootId) {
+                throw new Error(`Commit trace root ${rowId} is not active`);
+            }
+            attributes = this.attributesFor(row, options);
+        }
+        catch (error) {
+            if (!this.isFailOpen())
+                throw error;
+            this.noteObservationFailure(error);
+            return callback(disabledChild());
+        }
+        const execute = async (native) => {
+            this.setNativeAttributes(native, nativeAttributesWithRowId(this.options.schema, rowId, attributes));
+            this.recordEmittedWorkerRow(row, native);
+            const startMs = this.now();
+            const record = {
+                rowId,
+                schema: this.options.schema,
+                face: options.face,
+                span: row.span,
+                emitter: row.emitter,
+                logicalParent: row.logicalParent,
+                rootId: state.rootId,
+                clockDomain: options.clockDomain ?? state.clockDomain,
+                startMs,
+                endMs: startMs,
+                present: true,
+                attributes: Object.freeze({ ...attributes }),
+                zeroDurationPlatformLimited: options.zeroDurationPlatformLimited ?? false,
+            };
+            this.spans.push(record);
+            if (row.logicalParent === null) {
+                this.activeRootRecord = record;
+                this.activeRootNative = native;
+            }
+            const child = new CommitTraceScope(this, {
+                rootId: state.rootId,
+                currentRowId: rowId,
+                face: options.face,
+                actorClass: options.actorClass,
+                ...(options.actorKey === undefined ? {} : { actorKey: options.actorKey }),
+                ...(options.attemptId === undefined ? {} : { attemptId: options.attemptId }),
+                clockDomain: options.clockDomain ?? state.clockDomain,
+            });
+            try {
+                const result = await callback(child);
+                const final = this.finish(record, native, this.outcomeFromResult(result, options.outcome, options.httpStatus));
+                if (row.logicalParent === null)
+                    this.activeRootRecord = final;
+                return result;
+            }
+            catch (failure) {
+                const final = this.finish(record, native, {
+                    outcome: options.outcome ?? "exception",
+                    ...(options.httpStatus === undefined ? {} : { httpStatus: options.httpStatus }),
+                });
+                if (row.logicalParent === null)
+                    this.activeRootRecord = final;
+                throw failure;
+            }
+        };
+        const native = this.options.nativeTracing;
+        return native === undefined
+            ? execute(undefined)
+            : this.enterNativeSpan(native, row.span, execute);
+    }
+    finish(existing, native, outcome) {
+        // markAccepted replaces the still-open S00 record so it can move from
+        // the pre-admission to accepted face. Finish the replacement rather than
+        // silently leaving its terminal outcome behind in the in-memory evidence
+        // adapter. Normal spans retain identity and follow the fast path.
+        const current = this.activeRootRecord !== undefined && existing.logicalParent === null
+            ? this.activeRootRecord
+            : existing;
+        const attributes = {
+            ...current.attributes,
+            ...(outcome?.outcome === undefined ? {} : { outcome: outcome.outcome }),
+            ...(outcome?.httpStatus === undefined ? {} : { "http.status": outcome.httpStatus }),
+        };
+        const endMs = this.now();
+        const next = Object.freeze({
+            ...current,
+            endMs,
+            // Cloudflare may quantize custom spans to a zero-length interval. The
+            // row remains present; duration is not used as a proxy for emission.
+            zeroDurationPlatformLimited: current.zeroDurationPlatformLimited || endMs === current.startMs,
+            attributes: Object.freeze(attributes),
+        });
+        const index = this.spans.indexOf(current);
+        if (index >= 0)
+            this.spans[index] = next;
+        this.setNativeAttributes(native, {
+            ...(outcome?.outcome === undefined ? {} : { outcome: outcome.outcome }),
+            ...(outcome?.httpStatus === undefined ? {} : { "http.status": outcome.httpStatus }),
+        });
+        return next;
+    }
+    recordEmittedWorkerRow(row, native) {
+        // `enterNativeSpan` calls this callback only after the platform has
+        // accepted the child callback. A declined/untraced span remains absent
+        // from the inventory so the exporter can distinguish local emission from
+        // a later provider-ingestion loss. DO and provider-subrequest rows are
+        // intentionally outside this Worker-local inventory.
+        if (native === undefined || native.isTraced === false || !isWorkerLocalEmitter(row))
+            return;
+        this.emittedWorkerRows.add(row.rowId);
+    }
+    attributesFor(row, options) {
+        const attributes = {
+            "schema.version": this.options.schema,
+            "correlation.id": this.correlationId,
+            "service.id": this.options.serviceId,
+            "actor.class": options.actorClass,
+            operation: row.span,
+            "span.kind": row.kind,
+            outcome: options.outcome ?? "in-progress",
+        };
+        if (options.actorKey !== undefined)
+            attributes["actor.key_hash"] = stableTraceHash(options.actorKey);
+        if (options.attemptId !== undefined)
+            attributes["attempt.id"] = options.attemptId;
+        if (options.phaseOrdinal !== undefined)
+            attributes["phase.ordinal"] = options.phaseOrdinal;
+        if (options.retryIndex !== undefined)
+            attributes["retry.index"] = options.retryIndex;
+        if (options.memberIndex !== undefined)
+            attributes["member.index"] = options.memberIndex;
+        if (options.tag !== undefined)
+            attributes["tag.key_hash"] = stableTraceHash(options.tag);
+        if (options.httpStatus !== undefined)
+            attributes["http.status"] = options.httpStatus;
+        if (this.provider.scriptVersion !== undefined)
+            attributes["script.version"] = this.provider.scriptVersion;
+        if (this.provider.colo !== undefined)
+            attributes.colo = this.provider.colo;
+        if (this.provider.placement !== undefined)
+            attributes.placement = this.provider.placement;
+        for (const [key, value] of Object.entries(options.attributes ?? {})) {
+            attributes[key] = asTraceValue(value, key);
+        }
+        assertNoRawTagAttributes(attributes);
+        for (const [attribute, declaration] of Object.entries(manifest.attributeMatrix.attributes)) {
+            const present = hasOwn(attributes, attribute);
+            const state = rowScopedState(declaration, options.face, row.rowId);
+            if (state === "required" && !present) {
+                throw new Error(`Commit trace row ${row.rowId} is missing required ${attribute} on ${options.face}`);
+            }
+            if (state === "forbidden" && present) {
+                throw new Error(`Commit trace row ${row.rowId} must not emit ${attribute} on ${options.face}`);
+            }
+        }
+        // Every emitted schema attribute must have an authority-matrix row,
+        // except diagnostics which intentionally live out-of-band in snapshots.
+        for (const attribute of Object.keys(attributes)) {
+            faceState(attribute, options.face);
+        }
+        assertAttributeTypes(attributes);
+        return attributes;
+    }
+    setNativeAttributes(native, attributes) {
+        if (native === undefined || native.isTraced === false)
+            return;
+        for (const [key, value] of Object.entries(attributes)) {
+            try {
+                native.setAttribute(key, value);
+            }
+            catch (error) {
+                this.noteObservationFailure(error);
+            }
+        }
+    }
+    outcomeFromResult(result, explicit, fallbackHttpStatus) {
+        const response = result instanceof Response
+            ? result
+            : typeof result === "object" && result !== null && "response" in result && result.response instanceof Response
+                ? result.response
+                : undefined;
+        return {
+            outcome: explicit ?? (response === undefined ? "success" : response.ok ? "success" : `http-${response.status}`),
+            ...(response === undefined ? fallbackHttpStatus === undefined ? {} : { httpStatus: fallbackHttpStatus } : { httpStatus: response.status }),
+        };
+    }
+    clock() {
+        return this.options.clock ?? DEFAULT_CLOCK;
+    }
+    now() {
+        try {
+            return this.clock().now();
+        }
+        catch (error) {
+            this.noteObservationFailure(error);
+            // The timestamp is evidence-only.  Fall back to the process clock so
+            // a broken injected/provider clock cannot change the observed commit.
+            return Date.now();
+        }
+    }
+    publishSnapshot() {
+        let beforeVerification;
+        try {
+            beforeVerification = this.snapshot();
+        }
+        catch (error) {
+            this.noteObservationFailure(error);
+            return;
+        }
+        if (this.options.runtimeVerifier !== undefined) {
+            try {
+                if (this.observationFailureCode !== undefined) {
+                    this.runtimeVerification = this.observationVerification();
+                }
+                else {
+                    this.options.runtimeVerifier.verify(beforeVerification);
+                    this.runtimeVerification = Object.freeze({ passed: true });
+                }
+            }
+            catch (error) {
+                // G30 observes the existing protocol. A trace defect must be retained
+                // for the sink/evidence lane but can never turn a successful commit
+                // into a new rejection or retry.
+                const code = typeof error === "object" && error !== null && "code" in error && typeof error.code === "string"
+                    ? error.code
+                    : "runtime-verifier-error";
+                this.runtimeVerification = Object.freeze({ passed: false, code });
+            }
+        }
+        try {
+            this.options.sink?.record(this.snapshot());
+        }
+        catch (error) {
+            // Export/sink loss is recorded in-process when a later observer asks
+            // for a snapshot, but it can never replace the application result.
+            this.noteObservationFailure(error);
+        }
+    }
+    /**
+     * 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.
+     */
+    async scheduleDetachedObservation() {
+        try {
+            await this.options.scheduleDetachedObservation?.();
+        }
+        catch (error) {
+            this.noteObservationFailure(error);
+        }
+    }
+    isFailOpen() {
+        return this.options.failOpen !== false;
+    }
+    observationVerification() {
+        return Object.freeze({ passed: false, code: this.observationFailureCode ?? "trace-observation-error" });
+    }
+    noteObservationFailure(error) {
+        if (this.observationFailureCode !== undefined)
+            return;
+        this.observationFailureCode = typeof error === "object" && error !== null && "code" in error && typeof error.code === "string"
+            ? error.code
+            : "trace-observation-error";
+        this.runtimeVerification = this.observationVerification();
+    }
+    /**
+     * 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.
+     */
+    async enterNativeSpan(native, name, callback) {
+        let callbackStarted = false;
+        const wrapped = (span) => {
+            callbackStarted = true;
+            return callback(span);
+        };
+        try {
+            const result = native.enterSpan(name, wrapped);
+            if (!callbackStarted) {
+                this.noteObservationFailure(new Error("native tracer returned without invoking callback"));
+                return callback(undefined);
+            }
+            return await result;
+        }
+        catch (error) {
+            if (callbackStarted)
+                throw error;
+            this.noteObservationFailure(error);
+            return callback(undefined);
+        }
+    }
+}
+/**
+ * Constructor-only activation observation. It never touches Durable Object
+ * storage and callers must invoke beginHandler synchronously before awaiting.
+ */
+export class DurableObjectActivation {
+    activationId = crypto.randomUUID();
+    constructedAtMs = Date.now();
+    first = true;
+    beginHandler() {
+        const first = this.first;
+        this.first = false;
+        const handlerStartedAtMs = Date.now();
+        return Object.freeze({
+            activationId: this.activationId,
+            first,
+            handlerStartedAtMs,
+            constructorToHandlerMs: Math.max(0, handlerStartedAtMs - this.constructedAtMs),
+        });
+    }
+}
+// Workerd forbids random generation while evaluating a module. Keep the
+// isolate identity module-scoped once observed, but create it at the first
+// request-handler boundary rather than during Worker startup.
+let workerIsolateInstanceId;
+let workerIsolateFirstInvocation = true;
+export function beginWorkerInvocationObservation() {
+    workerIsolateInstanceId ??= crypto.randomUUID();
+    const firstInvocation = workerIsolateFirstInvocation;
+    workerIsolateFirstInvocation = false;
+    return Object.freeze({ isolateInstanceId: workerIsolateInstanceId, firstInvocation });
+}
+/**
+ * This deliberately accepts only an externally collected complete ledger.
+ * The DO runtime never records timestamps or idle observations in storage.
+ */
+export function observedIdleGapLowerBoundMs(previous, currentStartMs) {
+    if (previous === undefined || !previous.complete || !Number.isFinite(previous.endMs) || !Number.isFinite(currentStartMs))
+        return null;
+    return Math.max(0, currentStartMs - previous.endMs);
+}
+export const IDLE_EXPERIMENT_SCHEDULE_MS = Object.freeze([2_000, 15_000, 180_000]);
+export function classifyReactivationCause(evidence) {
+    if (evidence.deployedVersionChanged)
+        return "deployment-correlated";
+    if (typeof evidence.platformEvidence === "string" && evidence.platformEvidence.length > 0)
+        return "platform-evidenced";
+    return "unknown";
+}
+function assertNativeFaceAttributes(schema, face, rowId, attributes, options = {}) {
+    const row = rowFor(schema, rowId);
+    if (attributes.operation !== row.span) {
+        throw new Error(`Native commit trace row ${rowId} operation must equal ${row.span}`);
+    }
+    if (attributes["span.kind"] !== row.kind) {
+        throw new Error(`Native commit trace row ${rowId} span.kind must equal ${row.kind}`);
+    }
+    assertNoRawTagAttributes(attributes);
+    for (const [attribute, declaration] of Object.entries(manifest.attributeMatrix.attributes)) {
+        const present = hasOwn(attributes, attribute);
+        const state = rowScopedState(declaration, face, rowId);
+        if (state === "required" && !present && !(options.allowDeferredFactDerived === true && declaration.factDerived === true)) {
+            throw new Error(`Native commit trace row ${rowId} is missing required ${attribute} on ${face}`);
+        }
+        if (state === "forbidden" && present) {
+            throw new Error(`Native commit trace row ${rowId} must not emit ${attribute} on ${face}`);
+        }
+    }
+    for (const attribute of Object.keys(attributes)) {
+        faceState(attribute, face);
+    }
+    assertAttributeTypes(attributes);
+}
+function nativeAttributesAreValid(schema, face, rowId, attributes, options = {}) {
+    try {
+        assertNativeFaceAttributes(schema, face, rowId, attributes, options);
+        return true;
+    }
+    catch {
+        // The static manifest and mutation lanes make this observable.  At a
+        // production callback boundary it must remain telemetry loss, never a
+        // new application rejection or alarm retry.
+        return false;
+    }
+}
+function nativeTracingEnabled(span) {
+    return span !== undefined && span.isTraced !== false;
+}
+function setNativeAttribute(span, key, value) {
+    if (!nativeTracingEnabled(span))
+        return;
+    try {
+        span.setAttribute(key, value);
+    }
+    catch {
+        // Span export is explicitly non-semantic.
+    }
+}
+function setNativeAttributes(span, attributes) {
+    for (const [key, value] of Object.entries(attributes))
+        setNativeAttribute(span, key, value);
+}
+/**
+ * `sdt.row.id` is an exporter-facing native-span discriminator, not a
+ * commit-snapshot attribute. Keep it outside the frozen authority matrix so
+ * it cannot alter validation, reservation, fence, response, or the in-memory
+ * evidence contract; add it only after that matrix has accepted the normal
+ * attributes for a real sdt.commit/v1 S-row.
+ */
+function nativeAttributesWithRowId(schema, rowId, attributes) {
+    if (schema !== "sdt.commit/v1" || !/^S\d/.test(rowId))
+        return { ...attributes };
+    return { ...attributes, [NATIVE_ROW_ID_ATTRIBUTE]: rowId };
+}
+/**
+ * A tracer that fails before callback invocation simply loses this span.  A
+ * callback that did begin is never run a second time: its normal result or
+ * error remains the protocol authority.
+ */
+async function enterNativeSpanFailOpen(nativeTracing, name, callback) {
+    let callbackStarted = false;
+    const wrapped = (span) => {
+        callbackStarted = true;
+        return callback(span);
+    };
+    try {
+        const result = nativeTracing.enterSpan(name, wrapped);
+        if (!callbackStarted)
+            return callback(undefined);
+        return await result;
+    }
+    catch (error) {
+        if (callbackStarted)
+            throw error;
+        return callback(undefined);
+    }
+}
+/**
+ * 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 async function enterNativeCommitSpan(nativeTracing, name, input, callback) {
+    const attributes = {
+        "schema.version": input.schema,
+        "correlation.id": input.correlationId,
+        "service.id": input.serviceId,
+        "actor.class": input.actorClass,
+        "actor.key_hash": stableTraceHash(input.actorKey),
+        "activation.id": input.activation.activationId,
+        "activation.first": input.activation.first,
+        operation: input.operation,
+        "span.kind": input.kind,
+        outcome: "in-progress",
+        ...(input.attributes ?? {}),
+    };
+    if (input.attemptId !== undefined)
+        attributes["attempt.id"] = input.attemptId;
+    if (!nativeAttributesAreValid(input.schema, input.face, input.rowId, attributes)) {
+        return callback();
+    }
+    return enterNativeSpanFailOpen(nativeTracing, name, async (span) => {
+        setNativeAttributes(span, nativeAttributesWithRowId(input.schema, input.rowId, attributes));
+        try {
+            const result = await callback();
+            const response = result instanceof Response
+                ? result
+                : typeof result === "object" && result !== null && "response" in result && result.response instanceof Response
+                    ? result.response
+                    : undefined;
+            if (nativeTracingEnabled(span)) {
+                setNativeAttribute(span, "outcome", response === undefined ? "success" : response.ok ? "success" : `http-${response.status}`);
+                // Alarm-root rows have no HTTP response surface, and the manifest
+                // forbids http.status for that face even when a test harness happens
+                // to represent an internal result as Response.
+                if (response !== undefined && input.face !== "reconcile-root")
+                    setNativeAttribute(span, "http.status", response.status);
+            }
+            return result;
+        }
+        catch (error) {
+            setNativeAttribute(span, "outcome", "exception");
+            throw error;
+        }
+    });
+}
+/**
+ * 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 async function enterNativeActorHandleSpan(nativeTracing, input, resolveIdentity, callback) {
+    return enterNativeSpanFailOpen(nativeTracing, "actor.handle", async (span) => {
+        let identity;
+        try {
+            identity = await resolveIdentity();
+        }
+        catch {
+            // Observation is deliberately fail-open. Parsing a cloned body must
+            // never turn an internal actor request into a new rejection.
+            identity = undefined;
+        }
+        if (identity !== undefined) {
+            input.observation?.bindCorrelation(correlationIdForAttempt(identity.attemptId));
+            const attributes = {
+                "schema.version": "sdt.commit/v1",
+                "correlation.id": correlationIdForAttempt(identity.attemptId),
+                "attempt.id": identity.attemptId,
+                "service.id": identity.serviceId,
+                "actor.class": input.actorClass,
+                "actor.key_hash": stableTraceHash(identity.actorKey ?? input.actorKey),
+                "activation.id": input.activation.activationId,
+                "activation.first": input.activation.first,
+                operation: "actor.handle",
+                "span.kind": "callee",
+                outcome: "in-progress",
+            };
+            if (nativeAttributesAreValid("sdt.commit/v1", "accepted", "S16", attributes)) {
+                setNativeAttributes(span, nativeAttributesWithRowId("sdt.commit/v1", "S16", attributes));
+            }
+        }
+        try {
+            const result = await callback();
+            if (identity !== undefined && nativeTracingEnabled(span)) {
+                const response = result instanceof Response
+                    ? result
+                    : typeof result === "object" && result !== null && "response" in result && result.response instanceof Response
+                        ? result.response
+                        : undefined;
+                setNativeAttribute(span, "outcome", response === undefined ? "success" : response.ok ? "success" : `http-${response.status}`);
+                if (response !== undefined)
+                    setNativeAttribute(span, "http.status", response.status);
+            }
+            return result;
+        }
+        catch (error) {
+            if (identity !== undefined)
+                setNativeAttribute(span, "outcome", "exception");
+            throw error;
+        }
+        finally {
+            // The structured log is emitted while the actor span is still active.
+            // Its existing attempt correlation is bound above; no header or request
+            // shape is added merely to label observation telemetry.
+            input.observation?.finish();
+        }
+    });
+}
+/**
+ * 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 async function enterNativeReconcileRootSpan(nativeTracing, resolveIdentity, callback) {
+    return enterNativeSpanFailOpen(nativeTracing, "sdt.commit.reconcile", async (span) => {
+        let identity;
+        let attributes;
+        let recoveryKind;
+        const facts = {
+            setRecoveryKind: (kind) => {
+                recoveryKind = kind;
+            },
+        };
+        try {
+            identity = await resolveIdentity();
+        }
+        catch {
+            // A missing/corrupt Journal record cannot be turned into a different
+            // alarm outcome by attribution. The handler preserves its normal
+            // fail-closed path while this non-commit invocation remains unlabelled.
+            identity = undefined;
+        }
+        if (identity !== undefined) {
+            attributes = {
+                "schema.version": "sdt.commit.reconcile/v1",
+                "correlation.id": correlationIdForAttempt(identity.attemptId),
+                "attempt.id": identity.attemptId,
+                "service.id": identity.serviceId,
+                "actor.class": "JOURNAL",
+                "actor.key_hash": stableTraceHash(identity.actorKey),
+                "activation.id": identity.activation.activationId,
+                "activation.first": identity.activation.first,
+                operation: "sdt.commit.reconcile",
+                "span.kind": "root",
+                outcome: "in-progress",
+                "alarm.event.id": identity.alarmEventId,
+                "alarm.invocation.id": identity.invocationId,
+                "alarm.retryCount": identity.retryCount,
+                "alarm.isRetry": identity.isRetry,
+                "durable.prefix.at_entry": identity.prefixAtEntry,
+            };
+            // recovery.kind is the one fact-derived R00 attribute. It is checked
+            // after the recovery callback establishes the durable branch.
+            if (nativeAttributesAreValid("sdt.commit.reconcile/v1", "reconcile-root", "R00", attributes, { allowDeferredFactDerived: true })) {
+                setNativeAttributes(span, attributes);
+            }
+        }
+        const finish = (outcome) => {
+            if (identity === undefined || attributes === undefined || !nativeTracingEnabled(span))
+                return;
+            if (recoveryKind === undefined) {
+                // Trace-only behavior: an incomplete observation cannot alter the
+                // alarm result. The export verifier retains the missing required fact.
+                setNativeAttribute(span, "outcome", outcome);
+                return;
+            }
+            const completed = { ...attributes, "recovery.kind": recoveryKind, outcome };
+            if (!nativeAttributesAreValid("sdt.commit.reconcile/v1", "reconcile-root", "R00", completed))
+                return;
+            setNativeAttribute(span, "recovery.kind", recoveryKind);
+            setNativeAttribute(span, "outcome", outcome);
+        };
+        try {
+            const result = await callback(identity, facts);
+            finish("success");
+            return result;
+        }
+        catch (error) {
+            finish("exception");
+            throw error;
+        }
+    });
+}