@volter/twin-hubspot 0.1.0

package/src/hubspot-capabilities.ts

@@ -0,0 +1,1523 @@
+// HubSpot capability manifest — the EXPECTED REAL-PRODUCT SURFACE (the target), authored
+// top-down from what HubSpot's CRM API actually does — NOT from what this twin has built.
+//
+// The DENOMINATOR's source is `@hubspot/api-client` 14.0.1's generated client: 936 operations
+// across eleven top-level families, enumerated from every `lib/codegen/**/apis/*Api.js` request
+// factory. The eleven families are censused in `hubspot-areas.ts`; the CRM ones are modeled here
+// and the rest carry their area's reason in `hubspot-deferred-capabilities.ts` (the azure
+// precedent). Coverage reads LOW and that is correct — a broad honest denominator beats a thin
+// self-portrait.
+//
+// `verify()` (required to count as done) is ground truth: offline, deterministic, and FAILABLE —
+// a real create → read → assert VALUES, plus the vendor's negative 4xx. Every `expected:'done'`
+// is genuinely claimed, so a broken one shows as a regression.
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createElement } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import {
+  assertAreaCensus, checkCapabilities, harnessError, isInfrastructureError, uiDataCoupled,
+  verifyBoundary, type CapabilityReport, type CapabilitySpec,
+} from '@volter/world-tooling';
+import { DealBoard, RecordDetail, RecordsTable } from '../client/hubspot-mirror.tsx';
+import { HUBSPOT_AREAS, HUBSPOT_AREA_IDS } from './hubspot-areas.ts';
+import { hubspotOAuth, TWIN_HUB_ID } from './hubspot-oauth.tsx';
+import { HUBSPOT_DEFERRED_AREA_CAPABILITIES, HUBSPOT_UNMODELED_CRM_CAPABILITIES } from './hubspot-deferred-capabilities.ts';
+import { MIRROR_SECTIONS, createHubspotMirrorServer, groupByStage, recordTitle, stageTone, type HubspotRow } from './hubspot-mirror-ui.ts';
+import { HUBSPOT_LOCAL_ID_BASE, SEARCH_FILTER_OPERATORS, handleHubspotTwinRequest, type HubspotResponse } from './hubspot-twin.ts';
+import {
+  hubspotRequestForAction, mapCrmObject, pullHubspotAll, pushPendingHubspotActions,
+  syncHubspotFromReal, type HubspotExecute,
+} from './hubspot-connector.ts';
+
+// ── API verify: drive REAL requests against a fresh temp root, then assert status/shape ──
+type Step = { m: string; p: string; b?: unknown };
+type H = (s: Step) => Promise<HubspotResponse>;
+const AT = '2026-02-01T00:00:00.000Z';
+
+async function withRoot(steps: (h: H) => Promise<boolean>): Promise<boolean> {
+  const root = mkdtempSync(join(tmpdir(), 'hubspot-cap-'));
+  const h: H = (s) => handleHubspotTwinRequest({ method: s.m, path: s.p, body: s.b === undefined ? undefined : JSON.stringify(s.b), root, occurredAt: AT });
+  try { return await verifyBoundary('hubspot.withRoot', () => steps(h)); } finally { rmSync(root, { recursive: true, force: true }); }
+}
+/** Same, but with a CALLER-CHOSEN occurredAt per step — needed wherever a verify repeats an
+ *  identical transition (the kernel dedupes an action by content + millisecond). */
+async function withClock(steps: (h: (s: Step & { at?: string }) => Promise<HubspotResponse>) => Promise<boolean>): Promise<boolean> {
+  const root = mkdtempSync(join(tmpdir(), 'hubspot-cap-clock-'));
+  const h = (s: Step & { at?: string }) => handleHubspotTwinRequest({ method: s.m, path: s.p, body: s.b === undefined ? undefined : JSON.stringify(s.b), root, occurredAt: s.at ?? AT });
+  try { return await verifyBoundary('hubspot.withClock', () => steps(h)); } finally { rmSync(root, { recursive: true, force: true }); }
+}
+
+const ok = (r: HubspotResponse) => r.status >= 200 && r.status < 300;
+const body = (r: HubspotResponse) => r.body as any;
+const errOf = (r: HubspotResponse) => r.body as { status?: string; message?: string; category?: string; correlationId?: string; errors?: unknown[] };
+/**
+ * The four keys HubSpot's own error-handling reference shows on every error body. NB the
+ * generated `ModelError.d.ts` declares message/correlationId/category (plus optional
+ * subCategory/context/links/errors) and NOT `status` — the vendor emits it and `StandardError`
+ * declares it, so the twin serving it is correct, but under §6's precedence rule this one key is
+ * grounded in the DOCS rather than in a generated type. Said out loud rather than implied.
+ */
+const isHubspotError = (r: HubspotResponse, category: string): boolean => {
+  const e = errOf(r);
+  return e?.status === 'error' && e.category === category && typeof e.message === 'string' && e.message.length > 0
+    && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(String(e.correlationId));
+};
+const mk = async (h: H, type: string, props: Record<string, string>): Promise<string> => {
+  const r = await h({ m: 'POST', p: `/crm/v3/objects/${type}`, b: { properties: props } });
+  return r.status === 201 ? String(body(r).id) : '';
+};
+
+// ── shorthands ──
+const done = (id: string, area: string, title: string, dimension: CapabilitySpec['dimension'], tier: CapabilitySpec['tier'], verify: CapabilitySpec['verify']): CapabilitySpec => ({ id, area, title, dimension, tier, expected: 'done', verify });
+const todo = (id: string, area: string, title: string, dimension: CapabilitySpec['dimension'], tier: CapabilitySpec['tier']): CapabilitySpec => ({ id, area, title, dimension, tier, expected: 'todo' });
+
+// ── connector fakes (offline, no network) ──
+/** A fake portal with two pages of contacts and one of everything else. */
+function fakePortal(opts: { failOn?: string; httpStatus?: number } = {}): { execute: HubspotExecute; calls: string[] } {
+  const calls: string[] = [];
+  const execute: HubspotExecute = async (method, path) => {
+    calls.push(`${method} ${path}`);
+    if (opts.failOn && path.includes(opts.failOn)) {
+      return { httpStatus: opts.httpStatus ?? 401, body: { status: 'error', message: 'refused', category: 'INVALID_AUTHENTICATION', correlationId: 'x' } };
+    }
+    if (path.startsWith('/crm/v3/owners')) {
+      return { httpStatus: 200, body: { results: [{ id: '77', email: 'real@portal.test', firstName: 'Real', lastName: 'Owner', type: 'PERSON', userId: 9, archived: false, createdAt: AT, updatedAt: AT }] } };
+    }
+    if (path.startsWith('/crm/v3/objects/contacts')) {
+      // TWO pages, so the connector's paging.next.after loop is genuinely exercised — and the ids
+      // are SPARSE and low, the shape real HubSpot contact ids actually take. §9's revert matrix
+      // found the first version of this fixture (501/502) could not expose a count-based mint at
+      // all, because both ids sat below the mint's base: the collision the doctrine names needs a
+      // pulled id sitting in the gap a naive mint walks through.
+      if (!path.includes('after=')) {
+        return { httpStatus: 200, body: { results: [{ id: '1001', properties: { email: 'p1@portal.test' }, createdAt: AT, updatedAt: AT, archived: false }], paging: { next: { after: '1003' } } } };
+      }
+      return { httpStatus: 200, body: { results: [{ id: '1003', properties: { email: 'p2@portal.test' }, createdAt: AT, updatedAt: AT, archived: false }] } };
+    }
+    if (path.startsWith('/crm/v3/objects/companies')) {
+      return { httpStatus: 200, body: { results: [{ id: '1051', properties: { name: 'Portal Co' }, createdAt: AT, updatedAt: AT, archived: false }] } };
+    }
+    return { httpStatus: 200, body: { results: [] } };
+  };
+  return { execute, calls };
+}
+
+export const HUBSPOT_CAPABILITIES: CapabilitySpec[] = [
+  // ══ CRM objects ═════════════════════════════════════════════════════════════════════════
+  done('hubspot.objects.create', 'objects', 'POST /crm/v3/objects/{objectType} — create a record (201 SimplePublicObject)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/crm/v3/objects/contacts', b: { properties: { email: 'a@b.test', firstname: 'Ada' } } });
+      const d = body(r);
+      return r.status === 201 && d.properties.email === 'a@b.test' && d.properties.firstname === 'Ada'
+        && d.properties.hs_object_id === d.id && d.archived === false
+        && typeof d.createdAt === 'string' && typeof d.updatedAt === 'string';
+    })),
+  done('hubspot.objects.create.rejects_bad_properties', 'objects', 'POST rejects a non-string / non-object properties map (400 VALIDATION_ERROR)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const missing = await h({ m: 'POST', p: '/crm/v3/objects/contacts', b: {} });
+      const nested = await h({ m: 'POST', p: '/crm/v3/objects/contacts', b: { properties: { email: { nested: true } } } });
+      return missing.status === 400 && isHubspotError(missing, 'VALIDATION_ERROR')
+        && nested.status === 400 && Array.isArray(errOf(nested).errors);
+    })),
+  done('hubspot.objects.create.unknown_object_type', 'objects', 'An objectType HubSpot cannot infer either → 400 "Unable to infer object type from: …"', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/crm/v3/objects/wombats', b: { properties: { name: 'x' } } });
+      const props = await h({ m: 'GET', p: '/crm/v3/properties/wombats' });
+      return r.status === 400 && isHubspotError(r, 'VALIDATION_ERROR') && String(errOf(r).message).startsWith('Unable to infer object type from: wombats')
+        && props.status === 400;
+    })),
+  done('hubspot.objects.get', 'objects', 'GET /crm/v3/objects/{objectType}/{objectId} — read a record back', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const id = await mk(h, 'contacts', { email: 'a@b.test' });
+      const g = await h({ m: 'GET', p: `/crm/v3/objects/contacts/${id}` });
+      return ok(g) && body(g).id === id && body(g).properties.email === 'a@b.test';
+    })),
+  done('hubspot.objects.get.unknown_404', 'objects', 'An unknown record id → 404 OBJECT_NOT_FOUND in the documented envelope', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/crm/v3/objects/contacts/99999999' });
+      return r.status === 404 && isHubspotError(r, 'OBJECT_NOT_FOUND');
+    })),
+  done('hubspot.objects.get.properties_param', 'objects', '?properties= narrows the returned property map (system properties always ride along)', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const id = await mk(h, 'contacts', { email: 'a@b.test', firstname: 'Ada', lastname: 'L' });
+      const g = await h({ m: 'GET', p: `/crm/v3/objects/contacts/${id}?properties=firstname` });
+      const p = body(g).properties;
+      return ok(g) && p.firstname === 'Ada' && p.lastname === undefined
+        && p.hs_object_id === id && typeof p.createdate === 'string' && typeof p.lastmodifieddate === 'string';
+    })),
+  done('hubspot.objects.list', 'objects', 'GET /crm/v3/objects/{objectType} — the { results } collection envelope', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await mk(h, 'contacts', { email: 'a@b.test' });
+      await mk(h, 'contacts', { email: 'c@d.test' });
+      const r = await h({ m: 'GET', p: '/crm/v3/objects/contacts' });
+      return ok(r) && body(r).results.length === 2 && body(r).results.every((x: any) => typeof x.id === 'string')
+        && body(r).paging === undefined;
+    })),
+  done('hubspot.objects.list.paging_after', 'objects', 'paging.next.after is the NEXT record id, and following it returns the rest without overlap', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const ids: string[] = [];
+      for (let i = 0; i < 5; i += 1) ids.push(await mk(h, 'contacts', { email: `p${i}@b.test` }));
+      const p1 = await h({ m: 'GET', p: '/crm/v3/objects/contacts?limit=2' });
+      const after = body(p1).paging?.next?.after;
+      if (body(p1).results.length !== 2 || after !== ids[2]) return false;
+      const p2 = await h({ m: 'GET', p: `/crm/v3/objects/contacts?limit=2&after=${after}` });
+      if (body(p2).results.length !== 2 || body(p2).results[0].id !== ids[2]) return false;
+      const p3 = await h({ m: 'GET', p: `/crm/v3/objects/contacts?limit=2&after=${body(p2).paging.next.after}` });
+      const seen = [...body(p1).results, ...body(p2).results, ...body(p3).results].map((x: any) => x.id);
+      return body(p3).paging === undefined && new Set(seen).size === 5;
+    })),
+  done('hubspot.objects.list.limit_cap', 'objects', 'The documented list cap: ?limit above 100 (or below 1) → 400 VALIDATION_ERROR', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const over = await h({ m: 'GET', p: '/crm/v3/objects/contacts?limit=101' });
+      const at = await h({ m: 'GET', p: '/crm/v3/objects/contacts?limit=100' });
+      const zero = await h({ m: 'GET', p: '/crm/v3/objects/contacts?limit=0' });
+      return over.status === 400 && isHubspotError(over, 'VALIDATION_ERROR') && at.status === 200 && zero.status === 400;
+    })),
+  done('hubspot.objects.list.archived', 'objects', '?archived=true lists archived records and excludes live ones (and vice versa)', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const live = await mk(h, 'contacts', { email: 'live@b.test' });
+      const gone = await mk(h, 'contacts', { email: 'gone@b.test' });
+      await h({ m: 'DELETE', p: `/crm/v3/objects/contacts/${gone}` });
+      const active = await h({ m: 'GET', p: '/crm/v3/objects/contacts' });
+      const arch = await h({ m: 'GET', p: '/crm/v3/objects/contacts?archived=true' });
+      return body(active).results.length === 1 && body(active).results[0].id === live
+        && body(arch).results.length === 1 && body(arch).results[0].id === gone && body(arch).results[0].archived === true;
+    })),
+  done('hubspot.objects.update', 'objects', 'PATCH merges the given properties and leaves the rest alone', 'api', 'core', () =>
+    withClock(async (h) => {
+      const c = await h({ m: 'POST', p: '/crm/v3/objects/contacts', b: { properties: { email: 'a@b.test', firstname: 'Ada' } }, at: '2026-02-01T00:00:00.000Z' });
+      const id = body(c).id;
+      const p = await h({ m: 'PATCH', p: `/crm/v3/objects/contacts/${id}`, b: { properties: { lastname: 'Lovelace' } }, at: '2026-02-02T00:00:00.000Z' });
+      const g = await h({ m: 'GET', p: `/crm/v3/objects/contacts/${id}` });
+      return ok(p) && body(g).properties.firstname === 'Ada' && body(g).properties.lastname === 'Lovelace'
+        && body(g).properties.email === 'a@b.test'
+        && body(g).properties.lastmodifieddate === '2026-02-02T00:00:00.000Z'
+        && body(g).properties.createdate === '2026-02-01T00:00:00.000Z';
+    })),
+  done('hubspot.objects.update.unknown_404', 'objects', 'PATCH on an unknown or archived record → 404 OBJECT_NOT_FOUND', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const id = await mk(h, 'contacts', { email: 'a@b.test' });
+      await h({ m: 'DELETE', p: `/crm/v3/objects/contacts/${id}` });
+      const gone = await h({ m: 'PATCH', p: `/crm/v3/objects/contacts/${id}`, b: { properties: { firstname: 'x' } } });
+      const never = await h({ m: 'PATCH', p: '/crm/v3/objects/contacts/424242', b: { properties: { firstname: 'x' } } });
+      return gone.status === 404 && never.status === 404 && isHubspotError(never, 'OBJECT_NOT_FOUND');
+    })),
+  done('hubspot.objects.archive', 'objects', 'DELETE archives (204, no body) — a later GET is 404 and the list drops it', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const id = await mk(h, 'contacts', { email: 'a@b.test' });
+      const d = await h({ m: 'DELETE', p: `/crm/v3/objects/contacts/${id}` });
+      const g = await h({ m: 'GET', p: `/crm/v3/objects/contacts/${id}` });
+      const l = await h({ m: 'GET', p: '/crm/v3/objects/contacts' });
+      const again = await h({ m: 'DELETE', p: `/crm/v3/objects/contacts/${id}` });
+      return d.status === 204 && d.body === null && g.status === 404 && body(l).results.length === 0 && again.status === 404;
+    })),
+  // ── DIRTY-STATE: behavior that only breaks OVER prior state ──
+  done('hubspot.objects.id_mint_never_reuses_an_archived_id', 'objects', 'DIRTY STATE: archive then create — the new record never reuses the archived id', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const a = await mk(h, 'contacts', { email: 'a@b.test' });
+      const b2 = await mk(h, 'contacts', { email: 'b@b.test' });
+      await h({ m: 'DELETE', p: `/crm/v3/objects/contacts/${b2}` });
+      await h({ m: 'DELETE', p: `/crm/v3/objects/contacts/${a}` });
+      const c = await mk(h, 'contacts', { email: 'c@b.test' });
+      const d = await mk(h, 'contacts', { email: 'd@b.test' });
+      // A count-based mint would answer `a` and `b2` again here and clobber the tombstones.
+      if (c === a || c === b2 || d === a || d === b2 || c === d) return false;
+      const archived = await h({ m: 'GET', p: '/crm/v3/objects/contacts?archived=true' });
+      return body(archived).results.length === 2 && Number(c) > Number(b2);
+    })),
+  done('hubspot.objects.id_mint_never_collides_with_a_pulled_id', 'objects', 'DIRTY STATE: create AFTER a connector pull — a local mint never lands on an observed portal id', 'api', 'core', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'hubspot-cap-mint-'));
+    try {
+      const { execute } = fakePortal();
+      await pullHubspotAll(execute, root); // observes contacts 1001 and 1003 — a SPARSE id range
+      const r = await handleHubspotTwinRequest({ method: 'POST', path: '/crm/v3/objects/contacts', body: JSON.stringify({ properties: { email: 'local@b.test' } }), root, occurredAt: AT });
+      const minted = String((r.body as any).id);
+      // The mint must clear EVERY observed id AND sit above the namespaced base — and both pulled
+      // records must still hold their own values. A count-based mint answers exactly '1003' here
+      // (a base of 1000 plus two observed rows plus one) and silently overwrites the second
+      // pulled contact, which is why the fixture's ids are sparse rather than contiguous.
+      const first = await handleHubspotTwinRequest({ method: 'GET', path: '/crm/v3/objects/contacts/1001', root, occurredAt: AT });
+      const second = await handleHubspotTwinRequest({ method: 'GET', path: '/crm/v3/objects/contacts/1003', root, occurredAt: AT });
+      // The magnitude is asserted against a LITERAL written here, not against the constant
+      // itself: `minted > HUBSPOT_LOCAL_ID_BASE` alone is two constants agreeing, and would stay
+      // green if the base were shrunk back into HubSpot's own id range. 1e11 is ~4x the largest
+      // HubSpot record id this repo has observed (~2.7e10).
+      return r.status === 201
+        && HUBSPOT_LOCAL_ID_BASE >= 100_000_000_000
+        && minted !== '1001' && minted !== '1003' && Number(minted) > HUBSPOT_LOCAL_ID_BASE
+        && first.status === 200 && (first.body as any).properties.email === 'p1@portal.test'
+        && second.status === 200 && (second.body as any).properties.email === 'p2@portal.test';
+    } catch (err) { if (isInfrastructureError(err)) throw harnessError('hubspot.objects.id_mint_never_collides_with_a_pulled_id', err); return false; } finally { rmSync(root, { recursive: true, force: true }); }
+  }),
+  // The INVERSE direction, which §9 round one found unhunted: a pull arriving AFTER a local
+  // create. `mapCrmObject` keys its subject as `<objectType>_<portal id>`, so a portal record
+  // numbered like a locally minted one would fold onto the same kernel subject. Two things make
+  // that safe, and this pins BOTH:
+  //   • the mint is NAMESPACED (HUBSPOT_LOCAL_ID_BASE) an order of magnitude above the largest
+  //     HubSpot record id this repo has observed, so the two ranges cannot meet; and
+  //   • `mapCrmObject` stamps `hsLocalMint: false`, so an OBSERVED row is addressable upstream
+  //     while a locally minted one is not — the contrast this verify asserts directly.
+  done('hubspot.objects.id_mint_pull_after_local_create', 'objects', 'DIRTY STATE: a connector pull AFTER a local create — ordinary portal ids cannot reach the local mint range, and an observed record is addressable where a minted one is not', 'api', 'core', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'hubspot-cap-mint-inverse-'));
+    try {
+      const local = await handleHubspotTwinRequest({ method: 'POST', path: '/crm/v3/objects/contacts', body: JSON.stringify({ properties: { email: 'local@b.test' } }), root, occurredAt: '2026-02-01T00:00:00.000Z' });
+      const localId = String((local.body as any).id);
+      if (Number(localId) <= HUBSPOT_LOCAL_ID_BASE) return false;
+      await pullHubspotAll(fakePortal().execute, root, '2026-02-02T00:00:00.000Z');
+      const list = await handleHubspotTwinRequest({ method: 'GET', path: '/crm/v3/objects/contacts?limit=100', root, occurredAt: AT });
+      const rows = (list.body as any).results as { id: string; properties: Record<string, string> }[];
+      const byId = new Map(rows.map((x) => [x.id, x.properties.email]));
+      // three DISTINCT records survive, each holding its own value — nothing was folded away.
+      if (rows.length !== 3 || byId.get(localId) !== 'local@b.test' || byId.get('1001') !== 'p1@portal.test' || byId.get('1003') !== 'p2@portal.test') return false;
+      // …and the ranges genuinely cannot meet: every id the portal handed over is below the base.
+      if (!['1001', '1003'].every((id) => Number(id) < HUBSPOT_LOCAL_ID_BASE)) return false;
+      // The addressability contrast, asserted on the mapper and the request builder directly: an
+      // OBSERVED row carries `hsLocalMint: false` and is addressed by its real id; a MINTED one
+      // carries true and can only ever be a create.
+      // Read the stamp back OUT OF FOLDED STATE, not only off the mapper's return value: the
+      // claim is about what a pull leaves in the projection (§9 round two).
+      const { twinResources } = await import('@volter/world-core');
+      const folded = twinResources('hubspot', root).find((x) => x.id === 'contacts_1001') as Record<string, unknown> | undefined;
+      if (!folded || folded.hsLocalMint !== false) return false;
+      const localFolded = twinResources('hubspot', root).find((x) => x.id === `contacts_${localId}`) as Record<string, unknown> | undefined;
+      if (!localFolded || localFolded.hsLocalMint !== true) return false;
+      const observedFields = mapCrmObject('contacts', { id: '1001', properties: { email: 'p1@portal.test' }, createdAt: AT, updatedAt: AT, archived: false }).fields as Record<string, unknown>;
+      if (observedFields.hsLocalMint !== false) return false;
+      const observedReq = hubspotRequestForAction({ id: 'o', subject: { type: 'crm_object', id: 'contacts_1001' }, fields: { ...observedFields, props: { email: 'edited@portal.test' } } } as never);
+      const mintedReq = hubspotRequestForAction({ id: 'm', subject: { type: 'crm_object', id: `contacts_${localId}` }, fields: { objectType: 'contacts', hsId: localId, hsLocalMint: true, props: { email: 'local@b.test' } } } as never);
+      return observedReq?.method === 'PATCH' && observedReq.path === '/crm/v3/objects/contacts/1001'
+        && mintedReq?.method === 'POST' && mintedReq.path === '/crm/v3/objects/contacts';
+    } catch (err) { if (isInfrastructureError(err)) throw harnessError('hubspot.objects.id_mint_pull_after_local_create', err); return false; } finally { rmSync(root, { recursive: true, force: true }); }
+  }),
+  done('hubspot.objects.merge', 'objects', 'POST /merge — the primary keeps its values, its BLANKS fill from the secondary, the secondary archives', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const primary = await mk(h, 'contacts', { email: 'keep@b.test', firstname: '' });
+      const secondary = await mk(h, 'contacts', { email: 'drop@b.test', firstname: 'Filled', phone: '+15550100' });
+      const m = await h({ m: 'POST', p: '/crm/v3/objects/contacts/merge', b: { primaryObjectId: primary, objectIdToMerge: secondary } });
+      const g = await h({ m: 'GET', p: `/crm/v3/objects/contacts/${primary}` });
+      const s = await h({ m: 'GET', p: `/crm/v3/objects/contacts/${secondary}` });
+      return ok(m) && body(m).id === primary
+        && body(g).properties.email === 'keep@b.test'   // primary's own value wins
+        && body(g).properties.firstname === 'Filled'    // primary's BLANK filled from secondary
+        && body(g).properties.phone === '+15550100'     // absent on primary → taken
+        && s.status === 404;                            // secondary archived
+    })),
+  done('hubspot.objects.merge.rejects_bad_input', 'objects', 'POST /merge refuses missing ids, identical ids, and an unknown id', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const a = await mk(h, 'contacts', { email: 'a@b.test' });
+      const missing = await h({ m: 'POST', p: '/crm/v3/objects/contacts/merge', b: { primaryObjectId: a } });
+      const same = await h({ m: 'POST', p: '/crm/v3/objects/contacts/merge', b: { primaryObjectId: a, objectIdToMerge: a } });
+      const gone = await h({ m: 'POST', p: '/crm/v3/objects/contacts/merge', b: { primaryObjectId: a, objectIdToMerge: '424242' } });
+      return missing.status === 400 && same.status === 400 && gone.status === 404 && isHubspotError(gone, 'OBJECT_NOT_FOUND');
+    })),
+  done('hubspot.objects.object_type_id_alias', 'objects', 'The numeric objectTypeId path segment (0-1/0-2/0-3/0-5) resolves to the same records', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const id = await mk(h, 'contacts', { email: 'a@b.test' });
+      const viaAlias = await h({ m: 'GET', p: `/crm/v3/objects/0-1/${id}` });
+      const dealAlias = await h({ m: 'POST', p: '/crm/v3/objects/0-3', b: { properties: { dealname: 'D' } } });
+      const dealByName = await h({ m: 'GET', p: '/crm/v3/objects/deals' });
+      return ok(viaAlias) && body(viaAlias).id === id && dealAlias.status === 201
+        && body(dealByName).results.length === 1 && body(dealByName).results[0].id === body(dealAlias).id;
+    })),
+  done('hubspot.objects.companies', 'objects', 'The companies object: create/read with its own HubSpot-defined properties', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const id = await mk(h, 'companies', { name: 'Acme', domain: 'acme.test' });
+      const g = await h({ m: 'GET', p: `/crm/v3/objects/companies/${id}` });
+      // companies use hs_lastmodifieddate, NOT contacts' lastmodifieddate
+      return ok(g) && body(g).properties.name === 'Acme' && typeof body(g).properties.hs_lastmodifieddate === 'string'
+        && body(g).properties.lastmodifieddate === undefined;
+    })),
+  done('hubspot.objects.deals', 'objects', 'The deals object: create/read with dealname, amount, dealstage, pipeline', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const id = await mk(h, 'deals', { dealname: 'Big One', amount: '2500', dealstage: 'qualifiedtobuy', pipeline: 'default' });
+      const g = await h({ m: 'GET', p: `/crm/v3/objects/deals/${id}` });
+      return ok(g) && body(g).properties.dealname === 'Big One' && body(g).properties.amount === '2500'
+        && body(g).properties.dealstage === 'qualifiedtobuy';
+    })),
+  done('hubspot.objects.tickets', 'objects', 'The tickets object: create/read with subject, priority and pipeline stage', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const id = await mk(h, 'tickets', { subject: 'Broken', hs_ticket_priority: 'HIGH', hs_pipeline: '0', hs_pipeline_stage: '1' });
+      const g = await h({ m: 'GET', p: `/crm/v3/objects/tickets/${id}` });
+      return ok(g) && body(g).properties.subject === 'Broken' && body(g).properties.hs_pipeline_stage === '1';
+    })),
+  todo('hubspot.objects.get_by_id_property', 'objects', 'GET ?idProperty= — read a record by a unique custom property instead of its record id', 'api', 'common'),
+  todo('hubspot.objects.properties_with_history', 'objects', '?propertiesWithHistory= — the per-property ValueWithTimestamp history HubSpot keeps', 'api', 'common'),
+  todo('hubspot.objects.gdpr_delete', 'objects', 'POST /crm/v3/objects/contacts/gdpr-delete — permanent GDPR erasure', 'api', 'niche'),
+  todo('hubspot.objects.object_write_trace_id', 'objects', 'objectWriteTraceId on create/update, echoed back on the response', 'api', 'niche'),
+  todo('hubspot.objects.calculated_properties', 'objects', 'HubSpot-calculated rollup properties (num_associated_contacts, total revenue…)', 'api', 'common'),
+  todo('hubspot.objects.required_property_validation', 'objects', 'Per-object required-property validation (a company needs name or domain)', 'api', 'common'),
+  todo('hubspot.objects.unique_property_conflict', 'objects', 'A duplicate value on a hasUniqueValue property → 409 CONFLICT', 'api', 'common'),
+  todo('hubspot.objects.enumeration_option_validation', 'objects', 'A value outside an enumeration property\'s option set is refused', 'api', 'common'),
+  todo('hubspot.objects.number_and_date_property_types', 'objects', 'Type coercion + validation for number/date/datetime/bool property types', 'api', 'common'),
+  todo('hubspot.objects.restore_archived', 'objects', 'Restoring an archived record (HubSpot\'s 90-day recycle window)', 'api', 'niche'),
+  todo('hubspot.objects.secondary_email', 'objects', 'Contacts\' hs_additional_emails secondary-email semantics', 'api', 'niche'),
+  todo('hubspot.objects.company_domain_dedupe', 'objects', 'HubSpot\'s automatic company de-duplication by domain', 'api', 'niche'),
+  todo('hubspot.objects.contact_email_dedupe', 'objects', 'HubSpot\'s automatic contact de-duplication by email on create', 'api', 'common'),
+  todo('hubspot.objects.lifecycle_stage_transitions', 'objects', 'Lifecycle-stage forward-only transition rules and their timestamps', 'api', 'niche'),
+  todo('hubspot.objects.owner_assignment_validation', 'objects', 'hubspot_owner_id must name a real owner', 'api', 'common'),
+
+  // ══ batch ═══════════════════════════════════════════════════════════════════════════════
+  done('hubspot.batch.create', 'objects', 'POST /batch/create — 201 BatchResponseSimplePublicObject with distinct ids', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/crm/v3/objects/contacts/batch/create', b: { inputs: [{ properties: { email: 'a@b.test' } }, { properties: { email: 'c@d.test' } }] } });
+      const d = body(r);
+      return r.status === 201 && d.status === 'COMPLETE' && d.results.length === 2
+        && d.results[0].id !== d.results[1].id && d.results[1].properties.email === 'c@d.test'
+        && typeof d.startedAt === 'string' && typeof d.completedAt === 'string';
+    })),
+  done('hubspot.batch.read', 'objects', 'POST /batch/read — 200 for a fully-found batch, with the requested properties', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const a = await mk(h, 'contacts', { email: 'a@b.test', firstname: 'Ada' });
+      const b2 = await mk(h, 'contacts', { email: 'c@d.test', firstname: 'Bo' });
+      const r = await h({ m: 'POST', p: '/crm/v3/objects/contacts/batch/read', b: { properties: ['email'], inputs: [{ id: a }, { id: b2 }] } });
+      return r.status === 200 && body(r).results.length === 2
+        && body(r).results[0].properties.email === 'a@b.test' && body(r).results[0].properties.firstname === undefined;
+    })),
+  done('hubspot.batch.read.partial_207', 'objects', 'A batch read with a missing id → 207 MULTI-STATUS carrying the found results AND the errors', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const a = await mk(h, 'contacts', { email: 'a@b.test' });
+      const r = await h({ m: 'POST', p: '/crm/v3/objects/contacts/batch/read', b: { properties: [], inputs: [{ id: a }, { id: '424242' }] } });
+      const e = body(r).errors[0];
+      // `StandardError` declares status/category/message/context/links/errors as REQUIRED — a
+      // partial entry would not survive the SDK's own deserializer (§9 round two: unpinned).
+      return r.status === 207 && body(r).results.length === 1 && body(r).numErrors === 1
+        && e.category === 'OBJECT_NOT_FOUND' && e.status === 'error' && typeof e.message === 'string'
+        && Array.isArray(e.context.ids) && e.context.ids[0] === '424242'
+        && typeof e.links === 'object' && Array.isArray(e.errors);
+    })),
+  done('hubspot.batch.read.id_property', 'objects', 'POST /batch/read with idProperty resolves records by a property value', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const a = await mk(h, 'contacts', { email: 'ada@b.test' });
+      const r = await h({ m: 'POST', p: '/crm/v3/objects/contacts/batch/read', b: { idProperty: 'email', properties: ['email'], inputs: [{ id: 'ada@b.test' }] } });
+      const miss = await h({ m: 'POST', p: '/crm/v3/objects/contacts/batch/read', b: { idProperty: 'email', properties: [], inputs: [{ id: 'nobody@b.test' }] } });
+      return r.status === 200 && body(r).results[0].id === a && miss.status === 207 && body(miss).results.length === 0;
+    })),
+  done('hubspot.batch.update', 'objects', 'POST /batch/update — 200, and the projection reflects every input', 'api', 'core', () =>
+    withClock(async (h) => {
+      const c1 = await h({ m: 'POST', p: '/crm/v3/objects/contacts', b: { properties: { email: 'a@b.test' } }, at: '2026-02-01T00:00:00.000Z' });
+      const c2 = await h({ m: 'POST', p: '/crm/v3/objects/contacts', b: { properties: { email: 'c@d.test' } }, at: '2026-02-01T00:00:00.000Z' });
+      const a = body(c1).id; const b2 = body(c2).id;
+      const r = await h({ m: 'POST', p: '/crm/v3/objects/contacts/batch/update', b: { inputs: [{ id: a, properties: { firstname: 'Ada' } }, { id: b2, properties: { firstname: 'Bo' } }] }, at: '2026-02-02T00:00:00.000Z' });
+      const ga = await h({ m: 'GET', p: `/crm/v3/objects/contacts/${a}` });
+      const gb = await h({ m: 'GET', p: `/crm/v3/objects/contacts/${b2}` });
+      return r.status === 200 && body(ga).properties.firstname === 'Ada' && body(gb).properties.firstname === 'Bo';
+    })),
+  done('hubspot.batch.upsert', 'objects', 'POST /batch/upsert by idProperty — new:true on a create, new:false on an update', 'api', 'common', () =>
+    withClock(async (h) => {
+      const first = await h({ m: 'POST', p: '/crm/v3/objects/contacts/batch/upsert', b: { inputs: [{ idProperty: 'email', id: 'up@b.test', properties: { firstname: 'One' } }] }, at: '2026-02-01T00:00:00.000Z' });
+      if (first.status !== 200 || body(first).results[0].new !== true) return false;
+      const id = body(first).results[0].id;
+      const second = await h({ m: 'POST', p: '/crm/v3/objects/contacts/batch/upsert', b: { inputs: [{ idProperty: 'email', id: 'up@b.test', properties: { firstname: 'Two' } }] }, at: '2026-02-02T00:00:00.000Z' });
+      const g = await h({ m: 'GET', p: `/crm/v3/objects/contacts/${id}` });
+      const l = await h({ m: 'GET', p: '/crm/v3/objects/contacts' });
+      return body(second).results[0].new === false && body(second).results[0].id === id
+        && body(g).properties.firstname === 'Two' && body(l).results.length === 1;
+    })),
+  done('hubspot.batch.archive', 'objects', 'POST /batch/archive — 204, and every listed record is gone from the live list', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const a = await mk(h, 'contacts', { email: 'a@b.test' });
+      const b2 = await mk(h, 'contacts', { email: 'c@d.test' });
+      const keep = await mk(h, 'contacts', { email: 'e@f.test' });
+      const r = await h({ m: 'POST', p: '/crm/v3/objects/contacts/batch/archive', b: { inputs: [{ id: a }, { id: b2 }] } });
+      const l = await h({ m: 'GET', p: '/crm/v3/objects/contacts' });
+      return r.status === 204 && r.body === null && body(l).results.length === 1 && body(l).results[0].id === keep;
+    })),
+  done('hubspot.batch.requires_inputs', 'objects', 'Every batch endpoint refuses a body with no inputs array (400 VALIDATION_ERROR)', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const ops = ['create', 'read', 'update', 'upsert', 'archive'];
+      for (const op of ops) {
+        const r = await h({ m: 'POST', p: `/crm/v3/objects/contacts/batch/${op}`, b: {} });
+        if (r.status !== 400 || !isHubspotError(r, 'VALIDATION_ERROR')) return false;
+      }
+      const unknown = await h({ m: 'POST', p: '/crm/v3/objects/contacts/batch/frobnicate', b: { inputs: [] } });
+      return unknown.status === 404;
+    })),
+  todo('hubspot.batch.size_cap', 'objects', 'The documented 100-input cap per batch call, refused above it', 'api', 'common'),
+  todo('hubspot.batch.upsert_conflict', 'objects', 'Upsert by a non-unique idProperty matching two records → the documented conflict', 'api', 'niche'),
+  todo('hubspot.batch.create_partial_207', 'objects', 'A partially-invalid batch CREATE → 207 with per-input errors instead of an all-or-nothing 400', 'api', 'common'),
+  todo('hubspot.batch.update_partial_207', 'objects', 'A batch UPDATE naming one missing id → 207 with per-input errors (today the whole batch aborts on that record\'s 404)', 'api', 'common'),
+  todo('hubspot.batch.upsert_partial_207', 'objects', 'A partially-invalid batch UPSERT → 207 with per-input errors', 'api', 'common'),
+  todo('hubspot.batch.archive_partial_207', 'objects', 'A batch ARCHIVE naming one missing id → 207 with per-input errors', 'api', 'niche'),
+
+  // ══ CRM Search ══════════════════════════════════════════════════════════════════════════
+  done('hubspot.search.filter_eq', 'search', 'POST /search — an EQ filter returns the matching records with a total', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await mk(h, 'contacts', { email: 'a@b.test', lifecyclestage: 'lead' });
+      await mk(h, 'contacts', { email: 'c@d.test', lifecyclestage: 'customer' });
+      const r = await h({ m: 'POST', p: '/crm/v3/objects/contacts/search', b: { filterGroups: [{ filters: [{ propertyName: 'lifecyclestage', operator: 'EQ', value: 'lead' }] }] } });
+      return ok(r) && body(r).total === 1 && body(r).results[0].properties.email === 'a@b.test';
+    })),
+  done('hubspot.search.operator_set_is_closed', 'search', 'Exactly the 13 documented FilterOperatorEnum values are accepted; anything else → 400', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await mk(h, 'contacts', { email: 'a@b.test' });
+      // The allowlist is the GENERATED FilterOperatorEnum from @hubspot/api-client, spelled out
+      // here as a literal so this is an oracle rather than the twin agreeing with itself.
+      const documented = ['EQ', 'NEQ', 'LT', 'LTE', 'GT', 'GTE', 'BETWEEN', 'IN', 'NOT_IN', 'HAS_PROPERTY', 'NOT_HAS_PROPERTY', 'CONTAINS_TOKEN', 'NOT_CONTAINS_TOKEN'];
+      if (documented.length !== SEARCH_FILTER_OPERATORS.length) return false;
+      for (const operator of documented) {
+        const r = await h({ m: 'POST', p: '/crm/v3/objects/contacts/search', b: { filterGroups: [{ filters: [{ propertyName: 'email', operator, value: 'a@b.test', values: ['a@b.test'], highValue: '1' }] }] } });
+        if (r.status !== 200) return false;
+      }
+      for (const operator of ['LIKE', 'CONTAINS', 'eq', '']) {
+        const r = await h({ m: 'POST', p: '/crm/v3/objects/contacts/search', b: { filterGroups: [{ filters: [{ propertyName: 'email', operator, value: 'x' }] }] } });
+        if (r.status !== 400 || !isHubspotError(r, 'VALIDATION_ERROR')) return false;
+      }
+      const noProp = await h({ m: 'POST', p: '/crm/v3/objects/contacts/search', b: { filterGroups: [{ filters: [{ operator: 'EQ', value: 'x' }] }] } });
+      return noProp.status === 400;
+    })),
+  done('hubspot.search.filter_groups_or_and', 'search', 'Filters AND within a group; groups OR with each other', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await mk(h, 'contacts', { email: 'a@b.test', lifecyclestage: 'lead', firstname: 'Ada' });
+      await mk(h, 'contacts', { email: 'c@d.test', lifecyclestage: 'customer', firstname: 'Bo' });
+      await mk(h, 'contacts', { email: 'e@f.test', lifecyclestage: 'lead', firstname: 'Cy' });
+      const and = await h({ m: 'POST', p: '/crm/v3/objects/contacts/search', b: { filterGroups: [{ filters: [{ propertyName: 'lifecyclestage', operator: 'EQ', value: 'lead' }, { propertyName: 'firstname', operator: 'EQ', value: 'Ada' }] }] } });
+      const or = await h({ m: 'POST', p: '/crm/v3/objects/contacts/search', b: { filterGroups: [{ filters: [{ propertyName: 'firstname', operator: 'EQ', value: 'Ada' }] }, { filters: [{ propertyName: 'firstname', operator: 'EQ', value: 'Bo' }] }] } });
+      return body(and).total === 1 && body(and).results[0].properties.firstname === 'Ada' && body(or).total === 2;
+    })),
+  done('hubspot.search.comparison_operators', 'search', 'LT/LTE/GT/GTE/BETWEEN compare numerically, not lexically', 'api', 'common', () =>
+    withRoot(async (h) => {
+      for (const amount of ['5', '50', '500']) await mk(h, 'deals', { dealname: `D${amount}`, amount });
+      const gt = await h({ m: 'POST', p: '/crm/v3/objects/deals/search', b: { filterGroups: [{ filters: [{ propertyName: 'amount', operator: 'GT', value: '40' }] }] } });
+      const between = await h({ m: 'POST', p: '/crm/v3/objects/deals/search', b: { filterGroups: [{ filters: [{ propertyName: 'amount', operator: 'BETWEEN', value: '10', highValue: '100' }] }] } });
+      const lte = await h({ m: 'POST', p: '/crm/v3/objects/deals/search', b: { filterGroups: [{ filters: [{ propertyName: 'amount', operator: 'LTE', value: '50' }] }] } });
+      // Lexically '5' > '40'; numerically it is not. That difference is the whole assertion.
+      return body(gt).total === 2 && body(between).total === 1 && body(lte).total === 2;
+    })),
+  done('hubspot.search.membership_operators', 'search', 'IN / NOT_IN match against the values[] array', 'api', 'common', () =>
+    withRoot(async (h) => {
+      for (const stage of ['lead', 'customer', 'other']) await mk(h, 'contacts', { email: `${stage}@b.test`, lifecyclestage: stage });
+      const inR = await h({ m: 'POST', p: '/crm/v3/objects/contacts/search', b: { filterGroups: [{ filters: [{ propertyName: 'lifecyclestage', operator: 'IN', values: ['lead', 'customer'] }] }] } });
+      const notIn = await h({ m: 'POST', p: '/crm/v3/objects/contacts/search', b: { filterGroups: [{ filters: [{ propertyName: 'lifecyclestage', operator: 'NOT_IN', values: ['lead'] }] }] } });
+      return body(inR).total === 2 && body(notIn).total === 2;
+    })),
+  done('hubspot.search.presence_operators', 'search', 'HAS_PROPERTY / NOT_HAS_PROPERTY treat an empty string as absent', 'api', 'common', () =>
+    withRoot(async (h) => {
+      await mk(h, 'contacts', { email: 'a@b.test', phone: '+15550100' });
+      await mk(h, 'contacts', { email: 'c@d.test', phone: '' });
+      await mk(h, 'contacts', { email: 'e@f.test' });
+      const has = await h({ m: 'POST', p: '/crm/v3/objects/contacts/search', b: { filterGroups: [{ filters: [{ propertyName: 'phone', operator: 'HAS_PROPERTY' }] }] } });
+      const not = await h({ m: 'POST', p: '/crm/v3/objects/contacts/search', b: { filterGroups: [{ filters: [{ propertyName: 'phone', operator: 'NOT_HAS_PROPERTY' }] }] } });
+      return body(has).total === 1 && body(not).total === 2;
+    })),
+  done('hubspot.search.contains_token', 'search', 'CONTAINS_TOKEN matches whole tokens and honours a trailing * wildcard', 'api', 'common', () =>
+    withRoot(async (h) => {
+      await mk(h, 'companies', { name: 'Acme Rocket Works' });
+      await mk(h, 'companies', { name: 'Globex Industries' });
+      const exact = await h({ m: 'POST', p: '/crm/v3/objects/companies/search', b: { filterGroups: [{ filters: [{ propertyName: 'name', operator: 'CONTAINS_TOKEN', value: 'rocket' }] }] } });
+      const wild = await h({ m: 'POST', p: '/crm/v3/objects/companies/search', b: { filterGroups: [{ filters: [{ propertyName: 'name', operator: 'CONTAINS_TOKEN', value: 'glob*' }] }] } });
+      const partial = await h({ m: 'POST', p: '/crm/v3/objects/companies/search', b: { filterGroups: [{ filters: [{ propertyName: 'name', operator: 'CONTAINS_TOKEN', value: 'ocke' }] }] } });
+      const negated = await h({ m: 'POST', p: '/crm/v3/objects/companies/search', b: { filterGroups: [{ filters: [{ propertyName: 'name', operator: 'NOT_CONTAINS_TOKEN', value: 'rocket' }] }] } });
+      // A partial token must NOT match — that is what makes this a token match, not a substring.
+      return body(exact).total === 1 && body(wild).total === 1 && body(partial).total === 0 && body(negated).total === 1;
+    })),
+  done('hubspot.search.free_text_query', 'search', 'A bare `query` searches across every property value', 'api', 'common', () =>
+    withRoot(async (h) => {
+      await mk(h, 'contacts', { email: 'ada@lovelace.test', firstname: 'Ada' });
+      await mk(h, 'contacts', { email: 'bo@peep.test', firstname: 'Bo' });
+      const r = await h({ m: 'POST', p: '/crm/v3/objects/contacts/search', b: { query: 'lovelace' } });
+      const none = await h({ m: 'POST', p: '/crm/v3/objects/contacts/search', b: { query: 'nobody' } });
+      return body(r).total === 1 && body(r).results[0].properties.firstname === 'Ada' && body(none).total === 0;
+    })),
+  done('hubspot.search.limit_cap', 'search', 'The documented search page cap: limit above 200 → 400 (200 itself is accepted)', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const at = await h({ m: 'POST', p: '/crm/v3/objects/contacts/search', b: { limit: 200 } });
+      const over = await h({ m: 'POST', p: '/crm/v3/objects/contacts/search', b: { limit: 201 } });
+      const zero = await h({ m: 'POST', p: '/crm/v3/objects/contacts/search', b: { limit: 0 } });
+      return at.status === 200 && over.status === 400 && isHubspotError(over, 'VALIDATION_ERROR') && zero.status === 400;
+    })),
+  done('hubspot.search.result_cap', 'search', 'Paging past the documented 10 000-result cap → 400', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const inside = await h({ m: 'POST', p: '/crm/v3/objects/contacts/search', b: { after: 9800, limit: 200 } });
+      const past = await h({ m: 'POST', p: '/crm/v3/objects/contacts/search', b: { after: 9801, limit: 200 } });
+      const negative = await h({ m: 'POST', p: '/crm/v3/objects/contacts/search', b: { after: -1 } });
+      return inside.status === 200 && past.status === 400 && negative.status === 400;
+    })),
+  done('hubspot.search.filter_count_caps', 'search', 'The documented 5 filterGroups / 6 filters per group / 18 filters overall caps', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const f = (n: number) => Array.from({ length: n }, () => ({ propertyName: 'email', operator: 'HAS_PROPERTY' }));
+      const groups = (g: number, per: number) => ({ filterGroups: Array.from({ length: g }, () => ({ filters: f(per) })) });
+      const okGroups = await h({ m: 'POST', p: '/crm/v3/objects/contacts/search', b: groups(3, 6) });
+      const tooManyGroups = await h({ m: 'POST', p: '/crm/v3/objects/contacts/search', b: groups(6, 1) });
+      const tooManyPerGroup = await h({ m: 'POST', p: '/crm/v3/objects/contacts/search', b: groups(1, 7) });
+      const tooManyTotal = await h({ m: 'POST', p: '/crm/v3/objects/contacts/search', b: groups(4, 5) });
+      return okGroups.status === 200 && tooManyGroups.status === 400 && tooManyPerGroup.status === 400 && tooManyTotal.status === 400;
+    })),
+  done('hubspot.search.paging', 'search', 'Search paging: total is the FULL match count and paging.next.after is the next offset', 'api', 'common', () =>
+    withRoot(async (h) => {
+      for (let i = 0; i < 5; i += 1) await mk(h, 'contacts', { email: `s${i}@b.test`, lifecyclestage: 'lead' });
+      const p1 = await h({ m: 'POST', p: '/crm/v3/objects/contacts/search', b: { limit: 2, filterGroups: [{ filters: [{ propertyName: 'lifecyclestage', operator: 'EQ', value: 'lead' }] }] } });
+      if (body(p1).total !== 5 || body(p1).results.length !== 2 || body(p1).paging.next.after !== '2') return false;
+      const p2 = await h({ m: 'POST', p: '/crm/v3/objects/contacts/search', b: { limit: 2, after: '2', filterGroups: [{ filters: [{ propertyName: 'lifecyclestage', operator: 'EQ', value: 'lead' }] }] } });
+      const p3 = await h({ m: 'POST', p: '/crm/v3/objects/contacts/search', b: { limit: 2, after: '4', filterGroups: [{ filters: [{ propertyName: 'lifecyclestage', operator: 'EQ', value: 'lead' }] }] } });
+      const seen = [...body(p1).results, ...body(p2).results, ...body(p3).results].map((x: any) => x.id);
+      return new Set(seen).size === 5 && body(p3).paging === undefined;
+    })),
+  done('hubspot.search.excludes_archived', 'search', 'Search never returns archived records', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const a = await mk(h, 'contacts', { email: 'a@b.test', lifecyclestage: 'lead' });
+      await mk(h, 'contacts', { email: 'c@d.test', lifecyclestage: 'lead' });
+      await h({ m: 'DELETE', p: `/crm/v3/objects/contacts/${a}` });
+      const r = await h({ m: 'POST', p: '/crm/v3/objects/contacts/search', b: { filterGroups: [{ filters: [{ propertyName: 'lifecyclestage', operator: 'EQ', value: 'lead' }] }] } });
+      return body(r).total === 1 && body(r).results[0].id !== a;
+    })),
+  done('hubspot.search.properties_projection', 'search', 'The `properties` array narrows the returned property map on search results', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      await mk(h, 'contacts', { email: 'a@b.test', firstname: 'Ada', lastname: 'L' });
+      const r = await h({ m: 'POST', p: '/crm/v3/objects/contacts/search', b: { properties: ['firstname'] } });
+      const p = body(r).results[0].properties;
+      return p.firstname === 'Ada' && p.lastname === undefined && p.hs_object_id !== undefined;
+    })),
+  done('hubspot.search.sorts', 'search', 'A `sorts` entry orders the result page by that property', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      await mk(h, 'companies', { name: 'Zeta' });
+      await mk(h, 'companies', { name: 'Alpha' });
+      const r = await h({ m: 'POST', p: '/crm/v3/objects/companies/search', b: { sorts: ['name'] } });
+      return body(r).results[0].properties.name === 'Alpha' && body(r).results[1].properties.name === 'Zeta';
+    })),
+  todo('hubspot.search.sort_direction', 'search', 'The `{ propertyName, direction }` sort object form, and DESCENDING order', 'api', 'common'),
+  todo('hubspot.search.associations_filter', 'search', 'Filtering by associations.{objectType} — records associated with a given record', 'api', 'common'),
+  todo('hubspot.search.eventual_consistency_window', 'search', 'HubSpot\'s documented indexing delay between a write and its searchability', 'api', 'niche'),
+  todo('hubspot.search.crm_search_rate_limit', 'search', 'The Search API\'s own 5-requests-per-second burst limit and its 429', 'api', 'niche'),
+
+  // ══ properties ══════════════════════════════════════════════════════════════════════════
+  done('hubspot.properties.list', 'properties', 'GET /crm/v3/properties/{objectType} — the HubSpot-defined property set per object', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const c = await h({ m: 'GET', p: '/crm/v3/properties/contacts' });
+      const d = await h({ m: 'GET', p: '/crm/v3/properties/deals' });
+      const names = (r: HubspotResponse) => body(r).results.map((p: any) => p.name);
+      return ok(c) && ['email', 'firstname', 'lastname', 'hs_object_id'].every((n) => names(c).includes(n))
+        && ['dealname', 'amount', 'dealstage', 'pipeline'].every((n) => names(d).includes(n))
+        && !names(d).includes('email')
+        && body(c).results.find((p: any) => p.name === 'email').hubspotDefined === true;
+    })),
+  done('hubspot.properties.create', 'properties', 'POST /crm/v3/properties/{objectType} — 201 Property, hubspotDefined false', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/crm/v3/properties/contacts', b: { name: 'account_tier', label: 'Account Tier', type: 'string', fieldType: 'text', groupName: 'contactinformation', description: 'The tier' } });
+      const g = await h({ m: 'GET', p: '/crm/v3/properties/contacts/account_tier' });
+      return r.status === 201 && body(r).name === 'account_tier' && body(r).label === 'Account Tier'
+        && body(r).hubspotDefined === false && body(g).description === 'The tier';
+    })),
+  done('hubspot.properties.create.requires_fields', 'properties', 'POST refuses a property missing name/label/type/fieldType/groupName (400 with errors[])', 'api', 'common', () =>
+    withRoot(async (h) => {
+      for (const omit of ['name', 'label', 'type', 'fieldType', 'groupName']) {
+        const full: Record<string, string> = { name: 'x', label: 'X', type: 'string', fieldType: 'text', groupName: 'contactinformation' };
+        delete full[omit];
+        const r = await h({ m: 'POST', p: '/crm/v3/properties/contacts', b: full });
+        if (r.status !== 400 || !isHubspotError(r, 'VALIDATION_ERROR') || !Array.isArray(errOf(r).errors)) return false;
+      }
+      return true;
+    })),
+  done('hubspot.properties.create.duplicate', 'properties', 'Creating a property whose name already exists → 409', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/crm/v3/properties/contacts', b: { name: 'email', label: 'E', type: 'string', fieldType: 'text', groupName: 'contactinformation' } });
+      return r.status === 409 && isHubspotError(r, 'CONFLICT');
+    })),
+  done('hubspot.properties.get', 'properties', 'GET one property by name; an unknown name → 404 OBJECT_NOT_FOUND', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const g = await h({ m: 'GET', p: '/crm/v3/properties/contacts/email' });
+      const miss = await h({ m: 'GET', p: '/crm/v3/properties/contacts/nope' });
+      return ok(g) && body(g).name === 'email' && body(g).groupName === 'contactinformation'
+        && miss.status === 404 && isHubspotError(miss, 'OBJECT_NOT_FOUND');
+    })),
+  done('hubspot.properties.update', 'properties', 'PATCH a property — the change folds and both the single GET and the list reflect it', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const p = await h({ m: 'PATCH', p: '/crm/v3/properties/contacts/email', b: { label: 'E-mail address' } });
+      const g = await h({ m: 'GET', p: '/crm/v3/properties/contacts/email' });
+      const l = await h({ m: 'GET', p: '/crm/v3/properties/contacts' });
+      const inList = body(l).results.find((x: any) => x.name === 'email');
+      const miss = await h({ m: 'PATCH', p: '/crm/v3/properties/contacts/nope', b: { label: 'x' } });
+      return ok(p) && body(g).label === 'E-mail address' && inList.label === 'E-mail address' && miss.status === 404;
+    })),
+  done('hubspot.properties.archive', 'properties', 'DELETE a property — 204, then GET 404 and the list drops it', 'api', 'common', () =>
+    withRoot(async (h) => {
+      await h({ m: 'POST', p: '/crm/v3/properties/contacts', b: { name: 'temp_prop', label: 'T', type: 'string', fieldType: 'text', groupName: 'contactinformation' } });
+      const d = await h({ m: 'DELETE', p: '/crm/v3/properties/contacts/temp_prop' });
+      const g = await h({ m: 'GET', p: '/crm/v3/properties/contacts/temp_prop' });
+      const l = await h({ m: 'GET', p: '/crm/v3/properties/contacts' });
+      const again = await h({ m: 'DELETE', p: '/crm/v3/properties/contacts/temp_prop' });
+      return d.status === 204 && g.status === 404 && !body(l).results.some((x: any) => x.name === 'temp_prop') && again.status === 404;
+    })),
+  done('hubspot.properties.custom_property_round_trips', 'properties', 'A custom property\'s value round-trips on a record and is searchable', 'api', 'common', () =>
+    withRoot(async (h) => {
+      await h({ m: 'POST', p: '/crm/v3/properties/contacts', b: { name: 'account_tier', label: 'Tier', type: 'string', fieldType: 'text', groupName: 'contactinformation' } });
+      const id = await mk(h, 'contacts', { email: 'a@b.test', account_tier: 'gold' });
+      const g = await h({ m: 'GET', p: `/crm/v3/objects/contacts/${id}?properties=account_tier` });
+      const s = await h({ m: 'POST', p: '/crm/v3/objects/contacts/search', b: { filterGroups: [{ filters: [{ propertyName: 'account_tier', operator: 'EQ', value: 'gold' }] }] } });
+      return body(g).properties.account_tier === 'gold' && body(s).total === 1;
+    })),
+  done('hubspot.property_groups.crud', 'properties', 'Property groups: list the HubSpot-defined group, create, read, rename, archive', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const seeded = await h({ m: 'GET', p: '/crm/v3/properties/contacts/groups' });
+      if (!body(seeded).results.some((g: any) => g.name === 'contactinformation')) return false;
+      const c = await h({ m: 'POST', p: '/crm/v3/properties/contacts/groups', b: { name: 'custom_group', label: 'Custom Group', displayOrder: 4 } });
+      if (c.status !== 201 || body(c).label !== 'Custom Group' || body(c).displayOrder !== 4) return false;
+      const dup = await h({ m: 'POST', p: '/crm/v3/properties/contacts/groups', b: { name: 'custom_group', label: 'Again' } });
+      const g = await h({ m: 'GET', p: '/crm/v3/properties/contacts/groups/custom_group' });
+      const p = await h({ m: 'PATCH', p: '/crm/v3/properties/contacts/groups/custom_group', b: { label: 'Renamed' } });
+      const d = await h({ m: 'DELETE', p: '/crm/v3/properties/contacts/groups/custom_group' });
+      const gone = await h({ m: 'GET', p: '/crm/v3/properties/contacts/groups/custom_group' });
+      return dup.status === 409 && isHubspotError(dup, 'CONFLICT') && body(g).name === 'custom_group' && body(p).label === 'Renamed' && d.status === 204 && gone.status === 404;
+    })),
+  done('hubspot.properties.unknown_object_type', 'properties', 'The properties routes refuse an unknown {objectType} the same way the object routes do', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const l = await h({ m: 'GET', p: '/crm/v3/properties/wombats' });
+      const g = await h({ m: 'GET', p: '/crm/v3/properties/wombats/groups' });
+      // …and a real-but-unmodeled type is refused HONESTLY on this family too, not with the
+      // vendor's cannot-infer wording.
+      const known = await h({ m: 'GET', p: '/crm/v3/properties/notes' });
+      return l.status === 400 && g.status === 400 && String(errOf(l).message).startsWith('Unable to infer object type from:')
+        && known.status === 404 && String(errOf(known).message).includes('does not model');
+    })),
+  // "Create a batch of properties" (the CRM properties reference): each input created as POST /crm/v3/properties/{objectType}
+  // creates one, answered in the batch envelope; a refused input refuses the batch and nothing of it is written.
+  done('hubspot.properties.batch_create', 'properties', 'POST /crm/v3/properties/{objectType}/batch/create — 201 batch of Property (formField kept); one refused input (a taken name, the same name twice, a missing field) refuses the batch, writing none', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const prop = (name: string, extra: Record<string, unknown> = {}) => ({ name, label: name, type: 'string', fieldType: 'text', groupName: 'contactinformation', ...extra });
+      const made = await h({ m: 'POST', p: '/crm/v3/properties/0-1/batch/create', b: { inputs: [prop('dub_id', { formField: true }), prop('dub_partner_email')] } });
+      const conflict = await h({ m: 'POST', p: '/crm/v3/properties/contacts/batch/create', b: { inputs: [prop('fresh_one'), prop('dub_id')] } });
+      const fresh = await h({ m: 'GET', p: '/crm/v3/properties/contacts/fresh_one' });
+      const missing = await h({ m: 'POST', p: '/crm/v3/properties/contacts/batch/create', b: { inputs: [{ name: 'no_label' }] } });
+      // one name twice in the same batch is the same conflict, and neither is created
+      const twice = await h({ m: 'POST', p: '/crm/v3/properties/contacts/batch/create', b: { inputs: [prop('twin_twice'), prop('twin_twice')] } });
+      const twiceRead = await h({ m: 'GET', p: '/crm/v3/properties/contacts/twin_twice' });
+      const kept = await h({ m: 'GET', p: '/crm/v3/properties/contacts/dub_id' });
+      return made.status === 201 && body(made).status === 'COMPLETE' && body(made).results.map((p: any) => p.name).join() === 'dub_id,dub_partner_email'
+        && body(made).results[0].formField === true && body(made).results[1].formField === false
+        && conflict.status === 409 && isHubspotError(conflict, 'CONFLICT') && fresh.status === 404
+        && missing.status === 400 && twice.status === 409 && isHubspotError(twice, 'CONFLICT') && twiceRead.status === 404 && body(kept).formField === true;
+    })),
+  todo('hubspot.properties.batch_read', 'properties', 'POST /crm/v3/properties/{objectType}/batch/read', 'api', 'common'),
+  todo('hubspot.properties.batch_archive', 'properties', 'POST /crm/v3/properties/{objectType}/batch/archive', 'api', 'niche'),
+  todo('hubspot.properties.enumeration_options', 'properties', 'Enumeration property `options` validation and option ordering', 'api', 'common'),
+  todo('hubspot.properties.calculation_formula', 'properties', 'Calculated properties: calculationFormula, calculated:true, read-only enforcement', 'api', 'niche'),
+  todo('hubspot.properties.modification_metadata', 'properties', 'modificationMetadata (readOnlyValue/readOnlyDefinition/archivable) on every property', 'api', 'niche'),
+  todo('hubspot.properties.referenced_object_type', 'properties', 'referencedObjectType on owner/record-reference properties', 'api', 'niche'),
+  todo('hubspot.properties.archive_blocks_hubspot_defined', 'properties', 'HubSpot refuses to archive a hubspotDefined property', 'api', 'common'),
+  todo('hubspot.properties.field_type_validation', 'properties', 'The closed PropertyCreateFieldTypeEnum / PropertyCreateTypeEnum vocabularies are enforced', 'api', 'common'),
+  todo('hubspot.properties.display_order', 'properties', 'displayOrder ordering of properties within a group', 'api', 'niche'),
+
+  // ══ pipelines ═══════════════════════════════════════════════════════════════════════════
+  done('hubspot.pipelines.default_deal_pipeline', 'pipelines', 'The out-of-the-box deal pipeline and its seven documented stage ids', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/crm/v3/pipelines/deals' });
+      const p = body(r).results.find((x: any) => x.id === 'default');
+      const stageIds = p ? p.stages.map((s: any) => s.id) : [];
+      return ok(r) && p?.label === 'Sales Pipeline'
+        && ['appointmentscheduled', 'qualifiedtobuy', 'presentationscheduled', 'decisionmakerboughtin', 'contractsent', 'closedwon', 'closedlost'].every((s) => stageIds.includes(s))
+        && p.stages.find((s: any) => s.id === 'closedwon').metadata.isClosed === 'true';
+    })),
+  done('hubspot.pipelines.default_ticket_pipeline', 'pipelines', 'The out-of-the-box ticket pipeline (id "0") and its four stages', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/crm/v3/pipelines/tickets' });
+      const p = body(r).results.find((x: any) => x.id === '0');
+      return ok(r) && p?.stages.length === 4 && p.stages.map((s: any) => s.id).join(',') === '1,2,3,4'
+        && p.stages[3].metadata.ticketState === 'CLOSED';
+    })),
+  done('hubspot.pipelines.create', 'pipelines', 'POST /crm/v3/pipelines/{objectType} — 201 Pipeline with its stages', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/crm/v3/pipelines/deals', b: { label: 'Renewals', displayOrder: 2, stages: [{ label: 'Contacted', displayOrder: 0 }, { label: 'Renewed', displayOrder: 1 }] } });
+      const l = await h({ m: 'GET', p: '/crm/v3/pipelines/deals' });
+      return r.status === 201 && body(r).label === 'Renewals' && body(r).stages.length === 2
+        && body(r).stages[0].label === 'Contacted' && body(r).archived === false
+        && body(l).results.length === 2;
+    })),
+  done('hubspot.pipelines.create.requires_fields', 'pipelines', 'POST refuses a pipeline missing label/displayOrder, or a stage missing either', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const noLabel = await h({ m: 'POST', p: '/crm/v3/pipelines/deals', b: { displayOrder: 1, stages: [] } });
+      const noOrder = await h({ m: 'POST', p: '/crm/v3/pipelines/deals', b: { label: 'X', stages: [] } });
+      const badStage = await h({ m: 'POST', p: '/crm/v3/pipelines/deals', b: { label: 'X', displayOrder: 1, stages: [{ label: 'S' }] } });
+      return noLabel.status === 400 && noOrder.status === 400 && badStage.status === 400 && isHubspotError(badStage, 'VALIDATION_ERROR');
+    })),
+  done('hubspot.pipelines.get', 'pipelines', 'GET one pipeline; an unknown id → 404 OBJECT_NOT_FOUND', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const g = await h({ m: 'GET', p: '/crm/v3/pipelines/deals/default' });
+      const miss = await h({ m: 'GET', p: '/crm/v3/pipelines/deals/nope' });
+      return ok(g) && body(g).id === 'default' && miss.status === 404 && isHubspotError(miss, 'OBJECT_NOT_FOUND');
+    })),
+  done('hubspot.pipelines.update_and_replace', 'pipelines', 'PATCH renames; PUT replaces and REQUIRES the full body', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const c = await h({ m: 'POST', p: '/crm/v3/pipelines/deals', b: { label: 'Renewals', displayOrder: 2, stages: [{ label: 'A', displayOrder: 0 }, { label: 'B', displayOrder: 1 }] } });
+      const id = body(c).id;
+      const patched = await h({ m: 'PATCH', p: `/crm/v3/pipelines/deals/${id}`, b: { label: 'Renamed' } });
+      if (!ok(patched) || body(patched).label !== 'Renamed' || body(patched).stages.length !== 2) return false;
+      const partialPut = await h({ m: 'PUT', p: `/crm/v3/pipelines/deals/${id}`, b: { label: 'Half' } });
+      const put = await h({ m: 'PUT', p: `/crm/v3/pipelines/deals/${id}`, b: { label: 'Replaced', displayOrder: 3, stages: [{ label: 'Only', displayOrder: 0 }] } });
+      const g = await h({ m: 'GET', p: `/crm/v3/pipelines/deals/${id}` });
+      return partialPut.status === 400 && ok(put) && body(g).label === 'Replaced' && body(g).stages.length === 1;
+    })),
+  done('hubspot.pipelines.archive', 'pipelines', 'DELETE a pipeline — 204, then GET 404 and the list drops it', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const c = await h({ m: 'POST', p: '/crm/v3/pipelines/deals', b: { label: 'Temp', displayOrder: 9, stages: [] } });
+      const id = body(c).id;
+      const d = await h({ m: 'DELETE', p: `/crm/v3/pipelines/deals/${id}` });
+      const g = await h({ m: 'GET', p: `/crm/v3/pipelines/deals/${id}` });
+      const l = await h({ m: 'GET', p: '/crm/v3/pipelines/deals' });
+      return d.status === 204 && g.status === 404 && body(l).results.length === 1;
+    })),
+  done('hubspot.pipelines.stages_crud', 'pipelines', 'Stages: list, add (201), read, rename, replace and remove — all folded into the pipeline', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const c = await h({ m: 'POST', p: '/crm/v3/pipelines/deals', b: { label: 'P', displayOrder: 2, stages: [{ label: 'A', displayOrder: 0 }] } });
+      const id = body(c).id;
+      const add = await h({ m: 'POST', p: `/crm/v3/pipelines/deals/${id}/stages`, b: { label: 'B', displayOrder: 1, metadata: { isClosed: 'false' } } });
+      if (add.status !== 201 || body(add).label !== 'B' || body(add).metadata.isClosed !== 'false') return false;
+      const sid = body(add).id;
+      const list = await h({ m: 'GET', p: `/crm/v3/pipelines/deals/${id}/stages` });
+      if (body(list).results.length !== 2) return false;
+      const get = await h({ m: 'GET', p: `/crm/v3/pipelines/deals/${id}/stages/${sid}` });
+      const patch = await h({ m: 'PATCH', p: `/crm/v3/pipelines/deals/${id}/stages/${sid}`, b: { label: 'B2' } });
+      const put = await h({ m: 'PUT', p: `/crm/v3/pipelines/deals/${id}/stages/${sid}`, b: { label: 'B3', displayOrder: 5 } });
+      const badPut = await h({ m: 'PUT', p: `/crm/v3/pipelines/deals/${id}/stages/${sid}`, b: { label: 'B4' } });
+      const del = await h({ m: 'DELETE', p: `/crm/v3/pipelines/deals/${id}/stages/${sid}` });
+      const gone = await h({ m: 'GET', p: `/crm/v3/pipelines/deals/${id}/stages/${sid}` });
+      const after = await h({ m: 'GET', p: `/crm/v3/pipelines/deals/${id}` });
+      return body(get).id === sid && body(patch).label === 'B2' && body(put).displayOrder === 5
+        && badPut.status === 400 && del.status === 204 && gone.status === 404 && body(after).stages.length === 1;
+    })),
+  done('hubspot.pipelines.stage_id_mint_never_reuses', 'pipelines', 'DIRTY STATE: remove a stage then add one — the new stage never reuses the removed id', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const c = await h({ m: 'POST', p: '/crm/v3/pipelines/deals', b: { label: 'P', displayOrder: 2, stages: [{ label: 'A', displayOrder: 0 }, { label: 'B', displayOrder: 1 }] } });
+      const id = body(c).id;
+      const stages = body(c).stages.map((s: any) => s.id);
+      await h({ m: 'DELETE', p: `/crm/v3/pipelines/deals/${id}/stages/${stages[0]}` });
+      const added = await h({ m: 'POST', p: `/crm/v3/pipelines/deals/${id}/stages`, b: { label: 'C', displayOrder: 2 } });
+      const after = await h({ m: 'GET', p: `/crm/v3/pipelines/deals/${id}` });
+      // A count-based mint would answer stages[0] again and silently take C's place.
+      return body(added).id !== stages[0] && body(after).stages.length === 2
+        && new Set(body(after).stages.map((s: any) => s.id)).size === 2;
+    })),
+  done('hubspot.pipelines.unsupported_object_type', 'pipelines', 'Only deals and tickets have pipelines — contacts/companies are refused (400)', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const contacts = await h({ m: 'GET', p: '/crm/v3/pipelines/contacts' });
+      const companies = await h({ m: 'GET', p: '/crm/v3/pipelines/companies' });
+      const deals = await h({ m: 'GET', p: '/crm/v3/pipelines/deals' });
+      return contacts.status === 400 && companies.status === 400 && deals.status === 200
+        && String(errOf(contacts).message).includes('does not support pipelines');
+    })),
+  todo('hubspot.pipelines.audit', 'pipelines', 'GET /crm/v3/pipelines/{objectType}/{pipelineId}/audit — the pipeline change audit trail', 'api', 'niche'),
+  todo('hubspot.pipelines.stage_audit', 'pipelines', 'GET …/stages/{stageId}/audit — the stage change audit trail', 'api', 'niche'),
+  todo('hubspot.pipelines.write_permissions', 'pipelines', 'PipelineStage writePermissions enforcement (CRM_PERMISSIONS_ENFORCEMENT vs READ_ONLY)', 'api', 'niche'),
+  todo('hubspot.pipelines.stage_validation_on_records', 'pipelines', 'A deal\'s dealstage must name a stage that exists in its pipeline', 'api', 'common'),
+  todo('hubspot.pipelines.probability_metadata', 'pipelines', 'Stage probability metadata and its effect on forecast properties', 'api', 'niche'),
+  todo('hubspot.pipelines.archive_blocks_default', 'pipelines', 'HubSpot refuses to archive a portal\'s only/default pipeline', 'api', 'niche'),
+
+  // ══ owners ══════════════════════════════════════════════════════════════════════════════
+  done('hubspot.owners.list', 'owners', 'GET /crm/v3/owners — the portal\'s owners in the PublicOwner shape', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/crm/v3/owners' });
+      const o = body(r).results[0];
+      return ok(r) && body(r).results.length >= 1 && o.id === '1' && o.type === 'PERSON'
+        && typeof o.email === 'string' && Array.isArray(o.teams) && o.teams[0].primary === true;
+    })),
+  done('hubspot.owners.get', 'owners', 'GET /crm/v3/owners/{ownerId}; an unknown id → 404 OBJECT_NOT_FOUND', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const g = await h({ m: 'GET', p: '/crm/v3/owners/1' });
+      const miss = await h({ m: 'GET', p: '/crm/v3/owners/9999' });
+      return ok(g) && body(g).id === '1' && miss.status === 404 && isHubspotError(miss, 'OBJECT_NOT_FOUND');
+    })),
+  done('hubspot.owners.filter_email', 'owners', 'GET /crm/v3/owners?email= narrows to that owner', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const all = await h({ m: 'GET', p: '/crm/v3/owners' });
+      const hit = await h({ m: 'GET', p: `/crm/v3/owners?email=${encodeURIComponent(body(all).results[0].email)}` });
+      const miss = await h({ m: 'GET', p: '/crm/v3/owners?email=nobody@nowhere.test' });
+      return body(hit).results.length === 1 && body(miss).results.length === 0;
+    })),
+  done('hubspot.owners.pulled_owners_surface', 'owners', 'Owners observed by a connector pull are served by the owners API', 'connector', 'common', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'hubspot-cap-owners-'));
+    try {
+      const { execute } = fakePortal();
+      await pullHubspotAll(execute, root);
+      const r = await handleHubspotTwinRequest({ method: 'GET', path: '/crm/v3/owners', root, occurredAt: AT });
+      const ids = (r.body as any).results.map((o: any) => o.id);
+      const one = await handleHubspotTwinRequest({ method: 'GET', path: '/crm/v3/owners/77', root, occurredAt: AT });
+      return ids.includes('77') && (one.body as any).email === 'real@portal.test';
+    } catch (err) { if (isInfrastructureError(err)) throw harnessError('hubspot.owners.pulled_owners_surface', err); return false; } finally { rmSync(root, { recursive: true, force: true }); }
+  }),
+  todo('hubspot.owners.archived_filter', 'owners', 'GET /crm/v3/owners?archived=true — deactivated owners', 'api', 'niche'),
+  todo('hubspot.owners.teams', 'owners', 'GET /settings/v3/users/teams — the team roster owners reference', 'api', 'niche'),
+  todo('hubspot.owners.queues', 'owners', 'Owner type QUEUE (a shared inbox/queue owner rather than a person)', 'api', 'niche'),
+
+  // ══ associations ════════════════════════════════════════════════════════════════════════
+  done('hubspot.associations.create_default', 'associations', 'PUT …/associations/default/… uses HubSpot\'s documented default type id (contact→company 279)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const c = await mk(h, 'contacts', { email: 'a@b.test' });
+      const co = await mk(h, 'companies', { name: 'Acme' });
+      const r = await h({ m: 'PUT', p: `/crm/v4/objects/contacts/${c}/associations/default/companies/${co}` });
+      return ok(r) && body(r).status === 'COMPLETE'
+        && body(r).results[0].associationSpec.associationTypeId === 279
+        && body(r).results[0].associationSpec.associationCategory === 'HUBSPOT_DEFINED'
+        && body(r).results[0].to.id === co;
+    })),
+  done('hubspot.associations.default_is_bidirectional', 'associations', 'A default association is readable from BOTH records, each with its own direction\'s type id', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const c = await mk(h, 'contacts', { email: 'a@b.test' });
+      const co = await mk(h, 'companies', { name: 'Acme' });
+      await h({ m: 'PUT', p: `/crm/v4/objects/contacts/${c}/associations/default/companies/${co}` });
+      const forward = await h({ m: 'GET', p: `/crm/v4/objects/contacts/${c}/associations/companies` });
+      const back = await h({ m: 'GET', p: `/crm/v4/objects/companies/${co}/associations/contacts` });
+      return body(forward).results[0].toObjectId === co && body(forward).results[0].associationTypes[0].typeId === 279
+        && body(back).results[0].toObjectId === c && body(back).results[0].associationTypes[0].typeId === 280;
+    })),
+  done('hubspot.associations.create_with_spec', 'associations', 'PUT with an AssociationSpec[] body → 201 LabelsBetweenObjectPair, and the spec round-trips onto the association', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const c = await mk(h, 'contacts', { email: 'a@b.test' });
+      const co = await mk(h, 'companies', { name: 'Acme' });
+      const r = await h({ m: 'PUT', p: `/crm/v4/objects/contacts/${c}/associations/companies/${co}`, b: [{ associationCategory: 'USER_DEFINED', associationTypeId: 42 }] });
+      const g = await h({ m: 'GET', p: `/crm/v4/objects/contacts/${c}/associations/companies` });
+      return r.status === 201
+        // the numeric objectTypeIds HubSpot reports, NOT the plural path segments
+        && body(r).fromObjectTypeId === '0-1' && body(r).toObjectTypeId === '0-2'
+        && body(r).fromObjectId === c && body(r).toObjectId === co
+        && body(g).results[0].toObjectId === co
+        && body(g).results[0].associationTypes[0].typeId === 42
+        && body(g).results[0].associationTypes[0].category === 'USER_DEFINED';
+    })),
+  // §9 round one: the previous version of the capability above PASSED ONLY BECAUSE the handler
+  // accepted a `label` on the request body and echoed it back. `AssociationSpec` declares exactly
+  // two keys and `label` is not one of them — on real HubSpot a label is RESOLVED from the
+  // association-type DEFINITION (`hubspot.associations.label_definitions`, unmodeled here). This
+  // pins the anti-invention property directly: a caller-supplied `label` must not come back.
+  done('hubspot.associations.spec_is_a_closed_two_key_shape', 'associations', 'A caller-supplied `label` on an AssociationSpec is NOT a request field and is never echoed back', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const c = await mk(h, 'contacts', { email: 'a@b.test' });
+      const co = await mk(h, 'companies', { name: 'Acme' });
+      const r = await h({ m: 'PUT', p: `/crm/v4/objects/contacts/${c}/associations/companies/${co}`, b: [{ associationCategory: 'USER_DEFINED', associationTypeId: 42, label: 'Decision maker' }] });
+      const g = await h({ m: 'GET', p: `/crm/v4/objects/contacts/${c}/associations/companies` });
+      const batch = await h({ m: 'POST', p: '/crm/v4/associations/contacts/companies/batch/create', b: { inputs: [{ from: { id: c }, to: { id: co }, types: [{ associationCategory: 'USER_DEFINED', associationTypeId: 43, label: 'Smuggled' }] }] } });
+      const flat = JSON.stringify([r.body, g.body, batch.body]);
+      // `labels` stays EMPTY (no definitions are modeled) and the smuggled string appears nowhere.
+      return r.status === 201 && Array.isArray(body(r).labels) && body(r).labels.length === 0
+        // `AssociationSpecWithLabel` declares `label?: string` — OPTIONAL, so an unlabeled
+        // association carries NO key at all. An explicit null would be an invented value.
+        && body(g).results[0].associationTypes.every((t: any) => !('label' in t))
+        && !flat.includes('Decision maker') && !flat.includes('Smuggled');
+    })),
+  done('hubspot.associations.category_set_is_closed', 'associations', 'Only the three documented AssociationSpec categories are accepted; anything else → 400', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const c = await mk(h, 'contacts', { email: 'a@b.test' });
+      const co = await mk(h, 'companies', { name: 'Acme' });
+      // The generated AssociationSpecAssociationCategoryEnum, spelled out as a literal here.
+      for (const associationCategory of ['HUBSPOT_DEFINED', 'USER_DEFINED', 'INTEGRATOR_DEFINED']) {
+        const r = await h({ m: 'PUT', p: `/crm/v4/objects/contacts/${c}/associations/companies/${co}`, b: [{ associationCategory, associationTypeId: 1 }] });
+        if (r.status !== 201) return false;
+      }
+      for (const associationCategory of ['CUSTOM', 'hubspot_defined', '']) {
+        const r = await h({ m: 'PUT', p: `/crm/v4/objects/contacts/${c}/associations/companies/${co}`, b: [{ associationCategory, associationTypeId: 1 }] });
+        if (r.status !== 400 || !isHubspotError(r, 'VALIDATION_ERROR')) return false;
+      }
+      const noId = await h({ m: 'PUT', p: `/crm/v4/objects/contacts/${c}/associations/companies/${co}`, b: [{ associationCategory: 'USER_DEFINED', associationTypeId: 'x' }] });
+      const empty = await h({ m: 'PUT', p: `/crm/v4/objects/contacts/${c}/associations/companies/${co}`, b: [] });
+      return noId.status === 400 && empty.status === 400;
+    })),
+  done('hubspot.associations.unknown_record_404', 'associations', 'Associating to or from a record that does not exist → 404 OBJECT_NOT_FOUND', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const c = await mk(h, 'contacts', { email: 'a@b.test' });
+      const noFrom = await h({ m: 'PUT', p: '/crm/v4/objects/contacts/424242/associations/default/companies/1' });
+      const noTo = await h({ m: 'PUT', p: `/crm/v4/objects/contacts/${c}/associations/default/companies/424242` });
+      return noFrom.status === 404 && noTo.status === 404 && isHubspotError(noTo, 'OBJECT_NOT_FOUND');
+    })),
+  done('hubspot.associations.archive', 'associations', 'DELETE an association — 204, and it is gone from BOTH directions', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const c = await mk(h, 'contacts', { email: 'a@b.test' });
+      const co = await mk(h, 'companies', { name: 'Acme' });
+      await h({ m: 'PUT', p: `/crm/v4/objects/contacts/${c}/associations/default/companies/${co}` });
+      const d = await h({ m: 'DELETE', p: `/crm/v4/objects/contacts/${c}/associations/companies/${co}` });
+      const forward = await h({ m: 'GET', p: `/crm/v4/objects/contacts/${c}/associations/companies` });
+      const back = await h({ m: 'GET', p: `/crm/v4/objects/companies/${co}/associations/contacts` });
+      return d.status === 204 && body(forward).results.length === 0 && body(back).results.length === 0;
+    })),
+  done('hubspot.associations.on_create', 'associations', 'The `associations` block on a create body associates the new record in the same call', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const co = await mk(h, 'companies', { name: 'Acme' });
+      const r = await h({ m: 'POST', p: '/crm/v3/objects/contacts', b: { properties: { email: 'a@b.test' }, associations: [{ to: { id: co }, types: [{ associationCategory: 'HUBSPOT_DEFINED', associationTypeId: 279 }] }] } });
+      if (r.status !== 201) return false;
+      const g = await h({ m: 'GET', p: `/crm/v4/objects/contacts/${body(r).id}/associations/companies` });
+      const bad = await h({ m: 'POST', p: '/crm/v3/objects/contacts', b: { properties: { email: 'c@d.test' }, associations: [{ to: { id: '424242' }, types: [{ associationCategory: 'HUBSPOT_DEFINED', associationTypeId: 279 }] }] } });
+      return body(g).results[0].toObjectId === co && bad.status === 404;
+    })),
+  done('hubspot.associations.rendered_on_get', 'associations', '?associations= renders the associated ids on a record read', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const c = await mk(h, 'contacts', { email: 'a@b.test' });
+      const co = await mk(h, 'companies', { name: 'Acme' });
+      await h({ m: 'PUT', p: `/crm/v4/objects/contacts/${c}/associations/default/companies/${co}` });
+      const g = await h({ m: 'GET', p: `/crm/v3/objects/contacts/${c}?associations=companies` });
+      const without = await h({ m: 'GET', p: `/crm/v3/objects/contacts/${c}` });
+      return body(g).associations.companies.results[0].id === co
+        && body(g).associations.companies.results[0].type === 'contact_to_company'
+        && body(without).associations === undefined;
+    })),
+  done('hubspot.associations.batch', 'associations', 'v4 batch create / read / archive over the association pair', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const c = await mk(h, 'contacts', { email: 'a@b.test' });
+      const co1 = await mk(h, 'companies', { name: 'Acme' });
+      const co2 = await mk(h, 'companies', { name: 'Globex' });
+      const create = await h({ m: 'POST', p: '/crm/v4/associations/contacts/companies/batch/create', b: { inputs: [
+        { from: { id: c }, to: { id: co1 }, types: [{ associationCategory: 'HUBSPOT_DEFINED', associationTypeId: 279 }] },
+        { from: { id: c }, to: { id: co2 }, types: [{ associationCategory: 'HUBSPOT_DEFINED', associationTypeId: 279 }] },
+      ] } });
+      if (create.status !== 201 || body(create).results.length !== 2) return false;
+      if (body(create).results[0].fromObjectTypeId !== '0-1' || body(create).results[0].toObjectTypeId !== '0-2') return false;
+      const read = await h({ m: 'POST', p: '/crm/v4/associations/contacts/companies/batch/read', b: { inputs: [{ id: c }] } });
+      if (body(read).results[0].to.length !== 2) return false;
+      const archive = await h({ m: 'POST', p: '/crm/v4/associations/contacts/companies/batch/archive', b: { inputs: [{ from: { id: c }, to: [{ id: co1 }] }] } });
+      const after = await h({ m: 'POST', p: '/crm/v4/associations/contacts/companies/batch/read', b: { inputs: [{ id: c }] } });
+      const bad = await h({ m: 'POST', p: '/crm/v4/associations/contacts/companies/batch/create', b: { inputs: [{ from: { id: c }, to: { id: co1 } }] } });
+      return archive.status === 204 && body(after).results[0].to.length === 1 && body(after).results[0].to[0].toObjectId === co2 && bad.status === 400;
+    })),
+  done('hubspot.associations.unmodeled_default_pair_refused', 'associations', 'A pair with no documented default type id is REFUSED rather than given a fabricated one', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const t = await mk(h, 'tickets', { subject: 'T' });
+      const co = await mk(h, 'companies', { name: 'Acme' });
+      const r = await h({ m: 'PUT', p: `/crm/v4/objects/tickets/${t}/associations/default/companies/${co}` });
+      // The twin has no source for a ticket→company default id, so it refuses instead of
+      // inventing one — the honest failure `hubspot.associations.default_pairs_beyond_the_eight`
+      // files as the gap.
+      return r.status === 400 && isHubspotError(r, 'VALIDATION_ERROR') && String(errOf(r).message).includes('standard CRM pairs');
+    })),
+  done('hubspot.associations.unmodeled_type_in_query_is_refused', 'associations', '?associations=<an unmodeled object type> is REFUSED, not silently dropped from the response', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const c = await mk(h, 'contacts', { email: 'a@b.test' });
+      const co = await mk(h, 'companies', { name: 'Acme' });
+      await h({ m: 'PUT', p: `/crm/v4/objects/contacts/${c}/associations/default/companies/${co}` });
+      // §9 round two: this used to answer 200 with the block simply absent — a silent partial
+      // success, where the PATH form of the same question is an honest 404.
+      const one = await h({ m: 'GET', p: `/crm/v3/objects/contacts/${c}?associations=notes` });
+      const listed = await h({ m: 'GET', p: '/crm/v3/objects/contacts?associations=notes' });
+      const nonsense = await h({ m: 'GET', p: `/crm/v3/objects/contacts/${c}?associations=wombats` });
+      const good = await h({ m: 'GET', p: `/crm/v3/objects/contacts/${c}?associations=companies` });
+      return one.status === 404 && String(errOf(one).message).includes('does not model')
+        && listed.status === 404
+        && nonsense.status === 400 && isHubspotError(nonsense, 'VALIDATION_ERROR')
+        && good.status === 200 && body(good).associations.companies.results[0].id === co;
+    })),
+  todo('hubspot.associations.default_pairs_beyond_the_eight', 'associations', 'HubSpot-defined default type ids for every standard pair (tickets↔companies, deals↔tickets, engagements↔…)', 'api', 'common'),
+  todo('hubspot.associations.label_definitions', 'associations', 'CRUD on /crm/v4/associations/{from}/{to}/labels — user-defined association labels', 'api', 'common'),
+  todo('hubspot.associations.schema_types', 'associations', 'GET /crm/v3/associations/{from}/{to}/types — the association type catalogue', 'api', 'common'),
+  todo('hubspot.associations.limits', 'associations', 'Association definition CONFIGURATIONS (per-pair cardinality limits) and their enforcement', 'api', 'niche'),
+  todo('hubspot.associations.paging', 'associations', 'paging.next.after on an association list with more than one page', 'api', 'common'),
+  todo('hubspot.associations.primary_type_ids', 'associations', 'The "primary" default variants (contact→primary company = 1, deal→primary company = 5)', 'api', 'common'),
+  todo('hubspot.associations.v3_batch_compat', 'associations', 'The legacy v3 /crm/v3/associations/{from}/{to}/batch/* endpoints', 'api', 'niche'),
+  todo('hubspot.associations.high_usage_report', 'associations', 'POST /crm/v4/associations/usage/high-usage-report/{userId}', 'api', 'niche'),
+
+  // ══ protocol fidelity ═══════════════════════════════════════════════════════════════════
+  done('hubspot.protocol.error_envelope', 'protocol', 'Errors carry { status:"error", message, correlationId, category } — and errors[] where the vendor does', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const notFound = await h({ m: 'GET', p: '/crm/v3/objects/contacts/424242' });
+      const validation = await h({ m: 'POST', p: '/crm/v3/objects/contacts', b: { properties: { email: { bad: 1 } } } });
+      const e = errOf(validation);
+      return isHubspotError(notFound, 'OBJECT_NOT_FOUND') && isHubspotError(validation, 'VALIDATION_ERROR')
+        && Array.isArray(e.errors) && typeof (e.errors![0] as any).message === 'string'
+        && typeof (e.errors![0] as any).code === 'string';
+    })),
+  done('hubspot.protocol.unmodeled_404', 'protocol', 'An unmodeled operation fails like the vendor (404), never a fake success', 'api', 'core', () =>
+    withRoot(async (h) => {
+      // Paths HubSpot has no route for at all. A WRONG METHOD on a routed path is deliberately
+      // NOT asserted here: HubSpot may answer 405 for it and the SDK gives no oracle either way,
+      // so claiming 404 would be inventing a refusal (`hubspot.protocol.method_not_allowed`).
+      const nonsense = await h({ m: 'GET', p: '/crm/v3/nonsense' });
+      const deep = await h({ m: 'GET', p: '/crm/v9/objects/contacts' });
+      const subresource = await h({ m: 'GET', p: '/crm/v3/objects/contacts/1/frobnicate' });
+      return nonsense.status === 404 && deep.status === 404 && subresource.status === 404
+        && isHubspotError(nonsense, 'OBJECT_NOT_FOUND');
+    })),
+  done('hubspot.protocol.read_only', 'protocol', 'A read-only twin serves reads and refuses every write with 405', 'api', 'common', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'hubspot-ro-'));
+    try {
+      const write = await handleHubspotTwinRequest({ method: 'POST', path: '/crm/v3/objects/contacts', body: '{}', root, readOnly: true });
+      const del = await handleHubspotTwinRequest({ method: 'DELETE', path: '/crm/v3/objects/contacts/1', root, readOnly: true });
+      const read = await handleHubspotTwinRequest({ method: 'GET', path: '/crm/v3/objects/contacts', root, readOnly: true });
+      return write.status === 405 && del.status === 405 && read.status === 200
+        && (write.body as any).category === 'TWIN_READ_ONLY';
+    } catch (err) { if (isInfrastructureError(err)) throw harnessError('hubspot.protocol.read_only', err); return false; } finally { rmSync(root, { recursive: true, force: true }); }
+  }),
+  done('hubspot.protocol.rate_limit_headers', 'protocol', 'Every response carries HubSpot\'s documented rate-limit POLICY headers', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const okRes = await h({ m: 'GET', p: '/crm/v3/objects/contacts' });
+      const errRes = await h({ m: 'GET', p: '/crm/v3/objects/contacts/424242' });
+      const created = await h({ m: 'POST', p: '/crm/v3/objects/contacts', b: { properties: { email: 'a@b.test' } } });
+      const del = await h({ m: 'DELETE', p: `/crm/v3/objects/contacts/${body(created).id}` });
+      const has = (r: HubspotResponse) => r.headers?.['x-hubspot-ratelimit-max'] === '190'
+        && r.headers?.['x-hubspot-ratelimit-interval-milliseconds'] === '10000'
+        && r.headers?.['x-hubspot-ratelimit-daily'] === '625000';
+      // …and NOT the two `-Remaining` counters: a local twin cannot report a truthful account-wide
+      // remaining count without wall-clock metering, and inventing one would break replayability.
+      const noCounters = (r: HubspotResponse) => r.headers?.['x-hubspot-ratelimit-remaining'] === undefined
+        && r.headers?.['x-hubspot-ratelimit-daily-remaining'] === undefined;
+      return [okRes, errRes, created, del].every((r) => has(r) && noCounters(r));
+    })),
+  done('hubspot.protocol.deterministic_correlation_id', 'protocol', 'Serve-path determinism: an identical request answers byte-identically, correlationId included', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const a = await h({ m: 'GET', p: '/crm/v3/objects/contacts/424242' });
+      const b2 = await h({ m: 'GET', p: '/crm/v3/objects/contacts/424242' });
+      const other = await h({ m: 'GET', p: '/crm/v3/objects/companies/424242' });
+      return JSON.stringify(a.body) === JSON.stringify(b2.body)
+        && errOf(a).correlationId !== errOf(other).correlationId; // derived from the request, not constant
+    })),
+  done('hubspot.protocol.reserved_field_round_trip', 'protocol', 'id / createdAt / updatedAt survive the projection (the kernel\'s META set drops all three)', 'api', 'core', () =>
+    withClock(async (h) => {
+      const c = await h({ m: 'POST', p: '/crm/v3/objects/contacts', b: { properties: { email: 'a@b.test' } }, at: '2026-02-01T00:00:00.000Z' });
+      const id = body(c).id;
+      await h({ m: 'PATCH', p: `/crm/v3/objects/contacts/${id}`, b: { properties: { firstname: 'Ada' } }, at: '2026-02-05T00:00:00.000Z' });
+      const g = await h({ m: 'GET', p: `/crm/v3/objects/contacts/${id}` });
+      const l = await h({ m: 'GET', p: '/crm/v3/objects/contacts' });
+      return body(g).id === id && body(g).createdAt === '2026-02-01T00:00:00.000Z' && body(g).updatedAt === '2026-02-05T00:00:00.000Z'
+        && body(l).results[0].createdAt === '2026-02-01T00:00:00.000Z';
+    })),
+  done('hubspot.protocol.invalid_json', 'protocol', 'A malformed or non-object JSON body → 400 VALIDATION_ERROR, never a 500', 'api', 'common', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'hubspot-json-'));
+    try {
+      const broken = await handleHubspotTwinRequest({ method: 'POST', path: '/crm/v3/objects/contacts', body: '{not json', root, occurredAt: AT });
+      const array = await handleHubspotTwinRequest({ method: 'POST', path: '/crm/v3/objects/contacts/batch/create', body: '[1,2]', root, occurredAt: AT });
+      return broken.status === 400 && (broken.body as any).category === 'VALIDATION_ERROR' && array.status === 400;
+    } catch (err) { if (isInfrastructureError(err)) throw harnessError('hubspot.protocol.invalid_json', err); return false; } finally { rmSync(root, { recursive: true, force: true }); }
+  }),
+  done('hubspot.protocol.collection_envelope', 'protocol', 'Collections are { results } with paging ONLY when another page exists', 'api', 'common', () =>
+    withRoot(async (h) => {
+      await mk(h, 'contacts', { email: 'a@b.test' });
+      const short = await h({ m: 'GET', p: '/crm/v3/objects/contacts?limit=10' });
+      await mk(h, 'contacts', { email: 'c@d.test' });
+      const paged = await h({ m: 'GET', p: '/crm/v3/objects/contacts?limit=1' });
+      return Array.isArray(body(short).results) && body(short).paging === undefined
+        && typeof body(paged).paging.next.after === 'string'
+        // …and NO fabricated `link`: HubSpot's is an absolute URL rooted at its public host, which
+        // a twin on an ephemeral loopback port does not know. Omitted rather than faked.
+        && body(paged).paging.next.link === undefined;
+    })),
+  // ── oauth: the install (hubspot-oauth.tsx) ──
+  done('hubspot.oauth.token_exchange', 'oauth', 'app.hubspot.com/oauth/authorize consents and redirects with a code; POST /oauth/v1/token redeems it once and refreshes', 'api', 'common', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'hubspot-cap-oauth-'));
+    try {
+      const at = () => AT;
+      const form = (fields: Record<string, string>) => new Request('https://api.hubapi.com/oauth/v1/token', { method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams(fields).toString() });
+      const page = await hubspotOAuth(new Request('https://app.hubspot.com/oauth/authorize?client_id=app1&redirect_uri=https%3A%2F%2Fapp.test%2Fcb&scope=oauth%20crm.objects.contacts.read&state=s1'), root, at);
+      const allowed = await hubspotOAuth(new Request('https://app.hubspot.com/oauth/authorize', { method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded' }, body: 'client_id=app1&redirect_uri=https%3A%2F%2Fapp.test%2Fcb&scope=oauth%20crm.objects.contacts.read&state=s1&answer=allow' }), root, at);
+      const location = new URL(allowed?.headers.get('location') ?? 'https://x.invalid');
+      const code = location.searchParams.get('code') ?? '';
+      const exchange = { grant_type: 'authorization_code', client_id: 'app1', client_secret: 's', redirect_uri: 'https://app.test/cb', code };
+      const first = await hubspotOAuth(form(exchange), root, at);
+      const tok = (await first?.json()) as { access_token?: string; refresh_token?: string; hub_id?: number; scopes?: string[]; expires_in?: number; token_type?: string };
+      const again = await hubspotOAuth(form(exchange), root, at);
+      const refreshed = await hubspotOAuth(form({ grant_type: 'refresh_token', client_id: 'app1', client_secret: 's', redirect_uri: 'https://app.test/cb', refresh_token: tok.refresh_token ?? '' }), root, at);
+      const badRefresh = await hubspotOAuth(form({ grant_type: 'refresh_token', client_id: 'app1', client_secret: 's', redirect_uri: 'https://app.test/cb', refresh_token: 'nope' }), root, at);
+      const denied = await hubspotOAuth(new Request('https://app.hubspot.com/oauth/authorize', { method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded' }, body: 'client_id=app1&redirect_uri=https%3A%2F%2Fapp.test%2Fcb&scope=oauth&answer=cancel' }), root, at);
+      // a code redeemed by another app, at another redirect, or after ten minutes is invalid_grant; another grant type too
+      const codeFor = async (): Promise<string> => new URL((await hubspotOAuth(new Request('https://app.hubspot.com/oauth/authorize', { method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded' }, body: 'client_id=app1&redirect_uri=https%3A%2F%2Fapp.test%2Fcb&scope=oauth&answer=allow' }), root, at))?.headers.get('location') ?? 'https://x.invalid').searchParams.get('code') ?? '';
+      const otherApp = await hubspotOAuth(form({ ...exchange, client_id: 'app2', code: await codeFor() }), root, at);
+      const otherRedirect = await hubspotOAuth(form({ ...exchange, redirect_uri: 'https://evil.test/cb', code: await codeFor() }), root, at);
+      const staleCode = await codeFor();
+      const late = await hubspotOAuth(form({ ...exchange, code: staleCode }), root, () => new Date(Date.parse(AT) + 11 * 60_000).toISOString());
+      const badGrant = await hubspotOAuth(form({ grant_type: 'password', client_id: 'app1' }), root, at);
+      const refreshedTok = refreshed ? ((await refreshed.clone().json()) as { access_token?: string; refresh_token?: string; hub_id?: number }) : {};
+      // the consent is HubSpot's app host's, not the API host's
+      const onApiHost = await hubspotOAuth(new Request('https://api.hubapi.com/oauth/authorize?client_id=app1&redirect_uri=https%3A%2F%2Fapp.test%2Fcb&scope=oauth'), root, at);
+      return page?.status === 200 && (await page.text()).includes('crm.objects.contacts.read')
+        && [otherApp, otherRedirect, late].every((r) => r?.status === 400) && badGrant?.status === 400
+        && ((await badGrant!.json()) as { error?: string }).error === 'unsupported_grant_type'
+        && !!refreshedTok.access_token && refreshedTok.access_token !== tok.access_token && refreshedTok.hub_id === TWIN_HUB_ID
+        && onApiHost === undefined
+        && allowed?.status === 302 && location.origin === 'https://app.test' && location.searchParams.get('state') === 's1' && !!code
+        && first?.status === 200 && tok.token_type === 'bearer' && tok.hub_id === TWIN_HUB_ID && tok.expires_in === 1800 && JSON.stringify(tok.scopes) === '["oauth","crm.objects.contacts.read"]' && !!tok.access_token && !!tok.refresh_token
+        && again?.status === 400 && ((await again.json()) as { error?: string }).error === 'invalid_grant'
+        && refreshed?.status === 200
+        && badRefresh?.status === 400 && ((await badRefresh.json()) as { status?: string }).status === 'BAD_REFRESH_TOKEN'
+        && new URL(denied?.headers.get('location') ?? 'https://x.invalid').searchParams.get('error') === 'access_denied';
+    } finally { rmSync(root, { recursive: true, force: true }); }
+  }),
+  done('hubspot.oauth.access_token_info', 'oauth', 'GET /oauth/v1/access-tokens/{token} — a minted token\'s metadata (hub id, scopes, expires_in)', 'api', 'common', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'hubspot-cap-oauth-info-'));
+    try {
+      const at = () => AT;
+      const allowed = await hubspotOAuth(new Request('https://app.hubspot.com/oauth/authorize', { method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded' }, body: 'client_id=app1&redirect_uri=https%3A%2F%2Fapp.test%2Fcb&scope=oauth&answer=allow' }), root, at);
+      const code = new URL(allowed?.headers.get('location') ?? 'https://x.invalid').searchParams.get('code') ?? '';
+      const tok = (await (await hubspotOAuth(new Request('https://api.hubapi.com/oauth/v1/token', { method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams({ grant_type: 'authorization_code', client_id: 'app1', client_secret: 's', redirect_uri: 'https://app.test/cb', code }).toString() }), root, at))?.json()) as { access_token: string };
+      const info = await hubspotOAuth(new Request(`https://api.hubapi.com/oauth/v1/access-tokens/${tok.access_token}`), root, at);
+      const meta = (await info?.json()) as { hub_id?: number; scopes?: string[]; token_type?: string; expires_in?: number };
+      const unknown = await hubspotOAuth(new Request('https://api.hubapi.com/oauth/v1/access-tokens/CNnope'), root, at);
+      // after its 1800 seconds the token has no metadata
+      const expired = await hubspotOAuth(new Request(`https://api.hubapi.com/oauth/v1/access-tokens/${tok.access_token}`), root, () => new Date(Date.parse(AT) + 1801_000).toISOString());
+      return expired?.status === 401 && info?.status === 200 && meta.hub_id === TWIN_HUB_ID && JSON.stringify(meta.scopes) === '["oauth"]' && meta.token_type === 'access' && meta.expires_in === 1800 && unknown?.status === 401;
+    } finally { rmSync(root, { recursive: true, force: true }); }
+  }),
+  done('hubspot.deferred.area_routes_refused', 'protocol', 'Every DEFERRED product area\'s routes are REFUSED in the vendor envelope, never faked', 'api', 'core', () =>
+    withRoot(async (h) => {
+      // One representative route per DEFERRED family (hubspot-areas.ts) — separate HubSpot
+      // PRODUCTS behind the same host. No /crm/ route appears here: §9 round one pointed out that
+      // probing /crm/v3/objects/notes made this capability "prove" the twin refuses part of its
+      // OWN declared scope. Those areas are plain todos, and
+      // `hubspot.objects.unmodeled_crm_object_types` covers their honest refusal instead.
+      // One representative route per DEFERRED area, KEYED BY AREA ID — and asserted to biject
+      // with the census, so adding a deferred area (or deleting one) reddens the capability whose
+      // title says "Every". §9 round two caught the hardcoded list making that word unenforceable,
+      // the same defect minor 9 had already fixed in `ui.nav`.
+      const routes: Record<string, [string, string]> = {
+        cms: ['GET', '/cms/v3/pages/site-pages'],
+        marketing: ['GET', '/marketing/v3/emails'],
+        automation: ['GET', '/automation/v4/actions/1'],
+        conversations: ['POST', '/conversations/v3/visitor-identification/tokens/create'],
+        files: ['GET', '/files/v3/files'],
+        'analytics-events': ['POST', '/events/v3/send'],
+        'communication-preferences': ['GET', '/communication-preferences/v3/definitions'],
+        settings: ['GET', '/settings/v3/users'],
+        webhooks: ['GET', '/webhooks/v3/1/subscriptions'],
+      };
+      const deferredAreas = HUBSPOT_AREAS.filter((x) => x.reason !== undefined).map((x) => x.id).sort();
+      if (JSON.stringify(deferredAreas) !== JSON.stringify(Object.keys(routes).sort())) return false;
+      for (const [m, p] of Object.values(routes)) {
+        const r = await h({ m, p });
+        // A 404 in HubSpot's own envelope, specifically — not "a 4xx of some kind".
+        if (r.status !== 404 || !isHubspotError(r, 'OBJECT_NOT_FOUND')) return false;
+      }
+      return true;
+    })),
+  // The other half of the refusal story: CRM object types HubSpot really HAS and this twin does
+  // not model. They must NOT borrow the vendor's "Unable to infer object type from" grammar —
+  // HubSpot infers `notes` perfectly well (the ahrefs precedent: only an option the endpoint
+  // actually declares can be an unmodeled option).
+  done('hubspot.objects.unmodeled_crm_object_types', 'objects', 'A real-but-unmodeled CRM object type is refused HONESTLY, not with the vendor\'s cannot-infer message', 'api', 'core', () =>
+    withRoot(async (h) => {
+      // All three spellings HubSpot accepts in a {objectType} segment. §9 round two caught the
+      // first version driving NAMES only — so `0-46` (notes) and a real custom-object spelling
+      // still got the vendor's cannot-infer sentence — and caught `p_custom_thing` being a
+      // fixture shaped like nothing the vendor emits (the real forms are the objectTypeId
+      // `2-3453932` and the fullyQualifiedName `p2953265_car`).
+      const spellings = [
+        'notes', 'tasks', 'calls', 'emails', 'meetings', 'line_items', 'products', 'quotes', 'invoices', 'leads',
+        '0-46', '0-27', '0-48', '0-7', '0-8',      // objectTypeId form
+        '2-3453932', 'p2953265_car',                // custom object: objectTypeId + fullyQualifiedName
+      ];
+      for (const type of spellings) {
+        const r = await h({ m: 'GET', p: `/crm/v3/objects/${type}` });
+        if (r.status !== 404 || !isHubspotError(r, 'OBJECT_NOT_FOUND')) return false;
+        const msg = String(errOf(r).message);
+        if (msg.includes('Unable to infer object type')) return false;   // not the vendor's words
+        if (!msg.includes(type) || !msg.includes('does not model')) return false;
+      }
+      // …while a segment that is not well-formed HubSpot addressing at all still gets the
+      // vendor's own 400, on every objectType-bearing route family.
+      for (const p of ['/crm/v3/objects/wombats', '/crm/v3/properties/wombats', '/crm/v3/pipelines/wombats']) {
+        const bad = await h({ m: 'GET', p });
+        if (bad.status !== 400 || !isHubspotError(bad, 'VALIDATION_ERROR') || !String(errOf(bad).message).startsWith('Unable to infer object type from: wombats')) return false;
+      }
+      // …and the honest refusal reaches the OTHER route families too, not just /objects.
+      for (const p of ['/crm/v3/properties/notes', '/crm/v3/pipelines/0-46', `/crm/v4/objects/notes/1/associations/contacts`]) {
+        const r = await h({ m: 'GET', p });
+        if (r.status !== 404 || !String(errOf(r).message).includes('does not model')) return false;
+      }
+      return true;
+    })),
+  todo('hubspot.protocol.paging_next_link', 'protocol', 'paging.next.link — the ABSOLUTE URL HubSpot returns alongside `after` (a twin on an ephemeral port does not know its own public host)', 'api', 'niche'),
+  todo('hubspot.protocol.method_not_allowed', 'protocol', 'A wrong METHOD on a routed path — 405 vs 404 (the SDK carries no oracle for this, so the twin asserts nothing about it today)', 'api', 'niche'),
+  todo('hubspot.protocol.rate_limit_remaining_headers', 'protocol', 'The X-HubSpot-RateLimit-Remaining / -Daily-Remaining COUNTERS (a truthful count needs wall-clock metering the serve path forbids)', 'api', 'common'),
+  todo('hubspot.protocol.rate_limit_429', 'protocol', 'A 429 with HubSpot\'s policyName ("DAILY" / "SECONDLY") body and the retry guidance', 'api', 'common'),
+  todo('hubspot.protocol.auth_401', 'protocol', 'A missing or malformed Bearer token → 401 with category INVALID_AUTHENTICATION', 'api', 'common'),
+  todo('hubspot.protocol.scope_403', 'protocol', 'A token without the required scope → 403 MISSING_SCOPES naming the scope', 'api', 'common'),
+  todo('hubspot.protocol.developer_api_key', 'protocol', 'The developer-API-key auth mode the SDK\'s `developerApiKey` option uses', 'api', 'niche'),
+  todo('hubspot.protocol.cors_and_preflight', 'protocol', 'CORS preflight behaviour for browser-side callers', 'api', 'niche'),
+
+  // ══ connector ═══════════════════════════════════════════════════════════════════════════
+  done('hubspot.connector.pull', 'connector', 'PULL contacts/companies/deals/tickets + owners into the observed log — idempotent', 'connector', 'core', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'hubspot-cap-pull-'));
+    try {
+      const { twinResources } = await import('@volter/world-core');
+      const { execute } = fakePortal();
+      const r1 = await syncHubspotFromReal(execute, { root, occurredAt: '2026-02-01T00:00:00.000Z' });
+      if (r1.observed !== 4 || r1.deltasAppended === 0) return false;
+      const before = twinResources('hubspot', root).length;
+      // A re-pull of IDENTICAL state must append nothing — but with a MOVING occurredAt, which
+      // is what the connector's own default does (a pinned one hides reverting-value bugs).
+      const r2 = await syncHubspotFromReal(execute, { root, occurredAt: '2026-02-01T00:05:00.000Z' });
+      const contact = twinResources('hubspot', root).find((x) => x.id === 'contacts_1001');
+      return r2.deltasAppended === 0 && !!contact && twinResources('hubspot', root).length === before;
+    } catch (err) { if (isInfrastructureError(err)) throw harnessError('hubspot.connector.pull', err); return false; } finally { rmSync(root, { recursive: true, force: true }); }
+  }),
+  done('hubspot.connector.pull_follows_paging', 'connector', 'PULL follows paging.next.after until it is absent, and every page lands', 'connector', 'core', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'hubspot-cap-page-'));
+    try {
+      const { execute, calls } = fakePortal();
+      await pullHubspotAll(execute, root);
+      const contactCalls = calls.filter((c) => c.includes('/crm/v3/objects/contacts'));
+      const page1 = await handleHubspotTwinRequest({ method: 'GET', path: '/crm/v3/objects/contacts/1001', root, occurredAt: AT });
+      const page2 = await handleHubspotTwinRequest({ method: 'GET', path: '/crm/v3/objects/contacts/1003', root, occurredAt: AT });
+      // …and every page ASKS FOR the properties it needs. HubSpot's list endpoints return only a
+      // small default set otherwise, so a pull that omitted `?properties=` would land near-empty
+      // records against a real portal while a generous fixture hid it (§9 round two: the fix had
+      // no pin at all).
+      const askedFor = contactCalls.every((c) => c.includes('properties=') && c.includes('email') && c.includes('lastmodifieddate'));
+      return contactCalls.length === 2 && contactCalls[1]!.includes('after=1003') && askedFor
+        && (page1.body as any).properties.email === 'p1@portal.test'
+        && (page2.body as any).properties.email === 'p2@portal.test';
+    } catch (err) { if (isInfrastructureError(err)) throw harnessError('hubspot.connector.pull_follows_paging', err); return false; } finally { rmSync(root, { recursive: true, force: true }); }
+  }),
+  done('hubspot.connector.pull_refuses_a_failure', 'connector', 'A REFUSED pull THROWS — it never folds an empty account over real observed state', 'connector', 'core', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'hubspot-cap-refuse-'));
+    try {
+      const { twinResources } = await import('@volter/world-core');
+      await pullHubspotAll(fakePortal().execute, root);
+      const before = twinResources('hubspot', root).filter((x) => (x as any).deleted !== true).length;
+      if (before === 0) return false;
+      // (a) a 4xx refusal
+      let threw = false;
+      try { await syncHubspotFromReal(fakePortal({ failOn: '/crm/v3/objects/companies' }).execute, { root }); } catch { threw = true; }
+      if (!threw) return false;
+      // (b) HubSpot's error envelope arriving with a 200 — a status check ALONE would miss it
+      let threw200 = false;
+      try { await syncHubspotFromReal(fakePortal({ failOn: '/crm/v3/objects/companies', httpStatus: 200 }).execute, { root }); } catch { threw200 = true; }
+      const after = twinResources('hubspot', root).filter((x) => (x as any).deleted !== true).length;
+      return threw200 && after === before;
+    } catch (err) { if (isInfrastructureError(err)) throw harnessError('hubspot.connector.pull_refuses_a_failure', err); return false; } finally { rmSync(root, { recursive: true, force: true }); }
+  }),
+  done('hubspot.connector.push', 'connector', 'PUSH confirms a pending local action on success and leaves it PENDING on an error', 'connector', 'core', async () => {
+    const { pendingActions } = await import('@volter/world-core');
+    // (a) an ERROR response must leave the action pending (no false confirm)
+    const r1 = mkdtempSync(join(tmpdir(), 'hubspot-cap-push-err-'));
+    try {
+      await handleHubspotTwinRequest({ method: 'POST', path: '/crm/v3/objects/contacts', body: JSON.stringify({ properties: { email: 'a@b.test' } }), root: r1, occurredAt: AT });
+      const errExec: HubspotExecute = async () => ({ httpStatus: 400, body: { status: 'error', message: 'nope', category: 'VALIDATION_ERROR' } });
+      if (await pushPendingHubspotActions(errExec, r1) !== 0) return false;
+      if (pendingActions('hubspot', r1).length === 0) return false;
+      // …and a 200 carrying an error envelope must ALSO not confirm.
+      const sneaky: HubspotExecute = async () => ({ httpStatus: 200, body: { status: 'error', message: 'nope', category: 'VALIDATION_ERROR' } });
+      if (await pushPendingHubspotActions(sneaky, r1) !== 0) return false;
+    } catch (err) { if (isInfrastructureError(err)) throw harnessError('hubspot.connector.push', err); return false; } finally { rmSync(r1, { recursive: true, force: true }); }
+    // (b) a SUCCESS response confirms the action and hits the right endpoint
+    const r2 = mkdtempSync(join(tmpdir(), 'hubspot-cap-push-ok-'));
+    try {
+      await handleHubspotTwinRequest({ method: 'POST', path: '/crm/v3/objects/contacts', body: JSON.stringify({ properties: { email: 'a@b.test' } }), root: r2, occurredAt: AT });
+      const calls: string[] = [];
+      const okExec: HubspotExecute = async (m, p, b) => { calls.push(`${m} ${p} ${JSON.stringify(b)}`); return { httpStatus: 201, body: { id: '999', properties: {} } }; };
+      const pushed = await pushPendingHubspotActions(okExec, r2);
+      return pushed > 0 && calls.some((c) => c.startsWith('POST /crm/v3/objects/contacts '))
+        && calls.some((c) => c.includes('"email":"a@b.test"') && !c.includes('hs_object_id'))
+        && pendingActions('hubspot', r2).length === 0;
+    } catch (err) { if (isInfrastructureError(err)) throw harnessError('hubspot.connector.push', err); return false; } finally { rmSync(r2, { recursive: true, force: true }); }
+  }),
+  done('hubspot.connector.push_never_addresses_a_local_id', 'connector', 'A LOCALLY MINTED record id is never sent at a real portal as a real record id', 'connector', 'core', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'hubspot-cap-push-mint-'));
+    try {
+      const { pendingActions } = await import('@volter/world-core');
+      // A locally created record, then locally updated and archived.
+      const c = await handleHubspotTwinRequest({ method: 'POST', path: '/crm/v3/objects/contacts', body: JSON.stringify({ properties: { email: 'a@b.test' } }), root, occurredAt: '2026-02-01T00:00:00.000Z' });
+      const id = (c.body as any).id;
+      await handleHubspotTwinRequest({ method: 'PATCH', path: `/crm/v3/objects/contacts/${id}`, body: JSON.stringify({ properties: { firstname: 'Ada' } }), root, occurredAt: '2026-02-02T00:00:00.000Z' });
+      await handleHubspotTwinRequest({ method: 'DELETE', path: `/crm/v3/objects/contacts/${id}`, root, occurredAt: '2026-02-03T00:00:00.000Z' });
+      const calls: string[] = [];
+      const exec: HubspotExecute = async (m, p) => { calls.push(`${m} ${p}`); return { httpStatus: 200, body: {} }; };
+      await pushPendingHubspotActions(exec, root);
+      // EVERY call must be a create; not one may address the twin's own id. Without the guard,
+      // the archive action would fire DELETE /crm/v3/objects/contacts/<local id> at a real
+      // portal — a stranger's record (the groq round-two defect class).
+      const leaked = calls.some((c) => c.includes(`/${id}`));
+      const everyCallIsACreate = calls.length > 0 && calls.every((c) => c === 'POST /crm/v3/objects/contacts');
+      // The unpushable archive must still be visible as pending, never silently dropped.
+      const stillPending = pendingActions('hubspot', root).length > 0;
+      const directly = hubspotRequestForAction({ id: 'x', subject: { type: 'crm_object', id: `contacts_${id}` }, fields: { objectType: 'contacts', hsId: id, hsLocalMint: true, archived: true } } as never);
+      return !leaked && everyCallIsACreate && stillPending && directly === null;
+    } catch (err) { if (isInfrastructureError(err)) throw harnessError('hubspot.connector.push_never_addresses_a_local_id', err); return false; } finally { rmSync(root, { recursive: true, force: true }); }
+  }),
+  done('hubspot.connector.push_addresses_a_pulled_id', 'connector', 'A record OBSERVED from the portal IS addressed by its real id on a later local edit', 'connector', 'common', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'hubspot-cap-push-pulled-'));
+    try {
+      await pullHubspotAll(fakePortal().execute, root);
+      await handleHubspotTwinRequest({ method: 'PATCH', path: '/crm/v3/objects/contacts/1001', body: JSON.stringify({ properties: { firstname: 'Edited' } }), root, occurredAt: '2026-02-09T00:00:00.000Z' });
+      const calls: string[] = [];
+      const exec: HubspotExecute = async (m, p) => { calls.push(`${m} ${p}`); return { httpStatus: 200, body: {} }; };
+      const pushed = await pushPendingHubspotActions(exec, root);
+      return pushed === 1 && calls.length === 1 && calls[0] === 'PATCH /crm/v3/objects/contacts/1001';
+    } catch (err) { if (isInfrastructureError(err)) throw harnessError('hubspot.connector.push_addresses_a_pulled_id', err); return false; } finally { rmSync(root, { recursive: true, force: true }); }
+  }),
+  done('hubspot.connector.map_renames_reserved_fields', 'connector', 'The pull mapping renames id/createdAt/updatedAt, which the kernel projection would otherwise DROP', 'connector', 'common', () => {
+    const mapped = mapCrmObject('contacts', { id: '1001', properties: { email: 'p@x.test' }, createdAt: AT, updatedAt: AT, archived: false });
+    const f = mapped.fields as Record<string, unknown>;
+    return mapped.type === 'crm_object' && mapped.id === 'contacts_1001'
+      && f.hsId === '1001' && f.hsCreatedAt === AT && f.hsUpdatedAt === AT && f.hsLocalMint === false
+      && (f as any).id === undefined && (f as any).updatedAt === undefined && (f as any).createdAt === undefined;
+  }),
+  todo('hubspot.connector.pull_properties', 'connector', 'Connector: pull the portal\'s property + property-group definitions (GET /crm/v3/properties/{objectType})', 'connector', 'common'),
+  todo('hubspot.connector.pull_pipelines', 'connector', 'Connector: pull the portal\'s real pipelines and stages (GET /crm/v3/pipelines/{objectType})', 'connector', 'common'),
+  todo('hubspot.connector.pull_associations', 'connector', 'Connector: pull existing associations between pulled records', 'connector', 'common'),
+  todo('hubspot.connector.push_associations', 'connector', 'Connector: push a locally created association once both records exist upstream', 'connector', 'common'),
+  todo('hubspot.connector.push_id_reconciliation', 'connector', 'Reconcile a locally minted id with the id the portal assigned on push, so later edits address the real record', 'connector', 'core'),
+  todo('hubspot.connector.pull_incremental', 'connector', 'Incremental pull by hs_lastmodifieddate instead of a full re-page', 'connector', 'common'),
+  todo('hubspot.connector.pull_archived', 'connector', 'Connector: observe archived records (?archived=true) so a remote archive lands locally', 'connector', 'niche'),
+
+  // ══ the CRM mirror ══════════════════════════════════════════════════════════════════════
+  // HubSpot's core job is done in the browser — a sales rep works a deal on the pipeline board —
+  // so this pack mirrors (docs/contributing/adding-a-twin.md, "Does this vendor get a mirror?"). Every UI
+  // capability is DATA-COUPLED: seed through the twin's write path, fetch the SAME vendor API the
+  // screen reads, render the mirror's OWN component, assert the seeded value survives.
+  done('hubspot.ui.contacts', 'ui', 'The contacts list renders real twin records (data-coupled)', 'ui', 'core',
+    uiDataCoupled<H, HubspotRow[]>({
+      withRoot,
+      seed: async (h) => {
+        await mk(h, 'contacts', { email: 'ada@lovelace.test', firstname: 'Ada', lastname: 'Lovelace' });
+        await mk(h, 'contacts', { email: 'bo@peep.test', firstname: 'Bo', lastname: 'Peep' });
+      },
+      fetch: async (h) => body(await h({ m: 'GET', p: '/crm/v3/objects/contacts?properties=email,firstname,lastname' })).results as HubspotRow[],
+      render: (rows) => renderToStaticMarkup(createElement(RecordsTable, { section: 'contacts', rows })),
+      assert: (rows, markup) => rows.length === 2 && !!markup
+        && (markup.match(/list-row/g) ?? []).length === 2
+        && markup.includes('Ada Lovelace') && markup.includes('ada@lovelace.test')
+        && rows.every((r) => markup.includes(String(r.id))),
+    })),
+  done('hubspot.ui.deals_board', 'ui', 'The deal pipeline board groups real deals by their dealstage (data-coupled)', 'ui', 'core',
+    uiDataCoupled<H, HubspotRow[]>({
+      withRoot,
+      seed: async (h) => {
+        await mk(h, 'deals', { dealname: 'Won Deal', amount: '5000', dealstage: 'closedwon' });
+        await mk(h, 'deals', { dealname: 'Open Deal', amount: '1250', dealstage: 'qualifiedtobuy' });
+        await mk(h, 'deals', { dealname: 'Lost Deal', amount: '90', dealstage: 'closedlost' });
+      },
+      fetch: async (h) => body(await h({ m: 'GET', p: '/crm/v3/objects/deals?properties=dealname,amount,dealstage' })).results as HubspotRow[],
+      render: (rows) => renderToStaticMarkup(createElement(DealBoard, { rows })),
+      assert: (rows, markup) => {
+        if (rows.length !== 3 || !markup) return false;
+        const groups = groupByStage(rows);
+        if (groups.length !== 3 || (markup.match(/deal-card/g) ?? []).length !== 3) return false;
+        // MEMBERSHIP, not just cardinality (§9 round one): slice the markup at each column's own
+        // `data-stage` landmark and require THAT column to carry the deal whose stage names it —
+        // and not the others. A board that rendered every card in one column passes a count check
+        // and fails this one.
+        const column = (stage: string): string => {
+          const at = markup.indexOf(`data-stage="${stage}"`);
+          if (at === -1) return '';
+          const next = markup.indexOf('data-stage="', at + 1);
+          return markup.slice(at, next === -1 ? markup.length : next);
+        };
+        const won = column('closedwon');
+        const open = column('qualifiedtobuy');
+        const lost = column('closedlost');
+        return won.includes('Won Deal') && !won.includes('Open Deal') && !won.includes('Lost Deal')
+          && open.includes('Open Deal') && !open.includes('Won Deal')
+          && lost.includes('Lost Deal') && !lost.includes('Won Deal')
+          // the mirror's own amount formatter, over the seeded values, in the right columns
+          && won.includes('$5,000') && open.includes('$1,250');
+      },
+    })),
+  done('hubspot.ui.stage_pill', 'ui', 'Deal-stage pills map closedwon/open/closedlost to ok/warn/bad tones (data-coupled)', 'ui', 'common',
+    uiDataCoupled<H, Record<string, string>>({
+      withRoot,
+      seed: async (h) => {
+        await mk(h, 'deals', { dealname: 'W', dealstage: 'closedwon' });
+        await mk(h, 'deals', { dealname: 'O', dealstage: 'presentationscheduled' });
+        await mk(h, 'deals', { dealname: 'L', dealstage: 'closedlost' });
+      },
+      fetch: async (h) => {
+        const rows = body(await h({ m: 'GET', p: '/crm/v3/objects/deals?properties=dealstage' })).results as HubspotRow[];
+        const stageOf = (want: string) => rows.find((r) => r.properties?.dealstage === want)?.properties?.dealstage;
+        // The mirror's OWN tone function, over values that came back through the twin's API.
+        return {
+          won: stageTone(stageOf('closedwon')),
+          open: stageTone(stageOf('presentationscheduled')),
+          lost: stageTone(stageOf('closedlost')),
+        };
+      },
+      // On an unseeded root every lookup is undefined ⇒ stageTone('') ⇒ '' ⇒ this is false.
+      assert: (tones) => tones.won === 'ok' && tones.open === 'warn' && tones.lost === 'bad',
+    })),
+  done('hubspot.ui.record_detail', 'ui', 'The record property sheet renders a real record\'s properties (data-coupled)', 'ui', 'common',
+    uiDataCoupled<H, HubspotRow[]>({
+      withRoot,
+      seed: (h) => mk(h, 'companies', { name: 'Acme Rocket Works', domain: 'acme.test', city: 'Portland' }),
+      fetch: async (h) => body(await h({ m: 'GET', p: '/crm/v3/objects/companies' })).results as HubspotRow[],
+      render: (rows) => renderToStaticMarkup(createElement(RecordDetail, { section: 'companies', rows })),
+      assert: (rows, markup) => rows.length === 1 && !!markup
+        && markup.includes('Acme Rocket Works') && markup.includes('acme.test') && markup.includes('Portland')
+        && markup.includes(recordTitle('companies', rows[0]!.properties))
+        && markup.includes(String(rows[0]!.id)),
+    })),
+  done('hubspot.ui.nav', 'ui', 'Every nav destination (Contacts / Companies / Deals / Tickets) reads live twin data (data-coupled)', 'ui', 'common',
+    uiDataCoupled<H, Record<string, boolean>>({
+      withRoot,
+      seed: async (h) => {
+        await mk(h, 'contacts', { email: 'nav-contact@x.test' });
+        await mk(h, 'companies', { name: 'Nav Company' });
+        await mk(h, 'deals', { dealname: 'Nav Deal' });
+        await mk(h, 'tickets', { subject: 'Nav Ticket' });
+      },
+      fetch: async (h) => {
+        // The nav's destinations are read FROM the mirror's own MIRROR_SECTIONS — the exact paths
+        // the client fetches — and each is driven for real. Reading the section list rather than
+        // re-typing it is what makes this a bijection: §9 round one noted the literal-only version
+        // stayed green if a section were DELETED from the nav, against a title that says "every".
+        const expected: Record<string, [string, string]> = {
+          contacts: ['email', 'nav-contact@x.test'],
+          companies: ['name', 'Nav Company'],
+          deals: ['dealname', 'Nav Deal'],
+          tickets: ['subject', 'Nav Ticket'],
+        };
+        const hits: Record<string, boolean> = {};
+        for (const section of MIRROR_SECTIONS) {
+          const pair = expected[section.key];
+          if (!pair) { hits[section.key] = false; continue; }
+          const rows = body(await h({ m: 'GET', p: section.path })).results as HubspotRow[];
+          hits[section.key] = rows.some((r) => r.properties?.[pair[0]] === pair[1]);
+        }
+        // the four destinations the product HAS must all be present in the shipped nav
+        hits.__bijection = Object.keys(expected).every((k) => MIRROR_SECTIONS.some((s) => s.key === k))
+          && MIRROR_SECTIONS.length === Object.keys(expected).length;
+        return hits;
+      },
+      assert: (hits) => hits.__bijection === true && ['contacts', 'companies', 'deals', 'tickets'].every((k) => hits[k] === true),
+    })),
+  done('hubspot.ui.empty_state', 'ui', 'An empty section renders the empty state — and gives way the moment a record exists', 'ui', 'niche', async () => {
+    const empty = renderToStaticMarkup(createElement(RecordsTable, { section: 'contacts', rows: [] }));
+    if (!empty.includes('No contacts yet.')) return false;
+    return withRoot(async (h) => {
+      await mk(h, 'contacts', { email: 'a@b.test', firstname: 'Ada' });
+      const rows = body(await h({ m: 'GET', p: '/crm/v3/objects/contacts' })).results as HubspotRow[];
+      const filled = renderToStaticMarkup(createElement(RecordsTable, { section: 'contacts', rows }));
+      return !filled.includes('No contacts yet.') && filled.includes('list-row') && filled.includes('Ada');
+    });
+  }),
+  done('hubspot.ui.mirror_write_path', 'ui', 'A UI write goes through the vendor\'s own endpoint on the mirror server, and a REVERTED value still lands', 'ui', 'core', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'hubspot-ui-write-'));
+    const server = await createHubspotMirrorServer({ root, port: 0 });
+    try {
+      const post = (path: string, b: unknown) => fetch(`${server.url}${path}`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(b) });
+      const patch = (path: string, b: unknown) => fetch(`${server.url}${path}`, { method: 'PATCH', headers: { 'content-type': 'application/json' }, body: JSON.stringify(b) });
+      // The mirror has NO write path of its own: this is the vendor's real endpoint, on the same
+      // handler the API serves.
+      const created = await post('/crm/v3/objects/deals', { properties: { dealname: 'D' } });
+      if (created.status !== 201) return false;
+      const id = ((await created.json()) as any).id;
+      // A GENUINE REVERT through the UI: X -> Y -> X. The kernel's action id is (content +
+      // occurredAt MILLISECOND), so the third write's content is byte-identical to the first's —
+      // and if the mirror server stamped a PINNED constant instead of the world clock, its
+      // timestamp would be identical too, the action would be swallowed as `replayed`, and the
+      // projection would still serve `closedlost` while the reply claimed otherwise.
+      // (A -> B -> C would NOT catch that: only a value the subject previously HELD collides.
+      // §9's revert matrix found the first version of this pin hollow for exactly that reason.)
+      for (const dealstage of ['closedwon', 'closedlost', 'closedwon']) {
+        const r = await patch(`/crm/v3/objects/deals/${id}`, { properties: { dealstage } });
+        if (r.status !== 200) return false;
+      }
+      const back = await fetch(`${server.url}/crm/v3/objects/deals/${id}`);
+      const seen = ((await back.json()) as any).properties.dealstage;
+      // …and the same value is what the API path serves, because there is only one of them.
+      const viaApi = await handleHubspotTwinRequest({ method: 'GET', path: `/crm/v3/objects/deals/${id}`, root, occurredAt: AT });
+      return seen === 'closedwon' && (viaApi.body as any).properties.dealstage === 'closedwon';
+    } catch (err) { if (isInfrastructureError(err)) throw harnessError('hubspot.ui.mirror_write_path', err); return false; } finally { server.stop(); rmSync(root, { recursive: true, force: true }); }
+  }),
+  todo('hubspot.ui.mirror_write_same_millisecond', 'ui', 'Two UI writes inside ONE millisecond still collide — worldNow() is not forced strictly increasing the way the connector\'s pollTimestamp() is', 'ui', 'niche'),
+  todo('hubspot.ui.record_timeline', 'ui', 'The activity timeline on a record (engagements — a deferred area)', 'ui', 'common'),
+  todo('hubspot.ui.board_drag_to_stage', 'ui', 'Dragging a deal card to another stage, writing back through PATCH /crm/v3/objects/deals/{id}', 'ui', 'core'),
+  todo('hubspot.ui.saved_views_and_filters', 'ui', 'Saved views, column selection and per-view filters on a record list', 'ui', 'common'),
+  todo('hubspot.ui.search_bar', 'ui', 'The global search bar backed by POST /crm/v3/objects/{objectType}/search', 'ui', 'common'),
+  todo('hubspot.ui.association_panel', 'ui', 'The associated-records panel on a record detail screen', 'ui', 'common'),
+  todo('hubspot.ui.inline_property_edit', 'ui', 'Inline property editing on the record sheet, writing through PATCH', 'ui', 'common'),
+  todo('hubspot.ui.pipeline_switcher', 'ui', 'Switching the board between pipelines', 'ui', 'niche'),
+  todo('hubspot.ui.bulk_actions', 'ui', 'Bulk select + bulk edit/delete backed by the batch endpoints', 'ui', 'niche'),
+
+  todo('hubspot.marketing.ai_content_assistant', 'marketing', 'Breeze / AI content assistant endpoints: the documented request/response envelope with a deterministic, labeled twin-stub result', 'api', 'niche'),
+
+  ...HUBSPOT_UNMODELED_CRM_CAPABILITIES,
+  ...HUBSPOT_DEFERRED_AREA_CAPABILITIES,
+];
+
+// The area census is asserted at module load so a stray or missing `area` is loud, not silent.
+assertAreaCensus('hubspot', HUBSPOT_AREA_IDS, HUBSPOT_CAPABILITIES);
+
+export async function hubspotCapabilities(): Promise<CapabilityReport> {
+  return checkCapabilities('hubspot', HUBSPOT_CAPABILITIES);
+}