@antasphere/chassis-contract 0.0.0-stage → 1.0.0

package/src/schemas/teams.ts

@@ -0,0 +1,101 @@
+import { z } from 'zod';
+import { cursorPageQuerySchema, noControlChars, plainText, workspaceRoleSchema } from './common.js';
+
+/**
+ * Teams: named groups of the workspace's people, on BOTH editions with the
+ * same routes and screens; only the source differs (PRDCT-2813). On the
+ * self-hosted edition, and in a cloud-local workspace, owners and admins
+ * make and shape them here; in a hub-origin workspace they are the hub's
+ * projection, read here and managed on the account site (every write answers
+ * `hub_managed`). Every non-guest member reads the teams and a team's
+ * members. A team holds the workspace's MEMBERSHIPS, so it can never hold an
+ * outsider, and a person leaves every team with their membership.
+ *
+ * The shapes mirror the hub's own teams contract (its `schemas/teams.ts`), so
+ * the two Teams pages read the same; a person is named by their user id or
+ * their email, as on this tool's project routes.
+ */
+
+/** A team's slug: lowercase words joined by single dashes, unique within a workspace. */
+export const teamSlugSchema = z
+  .string()
+  .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, 'lowercase letters and digits, joined by single dashes')
+  .min(1)
+  .max(60);
+
+export const teamSchema = z.object({
+  id: z.string(),
+  slug: z.string(),
+  name: z.string(),
+  membersCount: z.number().int(),
+  /** The caller belongs to this team. */
+  isMember: z.boolean(),
+  /**
+   * The hub's team id when the team is the account site's projection (the
+   * Manage link opens it there); null for a team the tool owns.
+   */
+  hubTeamId: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string()
+});
+export type Team = z.infer<typeof teamSchema>;
+
+export const teamsListSchema = z.object({
+  teams: z.array(teamSchema),
+  nextCursor: z.string().nullable()
+});
+export type TeamsList = z.infer<typeof teamsListSchema>;
+
+export const teamsListQuerySchema = cursorPageQuerySchema;
+
+export const teamCreateSchema = z.object({
+  name: plainText(1, 80),
+  /** Absent: derived from the name (lowercased, non-alphanumerics to dashes, cut to 60). */
+  slug: teamSlugSchema.optional()
+});
+export type TeamCreate = z.infer<typeof teamCreateSchema>;
+
+export const teamUpdateSchema = z
+  .object({
+    name: plainText(1, 80).optional(),
+    slug: teamSlugSchema.optional()
+  })
+  .refine((b) => b.name !== undefined || b.slug !== undefined, { error: 'nothing to change' });
+export type TeamUpdate = z.infer<typeof teamUpdateSchema>;
+
+export const teamMemberSchema = z.object({
+  userId: z.string(),
+  email: z.string(),
+  name: z.string(),
+  /** The person's role in the WORKSPACE (a team has no roles of its own). */
+  role: workspaceRoleSchema,
+  isActive: z.boolean(),
+  addedAt: z.string()
+});
+export type TeamMemberInfo = z.infer<typeof teamMemberSchema>;
+
+export const teamMembersListSchema = z.object({
+  members: z.array(teamMemberSchema),
+  nextCursor: z.string().nullable()
+});
+export type TeamMembersList = z.infer<typeof teamMembersListSchema>;
+
+/**
+ * Seat one of the workspace's OWN active non-guest members, named by user id
+ * or by email: exactly one of the two. Nothing is invited or minted here.
+ */
+export const teamMemberAddSchema = z
+  .object({
+    userId: plainText(1, 200).optional(),
+    email: z.email().optional()
+  })
+  .refine((v) => (v.userId === undefined) !== (v.email === undefined), {
+    error: 'exactly one of userId or email is required'
+  });
+export type TeamMemberAdd = z.infer<typeof teamMemberAddSchema>;
+
+/** `{id}` the team (a uuid); `{userId}` Better Auth's text id: bounded free text, no control characters. */
+export const teamMemberParamsSchema = z.object({
+  id: z.uuid(),
+  userId: noControlChars(z.string().min(1).max(200))
+});

package/src/schemas/workspaces.ts

@@ -0,0 +1,109 @@
+import { z } from 'zod';
+import { plainText } from './common.js';
+
+/**
+ * A workspace's look: one of the dashboard's theme keys and one pattern key
+ * of the brand's library. A fact of the WORKSPACE (every member sees the
+ * same tile), kept as two short slugs the server does not interpret: the
+ * dashboard owns the catalogue and falls back to its defaults on a key it
+ * does not know, so retiring a theme never breaks a workspace. null = the
+ * dashboard's default for this workspace.
+ */
+const lookKey = z
+  .string()
+  .regex(/^[a-z][a-z0-9-]{0,31}$/, 'a short lowercase key')
+  .nullable();
+/**
+ * How much of the field's gradient reaches the page, and how much grain sits
+ * on it: 0..1, the workspace's too (they were each browser's until
+ * 2026-09-19, so two members never saw the same page). null = the brand's
+ * constant.
+ */
+const lookLevel = z.number().min(0).max(1).nullable();
+export const workspaceLookSchema = z.object({
+  theme: lookKey,
+  pattern: lookKey,
+  field: lookLevel,
+  grain: lookLevel
+});
+export type WorkspaceLook = z.infer<typeof workspaceLookSchema>;
+
+/**
+ * POST /api/v1/workspaces — a signed-in person creates ANOTHER workspace from
+ * inside the product (PRDCT-2444 self-hosted, PRDCT-2443 cloud). One route,
+ * one body, one answer on both editions; the dashboard keys off
+ * `/me.canCreateWorkspace` and never sniffs the edition.
+ *
+ *  - Self-hosted: the workspace is created locally with the caller as its
+ *    active owner, under the operator's per-person cap
+ *    (`MAX_WORKSPACES_PER_USER`).
+ *  - Cloud: the organization is created at Antasphere AS THE CALLER, then
+ *    projected locally before the answer — `workspace.id` is always the
+ *    LOCAL workspace id, the one `X-Workspace-Id` selects.
+ *
+ * Sessions only: API keys and OAuth bearers are refused (the route is
+ * deliberately absent from the machine scope allowlist). The name is trimmed
+ * server-side; a name that is blank once trimmed answers 400. The look the
+ * person picked in the dialog rides along, so the workspace is born with it
+ * on every member's screen.
+ */
+export const workspaceCreateSchema = z.object({
+  name: plainText(1, 120),
+  look: workspaceLookSchema.partial().optional()
+});
+export type WorkspaceCreate = z.infer<typeof workspaceCreateSchema>;
+
+export const workspaceCreatedSchema = z.object({
+  workspace: z.object({
+    /** The LOCAL workspace id — pass it as `X-Workspace-Id` to work in it. */
+    id: z.string(),
+    name: z.string(),
+    look: workspaceLookSchema
+  })
+});
+export type WorkspaceCreated = z.infer<typeof workspaceCreatedSchema>;
+
+/**
+ * PUT /api/v1/me/default-workspace — the workspace a request naming none
+ * resolves to, chosen by the person for themselves (PRDCT-2815). `null`
+ * clears the choice: the oldest active membership answers again. On the
+ * cloud edition the default is a setting of the person's Antasphere account,
+ * projected here at every sign-in: the route answers 403 `hub_managed` with
+ * the account site to set it on.
+ */
+export const defaultWorkspaceSetSchema = z.object({
+  workspaceId: z.string().uuid().nullable()
+});
+export type DefaultWorkspaceSet = z.infer<typeof defaultWorkspaceSetSchema>;
+
+export const defaultWorkspaceSchema = z.object({
+  /** The LOCAL id of the person's default workspace, or null when none is chosen. */
+  defaultWorkspaceId: z.string().nullable()
+});
+export type DefaultWorkspace = z.infer<typeof defaultWorkspaceSchema>;
+
+/**
+ * PATCH /api/v1/workspace — the ACTIVE workspace's own settings (its name,
+ * its look), by an owner or an admin of it, from a browser session. The
+ * route names no id: a request works in exactly one workspace (ADR 014),
+ * and that is the one it edits. On the cloud edition a hub-origin
+ * workspace's NAME is the hub's (P7): a rename answers 403 `hub_managed`
+ * with the console to do it at; its look stays a local fact and is
+ * accepted.
+ */
+export const workspaceUpdateSchema = z
+  .object({
+    name: plainText(1, 120).optional(),
+    look: workspaceLookSchema.partial().optional()
+  })
+  .refine((b) => b.name !== undefined || b.look !== undefined, { message: 'nothing to change' });
+export type WorkspaceUpdate = z.infer<typeof workspaceUpdateSchema>;
+
+export const workspaceUpdatedSchema = z.object({
+  workspace: z.object({
+    id: z.string(),
+    name: z.string(),
+    look: workspaceLookSchema
+  })
+});
+export type WorkspaceUpdated = z.infer<typeof workspaceUpdatedSchema>;

package/src/seams.ts

@@ -0,0 +1,202 @@
+/**
+ * The central-rail seam: three small interfaces wired through the boot-time
+ * module registry. The central account/credits service is NOT part of the
+ * template — these interfaces are the socket it plugs into later with zero
+ * refactor. Template defaults: LocalIdentityProvider, AllowAllEntitlements,
+ * a no-op UsageSink.
+ */
+
+/** Structural Headers so the contract stays lib-agnostic (works in DOM and Node). */
+export interface HeaderReader {
+  get(name: string): string | null;
+}
+
+export interface RequestContext {
+  /** Raw request headers (credential material lives here). */
+  headers: HeaderReader;
+  path: string;
+  method: string;
+  requestId: string;
+}
+
+/**
+ * The universal per-request workspace selector (user-scoped credential
+ * model). EVERY credential kind — session, API key, OAuth bearer — MAY send
+ * it to name which of the caller's workspaces this request targets; the
+ * resolvers verify an ACTIVE membership of that workspace and resolve to
+ * null otherwise (fail closed — no oracle about the workspace's existence).
+ * Absent, the user's DEFAULT membership is used, else the deterministic
+ * fallback (oldest active membership). The one exception is a PINNED API
+ * key (an optional least-privilege pin, and the grandfathered binding of
+ * keys minted under the old per-workspace model): it always resolves its
+ * pinned workspace, and a header naming a DIFFERENT one is rejected
+ * outright (403 workspace_mismatch).
+ */
+export const ACTIVE_WORKSPACE_HEADER = 'x-workspace-id';
+
+/**
+ * The resolved caller of ONE request. A credential identifies a USER; the
+ * Principal is still scoped to exactly ONE workspace per request (ADR 014):
+ * `workspaceId` is the workspace this request SELECTED via
+ * {@link ACTIVE_WORKSPACE_HEADER} (or the user's default), authorized
+ * against the caller's own live memberships. A user's OTHER memberships are
+ * deliberately not represented here; a request never spans workspaces.
+ */
+export interface Principal {
+  userId: string;
+  email: string;
+  name: string;
+  workspaceId: string;
+  role: 'owner' | 'admin' | 'member';
+  /**
+   * How the resolved membership came to exist (D2, internal/federation.md §P6):
+   * 'local' = ordinary membership (setup, workspace invitation), 'hub' = a
+   * hub-org projection (cloud SSO), 'guest' = an external per-resource
+   * collaborator minted by the claim path. Origin is a CAPABILITY axis, not
+   * a role: a guest resolves like any member but is refused resource creation
+   * and workspace-level surfaces (requireNonGuest) on BOTH editions — their
+   * access is the per-resource grant (ADR 013), which stays untouched. Every
+   * credential path (session, API key, OAuth bearer) reads it live from the
+   * membership row backing the request's workspace.
+   */
+  origin: 'local' | 'hub' | 'guest';
+  via: 'session' | 'api_key' | 'oauth';
+  /** Scope allowlist for machine principals; null = full role-based (session). */
+  scopes: ReadonlySet<string> | null;
+  apiKeyId?: string;
+  /** Expiry of the presented API key (ISO 8601) — absent for non-expiring keys. */
+  apiKeyExpiresAt?: string;
+  /** Central account id — undefined in local mode. */
+  accountRef?: string;
+  /**
+   * The credential itself fixed the workspace (an API key pinned to one):
+   * the request's selector was checked against the pin, and no default of
+   * the person ever moves the request elsewhere. Absent on every credential
+   * whose workspace the request selected, or the person's default chose.
+   */
+  pinned?: true;
+}
+
+/**
+ * Sign-in methods an instance can advertise in discovery. The set is OPEN
+ * (ADR 003 reserved this): clients must IGNORE entries they do not
+ * recognize, so an edition can add a method — like the cloud edition's
+ * 'antasphere' hub SSO — without breaking older SDKs/CLIs. This list is the
+ * known vocabulary, not a closed enum.
+ */
+export const KNOWN_AUTH_METHODS = [
+  'password',
+  'email-otp',
+  'google',
+  'api-key',
+  'oauth',
+  'antasphere'
+] as const;
+export type KnownAuthMethod = (typeof KNOWN_AUTH_METHODS)[number];
+
+export interface InstanceAuthDescriptor {
+  /** Open set — known values in {@link KNOWN_AUTH_METHODS}; ignore unknown entries. */
+  methods: Array<KnownAuthMethod | (string & {})>;
+  /** Self-serve password reset is available (requires a configured email driver). */
+  passwordReset: boolean;
+  /** Self-serve email change is available (requires a configured email driver). */
+  emailChange: boolean;
+  /** Opt-in per-user 2FA (TOTP + backup codes) is available on this instance. */
+  twoFactor: boolean;
+}
+
+export interface IdentityProvider {
+  /** Resolve a request to a live principal (fresh membership check) or null. */
+  resolve(ctx: RequestContext): Promise<Principal | null>;
+  /** Feeds the instance discovery endpoint. */
+  describe(): InstanceAuthDescriptor;
+}
+
+export interface MeteredAction {
+  /** The action key, e.g. 'files.upload' (the route's `meter.key`, namespaced by the tool's price book). */
+  key: string;
+  quantity: number;
+  unit: string;
+}
+
+export type EntitlementDecision = { allowed: true } | { allowed: false; reason: string };
+
+/** Per-principal general-API request quota, enforced by the server's quota middleware. */
+export interface RequestQuota {
+  /** Sustained allowance per principal per minute. 0 = unlimited (the limiter is skipped). */
+  perMinute: number;
+  /** Spike cap per principal per second inside the minute window. 0 = no burst smoothing. */
+  burstPerSecond: number;
+}
+
+export interface EntitlementService {
+  check(
+    principal: Principal,
+    action: MeteredAction,
+    ctx?: Record<string, unknown>
+  ): Promise<EntitlementDecision>;
+  /**
+   * Request-rate quota for this principal. The template default returns the
+   * instance-level env caps for everyone; a plan-aware edition varies it per
+   * account/plan. The quota is enforced per authenticated principal identity
+   * (API key id / OAuth subject / session user id), never per client header.
+   */
+  getRequestQuota(principal: Principal): Promise<RequestQuota>;
+}
+
+/**
+ * One metered action, as the tool emits it and the hub ingests it (the
+ * billing rail spec, §5 `POST /usage/events`). At-least-once from the tool;
+ * exactly-once at the hub by `id`. Paid by the account, reported per user.
+ */
+export interface UsageEvent {
+  /** ULID — the idempotency key; receivers dedupe on it (at-least-once emission). */
+  id: string;
+  /** The action key (`meter` is its historical name; the two carry the same value). */
+  meter: string;
+  actionKey: string;
+  quantity: number;
+  unit: string;
+  occurredAt: string; // ISO 8601
+  workspaceId: string;
+  /** The paying account (the workspace's central account id). */
+  accountRef?: string;
+  /** The reported user; null when the actor is a resource owner the tool could not name. */
+  userId: string | null;
+  /** How the action arrived: a session (the dashboard), an API key (the CLI), an OAuth client (an MCP connector). */
+  via: 'session' | 'api_key' | 'oauth';
+  /** The resource the handler recorded (its audit `resourceType` / `resourceId`), when it recorded one. */
+  resourceType?: string;
+  resourceId?: string;
+  source: {
+    instanceId: string;
+    edition: string;
+    version: string;
+  };
+}
+
+export interface UsageSink {
+  emit(event: UsageEvent): Promise<void>;
+}
+
+/**
+ * What a downstream says about a batch it took: the events it did NOT post
+ * because the hub would refuse them on their date (PRDCT-2644), each with
+ * its reason. The worker sends those to the held queue instead of leaving
+ * them counted as rejections at the hub; an empty list, or no outcome at
+ * all, means the whole batch was handled.
+ */
+export interface UsageBatchOutcome {
+  held: ReadonlyArray<{ id: string; reason: string }>;
+}
+
+/**
+ * Where the durable queue hands the events it drained: the no-op locally,
+ * the hub poster on cloud. A downstream that takes whole batches gets them
+ * as the worker drained them (fifty at most); one that only takes single
+ * events is called once per event. A batch downstream may answer an outcome
+ * naming the events it held back.
+ */
+export interface UsageDownstream extends UsageSink {
+  emitBatch?(events: readonly UsageEvent[]): Promise<void | UsageBatchOutcome>;
+}

package/src/wire.ts

@@ -0,0 +1,246 @@
+import { z } from 'zod';
+import {
+  BILLING_PLANS,
+  USAGE_CHECK_REASONS,
+  USAGE_EVENT_MAX_FUTURE_MS,
+  USAGE_EVENT_MAX_PAST_MS,
+  USAGE_EVENTS_BATCH_MAX,
+  USAGE_REJECT_REASONS,
+  USAGE_ROUTE_ERRORS,
+  USAGE_WRITE_SCOPE,
+  entitlementProfileSchema,
+  usageCheckRequestSchema,
+  usageCheckSchema,
+  usageEventOccurrenceIssue,
+  usageEventSchema,
+  usageEventsBatchSchema,
+  usageIngestResultSchema
+} from './entitlements.js';
+
+/**
+ * The chassis's side of the hub–tool wire check (PRDCT-2677). The hub owns
+ * the messages the tools exchange with it and publishes them as ONE
+ * generated snapshot, `packages/contract/wire/hub-tool-messages.json` of the
+ * hub, built by its `packages/contract/src/wire.ts`. The block below, from
+ * `WIRE_SCHEMA_KEYS` to `buildWireSnapshot`, is the chassis's copy of that
+ * builder, kept VERBATIM so both sides compute the same picture: the same
+ * JSON Schema export, the same probe verdicts, the same occurrence table.
+ * The hub's inputs (its offsets and probe payloads) and its definitions are
+ * NOT copied: the inputs are read back from the hub's file
+ * (`wireInputsOf`), the definitions are this package's own copies
+ * (`CHASSIS_WIRE_DEFINITIONS`, from `entitlements.ts`).
+ *
+ * `compareWireSnapshots` names every difference by its dotted path;
+ * `scripts/hub-wire-check.mjs` (`pnpm --filter @antasphere/chassis-contract
+ * wire:check`, the `hub-wire` CI job against the hub's `dev`) fails on any.
+ * The check runs one way: the hub changes first, the chassis follows.
+ */
+
+// ── Copied VERBATIM from the hub's packages/contract/src/wire.ts ──────────
+
+/** The keys of the six shapes, the same on both sides. */
+export const WIRE_SCHEMA_KEYS = [
+  'usageEvent',
+  'usageEventsBatch',
+  'usageIngestResult',
+  'usageEntitlements',
+  'usageCheckRequest',
+  'usageCheck'
+] as const;
+export type WireSchemaKey = (typeof WIRE_SCHEMA_KEYS)[number];
+
+export interface WireConstants {
+  USAGE_WRITE_SCOPE: string;
+  BILLING_PLANS: readonly string[];
+  USAGE_EVENTS_BATCH_MAX: number;
+  USAGE_EVENT_MAX_PAST_MS: number;
+  USAGE_EVENT_MAX_FUTURE_MS: number;
+  USAGE_CHECK_REASONS: readonly string[];
+  USAGE_REJECT_REASONS: readonly string[];
+  USAGE_ROUTE_ERRORS: Readonly<Record<string, number>>;
+}
+
+export interface WireProbe {
+  name: string;
+  input: unknown;
+}
+
+export interface WireProbeResult extends WireProbe {
+  /** Whether the schema accepts the input. */
+  ok: boolean;
+}
+
+export interface WireOccurrence {
+  /** The event's `occurredAt` minus the receipt time, in milliseconds. */
+  offsetMs: number;
+  issue: { path: 'occurredAt'; message: string } | null;
+}
+
+/** What one side feeds the builder: its own definitions. */
+export interface WireDefinitions {
+  constants: WireConstants;
+  schemas: Record<WireSchemaKey, z.ZodType>;
+  occurrenceIssue: (occurredAt: Date, receivedAt: Date) => { path: 'occurredAt'; message: string } | null;
+}
+
+/** The inputs the snapshot is computed on: the hub's, read back by the chassis from the hub's file. */
+export interface WireInputs {
+  occurrenceOffsetsMs: readonly number[];
+  probes: Record<WireSchemaKey, readonly WireProbe[]>;
+}
+
+export interface HubToolWireSnapshot {
+  v: 1;
+  constants: WireConstants;
+  schemas: Record<WireSchemaKey, unknown>;
+  occurrence: WireOccurrence[];
+  probes: Record<WireSchemaKey, WireProbeResult[]>;
+}
+
+/** A fixed receipt time, so the occurrence table is the same on every run. */
+const RECEIVED_AT = new Date('2026-09-23T12:00:00.000Z');
+
+/**
+ * Build the snapshot from one side's definitions on the given inputs. The
+ * SAME function runs on both sides (the chassis carries a verbatim copy):
+ * the hub with its own inputs, the chassis with the inputs read from the
+ * hub's file. Deterministic: no clock, no randomness, no environment.
+ */
+export function buildWireSnapshot(defs: WireDefinitions, inputs: WireInputs): HubToolWireSnapshot {
+  const schemas = {} as Record<WireSchemaKey, unknown>;
+  const probes = {} as Record<WireSchemaKey, WireProbeResult[]>;
+  for (const key of WIRE_SCHEMA_KEYS) {
+    const schema = defs.schemas[key];
+    // A refinement has no JSON Schema form and is dropped on both sides
+    // alike; the probes below carry what it decides.
+    schemas[key] = z.toJSONSchema(schema, { unrepresentable: 'any' });
+    probes[key] = inputs.probes[key].map((probe) => ({
+      name: probe.name,
+      input: probe.input,
+      ok: schema.safeParse(probe.input).success
+    }));
+  }
+  return {
+    v: 1,
+    constants: {
+      USAGE_WRITE_SCOPE: defs.constants.USAGE_WRITE_SCOPE,
+      BILLING_PLANS: [...defs.constants.BILLING_PLANS],
+      USAGE_EVENTS_BATCH_MAX: defs.constants.USAGE_EVENTS_BATCH_MAX,
+      USAGE_EVENT_MAX_PAST_MS: defs.constants.USAGE_EVENT_MAX_PAST_MS,
+      USAGE_EVENT_MAX_FUTURE_MS: defs.constants.USAGE_EVENT_MAX_FUTURE_MS,
+      USAGE_CHECK_REASONS: [...defs.constants.USAGE_CHECK_REASONS],
+      USAGE_REJECT_REASONS: [...defs.constants.USAGE_REJECT_REASONS],
+      USAGE_ROUTE_ERRORS: { ...defs.constants.USAGE_ROUTE_ERRORS }
+    },
+    schemas,
+    occurrence: inputs.occurrenceOffsetsMs.map((offsetMs) => ({
+      offsetMs,
+      issue: defs.occurrenceIssue(new Date(RECEIVED_AT.getTime() + offsetMs), RECEIVED_AT)
+    })),
+    probes
+  };
+}
+
+// ── The chassis's own half ─────────────────────────────────────────────────
+
+/** The chassis's definitions: this package's copies of the hub's shapes, under the hub's keys. */
+export const CHASSIS_WIRE_DEFINITIONS: WireDefinitions = {
+  constants: {
+    USAGE_WRITE_SCOPE,
+    BILLING_PLANS,
+    USAGE_EVENTS_BATCH_MAX,
+    USAGE_EVENT_MAX_PAST_MS,
+    USAGE_EVENT_MAX_FUTURE_MS,
+    USAGE_CHECK_REASONS,
+    USAGE_REJECT_REASONS,
+    USAGE_ROUTE_ERRORS
+  },
+  schemas: {
+    usageEvent: usageEventSchema,
+    usageEventsBatch: usageEventsBatchSchema,
+    usageIngestResult: usageIngestResultSchema,
+    usageEntitlements: entitlementProfileSchema,
+    usageCheckRequest: usageCheckRequestSchema,
+    usageCheck: usageCheckSchema
+  },
+  occurrenceIssue: usageEventOccurrenceIssue
+};
+
+/** The inputs the hub computed its snapshot on, read back from its file: the offsets and the probe payloads. */
+export function wireInputsOf(reference: HubToolWireSnapshot): WireInputs {
+  const probes = {} as Record<WireSchemaKey, readonly WireProbe[]>;
+  for (const key of WIRE_SCHEMA_KEYS) {
+    probes[key] = (reference.probes[key] ?? []).map((probe) => ({ name: probe.name, input: probe.input }));
+  }
+  return {
+    occurrenceOffsetsMs: reference.occurrence.map((row) => row.offsetMs),
+    probes
+  };
+}
+
+/** The snapshot the chassis's copies give on the hub's own inputs: what must equal the hub's file. */
+export function chassisWireSnapshot(reference: HubToolWireSnapshot): HubToolWireSnapshot {
+  return buildWireSnapshot(CHASSIS_WIRE_DEFINITIONS, wireInputsOf(reference));
+}
+
+/** One place where the hub's snapshot and the chassis's differ: its dotted path and the two values. */
+export interface WireDifference {
+  path: string;
+  hub: unknown;
+  chassis: unknown;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function childPath(parent: string, key: string): string {
+  return /^[A-Za-z_$][\w$]*$/.test(key)
+    ? parent === ''
+      ? key
+      : `${parent}.${key}`
+    : `${parent}[${JSON.stringify(key)}]`;
+}
+
+function compareAt(path: string, hub: unknown, chassis: unknown, out: WireDifference[]): void {
+  if (Array.isArray(hub) && Array.isArray(chassis)) {
+    if (hub.length !== chassis.length) {
+      out.push({ path, hub, chassis });
+      return;
+    }
+    for (let i = 0; i < hub.length; i += 1) compareAt(`${path}[${i}]`, hub[i], chassis[i], out);
+    return;
+  }
+  if (isPlainObject(hub) && isPlainObject(chassis)) {
+    const keys = [...new Set([...Object.keys(hub), ...Object.keys(chassis)])].sort();
+    for (const key of keys) compareAt(childPath(path, key), hub[key], chassis[key], out);
+    return;
+  }
+  if (!Object.is(hub, chassis)) out.push({ path, hub, chassis });
+}
+
+/**
+ * Every difference between the hub's snapshot and the chassis's, by dotted
+ * path (`constants.USAGE_CHECK_REASONS[2]`,
+ * `schemas.usageCheck.properties.reason.anyOf[0].enum`,
+ * `probes.usageCheck[3].ok`). Objects compare by the union of their keys,
+ * order ignored, an absent key and `undefined` being the same; arrays by
+ * index, a length difference being one difference at the array's path.
+ * Deterministic: keys sorted, arrays in order. Empty when they agree.
+ */
+export function compareWireSnapshots(
+  hub: HubToolWireSnapshot,
+  chassis: HubToolWireSnapshot
+): WireDifference[] {
+  const out: WireDifference[] = [];
+  compareAt('', hub, chassis, out);
+  return out;
+}
+
+/** One line of figures for a snapshot: `6 shapes, N constants, M probes, K occurrence offsets`. */
+export function describeWireSnapshot(snapshot: HubToolWireSnapshot): string {
+  const shapes = Object.keys(snapshot.schemas).length;
+  const constants = Object.keys(snapshot.constants).length;
+  const probes = Object.values(snapshot.probes).reduce((n, list) => n + list.length, 0);
+  return `${shapes} shapes, ${constants} constants, ${probes} probes, ${snapshot.occurrence.length} occurrence offsets`;
+}