@substrat-run/kernel 0.126.0 → 0.128.0

package/dist/invocation-log.js

@@ -54,6 +54,9 @@
  * verification the vertical does for its own routing happens here, with the same secret
  * and the same dev opt-out, and a failed one writes nothing at all.
  */
+// The subpath, not the root: this module is bundled into every vertical's upload (the
+// platform entry, #1893), and the root carries every schema in the vocabulary.
+import { encodeInvocationRecord, INVOCATION_RECORD_HEADER, invocationLevelOf, } from '@substrat-run/contracts/invocation-record';
 import { ulid } from './ulid.js';
 import { readRoutedNode, RouterAssertionError } from './routed-node.js';
 /**
@@ -62,27 +65,9 @@ import { readRoutedNode, RouterAssertionError } from './routed-node.js';
  * package, and a vertical's own routes may fill it in too.
  */
 export const INVOCATION_RECORD_KEY = 'substratInvocationRecord';
-/**
- * The level of an invocation, from how it ended.
- *
- * A stamped line is pure JSON, so the log platform sets no level on it (the reader's
- * comments in `cf-observability.ts` found this out the hard way). The level histogram
- * still needs one per request, so the line carries its own: a 5xx or an escaped throw is
- * an error, a 4xx is a warning (the request was refused, which the caller may need to
- * hear about, and nothing broke), a success carrying a problem code is a warning too, and
- * anything else is info.
- */
-export function invocationLevelOf(status, threw, problemCode) {
-    if (threw || status === null || status >= 500)
-        return 'error';
-    if (status >= 400)
-        return 'warn';
-    // A failure answered IN-BAND — an MCP tool error is a 200 carrying `isError` — is still
-    // a refused call, and filing it as info would hide it from the one filter that looks.
-    if (problemCode)
-        return 'warn';
-    return 'info';
-}
+// The level and its type moved to contracts in #1904 — the router files its datapoint under
+// the same level — and stay exported from here, where every caller already reads them.
+export { invocationLevelOf } from '@substrat-run/contracts/invocation-record';
 /** Distinct values, first occurrence wins — the order a reader expects to see them in. */
 function distinct(values) {
     return [...new Set(values)];
@@ -119,6 +104,86 @@ function pathOf(url) {
         return '/';
     }
 }
+/**
+ * The registry of stamps, keyed by the incoming `Request`, on `globalThis` under a GLOBAL
+ * symbol. Global rather than module state, because two copies of this code meet in one
+ * request: the platform's entry (`withInvocationLog`, prebuilt into the upload) and the
+ * kernel the vertical bundled — different module instances, one `Symbol.for`. Weak, so a
+ * finished request's stamp goes with its `Request`.
+ */
+const STAMPS = Symbol.for('substrat.invocation-stamp');
+function stamps() {
+    const g = globalThis;
+    return (g[STAMPS] ??= new WeakMap());
+}
+/**
+ * The stamp a request already carries, if a layer outside this one started it (#1893).
+ * `vertical-host` reads the record through this when the Hono context has none, which is
+ * the case when the platform's entry stamped the request and the vertical mounts nothing.
+ */
+export function invocationStampOf(request) {
+    return stamps().get(request);
+}
+function beginStamp(request) {
+    const stamp = { invocationId: ulid(), record: {} };
+    stamps().set(request, stamp);
+    return stamp;
+}
+/**
+ * Write the line for a finished request — the one place it is written, whichever layer
+ * started the stamp.
+ *
+ * No VERIFIED tenant ⇒ no line, and the three ways that happens are all silence here: no
+ * assertion at all (an un-routed call), an assertion this worker cannot verify or that is
+ * not the router's (`RouterAssertionError`), and — defensively — anything else the read
+ * throws. Writing a line for any of them would be filing one caller's request under a
+ * tenant of their choosing.
+ */
+function writeInvocationLine(stamp, done, options) {
+    // Called from a `finally`: a throw here would replace the vertical's answer, or its own
+    // error, with a logging failure. The platform wraps every uploaded script in this (#1893),
+    // so nothing in it may escape — a line that cannot be written is one missing line.
+    try {
+        writeLineOrThrow(stamp, done, options);
+    }
+    catch (e) {
+        try {
+            console.log(JSON.stringify({ substrat: 'invocation-log-fault', detail: String(e) }));
+        }
+        catch {
+            /* the console itself is gone; there is nowhere left to say so */
+        }
+    }
+}
+function writeLineOrThrow(stamp, done, options) {
+    const node = routedNodeOrNull(done.request.headers, done.env, options);
+    if (!node)
+        return;
+    const { record, invocationId } = stamp;
+    const emitted = record.emitted;
+    const line = {
+        substrat: 'invocation',
+        tenantId: node.tenantId,
+        scopeId: node.scopeId,
+        vertical: node.verticalSlug,
+        surface: node.surface,
+        method: done.request.method,
+        path: pathOf(done.request.url),
+        status: done.status,
+        threw: done.threw,
+        durationMs: Date.now() - done.started,
+        invocationId,
+        level: invocationLevelOf(done.status, done.threw, record.problemCode),
+        operation: record.operation ?? null,
+        problemCode: record.problemCode ?? null,
+        principalKind: record.principalKind ?? null,
+        eventCount: emitted ? emitted.total : null,
+        eventTypes: emitted ? distinct(emitted.events.map((e) => e.type)) : [],
+        entities: emitted ? distinct(emitted.events.map((e) => e.entity)) : [],
+        versionId: versionIdOf(done.env),
+    };
+    console.log(JSON.stringify(line));
+}
 /**
  * Mount as the FIRST middleware on a vertical's app, with the same two answers the
  * vertical gives `readRoutedNode` in its own `nodeFor`:
@@ -135,26 +200,36 @@ function pathOf(url) {
  * ```
  *
  * First, because Hono composes handlers in registration order and stops at the one that
- * returns a response — middleware registered after a route does not wrap that route. A
- * vertical that mounts this below its own routes gets a log for some of its surface and
- * silence for the rest, which is worse than none, because the silence reads as no
- * traffic. `pnpm lint:invocation-log` refuses that arrangement rather than trusting
- * anyone to remember it.
+ * returns a response — middleware registered after a route does not wrap that route.
+ *
+ * **Since #1893 the platform stamps every deployed request itself**, by wrapping the
+ * uploaded entry with `withInvocationLog`. A vertical that still mounts this middleware
+ * then finds the request already stamped and steps aside — it hands the platform's stamp
+ * to the handler chain through the context, as it always did, and writes no second line.
+ * Mounted where no platform entry runs (a dev server behind a dev router), it stamps as
+ * before.
  *
  * Nothing here can fail a request: the line is written in a `finally`, and a throw from
  * the handler is re-thrown untouched for `onError` to map as it always did.
  */
 export function invocationLog(options = {}) {
     return async (c, next) => {
+        // Stamped already by the platform's entry: pass the stamp down, write nothing.
+        const existing = invocationStampOf(c.req.raw);
+        if (existing) {
+            c.set?.('substratInvocationId', existing.invocationId);
+            c.set?.(INVOCATION_RECORD_KEY, existing.record);
+            await next();
+            return;
+        }
         // Host code, so a real clock is correct here — `ctx.now()` is the module-code rule,
         // and this middleware runs outside any operation's transaction.
         const started = Date.now();
         // Minted per request, before anything can emit. A ULID so it sorts by time like
         // every other id on the spine.
-        const invocationId = ulid();
-        c.set?.('substratInvocationId', invocationId);
-        const record = {};
-        c.set?.(INVOCATION_RECORD_KEY, record);
+        const stamp = beginStamp(c.req.raw);
+        c.set?.('substratInvocationId', stamp.invocationId);
+        c.set?.(INVOCATION_RECORD_KEY, stamp.record);
         let threw = false;
         try {
             await next();
@@ -166,41 +241,83 @@ export function invocationLog(options = {}) {
             throw e;
         }
         finally {
-            // No VERIFIED tenant ⇒ no line, and the three ways that happens are all silence
-            // here: no assertion at all (an un-routed call), an assertion this worker cannot
-            // verify or that is not the router's (`RouterAssertionError`), and — defensively —
-            // anything else the read throws. Writing a line for any of them would be filing
-            // one caller's request under a tenant of their choosing.
-            const node = routedNodeOrNull(c, options);
-            if (node) {
-                const status = threw ? null : (c.res?.status ?? null);
-                const emitted = record.emitted;
-                const line = {
-                    substrat: 'invocation',
-                    tenantId: node.tenantId,
-                    scopeId: node.scopeId,
-                    vertical: node.verticalSlug,
-                    surface: node.surface,
-                    method: c.req.method,
-                    path: pathOf(c.req.raw.url),
-                    status,
-                    threw,
-                    durationMs: Date.now() - started,
-                    invocationId,
-                    level: invocationLevelOf(status, threw, record.problemCode),
-                    operation: record.operation ?? null,
-                    problemCode: record.problemCode ?? null,
-                    principalKind: record.principalKind ?? null,
-                    eventCount: emitted ? emitted.total : null,
-                    eventTypes: emitted ? distinct(emitted.events.map((e) => e.type)) : [],
-                    entities: emitted ? distinct(emitted.events.map((e) => e.entity)) : [],
-                    versionId: versionIdOf(c.env),
-                };
-                console.log(JSON.stringify(line));
-            }
+            writeInvocationLine(stamp, { request: { method: c.req.method, url: c.req.raw.url, headers: c.req.raw.headers }, env: c.env, status: threw ? null : (c.res?.status ?? null), threw, started }, options);
         }
     };
 }
+/** The handlers a module worker may export besides `fetch`, passed through untouched. */
+const OTHER_HANDLERS = ['scheduled', 'queue', 'email', 'tail', 'trace', 'alarm', 'test'];
+/**
+ * The platform's half of the stamp (#1893): wrap a module worker's `fetch` so every request
+ * it serves is stamped, whatever framework the worker is written in and whether or not it
+ * mounts the middleware.
+ *
+ * The control plane builds this into the entry it uploads in front of every vertical's
+ * bundle (`platform-entry.generated.ts`), which is what makes the stamp the platform's
+ * rather than a line each vertical has to remember. A request the vertical's own
+ * middleware already stamped — possible only if something wrapped this one — is passed
+ * straight through. The other handlers (`scheduled`, `queue`, …) are passed through
+ * untouched, bound to the worker, since a stamp is about a routed request.
+ *
+ * Nothing here can fail a request: the line is written in a `finally`, and a throw is
+ * re-thrown untouched.
+ */
+export function withInvocationLog(worker, options = {}) {
+    // The platform wraps whatever a bundle's default export is (#1893): a class entrypoint or
+    // no default at all has no `fetch` to stamp, and is handed back untouched.
+    const inner = worker?.fetch;
+    if (typeof inner !== 'function')
+        return worker;
+    const wrapped = {
+        async fetch(request, env, ctx) {
+            if (invocationStampOf(request))
+                return inner.call(worker, request, env, ctx);
+            const started = Date.now();
+            const stamp = beginStamp(request);
+            let status = null;
+            let threw = false;
+            try {
+                const response = await inner.call(worker, request, env, ctx);
+                status = response.status;
+                handRecordToRouter(response, stamp.record, request, env, options);
+                return response;
+            }
+            catch (e) {
+                threw = true;
+                throw e;
+            }
+            finally {
+                writeInvocationLine(stamp, { request, env, status, threw, started }, options);
+            }
+        },
+    };
+    for (const name of OTHER_HANDLERS) {
+        const h = worker[name];
+        if (typeof h === 'function')
+            wrapped[name] = h.bind(worker);
+    }
+    return wrapped;
+}
+/**
+ * #1904: hand the record back to the router on the response, which meters the request with
+ * it and strips the header before the response leaves (`INVOCATION_RECORD_HEADER`).
+ *
+ * Only on a request the router vouched for: a direct caller gets no header, and the router
+ * is the only reader. Never a throw — a response whose headers are immutable (one passed
+ * straight through from a `fetch`) reached no operation and has nothing to hand back, and
+ * metering must not fail a request either way.
+ */
+function handRecordToRouter(response, record, request, env, options) {
+    try {
+        const value = encodeInvocationRecord(record);
+        if (value === null || !routedNodeOrNull(request.headers, env, options))
+            return;
+        response.headers?.set?.(INVOCATION_RECORD_HEADER, value);
+    }
+    catch {
+        /* immutable headers: see above */
+    }
+}
 /**
  * The verified node, or `null` — never a throw.
  *
@@ -210,11 +327,11 @@ export function invocationLog(options = {}) {
  * would replace the vertical's real answer with a logging failure. So the loudness is
  * swallowed HERE and only here, and the request is unaffected either way.
  */
-function routedNodeOrNull(c, options) {
+function routedNodeOrNull(headers, env, options) {
     try {
-        return readRoutedNode(c.req.raw.headers, {
-            expectedSecret: options.routerSecret?.(c.env),
-            allowUnsigned: options.allowUnsigned?.(c.env) ?? false,
+        return readRoutedNode(headers, {
+            expectedSecret: options.routerSecret?.(env),
+            allowUnsigned: options.allowUnsigned?.(env) ?? false,
         });
     }
     catch (e) {

package/dist/invocation-log.js.map

@@ -1 +1 @@
-{"version":3,"file":"invocation-log.js","sourceRoot":"","sources":["../src/invocation-log.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"invocation-log.js","sourceRoot":"","sources":["../src/invocation-log.ts"],"names":[],"mappings":"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"}

package/dist/lifecycle-flow.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Replay one entity's declared lifecycle over a scope's outbox (#1744) — the process map's
+ * data, with no new write path.
+ *
+ * A transition is a status write inside an operation body, and the kernel never recorded
+ * "entity X moved from A to B". It did record everything a replay needs: every event names
+ * its entity, and (#1243) the operation that emitted it — which is exactly what a declared
+ * edge is keyed by. So one entity's events, in order, give its state sequence, and the gaps
+ * between moves give time-in-state.
+ *
+ * ## Where a state comes from
+ *
+ * **The payload first.** A fat event usually carries the row's lifecycle field, and when it
+ * does that value is what the row actually held — no inference about what the operation
+ * meant. It is read only from events classed `pii_class = 'none'`: the field is an enum, but
+ * #1762's rule is per event, and a read that extracts from a classified payload is the kind
+ * of exception that later grows.
+ *
+ * **The declaration otherwise.** An erased, classified or field-less event still names its
+ * operation, and the operation column survives a shred. From the state the replay has the
+ * entity in, `on[operation]` is where the declaration says it went. Counted apart
+ * (`inferred`), because this half is faithful only while the code agrees with the model.
+ *
+ * The previous state decides what an event means, which is why this is a walk in order and
+ * not a GROUP BY: `ticket0/ingest-message` is merely *allowed* in `open` and an *edge* out of
+ * `resolved`, so the same operation is a move or not depending on where the entity was.
+ *
+ * ## Bounded
+ *
+ * One entity type's events, walked in `(entity_id, id)` order — the `_substrat_outbox_entity`
+ * index — in keyset pages, up to `LIFECYCLE_FLOW_EVENT_BUDGET`. Past it the answer says
+ * `complete: false`, and every count is a lower bound; it never quietly becomes a smaller
+ * answer. History BEFORE the window is replayed too, since the state an entity was in when
+ * the window opened is only known from it; events after `until` are not read at all.
+ *
+ * Same permission posture as every read in `timeline.ts`: the caller checks, this does not.
+ */
+import { type LifecycleFlowInput, type LifecycleFlowResult } from '@substrat-run/contracts';
+import type { TimelineReader } from './timeline.js';
+export declare function readLifecycleFlow(ctx: TimelineReader, input: LifecycleFlowInput): LifecycleFlowResult;
+//# sourceMappingURL=lifecycle-flow.d.ts.map

package/dist/lifecycle-flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-flow.d.ts","sourceRoot":"","sources":["../src/lifecycle-flow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,OAAO,EAGL,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACzB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AA+EpD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,cAAc,EAAE,KAAK,EAAE,kBAAkB,GAAG,mBAAmB,CAgRrG"}