@volter/twin-hubspot 0.1.0

package/dist/src/hubspot-twin.js

@@ -0,0 +1,1558 @@
+// 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.js";
+import { ownersOf } from "./accounts.js";
+import { announceWrite } from "./webhooks.js";
+import { createHash } from 'node:crypto';
+const SERVICE = 'hubspot';
+// ── 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 = 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'];
+const OBJECT_TYPE_IDS = {
+    '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 = { 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 = { 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, raw) {
+    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) {
+    const lower = raw.toLowerCase();
+    if (OBJECT_TYPES.includes(lower))
+        return lower;
+    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 = {
+    contacts: 'lastmodifieddate', companies: 'hs_lastmodifieddate', deals: 'hs_lastmodifieddate', tickets: 'hs_lastmodifieddate',
+};
+const DEFAULT_PROPERTIES = {
+    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 = {
+    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(['deals', 'tickets']);
+const DEFAULT_PIPELINES = {
+    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 = {
+    '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',
+];
+const OPERATOR_SET = new Set(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;
+/** 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) {
+    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, status = 200) {
+    return { status, body: data, headers: { ...HUBSPOT_RATE_LIMIT_HEADERS } };
+}
+function noContent() {
+    return { status: 204, body: null, headers: { ...HUBSPOT_RATE_LIMIT_HEADERS } };
+}
+function fail(ctx, status, category, message, errors) {
+    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, root) {
+    const hub = currentPortal().hub;
+    const out = [];
+    for (const r of projectResources(SERVICE, root)) {
+        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, root) {
+    return rowsAll(type, root).filter((r) => r.deleted !== true);
+}
+function byId(type, id, root) {
+    return rows(type, root).find((r) => r.id === id);
+}
+async function write(type, id, fields, root, occurredAt) {
+    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) {
+    if (!body)
+        return { ok: true, value: {} };
+    try {
+        const parsed = JSON.parse(body);
+        if (parsed === null || typeof parsed !== 'object')
+            return { ok: false };
+        return { ok: true, value: parsed };
+    }
+    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, id) {
+    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, root) {
+    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);
+}
+function readRecord(objectType, id, root) {
+    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 ?? {}),
+        hsLocalMint: r.hsLocalMint === true,
+    };
+}
+function allRecords(objectType, root) {
+    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 ?? {}),
+        hsLocalMint: r.hsLocalMint === true,
+    }))
+        .sort((a, b) => Number(a.hsId) - Number(b.hsId));
+}
+/** SimplePublicObject / SimplePublicObjectWithAssociations, per the generated models. */
+function renderObject(rec, opts, unresolved = []) {
+    const properties = {};
+    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 = {
+        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 = {};
+        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;
+}
+function seededProperties(objectType) {
+    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, name) { 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, root) {
+    const merged = new Map();
+    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 } : {}),
+            ...(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) {
+    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,
+    };
+}
+function listPropertyGroups(objectType, root) {
+    const merged = new Map();
+    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()];
+}
+function pipelineKey(objectType, id) { return `${objectType}_${id}`; }
+function listPipelines(objectType, root) {
+    const merged = new Map();
+    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 ?? 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) {
+    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, p) {
+    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' };
+}
+function associationKey(fromType, fromId, toType, toId) {
+    return `${fromType}:${fromId}>${toType}:${toId}`;
+}
+function readAssociations(fromType, fromId, toType, root) {
+    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 ?? [],
+    }))
+        .sort((a, b) => Number(a.toId) - Number(b.toId));
+}
+function matchesFilter(rec, f) {
+    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) {
+    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, needle) {
+    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) {
+    const { method, root, occurredAt } = req;
+    const readOnly = req.readOnly ?? false;
+    const isWrite = method !== 'GET' && method !== 'HEAD';
+    const at = occurredAt ?? EPOCH;
+    let 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 = { 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 = { 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 : 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();
+            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 = [];
+            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 = { objectType, name };
+                for (const k of ['label', 'description', 'groupName', 'fieldType', 'options'])
+                    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 = { 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, 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 = { id: `stage_${seq}`, label: String(body.label), displayOrder: Number(body.displayOrder), metadata: body.metadata ?? {} };
+                    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 = {
+                            id: stage.id,
+                            label: body.label !== undefined ? String(body.label) : stage.label,
+                            displayOrder: body.displayOrder !== undefined ? Number(body.displayOrder) : stage.displayOrder,
+                            metadata: body.metadata ?? 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) {
+    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, pathname) {
+    const ctx = { 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 = { 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) {
+    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) {
+    if (input === undefined || input === null)
+        return null;
+    if (typeof input !== 'object' || Array.isArray(input))
+        return null;
+    const out = {};
+    for (const [k, v] of Object.entries(input)) {
+        if (v === null || v === undefined) {
+            out[k] = '';
+            continue;
+        }
+        if (typeof v === 'object')
+            return null;
+        out[k] = String(v);
+    }
+    return out;
+}
+async function createRecord(ctx, objectType, body, root, at) {
+    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) {
+            const to = a.to;
+            const toId = to?.id === undefined ? undefined : String(to.id);
+            const types = Array.isArray(a.types) ? a.types : [];
+            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, types) {
+    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('>');
+            if (from === fromType && id === typeId)
+                return to;
+        }
+    }
+    return null;
+}
+function listRecords(ctx, objectType, query, root) {
+    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 = [];
+    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) {
+    return values.flatMap((v) => v.split(',')).map((v) => v.trim()).filter(Boolean);
+}
+function getRecord(ctx, objectType, id, query, root) {
+    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 = [];
+    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, objectType, id, body, root, at) {
+    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, objectType, id, root, at) {
+    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, objectType, body, root, at) {
+    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 = { ...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, at, extra = {}) {
+    return { status: 'COMPLETE', results, startedAt: at, completedAt: at, ...extra };
+}
+async function batchOp(ctx, objectType, op, body, root, at) {
+    const inputs = Array.isArray(body.inputs) ? body.inputs : null;
+    if (inputs === null)
+        return fail(ctx, 400, 'VALIDATION_ERROR', 'inputs must be an array');
+    if (op === 'create') {
+        const results = [];
+        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 : [];
+        const idProperty = body.idProperty === undefined ? null : String(body.idProperty);
+        const results = [];
+        const errors = [];
+        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 = [];
+        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 = [];
+        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, 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, 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, objectType, body, root) {
+    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 : [];
+    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 = [];
+    for (const g of groups) {
+        const filters = Array.isArray(g.filters) ? g.filters : [];
+        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 = [];
+        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.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.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.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, objectType, body, root) {
+    for (const required of ['name', 'label', 'type', 'fieldType', 'groupName']) {
+        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, objectType, body, root, at) {
+    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, objectType, body, root, at) {
+    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, startSeq) {
+    const stages = [];
+    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 ?? {} });
+    }
+    return { stages, seq };
+}
+async function createPipeline(ctx, objectType, body, root, at) {
+    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 : [];
+    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();
+    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) {
+    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();
+    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 ?? [],
+            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, specs) {
+    const 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, fromId, toType, toId, labels) {
+    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: [],
+    };
+}
+async function storeAssociation(fromType, fromId, toType, toId, labels, root, at) {
+    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, fromType, fromId, rawToType, toId, root, at) {
+    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, fromType, fromId, toType, toId, body, root, at) {
+    if (!readRecord(toType, toId, root))
+        return fail(ctx, 404, 'OBJECT_NOT_FOUND', `${toType} ${toId} not found`);
+    const specs = Array.isArray(body) ? body : Array.isArray(body.types) ? body.types : 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, fromType, toType, op, body, root, at) {
+    const inputs = Array.isArray(body.inputs) ? body.inputs : null;
+    if (inputs === null)
+        return fail(ctx, 400, 'VALIDATION_ERROR', 'inputs must be an array');
+    if (op === 'read') {
+        const results = [];
+        for (const input of inputs) {
+            const fromId = String((input.id ?? input.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 = [];
+        for (const input of inputs) {
+            const fromId = String(input.from?.id ?? input._from?.id ?? '');
+            const toId = String(input.to?.id ?? '');
+            const types = Array.isArray(input.types) ? input.types : [];
+            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.from?.id ?? '');
+            const tos = Array.isArray(input.to) ? input.to : [];
+            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'];
+/**
+ * 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() {
+    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',
+        ],
+    };
+}