@volter/twin-hubspot 0.1.0

package/dist/src/hubspot-conformance.d.ts

@@ -0,0 +1,16 @@
+export type HubspotConformanceReport = {
+    ok: boolean;
+    endpointsClaimed: number;
+    endpointsProbed: number;
+    routerRoutesChecked: number;
+    violations: string[];
+};
+/**
+ * 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 declare function canonicalPath(path: string): string;
+export declare function checkHubspotConformance(opts?: {
+    root?: string;
+}): Promise<HubspotConformanceReport>;

package/dist/src/hubspot-conformance.js

@@ -0,0 +1,523 @@
+// 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 } from "./hubspot-twin.js";
+const isObject = (b) => !!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) {
+    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) {
+    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, minResults = 1) {
+    return isObject(b) && Array.isArray(b.results) && b.results.length >= minResults;
+}
+function isBatch(b, minResults = 1) {
+    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) => b;
+/** A representative request per claimed endpoint, with the outcome a LIVE handler produces. */
+const PROBES = {
+    // ── 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) => 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) => 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) => p.id === 'default' && Array.isArray(p.stages)
+            && p.stages.some((s) => s.id === 'closedwon') && p.stages.some((s) => 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.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.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) => 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) => 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) => typeof r.toObjectId === 'string' && r.toObjectId !== ''
+                && Array.isArray(r.associationTypes) && r.associationTypes.some((t) => 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.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[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,
+    },
+};
+const ROUTER_SURFACE = [
+    // 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) {
+    return res.status === 404
+        && isObject(res.body)
+        && typeof res.body.message === 'string'
+        && res.body.message.startsWith('resource not found: ');
+}
+export async function checkHubspotConformance(opts = {}) {
+    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 = [];
+    const root = mkdtempSync(join(tmpdir(), 'hubspot-conformance-'));
+    const call = (method, path, body) => handleHubspotTwinRequest({ method, path, ...(body === undefined ? {} : { body: JSON.stringify(body) }), root, occurredAt: AT });
+    let probed = 0;
+    try {
+        // ── fixtures the probes address ───────────────────────────────────────────────────────
+        const mk = async (type, props) => {
+            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, stages) => {
+            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) => {
+            const res = await call('GET', `/crm/v3/pipelines/deals/${pid}`);
+            return isObject(res.body) && Array.isArray(res.body.stages) ? res.body.stages.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) => 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) => (b === undefined ? undefined : JSON.parse(substitute(JSON.stringify(b))));
+        // ── 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;
+        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,
+    };
+}