@volter/twin-runhuman 0.1.0

package/src/runhuman-capabilities.ts

@@ -0,0 +1,470 @@
+// Runhuman 1 capability manifest — the EXPECTED REAL-PRODUCT SURFACE, authored top-down from RH1's
+// own source at volter-ai/runhuman 2f2fcb2c5 (the vendor is our own product, so its source is the
+// specification). The denominator is the union of three first-party inventories:
+//   - the public REST reference, packages/static-site/src/content/docs/api.mdx (46 operations:
+//     jobs, organizations, projects, API keys, PATs, templates, schedules, GitHub, auth, billing);
+//   - the jobs router, packages/api/src/routes/jobs/jobs.routes.ts (32 operations: the customer's
+//     job reads and the tester's claim-to-completion lifecycle — the surface RH2's
+//     human-marketplace provider and the tester app drive);
+//   - the customer-API allowlist, packages/shared/src/routes/customer-api-routes.ts (the routes
+//     RH1 ships in its CLI / MCP server), plus GET /api/projects/:projectId/jobs from
+//     routes/projects.routes.ts.
+// One capability per route × method (83), plus the behavioral and connector capabilities a real
+// integration relies on. Most entries are `todo`; coverage reads LOW on purpose.
+//
+// The DONE slice is what the twin serves (src/runhuman-twin.ts, README ## Coverage). Every verify()
+// drives the handler the fetch adapter wraps (`handleRunhumanTwinRequest`) on a FRESH temp root at
+// pinned instants, seeds through the twin-only `/_twin/*` routes (RH1 creates orgs, projects, keys
+// and testers outside the job API), and asserts VALUES plus the RH1 refusals its title names.
+//
+// UI: none. RH1's customers post jobs from code, and the tester web app's core loop is the tester
+// API below (census.json ui.needsUi:false), so there is no `mirror` area.
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { checkCapabilities, type CapabilityReport, type CapabilitySpec, verifyBoundary } from '@volter/world-tooling';
+import { handleRunhumanTwinRequest, type RunhumanTwinResponse } from './runhuman-twin.ts';
+
+type Body = Record<string, any>;
+type Step = { m: string; p: string; b?: unknown; raw?: string; auth?: string | null; at?: number; headers?: Record<string, string> };
+type H = (s: Step) => Promise<RunhumanTwinResponse>;
+
+const T0 = Date.parse('2026-03-01T12:00:00.000Z');
+/** The pinned instant `s` seconds after T0. */
+const iso = (s = 0) => new Date(T0 + s * 1000).toISOString();
+
+const KEY = 'rh_capability_acme';
+const OTHER_KEY = 'rh_capability_other';
+const PAID_KEY = 'rh_capability_paid';
+const TESS = 'Bearer clerk_tess@x.test';
+const MIKE = 'Bearer clerk_mike@x.test';
+
+/** A fresh world: org-1 (Acme) owns proj-1 (Web, default https://app.example.com) and KEY;
+ *  org-2 owns proj-2 and OTHER_KEY; org-3 (Paid, an active subscription) owns proj-3 and PAID_KEY;
+ *  testers tess and mike (desktop, English). */
+async function withWorld(label: string, steps: (h: H) => Promise<boolean>): Promise<boolean> {
+  const root = mkdtempSync(join(tmpdir(), 'runhuman-cap-'));
+  const h: H = (s) =>
+    handleRunhumanTwinRequest({
+      method: s.m,
+      path: s.p,
+      ...(s.raw !== undefined ? { body: s.raw } : s.b !== undefined ? { body: JSON.stringify(s.b) } : {}),
+      headers: { ...(s.auth === null ? {} : { authorization: s.auth ?? `Bearer ${KEY}` }), 'content-type': 'application/json', ...(s.headers ?? {}) },
+      occurredAt: iso(s.at ?? 0),
+      root,
+    });
+  try {
+    return await verifyBoundary(label, async () => {
+      const seeds: Array<[string, Body]> = [
+        ['organizations', { id: 'org-1', name: 'Acme' }],
+        ['organizations', { id: 'org-2', name: 'Other' }],
+        ['organizations', { id: 'org-3', name: 'Paid', hasActiveSubscription: true }],
+        ['projects', { id: 'proj-1', organizationId: 'org-1', name: 'Web', defaultUrl: 'https://app.example.com' }],
+        ['projects', { id: 'proj-2', organizationId: 'org-2', name: 'Elsewhere' }],
+        ['projects', { id: 'proj-3', organizationId: 'org-3', name: 'Paid web' }],
+        ['api-keys', { organizationId: 'org-1', key: KEY }],
+        ['api-keys', { organizationId: 'org-2', key: OTHER_KEY }],
+        ['api-keys', { organizationId: 'org-3', key: PAID_KEY }],
+        ['testers', { email: 'tess@x.test', alias: 'tess' }],
+        ['testers', { email: 'mike@x.test', alias: 'mike' }],
+      ];
+      for (const [kind, body] of seeds) {
+        const r = await h({ m: 'POST', p: `/_twin/${kind}`, b: body, auth: null });
+        if (r.status !== 201) throw new Error(`seed ${kind} answered ${r.status}`);
+      }
+      return steps(h);
+    });
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+const b = (r: RunhumanTwinResponse) => r.body as Body;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+
+async function createJob(h: H, extra: Body = {}, at = 0): Promise<string> {
+  const r = await h({ m: 'POST', p: '/api/jobs', b: { projectId: 'proj-1', url: 'https://app.example.com/checkout', description: 'Buy the cheapest item', ...extra }, at });
+  if (r.status !== 201) throw new Error(`create answered ${r.status}`);
+  return String(b(r).jobId);
+}
+/** Claim as a tester and return the testerToken the claim minted (from its webTestLink). */
+async function claim(h: H, jobId: string, who = TESS, at = 0): Promise<string> {
+  const r = await h({ m: 'POST', p: `/api/jobs/${jobId}/claim`, b: { claimSource: 'tester-portal' }, auth: who, at });
+  if (r.status !== 200) throw new Error(`claim answered ${r.status}`);
+  const token = new URL(String(b(r).webTestLink)).searchParams.get('testerToken');
+  if (!token) throw new Error('claim returned no testerToken');
+  return token;
+}
+const tester = (token: string) => `Bearer ${token}`;
+/** Submit a result and run the pipeline to a verdict: process-results → poll (extract) →
+ *  issue-review continue → poll (finalize). */
+async function toVerdict(h: H, jobId: string, token: string, success: boolean | undefined, at: number): Promise<boolean> {
+  const auth = tester(token);
+  const patch = await h({ m: 'PATCH', p: `/api/tester/jobs/${jobId}`, b: { result: { explanation: 'walked the flow', data: success === undefined ? {} : { success } } }, auth, at });
+  const pr = await h({ m: 'POST', p: `/api/tester/jobs/${jobId}/process-results`, b: {}, auth, at });
+  const poll1 = await h({ m: 'GET', p: `/api/tester/jobs/${jobId}/processing/${b(pr).processingJobId}`, auth, at });
+  const review = await h({ m: 'POST', p: `/api/tester/jobs/${jobId}/issue-review`, b: { action: 'continue' }, auth, at });
+  const poll2 = await h({ m: 'GET', p: `/api/tester/jobs/${jobId}/processing/${b(review).processingJobId}`, auth, at });
+  return patch.status === 200 && pr.status === 200 && b(poll1).status === 'completed' && review.status === 200 && b(poll2).status === 'completed';
+}
+
+const done = (id: string, area: string, title: string, dimension: CapabilitySpec['dimension'], tier: CapabilitySpec['tier'], verify: CapabilitySpec['verify']): CapabilitySpec => ({ id, area, title, dimension, tier, expected: 'done', verify });
+const todo = (id: string, area: string, title: string, dimension: CapabilitySpec['dimension'], tier: CapabilitySpec['tier']): CapabilitySpec => ({ id, area, title, dimension, tier, expected: 'todo' });
+
+export const RUNHUMAN_CAPABILITIES: CapabilitySpec[] = [
+  // ── JOBS (customer side) ────────────────────────────────────────────────────────────────────
+  done('runhuman.jobs.create', 'jobs', 'POST /api/jobs creates a pending job (201 {jobId, message}, RH1 defaults 15+5 min) and refuses a missing key (401), a schema-invalid body (400 FST_ERR_VALIDATION), a non-http URL (400) and another org\'s project (403)', 'api', 'core', () =>
+    withWorld('runhuman.jobs.create', async (h) => {
+      const c = await h({ m: 'POST', p: '/api/jobs', b: { projectId: 'proj-1', url: 'https://app.example.com/checkout', description: 'Buy the cheapest item' } });
+      if (!(c.status === 201 && UUID.test(String(b(c).jobId)) && b(c).message === 'Job created successfully. Use GET /api/jobs/:id to check status.')) return false;
+      const g = await h({ m: 'GET', p: `/api/jobs/${b(c).jobId}` });
+      if (!(b(g).status === 'pending' && b(g).targetDurationMinutes === 15 && b(g).maxExtensionMinutes === 5 && b(g).description === 'Buy the cheapest item' && b(g).createdAt === iso(0))) return false;
+      const noAuth = await h({ m: 'POST', p: '/api/jobs', b: { projectId: 'proj-1', url: 'https://a.test', description: 'x' }, auth: null });
+      const badBody = await h({ m: 'POST', p: '/api/jobs', b: { projectId: 'proj-1', url: 5, description: 'x' } });
+      const ftp = await h({ m: 'POST', p: '/api/jobs', b: { projectId: 'proj-1', url: 'ftp://files.test', description: 'x' } });
+      const foreign = await h({ m: 'POST', p: '/api/jobs', b: { projectId: 'proj-2', url: 'https://a.test', description: 'x' } });
+      return noAuth.status === 401 && b(noAuth).error === 'Unauthorized'
+        && badBody.status === 400 && b(badBody).code === 'FST_ERR_VALIDATION' && b(badBody).error === 'Invalid request body: url: Expected string, received number'
+        && ftp.status === 400 && b(ftp).error === 'Invalid URL protocol "ftp:". URL must start with http:// or https://'
+        && foreign.status === 403 && b(foreign).error === 'Access denied: API key organization does not match project organization';
+    })),
+  done('runhuman.jobs.create.active_job_limit', 'jobs', 'POST /api/jobs holds an organization to 12 active jobs (the 13th is 429 ACTIVE_JOB_LIMIT) and a job that leaves the active set frees its slot', 'api', 'common', () =>
+    withWorld('runhuman.jobs.create.active_job_limit', async (h) => {
+      const ids: string[] = [];
+      for (let i = 0; i < 12; i++) ids.push(await createJob(h, {}, i));
+      const over = await h({ m: 'POST', p: '/api/jobs', b: { projectId: 'proj-1', url: 'https://app.example.com', description: '13th' }, at: 20 });
+      if (!(over.status === 429 && b(over).code === 'ACTIVE_JOB_LIMIT' && b(over).statusCode === 429)) return false;
+      const token = await claim(h, ids[0]!, TESS, 30);
+      const end = await h({ m: 'POST', p: `/api/tester/jobs/${ids[0]}/end`, b: { action: 'clear_and_cancel', note: 'cannot load' }, auth: tester(token), at: 40 });
+      const again = await h({ m: 'POST', p: '/api/jobs', b: { projectId: 'proj-1', url: 'https://app.example.com', description: '13th' }, at: 50 });
+      return end.status === 200 && again.status === 201;
+    })),
+  done('runhuman.jobs.create.surface_rules', 'jobs', 'POST /api/jobs answers RH1\'s claim-surface rules: a deviceClass/requiredDevices conflict is a 201 with a warning, a URL off the project\'s default host adds projectUrlMismatch, and external capture without a desktop-only surface is 400 VALIDATION_ERROR', 'api', 'common', () =>
+    withWorld('runhuman.jobs.create.surface_rules', async (h) => {
+      const conflict = await h({ m: 'POST', p: '/api/jobs', b: { projectId: 'proj-1', url: 'https://other.example.org', description: 'x', deviceClass: 'desktop', requiredDevices: ['ios'] } });
+      const external = await h({ m: 'POST', p: '/api/jobs', b: { projectId: 'proj-1', url: 'https://app.example.com', description: 'x', metadata: { captureMode: 'external' } } });
+      const externalDesktop = await h({ m: 'POST', p: '/api/jobs', b: { projectId: 'proj-1', url: 'https://www.app.example.com', description: 'x', deviceClass: 'desktop', metadata: { captureMode: 'external' } } });
+      const warnings = b(conflict).warnings as string[] | undefined;
+      return conflict.status === 201 && warnings?.length === 1 && warnings[0]!.startsWith('Device Class is set to Desktop, but the required device(s) iOS force the claim surface to mobile only.')
+        && b(conflict).projectUrlMismatch?.targetHost === 'other.example.org' && b(conflict).projectUrlMismatch?.projectDefaultHost === 'app.example.com' && b(conflict).projectUrlMismatch?.projectName === 'Web'
+        && external.status === 400 && b(external).code === 'VALIDATION_ERROR' && b(external).error === 'External capture requires a desktop browser assignment.'
+        && externalDesktop.status === 201 && b(externalDesktop).projectUrlMismatch === undefined && b(externalDesktop).warnings === undefined;
+    })),
+  todo('runhuman.jobs.create.integrations', 'jobs', 'POST /api/jobs branches that run RH1 services: templates, PR/issue test-plan generation, KB-enhanced instructions, githubRepos access and project auto-creation, outputSchema, attachments, sideload/social-video tiers, issue-tracker auto-create', 'api', 'common'),
+  done('runhuman.jobs.get', 'jobs', 'GET /api/jobs/:jobId returns the enriched, result-gated job (jobUrl, projectName, no testerToken in metadata; without a subscription the conversation is withheld and the owning org named, with one the testerResponse is served); unknown is 404, another org\'s key is 403', 'api', 'core', () =>
+    withWorld('runhuman.jobs.get', async (h) => {
+      const id = await createJob(h);
+      await claim(h, id, TESS, 10);
+      const g = await h({ m: 'GET', p: `/api/jobs/${id}` });
+      const j = b(g);
+      if (!(g.status === 200 && j.id === id && j.status === 'working' && j.testerAlias === 'tess' && j.jobUrl === `https://runhuman.com/dashboard/proj-1/jobs/${id}`
+        && j.projectName === 'Web' && j.richResultsGated === true && j.ownerOrganizationName === 'Acme' && j.recordingStatus === 'none'
+        && j.metadata?.source === 'api-async' && j.metadata?.testerToken === undefined && j.assignedTester === undefined && j.conversationHistory === undefined)) return false;
+      // result gating: without a subscription the conversation (and the testerResponse drawn from it) is withheld
+      const said = [{ role: 'user', content: 'Checkout works' }];
+      const paid = String(b(await h({ m: 'POST', p: '/api/jobs', b: { projectId: 'proj-3', url: 'https://paid.example.com', description: 'x' }, auth: `Bearer ${PAID_KEY}` })).jobId);
+      const paidToken = await claim(h, paid, MIKE, 10);
+      await h({ m: 'PATCH', p: `/api/tester/jobs/${paid}`, b: { conversationHistory: said }, auth: tester(paidToken), at: 20 });
+      const pg = await h({ m: 'GET', p: `/api/jobs/${paid}`, auth: `Bearer ${PAID_KEY}` });
+      if (!(b(pg).richResultsGated === false && b(pg).testerResponse === 'Checkout works' && b(pg).ownerOrganizationName === undefined)) return false;
+      const miss = await h({ m: 'GET', p: '/api/jobs/00000000-0000-4000-8000-000000000000' });
+      const foreign = await h({ m: 'GET', p: `/api/jobs/${id}`, auth: `Bearer ${OTHER_KEY}` });
+      return miss.status === 404 && b(miss).error === 'Job not found'
+        && foreign.status === 403 && b(foreign).message === 'API key organization does not match job project organization';
+    })),
+  done('runhuman.jobs.status', 'jobs', 'GET /api/jobs/:jobId/status returns the polling view (status, timing, jobUrl, gating) without the full row; unknown is 404, another org\'s key is 403', 'api', 'core', () =>
+    withWorld('runhuman.jobs.status', async (h) => {
+      const id = await createJob(h, { targetDurationMinutes: 10, maxExtensionMinutes: 2 });
+      const s = await h({ m: 'GET', p: `/api/jobs/${id}/status` });
+      const v = b(s);
+      if (!(s.status === 200 && v.id === id && v.status === 'pending' && v.targetDurationMinutes === 10 && v.maxExtensionMinutes === 2 && v.projectName === 'Web'
+        && v.jobUrl === `https://runhuman.com/dashboard/proj-1/jobs/${id}` && v.richResultsGated === true && v.recordingStatus === 'none'
+        && v.version === undefined && v.billedOrganizationId === undefined && v.metadata === undefined)) return false;
+      const miss = await h({ m: 'GET', p: '/api/jobs/00000000-0000-4000-8000-000000000000/status' });
+      const foreign = await h({ m: 'GET', p: `/api/jobs/${id}/status`, auth: `Bearer ${OTHER_KEY}` });
+      return miss.status === 404 && foreign.status === 403;
+    })),
+  todo('runhuman.jobs.list', 'jobs', 'GET /api/jobs — the caller\'s paginated job list (web and CLI)', 'api', 'common'),
+  todo('runhuman.jobs.run_sync', 'jobs', 'POST /api/run — create a job and block until a tester finishes (up to 60 minutes)', 'api', 'core'),
+  todo('runhuman.jobs.rerun', 'jobs', 'POST /api/jobs/:jobId/rerun — clone a job\'s settings and re-dispatch, with body overrides', 'api', 'common'),
+  todo('runhuman.jobs.artifact', 'jobs', 'GET /api/jobs/:jobId/artifacts/:artifactType — one job artifact by type', 'api', 'common'),
+  todo('runhuman.jobs.frame', 'jobs', 'GET /api/jobs/:jobId/frames/:frameId — capability redirect to an extracted video frame', 'api', 'niche'),
+  todo('runhuman.jobs.popout_details', 'jobs', 'GET /api/jobs/:jobId/popout-details — the dashboard pop-out detail view', 'api', 'niche'),
+  todo('runhuman.jobs.feedback', 'jobs', 'PATCH /api/jobs/:jobId/feedback — the customer\'s rating/feedback on a job', 'api', 'niche'),
+  todo('runhuman.jobs.share_enable', 'jobs', 'POST /api/jobs/:jobId/share — enable a public share link', 'api', 'niche'),
+  todo('runhuman.jobs.share_disable', 'jobs', 'DELETE /api/jobs/:jobId/share — disable the public share link', 'api', 'niche'),
+  todo('runhuman.jobs.public', 'jobs', 'GET /api/public/jobs/:jobId/:token — the shared job read without auth', 'api', 'niche'),
+  todo('runhuman.jobs.baked_video_status', 'jobs', 'GET /api/jobs/:jobId/baked-demo-video-status — latest baked demo-video render status', 'api', 'niche'),
+  todo('runhuman.jobs.baked_video_render', 'jobs', 'POST /api/jobs/:jobId/baked-demo-video — trigger an idempotent baked demo-video render', 'api', 'niche'),
+  todo('runhuman.jobs.timers', 'jobs', 'Time-driven job monitors: release throttle (pending → queued → waiting), claim-window expiry, no-response timeout, overdue', 'api', 'common'),
+
+  // ── PROJECTS ────────────────────────────────────────────────────────────────────────────────
+  done('runhuman.projects.jobs', 'projects', 'GET /api/projects/:projectId/jobs pages the project\'s jobs newest first in customer list columns with {total, limit, offset, hasMore}; unknown project is 404, another org\'s key is 403', 'api', 'common', () =>
+    withWorld('runhuman.projects.jobs', async (h) => {
+      const a = await createJob(h, { description: 'first' }, 0);
+      const bb = await createJob(h, { description: 'second' }, 10);
+      const c = await createJob(h, { description: 'third' }, 20);
+      const p1 = await h({ m: 'GET', p: '/api/projects/proj-1/jobs?limit=2' });
+      const p2 = await h({ m: 'GET', p: '/api/projects/proj-1/jobs?limit=2&offset=2' });
+      const items1 = b(p1).items as Body[];
+      const items2 = b(p2).items as Body[];
+      const pg1 = b(p1).pagination;
+      const pg2 = b(p2).pagination;
+      if (!(p1.status === 200 && items1.map((j) => j.id).join() === [c, bb].join() && items2.map((j) => j.id).join() === a
+        && pg1.total === 3 && pg1.limit === 2 && pg1.offset === 0 && pg1.hasMore === true && pg2.hasMore === false
+        && items1[0]!.description === 'third' && items1[0]!.version === undefined && items1[0]!.targetDurationMinutes === undefined)) return false;
+      const miss = await h({ m: 'GET', p: '/api/projects/nope/jobs' });
+      const foreign = await h({ m: 'GET', p: '/api/projects/proj-1/jobs', auth: `Bearer ${OTHER_KEY}` });
+      return miss.status === 404 && b(miss).error === 'Project not found' && foreign.status === 403 && b(foreign).error === 'Access denied';
+    })),
+  todo('runhuman.projects.list', 'projects', 'GET /api/projects — projects accessible to the caller', 'api', 'common'),
+  todo('runhuman.projects.create', 'projects', 'POST /api/projects — create a project in an organization', 'api', 'common'),
+  todo('runhuman.projects.get', 'projects', 'GET /api/projects/:projectId — project details', 'api', 'common'),
+  todo('runhuman.projects.update', 'projects', 'PATCH /api/projects/:projectId — update project details', 'api', 'niche'),
+  todo('runhuman.projects.delete', 'projects', 'DELETE /api/projects/:projectId — soft-delete a project and its data', 'api', 'niche'),
+
+  // ── ORGANIZATIONS ───────────────────────────────────────────────────────────────────────────
+  todo('runhuman.organizations.list', 'organizations', 'GET /api/organizations — organizations the caller belongs to', 'api', 'common'),
+  todo('runhuman.organizations.get', 'organizations', 'GET /api/organizations/:organizationId — organization details', 'api', 'common'),
+  todo('runhuman.organizations.create', 'organizations', 'POST /api/organizations — create an organization', 'api', 'niche'),
+  todo('runhuman.organizations.members', 'organizations', 'GET /api/organizations/:organizationId/members — list members', 'api', 'niche'),
+  todo('runhuman.organizations.invite', 'organizations', 'POST /api/organizations/:organizationId/invite — invite a user by email', 'api', 'niche'),
+  todo('runhuman.organizations.remove_member', 'organizations', 'DELETE /api/organizations/:organizationId/members/:userId — remove a member', 'api', 'niche'),
+  todo('runhuman.organizations.projects', 'organizations', 'GET /api/organizations/:organizationId/projects — the organization\'s projects', 'api', 'niche'),
+
+  // ── API KEYS / PATS ─────────────────────────────────────────────────────────────────────────
+  todo('runhuman.keys.list', 'keys', 'GET /api/keys?organizationId= — an organization\'s API keys', 'api', 'common'),
+  todo('runhuman.keys.create', 'keys', 'POST /api/keys — mint an organization-scoped API key', 'api', 'common'),
+  todo('runhuman.keys.revoke', 'keys', 'POST /api/keys/:keyId/revoke — revoke an API key', 'api', 'niche'),
+  todo('runhuman.keys.delete', 'keys', 'DELETE /api/keys/:keyId — permanently delete an API key', 'api', 'niche'),
+  todo('runhuman.pats.create', 'pats', 'POST /api/pats — create a Personal Access Token', 'api', 'niche'),
+  todo('runhuman.pats.list', 'pats', 'GET /api/pats — the caller\'s PATs', 'api', 'niche'),
+  todo('runhuman.pats.revoke', 'pats', 'POST /api/pats/:patId/revoke — revoke a PAT', 'api', 'niche'),
+  todo('runhuman.pats.delete', 'pats', 'DELETE /api/pats/:patId — permanently delete a PAT', 'api', 'niche'),
+
+  // ── TEMPLATES / SCHEDULES ───────────────────────────────────────────────────────────────────
+  todo('runhuman.templates.list', 'templates', 'GET /api/projects/:projectId/templates — a project\'s templates', 'api', 'common'),
+  todo('runhuman.templates.create', 'templates', 'POST /api/projects/:projectId/templates — create a template', 'api', 'common'),
+  todo('runhuman.templates.get', 'templates', 'GET /api/projects/:projectId/templates/:templateId — template details', 'api', 'common'),
+  todo('runhuman.templates.update', 'templates', 'PATCH /api/projects/:projectId/templates/:templateId — update a template', 'api', 'niche'),
+  todo('runhuman.templates.delete', 'templates', 'DELETE /api/projects/:projectId/templates/:templateId — delete a template', 'api', 'niche'),
+  todo('runhuman.schedules.list', 'schedules', 'GET /api/projects/:projectId/schedules — a project\'s schedules', 'api', 'niche'),
+  todo('runhuman.schedules.create', 'schedules', 'POST /api/projects/:projectId/schedules — create a recurring schedule', 'api', 'niche'),
+  todo('runhuman.schedules.get', 'schedules', 'GET /api/projects/:projectId/schedules/:scheduleId — schedule details with template name', 'api', 'niche'),
+  todo('runhuman.schedules.update', 'schedules', 'PATCH /api/projects/:projectId/schedules/:scheduleId — partial schedule update', 'api', 'niche'),
+  todo('runhuman.schedules.delete', 'schedules', 'DELETE /api/projects/:projectId/schedules/:scheduleId — delete a schedule', 'api', 'niche'),
+  todo('runhuman.schedules.executions', 'schedules', 'GET /api/projects/:projectId/schedules/:scheduleId/executions — a schedule\'s execution history', 'api', 'niche'),
+
+  // ── GITHUB / ISSUES ─────────────────────────────────────────────────────────────────────────
+  todo('runhuman.github.oauth_authorize', 'github', 'GET /api/github/oauth/authorize — start the GitHub connection', 'api', 'niche'),
+  todo('runhuman.github.issues_list', 'github', 'GET /api/github/issues — a connected repo\'s issues', 'api', 'niche'),
+  todo('runhuman.github.issue_get', 'github', 'GET /api/github/issues/:issueNumber — one issue', 'api', 'niche'),
+  todo('runhuman.github.issue_test', 'github', 'POST /api/github/issues/test — test an issue with a human tester', 'api', 'niche'),
+  todo('runhuman.github.issues_bulk_test', 'github', 'POST /api/github/issues/bulk-test — test several issues', 'api', 'niche'),
+  todo('runhuman.github.test_sessions', 'github', 'GET /api/github/issues/test-sessions — issue test sessions', 'api', 'niche'),
+  todo('runhuman.github.create_issue', 'github', 'POST /api/jobs/:jobId/create-issue — file a GitHub issue from a finding', 'api', 'niche'),
+  todo('runhuman.github.feedback_issue', 'github', 'POST /api/jobs/:jobId/feedback/:extractedFeedbackIndex/github — file extracted feedback to GitHub', 'api', 'niche'),
+  todo('runhuman.github.undo_issue_comment', 'github', 'POST /api/jobs/:jobId/extracted-issues/:extractedIssueIndex/undo-comment — undo a duplicate-issue comment', 'api', 'niche'),
+
+  // ── AUTH / BILLING ──────────────────────────────────────────────────────────────────────────
+  todo('runhuman.auth.me', 'auth', 'GET /api/auth/me — the current user', 'api', 'common'),
+  todo('runhuman.billing.balance', 'billing', 'GET /api/billing/balance — credit balance', 'api', 'niche'),
+  todo('runhuman.billing.has_credits', 'billing', 'GET /api/billing/has-credits — whether credits are available', 'api', 'niche'),
+  todo('runhuman.billing.checkout', 'billing', 'POST /api/billing/checkout — create a checkout session', 'api', 'niche'),
+  todo('runhuman.billing.subscription', 'billing', 'GET /api/billing/subscription — the subscription', 'api', 'niche'),
+  todo('runhuman.billing.change_plan', 'billing', 'POST /api/billing/change-plan — change the plan', 'api', 'niche'),
+
+  // ── TESTER NOTES (customer-authored guidance) ───────────────────────────────────────────────
+  todo('runhuman.notes.list', 'notes', 'GET /api/tester/notes — list/search tester notes', 'api', 'niche'),
+  todo('runhuman.notes.create', 'notes', 'POST /api/tester/notes — create a tester note', 'api', 'niche'),
+  todo('runhuman.notes.get', 'notes', 'GET /api/tester/notes/:noteId — one tester note', 'api', 'niche'),
+  todo('runhuman.notes.update', 'notes', 'PATCH /api/tester/notes/:noteId — update a tester note', 'api', 'niche'),
+  todo('runhuman.notes.archive', 'notes', 'POST /api/tester/notes/:noteId/archive — archive a tester note', 'api', 'niche'),
+
+  // ── TESTER LIFECYCLE ────────────────────────────────────────────────────────────────────────
+  done('runhuman.tester.claim', 'tester', 'POST /api/jobs/:jobId/claim moves a pending job to working and mints the testerToken in the webTestLink; a second claim is 409 job_already_claimed, an unknown job 404, a missing claimSource 400 FST_ERR_VALIDATION, an unknown web user 401', 'api', 'core', () =>
+    withWorld('runhuman.tester.claim', async (h) => {
+      const id = await createJob(h);
+      const c = await h({ m: 'POST', p: `/api/jobs/${id}/claim`, b: { claimSource: 'tester-portal' }, auth: TESS, at: 60 });
+      const link = String(b(c).webTestLink ?? '');
+      if (!(c.status === 200 && b(c).message === 'Job claimed successfully' && b(c).job?.id === id && b(c).job?.status === 'working' && b(c).job?.claimedAt === iso(60)
+        && link.startsWith(`https://runhuman.com/tester/test/${id}?testerToken=`) && link.split('testerToken=')[1]!.split('.').length === 3)) return false;
+      const s = await h({ m: 'GET', p: `/api/jobs/${id}/status` });
+      if (!(b(s).status === 'working' && b(s).testerAlias === 'tess' && b(s).responseDeadline === iso(60 + 20 * 60))) return false;
+      const twice = await h({ m: 'POST', p: `/api/jobs/${id}/claim`, b: { claimSource: 'tester-portal' }, auth: MIKE, at: 70 });
+      const miss = await h({ m: 'POST', p: '/api/jobs/00000000-0000-4000-8000-000000000000/claim', b: { claimSource: 'tester-portal' }, auth: MIKE });
+      const noSource = await h({ m: 'POST', p: `/api/jobs/${id}/claim`, b: {}, auth: MIKE });
+      const stranger = await h({ m: 'POST', p: `/api/jobs/${id}/claim`, b: { claimSource: 'tester-portal' }, auth: 'Bearer clerk_nobody@x.test' });
+      return twice.status === 409 && b(twice).code === 'job_already_claimed' && b(twice).error === 'Job already claimed'
+        && miss.status === 404 && b(miss).code === 'job_not_found'
+        && noSource.status === 400 && b(noSource).error === 'Invalid request body: claimSource: Required'
+        && stranger.status === 401;
+    })),
+  done('runhuman.tester.claim_gates', 'tester', 'POST /api/jobs/:jobId/claim enforces the pool and surface gates: a missing required language is 403 pool_requirements_not_met with the missing list, a mobile-only job claimed from the portal is 403 mobile_only, a tester already working is 409 tester_has_active_job', 'api', 'common', () =>
+    withWorld('runhuman.tester.claim_gates', async (h) => {
+      const spanish = await createJob(h, { requiredLanguages: ['spanish'] });
+      const mobile = await createJob(h, { requiredDevices: ['ios'] });
+      const first = await createJob(h);
+      const second = await createJob(h);
+      const pool = await h({ m: 'POST', p: `/api/jobs/${spanish}/claim`, b: { claimSource: 'tester-portal' }, auth: TESS });
+      const surface = await h({ m: 'POST', p: `/api/jobs/${mobile}/claim`, b: { claimSource: 'tester-portal' }, auth: TESS });
+      await claim(h, first, TESS, 10);
+      const busy = await h({ m: 'POST', p: `/api/jobs/${second}/claim`, b: { claimSource: 'tester-portal' }, auth: TESS, at: 20 });
+      const details = b(pool).details as string[];
+      return pool.status === 403 && b(pool).code === 'pool_requirements_not_met' && Array.isArray(details) && details.join() === 'Missing language(s): Spanish'
+        && surface.status === 403 && b(surface).code === 'mobile_only'
+        && busy.status === 409 && b(busy).code === 'tester_has_active_job' && b(busy).details === `Already working on job "${first}"`;
+    })),
+  done('runhuman.tester.job_get', 'tester', 'GET /api/tester/jobs/:jobId reads the claimed job under its testerToken (with organizationName); no token is 401, a forged token 401 invalid_signature, a valid token for another job 404', 'api', 'core', () =>
+    withWorld('runhuman.tester.job_get', async (h) => {
+      const id = await createJob(h);
+      const other = await createJob(h);
+      const token = await claim(h, id, TESS, 10);
+      const g = await h({ m: 'GET', p: `/api/tester/jobs/${id}`, auth: tester(token), at: 20 });
+      if (!(g.status === 200 && b(g).id === id && b(g).status === 'working' && b(g).organizationName === 'Acme' && b(g).testerAlias === 'tess' && b(g).description === 'Buy the cheapest item')) return false;
+      const [head, payload, sig] = token.split('.');
+      const forged = `${head}.${payload}.${sig!.slice(0, -2)}${sig!.endsWith('AA') ? 'BB' : 'AA'}`;
+      const none = await h({ m: 'GET', p: `/api/tester/jobs/${id}`, auth: null, at: 20 });
+      const bad = await h({ m: 'GET', p: `/api/tester/jobs/${id}`, auth: tester(forged), at: 20 });
+      const wrongJob = await h({ m: 'GET', p: `/api/tester/jobs/${other}`, auth: tester(token), at: 20 });
+      return none.status === 401 && bad.status === 401 && b(bad).reason === 'invalid_signature' && wrongJob.status === 404 && b(wrongJob).error === 'Job not found';
+    })),
+  done('runhuman.tester.job_update', 'tester', 'PATCH /api/tester/jobs/:jobId writes only the tester-writable fields (the conversation, stamped with the tester; never cost), refuses completion before an AI verdict (400) and a non-object body (400 FST_ERR_VALIDATION)', 'api', 'core', () =>
+    withWorld('runhuman.tester.job_update', async (h) => {
+      const id = await createJob(h);
+      const token = await claim(h, id, TESS, 10);
+      const u = await h({ m: 'PATCH', p: `/api/tester/jobs/${id}`, b: { conversationHistory: [{ role: 'user', content: 'Checkout works' }], costUsd: 999 }, auth: tester(token), at: 30 });
+      if (!(u.status === 200 && b(u).success === true && b(u).job?.id === id && b(u).job?.status === 'working')) return false;
+      const g = await h({ m: 'GET', p: `/api/tester/jobs/${id}`, auth: tester(token), at: 30 });
+      const history = b(g).conversationHistory as Body[];
+      if (!(history.length === 1 && history[0]!.content === 'Checkout works' && history[0]!.testerId === 'tess' && b(g).costUsd === undefined && b(g).lastActivity === iso(30))) return false;
+      const early = await h({ m: 'PATCH', p: `/api/tester/jobs/${id}`, b: { status: 'completed' }, auth: tester(token), at: 40 });
+      const arr = await h({ m: 'PATCH', p: `/api/tester/jobs/${id}`, raw: '[1]', auth: tester(token), at: 40 });
+      return early.status === 400 && b(early).error === 'Cannot complete job without an AI verdict'
+        && arr.status === 400 && b(arr).error === 'Invalid request body: Invalid input' && b(arr).code === 'FST_ERR_VALIDATION';
+    })),
+  done('runhuman.tester.process_results', 'tester', 'POST /api/tester/jobs/:jobId/process-results queues the results pipeline (200 {processingJobId, status:"processing"}); another job\'s testerToken is 403 "Invalid testerToken for job"', 'api', 'core', () =>
+    withWorld('runhuman.tester.process_results', async (h) => {
+      const id = await createJob(h);
+      const other = await createJob(h);
+      const token = await claim(h, id, TESS, 10);
+      const otherToken = await claim(h, other, MIKE, 10);
+      const pr = await h({ m: 'POST', p: `/api/tester/jobs/${id}/process-results`, b: { clientInfo: { browser: 'chrome' } }, auth: tester(token), at: 20 });
+      const g = await h({ m: 'GET', p: `/api/tester/jobs/${id}`, auth: tester(token), at: 20 });
+      const cross = await h({ m: 'POST', p: `/api/tester/jobs/${id}/process-results`, b: {}, auth: tester(otherToken), at: 20 });
+      return pr.status === 200 && typeof b(pr).processingJobId === 'string' && b(pr).status === 'processing' && String(b(pr).message).startsWith('Processing started.')
+        && b(g).metadata?.testerClient?.browser === 'chrome'
+        && cross.status === 403 && b(cross).error === 'Invalid testerToken for job';
+    })),
+  done('runhuman.tester.processing_status', 'tester', 'GET /api/tester/jobs/:jobId/processing/:processingJobId completes the queued extract run on its first read (the submitted result kept, no issues extracted); an unknown run is 404', 'api', 'core', () =>
+    withWorld('runhuman.tester.processing_status', async (h) => {
+      const id = await createJob(h);
+      const token = await claim(h, id, TESS, 10);
+      await h({ m: 'PATCH', p: `/api/tester/jobs/${id}`, b: { result: { explanation: 'paid with test card', data: { success: true } } }, auth: tester(token), at: 20 });
+      const pr = await h({ m: 'POST', p: `/api/tester/jobs/${id}/process-results`, b: {}, auth: tester(token), at: 30 });
+      const poll = await h({ m: 'GET', p: `/api/tester/jobs/${id}/processing/${b(pr).processingJobId}`, auth: tester(token), at: 40 });
+      const job = b(poll).result?.job as Body | undefined;
+      const miss = await h({ m: 'GET', p: `/api/tester/jobs/${id}/processing/nope`, auth: tester(token), at: 40 });
+      return poll.status === 200 && b(poll).status === 'completed' && b(poll).result?.isComplete === true
+        && job?.result?.explanation === 'paid with test card' && Array.isArray(job?.extractedIssues) && job.extractedIssues.length === 0 && Array.isArray(job?.extractedFeedback)
+        && miss.status === 404 && b(miss).error === 'Processing job not found';
+    })),
+  done('runhuman.tester.issue_review', 'tester', 'POST /api/tester/jobs/:jobId/issue-review `continue` queues the finalize run whose verdict follows result.data.success (false → fail); before extraction it is 409, an unknown action 400', 'api', 'core', () =>
+    withWorld('runhuman.tester.issue_review', async (h) => {
+      const id = await createJob(h);
+      const token = await claim(h, id, TESS, 10);
+      const early = await h({ m: 'POST', p: `/api/tester/jobs/${id}/issue-review`, b: { action: 'continue' }, auth: tester(token), at: 20 });
+      const badAction = await h({ m: 'POST', p: `/api/tester/jobs/${id}/issue-review`, b: { action: 'skip' }, auth: tester(token), at: 20 });
+      await h({ m: 'PATCH', p: `/api/tester/jobs/${id}`, b: { result: { explanation: 'checkout 500s', data: { success: false } } }, auth: tester(token), at: 30 });
+      const pr = await h({ m: 'POST', p: `/api/tester/jobs/${id}/process-results`, b: {}, auth: tester(token), at: 30 });
+      await h({ m: 'GET', p: `/api/tester/jobs/${id}/processing/${b(pr).processingJobId}`, auth: tester(token), at: 40 });
+      const review = await h({ m: 'POST', p: `/api/tester/jobs/${id}/issue-review`, b: { action: 'continue' }, auth: tester(token), at: 50 });
+      await h({ m: 'GET', p: `/api/tester/jobs/${id}/processing/${b(review).processingJobId}`, auth: tester(token), at: 60 });
+      const s = await h({ m: 'GET', p: `/api/jobs/${id}/status` });
+      return early.status === 409 && b(early).message === 'Issue review is not available until extraction has run.'
+        && badAction.status === 400 && b(badAction).message === 'action must be one of: reprocess, continue'
+        && review.status === 200 && typeof b(review).processingJobId === 'string' && b(review).rerunCount === 0 && b(review).softCapReached === false
+        && b(s).passStatus === 'fail';
+    })),
+  todo('runhuman.tester.issue_review_reprocess', 'tester', 'POST /api/tester/jobs/:jobId/issue-review `reprocess` — AI re-extraction with the tester\'s revise guidance', 'api', 'common'),
+  done('runhuman.tester.complete', 'tester', 'PATCH /api/tester/jobs/:jobId {status:"completed"} after a verdict completes the job with RH1\'s cost ($0.0085/s over claim → completion, capped at the allotted time) and settles the charge; a repeated completion is an idempotent 200', 'api', 'core', () =>
+    withWorld('runhuman.tester.complete', async (h) => {
+      const id = await createJob(h);
+      const token = await claim(h, id, TESS, 0);
+      if (!(await toVerdict(h, id, token, true, 60))) return false;
+      const c = await h({ m: 'PATCH', p: `/api/tester/jobs/${id}`, b: { status: 'completed' }, auth: tester(token), at: 120 });
+      const again = await h({ m: 'PATCH', p: `/api/tester/jobs/${id}`, b: { status: 'completed' }, auth: tester(token), at: 180 });
+      const g = await h({ m: 'GET', p: `/api/jobs/${id}` });
+      const j = b(g);
+      return c.status === 200 && b(c).job?.status === 'completed' && again.status === 200 && b(again).job?.status === 'completed'
+        && j.status === 'completed' && j.passStatus === 'pass' && j.completedAt === iso(120) && j.testDurationSeconds === 120
+        && Math.abs(Number(j.costUsd) - 120 * 0.0085) < 1e-9 && j.billedAmountCents === 102 && j.billedAt === iso(120);
+    })),
+  done('runhuman.tester.end', 'tester', 'POST /api/tester/jobs/:jobId/end cancels (tester_cancellation, cost 0) or files a platform issue (failed), answers an already-terminal job alreadyTerminal:true, and refuses a blank note (400) and an unknown action (400 FST_ERR_VALIDATION)', 'api', 'common', () =>
+    withWorld('runhuman.tester.end', async (h) => {
+      const id = await createJob(h);
+      const broken = await createJob(h);
+      const token = await claim(h, id, TESS, 10);
+      const brokenToken = await claim(h, broken, MIKE, 10);
+      const blank = await h({ m: 'POST', p: `/api/tester/jobs/${id}/end`, b: { action: 'clear_and_cancel', note: '  ' }, auth: tester(token), at: 20 });
+      const unknown = await h({ m: 'POST', p: `/api/tester/jobs/${id}/end`, b: { action: 'vanish', note: 'x' }, auth: tester(token), at: 20 });
+      const cancel = await h({ m: 'POST', p: `/api/tester/jobs/${id}/end`, b: { action: 'clear_and_cancel', note: 'site is down' }, auth: tester(token), at: 30 });
+      const repeat = await h({ m: 'POST', p: `/api/tester/jobs/${id}/end`, b: { action: 'clear_and_cancel', note: 'again' }, auth: tester(token), at: 40 });
+      const platform = await h({ m: 'POST', p: `/api/tester/jobs/${broken}/end`, b: { action: 'platform_issue', note: 'recorder crashed' }, auth: tester(brokenToken), at: 30 });
+      const g = await h({ m: 'GET', p: `/api/jobs/${id}` });
+      const gb = await h({ m: 'GET', p: `/api/jobs/${broken}` });
+      return blank.status === 400 && b(blank).message === 'A note is required for action "clear_and_cancel"'
+        && unknown.status === 400 && b(unknown).code === 'FST_ERR_VALIDATION'
+        && cancel.status === 200 && b(cancel).status === 'cancelled' && b(cancel).action === 'clear_and_cancel'
+        && repeat.status === 200 && b(repeat).alreadyTerminal === true
+        && b(g).status === 'cancelled' && b(g).modifier === 'tester_cancellation' && b(g).error === 'site is down' && b(g).costUsd === 0
+        && platform.status === 200 && b(gb).status === 'failed' && b(gb).modifier === 'platform_issue';
+    })),
+  done('runhuman.tester.release_reclaim', 'tester', 'POST /api/tester/jobs/:jobId/end clear_and_release returns the job to waiting with the tester cleared: the old testerToken stops working (404) and another tester can claim it', 'api', 'common', () =>
+    withWorld('runhuman.tester.release_reclaim', async (h) => {
+      const id = await createJob(h);
+      const token = await claim(h, id, TESS, 10);
+      const rel = await h({ m: 'POST', p: `/api/tester/jobs/${id}/end`, b: { action: 'clear_and_release', note: 'need a phone' }, auth: tester(token), at: 20 });
+      const s = await h({ m: 'GET', p: `/api/jobs/${id}/status` });
+      if (!(rel.status === 200 && b(rel).status === 'waiting' && b(s).status === 'waiting' && b(s).testerAlias === undefined && b(s).claimedAt === undefined)) return false;
+      const stale = await h({ m: 'GET', p: `/api/tester/jobs/${id}`, auth: tester(token), at: 30 });
+      const token2 = await claim(h, id, MIKE, 40);
+      const g = await h({ m: 'GET', p: `/api/tester/jobs/${id}`, auth: tester(token2), at: 50 });
+      return stale.status === 404 && b(g).status === 'working' && b(g).testerAlias === 'mike' && b(g).claimedAt === iso(40);
+    })),
+  todo('runhuman.tester.opened', 'tester', 'POST /api/tester/jobs/:jobId/opened — mark the job engaged when the tester opens it', 'api', 'common'),
+  todo('runhuman.tester.upload_urls', 'tester', 'GET /api/tester/jobs/:jobId/upload-urls — signed upload URLs for recordings', 'api', 'common'),
+  todo('runhuman.tester.decline_late_submission', 'tester', 'POST /api/tester/jobs/:jobId/decline-late-submission — drop an overdue job', 'api', 'niche'),
+  todo('runhuman.tester.access_ended_info', 'tester', 'GET /api/tester/jobs/:jobId/access-ended-info — why the tester\'s access ended', 'api', 'niche'),
+  todo('runhuman.tester.correlate', 'tester', 'POST /api/tester/jobs/:jobId/correlate — correlate browser-extension data with the session', 'api', 'niche'),
+  todo('runhuman.tester.data_status', 'tester', 'GET /api/tester/jobs/:jobId/data-status — captured-data status', 'api', 'niche'),
+  todo('runhuman.tester.extension_token', 'tester', 'POST /api/tester/jobs/:jobId/extension-token — mint the browser-extension token', 'api', 'niche'),
+  todo('runhuman.tester.retranscribe', 'tester', 'POST /api/tester/jobs/:jobId/retranscribe — re-run transcription', 'api', 'niche'),
+  todo('runhuman.tester.strip_audio', 'tester', 'POST /api/tester/jobs/:jobId/strip-audio — strip audio from the recording', 'api', 'niche'),
+
+  // ── CONNECTOR ───────────────────────────────────────────────────────────────────────────────
+  todo('runhuman.connector.pull', 'connector', 'syncRunhumanFromReal pulls a real account\'s jobs by paging GET /api/projects/:projectId/jobs', 'connector', 'common'),
+];
+
+/** RH1's product areas, top-down from the public REST reference's sections (jobs, organizations,
+ *  projects, API keys, PATs, templates, schedules, GitHub, auth, billing), the jobs router's tester
+ *  side, the customer allowlist's tester notes, and the connector. */
+export const RUNHUMAN_AREAS = [
+  'auth',
+  'billing',
+  'connector',
+  'github',
+  'jobs',
+  'keys',
+  'notes',
+  'organizations',
+  'pats',
+  'projects',
+  'schedules',
+  'templates',
+  'tester',
+] as const;
+
+export function runhumanCapabilities(): Promise<CapabilityReport> {
+  return checkCapabilities('runhuman', RUNHUMAN_CAPABILITIES);
+}

package/src/runhuman-conformance.ts

@@ -0,0 +1,14 @@
+import { handleRunhumanTwinRequest } from './runhuman-twin.ts';
+
+export type RunhumanConformanceReport = { ok: boolean; checksRun: number; failures: string[] };
+
+/** The fail-loudly floor: an unmodelled /api route answers RH1's JSON 404
+ *  (routes/route-static-routing.ts `isJsonOnlySurface` → `{ error: 'Not found' }`). */
+export async function checkRunhumanConformance(options: { root?: string } = {}): Promise<RunhumanConformanceReport> {
+  const failures: string[] = [];
+  const unknown = await handleRunhumanTwinRequest({ method: 'GET', path: '/api/never-a-real-endpoint', root: options.root });
+  if (!(unknown.status === 404 && JSON.stringify(unknown.body) === '{"error":"Not found"}')) {
+    failures.push('an unmodelled /api route must answer RH1\'s JSON 404 {"error":"Not found"}');
+  }
+  return { ok: failures.length === 0, checksRun: 1, failures };
+}

package/src/runhuman-connector.ts

@@ -0,0 +1,67 @@
+// Runhuman connector — pull/push against an INJECTED execute (the real network exists only
+// inside liveRunhumanExecute). v1 pulls NOTHING; the gap is filed as the runhuman.connector.pull
+// todo in runhuman-capabilities.ts, never a silent omission.
+import { observeResource } from '@volter/world-core';
+import { RunhumanBudget, RunhumanBudgetError, runhumanCallWeight, type RunhumanBudgetOptions } from './runhuman-budget.ts';
+
+export type RunhumanExecute = (req: { method: string; path: string; body?: unknown }) => Promise<{ status: number; data: unknown }>;
+
+export const RUNHUMAN_API_BASE = 'https://runhuman.com';
+
+/** THE CHOKE POINT — the one place this pack reaches the real Runhuman API. Reads RUNHUMAN_API_KEY.
+ *  EVERY request is charged against the RunhumanBudget BEFORE it goes out (`checkBudget` throws
+ *  instead of calling once the ceiling or a persisted cooldown says stop), and the response is fed
+ *  back (`recordCall`) so a 429 / Retry-After becomes a persisted cooldown. There is no option to
+ *  disable the guard: a `budget` that is not a real RunhumanBudget is refused. */
+export function liveRunhumanExecute(opts: {
+  apiKey?: string;
+  baseUrl?: string;
+  fetchImpl?: typeof fetch;
+  /** An existing budget to share across executes. Omit and one is constructed. */
+  budget?: RunhumanBudget;
+  /** Construction options for the default budget (ledger path, clock). Cannot loosen it. */
+  budgetOptions?: RunhumanBudgetOptions;
+} = {}): RunhumanExecute {
+  const apiKey = opts.apiKey ?? process.env.RUNHUMAN_API_KEY;
+  const baseUrl = (opts.baseUrl ?? RUNHUMAN_API_BASE).replace(/\/$/, '');
+  const doFetch = opts.fetchImpl ?? fetch;
+  if (!apiKey) throw new Error('liveRunhumanExecute: RUNHUMAN_API_KEY is not set (never pass a literal)');
+  if (opts.budget !== undefined && opts.budget !== null && !(opts.budget instanceof RunhumanBudget)) {
+    throw new Error('liveRunhumanExecute: `budget` must be a RunhumanBudget — refusing to build a live Runhuman client around an unverified rate guard');
+  }
+  // The default ledger is keyed by a hash of THIS key, so every checkout spending it shares one allowance.
+  const budget = opts.budget instanceof RunhumanBudget ? opts.budget : new RunhumanBudget({ token: apiKey, ...(opts.budgetOptions ?? {}) });
+  return async ({ method, path, body }) => {
+    const verb = (method || 'GET').toUpperCase();
+    const weight = runhumanCallWeight(verb, path);
+    // THROWS instead of calling. Nothing below this line runs when the budget refuses.
+    const reservation = budget.checkBudget(weight);
+    const res = await doFetch(`${baseUrl}${path}`, {
+      method: verb,
+      headers: { authorization: `Bearer ${apiKey}`, ...(body === undefined ? {} : { 'content-type': 'application/json' }) },
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+    });
+    const headers: Record<string, string> = {};
+    res.headers.forEach((v: string, k: string) => { headers[k.toLowerCase()] = v; });
+    const text = await res.text();
+    // recordCall may THROW after arming the cooldown (a back-off beyond the cap). On a refused
+    // call that louder refusal wins; an answer Runhuman ACCEPTED is kept, so a write that landed is
+    // never recorded as failed and performed again on retry.
+    try {
+      budget.recordCall(weight, headers, { status: res.status, reservation });
+    } catch (error) {
+      if (!(error instanceof RunhumanBudgetError) || !res.ok) throw error;
+    }
+    return { status: res.status, data: text ? JSON.parse(text) : null };
+  };
+}
+
+/** D7 entry point. v1 pulls nothing (the rehearsal World seeds the twin); a pull would page
+ *  GET /api/projects/:projectId/jobs. The runhuman.connector.pull capability records the gap. */
+export async function syncRunhumanFromReal(_execute: RunhumanExecute, options: { root?: string; occurredAt?: string } = {}): Promise<{ pulled: number }> {
+  const resources: Array<{ type: string; id: string; fields: Record<string, unknown> }> = [];
+  // PROTOCOL 2: the pack OBSERVES each resource; the kernel diffs it against the tree and folds what changed
+  const at = options.occurredAt ?? new Date().toISOString();
+  for (const r of resources) observeResource('runhuman', { type: r.type, id: r.id, fields: r.fields }, { ...(options.root !== undefined ? { root: options.root } : {}), at });
+  return { pulled: resources.length };
+}