@sekiban/dcb-runtime 0.2.0

package/dist/trace/CommitTraceConsoleSink.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Retained Workers Logs projection for a successful in-process commit trace.
+ *
+ * This module deliberately projects an already-frozen CommitTraceSnapshot; it
+ * neither creates a span nor participates in the commit protocol.  Keeping
+ * the log schema separate also avoids extending the sealed sdt.commit/v1
+ * attribute matrix just to make a console payload queryable.
+ */
+import type { CommitTraceSink, CommitTraceSnapshot, CommitTraceSpan, TraceAttributeValue } from "./CommitTrace";
+export declare const COMMIT_SNAPSHOT_LOG_SCHEMA: "sdt.commit-snapshot/v1";
+export declare const COMMIT_SNAPSHOT_LOG_EVENT: "commit.snapshot";
+/** Leave a substantial margin below the 256 KiB Workers Logs record limit. */
+export declare const COMMIT_SNAPSHOT_LOG_BYTE_BUDGET: number;
+export interface CommitSnapshotLogRow {
+    readonly rowId: string;
+    readonly name: string;
+    /** Explicit log-only row identity; it does not alter native span attributes. */
+    readonly "sdt.row.id": string;
+    readonly startOffsetMs: number;
+    readonly endOffsetMs: number;
+    readonly durationMs: number;
+    readonly face: CommitTraceSpan["face"];
+    readonly clockDomain: CommitTraceSpan["clockDomain"];
+    readonly zeroDurationPlatformLimited: boolean;
+    readonly attributes: Readonly<Record<string, TraceAttributeValue>>;
+}
+export interface CommitSnapshotLogRecord {
+    readonly schema: typeof COMMIT_SNAPSHOT_LOG_SCHEMA;
+    readonly event: typeof COMMIT_SNAPSHOT_LOG_EVENT;
+    readonly snapshotSchema: "sdt.commit/v1";
+    readonly correlationId: string;
+    readonly serviceId: string;
+    /** The ingress CF-Ray when the hosting Worker knows it. */
+    readonly platformRequestId?: string;
+    readonly rootId: string;
+    readonly rootStartedAtMs: number;
+    readonly rootEndedAtMs: number;
+    readonly rows: readonly CommitSnapshotLogRow[];
+    readonly provider: CommitTraceSnapshot["provider"];
+    readonly runtimeVerification?: CommitTraceSnapshot["runtimeVerification"];
+}
+export interface CommitTraceConsoleSinkOptions {
+    readonly platformRequestId?: string;
+    /** Test seam; production defaults to the structured Workers Logs transport. */
+    readonly log?: (record: CommitSnapshotLogRecord) => void;
+    /** A bounded receipt if the deterministic guard refuses an oversized log. */
+    readonly reportRejectedSize?: (receipt: Readonly<{
+        schema: typeof COMMIT_SNAPSHOT_LOG_SCHEMA;
+        event: "commit.snapshot-size-rejected";
+        serviceId: string;
+        correlationId: string;
+        encodedBytes: number;
+        byteBudget: number;
+    }>) => void;
+}
+/**
+ * Returns the one retained-log record for a successful V1 commit. Rejected,
+ * no-op, partial, and failed paths deliberately produce no snapshot log.
+ */
+export declare function commitSnapshotLogRecord(snapshot: CommitTraceSnapshot, options?: Pick<CommitTraceConsoleSinkOptions, "platformRequestId">): CommitSnapshotLogRecord | undefined;
+export declare function encodedCommitSnapshotLogBytes(record: CommitSnapshotLogRecord): number;
+export declare function assertCommitSnapshotLogSize(record: CommitSnapshotLogRecord): number;
+/**
+ * Observation-only CommitTrace sink used by Cloudflare Worker compositions.
+ * Its only side effect is one structured console record for an accepted HTTP
+ * 200 commit; failure is rethrown for CommitTrace's existing fail-open receipt.
+ */
+export declare function createCommitTraceConsoleSink(options?: CommitTraceConsoleSinkOptions): CommitTraceSink;

package/dist/trace/CommitTraceConsoleSink.js

@@ -0,0 +1,114 @@
+export const COMMIT_SNAPSHOT_LOG_SCHEMA = "sdt.commit-snapshot/v1";
+export const COMMIT_SNAPSHOT_LOG_EVENT = "commit.snapshot";
+/** Leave a substantial margin below the 256 KiB Workers Logs record limit. */
+export const COMMIT_SNAPSHOT_LOG_BYTE_BUDGET = 192 * 1024;
+function successfulRoot(snapshot) {
+    if (snapshot.schema !== "sdt.commit/v1")
+        return undefined;
+    const root = snapshot.spans.find((span) => span.rowId === "S00" && span.logicalParent === null);
+    if (root === undefined || root.face !== "accepted")
+        return undefined;
+    if (typeof root.attributes["attempt.id"] !== "string" || root.attributes["attempt.id"].length === 0)
+        return undefined;
+    return root.attributes.outcome === "success" && root.attributes["http.status"] === 200 ? root : undefined;
+}
+function nonEmpty(value) {
+    const trimmed = value?.trim();
+    return trimmed === undefined || trimmed.length === 0 ? undefined : trimmed;
+}
+function rowForLog(span, root) {
+    const startOffsetMs = span.startMs - root.startMs;
+    const endOffsetMs = span.endMs - root.startMs;
+    return Object.freeze({
+        rowId: span.rowId,
+        name: span.span,
+        "sdt.row.id": span.rowId,
+        startOffsetMs,
+        endOffsetMs,
+        durationMs: Math.max(0, span.endMs - span.startMs),
+        face: span.face,
+        clockDomain: span.clockDomain,
+        zeroDurationPlatformLimited: span.zeroDurationPlatformLimited,
+        attributes: Object.freeze({ ...span.attributes }),
+    });
+}
+/**
+ * Returns the one retained-log record for a successful V1 commit. Rejected,
+ * no-op, partial, and failed paths deliberately produce no snapshot log.
+ */
+export function commitSnapshotLogRecord(snapshot, options = {}) {
+    const root = successfulRoot(snapshot);
+    if (root === undefined)
+        return undefined;
+    return Object.freeze({
+        schema: COMMIT_SNAPSHOT_LOG_SCHEMA,
+        event: COMMIT_SNAPSHOT_LOG_EVENT,
+        snapshotSchema: "sdt.commit/v1",
+        correlationId: snapshot.correlationId,
+        serviceId: snapshot.serviceId,
+        ...(nonEmpty(options.platformRequestId) === undefined ? {} : { platformRequestId: nonEmpty(options.platformRequestId) }),
+        rootId: snapshot.rootId,
+        rootStartedAtMs: root.startMs,
+        rootEndedAtMs: root.endMs,
+        rows: Object.freeze(snapshot.spans.map((span) => rowForLog(span, root))),
+        provider: Object.freeze({ ...snapshot.provider }),
+        ...(snapshot.runtimeVerification === undefined ? {} : { runtimeVerification: snapshot.runtimeVerification }),
+    });
+}
+export function encodedCommitSnapshotLogBytes(record) {
+    return new TextEncoder().encode(JSON.stringify(record)).byteLength;
+}
+export function assertCommitSnapshotLogSize(record) {
+    const encodedBytes = encodedCommitSnapshotLogBytes(record);
+    if (encodedBytes > COMMIT_SNAPSHOT_LOG_BYTE_BUDGET) {
+        const error = new Error(`Commit snapshot log is ${encodedBytes} bytes; budget is ${COMMIT_SNAPSHOT_LOG_BYTE_BUDGET} bytes`);
+        error.code = "commit-snapshot-log-size";
+        error.encodedBytes = encodedBytes;
+        throw error;
+    }
+    return encodedBytes;
+}
+const workersConsoleLog = (record) => {
+    // Workers Logs indexes members of object console records directly.
+    console.log(record);
+};
+const workersConsoleRejectedSize = (receipt) => {
+    // Never silently truncate a record. This compact, bounded receipt names the
+    // observation loss while CommitTrace still returns the original response.
+    console.error(receipt);
+};
+/**
+ * Observation-only CommitTrace sink used by Cloudflare Worker compositions.
+ * Its only side effect is one structured console record for an accepted HTTP
+ * 200 commit; failure is rethrown for CommitTrace's existing fail-open receipt.
+ */
+export function createCommitTraceConsoleSink(options = {}) {
+    const log = options.log ?? workersConsoleLog;
+    const reportRejectedSize = options.reportRejectedSize ?? workersConsoleRejectedSize;
+    return Object.freeze({
+        record(snapshot) {
+            const record = commitSnapshotLogRecord(snapshot, options);
+            if (record === undefined)
+                return;
+            try {
+                assertCommitSnapshotLogSize(record);
+            }
+            catch (error) {
+                const encodedBytes = typeof error === "object" && error !== null && "encodedBytes" in error
+                    && typeof error.encodedBytes === "number"
+                    ? error.encodedBytes
+                    : encodedCommitSnapshotLogBytes(record);
+                reportRejectedSize(Object.freeze({
+                    schema: COMMIT_SNAPSHOT_LOG_SCHEMA,
+                    event: "commit.snapshot-size-rejected",
+                    serviceId: record.serviceId,
+                    correlationId: record.correlationId,
+                    encodedBytes,
+                    byteBudget: COMMIT_SNAPSHOT_LOG_BYTE_BUDGET,
+                }));
+                throw error;
+            }
+            log(record);
+        },
+    });
+}

package/dist/trace/CommitTraceVerifier.d.ts

@@ -0,0 +1,22 @@
+import { type CommitTraceSnapshot } from "./CommitTrace";
+import { type UnattributedRatio } from "./AttributionRatio";
+export { calculateUnattributedRatio } from "./AttributionRatio";
+export type { UnattributedRatio } from "./AttributionRatio";
+export declare class CommitTraceVerificationError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export interface CommitTraceVerificationOptions {
+    /** A literal v1 boundary name from the authority manifest. */
+    readonly boundary?: string;
+    /** Result of every manifest conditional predicate for this trace. */
+    readonly conditionals?: Readonly<Record<string, boolean>>;
+    /** Exact runtime cardinalities for indexed/fan-out rows. */
+    readonly cardinalities?: Readonly<Record<string, number>>;
+    /** Enforce the per-request <=5% unattributed gate. */
+    readonly accepted?: boolean;
+}
+export declare function verifyCommitTrace(snapshot: CommitTraceSnapshot, options?: CommitTraceVerificationOptions): Readonly<{
+    unattributed?: UnattributedRatio;
+    rows: number;
+}>;

package/dist/trace/CommitTraceVerifier.js

@@ -0,0 +1,295 @@
+import { traceManifest, } from "./CommitTrace";
+import { calculateUnattributedRatio } from "./AttributionRatio";
+export { calculateUnattributedRatio } from "./AttributionRatio";
+export class CommitTraceVerificationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "CommitTraceVerificationError";
+    }
+}
+const TRANSITION_PHASE = Object.freeze({
+    S05a: 0,
+    S05b: 1,
+    S05c: 2,
+    S05d: 3,
+    S05e: 4,
+});
+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;
+function failure(code, message) {
+    throw new CommitTraceVerificationError(code, message);
+}
+function schemaRows(snapshot) {
+    const schema = traceManifest().schemas[snapshot.schema];
+    if (schema === undefined || !Array.isArray(schema.rows))
+        failure("schema-missing", `manifest lacks ${snapshot.schema}`);
+    return schema.rows;
+}
+function rowMap(snapshot) {
+    return new Map(schemaRows(snapshot).map((row) => [row.rowId, row]));
+}
+function typeCheck(value, type, values, key) {
+    if (type === "enum-from-manifest-recovery") {
+        if (typeof value !== "string")
+            failure("attribute-type", `${key} must be a string`);
+        const reconcile = traceManifest().schemas["sdt.commit.reconcile/v1"];
+        const recoveryKinds = [
+            ...Object.keys(reconcile.recoveryDag ?? {}),
+            reconcile.terminalAtEntryBoundary?.name,
+        ].filter((candidate) => typeof candidate === "string");
+        if (!recoveryKinds.includes(value)) {
+            failure("attribute-enum", `${key} value ${value} is not manifest-declared`);
+        }
+        return;
+    }
+    if (type === "string" || type === "string-literal" || type === "enum" || type.startsWith("enum-") || type === "provider-adapter") {
+        if (typeof value !== "string")
+            failure("attribute-type", `${key} must be a string`);
+        if (values !== undefined && !values.includes(value))
+            failure("attribute-enum", `${key} value ${value} is not manifest-declared`);
+        return;
+    }
+    if (type === "hex64") {
+        if (typeof value !== "string" || !HEX64.test(value))
+            failure("attribute-hex64", `${key} must be lower-case 64-hex`);
+        return;
+    }
+    if (type === "uuid") {
+        if (typeof value !== "string" || !UUID.test(value))
+            failure("attribute-uuid", `${key} must be a UUID`);
+        return;
+    }
+    if (type === "boolean") {
+        if (typeof value !== "boolean")
+            failure("attribute-boolean", `${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)) {
+            failure("attribute-integer", `${key} must be ${type}`);
+        }
+        return;
+    }
+    failure("attribute-type-unknown", `manifest declares unsupported type ${type} for ${key}`);
+}
+function verifyAttributes(span, row) {
+    const matrix = traceManifest().attributeMatrix;
+    for (const [key, declaration] of Object.entries(matrix.attributes)) {
+        const state = declaration.rowScope !== undefined && !declaration.rowScope.includes(span.rowId)
+            ? "forbidden"
+            : declaration.faces[span.face];
+        const present = Object.prototype.hasOwnProperty.call(span.attributes, key);
+        if (state === "required" && !present)
+            failure("attribute-missing", `${span.rowId} lacks required ${key} on ${span.face}`);
+        if (state === "forbidden" && present)
+            failure("attribute-forbidden", `${span.rowId} emits forbidden ${key} on ${span.face}`);
+        if (present)
+            typeCheck(span.attributes[key], declaration.type, declaration.values, key);
+    }
+    for (const key of Object.keys(span.attributes)) {
+        if (!Object.prototype.hasOwnProperty.call(matrix.attributes, key)) {
+            failure("attribute-unknown", `${span.rowId} emits unknown attribute ${key}`);
+        }
+        if (key !== "tag.key_hash" && /(^|[._])tag($|[._])/i.test(key)) {
+            failure("raw-tag", `${span.rowId} emits raw tag-like attribute ${key}`);
+        }
+    }
+    if (span.attributes.operation !== row.span) {
+        failure("operation-row", `${span.rowId} operation must equal the manifest span name`);
+    }
+    if (span.attributes["span.kind"] !== row.kind) {
+        failure("kind-row", `${span.rowId} span.kind must equal the manifest row kind`);
+    }
+    const expectedPhase = TRANSITION_PHASE[span.rowId];
+    if (expectedPhase !== undefined && span.attributes["phase.ordinal"] !== expectedPhase) {
+        failure("transition-phase", `${span.rowId} must carry phase.ordinal=${expectedPhase}`);
+    }
+    // The host-owned rowScope is the authority for member attributes.  Do not
+    // duplicate a hand-maintained list here: S14 was omitted from such a list
+    // once even though it is a real v1 fan-out member.  The bundle validator
+    // proves rowScope is exactly the complete set of member rows; the runtime
+    // verifier therefore uses that same declared scope for the emitted trace.
+    const memberIndexScope = matrix.attributes["member.index"]?.rowScope ?? [];
+    if (memberIndexScope.includes(span.rowId) && span.attributes["member.index"] === undefined) {
+        failure("fanout-member-index", `${span.rowId} must carry member.index`);
+    }
+    const tagKeyHashScope = matrix.attributes["tag.key_hash"]?.rowScope ?? [];
+    if (tagKeyHashScope.includes(span.rowId) && span.attributes["tag.key_hash"] === undefined) {
+        failure("fanout-tag-hash", `${span.rowId} must carry tag.key_hash rather than a raw tag`);
+    }
+}
+function instancesByRow(spans) {
+    const entries = new Map();
+    for (const span of spans) {
+        const list = entries.get(span.rowId) ?? [];
+        list.push(span);
+        entries.set(span.rowId, list);
+    }
+    return entries;
+}
+function findBoundary(snapshot, name) {
+    const boundaries = traceManifest().schemas[snapshot.schema].boundaries;
+    const boundary = boundaries?.find((entry) => entry.name === name);
+    if (boundary === undefined)
+        failure("boundary-missing", `manifest lacks ${snapshot.schema} boundary ${name}`);
+    return boundary;
+}
+function expectedConditionalCount(conditional, enabled) {
+    const state = enabled ? conditional.whenTrue : conditional.whenFalse;
+    if (state === "forbidden")
+        return 0;
+    return typeof conditional.instanceCount === "number" ? conditional.instanceCount : 1;
+}
+function verifyBoundary(snapshot, options) {
+    if (options.boundary === undefined)
+        return;
+    const boundary = findBoundary(snapshot, options.boundary);
+    const instances = instancesByRow(snapshot.spans);
+    for (const rowId of boundary.requiredRows) {
+        if ((instances.get(rowId)?.length ?? 0) === 0)
+            failure("boundary-required", `${boundary.name} requires ${rowId}`);
+    }
+    for (const rowId of boundary.forbiddenRows) {
+        if ((instances.get(rowId)?.length ?? 0) !== 0)
+            failure("boundary-forbidden", `${boundary.name} forbids ${rowId}`);
+    }
+    for (const conditional of boundary.conditionalRows) {
+        const enabled = options.conditionals?.[conditional.rowId];
+        if (enabled === undefined)
+            failure("boundary-conditional-missing", `${boundary.name} needs predicate result for ${conditional.rowId}`);
+        const actual = instances.get(conditional.rowId)?.length ?? 0;
+        const expected = expectedConditionalCount(conditional, enabled);
+        if (actual !== expected) {
+            failure("boundary-conditional", `${boundary.name} expects ${conditional.rowId}=${expected}, observed ${actual}`);
+        }
+    }
+    for (const [rowId, expected] of Object.entries(options.cardinalities ?? {})) {
+        const actual = instances.get(rowId)?.length ?? 0;
+        if (actual !== expected)
+            failure("cardinality", `${rowId} expected ${expected}, observed ${actual}`);
+        const members = instances.get(rowId) ?? [];
+        if (members.length > 0 && members.every((span) => span.attributes["member.index"] !== undefined)) {
+            const indexes = members.map((span) => span.attributes["member.index"]).sort((left, right) => Number(left) - Number(right));
+            if (indexes.some((value, index) => value !== index))
+                failure("member-index", `${rowId} member.index is not 0..N-1`);
+        }
+    }
+}
+function verifyDeclaredCardinality(snapshot) {
+    const rows = rowMap(snapshot);
+    const instances = instancesByRow(snapshot.spans);
+    for (const [rowId, row] of rows) {
+        if (!row.successCardinality.startsWith("1"))
+            continue;
+        const count = instances.get(rowId)?.length ?? 0;
+        if (row.successCardinality.includes("per attempt")) {
+            const attempts = instances.get(rowId) ?? [];
+            const seen = new Set();
+            for (const span of attempts) {
+                const attempt = span.attributes["attempt.id"];
+                if (typeof attempt !== "string")
+                    failure("attempt-cardinality", `${rowId} needs attempt.id for its per-attempt cardinality`);
+                if (seen.has(attempt))
+                    failure("cardinality-duplicate", `${rowId} repeats attempt ${attempt}`);
+                seen.add(attempt);
+            }
+            continue;
+        }
+        // A conditional/terminal row may legitimately be absent. Repeated
+        // caller work is not a duplicate, however, when it is the manifest's
+        // explicit retry sequence. In particular S11/S12 can have a second
+        // append attempt after a failed member; collapsing it would make the
+        // partial-handoff trace lie about the actual remote work.
+        if (count > 1) {
+            const retryIndexes = instances.get(rowId)
+                .map((span) => span.attributes["retry.index"])
+                .filter((value) => typeof value === "number");
+            const distinct = [...new Set(retryIndexes)].sort((left, right) => left - right);
+            const sequential = distinct.length > 0 && distinct.every((value, index) => value === index);
+            if (retryIndexes.length !== count || !sequential) {
+                failure("cardinality-duplicate", `${rowId} has cardinality ${count} without a 0..n retry.index sequence`);
+            }
+        }
+    }
+}
+function verifyStructure(snapshot) {
+    const rows = rowMap(snapshot);
+    const byRoot = new Map();
+    for (const span of snapshot.spans) {
+        const row = rows.get(span.rowId);
+        if (row === undefined)
+            failure("row-unknown", `unknown row ${span.rowId}`);
+        if (span.schema !== snapshot.schema ||
+            span.span !== row.span ||
+            span.emitter !== row.emitter ||
+            span.logicalParent !== row.logicalParent) {
+            failure("row-shape", `row ${span.rowId} differs from the manifest authority`);
+        }
+        if (span.endMs < span.startMs)
+            failure("time-negative", `${span.rowId} ends before it starts`);
+        if (span.endMs === span.startMs && (span.zeroDurationPlatformLimited !== true || span.present !== true)) {
+            failure("zero-duration-missing", `${span.rowId} needs present=true and zeroDurationPlatformLimited=true for zero duration`);
+        }
+        verifyAttributes(span, row);
+        const list = byRoot.get(span.rootId) ?? [];
+        list.push(span);
+        byRoot.set(span.rootId, list);
+    }
+    for (const [rootId, spans] of byRoot) {
+        // S16 is a provider-linked remote-invocation universe. It is correlated
+        // through Cloudflare's active async context, not a synthetic local root.
+        if (spans.every((span) => span.logicalParent === "provider-subrequest"))
+            continue;
+        for (const child of spans) {
+            if (child.logicalParent === null || child.logicalParent === "provider-subrequest")
+                continue;
+            const parents = spans.filter((candidate) => candidate.rowId === child.logicalParent);
+            if (parents.length === 0) {
+                const otherRoot = snapshot.spans.find((candidate) => candidate.rootId !== rootId && candidate.rowId === child.logicalParent);
+                if (otherRoot !== undefined)
+                    failure("cross-root-parent", `${child.rowId} points to parent ${child.logicalParent} in another root`);
+                failure("parent-missing", `${child.rowId} lacks parent ${child.logicalParent}`);
+            }
+            const parent = parents.find((candidate) => child.startMs >= candidate.startMs && child.endMs <= candidate.endMs);
+            if (parent === undefined) {
+                const temporal = parents[0];
+                if (child.startMs < temporal.startMs || child.endMs > temporal.endMs) {
+                    failure("parent-containment", `${child.rowId} is not temporally contained by ${child.logicalParent}`);
+                }
+                failure("parent-missing", `${child.rowId} cannot resolve parent ${child.logicalParent}`);
+            }
+            if (parent.clockDomain !== child.clockDomain) {
+                failure("clock-domain-mix", `${child.rowId} mixes ${child.clockDomain} with parent ${parent.clockDomain}`);
+            }
+        }
+        const roots = spans.filter((span) => span.logicalParent === null);
+        if (roots.length !== 1)
+            failure("root-cardinality", `trace root ${rootId} has ${roots.length} roots`);
+    }
+    const repairLeases = snapshot.spans.filter((span) => span.rowId === "X02");
+    for (const item of snapshot.spans.filter((span) => span.rowId === "X03e")) {
+        const leaseId = item.attributes["repair.lease.id"];
+        const tagHash = item.attributes["tag.key_hash"];
+        if (typeof leaseId !== "string" || typeof tagHash !== "string") {
+            failure("repair-link-attributes", "X03e needs repair.lease.id and tag.key_hash");
+        }
+        if (!repairLeases.some((lease) => lease.attributes["repair.lease.id"] === leaseId && lease.attributes["tag.key_hash"] === tagHash)) {
+            failure("repair-link", "X03e must link to an X02 lease by repair.lease.id and tag.key_hash");
+        }
+    }
+}
+export function verifyCommitTrace(snapshot, options = {}) {
+    verifyStructure(snapshot);
+    verifyDeclaredCardinality(snapshot);
+    verifyBoundary(snapshot, options);
+    if (options.accepted === true) {
+        const unattributed = calculateUnattributedRatio(snapshot);
+        if (unattributed.unattributedRatio > 0.05) {
+            failure("unattributed-over-budget", `unattributed ratio ${unattributed.unattributedRatio} exceeds 0.05`);
+        }
+        return Object.freeze({ rows: snapshot.spans.length, unattributed });
+    }
+    return Object.freeze({ rows: snapshot.spans.length });
+}

package/dist/trace/ObservationStream.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Separate Workers Logs observation stream for SDT-G30.
+ *
+ * This deliberately is not a CommitTrace span and never adds an attribute to
+ * the sealed sdt.commit/v1 matrix. Structured console events carry provider
+ * request metadata but Workers Logs does not expose a trace id for them. The
+ * exporter joins existing post-admission/attempt correlation to S00 and fails
+ * closed when that chain or the client-ledger identity is absent.
+ *
+ * The stream is observation-only: it does not write Durable Object storage,
+ * decide a control branch, or contribute to a public response.
+ */
+import { type CommitTraceActorClass, type DurableObjectActivationObservation } from "./CommitTrace";
+export declare const OBSERVATION_SCHEMA: "sdt.observe/v1";
+export type ObservationActorClass = "WORKER" | Exclude<CommitTraceActorClass, "ROOT" | "REPAIR">;
+export type ObservationEvent = Readonly<{
+    schema: typeof OBSERVATION_SCHEMA;
+    event: "worker.invocation";
+    emittedAtMs: number;
+    /** Provider-owned ingress ray retained only in the observation stream. */
+    requestId: string;
+    /** Existing post-admission trace correlation; not a new wire field. */
+    correlationId: string;
+    actorClass: "WORKER";
+    /**
+     * Worker-local native span callbacks entered for this accepted request.
+     * This is an observation-only set used to classify a later missing
+     * exported row; it never supplies a completeness pass.
+     */
+    emittedWorkerRowIds: readonly string[];
+    isolateInstanceId: string;
+    activationFirst: boolean;
+    /** Overlaps S00 and is cross-checked by the exported evidence contract. */
+    scriptVersion?: string;
+    /** Overlaps S00 and is cross-checked by the exported evidence contract. */
+    colo?: string;
+    storageWrites: 0;
+    usedForControl: false;
+    exposedInPublicResponse: false;
+}> | Readonly<{
+    schema: typeof OBSERVATION_SCHEMA;
+    event: "do.handler";
+    emittedAtMs: number;
+    /** Existing attempt-derived trace correlation when actor identity exists. */
+    correlationId?: string;
+    actorClass: Exclude<ObservationActorClass, "WORKER">;
+    activationId: string;
+    activationFirst: boolean;
+    constructorToHandlerMs: number;
+    firstStorageReadMs: number | null;
+    subrequestWallMs: number | null;
+    storageWrites: 0;
+    usedForControl: false;
+    exposedInPublicResponse: false;
+}> | Readonly<{
+    schema: typeof OBSERVATION_SCHEMA;
+    event: "fault.barrier";
+    emittedAtMs: number;
+    /** Existing downstream-attempt correlation when the test seam has one. */
+    correlationId?: string;
+    barrierId: string;
+    stage: "started" | "ended" | "drained";
+    boundedWindowMs: number;
+    storageWrites: 0;
+    usedForControl: false;
+    exposedInPublicResponse: false;
+}>;
+export interface ObservationLogSink {
+    emit(event: ObservationEvent): void;
+}
+/** A log transport failure is itself non-semantic. */
+export declare function emitObservation(event: ObservationEvent, sink?: ObservationLogSink): void;
+export declare function observeWorkerInvocation(input: Readonly<{
+    isolateInstanceId: string;
+    firstInvocation: boolean;
+    requestId: string;
+    correlationId: string;
+    emittedWorkerRowIds: readonly string[];
+    scriptVersion?: string;
+    colo?: string;
+}>, sink?: ObservationLogSink): void;
+/**
+ * One handler-local stopwatch.  It is created after the constructor-derived
+ * activation fact and is passed explicitly; there is no module/global
+ * request state and no durable persistence.
+ */
+export declare class DurableObjectHandlerObservation {
+    private readonly actorClass;
+    private readonly activation;
+    private readonly sink?;
+    private firstStorageReadMs;
+    private subrequestWallMs;
+    private observedSubrequest;
+    private finished;
+    private correlationId;
+    constructor(actorClass: Exclude<ObservationActorClass, "WORKER">, activation: DurableObjectActivationObservation, sink?: ObservationLogSink | undefined);
+    /** Call immediately before the first durable read/transaction starts. */
+    markFirstStorageRead(): void;
+    /** Measures an actual awaited subrequest, never a declared duration. */
+    subrequest<T>(callback: () => Promise<T>): Promise<T>;
+    /**
+     * Actor identity is decoded from the existing body before the callback.
+     * Retaining its established trace correlation in the log avoids a new
+     * propagation header, durable write, or public response field.
+     */
+    bindCorrelation(correlationId: string | undefined): void;
+    /** Emits at most once and only after the native actor callback settles. */
+    finish(): void;
+}
+export declare function beginDurableObjectHandlerObservation(actorClass: Exclude<ObservationActorClass, "WORKER">, activation: DurableObjectActivationObservation, sink?: ObservationLogSink): DurableObjectHandlerObservation;
+/** Test seams may record bounded fault lifecycle facts without a V1 extension. */
+export declare function observeFaultBarrier(input: Readonly<{
+    barrierId: string;
+    stage: "started" | "ended" | "drained";
+    boundedWindowMs: number;
+    /** Existing downstream attempt identity available only to the test seam. */
+    attemptId?: string;
+}>, sink?: ObservationLogSink): void;