@volter/twin-hubspot 0.1.0

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

@@ -0,0 +1,125 @@
+import type { PerformContext, PushOutcome, RemoteExecute, SyncResource, TwinAction } from '@volter/world-core';
+import { HubspotBudget, type HubspotBudgetOptions } from './hubspot-budget.js';
+import { type ObjectType } from './hubspot-twin.js';
+/** The HubSpot error envelope, as the vendor documents it. */
+export type HubspotErrorBody = {
+    status?: string;
+    message?: string;
+    category?: string;
+    correlationId?: string;
+    errors?: unknown[];
+};
+/**
+ * The injected real-HubSpot boundary. `execute` issues ONE HubSpot REST call and returns the
+ * parsed JSON body together with the HTTP status, because HubSpot signals refusal with the STATUS
+ * (a 4xx carrying `{status:'error', …}`), and a body-only contract cannot tell a refusal from an
+ * empty account. A real client (a raw fetch wrapper) is structurally assignable; tests pass a fake.
+ */
+export type HubspotExecute = (method: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE', path: string, body?: Record<string, unknown>) => Promise<{
+    httpStatus: number;
+    body: unknown;
+}>;
+/** Construction options for the live executor. `budget` cannot be null and cannot be loosened. */
+export type LiveHubspotOptions = {
+    /** Injected `fetch`, so a test can COUNT the requests the guard did or did not let through. */
+    fetchImpl?: typeof fetch;
+    /** An existing budget to share across executors. Omit and one is constructed. Cannot be null. */
+    budget?: HubspotBudget;
+    /** Construction options for the default budget (ledger path, clock). Cannot loosen it. */
+    budgetOptions?: HubspotBudgetOptions;
+};
+/**
+ * A live executor against the real HubSpot CRM API (the operator's own private-app token).
+ *
+ * THIS IS THE ONE PLACE this pack issues a live `api.hubapi.com` request, and therefore the one
+ * place the rate budget has to be enforced. EVERY call is guarded: the budget is charged BEFORE
+ * the request goes out (`checkBudget`, which THROWS `HubspotBudgetError` instead of returning when
+ * the ceiling or a cooldown says stop) and the response is fed back (`recordCall`) so a
+ * `Retry-After` / 429 / `X-HubSpot-RateLimit-Remaining: 0` signal becomes a persisted cooldown that
+ * makes every later call fail fast WITHOUT touching HubSpot. There is deliberately no OPTION to
+ * disable the guard, and no value a caller can pass for `budget` that yields an unguarded client.
+ * That is NOT immunity from a caller who WANTS one: a fresh `budgetOptions.path` per construction,
+ * or an injected clock, restores the allowance, because the seam tests need cannot be denied to a
+ * determined caller in the same process. See `hubspot-budget.ts` and the kernel's own header.
+ */
+export declare function liveHubspotExecute(accessToken: string, base?: string, opts?: LiveHubspotOptions): HubspotExecute;
+/**
+ * Map a HubSpot SimplePublicObject → a SyncResource the kernel can fold.
+ *
+ * The renames are load-bearing, not cosmetic: the kernel's META set (`control-plane/src/
+ * actions.ts`) silently DROPS resource fields named `type`, `id` or `updatedAt`, and HubSpot's
+ * record carries all three. A field literally named `id` would vanish from the projection with no
+ * error at all.
+ *
+ * `hsLocalMint: false` is equally load-bearing. The twin's own create handler stamps
+ * `hsLocalMint: true`, and `hubspotRequestForAction` reads that stamp to decide whether a record
+ * id addresses anything in the real portal. `observeResources` MERGES observed fields onto an existing
+ * subject, so if a portal record ever landed on a subject a local create had already minted, an
+ * absent stamp here would leave the stale `true` in place — and the now-genuinely-real record
+ * would be permanently unaddressable, pushing every later edit as a duplicate CREATE. Stamping it
+ * false makes the OBSERVED row win. (`HUBSPOT_LOCAL_ID_BASE` is what makes that collision
+ * implausible in the first place; this is the belt to its braces.)
+ */
+export declare function mapCrmObject(objectType: ObjectType, o: Record<string, unknown>): SyncResource;
+/**
+ * The properties a pull ASKS FOR, per object type.
+ *
+ * HubSpot's list endpoints return only a small default property set unless `?properties=` names
+ * more, so a pull that omitted it would land records with near-empty property maps against a real
+ * portal — while a fixture handing back rich properties would hide that. These are the
+ * HubSpot-defined names the twin models for each type; the portal's CUSTOM properties still need
+ * the schema pull filed as `hubspot.connector.pull_properties`.
+ */
+export declare const PULL_PROPERTIES: Record<ObjectType, string[]>;
+/** Map a HubSpot PublicOwner → a SyncResource. */
+export declare function mapOwner(o: Record<string, unknown>): SyncResource;
+export declare function pollTimestamp(): string;
+/** PULL one CRM object type into the twin's observed log (idempotent). */
+export declare function pullHubspotObjects(execute: HubspotExecute, objectType: ObjectType, root?: string, occurredAt?: string): Promise<number>;
+/** PULL the portal's owners into the twin's observed log (idempotent). */
+export declare function pullHubspotOwners(execute: HubspotExecute, root?: string, occurredAt?: string): Promise<number>;
+/** Full pull: all four standard CRM object types + owners, folded record-type by record-type. */
+export declare function pullHubspotAll(execute: HubspotExecute, root?: string, occurredAt?: string): Promise<Record<string, number>>;
+/**
+ * D7 consumer-facing pull entry point: pull from real HubSpot (the four standard CRM objects +
+ * owners) and fold into the twin in ONE observation, returning the standard
+ * `{ observed, deltasAppended }` result. Idempotent — a re-pull of identical state appends
+ * nothing (deltasAppended drops to 0).
+ */
+export declare function syncHubspotFromReal(execute: HubspotExecute, opts?: {
+    root?: string;
+    occurredAt?: string;
+}): Promise<{
+    observed: number;
+    deltasAppended: number;
+}>;
+/** Translate one pending local action into the real HubSpot REST call it represents, or null. */
+export declare function hubspotRequestForAction(action: TwinAction): {
+    method: 'POST' | 'PATCH' | 'PUT' | 'DELETE';
+    path: string;
+    body?: Record<string, unknown>;
+} | null;
+/** PUSH every pending local action to the real portal; confirm each on success. */
+export declare function pushPendingHubspotActions(execute: HubspotExecute, root?: string, occurredAt?: string): Promise<number>;
+/** A `HubspotExecute` over the kernel's executor. At a REAL boundary the kernel sets the sealed
+ *  credential over these headers (executor.ts); at the twin's own wire any credential is one. */
+export declare function hubspotExecuteOver(execute: RemoteExecute): HubspotExecute;
+/** The refresh adapter: HubSpot enumerates every CRM object type this twin holds, so the whole
+ *  portal comes back without the world having to say what it has. */
+export declare function syncHubspotFromRemote(execute: RemoteExecute, opts?: {
+    root?: string;
+    origin?: string;
+    occurredAt?: string;
+}): Promise<{
+    observed: number;
+    deltasAppended: number;
+}>;
+/**
+ * The perform adapter.
+ *
+ * `hubspotRequestForAction` already carries this pack's hard-won rule: a record stamped
+ * `hsLocalMint` has never been seen by the portal, so it CREATES rather than patching an id that
+ * account does not have. Protocol 2 adds the other half — `ctx.resolve` gives the id HubSpot minted
+ * for a subject this world already deployed, so the patch addresses the real record.
+ */
+export declare function performHubspotAction(execute: RemoteExecute, action: TwinAction, ctx: PerformContext): Promise<PushOutcome>;

package/dist/src/hubspot-connector.js

@@ -0,0 +1,390 @@
+// HubSpot CONNECTOR — the live-vendor pull/push path that gives the HubSpot twin the full
+// "git for SaaS" lifecycle.
+//
+// PULL  (real → twin):  page real CRM records (contacts, companies, deals, tickets) plus the
+//                       portal's owners out of api.hubapi.com, map them → SyncResource[], and
+//                       fold into the observed-event log via observeResources (the kernel dedupes — a
+//                       re-pull of identical state appends nothing).
+// PUSH  (twin → real):  for every PENDING local action, call the real HubSpot CRM API and
+//                       confirmAction on success.
+//
+// The vendor I/O is an INJECTED executor (the auth boundary): the kernel and this pack hold NO
+// HubSpot token and import NO network client. Offline/tests pass a fake executor; live runs pass
+// `liveHubspotExecute(accessToken)`. Same code path either way.
+import { assertBudgetGuardIntact, confirmAction, deployableEntries, observeResources } from '@volter/world-core';
+import { HubspotBudget, HubspotBudgetError, hubspotCallWeight } from "./hubspot-budget.js";
+import { OBJECT_TYPES } from "./hubspot-twin.js";
+const SERVICE = 'hubspot';
+/** Subject types that are twin-internal state and are never pushed to a real portal. */
+const INTERNAL_SUBJECT_TYPES = new Set(['owner']);
+/**
+ * A live executor against the real HubSpot CRM API (the operator's own private-app token).
+ *
+ * THIS IS THE ONE PLACE this pack issues a live `api.hubapi.com` request, and therefore the one
+ * place the rate budget has to be enforced. EVERY call is guarded: the budget is charged BEFORE
+ * the request goes out (`checkBudget`, which THROWS `HubspotBudgetError` instead of returning when
+ * the ceiling or a cooldown says stop) and the response is fed back (`recordCall`) so a
+ * `Retry-After` / 429 / `X-HubSpot-RateLimit-Remaining: 0` signal becomes a persisted cooldown that
+ * makes every later call fail fast WITHOUT touching HubSpot. There is deliberately no OPTION to
+ * disable the guard, and no value a caller can pass for `budget` that yields an unguarded client.
+ * That is NOT immunity from a caller who WANTS one: a fresh `budgetOptions.path` per construction,
+ * or an injected clock, restores the allowance, because the seam tests need cannot be denied to a
+ * determined caller in the same process. See `hubspot-budget.ts` and the kernel's own header.
+ */
+export function liveHubspotExecute(accessToken, base = 'https://api.hubapi.com', opts = {}) {
+    const doFetch = opts.fetchImpl ?? fetch;
+    // `null`/`undefined` (or omitting it) build the default budget. Anything else must be an
+    // UNMODIFIED HubspotBudget: a duck-typed stand-in, a SUBCLASS that overrides `checkBudget`, and
+    // a Proxy that traps it are all refused, because all three are one-liners that would otherwise
+    // hand back a client with no ceiling at all. The default ledger is keyed by a hash of THIS
+    // token — HubSpot limits per app/token, so a cwd-scoped ledger would hand the same token a fresh
+    // allowance per checkout/worktree/CI leg.
+    const budget = opts.budget !== undefined && opts.budget !== null
+        ? assertBudgetGuardIntact(opts.budget, HubspotBudget, 'liveHubspotExecute')
+        : new HubspotBudget({ token: accessToken, ...(opts.budgetOptions ?? {}) });
+    return async (method, path, body) => {
+        const headers = { Authorization: `Bearer ${accessToken}` };
+        const init = { method, headers };
+        if (method !== 'GET' && body !== undefined) {
+            headers['Content-Type'] = 'application/json';
+            init.body = JSON.stringify(body);
+        }
+        const weight = hubspotCallWeight(method, path);
+        // THROWS instead of calling. Nothing below this line runs when the budget refuses.
+        const reservation = budget.checkBudget(weight);
+        const res = await doFetch(`${base}${path}`, init);
+        const resHeaders = {};
+        res.headers.forEach((v, k) => { resHeaders[k.toLowerCase()] = v; });
+        const text = await res.text();
+        let parsed = null;
+        if (text) {
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                parsed = { status: 'error', message: text };
+            }
+        }
+        // Settles the reservation and, on a back-off signal, arms the cooldown. May itself throw (a
+        // `Retry-After` beyond the cap is not something to sleep off) — the cooldown is persisted
+        // first either way, so the refusal survives the throw.
+        // recordCall may THROW after arming the cooldown (a back-off beyond the cap). On a refused
+        // call that louder refusal wins; an answer HubSpot ACCEPTED is kept, so a write that landed is
+        // never recorded as failed and performed again on retry.
+        try {
+            budget.recordCall(weight, resHeaders, { status: res.status, reservation });
+        }
+        catch (error) {
+            if (!(error instanceof HubspotBudgetError) || !res.ok)
+                throw error;
+        }
+        return { httpStatus: res.status, body: parsed };
+    };
+}
+// ── mapping ────────────────────────────────────────────────────────────────────────────────
+/**
+ * Map a HubSpot SimplePublicObject → a SyncResource the kernel can fold.
+ *
+ * The renames are load-bearing, not cosmetic: the kernel's META set (`control-plane/src/
+ * actions.ts`) silently DROPS resource fields named `type`, `id` or `updatedAt`, and HubSpot's
+ * record carries all three. A field literally named `id` would vanish from the projection with no
+ * error at all.
+ *
+ * `hsLocalMint: false` is equally load-bearing. The twin's own create handler stamps
+ * `hsLocalMint: true`, and `hubspotRequestForAction` reads that stamp to decide whether a record
+ * id addresses anything in the real portal. `observeResources` MERGES observed fields onto an existing
+ * subject, so if a portal record ever landed on a subject a local create had already minted, an
+ * absent stamp here would leave the stale `true` in place — and the now-genuinely-real record
+ * would be permanently unaddressable, pushing every later edit as a duplicate CREATE. Stamping it
+ * false makes the OBSERVED row win. (`HUBSPOT_LOCAL_ID_BASE` is what makes that collision
+ * implausible in the first place; this is the belt to its braces.)
+ */
+export function mapCrmObject(objectType, o) {
+    return {
+        type: 'crm_object',
+        id: `${objectType}_${String(o.id)}`,
+        fields: {
+            objectType,
+            hsId: String(o.id),
+            hsCreatedAt: String(o.createdAt ?? ''),
+            hsUpdatedAt: String(o.updatedAt ?? ''),
+            archived: o.archived === true,
+            hsLocalMint: false,
+            props: (o.properties ?? {}),
+        },
+    };
+}
+/**
+ * The properties a pull ASKS FOR, per object type.
+ *
+ * HubSpot's list endpoints return only a small default property set unless `?properties=` names
+ * more, so a pull that omitted it would land records with near-empty property maps against a real
+ * portal — while a fixture handing back rich properties would hide that. These are the
+ * HubSpot-defined names the twin models for each type; the portal's CUSTOM properties still need
+ * the schema pull filed as `hubspot.connector.pull_properties`.
+ */
+export const PULL_PROPERTIES = {
+    contacts: ['email', 'firstname', 'lastname', 'phone', 'company', 'lifecyclestage', 'hubspot_owner_id', 'createdate', 'lastmodifieddate', 'hs_object_id'],
+    companies: ['name', 'domain', 'city', 'industry', 'phone', 'hubspot_owner_id', 'createdate', 'hs_lastmodifieddate', 'hs_object_id'],
+    deals: ['dealname', 'amount', 'dealstage', 'pipeline', 'closedate', 'hubspot_owner_id', 'createdate', 'hs_lastmodifieddate', 'hs_object_id'],
+    tickets: ['subject', 'content', 'hs_pipeline', 'hs_pipeline_stage', 'hs_ticket_priority', 'hubspot_owner_id', 'createdate', 'hs_lastmodifieddate', 'hs_object_id'],
+};
+/** Map a HubSpot PublicOwner → a SyncResource. */
+export function mapOwner(o) {
+    return {
+        type: 'owner',
+        id: `owner_${String(o.id)}`,
+        fields: {
+            ownerId: String(o.id), email: o.email ?? null, firstName: o.firstName ?? null,
+            lastName: o.lastName ?? null, userId: o.userId ?? null, ownerType: o.type ?? 'PERSON',
+            archived: o.archived === true, teams: o.teams ?? [],
+            hsCreatedAt: String(o.createdAt ?? ''), hsUpdatedAt: String(o.updatedAt ?? ''),
+        },
+    };
+}
+/**
+ * A STRICTLY INCREASING poll timestamp — the connector's `occurredAt` default.
+ *
+ * NOT a pinned constant, deliberately. The kernel hashes an observed event over
+ * (`occurredAt` + post-state), so under a fixed poll time a vendor value that REVERTS
+ * (A → B → A across polls) collides with its own earlier observation: `observeResources` reports
+ * `deltasAppended: 1` while nothing lands, and the projection keeps serving the stale value.
+ * Forced strictly increasing within the process so two polls in the same millisecond still get
+ * distinct stamps (`dynadot-connector.ts` is the precedent).
+ */
+let lastPollMs = 0;
+export function pollTimestamp() {
+    const now = Date.now();
+    lastPollMs = now > lastPollMs ? now : lastPollMs + 1;
+    return new Date(lastPollMs).toISOString();
+}
+/**
+ * Read one vendor reply, or THROW.
+ *
+ * A refused pull is NOT an empty account: a connector that maps a failure to an empty resource
+ * list hands the kernel an empty account to fold OVER real observed state, silently deleting it.
+ * HubSpot answers a refusal with a 4xx/5xx AND a `{status:'error', category, message}` body, so
+ * both are checked — a body-only check would miss a bare 401 and a status-only check would miss
+ * an error envelope that arrived with a 2xx.
+ */
+function unwrap(res, what) {
+    const body = (res.body ?? {});
+    if (res.httpStatus < 200 || res.httpStatus >= 300) {
+        throw new Error(`hubspot ${what} refused: HTTP ${res.httpStatus} ${body.category ?? ''} ${body.message ?? ''}`.trim());
+    }
+    if (body.status === 'error') {
+        throw new Error(`hubspot ${what} refused: ${body.category ?? 'error'} ${body.message ?? ''}`.trim());
+    }
+    return body;
+}
+/** Page through one CRM object type, following `paging.next.after` until it is absent. */
+async function collectObjects(execute, objectType, pageSize = 100) {
+    const out = [];
+    let after = null;
+    // Bounded so a vendor (or a fake) that never stops advancing cannot loop forever.
+    for (let page = 0; page < 100; page += 1) {
+        const qs = `limit=${pageSize}&properties=${encodeURIComponent(PULL_PROPERTIES[objectType].join(','))}${after === null ? '' : `&after=${encodeURIComponent(after)}`}`;
+        const body = unwrap(await execute('GET', `/crm/v3/objects/${objectType}?${qs}`), `pull ${objectType}`);
+        const results = Array.isArray(body.results) ? body.results : [];
+        for (const r of results)
+            out.push(mapCrmObject(objectType, r));
+        const paging = body.paging;
+        const next = paging?.next?.after;
+        if (next === undefined || next === null || String(next) === after)
+            break;
+        after = String(next);
+    }
+    return out;
+}
+/** Read the portal's owners. */
+async function collectOwners(execute) {
+    const body = unwrap(await execute('GET', '/crm/v3/owners'), 'pull owners');
+    const results = Array.isArray(body.results) ? body.results : [];
+    return results.map(mapOwner);
+}
+/** PULL one CRM object type into the twin's observed log (idempotent). */
+export async function pullHubspotObjects(execute, objectType, root, occurredAt) {
+    const resources = await collectObjects(execute, objectType);
+    ((__at) => observeResources(SERVICE, resources, { ...(root !== undefined ? { root } : {}), at: __at, batch: `obs:${SERVICE}:${__at}` }))(occurredAt ?? pollTimestamp());
+    return resources.length;
+}
+/** PULL the portal's owners into the twin's observed log (idempotent). */
+export async function pullHubspotOwners(execute, root, occurredAt) {
+    const resources = await collectOwners(execute);
+    ((__at) => observeResources(SERVICE, resources, { ...(root !== undefined ? { root } : {}), at: __at, batch: `obs:${SERVICE}:${__at}` }))(occurredAt ?? pollTimestamp());
+    return resources.length;
+}
+/** Full pull: all four standard CRM object types + owners, folded record-type by record-type. */
+export async function pullHubspotAll(execute, root, occurredAt) {
+    const at = occurredAt ?? pollTimestamp();
+    const counts = {};
+    for (const objectType of OBJECT_TYPES)
+        counts[objectType] = await pullHubspotObjects(execute, objectType, root, at);
+    counts.owners = await pullHubspotOwners(execute, root, at);
+    return counts;
+}
+/**
+ * D7 consumer-facing pull entry point: pull from real HubSpot (the four standard CRM objects +
+ * owners) and fold into the twin in ONE observation, returning the standard
+ * `{ observed, deltasAppended }` result. Idempotent — a re-pull of identical state appends
+ * nothing (deltasAppended drops to 0).
+ */
+export async function syncHubspotFromReal(execute, opts = {}) {
+    const occurredAt = opts.occurredAt ?? pollTimestamp();
+    const resources = [];
+    for (const objectType of OBJECT_TYPES)
+        resources.push(...(await collectObjects(execute, objectType)));
+    resources.push(...(await collectOwners(execute)));
+    const result = ((__at) => observeResources(SERVICE, resources, { ...(opts.root !== undefined ? { root: opts.root } : {}), at: __at, batch: `obs:${SERVICE}:${__at}` }))(occurredAt);
+    return { observed: resources.length, deltasAppended: result.appended };
+}
+// ── push ───────────────────────────────────────────────────────────────────────────────────
+/** Translate one pending local action into the real HubSpot REST call it represents, or null. */
+export function hubspotRequestForAction(action) {
+    if (INTERNAL_SUBJECT_TYPES.has(action.subject.type))
+        return null;
+    const fields = (action.fields ?? {});
+    if (action.subject.type === 'crm_object') {
+        const objectType = String(fields.objectType ?? '');
+        if (!OBJECT_TYPES.includes(objectType))
+            return null;
+        const hsId = fields.hsId === undefined ? null : String(fields.hsId);
+        const props = (fields.props ?? {});
+        // A LOCALLY MINTED id must never be sent to the real portal as a real record id. The twin
+        // mints from `HUBSPOT_LOCAL_ID_BASE` (9e11) upward — an order of magnitude above the largest
+        // HubSpot record id this repo has observed — so such an id addresses NOTHING in a real
+        // account. A local create is therefore a CREATE upstream, and only a record whose id came
+        // from the real portal may be addressed by id. The two sides are told apart by an explicit
+        // stamp, in both directions: the twin's create handler sets `hsLocalMint: true` and every
+        // later write carries it forward, while `mapCrmObject` above sets it FALSE on anything a pull
+        // observed. Without this guard the archive branch below would fire
+        // `DELETE /crm/v3/objects/<type>/<a twin-minted id>` at the operator's real portal — the
+        // exact class of defect groq's round-two review found, one twin-minted id fired at a live
+        // account.
+        const addressable = fields.hsLocalMint !== true && hsId !== null;
+        if (fields.archived === true) {
+            if (!addressable)
+                return null;
+            return { method: 'DELETE', path: `/crm/v3/objects/${objectType}/${hsId}` };
+        }
+        // Strip the system properties HubSpot mints itself — sending them back is rejected upstream.
+        const payload = {};
+        for (const [k, v] of Object.entries(props)) {
+            if (k === 'hs_object_id' || k === 'createdate' || k === 'lastmodifieddate' || k === 'hs_lastmodifieddate')
+                continue;
+            payload[k] = v;
+        }
+        if (addressable)
+            return { method: 'PATCH', path: `/crm/v3/objects/${objectType}/${hsId}`, body: { properties: payload } };
+        return { method: 'POST', path: `/crm/v3/objects/${objectType}`, body: { properties: payload } };
+    }
+    if (action.subject.type === 'property') {
+        const objectType = String(fields.objectType ?? '');
+        const name = String(fields.name ?? '');
+        if (!objectType || !name)
+            return null;
+        if (fields.archived === true)
+            return { method: 'DELETE', path: `/crm/v3/properties/${objectType}/${name}` };
+        return {
+            method: 'POST', path: `/crm/v3/properties/${objectType}`,
+            body: { name, label: fields.label, type: fields.propType, fieldType: fields.fieldType, groupName: fields.groupName, description: fields.description ?? '' },
+        };
+    }
+    if (action.subject.type === 'property_group') {
+        const objectType = String(fields.objectType ?? '');
+        const name = String(fields.name ?? '');
+        if (!objectType || !name)
+            return null;
+        if (fields.archived === true)
+            return { method: 'DELETE', path: `/crm/v3/properties/${objectType}/groups/${name}` };
+        return { method: 'POST', path: `/crm/v3/properties/${objectType}/groups`, body: { name, label: fields.label, displayOrder: fields.displayOrder ?? -1 } };
+    }
+    if (action.subject.type === 'pipeline') {
+        const objectType = String(fields.objectType ?? '');
+        if (!objectType)
+            return null;
+        // Pipeline ids are minted locally (`pipeline_N`) and name nothing upstream, so a local
+        // pipeline is only ever a CREATE; an archive of one has no real target to address.
+        if (fields.archived === true)
+            return null;
+        return { method: 'POST', path: `/crm/v3/pipelines/${objectType}`, body: { label: fields.label, displayOrder: fields.displayOrder ?? 0, stages: fields.stages ?? [] } };
+    }
+    // Associations address BOTH sides by id, so the same locally-minted-id rule applies: a twin
+    // association between two locally created records names nothing in the real portal.
+    if (action.subject.type === 'association')
+        return null;
+    return null;
+}
+/** PUSH every pending local action to the real portal; confirm each on success. */
+export async function pushPendingHubspotActions(execute, root, occurredAt) {
+    const pending = deployableEntries(SERVICE, root);
+    const at = occurredAt ?? pollTimestamp();
+    let pushed = 0;
+    for (const action of pending) {
+        const req = hubspotRequestForAction(action);
+        // An action with no upstream representation is SKIPPED, never aborted — but it is also never
+        // confirmed, so it stays pending and visible rather than silently disappearing.
+        if (!req)
+            continue;
+        const res = await execute(req.method, req.path, req.body);
+        const body = (res.body ?? {});
+        const succeeded = res.httpStatus >= 200 && res.httpStatus < 300 && body.status !== 'error';
+        if (!succeeded)
+            continue;
+        confirmAction({ service: SERVICE, actionId: action.id, subject: action.subject, fields: (action.fields ?? {}), occurredAt: at, ...(root !== undefined ? { root } : {}) });
+        pushed += 1;
+    }
+    return pushed;
+}
+// ── PROTOCOL 2: the pack's half of the real state system ────────────────────────────────────
+/** A `HubspotExecute` over the kernel's executor. At a REAL boundary the kernel sets the sealed
+ *  credential over these headers (executor.ts); at the twin's own wire any credential is one. */
+export function hubspotExecuteOver(execute) {
+    return async (method, path, body) => {
+        const res = await execute({
+            method, path,
+            headers: { accept: 'application/json', 'content-type': 'application/json', authorization: 'Bearer twin' },
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        });
+        let parsed = {};
+        try {
+            parsed = JSON.parse(res.body || '{}');
+        }
+        catch {
+            parsed = {};
+        }
+        return { httpStatus: res.status, body: parsed };
+    };
+}
+/** The refresh adapter: HubSpot enumerates every CRM object type this twin holds, so the whole
+ *  portal comes back without the world having to say what it has. */
+export async function syncHubspotFromRemote(execute, opts = {}) {
+    return syncHubspotFromReal(hubspotExecuteOver(execute), {
+        ...(opts.root !== undefined ? { root: opts.root } : {}),
+        occurredAt: opts.occurredAt ?? pollTimestamp(),
+    });
+}
+/**
+ * The perform adapter.
+ *
+ * `hubspotRequestForAction` already carries this pack's hard-won rule: a record stamped
+ * `hsLocalMint` has never been seen by the portal, so it CREATES rather than patching an id that
+ * account does not have. Protocol 2 adds the other half — `ctx.resolve` gives the id HubSpot minted
+ * for a subject this world already deployed, so the patch addresses the real record.
+ */
+export async function performHubspotAction(execute, action, ctx) {
+    const req = hubspotRequestForAction(action);
+    if (!req) {
+        const op = action.operation ?? `${action.subject.type}.update`;
+        return { externalId: action.subject.id, data: { performed: false, reason: `${op} has no HubSpot mapping — it is this world's own record` } };
+    }
+    const resolved = ctx.resolve(action.subject.type, action.subject.id);
+    const path = resolved === action.subject.id ? req.path : req.path.replace(new RegExp(`/${action.subject.id}(?=$|[/?])`), `/${resolved}`);
+    const answered = await hubspotExecuteOver(execute)(req.method, path, req.body);
+    if (answered.httpStatus < 200 || answered.httpStatus >= 300) {
+        throw new Error(`hubspot ${req.method} ${path} refused: HTTP ${answered.httpStatus} ${JSON.stringify(answered.body).slice(0, 200)}`);
+    }
+    const body = (answered.body ?? {});
+    const externalId = typeof body.id === 'string' ? body.id : resolved;
+    return { externalId, data: body };
+}

package/dist/src/hubspot-deferred-capabilities.d.ts

@@ -0,0 +1,6 @@
+import type { CapabilitySpec } from '@volter/world-tooling';
+/** CRM surface this twin has not built yet — inside the declared scope. */
+export declare const HUBSPOT_UNMODELED_CRM_CAPABILITIES: CapabilitySpec[];
+/** Separate HubSpot PRODUCTS behind the same host — outside this pack's declared CRM scope, and
+ *  not built here; `hubspot-areas.ts` records why each is a separate product. */
+export declare const HUBSPOT_DEFERRED_AREA_CAPABILITIES: CapabilitySpec[];

package/dist/src/hubspot-deferred-capabilities.js

@@ -0,0 +1,64 @@
+/** Not built yet. A plain todo. */
+const unbuilt = (id, area, title, tier) => ({
+    id, area, title, dimension: 'api', tier, expected: 'todo',
+});
+/** CRM surface this twin has not built yet — inside the declared scope. */
+export const HUBSPOT_UNMODELED_CRM_CAPABILITIES = [
+    // ── CRM engagements ───────────────────────────────────────────────────────────────────────
+    unbuilt('hubspot.engagements.notes', 'crm-engagements', 'POST/GET/PATCH/DELETE /crm/v3/objects/notes — note engagements', 'common'),
+    unbuilt('hubspot.engagements.tasks', 'crm-engagements', 'POST/GET/PATCH/DELETE /crm/v3/objects/tasks — task engagements', 'common'),
+    unbuilt('hubspot.engagements.calls', 'crm-engagements', 'POST/GET/PATCH/DELETE /crm/v3/objects/calls — call engagements', 'common'),
+    unbuilt('hubspot.engagements.emails', 'crm-engagements', 'POST/GET/PATCH/DELETE /crm/v3/objects/emails — logged email engagements', 'common'),
+    unbuilt('hubspot.engagements.meetings', 'crm-engagements', 'POST/GET/PATCH/DELETE /crm/v3/objects/meetings — meeting engagements', 'common'),
+    unbuilt('hubspot.engagements.leads', 'crm-engagements', 'POST/GET/PATCH/DELETE /crm/v3/objects/leads — the leads object', 'niche'),
+    unbuilt('hubspot.engagements.feedback_submissions', 'crm-engagements', 'GET /crm/v3/objects/feedback_submissions — NPS/CSAT submissions (read-only)', 'niche'),
+    // ── CRM commerce ──────────────────────────────────────────────────────────────────────────
+    unbuilt('hubspot.commerce.products', 'crm-commerce', 'POST/GET/PATCH/DELETE /crm/v3/objects/products — the product library', 'common'),
+    unbuilt('hubspot.commerce.line_items', 'crm-commerce', 'POST/GET/PATCH/DELETE /crm/v3/objects/line_items — deal line items', 'common'),
+    unbuilt('hubspot.commerce.quotes', 'crm-commerce', 'POST/GET/PATCH/DELETE /crm/v3/objects/quotes — quotes and their approval state', 'niche'),
+    unbuilt('hubspot.commerce.invoices', 'crm-commerce', 'GET /crm/v3/objects/invoices — invoices (read-only)', 'niche'),
+    unbuilt('hubspot.commerce.deal_splits', 'crm-commerce', 'POST /crm/v3/objects/deals/splits/batch/upsert — deal revenue splits', 'niche'),
+    // ── CRM custom object schemas ─────────────────────────────────────────────────────────────
+    unbuilt('hubspot.schemas.create', 'crm-schemas', 'POST /crm-object-schemas/v3/schemas — define a custom object type', 'common'),
+    unbuilt('hubspot.schemas.list', 'crm-schemas', 'GET /crm-object-schemas/v3/schemas — list the portal\'s object type definitions', 'common'),
+    unbuilt('hubspot.schemas.custom_object_records', 'crm-schemas', 'CRUD on /crm/v3/objects/{objectTypeId} records for a custom type (2-3453932 / p{portalId}_name)', 'common'),
+    // ── CRM lists ─────────────────────────────────────────────────────────────────────────────
+    unbuilt('hubspot.lists.create', 'crm-lists', 'POST /crm/v3/lists — create a static or dynamic list', 'common'),
+    unbuilt('hubspot.lists.memberships', 'crm-lists', 'GET/PUT/DELETE /crm/v3/lists/{listId}/memberships — list membership', 'common'),
+    unbuilt('hubspot.lists.search', 'crm-lists', 'POST /crm/v3/lists/search — search list definitions', 'niche'),
+    // ── CRM imports / exports ─────────────────────────────────────────────────────────────────
+    unbuilt('hubspot.imports.create', 'crm-imports-exports', 'POST /crm/v3/imports — start a bulk CSV import job', 'niche'),
+    unbuilt('hubspot.imports.status', 'crm-imports-exports', 'GET /crm/v3/imports/{importId} — poll an import job', 'niche'),
+    unbuilt('hubspot.exports.create', 'crm-imports-exports', 'POST /crm/v3/exports/export/async — start a bulk export job', 'niche'),
+    // ── CRM extensions ────────────────────────────────────────────────────────────────────────
+    unbuilt('hubspot.extensions.cards', 'crm-extensions', 'POST/GET/PATCH/DELETE /crm/v3/extensions/cards-dev/{appId} — CRM card definitions', 'niche'),
+    unbuilt('hubspot.extensions.calling', 'crm-extensions', 'GET/POST /crm/v3/extensions/calling/{appId}/settings — calling provider registration', 'niche'),
+    unbuilt('hubspot.extensions.videoconferencing', 'crm-extensions', 'PUT /crm/v3/extensions/videoconferencing/settings/{appId}', 'niche'),
+    unbuilt('hubspot.extensions.timeline', 'crm-extensions', 'POST /integrators/timeline/v3/events — timeline event ingest + templates', 'niche'),
+];
+/** Separate HubSpot PRODUCTS behind the same host — outside this pack's declared CRM scope, and
+ *  not built here; `hubspot-areas.ts` records why each is a separate product. */
+export const HUBSPOT_DEFERRED_AREA_CAPABILITIES = [
+    // ── CMS ───────────────────────────────────────────────────────────────────────────────────
+    unbuilt('hubspot.cms.pages', 'cms', 'CRUD on /cms/v3/pages/site-pages and /landing-pages', 'niche'),
+    unbuilt('hubspot.cms.blog_posts', 'cms', 'CRUD on /cms/v3/blogs/posts', 'niche'),
+    unbuilt('hubspot.cms.hubdb', 'cms', 'CRUD on /cms/v3/hubdb/tables and their rows', 'niche'),
+    unbuilt('hubspot.cms.url_redirects', 'cms', 'CRUD on /cms/v3/url-redirects', 'niche'),
+    unbuilt('hubspot.cms.source_code', 'cms', 'GET/PUT/DELETE /cms/v3/source-code/{environment}/content/{path}', 'niche'),
+    unbuilt('hubspot.cms.domains', 'cms', 'GET /cms/v3/domains — connected domains', 'niche'),
+    // ── Marketing ─────────────────────────────────────────────────────────────────────────────
+    unbuilt('hubspot.marketing.emails', 'marketing', 'CRUD on /marketing/v3/emails — marketing email assets', 'niche'),
+    unbuilt('hubspot.marketing.forms', 'marketing', 'CRUD on /marketing/v3/forms — HubSpot forms', 'common'),
+    unbuilt('hubspot.marketing.events', 'marketing', 'CRUD on /marketing/v3/marketing-events — marketing event objects', 'niche'),
+    unbuilt('hubspot.marketing.transactional_send', 'marketing', 'POST /marketing/v3/transactional/single-email/send — send a real transactional email', 'niche'),
+    // ── the remaining families, one representative operation each ─────────────────────────────
+    unbuilt('hubspot.automation.custom_actions', 'automation', 'CRUD on /automation/v4/actions/{appId} — custom workflow action definitions', 'niche'),
+    unbuilt('hubspot.conversations.visitor_identification', 'conversations', 'POST /conversations/v3/visitor-identification/tokens/create', 'niche'),
+    unbuilt('hubspot.files.upload', 'files', 'POST /files/v3/files — upload a file to the file manager', 'niche'),
+    unbuilt('hubspot.analytics.send_event', 'analytics-events', 'POST /events/v3/send — send a custom behavioral event', 'niche'),
+    unbuilt('hubspot.analytics.event_definitions', 'analytics-events', 'CRUD on /events/v3/event-definitions', 'niche'),
+    unbuilt('hubspot.communication_preferences.status', 'communication-preferences', 'GET/POST /communication-preferences/v3/status/email/{emailAddress}', 'niche'),
+    unbuilt('hubspot.settings.users', 'settings', 'CRUD on /settings/v3/users — portal user seats', 'niche'),
+    unbuilt('hubspot.settings.business_units', 'settings', 'GET /settings/v3/business-units/user/{userId}', 'niche'),
+    unbuilt('hubspot.webhooks.subscriptions', 'webhooks', 'CRUD on /webhooks/v3/{appId}/subscriptions — app event subscriptions', 'niche'),
+];