@substrat-run/contracts 0.98.1 → 0.100.0

package/dist/signals.js

@@ -0,0 +1,91 @@
+import { z } from 'zod';
+import { connectionId } from './connections.js';
+import { scopeId, tenantId } from './ids.js';
+/**
+ * The signals dimension vocabulary (#1231) — the one set of names every
+ * observability-facing fact is stamped with, defined once so that every chart,
+ * list, graph node and failure record means the same thing by `version`, and an
+ * aggregate anywhere can click through to its exemplars with filters intact.
+ *
+ * What each dimension names, precisely:
+ *
+ * - `tenant` / `scope` — the branded directory ids, exactly as the spine stamps
+ *   them on every event.
+ * - `vertical` — the vertical's package name (`@substrat-run/demo-ticket0`),
+ *   the registry's identity for it.
+ * - `version` — the version REGISTRY id (ULID) of the vertical version the fact
+ *   was recorded under. The id, not the human version label: the label is one
+ *   `getVersion` away, while the id survives channels, previews and re-releases
+ *   of the same label. For a record written outside any deploy the stamp is the
+ *   version bound to the scope at write time — stated here because it is an
+ *   approximation everywhere the writer is not the deploy itself.
+ * - `operation` — the operation on whose behalf the work ran: a vertical's
+ *   operation name (`ticket0/answer`) for scope-side facts, the platform
+ *   operation string (`preview.create`, `intent.connector:scrive`) for
+ *   control-plane facts.
+ * - `eventType` — a DOMAIN event type (`receipt.landed`), never the Workers
+ *   invocation shape (fetch/rpc/scheduled/alarm); the observability seam names
+ *   that `invocation` so the two can never be confused in a filter.
+ * - `connection` — the connection id (ULID), not the provider slug: a tenant can
+ *   hold two connections to one provider, and the slug cannot tell them apart.
+ *
+ * `modelAttribution` (model-usage.ts) predates this vocabulary and stays its own
+ * frozen five-key shape — the smallest per-request metadata limit among model
+ * providers fixes it at five, so it is deliberately NOT widened to this schema;
+ * a signals reader reconciles it at read time.
+ */
+export const SIGNAL_DIMENSIONS = [
+    'tenant',
+    'scope',
+    'vertical',
+    'version',
+    'operation',
+    'eventType',
+    'connection',
+];
+/**
+ * A partial stamp: the dimensions one durable record carries. Every key is
+ * optional — a record states what it knows and nothing else — but `.strict()`,
+ * so an eighth dimension cannot drift in through a stamp; widening the
+ * vocabulary is an edit HERE, read in a PR diff, or nowhere.
+ */
+export const signalStamp = z
+    .object({
+    tenant: tenantId,
+    scope: scopeId,
+    vertical: z.string().min(1),
+    // Deliberately as loose as the registry's own `versionId` (`z.string().min(1)`,
+    // registry.ts): the registry owns that id's shape, and a stamp stricter than its
+    // owner could refuse an id the registry itself handed out. If the registry ever
+    // brands it, this field adopts the brand from there.
+    version: z.string().min(1),
+    operation: z.string().min(1),
+    eventType: z.string().min(1),
+    connection: connectionId,
+})
+    .partial()
+    .strict();
+/**
+ * What one deployed SERVICE (a Cloudflare script ref) means in signal dimensions —
+ * the service→(vertical, version) join, answered by the control plane's
+ * `GET /service-refs` so every consumer (dashboard, console, CLI, the signals
+ * views) gets the same answer instead of each re-deriving it (#1231's last item).
+ *
+ * `stamp.version` is the registry ULID, per this file's rule; the HUMAN label
+ * rides beside the stamp rather than inside it — `signalStamp` is `.strict()`
+ * precisely so a display concern cannot drift into the dimension vocabulary.
+ * `versionLabel` is null where the directory cannot name one (a serving ref
+ * bound to a scope whose version the registry no longer lists).
+ *
+ * `role` names which ref scheme this service is — the per-version archive
+ * script or the stable serving script — because conflating the two is the
+ * mistake that made the dashboard's per-version view read empty once already.
+ */
+export const serviceDimensions = z.object({
+    /** The deployed unit: a `deploymentRef` (archive) or a `servingRef` (serving). */
+    service: z.string().min(1),
+    role: z.enum(['archive', 'serving']),
+    stamp: signalStamp,
+    versionLabel: z.string().min(1).nullable(),
+});
+//# sourceMappingURL=signals.js.map

package/dist/signals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signals.js","sourceRoot":"","sources":["../src/signals.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,QAAQ;IACR,OAAO;IACP,UAAU;IACV,SAAS;IACT,WAAW;IACX,WAAW;IACX,YAAY;CACJ,CAAC;AAGX;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC;KACzB,MAAM,CAAC;IACN,MAAM,EAAE,QAAQ;IAChB,KAAK,EAAE,OAAO;IACd,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3B,gFAAgF;IAChF,iFAAiF;IACjF,gFAAgF;IAChF,qDAAqD;IACrD,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5B,UAAU,EAAE,YAAY;CACzB,CAAC;KACD,OAAO,EAAE;KACT,MAAM,EAAE,CAAC;AAGZ;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,kFAAkF;IAClF,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1B,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;IACpC,KAAK,EAAE,WAAW;IAClB,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;CAC3C,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@substrat-run/contracts",
-  "version": "0.98.1",
+  "version": "0.100.0",
   "description": "Substrat kernel contract schemas — Zod is the source of truth (master plan D-22); OAS/JSON Schema are emitted artifacts",
   "license": "Apache-2.0",
   "repository": {