@volter/twin-segment 0.1.0

package/src/segment-server.ts

@@ -0,0 +1,95 @@
+import { serveHttp } from '@volter/world-core';
+import { dropped, events, groups, handleSegmentTwinRequest, identities } from './segment-twin.ts';
+import { statefulTwinManifest, worldNow } from '@volter/world-core';
+
+/** Options every Segment-twin HTTP surface needs, independent of who owns the socket. */
+export interface SegmentTwinFetchOptions {
+  root?: string;
+}
+
+/** The keyless discovery door's body: a frozen VALUE, built once at module load from
+ *  constants only. Nothing here reads the clock or state, so every serve of GET /twin is
+ *  byte-identical (serve-path determinism, R9). */
+const BASE_MANIFEST = statefulTwinManifest({
+  vendor: 'segment',
+  twinOf: 'the Segment HTTP Tracking API',
+  stores: 'tracked events, identify calls, group calls and refused (dropped) messages',
+  identity: 'Authenticate as Segment does — the write key as HTTP Basic username, an OAuth bearer, or `writeKey` in the body; the twin accepts any non-sentinel credential.',
+});
+/** THE STORE DOOR's projections (R5c). The Segment HTTP Tracking API is WRITE-ONLY — every route
+ *  is an ingest and none of them reads a message back — so these four named projections are the
+ *  only way to observe what was accepted, and `dropped` is the only way to see what was
+ *  accepted-and-refused (Segment answers 200 and silently drops; this twin records the reason).
+ *  They are also what makes this pack's determinism checkable at the resource level rather than
+ *  only at the manifest door. */
+const STORES: Record<string, (root?: string) => unknown> = { events, identities, groups, dropped };
+const STORE_NAMES = Object.keys(STORES).sort();
+/** The manifest EDUCATES: it names the store door the way the kernel adapter does. */
+const MANIFEST = {
+  ...BASE_MANIFEST,
+  stores: STORE_NAMES,
+  doors: { ...(BASE_MANIFEST.doors as Record<string, unknown>), store: 'GET /twin/store/<name>' },
+};
+
+/** The twin's HTTP face. Two things it must get right, both invisible to an in-process verify:
+ *  1. THE AUTHORIZATION HEADER IS PART OF THE PAYLOAD on this vendor. Two of Segment's three
+ *     documented auth schemes live in that header (Basic with the write key as the username;
+ *     OAuth Bearer), so a fetch that dropped it would make an analytics-node v1 client — which
+ *     sends `auth: { username: writeKey }` and NO writeKey in the body — arrive anonymous.
+ *  2. An empty-body status must serve a genuinely EMPTY body: `Response.json(null)` puts the
+ *     four bytes "null" on the wire (the A3-caught serialization class in
+ *     var/line/mixpanel/REVIEW.md).
+ *
+ *  FETCH-FIRST (runtime contract R12b): this is the pack's whole HTTP surface as a plain fetch,
+ *  and `createSegmentTwinServer` is one line of `Bun.serve` around it. It is a CUSTOM fetch, not
+ *  the kernel adapter (`createTwinFetchFromHandler`): the authorization threading (1) and the
+ *  handler-throw guard (below) are this pack's own. The keyless `GET /twin` manifest door the
+ *  adapter would have provided is mounted here by hand, answering the same
+ *  `statefulTwinManifest` shape — discovery is a door every twin owes (serve-path determinism
+ *  R9 replays it), and `/twin` shadows no Segment route: the Tracking API lives under `/v1/*`. */
+export function createSegmentTwinFetch(options: SegmentTwinFetchOptions = {}): (request: Request) => Promise<Response> {
+  return async function segmentTwinFetch(request: Request): Promise<Response> {
+    try {
+      const url = new URL(request.url);
+      const cleanPath = url.pathname.replace(/\/+$/, '') || '/';
+      // The keyless discovery door, before any vendor dispatch: a pure function of the
+      // manifest VALUE — no clock, no state — so replaying it is byte-identical (R9).
+      if (request.method === 'GET' && cleanPath === '/twin') {
+        return Response.json(MANIFEST);
+      }
+      // THE STORE DOOR (R5c) — see STORES above. Read-only, deterministic, served by the same
+      // fetch the vendor paths come out of; `/twin/*` shadows no Segment route (`/v1/*`).
+      if (request.method === 'GET' && cleanPath.startsWith('/twin/store/')) {
+        const name = cleanPath.slice('/twin/store/'.length);
+        const store = STORES[name];
+        if (!store) return Response.json({ error: 'unknown store', store: name, stores: STORE_NAMES }, { status: 404 });
+        return Response.json(store(options.root));
+      }
+      const res = await handleSegmentTwinRequest({
+        method: request.method,
+        path: url.pathname + url.search,
+        body: request.method === 'GET' || request.method === 'HEAD' ? undefined : await request.text(),
+        contentType: request.headers.get('content-type') ?? undefined,
+        authorization: request.headers.get('authorization') ?? undefined,
+        // The WORLD instant (R9): `receivedAt` and every minted messageId come from the world
+        // clock, never wall time.
+        occurredAt: worldNow(),
+        root: options.root,
+      });
+      if (res.body === null || res.body === undefined) return new Response(null, { status: res.status, headers: res.headers });
+      return Response.json(res.body, { status: res.status, headers: res.headers });
+    } catch (err) {
+      // Never let a handler throw escape the fetch callback: under `bun test` that is reported as
+      // "unhandled between tests" and can stop later test registration, hiding the real defect
+      // (ADDING_A_TWIN §8). Answer the vendor's own error SHAPE.
+      return Response.json({ code: 'twin_internal_error', message: String(err) }, { status: 500 });
+    }
+  };
+}
+
+export async function createSegmentTwinServer(options: { port?: number; root?: string } = {}) {
+  return await serveHttp({
+    port: options.port ?? 0,
+    fetch: createSegmentTwinFetch(options),
+  });
+}

package/src/segment-surface.gen.ts

@@ -0,0 +1,277 @@
+// GENERATED by scripts/sdk-compile.ts from var/line/segment/SURFACE.json — the vendor
+// publishes no machine-readable spec; every op below carries the evidence it was ratified on.
+// Data only; regenerate, never hand-edit.
+
+export type TwinOp = {
+  id: string; area: string; method: string; path: string; summary: string;
+  pathParams: string[]; requiredQuery: string[]; requiredBody: string[];
+  successStatus: number; responseSkeleton: unknown; specFile: string; evidence: string; tier: string;
+};
+
+export const OPS: TwinOp[] = [
+ {
+  "id": "alias",
+  "area": "alias",
+  "method": "POST",
+  "path": "/v1/alias",
+  "summary": "associate one identity with another: a `previousId` (userId or anonymousId) is aliased onto a new `userId`",
+  "pathParams": [],
+  "requiredQuery": [],
+  "requiredBody": [],
+  "successStatus": 200,
+  "responseSkeleton": null,
+  "specFile": "SURFACE.json (sdk/docs-ratified, no vendor spec exists)",
+  "evidence": "DOCS ONLY, NOT VERIFIED OFFLINE. github.com/segmentio/segment-docs src/connections/sources/catalog/libraries/server/http-api/index.md '## Alias' declares `POST https://api.segment.io/v1/alias` with a worked body {previousId, userId, timestamp, writeKey} and a field table naming previousId. Absent from @segment/analytics-node@2's wire surface (batched as type:'alias'); the SDK's AliasParams (src/app/types/params.ts) requires both userId and previousId.",
+  "tier": "common"
+ },
+ {
+  "id": "batch",
+  "area": "batch",
+  "method": "POST",
+  "path": "/v1/batch",
+  "summary": "the SERVER-side batched ingestion envelope every official server SDK sends: {batch:[<message>...], writeKey, sentAt}, each message discriminated by its own `type`",
+  "pathParams": [],
+  "requiredQuery": [],
+  "requiredBody": [],
+  "successStatus": 200,
+  "responseSkeleton": null,
+  "specFile": "SURFACE.json (sdk/docs-ratified, no vendor spec exists)",
+  "evidence": "SDK WIRE LITERAL. @segment/analytics-node@2.3.0 src/plugins/segmentio/publisher.ts:73-76 builds the one and only URL this SDK ever posts to: tryCreateFormattedUrl(host ?? 'https://api.segment.io', path ?? '/v1/batch'); the body at :243-247 is JSON.stringify({batch: events, writeKey: this._writeKey, sentAt: new Date()}). It is the SOLE real path literal in var/line/segment/dossier/wire.json pathLiterals (the other, '/bar', is a JSDoc example). Corroborated in a second first-party SDK (analytics-python segment/analytics/request.py: url = remove_trailing_slash(host or 'https://api.segment.io') + '/v1/batch') and in the vendor's own reference, github.com/segmentio/segment-docs src/connections/sources/catalog/libraries/server/http-api/index.md '## Batch'.",
+  "tier": "core"
+ },
+ {
+  "id": "browser_track",
+  "area": "track",
+  "method": "POST",
+  "path": "/v1/t",
+  "summary": "analytics.js's short-form tracking route on the api.segment.io/v1 base — the path a browser proxy must forward",
+  "pathParams": [],
+  "requiredQuery": [],
+  "requiredBody": [],
+  "successStatus": 200,
+  "responseSkeleton": null,
+  "specFile": "SURFACE.json (sdk/docs-ratified, no vendor spec exists)",
+  "evidence": "DOCS ONLY, NOT VERIFIED OFFLINE. github.com/segmentio/segment-docs src/connections/sources/catalog/libraries/website/javascript/custom-proxy.md:123-125 documents the Analytics.js `integrations['Segment.io'].apiHost` proxy as: '// POST https://MY-CUSTOM-API-PROXY.com/v1/t --> proxies to // https://api.segment.io/v1/t'. Only the `/v1/t` short form appears on a first-party page; the sibling short routes analytics.js may use for the other call types are NOT documented anywhere in segment-docs and are deliberately not invented here. No literal in @segment/analytics-node@2 (a server SDK; this is the browser route).",
+  "tier": "niche"
+ },
+ {
+  "id": "group",
+  "area": "group",
+  "method": "POST",
+  "path": "/v1/group",
+  "summary": "associate an identified user with a group (company/account/team) and record group traits",
+  "pathParams": [],
+  "requiredQuery": [],
+  "requiredBody": [],
+  "successStatus": 200,
+  "responseSkeleton": null,
+  "specFile": "SURFACE.json (sdk/docs-ratified, no vendor spec exists)",
+  "evidence": "DOCS ONLY, NOT VERIFIED OFFLINE. github.com/segmentio/segment-docs src/connections/sources/catalog/libraries/server/http-api/index.md '## Group' declares `POST https://api.segment.io/v1/group` with a worked body {userId, groupId, traits, timestamp, writeKey} and a field table naming groupId and group traits. Absent from @segment/analytics-node@2's wire surface (batched as type:'group').",
+  "tier": "core"
+ },
+ {
+  "id": "identify",
+  "area": "identify",
+  "method": "POST",
+  "path": "/v1/identify",
+  "summary": "tie a user to their actions and record `traits` about them",
+  "pathParams": [],
+  "requiredQuery": [],
+  "requiredBody": [],
+  "successStatus": 200,
+  "responseSkeleton": null,
+  "specFile": "SURFACE.json (sdk/docs-ratified, no vendor spec exists)",
+  "evidence": "DOCS ONLY, NOT VERIFIED OFFLINE. github.com/segmentio/segment-docs src/connections/sources/catalog/libraries/server/http-api/index.md '## Identify' declares `POST https://api.segment.io/v1/identify` with a worked body {userId, traits, context, timestamp, writeKey} and a field table (anonymousId, context, integrations, timestamp, identify traits, userId); the '## Selecting Destinations' section posts an integrations-bearing identify to the same URL. Absent from @segment/analytics-node@2's wire surface (that SDK sends type:'identify' messages inside /v1/batch).",
+  "tier": "core"
+ },
+ {
+  "id": "mobile_batch",
+  "area": "batch",
+  "method": "POST",
+  "path": "/v1/b",
+  "summary": "the MOBILE batch endpoint — a distinct route from /v1/batch, which the vendor reserves for server-side sending",
+  "pathParams": [],
+  "requiredQuery": [],
+  "requiredBody": [],
+  "successStatus": 200,
+  "responseSkeleton": null,
+  "specFile": "SURFACE.json (sdk/docs-ratified, no vendor spec exists)",
+  "evidence": "DOCS ONLY, NOT VERIFIED OFFLINE. github.com/segmentio/segment-docs src/connections/sources/catalog/libraries/mobile/apple/index.md:163 and src/connections/sources/catalog/libraries/mobile/react-native/index.md:781: 'you must forward the batched events to https://api.segment.io/v1/b. The https://api.segment.io/v1/batch endpoint is reserved for events arriving from server-side sending, and proxying to that endpoint for your mobile events may result in unexpected behavior.' Also react-native/index.md:91, the `proxy` option: 'a batch url to post to instead of https://api.segment.io/v1/b'. No literal in @segment/analytics-node@2 — this is the Swift/Kotlin/React-Native route, and no mobile SDK is pinned in this dossier.",
+  "tier": "common"
+ },
+ {
+  "id": "oauth_token",
+  "area": "oauth",
+  "method": "POST",
+  "path": "/token",
+  "summary": "OAuth 2.0 client-credentials token exchange on the regional authorization server: a signed RS256 JWT client assertion is traded for a short-lived access token",
+  "pathParams": [],
+  "requiredQuery": [],
+  "requiredBody": [],
+  "successStatus": 200,
+  "responseSkeleton": null,
+  "specFile": "SURFACE.json (sdk/docs-ratified, no vendor spec exists)",
+  "evidence": "SDK WIRE LITERAL (interpolated, which is why wire.json's plain-string grep missed it). @segment/analytics-node@2.3.0 src/lib/token-manager.ts requestAccessToken(): `const accessTokenEndpoint = ${this.authServer}/token`, POSTed as application/x-www-form-urlencoded with grant_type=client_credentials & client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer & client_assertion=<signed JWT> & scope; authServer defaults to 'https://oauth2.segment.io' (same file's constructor) and the EU value 'https://oauth2.eu1.segmentapis.com' is documented on src/lib/types.ts OAuthSettings.authServer. Corroborated by github.com/segmentio/segment-docs src/connections/oauth.md '## Obtain the access token', which names both regional authorization servers and the same four form parameters.",
+  "tier": "niche"
+ },
+ {
+  "id": "page",
+  "area": "page",
+  "method": "POST",
+  "path": "/v1/page",
+  "summary": "record a web page view, with optional category, name and properties",
+  "pathParams": [],
+  "requiredQuery": [],
+  "requiredBody": [],
+  "successStatus": 200,
+  "responseSkeleton": null,
+  "specFile": "SURFACE.json (sdk/docs-ratified, no vendor spec exists)",
+  "evidence": "DOCS ONLY, NOT VERIFIED OFFLINE. github.com/segmentio/segment-docs src/connections/sources/catalog/libraries/server/http-api/index.md '## Page' declares `POST https://api.segment.io/v1/page` with a worked body {userId, name, timestamp, writeKey} and a field table (anonymousId, context, integrations, page name, page properties, timestamp, userId). Absent from @segment/analytics-node@2's wire surface (batched as type:'page').",
+  "tier": "core"
+ },
+ {
+  "id": "pixel_alias",
+  "area": "pixel",
+  "method": "GET",
+  "path": "/v1/pixel/alias",
+  "summary": "Tracking Pixel API: an alias call carried in the query string, answering 200 with a 1x1 transparent GIF",
+  "pathParams": [],
+  "requiredQuery": [],
+  "requiredBody": [],
+  "successStatus": 200,
+  "responseSkeleton": null,
+  "specFile": "SURFACE.json (sdk/docs-ratified, no vendor spec exists)",
+  "evidence": "DOCS ONLY, NOT VERIFIED OFFLINE. github.com/segmentio/segment-docs src/connections/sources/catalog/libraries/server/pixel-tracking-api/index.md '#### Pixel Routes' enumerates exactly six routes as a literal block — /v1/pixel/identify, /v1/pixel/group, /v1/pixel/alias, /v1/pixel/page, /v1/pixel/screen, /v1/pixel/track — under the signature `https://api.segment.io/v1/pixel/<METHOD ENDPOINT>?data=<base64-ENCODED-JSON>`, with 'Each endpoint *always* responds with a 200 <empty-gif>, even if an error occurs'. Not in any SDK.",
+  "tier": "niche"
+ },
+ {
+  "id": "pixel_group",
+  "area": "pixel",
+  "method": "GET",
+  "path": "/v1/pixel/group",
+  "summary": "Tracking Pixel API: a group call carried in the query string, answering 200 with a 1x1 transparent GIF",
+  "pathParams": [],
+  "requiredQuery": [],
+  "requiredBody": [],
+  "successStatus": 200,
+  "responseSkeleton": null,
+  "specFile": "SURFACE.json (sdk/docs-ratified, no vendor spec exists)",
+  "evidence": "DOCS ONLY, NOT VERIFIED OFFLINE. github.com/segmentio/segment-docs src/connections/sources/catalog/libraries/server/pixel-tracking-api/index.md '#### Pixel Routes' enumerates exactly six routes as a literal block — /v1/pixel/identify, /v1/pixel/group, /v1/pixel/alias, /v1/pixel/page, /v1/pixel/screen, /v1/pixel/track — under the signature `https://api.segment.io/v1/pixel/<METHOD ENDPOINT>?data=<base64-ENCODED-JSON>`, with 'Each endpoint *always* responds with a 200 <empty-gif>, even if an error occurs'. Not in any SDK.",
+  "tier": "niche"
+ },
+ {
+  "id": "pixel_identify",
+  "area": "pixel",
+  "method": "GET",
+  "path": "/v1/pixel/identify",
+  "summary": "Tracking Pixel API: an identify call carried in the query string, answering 200 with a 1x1 transparent GIF",
+  "pathParams": [],
+  "requiredQuery": [],
+  "requiredBody": [],
+  "successStatus": 200,
+  "responseSkeleton": null,
+  "specFile": "SURFACE.json (sdk/docs-ratified, no vendor spec exists)",
+  "evidence": "DOCS ONLY, NOT VERIFIED OFFLINE. github.com/segmentio/segment-docs src/connections/sources/catalog/libraries/server/pixel-tracking-api/index.md '#### Pixel Routes' enumerates exactly six routes as a literal block — /v1/pixel/identify, /v1/pixel/group, /v1/pixel/alias, /v1/pixel/page, /v1/pixel/screen, /v1/pixel/track — under the signature `https://api.segment.io/v1/pixel/<METHOD ENDPOINT>?data=<base64-ENCODED-JSON>`, with 'Each endpoint *always* responds with a 200 <empty-gif>, even if an error occurs'. Not in any SDK.",
+  "tier": "niche"
+ },
+ {
+  "id": "pixel_page",
+  "area": "pixel",
+  "method": "GET",
+  "path": "/v1/pixel/page",
+  "summary": "Tracking Pixel API: a page call carried in the query string, answering 200 with a 1x1 transparent GIF",
+  "pathParams": [],
+  "requiredQuery": [],
+  "requiredBody": [],
+  "successStatus": 200,
+  "responseSkeleton": null,
+  "specFile": "SURFACE.json (sdk/docs-ratified, no vendor spec exists)",
+  "evidence": "DOCS ONLY, NOT VERIFIED OFFLINE. github.com/segmentio/segment-docs src/connections/sources/catalog/libraries/server/pixel-tracking-api/index.md '#### Pixel Routes' enumerates exactly six routes as a literal block — /v1/pixel/identify, /v1/pixel/group, /v1/pixel/alias, /v1/pixel/page, /v1/pixel/screen, /v1/pixel/track — under the signature `https://api.segment.io/v1/pixel/<METHOD ENDPOINT>?data=<base64-ENCODED-JSON>`, with 'Each endpoint *always* responds with a 200 <empty-gif>, even if an error occurs'. Not in any SDK.",
+  "tier": "niche"
+ },
+ {
+  "id": "pixel_screen",
+  "area": "pixel",
+  "method": "GET",
+  "path": "/v1/pixel/screen",
+  "summary": "Tracking Pixel API: a screen call carried in the query string, answering 200 with a 1x1 transparent GIF",
+  "pathParams": [],
+  "requiredQuery": [],
+  "requiredBody": [],
+  "successStatus": 200,
+  "responseSkeleton": null,
+  "specFile": "SURFACE.json (sdk/docs-ratified, no vendor spec exists)",
+  "evidence": "DOCS ONLY, NOT VERIFIED OFFLINE. github.com/segmentio/segment-docs src/connections/sources/catalog/libraries/server/pixel-tracking-api/index.md '#### Pixel Routes' enumerates exactly six routes as a literal block — /v1/pixel/identify, /v1/pixel/group, /v1/pixel/alias, /v1/pixel/page, /v1/pixel/screen, /v1/pixel/track — under the signature `https://api.segment.io/v1/pixel/<METHOD ENDPOINT>?data=<base64-ENCODED-JSON>`, with 'Each endpoint *always* responds with a 200 <empty-gif>, even if an error occurs'. Not in any SDK.",
+  "tier": "niche"
+ },
+ {
+  "id": "pixel_track",
+  "area": "pixel",
+  "method": "GET",
+  "path": "/v1/pixel/track",
+  "summary": "Tracking Pixel API: a track call carried in the query string (base64 `?data=` or plain params), answering 200 with a 1x1 transparent GIF",
+  "pathParams": [],
+  "requiredQuery": [],
+  "requiredBody": [],
+  "successStatus": 200,
+  "responseSkeleton": null,
+  "specFile": "SURFACE.json (sdk/docs-ratified, no vendor spec exists)",
+  "evidence": "DOCS ONLY, NOT VERIFIED OFFLINE. github.com/segmentio/segment-docs src/connections/sources/catalog/libraries/server/pixel-tracking-api/index.md gives the signature `https://api.segment.io/v1/pixel/<METHOD ENDPOINT>?data=<base64-ENCODED-JSON>`, lists /v1/pixel/track among its six '#### Pixel Routes', states 'Each endpoint *always* responds with a 200 <empty-gif>, even if an error occurs', and shows both the base64 img-tag form (:67) and the unencoded query-param form (:61). Corroborated at src/connections/sources/custom-domain.md:79 and src/guides/how-to-guides/cross-channel-tracking.md:77. Not in any SDK: this route exists for email/ad contexts where JavaScript and POST are impossible.",
+  "tier": "niche"
+ },
+ {
+  "id": "screen",
+  "area": "screen",
+  "method": "POST",
+  "path": "/v1/screen",
+  "summary": "record a mobile app screen view, with optional category, name and properties",
+  "pathParams": [],
+  "requiredQuery": [],
+  "requiredBody": [],
+  "successStatus": 200,
+  "responseSkeleton": null,
+  "specFile": "SURFACE.json (sdk/docs-ratified, no vendor spec exists)",
+  "evidence": "DOCS ONLY, NOT VERIFIED OFFLINE. github.com/segmentio/segment-docs src/connections/sources/catalog/libraries/server/http-api/index.md '## Screen' declares `POST https://api.segment.io/v1/screen` with a worked body {userId, name, timestamp, writeKey}. @segment/analytics-node@2 exposes a .screen() method (src/app/analytics-node.ts) and its SegmentEventType union includes 'screen' (src/app/types/segment-event.ts), but the message still travels inside /v1/batch — no per-type path literal ships.",
+  "tier": "common"
+ },
+ {
+  "id": "track",
+  "area": "track",
+  "method": "POST",
+  "path": "/v1/track",
+  "summary": "record an action a user performed: required `event` name plus optional `properties`",
+  "pathParams": [],
+  "requiredQuery": [],
+  "requiredBody": [],
+  "successStatus": 200,
+  "responseSkeleton": null,
+  "specFile": "SURFACE.json (sdk/docs-ratified, no vendor spec exists)",
+  "evidence": "DOCS ONLY, NOT VERIFIED OFFLINE. github.com/segmentio/segment-docs src/connections/sources/catalog/libraries/server/http-api/index.md '## Track' declares `POST https://api.segment.io/v1/track` with a worked JSON body {userId, event, properties, context, timestamp, writeKey}; the same page's '### writeKey authentication' and '#### OAuth' curl examples both post to that exact URL. NO path literal for it exists in @segment/analytics-node@2 — that SDK batches every call type onto /v1/batch — so this entry is grounded in the vendor's reference page, not in shipped SDK bytes.",
+  "tier": "core"
+ }
+];
+
+export type TwinRequest = { method: string; path: string; body?: string };
+export type TwinResponse = { status: number; body: unknown; headers?: Record<string, string> };
+export type OpHandler = (ctx: { op: TwinOp; params: Record<string, string>; query: URLSearchParams; body: unknown; root?: string }) => TwinResponse | Promise<TwinResponse>;
+
+const compiled = OPS.map((op) => ({ op, re: new RegExp('^' + op.path.replace(/[.*+?^$()|[\]\\]/g, '\\$&').replace(/\{([^}]+)\}/g, '(?<$1>[^/]+)') + '$') }));
+
+/** Match one request against the ratified surface. PURE LOOKUP — dispatch belongs to the pack. */
+export function matchOp(req: TwinRequest): { op: TwinOp; params: Record<string, string>; query: URLSearchParams } | undefined {
+  const url = new URL(req.path, 'http://twin.local');
+  const match = compiled.find((c) => c.op.method === req.method.toUpperCase() && c.re.test(url.pathname));
+  if (!match) return undefined;
+  return { op: match.op, params: { ...(match.re.exec(url.pathname)?.groups ?? {}) }, query: url.searchParams };
+}
+
+/** First required query/body field missing, or undefined (empty for sdk-ratified surfaces —
+ *  validation truth lives in the pack's semantics, grounded per op). */
+export function missingRequired(op: TwinOp, query: URLSearchParams, body: unknown): string | undefined {
+  for (const q of op.requiredQuery) if (!query.has(q)) return q;
+  for (const f of op.requiredBody) if (!body || typeof body !== 'object' || (body as Record<string, unknown>)[f] === undefined) return f;
+  return undefined;
+}
+
+/** SCAFFOLD default error body — the A2 station replaces this with the vendor's REAL envelope. */
+export const errorBody = (message: string, field?: string) => ({ success: false, message, ...(field ? { field } : {}) });