@sekiban/dcb-runtime 0.2.0

package/dist/trace/ObservationStream.js

@@ -0,0 +1,148 @@
+/**
+ * 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 { correlationIdForAttempt, } from "./CommitTrace";
+export const OBSERVATION_SCHEMA = "sdt.observe/v1";
+const consoleSink = Object.freeze({
+    emit(event) {
+        // Workers Logs indexes object members directly.  The platform supplies
+        // the request/trace metadata; application code has no public trace-id API
+        // and must not introduce a propagation header just for attribution.
+        console.log(event);
+    },
+});
+function now() {
+    return Date.now();
+}
+function nonNegativeElapsed(startedAtMs) {
+    return Math.max(0, now() - startedAtMs);
+}
+/** A log transport failure is itself non-semantic. */
+export function emitObservation(event, sink = consoleSink) {
+    try {
+        sink.emit(event);
+    }
+    catch {
+        // G30 observes an existing commit; logging can never replace its result.
+    }
+}
+export function observeWorkerInvocation(input, sink) {
+    // A missing ingress identity cannot affect a commit. The B0 exporter fails
+    // closed later if an accepted request does not have this observation.
+    if (input.requestId.length === 0 || input.correlationId.length === 0)
+        return;
+    emitObservation(Object.freeze({
+        schema: OBSERVATION_SCHEMA,
+        event: "worker.invocation",
+        emittedAtMs: now(),
+        requestId: input.requestId,
+        correlationId: input.correlationId,
+        actorClass: "WORKER",
+        emittedWorkerRowIds: Object.freeze([...input.emittedWorkerRowIds]),
+        isolateInstanceId: input.isolateInstanceId,
+        activationFirst: input.firstInvocation,
+        ...(typeof input.scriptVersion === "string" && input.scriptVersion.length > 0 ? { scriptVersion: input.scriptVersion } : {}),
+        ...(typeof input.colo === "string" && input.colo.length > 0 ? { colo: input.colo } : {}),
+        storageWrites: 0,
+        usedForControl: false,
+        exposedInPublicResponse: false,
+    }), sink);
+}
+/**
+ * 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 class DurableObjectHandlerObservation {
+    actorClass;
+    activation;
+    sink;
+    firstStorageReadMs;
+    subrequestWallMs = 0;
+    observedSubrequest = false;
+    finished = false;
+    correlationId;
+    constructor(actorClass, activation, sink) {
+        this.actorClass = actorClass;
+        this.activation = activation;
+        this.sink = sink;
+    }
+    /** Call immediately before the first durable read/transaction starts. */
+    markFirstStorageRead() {
+        if (this.firstStorageReadMs !== undefined)
+            return;
+        this.firstStorageReadMs = nonNegativeElapsed(this.activation.handlerStartedAtMs);
+    }
+    /** Measures an actual awaited subrequest, never a declared duration. */
+    async subrequest(callback) {
+        const startedAtMs = now();
+        this.observedSubrequest = true;
+        try {
+            return await callback();
+        }
+        finally {
+            this.subrequestWallMs += nonNegativeElapsed(startedAtMs);
+        }
+    }
+    /**
+     * 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) {
+        if (typeof correlationId === "string" && correlationId.length > 0)
+            this.correlationId = correlationId;
+    }
+    /** Emits at most once and only after the native actor callback settles. */
+    finish() {
+        if (this.finished)
+            return;
+        this.finished = true;
+        emitObservation(Object.freeze({
+            schema: OBSERVATION_SCHEMA,
+            event: "do.handler",
+            emittedAtMs: now(),
+            ...(this.correlationId === undefined ? {} : { correlationId: this.correlationId }),
+            actorClass: this.actorClass,
+            activationId: this.activation.activationId,
+            activationFirst: this.activation.first,
+            constructorToHandlerMs: this.activation.constructorToHandlerMs,
+            firstStorageReadMs: this.firstStorageReadMs ?? null,
+            subrequestWallMs: this.observedSubrequest ? this.subrequestWallMs : null,
+            storageWrites: 0,
+            usedForControl: false,
+            exposedInPublicResponse: false,
+        }), this.sink);
+    }
+}
+export function beginDurableObjectHandlerObservation(actorClass, activation, sink) {
+    return new DurableObjectHandlerObservation(actorClass, activation, sink);
+}
+/** Test seams may record bounded fault lifecycle facts without a V1 extension. */
+export function observeFaultBarrier(input, sink) {
+    if (!Number.isFinite(input.boundedWindowMs) || input.boundedWindowMs < 0)
+        return;
+    emitObservation(Object.freeze({
+        schema: OBSERVATION_SCHEMA,
+        event: "fault.barrier",
+        emittedAtMs: now(),
+        ...(typeof input.attemptId === "string" && input.attemptId.length > 0
+            ? { correlationId: correlationIdForAttempt(input.attemptId) }
+            : {}),
+        barrierId: input.barrierId,
+        stage: input.stage,
+        boundedWindowMs: input.boundedWindowMs,
+        storageWrites: 0,
+        usedForControl: false,
+        exposedInPublicResponse: false,
+    }), sink);
+}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@sekiban/dcb-runtime",
+  "version": "0.2.0",
+  "private": false,
+  "description": "Cloudflare Durable Object and HTTP runtime for Serialized DCB V1.",
+  "license": "Elastic-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/J-Tech-Japan/sekiban-dcb-ts.git",
+    "directory": "packages/dcb-runtime"
+  },
+  "homepage": "https://github.com/J-Tech-Japan/sekiban-dcb-ts/tree/main/packages/dcb-runtime#readme",
+  "bugs": {
+    "url": "https://github.com/J-Tech-Japan/sekiban-dcb-ts/issues"
+  },
+  "keywords": [
+    "sekiban",
+    "dcb",
+    "runtime",
+    "cloudflare",
+    "durable-objects"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./cosmos": {
+      "types": "./dist/cosmos.d.ts",
+      "import": "./dist/cosmos.js"
+    },
+    "./d1": {
+      "types": "./dist/d1.d.ts",
+      "import": "./dist/d1.js"
+    },
+    "./d1-mv": {
+      "types": "./dist/d1-mv.d.ts",
+      "import": "./dist/d1-mv.js"
+    },
+    "./cloudflare": {
+      "types": "./dist/cloudflare.d.ts",
+      "import": "./dist/cloudflare.js"
+    },
+    "./mv": {
+      "types": "./dist/mv/index.d.ts",
+      "import": "./dist/mv/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@sekiban/dcb-core": "0.2.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && esbuild src/index.ts --bundle --format=esm --platform=neutral --external:postgres --external:cloudflare:workers --outfile=dist/index.js && esbuild src/cosmos.ts --bundle --format=esm --platform=neutral --external:postgres --external:cloudflare:workers --outfile=dist/cosmos.js && esbuild src/d1.ts --bundle --format=esm --platform=neutral --external:postgres --external:cloudflare:workers --outfile=dist/d1.js && esbuild src/d1-mv.ts --bundle --format=esm --platform=neutral --external:postgres --external:cloudflare:workers --outfile=dist/d1-mv.js && esbuild src/cloudflare.ts --bundle --format=esm --platform=neutral --external:cloudflare:workers --outfile=dist/cloudflare.js && esbuild src/mv/index.ts --bundle --format=esm --platform=neutral --external:postgres --external:cloudflare:workers --outfile=dist/mv/index.js",
+    "build:g42-probe": "esbuild src/g42-probe.ts --bundle --format=esm --platform=neutral --outfile=dist/g42-probe.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}