@volter/twin-calcom 0.1.0

package/src/calcom-conformance.ts

@@ -0,0 +1,92 @@
+// Cal.com twin CONFORMANCE (dev-only) — an OFFLINE, failable check that the resources the
+// twin projects carry the required v2 fields with the right primitive types. Cal.com has no
+// public per-object JSON Schema we can vendor cleanly, so this encodes the v2 shape we model
+// (required fields + types per resource) as a small hand-authored spec and validates the
+// twin's projection against it. A missing-required field, a wrong type, or a forbidden status
+// value fails the report. Imported LAZILY by the CLI so it never enters the runtime graph.
+import { twinResources } from '@volter/world-core';
+import type { TwinResource } from '@volter/world-core';
+
+const SERVICE = 'calcom';
+
+type FieldSpec = { type: 'string' | 'number' | 'boolean' | 'array' | 'object'; required?: boolean };
+type ResourceSpec = Record<string, FieldSpec>;
+
+// The v2 shape this twin models, per kernel resource type (the projected record's fields).
+const SPEC: Record<string, ResourceSpec> = {
+  booking: {
+    uid: { type: 'string', required: true },
+    bid: { type: 'number', required: true },
+    title: { type: 'string', required: true },
+    status: { type: 'string', required: true },
+    start: { type: 'string', required: true },
+    end: { type: 'string', required: true },
+    duration: { type: 'number', required: true },
+    eventTypeId: { type: 'number', required: true },
+    attendees: { type: 'array', required: true },
+    hosts: { type: 'array', required: true },
+  },
+  event_type: {
+    evtId: { type: 'number', required: true },
+    title: { type: 'string', required: true },
+    slug: { type: 'string', required: true },
+    lengthInMinutes: { type: 'number', required: true },
+    ownerId: { type: 'number', required: true },
+    hidden: { type: 'boolean' },
+  },
+  schedule: {
+    schedId: { type: 'number', required: true },
+    name: { type: 'string', required: true },
+    timeZone: { type: 'string', required: true },
+    availability: { type: 'array', required: true },
+    isDefault: { type: 'boolean', required: true },
+  },
+  team: {
+    teamId: { type: 'number', required: true },
+    name: { type: 'string', required: true },
+    slug: { type: 'string', required: true },
+  },
+  webhook: {
+    whId: { type: 'string', required: true },
+    subscriberUrl: { type: 'string', required: true },
+    triggers: { type: 'array', required: true },
+    active: { type: 'boolean' },
+  },
+};
+
+const VALID_BOOKING_STATUS = new Set(['accepted', 'pending', 'cancelled', 'rejected']);
+
+export type CalcomViolation = { type: string; id: string; field: string; reason: string };
+export type CalcomConformanceReport = { ok: boolean; resourcesChecked: number; fieldsChecked: number; violations: CalcomViolation[] };
+
+function jsType(v: unknown): string {
+  if (Array.isArray(v)) return 'array';
+  if (v === null) return 'null';
+  return typeof v;
+}
+
+export function checkCalcomConformance(opts: { root?: string } = {}): CalcomConformanceReport {
+  const resources = twinResources(SERVICE, opts.root) as unknown as (TwinResource & Record<string, unknown>)[];
+  const violations: CalcomViolation[] = [];
+  let fieldsChecked = 0;
+  let checked = 0;
+  for (const r of resources) {
+    if ((r as Record<string, unknown>).deleted === true) continue;
+    const spec = SPEC[r.type];
+    if (!spec) continue;
+    checked += 1;
+    for (const [field, fs] of Object.entries(spec)) {
+      const v = (r as Record<string, unknown>)[field];
+      if (v === undefined || v === null) {
+        if (fs.required) violations.push({ type: r.type, id: r.id, field, reason: 'missing required field' });
+        continue;
+      }
+      fieldsChecked += 1;
+      if (jsType(v) !== fs.type) violations.push({ type: r.type, id: r.id, field, reason: `expected ${fs.type}, got ${jsType(v)}` });
+    }
+    if (r.type === 'booking' && !VALID_BOOKING_STATUS.has(String((r as Record<string, unknown>).status))) {
+      violations.push({ type: r.type, id: r.id, field: 'status', reason: `invalid booking status ${(r as Record<string, unknown>).status}` });
+    }
+  }
+  return { ok: violations.length === 0, resourcesChecked: checked, fieldsChecked, violations };
+}

package/src/calcom-connector.ts

@@ -0,0 +1,258 @@
+// Cal.com CONNECTOR — the live-vendor pull/push path that gives the Cal.com twin the
+// full "git for SaaS" lifecycle.
+//
+// PULL  (real → twin):  fetch real Cal.com v2 objects (bookings, event types), map the
+//                       v2 `{ status, data }` envelope → SyncResource[], fold into the
+//                       tree via the kernel's observe fold (its own diff — a re-pull of identical
+//                       state appends nothing).
+// PUSH  (twin → real):  for every PENDING local action, call the real Cal.com v2 REST API
+//                       and confirmAction on success.
+//
+// The vendor I/O is an INJECTED executor (the auth boundary): the kernel and this pack hold
+// NO Cal.com key and import NO network client. Offline/tests pass a fake executor; live runs
+// pass `liveCalcomExecute(apiKey)`. Same code path either way.
+import { assertBudgetGuardIntact, observeResources } from '@volter/world-core';
+import type { PerformContext, PushOutcome, RemoteExecute, SyncResource, TwinAction } from '@volter/world-core';
+import { CalcomBudget, CalcomBudgetError, calcomCallWeight, type CalcomBudgetOptions } from './calcom-budget.ts';
+
+const SERVICE = 'calcom';
+
+// Subject types that are twin-internal and never pushed to real Cal.com.
+const INTERNAL_SUBJECT_TYPES = new Set(['slot']);
+
+/**
+ * The injected real-Cal.com boundary. `request` issues ONE Cal.com v2 REST call and returns
+ * the parsed JSON body (the v2 `{ status, data }` envelope). A real client (a raw fetch
+ * wrapper) is structurally assignable; tests pass a fake.
+ */
+export type CalcomExecute = (
+  method: 'GET' | 'POST' | 'PATCH' | 'DELETE',
+  path: string,
+  body?: Record<string, unknown>,
+) => Promise<{ status?: string; data?: any; error?: { message?: string; code?: string }; [k: string]: unknown }>;
+
+/** Construction options for the live executor. `budget` cannot be null and cannot be loosened. */
+export type LiveCalcomOptions = {
+  /** 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?: CalcomBudget;
+  /** Construction options for the default budget (ledger path, clock). Cannot loosen it. */
+  budgetOptions?: CalcomBudgetOptions;
+};
+
+/**
+ * A live executor against the real Cal.com v2 REST API (the user's own `cal_…` key).
+ *
+ * THIS IS THE ONE PLACE this pack issues a live `api.cal.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 `CalcomBudgetError` instead of returning when the
+ * ceiling or a cooldown says stop) and the response is fed back (`recordCall`) so a `Retry-After` /
+ * 429 / `X-RateLimit-Remaining: 0` signal becomes a persisted cooldown that makes every later call
+ * fail fast WITHOUT touching Cal.com. 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. The kernel header states that limit and this does not upgrade it. See
+ * `calcom-budget.ts` for why, and for the limits of the guarantee.
+ */
+export function liveCalcomExecute(
+  apiKey: string,
+  apiVersion = '2024-08-13',
+  base = 'https://api.cal.com',
+  opts: LiveCalcomOptions = {},
+): CalcomExecute {
+  // `null`/`undefined` (or omitting it) build the default budget. Anything else must be an
+  // UNMODIFIED CalcomBudget: 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 (§9 finding, 2026-07-26 — `instanceof` alone was
+  // not a check). What this cannot stop is deliberate sabotage from inside the process (an
+  // injected clock, a throwaway ledger path); the kernel's header says so rather than pretending
+  // otherwise, and this guards the accident and the one-liner, which are the shapes that happen.
+  const doFetch = opts.fetchImpl ?? fetch;
+  // The default ledger is keyed by a hash of THIS key — Cal.com limits per API key, so a cwd-scoped
+  // ledger would hand the same key a fresh allowance per checkout/worktree/CI leg.
+  // ONE expression decides which budget is used, so there is no second, weaker test that could
+  // disagree with the first. `null`/`undefined` (or omitting it) build the default; anything else
+  // must be an UNMODIFIED CalcomBudget — a duck-typed stand-in, a SUBCLASS overriding
+  // `checkBudget`, and a Proxy trapping it are ALL refused, because each is a one-liner that
+  // would otherwise hand back a client with no ceiling (§9 finding, 2026-07-26: `instanceof`
+  // alone was not a check — a subclass satisfied it). What this cannot stop is deliberate
+  // sabotage from inside the process (an injected clock, a throwaway ledger path); the kernel
+  // header states that limit rather than pretending otherwise. This closes the accident and the
+  // one-liner, which are the shapes that actually happen.
+  const budget = opts.budget !== undefined && opts.budget !== null
+    ? assertBudgetGuardIntact(opts.budget, CalcomBudget, 'liveCalcomExecute')
+    : new CalcomBudget({ token: apiKey, ...(opts.budgetOptions ?? {}) });
+  return async (method, path, body) => {
+    const headers: Record<string, string> = {
+      Authorization: `Bearer ${apiKey}`,
+      'cal-api-version': apiVersion,
+    };
+    const init: { method: string; headers: Record<string, string>; body?: string } = { method, headers };
+    if (method !== 'GET' && body) {
+      headers['Content-Type'] = 'application/json';
+      init.body = JSON.stringify(body);
+    }
+    const weight = calcomCallWeight(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}/v2${path}`, init);
+    const resHeaders: Record<string, string> = {};
+    res.headers.forEach((v: string, k: string) => { resHeaders[k.toLowerCase()] = v; });
+    const parsed = (await res.json()) as { status?: string; data?: any };
+    // 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 Cal.com 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 CalcomBudgetError) || !res.ok) throw error;
+    }
+    return parsed;
+  };
+}
+
+/** Map a v2 booking object → a SyncResource the kernel can fold. */
+export function mapBooking(b: Record<string, any>): SyncResource {
+  return {
+    type: 'booking',
+    // the uid IS Cal.com's id for a booking — prefixing it again made an observed booking a DIFFERENT
+    // subject from the written one, so every pull duplicated the row
+    id: String(b.uid),
+    // every field the twin's own write stores, so a refresh from this twin's wire observes what was written
+    fields: {
+      uid: b.uid, bid: b.id, title: b.title, status: b.status, start: b.start, end: b.end,
+      duration: b.duration, eventTypeId: b.eventTypeId, eventType: b.eventType,
+      attendees: b.attendees ?? [], hosts: b.hosts ?? [], guests: b.guests ?? [],
+      location: b.location ?? null, meetingUrl: b.meetingUrl ?? null, metadata: b.metadata ?? {},
+    },
+  };
+}
+
+/** Map a v2 event type object → a SyncResource. */
+export function mapEventType(e: Record<string, any>): SyncResource {
+  return {
+    type: 'event_type',
+    id: `evt_${e.id}`,
+    // every field the twin's own write stores, so a refresh from this twin's wire observes exactly what was
+    // written (protocol 2 shape parity) — the vendor answers all of them on GET /v2/event-types
+    fields: {
+      evtId: e.id, title: e.title, slug: e.slug, lengthInMinutes: e.lengthInMinutes,
+      description: e.description ?? null, ownerId: e.ownerId, hidden: e.hidden ?? false,
+      scheduleId: e.scheduleId ?? null, requiresConfirmation: e.requiresConfirmation ?? false,
+      bookingUrl: e.bookingUrl, locations: e.locations ?? [], bookingFields: e.bookingFields ?? [],
+      seatsPerTimeSlot: e.seatsPerTimeSlot ?? null, seatsShowAttendees: e.seatsShowAttendees ?? false,
+      seatsShowAvailabilityCount: e.seatsShowAvailabilityCount ?? true,
+      beforeEventBuffer: e.beforeEventBuffer ?? 0, afterEventBuffer: e.afterEventBuffer ?? 0,
+      minimumBookingNotice: e.minimumBookingNotice ?? 0,
+    },
+  };
+}
+
+// A pinned occurredAt keeps a pull deterministic/idempotent under test.
+const PULL_AT = '2026-07-01T00:00:00.000Z';
+
+/** Fetch + map real bookings into SyncResource[] (no fold) — shared by pull + syncFromReal. */
+async function collectCalcomBookings(execute: CalcomExecute): Promise<SyncResource[]> {
+  const res = await execute('GET', '/bookings');
+  const rows: any[] = Array.isArray(res.data) ? res.data : (res.data?.bookings ?? []);
+  return rows.map(mapBooking);
+}
+
+/** Fetch + map real event types into SyncResource[] (no fold) — shared by pull + syncFromReal. */
+async function collectCalcomEventTypes(execute: CalcomExecute): Promise<SyncResource[]> {
+  const res = await execute('GET', '/event-types');
+  const rows: any[] = Array.isArray(res.data) ? res.data : (res.data?.eventTypes ?? []);
+  return rows.map(mapEventType);
+}
+
+/** PULL bookings from the real account into the twin's observed log (idempotent). */
+export async function pullCalcomBookings(execute: CalcomExecute, root?: string, occurredAt = PULL_AT): Promise<number> {
+  const resources = await collectCalcomBookings(execute);
+  observeResources(SERVICE, resources.map((r) => ({ type: r.type, id: r.id, fields: r.fields })), { ...(root !== undefined ? { root } : {}), at: occurredAt, batch: `obs:${SERVICE}:${occurredAt}` });
+  return resources.length;
+}
+
+/** PULL event types from the real account into the twin's observed log (idempotent). */
+export async function pullCalcomEventTypes(execute: CalcomExecute, root?: string, occurredAt = PULL_AT): Promise<number> {
+  const resources = await collectCalcomEventTypes(execute);
+  observeResources(SERVICE, resources.map((r) => ({ type: r.type, id: r.id, fields: r.fields })), { ...(root !== undefined ? { root } : {}), at: occurredAt, batch: `obs:${SERVICE}:${occurredAt}` });
+  return resources.length;
+}
+
+/** Full pull: bookings + event types. */
+export async function pullCalcomAll(execute: CalcomExecute, root?: string, occurredAt = PULL_AT): Promise<{ bookings: number; eventTypes: number }> {
+  const bookings = await pullCalcomBookings(execute, root, occurredAt);
+  const eventTypes = await pullCalcomEventTypes(execute, root, occurredAt);
+  return { bookings, eventTypes };
+}
+
+/**
+ * D7 consumer-facing pull entry point: pull from real Cal.com (bookings + event types) and fold
+ * into the twin in ONE observed batch, returning the standard `{ observed, deltasAppended }`
+ * result. Idempotent — a re-pull of identical state appends nothing (deltasAppended drops to 0).
+ */
+export async function syncCalcomFromReal(
+  execute: CalcomExecute,
+  opts: { root?: string; occurredAt?: string } = {},
+): Promise<{ observed: number; deltasAppended: number }> {
+  const occurredAt = opts.occurredAt ?? PULL_AT;
+  const bookings = await collectCalcomBookings(execute);
+  const eventTypes = await collectCalcomEventTypes(execute);
+  const resources = [...bookings, ...eventTypes];
+  // protocol 2: the observation lands on the head through the kernel's fold — one batch, one instant
+  const report = observeResources(SERVICE, resources.map((r) => ({ type: r.type, id: r.id, fields: r.fields })), { ...(opts.root !== undefined ? { root: opts.root } : {}), at: occurredAt, batch: `obs:${SERVICE}:${occurredAt}` });
+  return { observed: report.observed, deltasAppended: report.appended };
+}
+
+/** Translate one pending local action into the real Cal.com v2 REST call it represents. */
+export function calcomRequestForAction(action: TwinAction): { method: 'GET' | 'POST' | 'PATCH' | 'DELETE'; path: string; body?: Record<string, unknown> } | null {
+  if (INTERNAL_SUBJECT_TYPES.has(action.subject.type)) return null;
+  const fields = (action.fields ?? {}) as Record<string, unknown>;
+  if (action.subject.type === 'booking') {
+    if (fields.status === 'cancelled') return { method: 'POST', path: `/bookings/${String(fields.uid ?? action.subject.id)}/cancel`, body: {} };
+    return { method: 'POST', path: '/bookings', body: fields };
+  }
+  if (action.subject.type === 'event_type') return { method: 'POST', path: '/event-types', body: fields };
+  if (action.subject.type === 'schedule') return { method: 'POST', path: '/schedules', body: fields };
+  if (action.subject.type === 'webhook') return { method: 'POST', path: '/webhooks', body: fields };
+  return null;
+}
+
+// ── PROTOCOL 2: the pack's half of the real state system ────────────────────────────────────
+/** The pack's executor over the kernel's: the same Cal.com v2 call, carried by the head. */
+export function calcomExecuteOver(execute: RemoteExecute): CalcomExecute {
+  return async (method, path, body) => {
+    const res = await execute({ method, path, headers: { accept: 'application/json', ...(body ? { 'content-type': 'application/json' } : {}) }, ...(body === undefined ? {} : { body: JSON.stringify(body) }) });
+    let parsed: Record<string, unknown> = {};
+    if (res.body) { try { parsed = JSON.parse(res.body) as Record<string, unknown>; } catch { parsed = { status: 'error', error: { message: res.body } }; } }
+    return parsed as ReturnType<CalcomExecute> extends Promise<infer R> ? R : never;
+  };
+}
+/** The refresh adapter: pull the account's bookings and event types through the executor. */
+export async function syncCalcomFromRemote(execute: RemoteExecute, opts: { root?: string; origin?: string; occurredAt?: string } = {}): Promise<{ observed: number; deltasAppended: number }> {
+  return syncCalcomFromReal(calcomExecuteOver(execute), { ...(opts.root !== undefined ? { root: opts.root } : {}), ...(opts.occurredAt !== undefined ? { occurredAt: opts.occurredAt } : {}) });
+}
+/** The perform adapter: one entry crosses to Cal.com, or settles with the reason it never could.
+ *  Cal.com v2 answers success with `status: 'success'`; an error envelope carries `status: 'error'`,
+ *  and the head must hear that as a refusal rather than mark an unwritten booking across. */
+export async function performCalcomAction(execute: RemoteExecute, action: TwinAction, ctx: PerformContext): Promise<PushOutcome> {
+  return performCalcomEntry(calcomExecuteOver(execute), action, ctx);
+}
+/** The same perform, one level down: over the pack's OWN client, so a suite holding a Cal.com fake can drive
+ *  the identical path the head drives over the kernel's executor. */
+export async function performCalcomEntry(execute: CalcomExecute, action: TwinAction, _ctx?: PerformContext): Promise<PushOutcome> {
+  const req = calcomRequestForAction(action);
+  if (!req) return { externalId: action.subject.id, data: { performed: false, reason: `${action.subject.type} is the twin's own record — nothing at Cal.com to write` } };
+  const res = await execute(req.method, req.path, req.body);
+  if (res.status !== 'success' || res.error !== undefined) {
+    throw new Error(`calcom perform ${action.operation ?? action.subject.type} refused: ${JSON.stringify(res.error ?? res).slice(0, 200)}`);
+  }
+  const data = (res.data ?? {}) as Record<string, unknown>;
+  const vendorId = data.uid ?? data.id;
+  return { externalId: vendorId === undefined ? action.subject.id : String(vendorId) };
+}

package/src/calcom-mirror-ui.ts

@@ -0,0 +1,110 @@
+// Cal.com MIRROR UI — a Cal.com-bookings-dashboard-like view served as a React/TSX app
+// (bundled by Bun). It renders by consuming the twin's OWN v2 REST API on the same origin
+// (/v2/bookings, /v2/event-types) — the same endpoints a real client uses — so the screen is
+// data-coupled to real twin state (API↔UI parity), not a hardcoded shell.
+// PURE FRONTEND (R3): the mirror imports no handler and no twin internals — it MOUNTS the pack's
+// own fetch adapter as its API backend and reads every byte of state back over the wire.
+import { readFile } from 'node:fs/promises';
+import { bundleClient, fileResponse } from '@volter/world-core';
+import { serveHttp } from '@volter/world-core';
+import { createCalcomTwinFetch } from './calcom-server.ts';
+
+const CLIENT_ENTRY = () => new URL('../client/calcom-mirror.tsx', import.meta.url).pathname;  // lazy: workerd rejects top-level relative URL from import.meta.url (bundled via pack index)
+const CLIENT_CSS = () => new URL('../client/calcom-mirror.css', import.meta.url).pathname;  // lazy: workerd rejects top-level relative URL from import.meta.url (bundled via pack index)
+
+// ---------------------------------------------------------------------------
+// Pure, dependency-free render/format helpers (importable by the React client; Bun
+// tree-shakes the server-only exports out of the browser bundle). Keep free of any
+// @volter/world-core / Bun / handler usage.
+// ---------------------------------------------------------------------------
+
+export type CalcomRow = Record<string, any>;
+
+/** Status pill tone for a booking status. */
+export type PillTone = 'ok' | 'warn' | 'bad' | '';
+export function bookingTone(status: unknown): PillTone {
+  const s = String(status ?? '').toLowerCase();
+  if (s === 'accepted') return 'ok';
+  if (s === 'pending') return 'warn';
+  if (s === 'cancelled' || s === 'rejected') return 'bad';
+  return '';
+}
+
+/** Format a booking's time window as a short "Jul 1, 16:00 → 16:30 UTC" label. */
+export function formatWindow(start: unknown, end: unknown): string {
+  const s = typeof start === 'string' ? new Date(start) : null;
+  const e = typeof end === 'string' ? new Date(end) : null;
+  if (!s || Number.isNaN(s.getTime())) return '—';
+  const day = s.toISOString().slice(0, 10);
+  const hm = (d: Date) => d.toISOString().slice(11, 16);
+  return e && !Number.isNaN(e.getTime()) ? `${day} ${hm(s)} → ${hm(e)} UTC` : `${day} ${hm(s)} UTC`;
+}
+
+/** The single attendee label a bookings row shows ("Name <email>"). */
+export function attendeeLabel(attendees: unknown): string {
+  if (!Array.isArray(attendees) || attendees.length === 0) return '—';
+  const a = attendees[0] as Record<string, unknown>;
+  return a?.email ? `${a.name ?? ''} <${a.email}>`.trim() : String(a?.name ?? '—');
+}
+
+const APP_SHELL = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<base href="/"><title>Cal.com UI mirror (twin)</title><link rel="stylesheet" href="assets/styles.css"></head>
+<body><div id="root"></div><script type="module" src="assets/app.js"></script></body></html>`;
+
+let clientBundle: Promise<string> | null = null;
+/** Build the React/TSX dashboard client to browser JS (Bun bundles TSX); cached. */
+export function buildCalcomMirrorClient(): Promise<string> {
+  if (!clientBundle) {
+    clientBundle = bundleClient(CLIENT_ENTRY())
+      .catch((error) => { clientBundle = null; throw error; });
+  }
+  return clientBundle;
+}
+
+/** Serve the Cal.com dashboard mirror UI (React app) + its backing v2 REST API. */
+export async function createCalcomMirrorServer(options: { root?: string; port?: number; readOnly?: boolean }): Promise<{ port: number; stop: () => void }> {
+  const twin = createCalcomTwinFetch(options);
+  const server = await serveHttp({
+    // LOOPBACK-SPECIFIC bind (2026-08-20, the roving ui-verify flake): with the default
+    // wildcard hostname, `port: 0` can be handed a port some long-running app already LISTENS
+    // on at 127.0.0.1 (SO_REUSEADDR allows the overlapping non-identical bind), and the more
+    // specific loopback listener then shadows this server for every 127.0.0.1 fetch — the
+    // verify talks to a STRANGER (captured: a desktop app's asset server answering 404s on the
+    // mirror's port). Binding 127.0.0.1 makes the kernel allocate a port that is actually free
+    // on loopback, so the verify's fetches deterministically reach THIS server.
+    hostname: '127.0.0.1',
+    port: options.port ?? 0,
+    idleTimeout: 60,
+    async fetch(request) {
+      const url = new URL(request.url);
+      if (request.method === 'GET' && url.pathname === '/assets/app.js') {
+        try { return new Response(await buildCalcomMirrorClient(), { headers: { 'content-type': 'text/javascript; charset=utf-8' } }); }
+        catch (error) { return new Response(String(error), { status: 500 }); }
+      }
+      if (request.method === 'GET' && url.pathname === '/assets/styles.css') {
+        return fileResponse(CLIENT_CSS(), { headers: { 'content-type': 'text/css; charset=utf-8' } });
+      }
+      if (request.method === 'GET' && (url.pathname === '/' || url.pathname === '')) {
+        return new Response(APP_SHELL, { headers: { 'content-type': 'text/html; charset=utf-8' } });
+      }
+      // everything else → the twin's OWN FETCH ADAPTER (composition, R2/R3): the React client
+      // fetches the vendor's real v2 paths, and the adapter is the same closure
+      // `createCalcomTwinServer` serves, so there is exactly ONE serving code path — the keyless
+      // `GET /twin` door, the world clock, `cal-api-version` threading and an honourable
+      // `readOnly` all come from it, and the mirror port cannot drift from the API port.
+      return twin(request);
+    },
+  });
+  return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}
+
+/** The app-shell HTML (pure, for tests). The dashboard itself is the React client. */
+export function calcomMirrorHtml(): string {
+  return APP_SHELL;
+}
+
+/** The mirror's stylesheet, for a host serving the shell's `assets/styles.css` itself (the hosted mirror mount). */
+export function calcomMirrorStyles(): Promise<string> {
+  return readFile(CLIENT_CSS(), 'utf8');
+}

package/src/calcom-perform-harness.ts

@@ -0,0 +1,24 @@
+// A MINIATURE OF THE HEAD, for this pack's own claims and suites (protocol 2). The kernel's own loop
+// (`performEntries`) needs a bound root and a sealed credential a unit test does not have; this is the same
+// shape without one — the same `deployableEntries`, the pack's adapter, the same `confirmAction`. Not on the
+// serve path, not exported from the pack.
+import { confirmAction, deployableEntries, worldNow } from '@volter/world-core';
+import { performCalcomEntry, type CalcomExecute } from './calcom-connector.ts';
+
+export async function performPending(execute: CalcomExecute, opts: { root?: string; occurredAt?: string } = {}): Promise<number> {
+  let pushed = 0;
+  for (const entry of deployableEntries('calcom', opts.root)) {
+    // the head stops the batch on a vendor refusal and marks nothing across; the harness reports the same
+    // by simply stopping here — an entry the vendor refused stays the head's to deploy
+    let outcome;
+    try { outcome = await performCalcomEntry(execute, entry); } catch { return pushed; }
+    if (outcome.data && (outcome.data as { performed?: boolean }).performed === false) continue;
+    confirmAction({
+      service: 'calcom', actionId: entry.id, subject: entry.subject, fields: entry.fields ?? {},
+      occurredAt: opts.occurredAt ?? worldNow(), vendorSubjectId: outcome.externalId, receipt: { status: 'deployed' },
+      ...(opts.root !== undefined ? { root: opts.root } : {}),
+    });
+    pushed += 1;
+  }
+  return pushed;
+}

package/src/calcom-server.ts

@@ -0,0 +1,39 @@
+// Cal.com twin HTTP server — serve the full Cal.com v2 twin handler over HTTP so an
+// unmodified scheduling client (or the QA backend sandbox's api.cal.com interception)
+// works against it. JSON bodies pass through to the handler. Writable by default; pass
+// readOnly to reject writes (R4). Auth is a faked-locally Bearer key — accepted, never
+// verified against a real Cal.com (a twin fakes auth locally).
+//
+// FETCH-FIRST (runtime contract R12b): the serve path is the plain fetch below, built from the
+// kernel's ONE adaptation (`createTwinFetchFromHandler`) with the `cal-api-version` threading as
+// its per-request `extras`; the server is one line of Bun.serve around that same closure.
+import { serveHttp } from '@volter/world-core';
+import { handleCalcomTwinRequest } from './calcom-twin.ts';
+import { createTwinFetchFromHandler, statefulTwinManifest } from '@volter/world-core';
+
+/** Options every Cal.com-twin HTTP surface needs, independent of who owns the socket. */
+export interface CalcomTwinFetchOptions {
+  root?: string;
+  readOnly?: boolean;
+}
+
+export function createCalcomTwinFetch(options: CalcomTwinFetchOptions = {}): (request: Request) => Promise<Response> {
+  return createTwinFetchFromHandler(handleCalcomTwinRequest, {
+    ...options,
+    manifest: statefulTwinManifest({ vendor: 'calcom', twinOf: 'the Cal.com v2 API', stores: 'event types, bookings, schedules and availability' }),
+    // Cal.com v2 pins endpoint behavior with the `cal-api-version` header; thread it through.
+    extras: (request) => {
+      const apiVersion = request.headers.get('cal-api-version');
+      return apiVersion ? { apiVersion } : {};
+    },
+  });
+}
+
+export async function createCalcomTwinServer(options: { root?: string; port?: number; readOnly?: boolean }): Promise<{ port: number; stop: () => void }> {
+  const server = await serveHttp({
+    port: options.port ?? 0,
+    idleTimeout: 60,
+    fetch: createCalcomTwinFetch(options),
+  });
+  return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}