@volter/twin-hubspot 0.1.0

package/src/hubspot-conformance.ts

@@ -0,0 +1,537 @@
+// HubSpot twin CONFORMANCE (dev-only; lazy-imported by the CLI, NEVER from index.ts/runtime).
+//
+// ── THIS CHECK DRIVES THE ROUTER AND ASSERTS WHAT CAME BACK ─────────────────────────────────
+// Held to docs/contributing/adding-a-twin.md §6's bar and to the two escalating false-greens two packs' §9
+// reviews found there:
+//   • two constants asserting about each other is not a check — so every expectation below is a
+//     LITERAL written here, never a value read back out of the handler's own module. The status
+//     codes are the ones @hubspot/api-client 14.0.1's GENERATED response processors accept
+//     (201 create, 200 read/update, 204 archive, 207 partial batch), transcribed from the
+//     published tarball, not from this twin;
+//   • "not the router's own miss" has teeth at the dispatch and nowhere deeper — so each probe
+//     declares the STATUS SET and a PREDICATE over the body a LIVE handler produces, and the
+//     hand-written ROUTER_SURFACE closes the third direction in BOTH directions: a served route
+//     the census does not claim is a violation, AND a census route the router no longer reaches
+//     is a violation. That second half is what makes deleting a handler branch redden the entry
+//     that NAMES it, rather than only the probe that happens to drive it.
+//
+// ROUTER_SURFACE is deliberately NOT a copy of the probe table's keys (the tautology the groq
+// build wrote and §9 rejected). It drives object types and route families the probes never
+// touch — companies, deals, tickets, the numeric `0-1` objectTypeId alias, the ticket pipeline —
+// and each is mapped back to its canonical template by `canonicalPath`, a hand-written second
+// encoding of the route shapes that the handler itself does not export.
+//
+// The field-name renames are checked as a round trip, not as a status: HubSpot's record carries
+// `id`, `createdAt` and `updatedAt`, all three of which the kernel's META set silently DROPS from
+// a stored resource, so every record probe asserts those three came BACK — a status-only check
+// sails straight past that class (mistral's dropped `type` field is the precedent).
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { handleHubspotTwinRequest, hubspotTwinSnapshot, type HubspotResponse } from './hubspot-twin.ts';
+
+export type HubspotConformanceReport = {
+  ok: boolean;
+  endpointsClaimed: number;
+  endpointsProbed: number;
+  routerRoutesChecked: number;
+  violations: string[];
+};
+
+type Probe = {
+  method: string;
+  /** A CONCRETE path (sentinels substituted at run time) whose canonical template must equal the
+   *  claimed endpoint's path — checked, not assumed. */
+  path: string;
+  body?: unknown;
+  /** The status(es) a WORKING handler answers with. */
+  status: number[];
+  /** What a working handler's body must look like. */
+  expect?: (body: unknown) => boolean;
+};
+
+const isObject = (b: unknown): b is Record<string, unknown> => !!b && typeof b === 'object' && !Array.isArray(b);
+const AT = '2026-02-01T00:00:00.000Z';
+
+// Sentinels substituted with the ids the seeded fixtures actually minted. Shaped so that no real
+// HubSpot id could collide, and so a missed substitution fails loudly rather than silently.
+const CONTACT = 'SENTINEL_CONTACT_ID';
+const CONTACT2 = 'SENTINEL_CONTACT2_ID';
+const COMPANY = 'SENTINEL_COMPANY_ID';
+const DEAL = 'SENTINEL_DEAL_ID';
+const TICKET = 'SENTINEL_TICKET_ID';
+const PIPELINE = 'SENTINEL_PIPELINE_ID';
+const STAGE_PIPELINE = 'SENTINEL_STAGE_PIPELINE';
+const STAGE = 'SENTINEL_STAGE_ID';
+
+/**
+ * Map a CONCRETE request path back to the canonical `{placeholder}` template the endpoint census
+ * names. Hand-written from the route shapes — a SECOND encoding, so a probe (or a router-census
+ * entry) that drifts onto a different route is caught rather than silently accepted.
+ */
+export function canonicalPath(path: string): string {
+  const p = path.split('?')[0]!;
+  const s = p.replace(/^\/+|\/+$/g, '').split('/');
+  if (s[0] !== 'crm') return p;
+  if (s[1] === 'v3' && s[2] === 'objects') {
+    if (s.length === 4) return '/crm/v3/objects/{objectType}';
+    if (s.length === 5 && (s[4] === 'search' || s[4] === 'merge')) return `/crm/v3/objects/{objectType}/${s[4]}`;
+    if (s.length === 6 && s[4] === 'batch') return `/crm/v3/objects/{objectType}/batch/${s[5]}`;
+    if (s.length === 5) return '/crm/v3/objects/{objectType}/{objectId}';
+  }
+  if (s[1] === 'v3' && s[2] === 'properties') {
+    if (s.length === 4) return '/crm/v3/properties/{objectType}';
+    if (s.length === 5 && s[4] === 'groups') return '/crm/v3/properties/{objectType}/groups';
+    if (s.length === 6 && s[4] === 'groups') return '/crm/v3/properties/{objectType}/groups/{groupName}';
+    if (s.length === 6 && s[4] === 'batch' && s[5] === 'create') return '/crm/v3/properties/{objectType}/batch/create';
+    if (s.length === 5) return '/crm/v3/properties/{objectType}/{propertyName}';
+  }
+  if (s[1] === 'v3' && s[2] === 'pipelines') {
+    if (s.length === 4) return '/crm/v3/pipelines/{objectType}';
+    if (s.length === 5) return '/crm/v3/pipelines/{objectType}/{pipelineId}';
+    if (s.length === 6 && s[5] === 'stages') return '/crm/v3/pipelines/{objectType}/{pipelineId}/stages';
+    if (s.length === 7 && s[5] === 'stages') return '/crm/v3/pipelines/{objectType}/{pipelineId}/stages/{stageId}';
+  }
+  if (s[1] === 'v3' && s[2] === 'owners') {
+    if (s.length === 3) return '/crm/v3/owners';
+    if (s.length === 4) return '/crm/v3/owners/{ownerId}';
+  }
+  if (s[1] === 'v4' && s[2] === 'objects' && s[4] !== undefined && s[5] === 'associations') {
+    if (s.length === 7) return '/crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}';
+    if (s.length === 9 && s[6] === 'default') return '/crm/v4/objects/{objectType}/{objectId}/associations/default/{toObjectType}/{toObjectId}';
+    if (s.length === 8) return '/crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}';
+  }
+  if (s[1] === 'v4' && s[2] === 'associations' && s[5] === 'batch' && s.length === 7) {
+    return `/crm/v4/associations/{fromObjectType}/{toObjectType}/batch/${s[6]}`;
+  }
+  return p;
+}
+
+/** A record body must carry the three field names the kernel projection reserves. */
+function isRecord(b: unknown): boolean {
+  return isObject(b)
+    && typeof b.id === 'string' && b.id !== ''
+    && isObject(b.properties)
+    && typeof b.createdAt === 'string' && b.createdAt !== ''
+    && typeof b.updatedAt === 'string' && b.updatedAt !== '';
+}
+function isCollection(b: unknown, minResults = 1): boolean {
+  return isObject(b) && Array.isArray(b.results) && b.results.length >= minResults;
+}
+function isBatch(b: unknown, minResults = 1): boolean {
+  return isObject(b) && b.status === 'COMPLETE' && Array.isArray(b.results) && b.results.length >= minResults
+    && typeof b.startedAt === 'string' && typeof b.completedAt === 'string';
+}
+const any_ = (b: unknown) => b as Record<string, any>;
+
+/** A representative request per claimed endpoint, with the outcome a LIVE handler produces. */
+const PROBES: Record<string, Probe> = {
+  // ── CRM objects ──
+  'POST /crm/v3/objects/{objectType}': {
+    method: 'POST', path: '/crm/v3/objects/contacts', body: { properties: { email: 'probe@twin.test', firstname: 'Probe' } },
+    status: [201],
+    expect: (b) => isRecord(b) && any_(b).properties.email === 'probe@twin.test' && any_(b).archived === false,
+  },
+  'GET /crm/v3/objects/{objectType}': {
+    method: 'GET', path: '/crm/v3/objects/contacts?limit=1', status: [200],
+    expect: (b) => isCollection(b) && isRecord(any_(b).results[0]),
+  },
+  'GET /crm/v3/objects/{objectType}/{objectId}': {
+    method: 'GET', path: `/crm/v3/objects/contacts/${CONTACT}`, status: [200],
+    expect: (b) => isRecord(b) && any_(b).properties.hs_object_id === any_(b).id,
+  },
+  'PATCH /crm/v3/objects/{objectType}/{objectId}': {
+    method: 'PATCH', path: `/crm/v3/objects/contacts/${CONTACT}`, body: { properties: { lastname: 'Patched' } },
+    status: [200], expect: (b) => isRecord(b) && any_(b).properties.lastname === 'Patched',
+  },
+  'DELETE /crm/v3/objects/{objectType}/{objectId}': {
+    method: 'DELETE', path: `/crm/v3/objects/contacts/${CONTACT2}`, status: [204], expect: (b) => b === null,
+  },
+  'POST /crm/v3/objects/{objectType}/search': {
+    method: 'POST', path: '/crm/v3/objects/contacts/search',
+    body: { filterGroups: [{ filters: [{ propertyName: 'email', operator: 'EQ', value: 'probe@twin.test' }] }] },
+    status: [200],
+    expect: (b) => isObject(b) && typeof b.total === 'number' && b.total >= 1 && Array.isArray(b.results) && isRecord(b.results[0]),
+  },
+  'POST /crm/v3/objects/{objectType}/merge': {
+    method: 'POST', path: '/crm/v3/objects/contacts/merge', body: { primaryObjectId: CONTACT, objectIdToMerge: 'SENTINEL_MERGE_ID' },
+    status: [200],
+    // HubSpot keeps the PRIMARY's values and fills only its blanks from the secondary: the
+    // primary's e-mail survives while the secondary's phone (which the primary lacks) arrives.
+    expect: (b) => isRecord(b) && any_(b).properties.email === 'probe@twin.test' && any_(b).properties.phone === '+15550199',
+  },
+  'POST /crm/v3/objects/{objectType}/batch/create': {
+    method: 'POST', path: '/crm/v3/objects/contacts/batch/create', body: { inputs: [{ properties: { email: 'batch1@twin.test' } }] },
+    status: [201], expect: (b) => isBatch(b) && isRecord(any_(b).results[0]),
+  },
+  'POST /crm/v3/objects/{objectType}/batch/read': {
+    method: 'POST', path: '/crm/v3/objects/contacts/batch/read', body: { properties: ['email'], inputs: [{ id: CONTACT }] },
+    status: [200, 207], expect: (b) => isBatch(b) && any_(b).results[0].properties.email === 'probe@twin.test',
+  },
+  'POST /crm/v3/objects/{objectType}/batch/update': {
+    method: 'POST', path: '/crm/v3/objects/contacts/batch/update', body: { inputs: [{ id: CONTACT, properties: { phone: '+15550100' } }] },
+    status: [200, 207], expect: (b) => isBatch(b) && any_(b).results[0].properties.phone === '+15550100',
+  },
+  'POST /crm/v3/objects/{objectType}/batch/upsert': {
+    method: 'POST', path: '/crm/v3/objects/contacts/batch/upsert', body: { inputs: [{ idProperty: 'email', id: 'upsert@twin.test', properties: { firstname: 'Ups' } }] },
+    status: [200, 207], expect: (b) => isBatch(b) && any_(b).results[0].new === true,
+  },
+  'POST /crm/v3/objects/{objectType}/batch/archive': {
+    method: 'POST', path: '/crm/v3/objects/contacts/batch/archive', body: { inputs: [{ id: 'SENTINEL_BATCH_ARCHIVE_ID' }] },
+    status: [204], expect: (b) => b === null,
+  },
+  // ── properties ──
+  'GET /crm/v3/properties/{objectType}': {
+    method: 'GET', path: '/crm/v3/properties/contacts', status: [200],
+    // HubSpot-defined contact property names — literals, so the assertion cannot drift with the
+    // handler's own seed table.
+    expect: (b) => isCollection(b, 5) && ['email', 'firstname', 'lastname', 'hs_object_id'].every((n) => any_(b).results.some((p: any) => p.name === n && p.hubspotDefined === true)),
+  },
+  'POST /crm/v3/properties/{objectType}': {
+    method: 'POST', path: '/crm/v3/properties/contacts',
+    body: { name: 'probe_custom', label: 'Probe Custom', type: 'string', fieldType: 'text', groupName: 'contactinformation' },
+    status: [201], expect: (b) => isObject(b) && b.name === 'probe_custom' && b.fieldType === 'text' && b.hubspotDefined === false,
+  },
+  'POST /crm/v3/properties/{objectType}/batch/create': {
+    method: 'POST', path: '/crm/v3/properties/contacts/batch/create',
+    body: { inputs: [{ name: 'probe_batch_a', label: 'Probe Batch A', type: 'string', fieldType: 'text', groupName: 'contactinformation', formField: true }] },
+    status: [201], expect: (b) => isBatch(b) && any_(b).results[0].name === 'probe_batch_a' && any_(b).results[0].formField === true,
+  },
+  'GET /crm/v3/properties/{objectType}/{propertyName}': {
+    method: 'GET', path: '/crm/v3/properties/contacts/email', status: [200],
+    expect: (b) => isObject(b) && b.name === 'email' && b.hubspotDefined === true && b.groupName === 'contactinformation',
+  },
+  'PATCH /crm/v3/properties/{objectType}/{propertyName}': {
+    method: 'PATCH', path: '/crm/v3/properties/contacts/email', body: { label: 'Probe Relabelled' },
+    status: [200], expect: (b) => isObject(b) && b.label === 'Probe Relabelled' && b.name === 'email',
+  },
+  'DELETE /crm/v3/properties/{objectType}/{propertyName}': {
+    method: 'DELETE', path: '/crm/v3/properties/contacts/probe_deletable', status: [204], expect: (b) => b === null,
+  },
+  'GET /crm/v3/properties/{objectType}/groups': {
+    method: 'GET', path: '/crm/v3/properties/contacts/groups', status: [200],
+    expect: (b) => isCollection(b) && any_(b).results.some((g: any) => g.name === 'contactinformation'),
+  },
+  'POST /crm/v3/properties/{objectType}/groups': {
+    method: 'POST', path: '/crm/v3/properties/contacts/groups', body: { name: 'probe_group', label: 'Probe Group' },
+    status: [201], expect: (b) => isObject(b) && b.name === 'probe_group' && b.label === 'Probe Group',
+  },
+  'GET /crm/v3/properties/{objectType}/groups/{groupName}': {
+    method: 'GET', path: '/crm/v3/properties/contacts/groups/contactinformation', status: [200],
+    expect: (b) => isObject(b) && b.name === 'contactinformation' && typeof b.label === 'string',
+  },
+  'PATCH /crm/v3/properties/{objectType}/groups/{groupName}': {
+    method: 'PATCH', path: '/crm/v3/properties/contacts/groups/contactinformation', body: { label: 'Probe Group Relabelled' },
+    status: [200], expect: (b) => isObject(b) && b.label === 'Probe Group Relabelled',
+  },
+  'DELETE /crm/v3/properties/{objectType}/groups/{groupName}': {
+    method: 'DELETE', path: '/crm/v3/properties/contacts/groups/probe_deletable_group', status: [204], expect: (b) => b === null,
+  },
+  // ── pipelines ──
+  'GET /crm/v3/pipelines/{objectType}': {
+    method: 'GET', path: '/crm/v3/pipelines/deals', status: [200],
+    // HubSpot's out-of-the-box deal pipeline id and two of its stage ids — literals.
+    expect: (b) => isCollection(b) && any_(b).results.some((p: any) => p.id === 'default' && Array.isArray(p.stages)
+      && p.stages.some((s: any) => s.id === 'closedwon') && p.stages.some((s: any) => s.id === 'appointmentscheduled')),
+  },
+  'POST /crm/v3/pipelines/{objectType}': {
+    method: 'POST', path: '/crm/v3/pipelines/deals', body: { label: 'Probe Pipeline', displayOrder: 3, stages: [{ label: 'Probe Stage', displayOrder: 0 }] },
+    status: [201], expect: (b) => isObject(b) && b.label === 'Probe Pipeline' && Array.isArray(b.stages) && (b.stages as any[]).length === 1,
+  },
+  'GET /crm/v3/pipelines/{objectType}/{pipelineId}': {
+    method: 'GET', path: `/crm/v3/pipelines/deals/${PIPELINE}`, status: [200],
+    expect: (b) => isObject(b) && b.label === 'Probe Fixture Pipeline' && Array.isArray(b.stages),
+  },
+  'PATCH /crm/v3/pipelines/{objectType}/{pipelineId}': {
+    method: 'PATCH', path: `/crm/v3/pipelines/deals/${PIPELINE}`, body: { label: 'Probe Pipeline Renamed' },
+    status: [200], expect: (b) => isObject(b) && b.label === 'Probe Pipeline Renamed',
+  },
+  'PUT /crm/v3/pipelines/{objectType}/{pipelineId}': {
+    method: 'PUT', path: `/crm/v3/pipelines/deals/${PIPELINE}`, body: { label: 'Probe Pipeline Replaced', displayOrder: 4, stages: [{ label: 'Only Stage', displayOrder: 0 }] },
+    status: [200], expect: (b) => isObject(b) && b.label === 'Probe Pipeline Replaced' && (b.stages as any[]).length === 1,
+  },
+  'DELETE /crm/v3/pipelines/{objectType}/{pipelineId}': {
+    method: 'DELETE', path: '/crm/v3/pipelines/deals/SENTINEL_DELETABLE_PIPELINE', status: [204], expect: (b) => b === null,
+  },
+  // The stage family drives its OWN pipeline: the `PUT /pipelines/{id}` probe above REPLACES
+  // that pipeline's stages, which would invalidate a stage id captured before it ran.
+  'GET /crm/v3/pipelines/{objectType}/{pipelineId}/stages': {
+    method: 'GET', path: `/crm/v3/pipelines/deals/${STAGE_PIPELINE}/stages`, status: [200],
+    expect: (b) => isCollection(b, 2) && any_(b).results.every((s: any) => typeof s.id === 'string' && typeof s.label === 'string'),
+  },
+  'POST /crm/v3/pipelines/{objectType}/{pipelineId}/stages': {
+    method: 'POST', path: `/crm/v3/pipelines/deals/${STAGE_PIPELINE}/stages`, body: { label: 'Added Stage', displayOrder: 9 },
+    status: [201], expect: (b) => isObject(b) && b.label === 'Added Stage' && b.displayOrder === 9,
+  },
+  'GET /crm/v3/pipelines/{objectType}/{pipelineId}/stages/{stageId}': {
+    method: 'GET', path: `/crm/v3/pipelines/deals/${STAGE_PIPELINE}/stages/${STAGE}`, status: [200],
+    expect: (b) => isObject(b) && b.label === 'S1' && typeof b.displayOrder === 'number',
+  },
+  'PATCH /crm/v3/pipelines/{objectType}/{pipelineId}/stages/{stageId}': {
+    method: 'PATCH', path: `/crm/v3/pipelines/deals/${STAGE_PIPELINE}/stages/${STAGE}`, body: { label: 'Stage Renamed' },
+    status: [200], expect: (b) => isObject(b) && b.label === 'Stage Renamed',
+  },
+  'PUT /crm/v3/pipelines/{objectType}/{pipelineId}/stages/{stageId}': {
+    method: 'PUT', path: `/crm/v3/pipelines/deals/${STAGE_PIPELINE}/stages/${STAGE}`, body: { label: 'Stage Replaced', displayOrder: 1 },
+    status: [200], expect: (b) => isObject(b) && b.label === 'Stage Replaced' && b.displayOrder === 1,
+  },
+  'DELETE /crm/v3/pipelines/{objectType}/{pipelineId}/stages/{stageId}': {
+    method: 'DELETE', path: `/crm/v3/pipelines/deals/${STAGE_PIPELINE}/stages/SENTINEL_DELETABLE_STAGE`, status: [204], expect: (b) => b === null,
+  },
+  // ── owners ──
+  'GET /crm/v3/owners': {
+    method: 'GET', path: '/crm/v3/owners', status: [200],
+    expect: (b) => isCollection(b) && any_(b).results.every((o: any) => typeof o.id === 'string' && ['PERSON', 'QUEUE'].includes(o.type)),
+  },
+  'GET /crm/v3/owners/{ownerId}': {
+    method: 'GET', path: '/crm/v3/owners/1', status: [200],
+    expect: (b) => isObject(b) && b.id === '1' && b.type === 'PERSON' && typeof b.email === 'string',
+  },
+  // ── associations v4 ──
+  'GET /crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}': {
+    // Driven against the fixture contact that ALREADY HAS an association. §9 round one caught the
+    // first version pointing at CONTACT, whose associations are only created by probes that run
+    // LATER in the census order — so the body was `{results: []}` and `length >= 0` plus
+    // `[].every(...)` were both vacuously true. A handler returning a constant empty list passed.
+    method: 'GET', path: '/crm/v4/objects/contacts/SENTINEL_ASSOC_CONTACT/associations/companies', status: [200],
+    expect: (b) => isCollection(b, 1)
+      && any_(b).results.some((r: any) => typeof r.toObjectId === 'string' && r.toObjectId !== ''
+        && Array.isArray(r.associationTypes) && r.associationTypes.some((t: any) => t.typeId === 279 && t.category === 'HUBSPOT_DEFINED')),
+  },
+  'PUT /crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}': {
+    method: 'PUT', path: `/crm/v4/objects/contacts/${CONTACT}/associations/companies/${COMPANY}`,
+    // `AssociationSpec` is a CLOSED two-key shape — there is no `label` on the request; HubSpot
+    // resolves labels from the association-type DEFINITION, which this twin does not model, so
+    // `labels` is empty and `fromObjectTypeId`/`toObjectTypeId` carry the NUMERIC objectTypeIds.
+    body: [{ associationCategory: 'USER_DEFINED', associationTypeId: 42 }],
+    status: [201],
+    expect: (b) => isObject(b) && Array.isArray(b.labels) && (b.labels as string[]).length === 0
+      && b.fromObjectTypeId === '0-1' && b.toObjectTypeId === '0-2' && typeof b.toObjectId === 'string',
+  },
+  'DELETE /crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}': {
+    method: 'DELETE', path: '/crm/v4/objects/contacts/SENTINEL_ASSOC_CONTACT/associations/companies/SENTINEL_ASSOC_COMPANY',
+    status: [204], expect: (b) => b === null,
+  },
+  'PUT /crm/v4/objects/{objectType}/{objectId}/associations/default/{toObjectType}/{toObjectId}': {
+    method: 'PUT', path: `/crm/v4/objects/contacts/${CONTACT}/associations/default/companies/${COMPANY}`, status: [200],
+    // 279 is HubSpot's documented contact→company default association type id — a literal.
+    expect: (b) => isObject(b) && Array.isArray(b.results) && (b.results as any[])[0]?.associationSpec?.associationTypeId === 279,
+  },
+  'POST /crm/v4/associations/{fromObjectType}/{toObjectType}/batch/read': {
+    method: 'POST', path: '/crm/v4/associations/contacts/companies/batch/read', body: { inputs: [{ id: CONTACT }] },
+    status: [200], expect: (b) => isBatch(b) && Array.isArray(any_(b).results[0].to),
+  },
+  'POST /crm/v4/associations/{fromObjectType}/{toObjectType}/batch/create': {
+    method: 'POST', path: '/crm/v4/associations/contacts/companies/batch/create',
+    body: { inputs: [{ from: { id: CONTACT }, to: { id: COMPANY }, types: [{ associationCategory: 'HUBSPOT_DEFINED', associationTypeId: 279 }] }] },
+    status: [201], expect: (b) => isBatch(b) && any_(b).results[0].fromObjectTypeId === '0-1' && any_(b).results[0].toObjectTypeId === '0-2',
+  },
+  'POST /crm/v4/associations/{fromObjectType}/{toObjectType}/batch/archive': {
+    method: 'POST', path: '/crm/v4/associations/contacts/companies/batch/archive',
+    body: { inputs: [{ from: { id: 'SENTINEL_ASSOC2_CONTACT' }, to: [{ id: 'SENTINEL_ASSOC2_COMPANY' }] }] },
+    status: [204], expect: (b) => b === null,
+  },
+};
+
+/**
+ * THE ROUTER CENSUS — method/path pairs `handleHubspotTwinRequest` branches on, enumerated BY HAND
+ * from the dispatch. Deliberately NOT the probe table's keys: these drive object types and route
+ * families the probes never touch, so the generic `{objectType}` branches are proven reachable for
+ * more than the one type the probes use.
+ */
+type RouterRoute = [method: string, path: string, status: number[], body?: unknown];
+const ROUTER_SURFACE: RouterRoute[] = [
+  // Each entry declares the STATUS a LIVE branch answers with. §9 round one caught the first
+  // version grading only "is this the generic 404 miss?", which meant a branch that degraded to
+  // a 400/405/500 — or one whose objectType alias table was deleted, so `GET /crm/v3/objects/0-1`
+  // started answering "Unable to infer object type from: 0-1" — stayed GREEN in the census that
+  // names it. That is the tinybird "teeth at the dispatch and nowhere deeper" trap, surviving in
+  // the census half. The status set closes it.
+  ['POST', '/crm/v3/objects/companies', [400]],            // no properties in the body
+  ['GET', '/crm/v3/objects/companies', [200]],
+  ['GET', `/crm/v3/objects/companies/${COMPANY}`, [200]],
+  ['PATCH', `/crm/v3/objects/companies/${COMPANY}`, [400]], // no properties in the body
+  ['GET', '/crm/v3/objects/deals', [200]],
+  ['GET', `/crm/v3/objects/deals/${DEAL}`, [200]],
+  ['GET', '/crm/v3/objects/tickets', [200]],
+  ['GET', `/crm/v3/objects/tickets/${TICKET}`, [200]],
+  ['POST', '/crm/v3/objects/deals/search', [200]],
+  // A REAL inputs array, so the request reaches the `op === 'read'` branch rather than
+  // stopping at the shared `inputs must be an array` guard above it. §9 round two: the earlier
+  // `[400]` entries were satisfied by that guard, so the branch they NAME stayed deletable.
+  ['POST', '/crm/v3/objects/tickets/batch/read', [200, 207], { properties: [], inputs: [{ id: '424242' }] }],
+  // the numeric objectTypeId alias HubSpot also accepts for contacts — a 200 here, so deleting
+  // OBJECT_TYPE_IDS reddens THIS entry rather than only a capability elsewhere
+  ['GET', '/crm/v3/objects/0-1', [200]],
+  // properties + groups on a second object type
+  ['GET', '/crm/v3/properties/deals', [200]],
+  ['GET', '/crm/v3/properties/deals/groups', [200]],
+  ['GET', '/crm/v3/properties/deals/dealstage', [200]],
+  ['POST', '/crm/v3/properties/deals/batch/create', [400]],   // no inputs array
+  // the pipelines family on tickets — HubSpot's other pipelined object
+  ['GET', '/crm/v3/pipelines/tickets', [200]],
+  ['GET', '/crm/v3/pipelines/tickets/0', [200]],
+  ['GET', '/crm/v3/pipelines/tickets/0/stages', [200]],
+  ['GET', '/crm/v3/pipelines/tickets/0/stages/1', [200]],
+  ['GET', '/crm/v3/owners', [200]],
+  ['GET', '/crm/v3/owners/1', [200]],
+  // associations in the other direction
+  // The company that HAS an association — a 200-on-empty would be the same vacuity round one
+  // removed from the probe half.
+  ['GET', '/crm/v4/objects/companies/SENTINEL_ASSOC_COMPANY/associations/contacts', [200]],
+  ['POST', '/crm/v4/associations/deals/contacts/batch/read', [404], { inputs: [{ id: '424242' }] }], // reaches the branch; the record miss is its own 404
+];
+
+/** The generic router miss — distinct in MESSAGE from a real record-not-found 404. */
+function isRouterMiss(res: HubspotResponse): boolean {
+  return res.status === 404
+    && isObject(res.body)
+    && typeof res.body.message === 'string'
+    && res.body.message.startsWith('resource not found: ');
+}
+
+export async function checkHubspotConformance(opts: { root?: string } = {}): Promise<HubspotConformanceReport> {
+  void opts; // always a THROWAWAY root: the probes create, archive and merge real records.
+  const snapshot = hubspotTwinSnapshot();
+  const claimed = new Set(snapshot.implementedEndpoints);
+  const violations: string[] = [];
+  const root = mkdtempSync(join(tmpdir(), 'hubspot-conformance-'));
+  const call = (method: string, path: string, body?: unknown): Promise<HubspotResponse> =>
+    handleHubspotTwinRequest({ method, path, ...(body === undefined ? {} : { body: JSON.stringify(body) }), root, occurredAt: AT });
+
+  let probed = 0;
+  try {
+    // ── fixtures the probes address ───────────────────────────────────────────────────────
+    const mk = async (type: string, props: Record<string, string>): Promise<string> => {
+      const res = await call('POST', `/crm/v3/objects/${type}`, { properties: props });
+      const id = isObject(res.body) ? String(res.body.id ?? '') : '';
+      if (res.status !== 201 || !id) violations.push(`fixture: POST /crm/v3/objects/${type} answered ${res.status}, so every probe addressing it is unverified`);
+      return id;
+    };
+    const contactId = await mk('contacts', { email: 'probe@twin.test', firstname: 'Probe' });
+    const contact2Id = await mk('contacts', { email: 'archivable@twin.test' });
+    const mergeId = await mk('contacts', { email: 'mergeable@twin.test', phone: '+15550199' });
+    const batchArchiveId = await mk('contacts', { email: 'batch-archivable@twin.test' });
+    const assocContactId = await mk('contacts', { email: 'assoc@twin.test' });
+    const assoc2ContactId = await mk('contacts', { email: 'assoc2@twin.test' });
+    const companyId = await mk('companies', { name: 'Probe Co', domain: 'probe.test' });
+    const assocCompanyId = await mk('companies', { name: 'Assoc Co' });
+    const assoc2CompanyId = await mk('companies', { name: 'Assoc2 Co' });
+    const dealId = await mk('deals', { dealname: 'Probe Deal', amount: '1200', dealstage: 'closedwon' });
+    const ticketId = await mk('tickets', { subject: 'Probe Ticket', hs_pipeline_stage: '1' });
+    // Each destructive probe gets its OWN fixture, so probe ORDER cannot make this check lie.
+    await call('PUT', `/crm/v4/objects/contacts/${assocContactId}/associations/default/companies/${assocCompanyId}`);
+    await call('PUT', `/crm/v4/objects/contacts/${assoc2ContactId}/associations/default/companies/${assoc2CompanyId}`);
+    await call('POST', '/crm/v3/properties/contacts', { name: 'probe_deletable', label: 'Deletable', type: 'string', fieldType: 'text', groupName: 'contactinformation' });
+    await call('POST', '/crm/v3/properties/contacts/groups', { name: 'probe_deletable_group', label: 'Deletable Group' });
+    const mkPipeline = async (label: string, stages: Record<string, unknown>[]): Promise<string> => {
+      const res = await call('POST', '/crm/v3/pipelines/deals', { label, displayOrder: 5, stages });
+      return isObject(res.body) ? String(res.body.id ?? '') : '';
+    };
+    const pipelineId = await mkPipeline('Probe Fixture Pipeline', [{ label: 'S1', displayOrder: 0 }]);
+    const deletablePipelineId = await mkPipeline('Deletable Pipeline', [{ label: 'S1', displayOrder: 0 }]);
+    const stagePipelineId = await mkPipeline('Stage Fixture Pipeline', [{ label: 'S1', displayOrder: 0 }, { label: 'S2', displayOrder: 1 }]);
+    const stagesOf = async (pid: string): Promise<string[]> => {
+      const res = await call('GET', `/crm/v3/pipelines/deals/${pid}`);
+      return isObject(res.body) && Array.isArray(res.body.stages) ? (res.body.stages as any[]).map((s) => String(s.id)) : [];
+    };
+    const fixtureStages = await stagesOf(stagePipelineId);
+    const stageId = fixtureStages[0] ?? '';
+    const deletableStageId = fixtureStages[1] ?? '';
+
+    // Longest sentinel first: CONTACT is a prefix of nothing, but CONTACT2 contains CONTACT's
+    // stem, so order matters (the §0.5 longest-match-first rule, applied to substitution).
+    const substitute = (s: string): string => s
+      .replaceAll(CONTACT2, contact2Id)
+      .replaceAll(CONTACT, contactId)
+      .replaceAll(COMPANY, companyId)
+      .replaceAll(DEAL, dealId)
+      .replaceAll(TICKET, ticketId)
+      .replaceAll('SENTINEL_MERGE_ID', mergeId)
+      .replaceAll('SENTINEL_BATCH_ARCHIVE_ID', batchArchiveId)
+      .replaceAll('SENTINEL_ASSOC2_CONTACT', assoc2ContactId)
+      .replaceAll('SENTINEL_ASSOC2_COMPANY', assoc2CompanyId)
+      .replaceAll('SENTINEL_ASSOC_CONTACT', assocContactId)
+      .replaceAll('SENTINEL_ASSOC_COMPANY', assocCompanyId)
+      .replaceAll('SENTINEL_DELETABLE_PIPELINE', deletablePipelineId)
+      .replaceAll(STAGE_PIPELINE, stagePipelineId)
+      .replaceAll('SENTINEL_DELETABLE_STAGE', deletableStageId)
+      .replaceAll(PIPELINE, pipelineId)
+      .replaceAll(STAGE, stageId);
+    const substituteBody = (b: unknown): unknown => (b === undefined ? undefined : JSON.parse(substitute(JSON.stringify(b))) as unknown);
+
+    // ── the ROUTER CENSUS, both directions ────────────────────────────────────────────────
+    for (const [method, rawPath, expected, routeBody] of ROUTER_SURFACE) {
+      const res = await call(method, substitute(rawPath), substituteBody(routeBody));
+      const key = `${method} ${canonicalPath(rawPath)}`;
+      if (isRouterMiss(res)) {
+        violations.push(`the router census names '${method} ${rawPath}' (canonically '${key}') but the router no longer REACHES it — it fell through to the generic miss, so the handler branch that served it is gone`);
+        continue;
+      }
+      if (!expected.includes(res.status)) {
+        violations.push(`the router census names '${method} ${rawPath}' and a live branch answers [${expected.join(', ')}] there, but it answered ${res.status} — ${JSON.stringify(res.body).slice(0, 200)}`);
+        continue;
+      }
+      if (!claimed.has(key)) {
+        violations.push(`the router answers '${method} ${rawPath}' (${res.status}) whose canonical form '${key}' the endpoint census does not claim — served surface outside the census is deletable without this check noticing`);
+      }
+    }
+
+    // ── probe⇄snapshot bijection, then one LIVE request per claimed endpoint ──────────────
+    for (const endpoint of snapshot.implementedEndpoints) {
+      const probe = PROBES[endpoint];
+      if (!probe) { violations.push(`endpoint '${endpoint}' is claimed but has no conformance probe — the claim is unverified`); continue; }
+      const [claimedMethod, claimedPath] = endpoint.split(' ');
+      if (probe.method !== claimedMethod) { violations.push(`probe '${endpoint}' drives ${probe.method}, not ${claimedMethod}`); continue; }
+      if (canonicalPath(probe.path) !== claimedPath) {
+        violations.push(`probe '${endpoint}' drives ${probe.path}, whose canonical form is ${canonicalPath(probe.path)} — not the claimed path ${claimedPath}`);
+        continue;
+      }
+      const res = await call(probe.method, substitute(probe.path), substituteBody(probe.body));
+      probed += 1;
+      if (!probe.status.includes(res.status)) {
+        violations.push(`${endpoint}: answered ${res.status}, expected one of [${probe.status.join(', ')}] — body ${JSON.stringify(res.body).slice(0, 200)}`);
+        continue;
+      }
+      if (probe.expect && !probe.expect(res.body)) {
+        violations.push(`${endpoint}: status ${res.status} was right but the body is not what a live handler produces — ${JSON.stringify(res.body).slice(0, 240)}`);
+      }
+    }
+    for (const key of Object.keys(PROBES)) {
+      if (!claimed.has(key)) violations.push(`probe '${key}' exercises an endpoint the census does not claim — the two must biject`);
+    }
+
+    // ── the error envelope + the determinism invariant, driven for real ───────────────────
+    const miss = await call('GET', '/crm/v3/objects/contacts/99999999');
+    const missBody = miss.body as Record<string, unknown> | null;
+    if (miss.status !== 404 || !isObject(missBody) || missBody.status !== 'error' || missBody.category !== 'OBJECT_NOT_FOUND'
+      || typeof missBody.message !== 'string'
+      || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(String(missBody.correlationId))) {
+      violations.push(`an unknown record id must answer HubSpot's documented error envelope { status:'error', message, correlationId (uuid-shaped), category:'OBJECT_NOT_FOUND' } — got ${miss.status} ${JSON.stringify(missBody)}`);
+    }
+    const badType = await call('GET', '/crm/v3/objects/wombats');
+    if (badType.status !== 400 || !isObject(badType.body) || badType.body.category !== 'VALIDATION_ERROR'
+      || !String(badType.body.message).startsWith('Unable to infer object type from:')) {
+      violations.push(`an unknown objectType must answer 400 VALIDATION_ERROR "Unable to infer object type from: …" — got ${badType.status} ${JSON.stringify(badType.body)}`);
+    }
+    const headed = await call('GET', '/crm/v3/objects/contacts');
+    if (headed.headers?.['x-hubspot-ratelimit-max'] !== '190' || headed.headers?.['x-hubspot-ratelimit-interval-milliseconds'] !== '10000' || headed.headers?.['x-hubspot-ratelimit-daily'] !== '625000') {
+      violations.push(`every response must carry HubSpot's documented rate-limit policy headers (Max 190 / Interval 10000 / Daily 625000) — got ${JSON.stringify(headed.headers)}`);
+    }
+    const a = await call('GET', '/crm/v3/objects/contacts/99999999');
+    const b = await call('GET', '/crm/v3/objects/contacts/99999999');
+    if (JSON.stringify(a.body) !== JSON.stringify(b.body)) {
+      violations.push('two identical requests produced different bodies — the correlationId (or something else) is not derived, and the serve path is not replayable');
+    }
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+
+  return {
+    ok: violations.length === 0,
+    endpointsClaimed: snapshot.implementedEndpoints.length,
+    endpointsProbed: probed,
+    routerRoutesChecked: ROUTER_SURFACE.length,
+    violations,
+  };
+}