@volter/twin-hubspot 0.1.0

package/src/hubspot-twin.ts

@@ -0,0 +1,1534 @@
+// HubSpot twin REQUEST HANDLER — the CRM v3/v4 API surface this twin models.
+// Contract: handleHubspotTwinRequest({ method, path, body }) -> { status, body, headers }.
+// Backed by the @volter/world-core event/action-log kernel; response SHAPES are taken from the
+// GENERATED types in `@hubspot/api-client` (lib/codegen/crm/**), which is the oracle here:
+// SimplePublicObject, SimplePublicObjectWithAssociations, CollectionResponse*ForwardPaging,
+// BatchResponseSimplePublicObject, Property, PropertyGroup, Pipeline, PipelineStage,
+// PublicOwner, LabelsBetweenObjectPair, MultiAssociatedObjectWithLabel — plus the documented
+// error envelope { status:'error', message, correlationId, category, errors? }.
+// HTTP wrapper: hubspot-server.ts -> createHubspotTwinServer.
+//
+// State lives in the action log (R18): writes are local actions, reads fold the projection.
+// No real HubSpot is ever called. Auth is a faked-locally Bearer private-app token; there is
+// no OAuth exchange and no signature verification.
+//
+// ── THREE FIDELITY NOTES THAT ARE EASY TO GET WRONG ───────────────────────────────────────
+//  1. The kernel's META set silently DROPS resource fields named `type`, `id` or `updatedAt`
+//     (control-plane/src/actions.ts). HubSpot's record carries ALL THREE of `id`/`createdAt`/
+//     `updatedAt`, so every stored record renames them (`hsId`, `hsCreatedAt`, `hsUpdatedAt`)
+//     and `renderObject` maps them back. A stored field literally named `id` would vanish with
+//     no error.
+//  2. `correlationId` is DERIVED, not random. Serve-path determinism (CLAUDE.md) requires a
+//     served response to be a pure function of (request, stored state) and byte-identical on
+//     replay, so the twin hashes (method, pathname, status, message) into a UUID-shaped id
+//     instead of minting entropy. Real HubSpot mints a fresh one per request; a twin that did
+//     the same would not be replayable.
+//  3. Record ids are minted as MAX(existing numeric id) + 1 over the WHOLE projection for that
+//     object type, archived rows included — never a row count. A count-mint reuses an archived
+//     record's id after a DELETE and silently clobbers it on the next create.
+//     The mint also starts from a NAMESPACED base far above HubSpot's own id range, which is what
+//     makes the OTHER collision direction impossible rather than merely unlikely: `max + 1` keeps
+//     a local id clear of every id a pull has ALREADY observed, but says nothing about a pull that
+//     arrives LATER — and `mapCrmObject` keys its subject as `<objectType>_<portal id>`, so a
+//     portal record numbered 1001 would fold straight onto a locally minted 1001, replacing its
+//     properties. datadog's `EVENT_ID_BASE` is the precedent (§9). `mapCrmObject` additionally
+//     stamps `hsLocalMint: false`, so if such a collision ever did occur the OBSERVED row wins the
+//     addressability question and later edits push as a PATCH rather than a duplicate CREATE.
+import { applyTwinWrite, projectResources } from '@volter/world-core';
+import { currentPortal, scopedId, TWIN_HUB_ID, unscoped } from './portal.ts';
+import { ownersOf } from './accounts.ts';
+import { announceWrite } from './webhooks.ts';
+import { createHash } from 'node:crypto';
+
+const SERVICE = 'hubspot';
+
+export type HubspotRequest = { method: string; path: string; body?: string; occurredAt?: string; root?: string; readOnly?: boolean };
+export type HubspotResponse = { status: number; body: unknown; headers?: Record<string, string> };
+
+// ── Rate-limit response headers ────────────────────────────────────────────────────────────
+// HubSpot documents X-HubSpot-RateLimit-Daily / -Daily-Remaining / -Interval-Milliseconds /
+// -Max / -Remaining on every response (developers.hubspot.com/docs/developer-tooling/platform/
+// usage-guidelines, read 2026-08-31). The twin serves the three POLICY headers with the
+// documented Professional-tier figures — 190 requests per 10 000 ms, 625 000 per day — and
+// deliberately does NOT serve the two `-Remaining` COUNTERS: a truthful remaining count is a
+// wall-clock-metered account-wide number that no local twin observes, and fabricating one would
+// break serve-path determinism (the same request would answer differently on replay) while
+// telling the caller a number that is not true. This is the figma precedent applied to a header
+// the vendor DOES document: publish what is a fact, refuse to invent what is not.
+// `hubspot.protocol.rate_limit_remaining_headers` carries that refusal as a filed todo.
+export const HUBSPOT_RATE_LIMIT_HEADERS: Readonly<Record<string, string>> = Object.freeze({
+  'x-hubspot-ratelimit-max': '190',
+  'x-hubspot-ratelimit-interval-milliseconds': '10000',
+  'x-hubspot-ratelimit-daily': '625000',
+});
+
+// ── Object types ───────────────────────────────────────────────────────────────────────────
+// The four standard CRM objects this twin models, with the numeric objectTypeIds HubSpot also
+// accepts in the {objectType} path segment.
+export const OBJECT_TYPES = ['contacts', 'companies', 'deals', 'tickets'] as const;
+export type ObjectType = (typeof OBJECT_TYPES)[number];
+const OBJECT_TYPE_IDS: Record<string, ObjectType> = {
+  '0-1': 'contacts', '0-2': 'companies', '0-3': 'deals', '0-5': 'tickets',
+};
+/** Singular form HubSpot uses in association payloads (`associations: { companies: … }` is
+ *  keyed plural, but `AssociatedId.type` reads `company`). */
+const SINGULAR: Record<ObjectType, string> = { contacts: 'contact', companies: 'company', deals: 'deal', tickets: 'ticket' };
+
+/** The numeric objectTypeId HubSpot reports for each modeled type — what `LabelsBetweenObjectPair`
+ *  and friends carry in their `fromObjectTypeId`/`toObjectTypeId` fields (NOT the plural name). */
+const OBJECT_TYPE_ID: Record<ObjectType, string> = { contacts: '0-1', companies: '0-2', deals: '0-3', tickets: '0-5' };
+
+/**
+ * CRM object types HubSpot really has and this twin does NOT model — the engagement, commerce and
+ * activity families, taken from @hubspot/api-client's own discovery tree (every `{objectType}`
+ * path segment under `lib/codegen/crm/**`, minus the four modeled here).
+ *
+ * These must be refused DIFFERENTLY from a type nobody has. HubSpot answers `GET /crm/v3/objects/
+ * wombats` with `Unable to infer object type from: wombats` because it genuinely cannot resolve
+ * it — but it resolves `notes` perfectly well, so borrowing that message here would be putting a
+ * vendor sentence in the vendor's mouth about a type the vendor knows. This is the ahrefs
+ * precedent (`ahrefs-twin.ts`: only an option the endpoint actually DECLARES can be an unmodeled
+ * option). A real-but-unmodeled type gets an honest 404 that says the twin does not model it —
+ * a refusal, never a fabricated success.
+ */
+const KNOWN_UNMODELED_OBJECT_TYPES = new Set([
+  'calls', 'communications', 'emails', 'feedback_submissions', 'goal_targets', 'invoices',
+  'leads', 'line_items', 'meetings', 'notes', 'postal_mail', 'products', 'quotes', 'taxes', 'tasks',
+]);
+
+/**
+ * The two NON-NAME spellings HubSpot accepts in a `{objectType}` segment, as GRAMMARS rather than
+ * as an enumerated id table — because enumerating them would mean writing down numeric ids this
+ * repo has no first-party source for, which is the invention the honest-refusal rule exists to
+ * stop. §9 round two caught the first version matching names only, so `/crm/v3/objects/0-46`
+ * (notes) and `/crm/v3/objects/p2953265_car` (a custom object) still received the vendor's
+ * cannot-infer sentence — the alternate spellings of exactly the types the fix was written for.
+ *
+ *   • `objectTypeId`        — `<n>-<m>`, e.g. `0-46`, `2-3453932` (the shape `ObjectSchema
+ *                             .objectTypeId` carries).
+ *   • `fullyQualifiedName`  — `p<portalId>_<name>`, e.g. `p2953265_car`.
+ *
+ * A segment matching either is WELL-FORMED HubSpot addressing, so the twin says it does not model
+ * it rather than pretending it cannot parse it.
+ */
+const OBJECT_TYPE_ID_FORM = /^\d+-\d+$/;
+const FULLY_QUALIFIED_NAME_FORM = /^p\d+_[a-z0-9_]+$/i;
+
+/** Refuse an {objectType} segment: honestly for a type HubSpot has or could have, in the vendor's
+ *  own grammar only for one it genuinely cannot resolve. */
+function refuseObjectType(ctx: ErrorContext, raw: string): HubspotResponse {
+  const lower = raw.toLowerCase();
+  const wellFormed = KNOWN_UNMODELED_OBJECT_TYPES.has(lower)
+    || OBJECT_TYPE_ID_FORM.test(lower)
+    || FULLY_QUALIFIED_NAME_FORM.test(lower);
+  if (wellFormed) {
+    return fail(ctx, 404, 'OBJECT_NOT_FOUND', `this twin models the contacts, companies, deals and tickets object types; it does not model '${raw}'`);
+  }
+  return fail(ctx, 400, 'VALIDATION_ERROR', `Unable to infer object type from: ${raw}`);
+}
+
+/** Resolve a {objectType} path segment to a modeled object type, or null. */
+export function resolveObjectType(raw: string): ObjectType | null {
+  const lower = raw.toLowerCase();
+  if ((OBJECT_TYPES as readonly string[]).includes(lower)) return lower as ObjectType;
+  return OBJECT_TYPE_IDS[lower] ?? null;
+}
+
+// The `lastmodifieddate` system property differs on contacts (HubSpot's oldest object) from
+// every other CRM object, which use `hs_lastmodifieddate`.
+const LAST_MODIFIED_PROP: Record<ObjectType, string> = {
+  contacts: 'lastmodifieddate', companies: 'hs_lastmodifieddate', deals: 'hs_lastmodifieddate', tickets: 'hs_lastmodifieddate',
+};
+
+// HubSpot-defined properties this twin seeds per object type. `type`/`fieldType` are the
+// generated PropertyCreateTypeEnum / PropertyCreateFieldTypeEnum vocabulary.
+type SeedProp = { name: string; label: string; type: string; fieldType: string; groupName: string };
+const DEFAULT_PROPERTIES: Record<ObjectType, SeedProp[]> = {
+  contacts: [
+    { name: 'email', label: 'Email', type: 'string', fieldType: 'text', groupName: 'contactinformation' },
+    { name: 'firstname', label: 'First Name', type: 'string', fieldType: 'text', groupName: 'contactinformation' },
+    { name: 'lastname', label: 'Last Name', type: 'string', fieldType: 'text', groupName: 'contactinformation' },
+    { name: 'phone', label: 'Phone Number', type: 'string', fieldType: 'phonenumber', groupName: 'contactinformation' },
+    { name: 'company', label: 'Company Name', type: 'string', fieldType: 'text', groupName: 'contactinformation' },
+    { name: 'lifecyclestage', label: 'Lifecycle Stage', type: 'enumeration', fieldType: 'radio', groupName: 'contactinformation' },
+    { name: 'hubspot_owner_id', label: 'Contact owner', type: 'enumeration', fieldType: 'select', groupName: 'contactinformation' },
+    { name: 'createdate', label: 'Create Date', type: 'datetime', fieldType: 'date', groupName: 'contactinformation' },
+    { name: 'lastmodifieddate', label: 'Last Modified Date', type: 'datetime', fieldType: 'date', groupName: 'contactinformation' },
+    { name: 'hs_object_id', label: 'Record ID', type: 'number', fieldType: 'number', groupName: 'contactinformation' },
+  ],
+  companies: [
+    { name: 'name', label: 'Name', type: 'string', fieldType: 'text', groupName: 'companyinformation' },
+    { name: 'domain', label: 'Company Domain Name', type: 'string', fieldType: 'text', groupName: 'companyinformation' },
+    { name: 'city', label: 'City', type: 'string', fieldType: 'text', groupName: 'companyinformation' },
+    { name: 'industry', label: 'Industry', type: 'enumeration', fieldType: 'select', groupName: 'companyinformation' },
+    { name: 'phone', label: 'Phone Number', type: 'string', fieldType: 'phonenumber', groupName: 'companyinformation' },
+    { name: 'hubspot_owner_id', label: 'Company owner', type: 'enumeration', fieldType: 'select', groupName: 'companyinformation' },
+    { name: 'createdate', label: 'Create Date', type: 'datetime', fieldType: 'date', groupName: 'companyinformation' },
+    { name: 'hs_lastmodifieddate', label: 'Last Modified Date', type: 'datetime', fieldType: 'date', groupName: 'companyinformation' },
+    { name: 'hs_object_id', label: 'Record ID', type: 'number', fieldType: 'number', groupName: 'companyinformation' },
+  ],
+  deals: [
+    { name: 'dealname', label: 'Deal Name', type: 'string', fieldType: 'text', groupName: 'dealinformation' },
+    { name: 'amount', label: 'Amount', type: 'number', fieldType: 'number', groupName: 'dealinformation' },
+    { name: 'dealstage', label: 'Deal Stage', type: 'enumeration', fieldType: 'radio', groupName: 'dealinformation' },
+    { name: 'pipeline', label: 'Pipeline', type: 'enumeration', fieldType: 'radio', groupName: 'dealinformation' },
+    { name: 'closedate', label: 'Close Date', type: 'datetime', fieldType: 'date', groupName: 'dealinformation' },
+    { name: 'hubspot_owner_id', label: 'Deal owner', type: 'enumeration', fieldType: 'select', groupName: 'dealinformation' },
+    { name: 'createdate', label: 'Create Date', type: 'datetime', fieldType: 'date', groupName: 'dealinformation' },
+    { name: 'hs_lastmodifieddate', label: 'Last Modified Date', type: 'datetime', fieldType: 'date', groupName: 'dealinformation' },
+    { name: 'hs_object_id', label: 'Record ID', type: 'number', fieldType: 'number', groupName: 'dealinformation' },
+  ],
+  tickets: [
+    { name: 'subject', label: 'Ticket name', type: 'string', fieldType: 'text', groupName: 'ticketinformation' },
+    { name: 'content', label: 'Ticket description', type: 'string', fieldType: 'textarea', groupName: 'ticketinformation' },
+    { name: 'hs_pipeline', label: 'Pipeline', type: 'enumeration', fieldType: 'select', groupName: 'ticketinformation' },
+    { name: 'hs_pipeline_stage', label: 'Ticket status', type: 'enumeration', fieldType: 'select', groupName: 'ticketinformation' },
+    { name: 'hs_ticket_priority', label: 'Priority', type: 'enumeration', fieldType: 'select', groupName: 'ticketinformation' },
+    { name: 'hubspot_owner_id', label: 'Ticket owner', type: 'enumeration', fieldType: 'select', groupName: 'ticketinformation' },
+    { name: 'createdate', label: 'Create Date', type: 'datetime', fieldType: 'date', groupName: 'ticketinformation' },
+    { name: 'hs_lastmodifieddate', label: 'Last Modified Date', type: 'datetime', fieldType: 'date', groupName: 'ticketinformation' },
+    { name: 'hs_object_id', label: 'Record ID', type: 'number', fieldType: 'number', groupName: 'ticketinformation' },
+  ],
+};
+
+const DEFAULT_PROPERTY_GROUPS: Record<ObjectType, { name: string; label: string; displayOrder: number }[]> = {
+  contacts: [{ name: 'contactinformation', label: 'Contact information', displayOrder: -1 }],
+  companies: [{ name: 'companyinformation', label: 'Company information', displayOrder: -1 }],
+  deals: [{ name: 'dealinformation', label: 'Deal information', displayOrder: -1 }],
+  tickets: [{ name: 'ticketinformation', label: 'Ticket information', displayOrder: -1 }],
+};
+
+// HubSpot's out-of-the-box deal + ticket pipelines. Only these two object types have pipelines.
+const PIPELINE_OBJECT_TYPES = new Set<ObjectType>(['deals', 'tickets']);
+type SeedStage = { id: string; label: string; displayOrder: number; metadata: Record<string, string> };
+const DEFAULT_PIPELINES: Record<string, { id: string; label: string; displayOrder: number; stages: SeedStage[] }> = {
+  deals: {
+    id: 'default', label: 'Sales Pipeline', displayOrder: 0,
+    stages: [
+      { id: 'appointmentscheduled', label: 'Appointment Scheduled', displayOrder: 0, metadata: { isClosed: 'false', probability: '0.2' } },
+      { id: 'qualifiedtobuy', label: 'Qualified To Buy', displayOrder: 1, metadata: { isClosed: 'false', probability: '0.4' } },
+      { id: 'presentationscheduled', label: 'Presentation Scheduled', displayOrder: 2, metadata: { isClosed: 'false', probability: '0.6' } },
+      { id: 'decisionmakerboughtin', label: 'Decision Maker Bought-In', displayOrder: 3, metadata: { isClosed: 'false', probability: '0.8' } },
+      { id: 'contractsent', label: 'Contract Sent', displayOrder: 4, metadata: { isClosed: 'false', probability: '0.9' } },
+      { id: 'closedwon', label: 'Closed Won', displayOrder: 5, metadata: { isClosed: 'true', probability: '1.0' } },
+      { id: 'closedlost', label: 'Closed Lost', displayOrder: 6, metadata: { isClosed: 'true', probability: '0.0' } },
+    ],
+  },
+  tickets: {
+    id: '0', label: 'Support Pipeline', displayOrder: 0,
+    stages: [
+      { id: '1', label: 'New', displayOrder: 0, metadata: { isClosed: 'false', ticketState: 'OPEN' } },
+      { id: '2', label: 'Waiting on contact', displayOrder: 1, metadata: { isClosed: 'false', ticketState: 'OPEN' } },
+      { id: '3', label: 'Waiting on us', displayOrder: 2, metadata: { isClosed: 'false', ticketState: 'OPEN' } },
+      { id: '4', label: 'Closed', displayOrder: 3, metadata: { isClosed: 'true', ticketState: 'CLOSED' } },
+    ],
+  },
+};
+
+// The portal's seeded owner — HubSpot's GET /crm/v3/owners.
+const SEED_OWNER = {
+  id: '1', email: 'owner@hubspot.twin', firstName: 'Twin', lastName: 'Owner',
+  userId: 1, userIdIncludingInactive: 1, type: 'PERSON', archived: false,
+  teams: [{ id: '1', name: 'Twin Team', primary: true }],
+};
+
+// HubSpot-defined DEFAULT association type ids, from the associations v4 reference
+// (developers.hubspot.com/docs/guides/api/crm/associations/associations-v4, read 2026-08-31).
+// Only the pairs this table names have a modeled default; every other pair is refused rather
+// than given a fabricated id (`hubspot.associations.create_default_unmodeled_pair`).
+const DEFAULT_ASSOCIATION_TYPE_IDS: Record<string, number> = {
+  'contacts>companies': 279, 'companies>contacts': 280,
+  'deals>contacts': 3, 'contacts>deals': 4,
+  'deals>companies': 341, 'companies>deals': 342,
+  'contacts>tickets': 15, 'tickets>contacts': 16,
+};
+
+// The pinned timestamp a twin write stamps onto a record when the caller supplies none. Kept
+// fixed so a fresh-root create is byte-identical on replay (serve-path determinism).
+const EPOCH = '2026-01-01T00:00:00.000Z';
+
+/**
+ * The floor this twin mints record ids from — NAMESPACED out of HubSpot's own range.
+ *
+ * HubSpot record ids are opaque numeric strings; the largest this repo has observed in the wild
+ * are ~2.7e10 (`26879063901`-shaped), and contact ids in particular are routinely in the low
+ * thousands. 9e11 is more than an order of magnitude above the largest of those and far below
+ * `Number.MAX_SAFE_INTEGER`, so a locally minted id and a real portal id cannot meet — in EITHER
+ * direction. See header note 3.
+ */
+export const HUBSPOT_LOCAL_ID_BASE = 900_000_000_000;
+
+// The closed FilterOperatorEnum from @hubspot/api-client's generated
+// crm/objects/models/Filter.d.ts. A literal allowlist, deliberately NOT derived from anything
+// the handler itself serves — an operator outside this set is a 400, and the bijection between
+// this constant and the generated enum is what makes that refusal an oracle rather than a
+// tautology (§6, "closed parameter set").
+export const SEARCH_FILTER_OPERATORS = [
+  'EQ', 'NEQ', 'LT', 'LTE', 'GT', 'GTE', 'BETWEEN', 'IN', 'NOT_IN',
+  'HAS_PROPERTY', 'NOT_HAS_PROPERTY', 'CONTAINS_TOKEN', 'NOT_CONTAINS_TOKEN',
+] as const;
+const OPERATOR_SET = new Set<string>(SEARCH_FILTER_OPERATORS);
+
+/** Documented caps. List: 100/page. Search: 200/page, 10 000 total results, 5 filterGroups of
+ *  6 filters (18 filters overall). All from HubSpot's own reference pages, read 2026-08-31. */
+export const LIST_LIMIT_MAX = 100;
+export const SEARCH_LIMIT_MAX = 200;
+export const SEARCH_RESULT_CAP = 10_000;
+export const SEARCH_MAX_FILTER_GROUPS = 5;
+export const SEARCH_MAX_FILTERS_PER_GROUP = 6;
+export const SEARCH_MAX_FILTERS_TOTAL = 18;
+
+// ── envelope ───────────────────────────────────────────────────────────────────────────────
+type ErrorDetail = { message: string; code?: string; context?: Record<string, string[]> };
+
+/** A DETERMINISTIC correlation id (see note 2 in the header). Shaped like the UUID real
+ *  HubSpot returns, derived from the request + outcome so a replay is byte-identical. */
+export function correlationIdFor(seed: string): string {
+  const h = createHash('sha256').update(seed).digest('hex');
+  return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20, 32)}`;
+}
+
+function ok(data: unknown, status = 200): HubspotResponse {
+  return { status, body: data, headers: { ...HUBSPOT_RATE_LIMIT_HEADERS } };
+}
+function noContent(): HubspotResponse {
+  return { status: 204, body: null, headers: { ...HUBSPOT_RATE_LIMIT_HEADERS } };
+}
+
+export type ErrorContext = { method: string; pathname: string };
+
+function fail(ctx: ErrorContext, status: number, category: string, message: string, errors?: ErrorDetail[]): HubspotResponse {
+  const correlationId = correlationIdFor(`${ctx.method} ${ctx.pathname} ${status} ${category} ${message}`);
+  return {
+    status,
+    body: { status: 'error', message, correlationId, category, ...(errors && errors.length ? { errors } : {}) },
+    headers: { ...HUBSPOT_RATE_LIMIT_HEADERS },
+  };
+}
+
+// ── kernel access ──────────────────────────────────────────────────────────────────────────
+// Every subject of these types belongs to one account (portal.ts): read in the request's account, its id as that account
+// sees it; written under the account.
+/** Every stored subject of a type in the request's account, tombstones included, ids as the account sees them. */
+function rowsAll(type: string, root?: string): Record<string, unknown>[] {
+  const hub = currentPortal().hub;
+  const out: Record<string, unknown>[] = [];
+  for (const r of projectResources(SERVICE, root) as unknown as Record<string, unknown>[]) {
+    if (r.type !== type) continue;
+    const u = unscoped(String(r.id ?? ''));
+    if (u.hub === hub) out.push({ ...r, id: u.id });
+  }
+  return out;
+}
+function rows(type: string, root?: string): Record<string, unknown>[] {
+  return rowsAll(type, root).filter((r) => r.deleted !== true);
+}
+function byId(type: string, id: string, root?: string): Record<string, unknown> | undefined {
+  return rows(type, root).find((r) => (r as { id: string }).id === id);
+}
+async function write(type: string, id: string, fields: Record<string, unknown>, root?: string, occurredAt?: string): Promise<void> {
+  await applyTwinWrite(SERVICE, { operation: `set.${type}`, subjectType: type, subjectId: scopedId(currentPortal().hub, id), fields, ...(occurredAt ? { occurredAt } : {}), actor: { kind: 'agent' } }, root);
+}
+
+/**
+ * Parse a request body. An ARRAY is a legitimate top-level body on HubSpot's v4 association
+ * endpoints (`PUT …/associations/{toObjectType}/{toObjectId}` takes `AssociationSpec[]`, per
+ * @hubspot/api-client's generated `BasicApi.create`), so arrays are accepted and handed on; a
+ * route that expected an object simply finds its required keys absent and answers its own 400.
+ * Only genuinely malformed JSON, or a scalar, is refused here.
+ */
+function parseBody(body?: string): { ok: true; value: Record<string, unknown> } | { ok: false } {
+  if (!body) return { ok: true, value: {} };
+  try {
+    const parsed = JSON.parse(body) as unknown;
+    if (parsed === null || typeof parsed !== 'object') return { ok: false };
+    return { ok: true, value: parsed as Record<string, unknown> };
+  } catch { return { ok: false }; }
+}
+
+// ── record ids ─────────────────────────────────────────────────────────────────────────────
+/** Kernel subject id for a CRM record. Namespaced by object type so `contacts` 1 and `deals` 1
+ *  are distinct subjects even though the kernel already resolves by (type, id). */
+function recordKey(objectType: ObjectType, id: string): string {
+  return `${objectType}_${id}`;
+}
+
+/**
+ * Mint the next record id: MAX over the numeric ids ALREADY IN STATE for this object type + 1,
+ * archived and tombstoned rows included (see header note 3). Never a count — a count reuses an
+ * archived id and collides with any larger id a connector pull observed.
+ */
+function nextRecordId(objectType: ObjectType, root?: string): string {
+  const prefix = `${objectType}_`;
+  let max = HUBSPOT_LOCAL_ID_BASE;
+  for (const r of rowsAll('crm_object', root)) {
+    const id = String(r.id ?? '');
+    if (!id.startsWith(prefix)) continue;
+    const n = Number(id.slice(prefix.length));
+    if (Number.isFinite(n) && n > max) max = n;
+  }
+  return String(max + 1);
+}
+
+// ── record rendering ───────────────────────────────────────────────────────────────────────
+type StoredRecord = {
+  id: string; objectType: ObjectType; hsId: string; hsCreatedAt: string; hsUpdatedAt: string;
+  archived: boolean; hsArchivedAt?: string; props: Record<string, string | null>;
+  /** True when THIS twin minted the record's id locally. A pulled record has no such stamp, so
+   *  the connector can tell an id that addresses a real portal record from one that addresses
+   *  nothing at all — see hubspot-connector.ts, `hubspotRequestForAction`. */
+  hsLocalMint: boolean;
+};
+
+function readRecord(objectType: ObjectType, id: string, root?: string): StoredRecord | undefined {
+  const r = byId('crm_object', recordKey(objectType, id), root);
+  if (!r) return undefined;
+  return {
+    id: String(r.id), objectType,
+    hsId: String(r.hsId), hsCreatedAt: String(r.hsCreatedAt), hsUpdatedAt: String(r.hsUpdatedAt),
+    archived: r.archived === true, ...(r.hsArchivedAt ? { hsArchivedAt: String(r.hsArchivedAt) } : {}),
+    props: (r.props ?? {}) as Record<string, string | null>,
+    hsLocalMint: r.hsLocalMint === true,
+  };
+}
+
+function allRecords(objectType: ObjectType, root?: string): StoredRecord[] {
+  const prefix = `${objectType}_`;
+  return rows('crm_object', root)
+    .filter((r) => String(r.id ?? '').startsWith(prefix) && r.objectType === objectType)
+    .map((r) => ({
+      id: String(r.id), objectType,
+      hsId: String(r.hsId), hsCreatedAt: String(r.hsCreatedAt), hsUpdatedAt: String(r.hsUpdatedAt),
+      archived: r.archived === true, ...(r.hsArchivedAt ? { hsArchivedAt: String(r.hsArchivedAt) } : {}),
+      props: (r.props ?? {}) as Record<string, string | null>,
+      hsLocalMint: r.hsLocalMint === true,
+    }))
+    .sort((a, b) => Number(a.hsId) - Number(b.hsId));
+}
+
+/** SimplePublicObject / SimplePublicObjectWithAssociations, per the generated models. */
+function renderObject(rec: StoredRecord, opts: { properties?: string[]; associations?: string[]; root?: string }, unresolved: string[] = []): Record<string, unknown> {
+  const properties: Record<string, string | null> = {};
+  const requested = opts.properties;
+  const always = ['hs_object_id', 'createdate', LAST_MODIFIED_PROP[rec.objectType]];
+  const keys = requested && requested.length
+    ? [...new Set([...always, ...requested])]
+    : Object.keys(rec.props);
+  for (const k of keys) properties[k] = rec.props[k] ?? null;
+  const out: Record<string, unknown> = {
+    id: rec.hsId,
+    properties,
+    createdAt: rec.hsCreatedAt,
+    updatedAt: rec.hsUpdatedAt,
+    archived: rec.archived,
+    ...(rec.archived && rec.hsArchivedAt ? { archivedAt: rec.hsArchivedAt } : {}),
+  };
+  if (opts.associations && opts.associations.length) {
+    const associations: Record<string, { results: { id: string; type: string }[] }> = {};
+    for (const raw of opts.associations) {
+      const to = resolveObjectType(raw);
+      // An unmodeled type here used to be skipped, which made `?associations=notes` a SILENT
+      // partial success — a 200 whose associations block simply lacked what was asked for, where
+      // the path form `…/associations/notes` is an honest 404 (§9 round two). The caller is told
+      // instead; `renderObject`'s caller turns this into the same refusal.
+      if (!to) { unresolved.push(raw); continue; }
+      const results = readAssociations(rec.objectType, rec.hsId, to, opts.root)
+        .map((a) => ({ id: a.toId, type: `${SINGULAR[rec.objectType]}_to_${SINGULAR[to]}` }));
+      if (results.length) associations[to] = { results };
+    }
+    if (Object.keys(associations).length) out.associations = associations;
+  }
+  return out;
+}
+
+// ── properties + groups ────────────────────────────────────────────────────────────────────
+type StoredProperty = SeedProp & { description: string; displayOrder: number; hidden: boolean; hubspotDefined: boolean; formField: boolean; options: unknown[]; calculated: boolean; externalOptions: boolean; hasUniqueValue: boolean; archived: boolean };
+
+function seededProperties(objectType: ObjectType): StoredProperty[] {
+  return DEFAULT_PROPERTIES[objectType].map((p) => ({
+    ...p, description: '', displayOrder: -1, hidden: false, hubspotDefined: true, formField: false,
+    options: [], calculated: false, externalOptions: false, hasUniqueValue: p.name === 'hs_object_id', archived: false,
+  }));
+}
+
+function propertyKey(objectType: ObjectType, name: string): string { return `${objectType}_${name}`; }
+
+/** All properties for an object type: the seeded HubSpot-defined ones overlaid with any the
+ *  caller created/updated/archived through the twin's own write path. */
+function listProperties(objectType: ObjectType, root?: string): StoredProperty[] {
+  const merged = new Map<string, StoredProperty>();
+  for (const p of seededProperties(objectType)) merged.set(p.name, p);
+  const prefix = `${objectType}_`;
+  for (const r of rows('property', root)) {
+    const id = String(r.id ?? '');
+    if (!id.startsWith(prefix) || r.objectType !== objectType) continue;
+    const name = String(r.name);
+    const base = merged.get(name);
+    merged.set(name, {
+      ...(base ?? { name, label: name, type: 'string', fieldType: 'text', groupName: '', description: '', displayOrder: -1, hidden: false, hubspotDefined: false, formField: false, options: [], calculated: false, externalOptions: false, hasUniqueValue: false, archived: false }),
+      ...(r.label !== undefined ? { label: String(r.label) } : {}),
+      ...(r.type !== undefined ? { type: String(r.propType ?? r.type) } : {}),
+      ...(r.propType !== undefined ? { type: String(r.propType) } : {}),
+      ...(r.fieldType !== undefined ? { fieldType: String(r.fieldType) } : {}),
+      ...(r.groupName !== undefined ? { groupName: String(r.groupName) } : {}),
+      ...(r.description !== undefined ? { description: String(r.description) } : {}),
+      ...(r.options !== undefined ? { options: r.options as unknown[] } : {}),
+      ...(r.formField !== undefined ? { formField: r.formField === true } : {}),
+      ...(r.hasUniqueValue !== undefined ? { hasUniqueValue: r.hasUniqueValue === true } : {}),
+      hubspotDefined: base?.hubspotDefined ?? false,
+      archived: r.archived === true,
+    });
+  }
+  return [...merged.values()];
+}
+
+function renderProperty(p: StoredProperty): Record<string, unknown> {
+  return {
+    name: p.name, label: p.label, type: p.type, fieldType: p.fieldType, groupName: p.groupName,
+    description: p.description, options: p.options, displayOrder: p.displayOrder, hidden: p.hidden,
+    hubspotDefined: p.hubspotDefined, formField: p.formField, calculated: p.calculated,
+    externalOptions: p.externalOptions, hasUniqueValue: p.hasUniqueValue, archived: p.archived,
+  };
+}
+
+type StoredGroup = { name: string; label: string; displayOrder: number; archived: boolean };
+function listPropertyGroups(objectType: ObjectType, root?: string): StoredGroup[] {
+  const merged = new Map<string, StoredGroup>();
+  for (const g of DEFAULT_PROPERTY_GROUPS[objectType]) merged.set(g.name, { ...g, archived: false });
+  const prefix = `${objectType}_`;
+  for (const r of rows('property_group', root)) {
+    const id = String(r.id ?? '');
+    if (!id.startsWith(prefix) || r.objectType !== objectType) continue;
+    const name = String(r.name);
+    const base = merged.get(name);
+    merged.set(name, {
+      name,
+      label: r.label !== undefined ? String(r.label) : (base?.label ?? name),
+      displayOrder: r.displayOrder !== undefined ? Number(r.displayOrder) : (base?.displayOrder ?? -1),
+      archived: r.archived === true,
+    });
+  }
+  return [...merged.values()];
+}
+
+// ── pipelines ──────────────────────────────────────────────────────────────────────────────
+type StoredPipeline = {
+  id: string; label: string; displayOrder: number; archived: boolean; stages: SeedStage[];
+  createdAt: string; updatedAt: string;
+  /** A MONOTONIC stage-id counter, persisted with the pipeline. It only ever increases, so a
+   *  stage id is never reused after a stage is removed — the same rule record ids follow, and
+   *  the reason `nextStageId` cannot simply scan the surviving stage ids (a delete would take
+   *  its id out of the set and the next add would silently take the deleted stage's place). */
+  stageSeq: number;
+};
+
+function pipelineKey(objectType: ObjectType, id: string): string { return `${objectType}_${id}`; }
+
+function listPipelines(objectType: ObjectType, root?: string): StoredPipeline[] {
+  const merged = new Map<string, StoredPipeline>();
+  const seed = DEFAULT_PIPELINES[objectType];
+  if (seed) merged.set(seed.id, { ...seed, archived: false, createdAt: EPOCH, updatedAt: EPOCH, stageSeq: 0, stages: seed.stages.map((s) => ({ ...s })) });
+  const prefix = `${objectType}_`;
+  for (const r of rows('pipeline', root)) {
+    const id = String(r.id ?? '');
+    if (!id.startsWith(prefix) || r.objectType !== objectType) continue;
+    const pid = String(r.pipelineId);
+    const base = merged.get(pid);
+    merged.set(pid, {
+      id: pid,
+      label: r.label !== undefined ? String(r.label) : (base?.label ?? pid),
+      displayOrder: r.displayOrder !== undefined ? Number(r.displayOrder) : (base?.displayOrder ?? 0),
+      archived: r.archived === true,
+      stages: (r.stages as SeedStage[] | undefined) ?? base?.stages ?? [],
+      createdAt: base?.createdAt ?? String(r.hsCreatedAt ?? EPOCH),
+      updatedAt: String(r.hsUpdatedAt ?? base?.updatedAt ?? EPOCH),
+      stageSeq: r.stageSeq !== undefined ? Number(r.stageSeq) : (base?.stageSeq ?? 0),
+    });
+  }
+  return [...merged.values()].filter((p) => !p.archived);
+}
+
+function renderPipeline(p: StoredPipeline): Record<string, unknown> {
+  return {
+    id: p.id, label: p.label, displayOrder: p.displayOrder, archived: p.archived,
+    createdAt: p.createdAt, updatedAt: p.updatedAt,
+    stages: p.stages.map((s) => renderStage(s, p)),
+  };
+}
+function renderStage(s: SeedStage, p: StoredPipeline): Record<string, unknown> {
+  return { id: s.id, label: s.label, displayOrder: s.displayOrder, metadata: s.metadata, archived: false, createdAt: p.createdAt, updatedAt: p.updatedAt, writePermissions: 'CRM_PERMISSIONS_ENFORCEMENT' };
+}
+
+// ── associations ───────────────────────────────────────────────────────────────────────────
+// `AssociationSpecWithLabel` declares `'label'?: string` — OPTIONAL, not nullable. The vendor
+// OMITS the key for an unlabeled association, so the twin stores no label and renders no key.
+// (§9 round two: the first fix removed an invented REQUEST field and pinned an invented RESPONSE
+// value — an explicit `label: null` — in the same stroke.)
+type StoredAssociation = { fromType: ObjectType; fromId: string; toType: ObjectType; toId: string; labels: { associationCategory: string; associationTypeId: number }[] };
+
+function associationKey(fromType: ObjectType, fromId: string, toType: ObjectType, toId: string): string {
+  return `${fromType}:${fromId}>${toType}:${toId}`;
+}
+
+function readAssociations(fromType: ObjectType, fromId: string, toType: ObjectType, root?: string): StoredAssociation[] {
+  return rows('association', root)
+    .filter((r) => r.fromType === fromType && r.fromId === fromId && r.toType === toType)
+    .map((r) => ({
+      fromType, fromId, toType, toId: String(r.toId),
+      labels: (r.labels as StoredAssociation['labels'] | undefined) ?? [],
+    }))
+    .sort((a, b) => Number(a.toId) - Number(b.toId));
+}
+
+// ── search ─────────────────────────────────────────────────────────────────────────────────
+type Filter = { propertyName: string; operator: string; value?: string; values?: string[]; highValue?: string };
+
+function matchesFilter(rec: StoredRecord, f: Filter): boolean {
+  const raw = rec.props[f.propertyName];
+  const present = raw !== undefined && raw !== null && raw !== '';
+  switch (f.operator) {
+    case 'HAS_PROPERTY': return present;
+    case 'NOT_HAS_PROPERTY': return !present;
+    case 'EQ': return present && String(raw) === String(f.value);
+    case 'NEQ': return !present || String(raw) !== String(f.value);
+    case 'LT': return present && numOr(raw) < numOr(f.value);
+    case 'LTE': return present && numOr(raw) <= numOr(f.value);
+    case 'GT': return present && numOr(raw) > numOr(f.value);
+    case 'GTE': return present && numOr(raw) >= numOr(f.value);
+    case 'BETWEEN': return present && numOr(raw) >= numOr(f.value) && numOr(raw) <= numOr(f.highValue);
+    case 'IN': return present && (f.values ?? []).map(String).includes(String(raw));
+    case 'NOT_IN': return !present || !(f.values ?? []).map(String).includes(String(raw));
+    case 'CONTAINS_TOKEN': return present && tokenMatch(String(raw), String(f.value ?? ''));
+    case 'NOT_CONTAINS_TOKEN': return !present || !tokenMatch(String(raw), String(f.value ?? ''));
+    default: return false;
+  }
+}
+function numOr(v: unknown): number {
+  const n = Number(v);
+  return Number.isFinite(n) ? n : Number.NaN;
+}
+/** HubSpot's CONTAINS_TOKEN is a tokenized match with an optional trailing `*` wildcard. */
+function tokenMatch(haystack: string, needle: string): boolean {
+  const tokens = haystack.toLowerCase().split(/[^a-z0-9]+/i).filter(Boolean);
+  const want = needle.toLowerCase();
+  if (want.endsWith('*')) {
+    const stem = want.slice(0, -1);
+    return tokens.some((t) => t.startsWith(stem));
+  }
+  return tokens.includes(want);
+}
+
+// ── the handler ────────────────────────────────────────────────────────────────────────────
+export async function handleHubspotTwinRequest(req: HubspotRequest): Promise<HubspotResponse> {
+  const { method, root, occurredAt } = req;
+  const readOnly = req.readOnly ?? false;
+  const isWrite = method !== 'GET' && method !== 'HEAD';
+  const at = occurredAt ?? EPOCH;
+
+  let url: URL;
+  try { url = new URL(req.path, 'http://twin.local'); } catch { return fail({ method, pathname: req.path }, 400, 'VALIDATION_ERROR', 'invalid request path'); }
+  const ctx: ErrorContext = { method, pathname: url.pathname };
+  const parts = url.pathname.replace(/^\/+|\/+$/g, '').split('/').filter(Boolean);
+  const query = url.searchParams;
+
+  if (readOnly && isWrite) {
+    // NOT a HubSpot category — the twin's own read-only refusal, named so a reader can never
+    // mistake it for one of the vendor's documented categories.
+    return fail(ctx, 405, 'TWIN_READ_ONLY', 'this twin was started read-only; omit readOnly to accept writes');
+  }
+
+  const parsed = parseBody(req.body);
+  if (!parsed.ok) return fail(ctx, 400, 'VALIDATION_ERROR', 'Invalid input JSON');
+  const body = parsed.value;
+
+  // ── /crm/v3/objects/... ──────────────────────────────────────────────────────────────────
+  if (parts[0] === 'crm' && parts[1] === 'v3' && parts[2] === 'objects') {
+    const rawType = parts[3];
+    if (rawType === undefined) return notFound(ctx);
+    const objectType = resolveObjectType(rawType);
+    if (!objectType) return refuseObjectType(ctx, rawType);
+
+    // POST /crm/v3/objects/{objectType}
+    if (method === 'POST' && parts.length === 4) return createRecord(ctx, objectType, body, root, at);
+    // GET /crm/v3/objects/{objectType}
+    if (method === 'GET' && parts.length === 4) return listRecords(ctx, objectType, query, root);
+    // POST /crm/v3/objects/{objectType}/search
+    if (method === 'POST' && parts.length === 5 && parts[4] === 'search') return searchRecords(ctx, objectType, body, root);
+    // POST /crm/v3/objects/{objectType}/merge
+    if (method === 'POST' && parts.length === 5 && parts[4] === 'merge') return mergeRecords(ctx, objectType, body, root, at);
+    // POST /crm/v3/objects/{objectType}/batch/{op}
+    if (method === 'POST' && parts.length === 6 && parts[4] === 'batch') return batchOp(ctx, objectType, parts[5]!, body, root, at);
+    // /crm/v3/objects/{objectType}/{objectId}
+    if (parts.length === 5) {
+      const id = parts[4]!;
+      if (method === 'GET') return getRecord(ctx, objectType, id, query, root);
+      if (method === 'PATCH') return updateRecord(ctx, objectType, id, body, root, at);
+      if (method === 'DELETE') return archiveRecord(ctx, objectType, id, root, at);
+    }
+    return notFound(ctx);
+  }
+
+  // ── /crm/v3/properties/{objectType}... ───────────────────────────────────────────────────
+  if (parts[0] === 'crm' && parts[1] === 'v3' && parts[2] === 'properties') {
+    const rawType = parts[3];
+    if (rawType === undefined) return notFound(ctx);
+    const objectType = resolveObjectType(rawType);
+    if (!objectType) return refuseObjectType(ctx, rawType);
+
+    // groups FIRST: /properties/{objectType}/groups collides with /{propertyName}
+    if (parts[4] === 'groups') {
+      if (method === 'GET' && parts.length === 5) return ok({ results: listPropertyGroups(objectType, root).filter((g) => !g.archived).map((g) => ({ name: g.name, label: g.label, displayOrder: g.displayOrder, archived: g.archived })) });
+      if (method === 'POST' && parts.length === 5) return createPropertyGroup(ctx, objectType, body, root, at);
+      if (parts.length === 6) {
+        const name = parts[5]!;
+        const found = listPropertyGroups(objectType, root).find((g) => g.name === name && !g.archived);
+        if (method === 'GET') {
+          if (!found) return fail(ctx, 404, 'OBJECT_NOT_FOUND', `Group ${name} not found`);
+          return ok({ name: found.name, label: found.label, displayOrder: found.displayOrder, archived: found.archived });
+        }
+        if (method === 'PATCH') {
+          if (!found) return fail(ctx, 404, 'OBJECT_NOT_FOUND', `Group ${name} not found`);
+          const patch: Record<string, unknown> = { objectType, name };
+          if (body.label !== undefined) patch.label = body.label;
+          if (body.displayOrder !== undefined) patch.displayOrder = body.displayOrder;
+          await write('property_group', `${objectType}_${name}`, patch, root, at);
+          const after = listPropertyGroups(objectType, root).find((g) => g.name === name)!;
+          return ok({ name: after.name, label: after.label, displayOrder: after.displayOrder, archived: after.archived });
+        }
+        if (method === 'DELETE') {
+          if (!found) return fail(ctx, 404, 'OBJECT_NOT_FOUND', `Group ${name} not found`);
+          await write('property_group', `${objectType}_${name}`, { objectType, name, archived: true }, root, at);
+          return noContent();
+        }
+      }
+      return notFound(ctx);
+    }
+
+    if (method === 'GET' && parts.length === 4) return ok({ results: listProperties(objectType, root).filter((p) => !p.archived).map(renderProperty) });
+    // POST /crm/v3/properties/{objectType}/batch/create — "Create a batch of properties": each of `inputs` created as
+    // POST /crm/v3/properties/{objectType} creates one, answered in the batch envelope the record batches use
+    if (method === 'POST' && parts.length === 6 && parts[4] === 'batch' && parts[5] === 'create') {
+      const inputs = Array.isArray(body.inputs) ? (body.inputs as Record<string, unknown>[]) : null;
+      if (inputs === null) return fail(ctx, 400, 'VALIDATION_ERROR', 'inputs must be an array');
+      // every input is checked before any is created, so a refused batch changes nothing (the twin's decision: the
+      // reference does not say whether a batch is all-or-nothing, and a refusal that left writes behind would lie)
+      const seen = new Set<string>();
+      for (const input of inputs) {
+        const refused = propertyRefusal(ctx, objectType, input, root);
+        if (refused) return refused;
+        if (seen.has(String(input.name))) return fail(ctx, 409, 'CONFLICT', `Property ${String(input.name)} already exists`);
+        seen.add(String(input.name));
+      }
+      const results: unknown[] = [];
+      for (const input of inputs) {
+        const created = await createProperty(ctx, objectType, input, root, at);
+        if (created.status !== 201) return created;
+        results.push(created.body);
+      }
+      return ok(batchEnvelope(results, at), 201);
+    }
+    if (method === 'POST' && parts.length === 4) return createProperty(ctx, objectType, body, root, at);
+    if (parts.length === 5) {
+      const name = parts[4]!;
+      const found = listProperties(objectType, root).find((p) => p.name === name && !p.archived);
+      if (method === 'GET') {
+        if (!found) return fail(ctx, 404, 'OBJECT_NOT_FOUND', `Property ${name} not found`);
+        return ok(renderProperty(found));
+      }
+      if (method === 'PATCH') {
+        if (!found) return fail(ctx, 404, 'OBJECT_NOT_FOUND', `Property ${name} not found`);
+        const patch: Record<string, unknown> = { objectType, name };
+        for (const k of ['label', 'description', 'groupName', 'fieldType', 'options'] as const) if (body[k] !== undefined) patch[k] = body[k];
+        if (body.type !== undefined) patch.propType = body.type; // `type` is a kernel META key
+        await write('property', propertyKey(objectType, name), patch, root, at);
+        return ok(renderProperty(listProperties(objectType, root).find((p) => p.name === name)!));
+      }
+      if (method === 'DELETE') {
+        if (!found) return fail(ctx, 404, 'OBJECT_NOT_FOUND', `Property ${name} not found`);
+        await write('property', propertyKey(objectType, name), { objectType, name, archived: true }, root, at);
+        return noContent();
+      }
+    }
+    return notFound(ctx);
+  }
+
+  // ── /crm/v3/pipelines/{objectType}... ────────────────────────────────────────────────────
+  if (parts[0] === 'crm' && parts[1] === 'v3' && parts[2] === 'pipelines') {
+    const rawType = parts[3];
+    if (rawType === undefined) return notFound(ctx);
+    const objectType = resolveObjectType(rawType);
+    if (!objectType) return refuseObjectType(ctx, rawType);
+    if (!PIPELINE_OBJECT_TYPES.has(objectType)) return fail(ctx, 400, 'VALIDATION_ERROR', `Object type ${objectType} does not support pipelines`);
+
+    if (method === 'GET' && parts.length === 4) return ok({ results: listPipelines(objectType, root).map(renderPipeline) });
+    if (method === 'POST' && parts.length === 4) return createPipeline(ctx, objectType, body, root, at);
+    if (parts.length >= 5) {
+      const pipelineId = parts[4]!;
+      const pipeline = listPipelines(objectType, root).find((p) => p.id === pipelineId);
+      if (parts.length === 5) {
+        if (method === 'GET') {
+          if (!pipeline) return fail(ctx, 404, 'OBJECT_NOT_FOUND', `Pipeline ${pipelineId} not found`);
+          return ok(renderPipeline(pipeline));
+        }
+        if (method === 'PATCH' || method === 'PUT') {
+          if (!pipeline) return fail(ctx, 404, 'OBJECT_NOT_FOUND', `Pipeline ${pipelineId} not found`);
+          if (method === 'PUT' && (body.label === undefined || body.displayOrder === undefined || !Array.isArray(body.stages))) {
+            return fail(ctx, 400, 'VALIDATION_ERROR', 'label, displayOrder and stages are required to replace a pipeline');
+          }
+          const patch: Record<string, unknown> = { objectType, pipelineId, hsUpdatedAt: at };
+          if (body.label !== undefined) patch.label = body.label;
+          if (body.displayOrder !== undefined) patch.displayOrder = body.displayOrder;
+          if (Array.isArray(body.stages)) {
+            const staged = normalizeStages(body.stages as Record<string, unknown>[], pipeline.stageSeq);
+            if ('error' in staged) return fail(ctx, 400, 'VALIDATION_ERROR', staged.error);
+            patch.stages = staged.stages;
+            patch.stageSeq = staged.seq;
+          }
+          await write('pipeline', pipelineKey(objectType, pipelineId), patch, root, at);
+          return ok(renderPipeline(listPipelines(objectType, root).find((p) => p.id === pipelineId)!));
+        }
+        if (method === 'DELETE') {
+          if (!pipeline) return fail(ctx, 404, 'OBJECT_NOT_FOUND', `Pipeline ${pipelineId} not found`);
+          await write('pipeline', pipelineKey(objectType, pipelineId), { objectType, pipelineId, archived: true, hsUpdatedAt: at }, root, at);
+          return noContent();
+        }
+      }
+      if (parts[5] === 'stages') {
+        if (!pipeline) return fail(ctx, 404, 'OBJECT_NOT_FOUND', `Pipeline ${pipelineId} not found`);
+        if (method === 'GET' && parts.length === 6) return ok({ results: pipeline.stages.map((s) => renderStage(s, pipeline)) });
+        if (method === 'POST' && parts.length === 6) {
+          if (body.label === undefined || body.displayOrder === undefined) return fail(ctx, 400, 'VALIDATION_ERROR', 'label and displayOrder are required');
+          const seq = pipeline.stageSeq + 1;
+          const stage: SeedStage = { id: `stage_${seq}`, label: String(body.label), displayOrder: Number(body.displayOrder), metadata: (body.metadata as Record<string, string> | undefined) ?? {} };
+          await write('pipeline', pipelineKey(objectType, pipelineId), { objectType, pipelineId, label: pipeline.label, displayOrder: pipeline.displayOrder, stages: [...pipeline.stages, stage], stageSeq: seq, hsUpdatedAt: at }, root, at);
+          return ok(renderStage(stage, pipeline), 201);
+        }
+        if (parts.length === 7) {
+          const stageId = parts[6]!;
+          const stage = pipeline.stages.find((s) => s.id === stageId);
+          if (method === 'GET') {
+            if (!stage) return fail(ctx, 404, 'OBJECT_NOT_FOUND', `Stage ${stageId} not found`);
+            return ok(renderStage(stage, pipeline));
+          }
+          if (method === 'PATCH' || method === 'PUT') {
+            if (!stage) return fail(ctx, 404, 'OBJECT_NOT_FOUND', `Stage ${stageId} not found`);
+            if (method === 'PUT' && (body.label === undefined || body.displayOrder === undefined)) return fail(ctx, 400, 'VALIDATION_ERROR', 'label and displayOrder are required to replace a stage');
+            const updated: SeedStage = {
+              id: stage.id,
+              label: body.label !== undefined ? String(body.label) : stage.label,
+              displayOrder: body.displayOrder !== undefined ? Number(body.displayOrder) : stage.displayOrder,
+              metadata: (body.metadata as Record<string, string> | undefined) ?? stage.metadata,
+            };
+            await write('pipeline', pipelineKey(objectType, pipelineId), { objectType, pipelineId, label: pipeline.label, displayOrder: pipeline.displayOrder, stages: pipeline.stages.map((s) => (s.id === stageId ? updated : s)), stageSeq: pipeline.stageSeq, hsUpdatedAt: at }, root, at);
+            return ok(renderStage(updated, pipeline));
+          }
+          if (method === 'DELETE') {
+            if (!stage) return fail(ctx, 404, 'OBJECT_NOT_FOUND', `Stage ${stageId} not found`);
+            await write('pipeline', pipelineKey(objectType, pipelineId), { objectType, pipelineId, label: pipeline.label, displayOrder: pipeline.displayOrder, stages: pipeline.stages.filter((s) => s.id !== stageId), stageSeq: pipeline.stageSeq, hsUpdatedAt: at }, root, at);
+            return noContent();
+          }
+        }
+      }
+    }
+    return notFound(ctx);
+  }
+
+  // ── /crm/v3/owners ───────────────────────────────────────────────────────────────────────
+  if (parts[0] === 'crm' && parts[1] === 'v3' && parts[2] === 'owners') {
+    const owners = listOwners(root);
+    if (method === 'GET' && parts.length === 3) {
+      const email = query.get('email');
+      const filtered = email ? owners.filter((o) => o.email === email) : owners;
+      return ok({ results: filtered });
+    }
+    if (method === 'GET' && parts.length === 4) {
+      const found = owners.find((o) => o.id === parts[3]);
+      if (!found) return fail(ctx, 404, 'OBJECT_NOT_FOUND', `Owner ${parts[3]} not found`);
+      return ok(found);
+    }
+    return notFound(ctx);
+  }
+
+  // ── /crm/v4/objects/{objectType}/{objectId}/associations/... ─────────────────────────────
+  if (parts[0] === 'crm' && parts[1] === 'v4' && parts[2] === 'objects' && parts[4] !== undefined && parts[5] === 'associations') {
+    const fromType = resolveObjectType(parts[3]!);
+    if (!fromType) return refuseObjectType(ctx, parts[3]!);
+    const fromId = parts[4]!;
+    if (!readRecord(fromType, fromId, root)) return fail(ctx, 404, 'OBJECT_NOT_FOUND', `${fromType} ${fromId} not found`);
+
+    // `default` FIRST — it occupies the {toObjectType} slot of the labeled route.
+    if (parts[6] === 'default' && parts.length === 9) {
+      if (method !== 'PUT') return notFound(ctx);
+      return createDefaultAssociation(ctx, fromType, fromId, parts[7]!, parts[8]!, root, at);
+    }
+    if (parts.length === 7) {
+      const toType = resolveObjectType(parts[6]!);
+      if (!toType) return refuseObjectType(ctx, parts[6]!);
+      if (method === 'GET') {
+        const results = readAssociations(fromType, fromId, toType, root).map((a) => ({
+          toObjectId: a.toId,
+          associationTypes: a.labels.map((l) => ({ category: l.associationCategory, typeId: l.associationTypeId })),
+        }));
+        return ok({ results });
+      }
+      return notFound(ctx);
+    }
+    if (parts.length === 8) {
+      const toType = resolveObjectType(parts[6]!);
+      if (!toType) return refuseObjectType(ctx, parts[6]!);
+      const toId = parts[7]!;
+      if (method === 'PUT') return createLabeledAssociation(ctx, fromType, fromId, toType, toId, body, root, at);
+      if (method === 'DELETE') {
+        if (!readRecord(toType, toId, root)) return fail(ctx, 404, 'OBJECT_NOT_FOUND', `${toType} ${toId} not found`);
+        const key = associationKey(fromType, fromId, toType, toId);
+        if (byId('association', key, root)) await write('association', key, { deleted: true }, root, at);
+        const mirror = associationKey(toType, toId, fromType, fromId);
+        if (byId('association', mirror, root)) await write('association', mirror, { deleted: true }, root, at);
+        return noContent();
+      }
+    }
+    return notFound(ctx);
+  }
+
+  // ── /crm/v4/associations/{fromObjectType}/{toObjectType}/batch/{op} ──────────────────────
+  if (parts[0] === 'crm' && parts[1] === 'v4' && parts[2] === 'associations' && parts[5] === 'batch' && parts.length === 7) {
+    const fromType = resolveObjectType(parts[3]!);
+    const toType = resolveObjectType(parts[4]!);
+    if (!fromType) return refuseObjectType(ctx, parts[3]!);
+    if (!toType) return refuseObjectType(ctx, parts[4]!);
+    if (method !== 'POST') return notFound(ctx);
+    return associationBatch(ctx, fromType, toType, parts[6]!, body, root, at);
+  }
+
+  // Unmodeled op → fails like the vendor, never a fake success.
+  return notFound(ctx);
+}
+
+function notFound(ctx: ErrorContext): HubspotResponse {
+  return fail(ctx, 404, 'OBJECT_NOT_FOUND', `resource not found: ${ctx.method} ${ctx.pathname}`);
+}
+
+/** What the twin answers a request for no operation it serves (the derived dispatch's gap, hubspot-server.ts): an
+ *  object type HubSpot cannot resolve under /crm/v3/objects/ is refused as the vendor refuses it, a type it has and
+ *  the twin does not model says so (`refuseObjectType`), and anything else is the twin's 404 in HubSpot's error body.
+ *  Where the documentation stops: no page prints HubSpot's answer to an unknown path; the 404 is the twin's. */
+export function hubspotUnknownRequest(method: string, pathname: string): HubspotResponse {
+  const ctx: ErrorContext = { method, pathname };
+  const parts = pathname.replace(/^\/+|\/+$/g, '').split('/').filter(Boolean);
+  if (parts[0] === 'crm' && parts[1] === 'v3' && parts[2] === 'objects' && parts[3] !== undefined && !resolveObjectType(parts[3])) return refuseObjectType(ctx, parts[3]);
+  return notFound(ctx);
+}
+
+/** The segment the spec's own paths give a modelled object type under /crm/v3/objects/: the Deals document publishes
+ *  its paths with the objectTypeId (`/crm/v3/objects/0-3`), the others with the name. HubSpot takes either in that
+ *  segment ("You can always use the numerical type ID value, but for contacts, companies, deals, tickets, or notes, in
+ *  some cases you can also use the object's fully qualified name", https://developers.hubspot.com/docs/api-reference/latest/crm/understanding-the-crm;
+ *  Dub reads a contact at /crm/v3/objects/contacts/{id} and a deal at /crm/v3/objects/0-3/{id}), so a request naming
+ *  the other spelling is answered by the same operation. */
+const SPEC_OBJECT_SEGMENT: Record<ObjectType, string> = { contacts: 'contacts', companies: 'companies', deals: '0-3', tickets: 'tickets' };
+
+/** A /crm/v3/objects/ path with its object type spelled as the spec's paths spell it; any other path unchanged. */
+export function specObjectPath(pathname: string): string {
+  const m = /^\/crm\/v3\/objects\/([^/]+)(\/.*)?$/.exec(pathname);
+  const type = m ? resolveObjectType(m[1]!) : null;
+  return m && type ? `/crm/v3/objects/${SPEC_OBJECT_SEGMENT[type]}${m[2] ?? ''}` : pathname;
+}
+
+// ── record operations ──────────────────────────────────────────────────────────────────────
+function normalizeProperties(input: unknown): Record<string, string> | null {
+  if (input === undefined || input === null) return null;
+  if (typeof input !== 'object' || Array.isArray(input)) return null;
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(input as Record<string, unknown>)) {
+    if (v === null || v === undefined) { out[k] = ''; continue; }
+    if (typeof v === 'object') return null;
+    out[k] = String(v);
+  }
+  return out;
+}
+
+async function createRecord(ctx: ErrorContext, objectType: ObjectType, body: Record<string, unknown>, root: string | undefined, at: string): Promise<HubspotResponse> {
+  const props = normalizeProperties(body.properties);
+  if (props === null) return fail(ctx, 400, 'VALIDATION_ERROR', 'Property values were not valid', [{ message: 'properties must be an object of string values', code: 'INVALID_PROPERTY_MAP', context: { properties: ['properties'] } }]);
+  const id = nextRecordId(objectType, root);
+  const record = {
+    objectType, hsId: id, hsCreatedAt: at, hsUpdatedAt: at, archived: false, hsLocalMint: true,
+    props: { ...props, hs_object_id: id, createdate: at, [LAST_MODIFIED_PROP[objectType]]: at },
+  };
+  await write('crm_object', recordKey(objectType, id), record, root, at);
+
+  // `associations` on a create body (PublicAssociationsForObject[]) is part of the create call.
+  const assocs = body.associations;
+  if (Array.isArray(assocs)) {
+    for (const a of assocs as Record<string, unknown>[]) {
+      const to = a.to as { id?: unknown } | undefined;
+      const toId = to?.id === undefined ? undefined : String(to.id);
+      const types = Array.isArray(a.types) ? (a.types as Record<string, unknown>[]) : [];
+      if (!toId || types.length === 0) return fail(ctx, 400, 'VALIDATION_ERROR', 'each association requires `to.id` and a non-empty `types`');
+      const toType = inferAssociationTarget(objectType, types);
+      if (!toType) return fail(ctx, 400, 'VALIDATION_ERROR', `Unknown associationTypeId for a ${objectType} association`);
+      if (!readRecord(toType, toId, root)) return fail(ctx, 404, 'OBJECT_NOT_FOUND', `${toType} ${toId} not found`);
+      await storeAssociation(objectType, id, toType, toId, types.map((t) => ({
+        associationCategory: String(t.associationCategory ?? 'HUBSPOT_DEFINED'),
+        associationTypeId: Number(t.associationTypeId),
+      })), root, at);
+    }
+  }
+  // announced once the create, its associations included, is stored: an app reading the new record finds them
+  await announceWrite({ objectType, objectId: id, kind: 'creation' }, root, at);
+  return ok(renderObject(readRecord(objectType, id, root)!, { root }), 201);
+}
+
+/** Resolve the target object type of an association spec by its HubSpot-defined type id. */
+function inferAssociationTarget(fromType: ObjectType, types: Record<string, unknown>[]): ObjectType | null {
+  for (const t of types) {
+    const typeId = Number(t.associationTypeId);
+    for (const [pair, id] of Object.entries(DEFAULT_ASSOCIATION_TYPE_IDS)) {
+      const [from, to] = pair.split('>') as [ObjectType, ObjectType];
+      if (from === fromType && id === typeId) return to;
+    }
+  }
+  return null;
+}
+
+function listRecords(ctx: ErrorContext, objectType: ObjectType, query: URLSearchParams, root?: string): HubspotResponse {
+  const limitRaw = query.get('limit');
+  const limit = limitRaw === null ? 10 : Number(limitRaw);
+  if (!Number.isInteger(limit) || limit < 1 || limit > LIST_LIMIT_MAX) {
+    return fail(ctx, 400, 'VALIDATION_ERROR', `limit must be an integer between 1 and ${LIST_LIMIT_MAX}`);
+  }
+  const archived = query.get('archived') === 'true';
+  const properties = splitCsv(query.getAll('properties'));
+  const associations = splitCsv(query.getAll('associations'));
+  const all = allRecords(objectType, root).filter((r) => r.archived === archived);
+  const after = query.get('after');
+  // HubSpot's `after` is the Record ID of the next record — results begin AT that id.
+  const start = after === null ? 0 : all.findIndex((r) => Number(r.hsId) >= Number(after));
+  const from = start === -1 ? all.length : start;
+  const unresolved: string[] = [];
+  const page = all.slice(from, from + limit);
+  for (const raw of associations) if (!resolveObjectType(raw)) unresolved.push(raw);
+  if (unresolved.length) return refuseObjectType(ctx, unresolved[0]!);
+  const nextIndex = from + limit;
+  // `NextPage.link` is OPTIONAL in the generated model, and HubSpot's own value is an ABSOLUTE
+  // URL rooted at its public host. A twin serving traffic on an ephemeral loopback port does not
+  // know that host, and a bare `?after=…` fragment is not what the vendor returns — so the field
+  // is omitted rather than filled with a lookalike (`hubspot.protocol.paging_next_link`).
+  const paging = nextIndex < all.length ? { next: { after: all[nextIndex]!.hsId } } : undefined;
+  return ok({
+    results: page.map((r) => renderObject(r, { ...(properties.length ? { properties } : {}), ...(associations.length ? { associations } : {}), root })),
+    ...(paging ? { paging } : {}),
+  });
+}
+
+function splitCsv(values: string[]): string[] {
+  return values.flatMap((v) => v.split(',')).map((v) => v.trim()).filter(Boolean);
+}
+
+function getRecord(ctx: ErrorContext, objectType: ObjectType, id: string, query: URLSearchParams, root?: string): HubspotResponse {
+  const rec = readRecord(objectType, id, root);
+  const wantArchived = query.get('archived') === 'true';
+  if (!rec || rec.archived !== wantArchived) return fail(ctx, 404, 'OBJECT_NOT_FOUND', `${objectType} ${id} not found`);
+  const properties = splitCsv(query.getAll('properties'));
+  const associations = splitCsv(query.getAll('associations'));
+  const unresolved: string[] = [];
+  const rendered = renderObject(rec, { ...(properties.length ? { properties } : {}), ...(associations.length ? { associations } : {}), root }, unresolved);
+  if (unresolved.length) return refuseObjectType(ctx, unresolved[0]!);
+  return ok(rendered);
+}
+
+async function updateRecord(ctx: ErrorContext, objectType: ObjectType, id: string, body: Record<string, unknown>, root: string | undefined, at: string): Promise<HubspotResponse> {
+  const rec = readRecord(objectType, id, root);
+  if (!rec || rec.archived) return fail(ctx, 404, 'OBJECT_NOT_FOUND', `${objectType} ${id} not found`);
+  const props = normalizeProperties(body.properties);
+  if (props === null) return fail(ctx, 400, 'VALIDATION_ERROR', 'Property values were not valid', [{ message: 'properties must be an object of string values', code: 'INVALID_PROPERTY_MAP', context: { properties: ['properties'] } }]);
+  const merged = { ...rec.props, ...props, [LAST_MODIFIED_PROP[objectType]]: at };
+  await write('crm_object', recordKey(objectType, id), { objectType, hsId: id, props: merged, hsUpdatedAt: at, archived: false, hsLocalMint: rec.hsLocalMint }, root, at);
+  // a property change is an event only when the value changed
+  for (const [name, value] of Object.entries(props)) {
+    if ((rec.props[name] ?? null) !== (value ?? null)) await announceWrite({ objectType, objectId: id, kind: 'propertyChange', propertyName: name, propertyValue: value }, root, at);
+  }
+  return ok(renderObject(readRecord(objectType, id, root)!, { root }));
+}
+
+async function archiveRecord(ctx: ErrorContext, objectType: ObjectType, id: string, root: string | undefined, at: string): Promise<HubspotResponse> {
+  const rec = readRecord(objectType, id, root);
+  if (!rec || rec.archived) return fail(ctx, 404, 'OBJECT_NOT_FOUND', `${objectType} ${id} not found`);
+  await write('crm_object', recordKey(objectType, id), { objectType, hsId: id, archived: true, hsArchivedAt: at, hsUpdatedAt: at, props: rec.props, hsLocalMint: rec.hsLocalMint }, root, at);
+  return noContent();
+}
+
+async function mergeRecords(ctx: ErrorContext, objectType: ObjectType, body: Record<string, unknown>, root: string | undefined, at: string): Promise<HubspotResponse> {
+  const primaryId = body.primaryObjectId === undefined ? undefined : String(body.primaryObjectId);
+  const mergeId = body.objectIdToMerge === undefined ? undefined : String(body.objectIdToMerge);
+  if (!primaryId || !mergeId) return fail(ctx, 400, 'VALIDATION_ERROR', 'primaryObjectId and objectIdToMerge are required');
+  if (primaryId === mergeId) return fail(ctx, 400, 'VALIDATION_ERROR', 'primaryObjectId and objectIdToMerge must differ');
+  const primary = readRecord(objectType, primaryId, root);
+  const secondary = readRecord(objectType, mergeId, root);
+  if (!primary || primary.archived) return fail(ctx, 404, 'OBJECT_NOT_FOUND', `${objectType} ${primaryId} not found`);
+  if (!secondary || secondary.archived) return fail(ctx, 404, 'OBJECT_NOT_FOUND', `${objectType} ${mergeId} not found`);
+  // HubSpot keeps the PRIMARY record's values and fills only its blanks from the secondary.
+  const merged: Record<string, string | null> = { ...secondary.props, ...primary.props };
+  for (const [k, v] of Object.entries(primary.props)) if (v === '' || v === null) merged[k] = secondary.props[k] ?? v;
+  merged[LAST_MODIFIED_PROP[objectType]] = at;
+  merged.hs_object_id = primaryId;
+  await write('crm_object', recordKey(objectType, primaryId), { objectType, hsId: primaryId, props: merged, hsUpdatedAt: at, archived: false, hsLocalMint: primary.hsLocalMint }, root, at);
+  await write('crm_object', recordKey(objectType, mergeId), { objectType, hsId: mergeId, archived: true, hsArchivedAt: at, hsUpdatedAt: at, hsMergedInto: primaryId, props: secondary.props, hsLocalMint: secondary.hsLocalMint }, root, at);
+  return ok(renderObject(readRecord(objectType, primaryId, root)!, { root }));
+}
+
+// ── batch ──────────────────────────────────────────────────────────────────────────────────
+function batchEnvelope(results: unknown[], at: string, extra: Record<string, unknown> = {}): Record<string, unknown> {
+  return { status: 'COMPLETE', results, startedAt: at, completedAt: at, ...extra };
+}
+
+async function batchOp(ctx: ErrorContext, objectType: ObjectType, op: string, body: Record<string, unknown>, root: string | undefined, at: string): Promise<HubspotResponse> {
+  const inputs = Array.isArray(body.inputs) ? (body.inputs as Record<string, unknown>[]) : null;
+  if (inputs === null) return fail(ctx, 400, 'VALIDATION_ERROR', 'inputs must be an array');
+
+  if (op === 'create') {
+    const results: unknown[] = [];
+    for (const input of inputs) {
+      const created = await createRecord(ctx, objectType, input, root, at);
+      if (created.status !== 201) return created;
+      results.push(created.body);
+    }
+    return ok(batchEnvelope(results, at), 201);
+  }
+  if (op === 'read') {
+    const properties = Array.isArray(body.properties) ? (body.properties as string[]) : [];
+    const idProperty = body.idProperty === undefined ? null : String(body.idProperty);
+    const results: unknown[] = [];
+    const errors: unknown[] = [];
+    for (const input of inputs) {
+      const wanted = String(input.id ?? '');
+      const rec = idProperty === null
+        ? readRecord(objectType, wanted, root)
+        : allRecords(objectType, root).find((r) => !r.archived && r.props[idProperty] === wanted);
+      if (!rec || rec.archived) {
+        // A complete `StandardError` — the generated model declares status/category/message/
+        // context/links/errors as REQUIRED, so a partial one would not survive the SDK's own
+        // deserializer.
+        errors.push({
+          status: 'error', category: 'OBJECT_NOT_FOUND',
+          message: `Could not get some ${objectType}. Some of the requested records were not found`,
+          context: { ids: [wanted] }, links: {}, errors: [],
+        });
+        continue;
+      }
+      results.push(renderObject(rec, { ...(properties.length ? { properties } : {}), root }));
+    }
+    // HubSpot answers a partially-successful batch read with 207 MULTI-STATUS and a
+    // BatchResponseSimplePublicObjectWithErrors (the generated processor accepts 200 or 207).
+    if (errors.length > 0) {
+      return ok({ ...batchEnvelope(results, at, { numErrors: errors.length, errors }), status: 'COMPLETE' }, 207);
+    }
+    return ok(batchEnvelope(results, at));
+  }
+  if (op === 'update') {
+    const results: unknown[] = [];
+    for (const input of inputs) {
+      const id = String(input.id ?? '');
+      const updated = await updateRecord(ctx, objectType, id, input, root, at);
+      if (updated.status !== 200) return updated;
+      results.push(updated.body);
+    }
+    return ok(batchEnvelope(results, at));
+  }
+  if (op === 'upsert') {
+    // "idProperty query param refers to a property whose values are unique for the object" (the spec's
+    // batch/upsert description): a property that is not unique, or not the object's, cannot identify a record. Where
+    // the documentation stops: HubSpot's words for the refusal are not published; the twin's name the rule.
+    for (const input of inputs) {
+      if (input.idProperty === undefined) continue;
+      const name = String(input.idProperty);
+      const property = listProperties(objectType, root).find((p) => p.name === name && !p.archived);
+      if (!property || !property.hasUniqueValue) return fail(ctx, 400, 'VALIDATION_ERROR', `${name} is not a unique-value property of ${objectType}, so it cannot be an idProperty`);
+    }
+    const results: unknown[] = [];
+    for (const input of inputs) {
+      const idProperty = input.idProperty === undefined ? null : String(input.idProperty);
+      const wanted = String(input.id ?? '');
+      const props = normalizeProperties(input.properties) ?? {};
+      const existing = idProperty === null
+        ? readRecord(objectType, wanted, root)
+        : allRecords(objectType, root).find((r) => !r.archived && r.props[idProperty] === wanted);
+      if (existing && !existing.archived) {
+        const updated = await updateRecord(ctx, objectType, existing.hsId, { properties: props }, root, at);
+        if (updated.status !== 200) return updated;
+        results.push({ ...(updated.body as Record<string, unknown>), new: false });
+      } else {
+        const seed = idProperty === null ? props : { ...props, [idProperty]: wanted };
+        const created = await createRecord(ctx, objectType, { properties: seed }, root, at);
+        if (created.status !== 201) return created;
+        results.push({ ...(created.body as Record<string, unknown>), new: true });
+      }
+    }
+    return ok(batchEnvelope(results, at));
+  }
+  if (op === 'archive') {
+    for (const input of inputs) {
+      const id = String(input.id ?? '');
+      const archived = await archiveRecord(ctx, objectType, id, root, at);
+      if (archived.status !== 204) return archived;
+    }
+    return noContent();
+  }
+  return notFound(ctx);
+}
+
+// ── search ─────────────────────────────────────────────────────────────────────────────────
+function searchRecords(ctx: ErrorContext, objectType: ObjectType, body: Record<string, unknown>, root?: string): HubspotResponse {
+  const limitRaw = body.limit;
+  const limit = limitRaw === undefined ? 10 : Number(limitRaw);
+  if (!Number.isInteger(limit) || limit < 1 || limit > SEARCH_LIMIT_MAX) {
+    return fail(ctx, 400, 'VALIDATION_ERROR', `The limit must be a positive integer no greater than ${SEARCH_LIMIT_MAX}`);
+  }
+  const groups = Array.isArray(body.filterGroups) ? (body.filterGroups as Record<string, unknown>[]) : [];
+  if (groups.length > SEARCH_MAX_FILTER_GROUPS) return fail(ctx, 400, 'VALIDATION_ERROR', `A maximum of ${SEARCH_MAX_FILTER_GROUPS} filterGroups is supported`);
+  let totalFilters = 0;
+  const parsedGroups: Filter[][] = [];
+  for (const g of groups) {
+    const filters = Array.isArray(g.filters) ? (g.filters as Record<string, unknown>[]) : [];
+    if (filters.length > SEARCH_MAX_FILTERS_PER_GROUP) return fail(ctx, 400, 'VALIDATION_ERROR', `A maximum of ${SEARCH_MAX_FILTERS_PER_GROUP} filters per filterGroup is supported`);
+    totalFilters += filters.length;
+    const out: Filter[] = [];
+    for (const f of filters) {
+      const operator = String(f.operator ?? '');
+      // The CLOSED FilterOperatorEnum is the oracle — an operator outside it is refused.
+      if (!OPERATOR_SET.has(operator)) return fail(ctx, 400, 'VALIDATION_ERROR', `Unsupported filter operator: ${operator || '(missing)'}`);
+      if (f.propertyName === undefined) return fail(ctx, 400, 'VALIDATION_ERROR', 'propertyName is required on every filter');
+      out.push({
+        propertyName: String(f.propertyName), operator,
+        ...(f.value !== undefined ? { value: String(f.value) } : {}),
+        ...(Array.isArray(f.values) ? { values: (f.values as unknown[]).map(String) } : {}),
+        ...(f.highValue !== undefined ? { highValue: String(f.highValue) } : {}),
+      });
+    }
+    parsedGroups.push(out);
+  }
+  if (totalFilters > SEARCH_MAX_FILTERS_TOTAL) return fail(ctx, 400, 'VALIDATION_ERROR', `A maximum of ${SEARCH_MAX_FILTERS_TOTAL} filters is supported`);
+
+  const afterRaw = body.after === undefined ? 0 : Number(body.after);
+  if (!Number.isInteger(afterRaw) || afterRaw < 0) return fail(ctx, 400, 'VALIDATION_ERROR', 'after must be a non-negative integer offset');
+  if (afterRaw + limit > SEARCH_RESULT_CAP) return fail(ctx, 400, 'VALIDATION_ERROR', `The search endpoint returns a maximum of ${SEARCH_RESULT_CAP} results; narrow your query`);
+
+  const query = body.query === undefined ? null : String(body.query);
+  let matched = allRecords(objectType, root).filter((r) => !r.archived);
+  if (parsedGroups.length) {
+    matched = matched.filter((r) => parsedGroups.some((g) => g.every((f) => matchesFilter(r, f))));
+  }
+  if (query) {
+    const needle = query.toLowerCase();
+    matched = matched.filter((r) => Object.values(r.props).some((v) => String(v ?? '').toLowerCase().includes(needle)));
+  }
+  const sorts = Array.isArray(body.sorts) ? (body.sorts as unknown[]).map(String) : [];
+  if (sorts.length) {
+    // HubSpot accepts a single sort as `{propertyName, direction}` or a bare property name; the
+    // generated PublicObjectSearchRequest types `sorts` as string[], which is what this models.
+    const key = sorts[0]!;
+    matched = [...matched].sort((a, b) => String(a.props[key] ?? '').localeCompare(String(b.props[key] ?? '')));
+  }
+  const properties = Array.isArray(body.properties) ? (body.properties as unknown[]).map(String) : [];
+  const page = matched.slice(afterRaw, afterRaw + limit);
+  const nextOffset = afterRaw + limit;
+  const paging = nextOffset < matched.length && nextOffset < SEARCH_RESULT_CAP ? { next: { after: String(nextOffset) } } : undefined;
+  return ok({
+    total: matched.length,
+    results: page.map((r) => renderObject(r, { ...(properties.length ? { properties } : {}), root })),
+    ...(paging ? { paging } : {}),
+  });
+}
+
+// ── properties / groups / pipelines writes ─────────────────────────────────────────────────
+/** Why a property create would be refused, answered as HubSpot answers it; undefined when it would succeed. */
+function propertyRefusal(ctx: ErrorContext, objectType: ObjectType, body: Record<string, unknown>, root: string | undefined): HubspotResponse | undefined {
+  for (const required of ['name', 'label', 'type', 'fieldType', 'groupName'] as const) {
+    if (body[required] === undefined || String(body[required]) === '') {
+      return fail(ctx, 400, 'VALIDATION_ERROR', `${required} is required`, [{ message: `${required} is required`, code: 'PROPERTY_MISSING_FIELD', context: { field: [required] } }]);
+    }
+  }
+  const name = String(body.name);
+  if (listProperties(objectType, root).some((p) => p.name === name && !p.archived)) return fail(ctx, 409, 'CONFLICT', `Property ${name} already exists`);
+  return undefined;
+}
+
+async function createProperty(ctx: ErrorContext, objectType: ObjectType, body: Record<string, unknown>, root: string | undefined, at: string): Promise<HubspotResponse> {
+  const refused = propertyRefusal(ctx, objectType, body, root);
+  if (refused) return refused;
+  const name = String(body.name);
+  await write('property', propertyKey(objectType, name), {
+    objectType, name, label: String(body.label), propType: String(body.type), fieldType: String(body.fieldType),
+    groupName: String(body.groupName), description: body.description === undefined ? '' : String(body.description),
+    options: Array.isArray(body.options) ? body.options : [], formField: body.formField === true,
+    // a property whose values are unique is one a record can be identified by (batch upsert's `idProperty`)
+    hasUniqueValue: body.hasUniqueValue === true, archived: false,
+  }, root, at);
+  return ok(renderProperty(listProperties(objectType, root).find((p) => p.name === name)!), 201);
+}
+
+async function createPropertyGroup(ctx: ErrorContext, objectType: ObjectType, body: Record<string, unknown>, root: string | undefined, at: string): Promise<HubspotResponse> {
+  if (body.name === undefined || body.label === undefined) return fail(ctx, 400, 'VALIDATION_ERROR', 'name and label are required');
+  const name = String(body.name);
+  if (listPropertyGroups(objectType, root).some((g) => g.name === name && !g.archived)) return fail(ctx, 409, 'CONFLICT', `Group ${name} already exists`);
+  await write('property_group', `${objectType}_${name}`, { objectType, name, label: String(body.label), displayOrder: body.displayOrder === undefined ? -1 : Number(body.displayOrder), archived: false }, root, at);
+  const g = listPropertyGroups(objectType, root).find((x) => x.name === name)!;
+  return ok({ name: g.name, label: g.label, displayOrder: g.displayOrder, archived: g.archived }, 201);
+}
+
+/**
+ * Assign ids to a stage list, drawing every new id from the pipeline's MONOTONIC counter.
+ * Returns the next counter value alongside the stages so the caller persists it — an id a
+ * removed stage once held is never handed out again.
+ */
+function normalizeStages(input: Record<string, unknown>[], startSeq: number): { stages: SeedStage[]; seq: number } | { error: string } {
+  const stages: SeedStage[] = [];
+  let seq = startSeq;
+  for (const s of input) {
+    if (s.label === undefined || s.displayOrder === undefined) return { error: 'each stage requires label and displayOrder' };
+    let id = s.id === undefined ? '' : String(s.id);
+    if (!id) { seq += 1; id = `stage_${seq}`; }
+    stages.push({ id, label: String(s.label), displayOrder: Number(s.displayOrder), metadata: (s.metadata as Record<string, string> | undefined) ?? {} });
+  }
+  return { stages, seq };
+}
+
+async function createPipeline(ctx: ErrorContext, objectType: ObjectType, body: Record<string, unknown>, root: string | undefined, at: string): Promise<HubspotResponse> {
+  if (body.label === undefined || body.displayOrder === undefined) return fail(ctx, 400, 'VALIDATION_ERROR', 'label and displayOrder are required');
+  const stagesInput = Array.isArray(body.stages) ? (body.stages as Record<string, unknown>[]) : [];
+  const staged = normalizeStages(stagesInput, 0);
+  if ('error' in staged) return fail(ctx, 400, 'VALIDATION_ERROR', staged.error);
+  // Pipeline ids come from the id SET of every pipeline EVER stored — archived ones included,
+  // so an archived pipeline's id is never handed to a new one (the same rule record ids follow).
+  const used = new Set<string>();
+  for (const r of rowsAll('pipeline', root)) {
+    if (r.objectType === objectType) used.add(String(r.pipelineId));
+  }
+  let n = 1;
+  while (used.has(`pipeline_${n}`)) n += 1;
+  const id = `pipeline_${n}`;
+  await write('pipeline', pipelineKey(objectType, id), { objectType, pipelineId: id, label: String(body.label), displayOrder: Number(body.displayOrder), stages: staged.stages, stageSeq: staged.seq, archived: false, hsCreatedAt: at, hsUpdatedAt: at }, root, at);
+  return ok(renderPipeline(listPipelines(objectType, root).find((p) => p.id === id)!), 201);
+}
+
+// ── owners ─────────────────────────────────────────────────────────────────────────────────
+function listOwners(root?: string): Record<string, unknown>[] {
+  const hub = currentPortal().hub;
+  // an account the World made: its owners are its users ("owners are portal users", the index's resourcesUnreachable)
+  if (hub !== TWIN_HUB_ID) return ownersOf(hub, root);
+  const merged = new Map<string, Record<string, unknown>>();
+  merged.set(SEED_OWNER.id, { ...SEED_OWNER, createdAt: EPOCH, updatedAt: EPOCH });
+  for (const r of rows('owner', root)) {
+    const id = String(r.ownerId ?? r.id);
+    merged.set(id, {
+      id, email: r.email ?? null, firstName: r.firstName ?? null, lastName: r.lastName ?? null,
+      userId: r.userId ?? null, userIdIncludingInactive: r.userId ?? null, type: r.ownerType ?? 'PERSON',
+      archived: r.archived === true, teams: (r.teams as unknown[] | undefined) ?? [],
+      createdAt: String(r.hsCreatedAt ?? EPOCH), updatedAt: String(r.hsUpdatedAt ?? EPOCH),
+    });
+  }
+  return [...merged.values()].filter((o) => o.archived !== true);
+}
+
+// ── association writes ─────────────────────────────────────────────────────────────────────
+/**
+ * Parse an `AssociationSpec[]` body — a CLOSED TWO-KEY shape.
+ *
+ * `crm/associations/v4/models/AssociationSpec.d.ts` declares exactly `associationCategory` and
+ * `associationTypeId`, and nothing else. In particular there is NO `label` on the REQUEST: a
+ * label is a property of the association-type DEFINITION (`/crm/v4/associations/{from}/{to}/
+ * labels`, which this twin files as `hubspot.associations.label_definitions` and does not model),
+ * and HubSpot RESOLVES it onto the response from that definition. Accepting a caller-supplied
+ * `label` and echoing it back would be inventing a request parameter the vendor does not have —
+ * the §6 "serving surface the vendor doesn't have" class — so the key is read from nothing here
+ * and every stored label is null until definitions are modeled.
+ */
+function parseAssociationSpecs(ctx: ErrorContext, specs: Record<string, unknown>[]): { labels: StoredAssociation['labels'] } | { error: HubspotResponse } {
+  const labels: StoredAssociation['labels'] = [];
+  for (const s of specs) {
+    const category = String(s.associationCategory ?? '');
+    // The closed AssociationSpecAssociationCategoryEnum from the generated model.
+    if (!['HUBSPOT_DEFINED', 'USER_DEFINED', 'INTEGRATOR_DEFINED'].includes(category)) {
+      return { error: fail(ctx, 400, 'VALIDATION_ERROR', `Unsupported associationCategory: ${category || '(missing)'}`) };
+    }
+    const typeId = Number(s.associationTypeId);
+    if (!Number.isInteger(typeId)) return { error: fail(ctx, 400, 'VALIDATION_ERROR', 'associationTypeId must be an integer') };
+    labels.push({ associationCategory: category, associationTypeId: typeId });
+  }
+  return { labels };
+}
+
+/**
+ * `LabelsBetweenObjectPair` — the 201 body of a labeled association PUT.
+ *
+ * `fromObjectTypeId` / `toObjectTypeId` carry HubSpot's NUMERIC objectTypeId (`0-1`, `0-2`), not
+ * the plural path segment. `labels` holds the resolved definition labels, which is EMPTY here
+ * for as long as `hubspot.associations.label_definitions` is unmodeled — an empty list is the
+ * honest answer; a list echoing the caller's own input would not be.
+ */
+function labelsBetweenObjectPair(fromType: ObjectType, fromId: string, toType: ObjectType, toId: string, labels: StoredAssociation['labels']): Record<string, unknown> {
+  return {
+    fromObjectTypeId: OBJECT_TYPE_ID[fromType], fromObjectId: fromId,
+    toObjectTypeId: OBJECT_TYPE_ID[toType], toObjectId: toId,
+    // Resolved from the association-type DEFINITIONS, which are unmodeled — so, empty.
+    labels: [] as string[],
+  };
+}
+
+async function storeAssociation(fromType: ObjectType, fromId: string, toType: ObjectType, toId: string, labels: StoredAssociation['labels'], root: string | undefined, at: string): Promise<void> {
+  await write('association', associationKey(fromType, fromId, toType, toId), { fromType, fromId, toType, toId, labels }, root, at);
+  // HubSpot associations are bidirectional — the inverse is readable from the other record.
+  const inverseId = DEFAULT_ASSOCIATION_TYPE_IDS[`${toType}>${fromType}`];
+  await write('association', associationKey(toType, toId, fromType, fromId), {
+    fromType: toType, fromId: toId, toType: fromType, toId: fromId,
+    labels: inverseId === undefined ? labels : [{ associationCategory: 'HUBSPOT_DEFINED', associationTypeId: inverseId }],
+  }, root, at);
+}
+
+async function createDefaultAssociation(ctx: ErrorContext, fromType: ObjectType, fromId: string, rawToType: string, toId: string, root: string | undefined, at: string): Promise<HubspotResponse> {
+  const toType = resolveObjectType(rawToType);
+  if (!toType) return refuseObjectType(ctx, rawToType);
+  if (!readRecord(toType, toId, root)) return fail(ctx, 404, 'OBJECT_NOT_FOUND', `${toType} ${toId} not found`);
+  const typeId = DEFAULT_ASSOCIATION_TYPE_IDS[`${fromType}>${toType}`];
+  if (typeId === undefined) {
+    // The twin refuses rather than fabricating an associationTypeId it has no source for
+    // (`hubspot.associations.create_default_unmodeled_pair` files this as a todo).
+    return fail(ctx, 400, 'VALIDATION_ERROR', `This twin models HubSpot-defined default association type ids only for the standard CRM pairs; ${fromType} -> ${toType} is not one of them`);
+  }
+  await storeAssociation(fromType, fromId, toType, toId, [{ associationCategory: 'HUBSPOT_DEFINED', associationTypeId: typeId }], root, at);
+  return ok({
+    status: 'COMPLETE', startedAt: at, completedAt: at,
+    results: [{ from: { id: fromId }, to: { id: toId }, associationSpec: { associationCategory: 'HUBSPOT_DEFINED', associationTypeId: typeId } }],
+  });
+}
+
+async function createLabeledAssociation(ctx: ErrorContext, fromType: ObjectType, fromId: string, toType: ObjectType, toId: string, body: Record<string, unknown>, root: string | undefined, at: string): Promise<HubspotResponse> {
+  if (!readRecord(toType, toId, root)) return fail(ctx, 404, 'OBJECT_NOT_FOUND', `${toType} ${toId} not found`);
+  const specs = Array.isArray(body) ? (body as unknown as Record<string, unknown>[]) : Array.isArray(body.types) ? (body.types as Record<string, unknown>[]) : null;
+  if (!specs || specs.length === 0) return fail(ctx, 400, 'VALIDATION_ERROR', 'a non-empty array of association specs is required');
+  const parsed = parseAssociationSpecs(ctx, specs);
+  if ('error' in parsed) return parsed.error;
+  await storeAssociation(fromType, fromId, toType, toId, parsed.labels, root, at);
+  return ok(labelsBetweenObjectPair(fromType, fromId, toType, toId, parsed.labels), 201);
+}
+
+async function associationBatch(ctx: ErrorContext, fromType: ObjectType, toType: ObjectType, op: string, body: Record<string, unknown>, root: string | undefined, at: string): Promise<HubspotResponse> {
+  const inputs = Array.isArray(body.inputs) ? (body.inputs as Record<string, unknown>[]) : null;
+  if (inputs === null) return fail(ctx, 400, 'VALIDATION_ERROR', 'inputs must be an array');
+
+  if (op === 'read') {
+    const results: unknown[] = [];
+    for (const input of inputs) {
+      const fromId = String((input.id ?? (input as { from?: { id?: unknown } }).from?.id) ?? '');
+      if (!readRecord(fromType, fromId, root)) return fail(ctx, 404, 'OBJECT_NOT_FOUND', `${fromType} ${fromId} not found`);
+      results.push({
+        from: { id: fromId },
+        to: readAssociations(fromType, fromId, toType, root).map((a) => ({
+          toObjectId: a.toId,
+          associationTypes: a.labels.map((l) => ({ category: l.associationCategory, typeId: l.associationTypeId })),
+        })),
+      });
+    }
+    return ok(batchEnvelope(results, at));
+  }
+  if (op === 'create') {
+    const results: unknown[] = [];
+    for (const input of inputs) {
+      const fromId = String((input as { _from?: { id?: unknown }; from?: { id?: unknown } }).from?.id ?? (input as { _from?: { id?: unknown } })._from?.id ?? '');
+      const toId = String((input as { to?: { id?: unknown } }).to?.id ?? '');
+      const types = Array.isArray(input.types) ? (input.types as Record<string, unknown>[]) : [];
+      if (!fromId || !toId || types.length === 0) return fail(ctx, 400, 'VALIDATION_ERROR', 'each input requires from.id, to.id and a non-empty types array');
+      if (!readRecord(fromType, fromId, root)) return fail(ctx, 404, 'OBJECT_NOT_FOUND', `${fromType} ${fromId} not found`);
+      if (!readRecord(toType, toId, root)) return fail(ctx, 404, 'OBJECT_NOT_FOUND', `${toType} ${toId} not found`);
+      const parsed = parseAssociationSpecs(ctx, types);
+      if ('error' in parsed) return parsed.error;
+      await storeAssociation(fromType, fromId, toType, toId, parsed.labels, root, at);
+      results.push(labelsBetweenObjectPair(fromType, fromId, toType, toId, parsed.labels));
+    }
+    return ok(batchEnvelope(results, at), 201);
+  }
+  if (op === 'archive') {
+    for (const input of inputs) {
+      const fromId = String((input as { from?: { id?: unknown } }).from?.id ?? '');
+      const tos = Array.isArray(input.to) ? (input.to as Record<string, unknown>[]) : [];
+      if (!fromId) return fail(ctx, 400, 'VALIDATION_ERROR', 'each input requires from.id');
+      for (const to of tos) {
+        const toId = String(to.id ?? '');
+        const key = associationKey(fromType, fromId, toType, toId);
+        if (byId('association', key, root)) await write('association', key, { deleted: true }, root, at);
+        const mirror = associationKey(toType, toId, fromType, fromId);
+        if (byId('association', mirror, root)) await write('association', mirror, { deleted: true }, root, at);
+      }
+    }
+    return noContent();
+  }
+  return notFound(ctx);
+}
+
+// The subject types this twin projects (for the pack descriptor / conformance).
+export const RESOURCE_TYPES = ['crm_object', 'property', 'property_group', 'pipeline', 'association', 'owner'] as const;
+
+/**
+ * THE ENDPOINT CENSUS — what this twin CLAIMS to serve, in canonical `{placeholder}` form.
+ *
+ * Hand-authored from the dispatch above, and held to a two-way bijection with
+ * `hubspot-conformance.ts`'s probe table (every claim needs a live probe; every probe needs a
+ * claim), while that file's independent ROUTER_SURFACE closes the third direction — surface the
+ * router SERVES that this list does not name. It exists here, next to the router, so a branch
+ * added without a claim is visible in the same diff.
+ */
+export function hubspotTwinSnapshot(): { implementedEndpoints: string[] } {
+  return {
+    implementedEndpoints: [
+      // CRM objects (the generic {objectType} family: contacts, companies, deals, tickets)
+      'POST /crm/v3/objects/{objectType}',
+      'GET /crm/v3/objects/{objectType}',
+      'GET /crm/v3/objects/{objectType}/{objectId}',
+      'PATCH /crm/v3/objects/{objectType}/{objectId}',
+      'DELETE /crm/v3/objects/{objectType}/{objectId}',
+      'POST /crm/v3/objects/{objectType}/search',
+      'POST /crm/v3/objects/{objectType}/merge',
+      'POST /crm/v3/objects/{objectType}/batch/create',
+      'POST /crm/v3/objects/{objectType}/batch/read',
+      'POST /crm/v3/objects/{objectType}/batch/update',
+      'POST /crm/v3/objects/{objectType}/batch/upsert',
+      'POST /crm/v3/objects/{objectType}/batch/archive',
+      // properties + property groups
+      'GET /crm/v3/properties/{objectType}',
+      'POST /crm/v3/properties/{objectType}',
+      'POST /crm/v3/properties/{objectType}/batch/create',
+      'GET /crm/v3/properties/{objectType}/{propertyName}',
+      'PATCH /crm/v3/properties/{objectType}/{propertyName}',
+      'DELETE /crm/v3/properties/{objectType}/{propertyName}',
+      'GET /crm/v3/properties/{objectType}/groups',
+      'POST /crm/v3/properties/{objectType}/groups',
+      'GET /crm/v3/properties/{objectType}/groups/{groupName}',
+      'PATCH /crm/v3/properties/{objectType}/groups/{groupName}',
+      'DELETE /crm/v3/properties/{objectType}/groups/{groupName}',
+      // pipelines + stages (deals and tickets)
+      'GET /crm/v3/pipelines/{objectType}',
+      'POST /crm/v3/pipelines/{objectType}',
+      'GET /crm/v3/pipelines/{objectType}/{pipelineId}',
+      'PATCH /crm/v3/pipelines/{objectType}/{pipelineId}',
+      'PUT /crm/v3/pipelines/{objectType}/{pipelineId}',
+      'DELETE /crm/v3/pipelines/{objectType}/{pipelineId}',
+      'GET /crm/v3/pipelines/{objectType}/{pipelineId}/stages',
+      'POST /crm/v3/pipelines/{objectType}/{pipelineId}/stages',
+      'GET /crm/v3/pipelines/{objectType}/{pipelineId}/stages/{stageId}',
+      'PATCH /crm/v3/pipelines/{objectType}/{pipelineId}/stages/{stageId}',
+      'PUT /crm/v3/pipelines/{objectType}/{pipelineId}/stages/{stageId}',
+      'DELETE /crm/v3/pipelines/{objectType}/{pipelineId}/stages/{stageId}',
+      // owners
+      'GET /crm/v3/owners',
+      'GET /crm/v3/owners/{ownerId}',
+      // associations v4
+      'GET /crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}',
+      'PUT /crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}',
+      'DELETE /crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}',
+      'PUT /crm/v4/objects/{objectType}/{objectId}/associations/default/{toObjectType}/{toObjectId}',
+      'POST /crm/v4/associations/{fromObjectType}/{toObjectType}/batch/read',
+      'POST /crm/v4/associations/{fromObjectType}/{toObjectType}/batch/create',
+      'POST /crm/v4/associations/{fromObjectType}/{toObjectType}/batch/archive',
+    ],
+  };
+}