@volter/twin-instagram 0.1.0

package/src/instagram-conformance.ts

@@ -0,0 +1,58 @@
+// Conformance for the Instagram surface — dev-only, imported LAZILY by cli.ts so it never enters the
+// pack's runtime entrypoint graph.
+//
+// One real request per claimed behaviour, asserting the OUTCOME a live handler produces against the
+// docs' own samples: a Reels container answers {id, uri} with the uri on the rupload host, its
+// status_code reads IN_PROGRESS before the bytes, publishing it early is 9007/2207027, the IG User node
+// answers the fields asked for, the publishing limit answers {data:[{quota_usage, config}]}, an
+// unknown node is the Graph API's "Unsupported get request", and a missing token is refused.
+import { handleInstagramTwinRequest } from './instagram-twin.ts';
+
+export type InstagramConformanceReport = { ok: boolean; checksRun: number; failures: string[] };
+
+export async function checkInstagramConformance(options: { root?: string } = {}): Promise<InstagramConformanceReport> {
+  const failures: string[] = [];
+  let checks = 0;
+  const check = (name: string, ok: boolean) => { checks += 1; if (!ok) failures.push(name); };
+  const root = options.root;
+  const auth = { authorization: 'Bearer conformance-token-1', 'content-type': 'application/json' };
+  const h = (method: string, path: string, body?: unknown, headers: Record<string, string> = auth) =>
+    handleInstagramTwinRequest({ method, path, headers, root, occurredAt: '2026-09-27T12:00:00.000Z', ...(body === undefined ? {} : { body: JSON.stringify(body) }) });
+  const ig = '17841405822304914';
+
+  await h('POST', '/_twin/users', { id: ig, username: 'metricsaurus', name: 'Metricsaurus', biography: 'Dino data crunching app', website: 'http://www.metricsaurus.com/', followers_count: 12, follows_count: 3 }, {});
+  await h('POST', '/_twin/tokens', { token: 'conformance-token-1', user: ig, permissions: ['instagram_basic', 'instagram_content_publish', 'pages_read_engagement'] }, {});
+
+  const user = await h('GET', `/v26.0/${ig}?fields=biography,id,username,website`);
+  check('the IG User node answers the reference sample\'s fields', user.status === 200
+    && JSON.stringify(user.body) === JSON.stringify({ biography: 'Dino data crunching app', id: ig, username: 'metricsaurus', website: 'http://www.metricsaurus.com/' }));
+
+  const created = await h('POST', `/v26.0/${ig}/media`, { media_type: 'REELS', upload_type: 'resumable', caption: 'hello #reels' });
+  const c = created.body as any;
+  check('a resumable Reels container answers {id, uri} on the rupload host', created.status === 200 && /^\d+$/.test(c?.id) && c?.uri === `https://rupload.facebook.com/ig-api-upload/v26.0/${c?.id}`);
+
+  const status = await h('GET', `/v26.0/${c?.id}?fields=status_code`);
+  check('a container with no bytes reads IN_PROGRESS', status.status === 200 && JSON.stringify(status.body) === JSON.stringify({ status_code: 'IN_PROGRESS', id: c?.id }));
+
+  const early = await h('POST', `/v26.0/${ig}/media_publish`, { creation_id: c?.id });
+  const e = (early.body as any)?.error;
+  check('publishing a container not yet FINISHED is 9007 / 2207027', early.status === 400 && e?.code === 9007 && e?.error_subcode === 2207027 && e?.type === 'OAuthException' && typeof e?.fbtrace_id === 'string');
+
+  const limit = await h('GET', `/v26.0/${ig}/content_publishing_limit?fields=quota_usage,config`);
+  check('content_publishing_limit answers {data:[{quota_usage, config}]}', limit.status === 200
+    && JSON.stringify(limit.body) === JSON.stringify({ data: [{ quota_usage: 0, config: { quota_total: 50, quota_duration: 86400 } }] }));
+
+  const list = await h('GET', `/v26.0/${ig}/media`);
+  check('the media edge answers {data: []} for an account with no media', list.status === 200 && JSON.stringify(list.body) === JSON.stringify({ data: [] }));
+
+  const unknown = await h('GET', '/v26.0/17841499999999999');
+  check('an unknown node is the Graph API\'s Unsupported get request (100 / 33)', unknown.status === 400 && (unknown.body as any)?.error?.code === 100 && (unknown.body as any)?.error?.error_subcode === 33);
+
+  const anon = await h('GET', `/v26.0/${ig}`, undefined, {});
+  check('no token is refused', anon.status === 400 && (anon.body as any)?.error?.type === 'OAuthException');
+
+  const image = await h('POST', `/v26.0/${ig}/media`, { image_url: 'https://www.example.com/images/bronz-fonz.jpg' });
+  check('an unmodelled image container is refused by name, never a success', image.status === 422 && /\[twin gap\]/.test(String((image.body as any)?.error?.message)));
+
+  return { ok: failures.length === 0, checksRun: checks, failures };
+}

package/src/instagram-connector.ts

@@ -0,0 +1,400 @@
+// INSTAGRAM CONNECTOR — the pack's half of the REAL state system (protocol 2), over the kernel's
+// executor. The kernel builds `execute` from the root's origin and its sealed credential; this file
+// holds no credential and imports no network client.
+//
+// PERFORM (twin → Instagram). A landed `instagram.media.publish` is a Reel: its entry names the video
+// by DIGEST (instagram-twin.ts `_video`); a container is staging and not an entry of its own
+// (instagram-media.ts), so the adapter does at Meta what the app did at the twin, as the Content
+// Publishing guide documents it:
+//   1. `POST /{ig-user-id}/media` — media_type=REELS, upload_type=resumable, the caption,
+//      share_to_feed, cover_url or thumb_offset, audio_name — answering the container id and its `uri`;
+//   2. `POST` the bytes to that `uri` on rupload.facebook.com in 8 MiB chunks (`offset`, `file_size`;
+//      the kernel gives a request 30 s), the container kept from the moment it opens and the offset the
+//      vendor confirmed kept after every chunk, so a retry resumes rather than re-opens. The upload
+//      host takes the SAME access token as the Graph API, so this is a CREDENTIALED call to a second
+//      host: the kernel executor sends the sealed credential there only because this pack's own
+//      descriptor declares `{ host: 'rupload.facebook.com', pathPattern: '^/ig-api-upload/' }`
+//      (kernel 06ecdd56b), and the URL goes absolute, never presigned. A twin standing as the vendor
+//      mints its `uri` under its own base, which IS the root's origin, so there the upload goes as the
+//      anchored path `/ig-api-upload/…` the root's own base prefixes.
+//      THE CREDENTIAL'S SCHEME: the rupload host documents `Authorization: OAuth <token>`, and the Graph
+//      API takes the same scheme (its Resumable Upload guide sends `Authorization: OAuth` to
+//      graph.facebook.com), so ONE sealed header — `authorization: OAuth <token>` — serves both hosts.
+//   3. `GET /{container-id}?fields=status_code` until FINISHED — Meta: "We recommend querying a
+//      container's status once per minute, for no more than 5 minutes"; this wait reads at 0, 60 and
+//      120 s (a HARD CAP of 120 s) and then fails RETRYABLY: the entry stays deployable and the
+//      container id is KEPT, so the retry publishes that container instead of uploading again;
+//   4. `POST /{ig-user-id}/media_publish` with `creation_id` → the media id; then one read of its
+//      permalink for the receipt (a failed read never drops the id that already arrived).
+// A container that ends in ERROR refuses the entry when its subcode says the FILE is out of the Reels
+// spec (2207026, or 2207057 for thumb_offset) — the same bytes fail again; any other ERROR fails
+// retryably and the retry opens a fresh container. A container that reads PUBLISHED though this entry
+// never got its media id (the publish answer was lost) is matched to the media it became; if none can
+// be identified the entry is refused, never published twice and never left blocking the queue.
+// A landed `instagram.media.delete` becomes `DELETE /{ig-media-id}`.
+//
+// THE PERFORM AND REFRESH PATHS ARE BUDGETED. The kernel's executor knows nothing of Instagram's
+// limits, so each adapter wraps it (`budgetedInstagramExecute`) in this pack's InstagramBudget ledger,
+// keyed by the sealed credential's fingerprint (`ctx.credential`): every call is charged BEFORE it goes
+// out, a refusal THROWS without calling Meta, and a 429 / Retry-After arms the persisted cooldown. An
+// answer that has already arrived is never dropped: if settling the ledger throws after a 2xx, the
+// answer is returned and the NEXT call meets the cooldown.
+//
+// REFRESH (Instagram → twin). The credential's account (`/me`) and its media (paged), OBSERVED through
+// the kernel. A refused read throws; it is never an empty page folded over state.
+import { assertBudgetGuardIntact, observeResource, RefusedWriteError } from '@volter/world-core';
+import type { PerformContext, PushOutcome, RemoteExecute, RemoteExecuteRequest, TwinAction } from '@volter/world-core';
+import { clearPerformContainer, CONTAINER_LIFETIME_MS, MAX_REEL_BYTES, readInstagramBlob, readPerformContainer, writePerformContainer } from './instagram-media.ts';
+import { InstagramBudget, instagramCallWeight } from './instagram-budget.ts';
+
+const SERVICE = 'instagram';
+
+/** The Graph API version every call this adapter makes pins — the newest the twin models. */
+export const INSTAGRAM_VERSION = 'v26.0';
+/** Meta's upload host. */
+export const RUPLOAD_HOST = 'rupload.facebook.com';
+
+/**
+ * The kernel executor, charged to this pack's InstagramBudget: the check RESERVES before the call and
+ * throws (InstagramBudgetError) instead of calling when the ceiling, the burst bound or a cooldown says
+ * stop; the answer settles the reservation and arms a cooldown on 429 / Retry-After.
+ */
+export function budgetedInstagramExecute(execute: RemoteExecute, budget: InstagramBudget = new InstagramBudget()): RemoteExecute {
+  const guard = assertBudgetGuardIntact(budget, InstagramBudget, 'budgetedInstagramExecute');
+  return async (request) => {
+    const weight = instagramCallWeight(request.method, request.path);
+    const reservation = guard.checkBudget(weight);
+    const res = await execute(request);
+    try {
+      guard.recordCall(weight, Object.fromEntries(Object.entries(res.headers ?? {}).map(([k, v]) => [k.toLowerCase(), v])), { status: res.status, reservation });
+    } catch (error) {
+      // the vendor has already answered: a 2xx is kept (the cooldown is persisted; the next call meets it)
+      if (res.status < 200 || res.status >= 300) throw error;
+    }
+    return res;
+  };
+}
+
+/** The status wait's schedule: a read at once, then one a minute (Meta's "once per minute"), and no
+ *  read past 120 s — the hard cap. */
+export const STATUS_POLL_MS = 60_000;
+export const MAX_STATUS_WAIT_MS = 120_000;
+
+type Reply = { status: number; headers: Record<string, string>; body: string; json: Record<string, any> };
+
+async function call(execute: RemoteExecute, label: string, request: RemoteExecuteRequest, expect: number[]): Promise<Reply> {
+  const res = await execute(request);
+  let json: Record<string, any> = {};
+  if (res.body.trim() !== '') {
+    try { json = JSON.parse(res.body) as Record<string, any>; } catch { throw new Error(`instagram answered ${label} with a body that is not JSON: HTTP ${res.status} ${res.body.slice(0, 200)}`); }
+  }
+  if (!expect.includes(res.status)) throw new InstagramCallError(label, res.status, res.body, json);
+  return { status: res.status, headers: res.headers, body: res.body, json };
+}
+
+/** A refusal from Meta, with its Graph error code and subcode kept for the caller to read. */
+export class InstagramCallError extends Error {
+  readonly code?: number;
+  readonly subcode?: number;
+  constructor(readonly label: string, readonly status: number, body: string, json: Record<string, any>) {
+    super(`instagram refused ${label}: HTTP ${status} ${body.slice(0, 300)}`);
+    this.name = 'InstagramCallError';
+    const e = json.error as Record<string, any> | undefined;
+    if (typeof e?.code === 'number') this.code = e.code;
+    if (typeof e?.error_subcode === 'number') this.subcode = e.error_subcode;
+  }
+}
+
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+const graph = (path: string): string => `/${INSTAGRAM_VERSION}${path}`;
+const JSON_TYPE = { 'content-type': 'application/json' };
+
+/**
+ * Where a container's bytes go, from the `uri` the vendor answered: on Meta's upload host, that
+ * absolute URL (a credentialed call to the host the descriptor declares); anywhere else it is the
+ * vendor's own base — a twin standing as the vendor — so the anchored `/ig-api-upload/…` path, which the
+ * root's own base prefixes. No `uri` at all: Meta's documented form.
+ */
+export function uploadTarget(uri: unknown, container: string): string {
+  if (typeof uri === 'string' && uri !== '') {
+    let u: URL;
+    try { u = new URL(uri); } catch { throw new Error(`instagram answered a container uri that is not a URL: ${uri.slice(0, 200)}`); }
+    if (u.hostname === RUPLOAD_HOST) {
+      if (u.protocol !== 'https:' || u.port !== '' || u.username !== '' || u.password !== '') throw new Error(`instagram answered an upload uri that is not plain https on its upload host: ${uri.slice(0, 200)}`);
+      return u.href;
+    }
+    const at = u.pathname.indexOf('/ig-api-upload/');
+    if (at < 0) throw new Error(`instagram answered a container uri with no /ig-api-upload/ path: ${uri.slice(0, 200)}`);
+    return u.pathname.slice(at);
+  }
+  return `https://${RUPLOAD_HOST}/ig-api-upload/${INSTAGRAM_VERSION}/${container}`;
+}
+
+/** The container body a stored Reel crosses as. */
+export function containerParamsForVendor(fields: Record<string, any>): Record<string, unknown> {
+  return {
+    media_type: 'REELS',
+    upload_type: 'resumable',
+    ...(typeof fields.caption === 'string' ? { caption: fields.caption } : {}),
+    share_to_feed: fields.is_shared_to_feed !== false,
+    ...(typeof fields._cover_url === 'string' ? { cover_url: fields._cover_url } : {}),
+    ...(typeof fields._thumb_offset === 'number' && typeof fields._cover_url !== 'string' ? { thumb_offset: fields._thumb_offset } : {}),
+    ...(typeof fields._audio_name === 'string' ? { audio_name: fields._audio_name } : {}),
+    ...(typeof fields.is_ai_generated === 'boolean' ? { is_ai_generated: fields.is_ai_generated } : {}),
+  };
+}
+
+/** One upload POST carries at most this much: the kernel's executor gives a request 30 s, so a chunk
+ *  must cross in that time on a modest uplink (8 MiB in 30 s is ~2.3 Mbps). */
+export const UPLOAD_CHUNK_BYTES = 8 * 1024 * 1024;
+
+/**
+ * A container's bytes to the upload host from `from`, in chunks of UPLOAD_CHUNK_BYTES, each POST's
+ * `offset` the first byte it carries and `file_size` the whole file (the Content Publishing guide:
+ * "offset is set to the first byte being upload"). `onChunk` hears each offset the vendor confirmed, so
+ * a retry resumes there. The last POST must answer the documented `{"success":true}`.
+ */
+export async function uploadReel(execute: RemoteExecute, target: string, bytes: Uint8Array, from = 0, onChunk: (uploaded: number) => Promise<void> = async () => undefined): Promise<void> {
+  for (let at = from; at < bytes.length; ) {
+    const end = Math.min(bytes.length, at + UPLOAD_CHUNK_BYTES);
+    const res = await call(execute, `rupload at offset ${at}`, {
+      method: 'POST', path: target, headers: { offset: String(at), file_size: String(bytes.length), 'content-type': 'application/octet-stream' }, body: bytes.subarray(at, end),
+    }, [200, 201]);
+    // the offset the host says it holds, when it says one, is what it confirmed
+    at = typeof res.json.offset === 'number' && Number.isInteger(res.json.offset) && res.json.offset > at && res.json.offset <= end ? res.json.offset : end;
+    if (at === bytes.length) {
+      if (res.json.success !== true) throw new Error(`instagram's upload host did not confirm the upload: ${res.body.slice(0, 300)}`);
+      await onChunk(at);
+      return;
+    }
+    await onChunk(at);
+  }
+}
+
+/** Read a container's status_code on the schedule until it is FINISHED; the verdict otherwise. */
+export async function waitForContainer(execute: RemoteExecute, container: string, wait: (ms: number) => Promise<void> = sleep): Promise<'FINISHED' | 'ERROR' | 'EXPIRED' | 'PUBLISHED' | 'TIMEOUT'> {
+  for (let waited = 0; ; waited += STATUS_POLL_MS) {
+    const got = await call(execute, 'container status', { method: 'GET', path: graph(`/${container}?fields=status_code,status`) }, [200]);
+    const status = got.json.status_code;
+    if (status === 'FINISHED' || status === 'ERROR' || status === 'EXPIRED' || status === 'PUBLISHED') return status;
+    if (status !== 'IN_PROGRESS') throw new Error(`instagram answered container ${container} with an unknown status_code ${JSON.stringify(status)}`);
+    if (waited + STATUS_POLL_MS > MAX_STATUS_WAIT_MS) return 'TIMEOUT';
+    await wait(STATUS_POLL_MS);
+  }
+}
+
+/**
+ * The perform adapter (runtime contract R18): what a World's deploy calls for each landed Instagram
+ * entry on a twin whose root is real. A seeded account or token is the twin's own record and crosses nothing.
+ */
+export async function performInstagramAction(kernelExecute: RemoteExecute, action: TwinAction, ctx: PerformContext): Promise<PushOutcome> {
+  // one ledger per real credential (the sealed credential's keyed fingerprint), as X, YouTube and
+  // LinkedIn key theirs: two World roots sealed with one credential spend one allowance
+  return performInstagramActionWithin(new InstagramBudget(ctx.credential !== undefined ? { token: ctx.credential } : ctx.root !== undefined ? { root: ctx.root } : {}), kernelExecute, action, ctx);
+}
+
+/** The perform, charged to a given budget: the credential's ledger in production (`performInstagramAction`),
+ *  a throwaway ledger where a verify must not spend the operator's allowance. */
+export async function performInstagramActionWithin(budget: InstagramBudget, kernelExecute: RemoteExecute, action: TwinAction, ctx: PerformContext, wait: (ms: number) => Promise<void> = sleep, now: () => number = Date.now): Promise<PushOutcome> {
+  const execute = budgetedInstagramExecute(kernelExecute, budget);
+  const fields = { ...(action.fields ?? {}) } as Record<string, any>;
+  const subjectId = action.subject?.id ?? '';
+  if ((action.operation ?? '').startsWith('instagram.twin.')) {
+    return { externalId: ctx.resolve(action.subject?.type ?? 'ig_user', subjectId), data: { performed: false, reason: `${action.operation} is the twin's own record — nothing at Instagram to write` } };
+  }
+  if (action.operation === 'instagram.media.delete') {
+    const target = ctx.resolve('media', subjectId);
+    const res = await call(execute, 'media DELETE', { method: 'DELETE', path: graph(`/${encodeURIComponent(target)}`) }, [200]);
+    if (res.json.success !== true) throw new Error(`instagram did not confirm deleting ${target}: ${res.body.slice(0, 200)}`);
+    return { externalId: target, data: { deleted: true } };
+  }
+  if (action.operation !== 'instagram.media.publish') throw new Error(`instagram cannot perform ${action.operation ?? 'this entry'} on ${subjectId}: no Instagram request expresses it`);
+
+  const video = fields._video as { sha256?: string; size?: number } | undefined;
+  const owner = ctx.resolve('ig_user', String(fields.owner?.id ?? ''));
+  if (!/^\d+$/.test(owner)) throw new RefusedWriteError('instagram.media.owner', `media ${subjectId} names no IG user`, action.id);
+  const bytes = video?.sha256 ? await readInstagramBlob(video.sha256, ctx.root) : null;
+  if (!bytes) throw new Error(`instagram cannot perform ${subjectId}: the bytes of its Reel are not on this twin's blob seam`);
+  if (bytes.length > MAX_REEL_BYTES) throw new RefusedWriteError('instagram.reel_spec', `a ${bytes.length}-byte Reel is over the 300MB maximum`, action.id);
+
+  // A retry of an entry whose Reel already reached a container at Meta continues THAT container: it
+  // resumes the upload at the offset the vendor confirmed, or waits on it, or publishes it.
+  let kept = await readPerformContainer(action.id, ctx.root);
+  if (kept && (kept.sha256 !== video!.sha256 || now() - kept.created_ms >= CONTAINER_LIFETIME_MS || !validTarget(kept.target, kept.container))) { await clearKept(action.id, ctx.root); kept = null; }
+  const reopened = kept !== null;
+  if (!kept) {
+    const created = await call(execute, 'media container CREATE', {
+      method: 'POST', path: graph(`/${owner}/media`), headers: JSON_TYPE, body: JSON.stringify(containerParamsForVendor(fields)),
+    }, [200]);
+    const id = created.json.id;
+    if (typeof id !== 'string' || !/^\d+$/.test(id)) throw new Error(`instagram answered the container CREATE without a container id: ${created.body.slice(0, 200)}`);
+    // kept at once: a retry after this point never opens a second container for this entry
+    // two instants: the local one counts the 24-hour lifetime; the VENDOR's (its answer's HTTP Date, the
+    // local clock only when the answer carries none) is what a lost publish is matched against
+    const served = Date.parse(headerOf(created.headers, 'date') ?? '');
+    kept = { container: id, sha256: video!.sha256!, created_ms: now(), vendor_opened_ms: Number.isFinite(served) ? served : now(), uploaded: 0, target: uploadTarget(created.json.uri, id) };
+    await writePerformContainer(action.id, kept, ctx.root);
+  }
+  const record = kept;
+  if (record.uploaded < bytes.length) {
+    // resuming: this container was opened by an earlier attempt, whose last chunk may have reached the
+    // host without its answer reaching here — so the host may hold more than `uploaded` says
+    const resumed = reopened;
+    try {
+      await uploadReel(execute, record.target, bytes, record.uploaded, async (uploaded) => { record.uploaded = uploaded; await writePerformContainer(action.id, record, ctx.root); });
+    } catch (error) {
+      // A RESUMED POST the host refused with 400 may hold another offset than the one confirmed here: a
+      // chunk arrived whose answer did not. If that chunk was the last, the container has the whole file
+      // and reads FINISHED (or ERROR / PUBLISHED): go on with it. Otherwise it is abandoned to expire and
+      // the next retry opens a fresh one — which a 400 for another cause (a bad credential) also costs:
+      // one container per two retries, the price of not reading Meta's undocumented refusal wording. A
+      // throttle (429) or any other status keeps the container as it is.
+      if (!(resumed && error instanceof InstagramCallError && error.status === 400)) throw error;
+      const now1 = await call(execute, 'container status', { method: 'GET', path: graph(`/${record.container}?fields=status_code`) }, [200]);
+      if (now1.json.status_code === 'EXPIRED') { await clearKept(action.id, ctx.root); throw error; }
+      // FINISHED / ERROR / PUBLISHED: the whole file is there. IN_PROGRESS: it may be (Meta processing the
+      // whole file) or not (a piece short) — wait on it, and if the wait ends IN_PROGRESS, give it up
+      record.uploaded = bytes.length;
+      if (now1.json.status_code === 'IN_PROGRESS') record.unsure = true;
+      await writePerformContainer(action.id, record, ctx.root);
+    }
+  }
+  const container = record.container;
+
+  const verdict = await waitForContainer(execute, container, wait);
+  if (verdict === 'ERROR') {
+    const got = await call(execute, 'container status', { method: 'GET', path: graph(`/${container}?fields=status_code,status`) }, [200]).catch(() => null);
+    const subcode = String(got?.json.status ?? '');
+    await clearKept(action.id, ctx.root);
+    // the file itself is out of the Reels spec (2207026) or its thumb_offset is (2207057): the same bytes
+    // fail again, so the entry is refused; any other ERROR ("Generate a new container ... try again")
+    // fails retryably and the retry opens a fresh container
+    if (/2207026|2207057/.test(subcode)) throw new RefusedWriteError('instagram.reel_spec', `Meta could not process the Reel (container ${container}, status ${subcode})`, action.id);
+    throw new Error(`instagram could not process the Reel (container ${container}, status ${subcode || 'ERROR'}); a retry uploads it to a new container`);
+  }
+  if (verdict === 'EXPIRED') {
+    await clearKept(action.id, ctx.root);
+    throw new Error(`instagram container ${container} expired before it was published; a retry uploads the Reel again`);
+  }
+  if (verdict === 'PUBLISHED') {
+    // this entry's publish reached Meta but its answer did not reach here: find the media it became
+    const found = await findPublished(execute, owner, fields, record.vendor_opened_ms ?? record.created_ms);
+    await clearKept(action.id, ctx.root);
+    if (found) return { externalId: found.id, ...(found.permalink ? { url: found.permalink } : {}), data: { _vendor_container: container } };
+    throw new RefusedWriteError('instagram.publish_answer_lost', `container ${container} is PUBLISHED at Meta, but its media could not be identified (a caption-less Reel, or not exactly one Reel with this caption since the container opened); not publishing it twice`, action.id);
+  }
+  if (verdict === 'TIMEOUT') {
+    if (record.unsure) {
+      await clearKept(action.id, ctx.root);
+      throw new Error(`instagram container ${container} was still IN_PROGRESS after ${MAX_STATUS_WAIT_MS / 1000}s after a refused resume: it may hold only part of the file; a retry uploads to a new container`);
+    }
+    throw new Error(`instagram container ${container} was still IN_PROGRESS after ${MAX_STATUS_WAIT_MS / 1000}s; kept — a retry publishes it without uploading again`);
+  }
+  const published = await call(execute, 'media_publish', {
+    method: 'POST', path: graph(`/${owner}/media_publish`), headers: JSON_TYPE, body: JSON.stringify({ creation_id: container }),
+  }, [200]);
+  const mediaId = published.json.id;
+  if (typeof mediaId !== 'string' || !/^\d+$/.test(mediaId)) throw new Error(`instagram answered media_publish without a media id: ${published.body.slice(0, 200)}`);
+  // the id has arrived: nothing after this line may drop it
+  await clearKept(action.id, ctx.root);
+  let permalink: string | undefined;
+  try {
+    const got = await call(execute, 'media GET', { method: 'GET', path: graph(`/${mediaId}?fields=permalink`) }, [200]);
+    if (typeof got.json.permalink === 'string') permalink = got.json.permalink;
+  } catch { /* the publish stands */ }
+  return { externalId: mediaId, ...(permalink ? { url: permalink } : {}), data: { _vendor_container: container } };
+}
+
+/** Drop an entry's kept container; a failure to drop it never fails what already happened. */
+async function clearKept(actionId: string, root?: string): Promise<void> {
+  try { await clearPerformContainer(actionId, root); } catch { /* the record is overwritten or expires with its container */ }
+}
+
+/** The media a PUBLISHED container became, when its publish answer was lost: the one media of the
+ *  account, among its newest, with this entry's caption and a timestamp after the container opened. */
+async function findPublished(execute: RemoteExecute, owner: string, fields: Record<string, any>, openedMs: number): Promise<{ id: string; permalink?: string } | undefined> {
+  // a caption-less Reel cannot be told from any other caption-less post: never guessed
+  const caption = typeof fields.caption === 'string' && fields.caption.trim() !== '' ? fields.caption : undefined;
+  if (caption === undefined) return undefined;
+  // a read that fails throws (the entry retries); only a read that succeeded can refuse
+  const res = await call(execute, 'media list (a lost publish)', { method: 'GET', path: graph(`/${owner}/media?fields=id,caption,timestamp,permalink,media_product_type&limit=25`) }, [200]);
+  if (!Array.isArray(res.json.data)) throw new Error(`instagram answered the media list with no data: ${res.body.slice(0, 200)}`);
+  // IG Media: "Captions don't include the @ symbol unless the app user is also able to perform
+  // admin-equivalent tasks" — compared with every @ removed on both sides
+  const bare = (c: unknown) => String(c ?? '').replace(/@/g, '');
+  const hits = (res.json.data as Array<Record<string, any>>).filter((m) => m.media_product_type === 'REELS' && bare(m.caption) === bare(caption)
+    && Date.parse(String(m.timestamp).replace(/([+-]\d\d)(\d\d)$/, '$1:$2')) >= openedMs - 60_000);
+  return hits.length === 1 && typeof hits[0]!.id === 'string' ? { id: hits[0]!.id, ...(typeof hits[0]!.permalink === 'string' ? { permalink: hits[0]!.permalink } : {}) } : undefined;
+}
+
+/** A kept target read back from the annex, held to what uploadTarget would answer: Meta's upload host
+ *  over plain https, or the anchored twin path. */
+function validTarget(target: string, container: string): boolean {
+  if (!/^\d+$/.test(container)) return false;
+  if (/^https:\/\//i.test(target)) {
+    try { return uploadTarget(target, container) === target && new URL(target).pathname.endsWith(`/${container}`); } catch { return false; }
+  }
+  return new RegExp(`^/ig-api-upload/(?:v\\d+\\.\\d+/)?${container}$`).test(target);
+}
+
+function headerOf(headers: Record<string, string>, name: string): string | undefined {
+  for (const [k, v] of Object.entries(headers ?? {})) if (k.toLowerCase() === name) return v;
+  return undefined;
+}
+
+// ── refresh ──────────────────────────────────────────────────────────────────────────────────
+
+/** How many pages of media a refresh reads before it refuses to go on. */
+const MAX_PAGES = 50;
+const USER_FIELDS = 'id,username,name,biography,website,followers_count,follows_count,profile_picture_url';
+const MEDIA_FIELDS = 'id,media_type,media_product_type,media_url,permalink,caption,timestamp,thumbnail_url,shortcode,owner,is_shared_to_feed,is_comment_enabled,comments_count,like_count';
+
+let lastPollMs = 0;
+/** A MOVING observation instant, strictly increasing in the process — never a pinned constant. */
+function pollTimestamp(): string {
+  const t = Date.now();
+  lastPollMs = t > lastPollMs ? t : lastPollMs + 1;
+  return new Date(lastPollMs).toISOString();
+}
+
+/**
+ * The refresh adapter: the credential's professional account and every media it holds, observed into
+ * the parent log. Read-side only. A refusal throws.
+ */
+export async function syncInstagramFromRemote(kernelExecute: RemoteExecute, opts: { root?: string; origin?: string; occurredAt?: string; budget?: InstagramBudget; credential?: string } = {}): Promise<{ observed: number; users: number; media: number }> {
+  const execute = budgetedInstagramExecute(kernelExecute, opts.budget ?? new InstagramBudget(opts.credential !== undefined ? { token: opts.credential } : opts.root !== undefined ? { root: opts.root } : {}));
+  const at = opts.occurredAt ?? pollTimestamp();
+  const observe = (type: string, id: string, f: Record<string, unknown>) =>
+    observeResource(SERVICE, { type, id, fields: f }, { ...(opts.root !== undefined ? { root: opts.root } : {}), at });
+  const me = await call(execute, 'IG User GET me', { method: 'GET', path: graph(`/me?fields=${USER_FIELDS}`) }, [200]);
+  const u = me.json;
+  if (typeof u.id !== 'string' || typeof u.username !== 'string') throw new Error(`instagram answered /me without its id and username: ${me.body.slice(0, 200)}`);
+  const userFields: Record<string, unknown> = { username: u.username };
+  for (const k of ['name', 'biography', 'website', 'profile_picture_url'] as const) if (typeof u[k] === 'string') userFields[k] = u[k];
+  for (const k of ['followers_count', 'follows_count'] as const) if (typeof u[k] === 'number') userFields[k] = u[k];
+  observe('ig_user', u.id, userFields);
+  let media = 0;
+  let after: string | undefined;
+  for (let page = 0; ; page += 1) {
+    if (page >= MAX_PAGES) throw new Error(`instagram media of ${u.id} exceeded ${MAX_PAGES} pages; refusing to page further`);
+    const res = await call(execute, `media list ${u.id}`, { method: 'GET', path: graph(`/${u.id}/media?fields=${MEDIA_FIELDS}&limit=100${after ? `&after=${encodeURIComponent(after)}` : ''}`) }, [200]);
+    const data = res.json.data;
+    if (!Array.isArray(data)) throw new Error(`instagram answered the media list with no data: ${res.body.slice(0, 200)}`);
+    for (const m of data as Array<Record<string, any>>) {
+      if (typeof m.id !== 'string' || !/^\d+$/.test(m.id)) throw new Error(`instagram answered a media with no id: ${JSON.stringify(m).slice(0, 200)}`);
+      const { id, username: _username, ...rest } = m;
+      observe('media', id, rest);
+      media += 1;
+    }
+    const next = res.json.paging?.next;
+    const cursor = res.json.paging?.cursors?.after;
+    if (typeof next !== 'string' || typeof cursor !== 'string' || data.length === 0) break;
+    after = cursor;
+  }
+  return { observed: 1 + media, users: 1, media };
+}
+
+/** D7's consumer-facing entry point, the same read as the refresh adapter. */
+export async function syncInstagramFromReal(execute: RemoteExecute, opts: { root?: string; occurredAt?: string; budget?: InstagramBudget; credential?: string } = {}): Promise<{ observed: number; users: number; media: number }> {
+  return syncInstagramFromRemote(execute, opts);
+}

package/src/instagram-errors.ts

@@ -0,0 +1,89 @@
+// Meta's Graph API error envelope, as the Instagram Platform answers it.
+//
+// SHAPE. `{ error: { message, type, code, error_subcode?, is_transient, error_user_title?,
+// error_user_msg?, fbtrace_id } }` — the Graph API "Handle Errors" guide's sample and the Instagram
+// Platform "Error Codes" reference sample (developers.facebook.com, read 2026-09-27). Codes and
+// subcodes below are that reference's table (-2/2207020 expired, 9/2207042 publish limit,
+// 24/2207006 unknown media, 24/2207008 unknown or expired creation id, 9007/2207027 not ready,
+// 352/2207026 unsupported video format, 1/2207057 thumb offset, 36004/2207010 caption length,
+// 100/2207040 too many @ tags, 100/2207023 unknown media type) and the Graph guide's general codes
+// (190 invalid token, 10 / 200-299 permission, 100 invalid parameter).
+//
+// EVIDENCE BOUNDARY. The codes and subcodes are the docs'. The `message` wording is quoted where the
+// table gives a "User Message"; elsewhere it states the refusal plainly and is not claimed to be
+// Meta's (`instagram.errors.message_wording`). `fbtrace_id` is opaque at Meta; the twin draws it from
+// a digest of the request so the same request answers the same body (R9).
+//
+// THE RUPLOAD HOST answers its own envelope — `{ success, message }` on success and
+// `{ debug_info: { retriable, type, message } }` on failure (the Content Publishing guide's samples).
+import { blobDigest } from '@volter/world-core';
+
+export type InstagramResponse = {
+  status: number;
+  body: unknown;
+  headers?: Record<string, string>;
+};
+
+const JSON_HEADERS = { 'content-type': 'application/json; charset=UTF-8' };
+
+/** The fbtrace_id of a refusal: 11 characters drawn from what was refused — stable for one request. */
+const TRACE_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+function traceId(seed: string): string {
+  const hex = blobDigest(new TextEncoder().encode(seed));
+  let out = '';
+  for (let i = 0; i < 11; i += 1) out += TRACE_ALPHABET[parseInt(hex.slice(i * 2, i * 2 + 2), 16) % 64];
+  return out;
+}
+
+export function graphError(status: number, code: number, message: string, extra: { subcode?: number; type?: string; title?: string; userMsg?: string; transient?: boolean } = {}): InstagramResponse {
+  return {
+    status,
+    headers: { ...JSON_HEADERS },
+    body: {
+      error: {
+        message,
+        type: extra.type ?? 'OAuthException',
+        code,
+        ...(extra.subcode !== undefined ? { error_subcode: extra.subcode } : {}),
+        is_transient: extra.transient ?? false,
+        ...(extra.title ? { error_user_title: extra.title } : {}),
+        ...(extra.userMsg ? { error_user_msg: extra.userMsg } : {}),
+        fbtrace_id: traceId(`${status}|${code}|${extra.subcode ?? ''}|${message}`),
+      },
+    },
+  };
+}
+
+/** No token at all. (Code 104 and its wording are the Graph API's long-standing answer; not in the
+ *  pages this build read — `instagram.errors.message_wording`.) */
+export const noToken = (): InstagramResponse => graphError(400, 104, 'An access token is required to request this resource.');
+/** A token the twin never issued. */
+export const invalidToken = (): InstagramResponse => graphError(400, 190, 'Invalid OAuth access token - Cannot parse access token');
+/** A token without the permission this edge needs (Graph code 10, "API Permission Denied"). */
+export const permissionDenied = (what: string): InstagramResponse => graphError(400, 10, `(#10) Application does not have permission for this action: ${what}`);
+/** An unknown node or edge (Graph's "Unsupported get request" family, code 100 subcode 33). */
+export const unsupported = (method: string, id: string): InstagramResponse =>
+  graphError(400, 100, `Unsupported ${method.toLowerCase()} request. Object with ID '${id}' does not exist, cannot be loaded due to missing permissions, or does not support this operation. Please read the Graph API documentation at https://developers.facebook.com/docs/graph-api`, { type: 'GraphMethodException', subcode: 33 });
+/** A path the Graph API does not know. */
+export const unknownPath = (path: string): InstagramResponse => graphError(400, 2500, `Unknown path components: ${path}`);
+export const invalidParam = (message: string, subcode?: number): InstagramResponse => graphError(400, 100, `(#100) ${message}`, subcode !== undefined ? { subcode } : {});
+export const missingParam = (name: string): InstagramResponse => graphError(400, 100, `(#100) The parameter ${name} is required`);
+
+/** Real Instagram Platform surface this twin does not model: refused by name, never answered as a success. */
+export const unmodeled = (what: string): InstagramResponse =>
+  graphError(422, 100, `[twin gap] ${what} is real Instagram Platform surface this twin does not model`);
+
+export const readOnlyRefusal = (): InstagramResponse => graphError(405, 3, '(#3) This twin is read-only');
+
+export function ok(body: unknown, status = 200): InstagramResponse {
+  return { status, body, headers: { ...JSON_HEADERS } };
+}
+
+// ── rupload.facebook.com ────────────────────────────────────────────────────────────────────
+
+export const ruploadOk = (): InstagramResponse => ok({ success: true, message: 'Upload successful.' });
+/** The rupload failure envelope. `type` names are the twin's where the guide gives only its one
+ *  sample (`ProcessingFailedError`, "unauthorized user request"). */
+export function ruploadFailure(status: number, type: string, message: string, retriable = false): InstagramResponse {
+  return { status, headers: { ...JSON_HEADERS }, body: { debug_info: { retriable, type, message: JSON.stringify({ success: false, error: { message } }) } } };
+}