@volter/twin-instagram 0.1.0

package/dist/src/instagram-conformance.d.ts

@@ -0,0 +1,8 @@
+export type InstagramConformanceReport = {
+    ok: boolean;
+    checksRun: number;
+    failures: string[];
+};
+export declare function checkInstagramConformance(options?: {
+    root?: string;
+}): Promise<InstagramConformanceReport>;

package/dist/src/instagram-conformance.js

@@ -0,0 +1,44 @@
+// 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.js";
+export async function checkInstagramConformance(options = {}) {
+    const failures = [];
+    let checks = 0;
+    const check = (name, ok) => { 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, path, body, headers = 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;
+    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?.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?.error?.code === 100 && unknown.body?.error?.error_subcode === 33);
+    const anon = await h('GET', `/v26.0/${ig}`, undefined, {});
+    check('no token is refused', anon.status === 400 && anon.body?.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?.error?.message)));
+    return { ok: failures.length === 0, checksRun: checks, failures };
+}

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

@@ -0,0 +1,79 @@
+import type { PerformContext, PushOutcome, RemoteExecute, TwinAction } from '@volter/world-core';
+import { InstagramBudget } from './instagram-budget.js';
+/** The Graph API version every call this adapter makes pins — the newest the twin models. */
+export declare const INSTAGRAM_VERSION = "v26.0";
+/** Meta's upload host. */
+export declare 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 declare function budgetedInstagramExecute(execute: RemoteExecute, budget?: InstagramBudget): RemoteExecute;
+/** 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 declare const STATUS_POLL_MS = 60000;
+export declare const MAX_STATUS_WAIT_MS = 120000;
+/** A refusal from Meta, with its Graph error code and subcode kept for the caller to read. */
+export declare class InstagramCallError extends Error {
+    readonly label: string;
+    readonly status: number;
+    readonly code?: number;
+    readonly subcode?: number;
+    constructor(label: string, status: number, body: string, json: Record<string, any>);
+}
+/**
+ * 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 declare function uploadTarget(uri: unknown, container: string): string;
+/** The container body a stored Reel crosses as. */
+export declare function containerParamsForVendor(fields: Record<string, any>): Record<string, unknown>;
+/** 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 declare const UPLOAD_CHUNK_BYTES: number;
+/**
+ * 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 declare function uploadReel(execute: RemoteExecute, target: string, bytes: Uint8Array, from?: number, onChunk?: (uploaded: number) => Promise<void>): Promise<void>;
+/** Read a container's status_code on the schedule until it is FINISHED; the verdict otherwise. */
+export declare function waitForContainer(execute: RemoteExecute, container: string, wait?: (ms: number) => Promise<void>): Promise<'FINISHED' | 'ERROR' | 'EXPIRED' | 'PUBLISHED' | 'TIMEOUT'>;
+/**
+ * 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 declare function performInstagramAction(kernelExecute: RemoteExecute, action: TwinAction, ctx: PerformContext): Promise<PushOutcome>;
+/** 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 declare function performInstagramActionWithin(budget: InstagramBudget, kernelExecute: RemoteExecute, action: TwinAction, ctx: PerformContext, wait?: (ms: number) => Promise<void>, now?: () => number): Promise<PushOutcome>;
+/**
+ * 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 declare function syncInstagramFromRemote(kernelExecute: RemoteExecute, opts?: {
+    root?: string;
+    origin?: string;
+    occurredAt?: string;
+    budget?: InstagramBudget;
+    credential?: string;
+}): Promise<{
+    observed: number;
+    users: number;
+    media: number;
+}>;
+/** D7's consumer-facing entry point, the same read as the refresh adapter. */
+export declare function syncInstagramFromReal(execute: RemoteExecute, opts?: {
+    root?: string;
+    occurredAt?: string;
+    budget?: InstagramBudget;
+    credential?: string;
+}): Promise<{
+    observed: number;
+    users: number;
+    media: number;
+}>;

package/dist/src/instagram-connector.js

@@ -0,0 +1,437 @@
+// 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 { clearPerformContainer, CONTAINER_LIFETIME_MS, MAX_REEL_BYTES, readInstagramBlob, readPerformContainer, writePerformContainer } from "./instagram-media.js";
+import { InstagramBudget, instagramCallWeight } from "./instagram-budget.js";
+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, budget = new InstagramBudget()) {
+    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;
+async function call(execute, label, request, expect) {
+    const res = await execute(request);
+    let json = {};
+    if (res.body.trim() !== '') {
+        try {
+            json = JSON.parse(res.body);
+        }
+        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 {
+    label;
+    status;
+    code;
+    subcode;
+    constructor(label, status, body, json) {
+        super(`instagram refused ${label}: HTTP ${status} ${body.slice(0, 300)}`);
+        this.label = label;
+        this.status = status;
+        this.name = 'InstagramCallError';
+        const e = json.error;
+        if (typeof e?.code === 'number')
+            this.code = e.code;
+        if (typeof e?.error_subcode === 'number')
+            this.subcode = e.error_subcode;
+    }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const graph = (path) => `/${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, container) {
+    if (typeof uri === 'string' && uri !== '') {
+        let u;
+        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) {
+    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, target, bytes, from = 0, onChunk = async () => undefined) {
+    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, container, wait = sleep) {
+    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, action, ctx) {
+    // 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, kernelExecute, action, ctx, wait = sleep, now = Date.now) {
+    const execute = budgetedInstagramExecute(kernelExecute, budget);
+    const fields = { ...(action.fields ?? {}) };
+    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;
+    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;
+    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, root) {
+    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, owner, fields, openedMs) {
+    // 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) => String(c ?? '').replace(/@/g, '');
+    const hits = res.json.data.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, container) {
+    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, name) {
+    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() {
+    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, opts = {}) {
+    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, id, f) => 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 = { username: u.username };
+    for (const k of ['name', 'biography', 'website', 'profile_picture_url'])
+        if (typeof u[k] === 'string')
+            userFields[k] = u[k];
+    for (const k of ['followers_count', 'follows_count'])
+        if (typeof u[k] === 'number')
+            userFields[k] = u[k];
+    observe('ig_user', u.id, userFields);
+    let media = 0;
+    let after;
+    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) {
+            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, opts = {}) {
+    return syncInstagramFromRemote(execute, opts);
+}

package/dist/src/instagram-errors.d.ts

@@ -0,0 +1,33 @@
+export type InstagramResponse = {
+    status: number;
+    body: unknown;
+    headers?: Record<string, string>;
+};
+export declare function graphError(status: number, code: number, message: string, extra?: {
+    subcode?: number;
+    type?: string;
+    title?: string;
+    userMsg?: string;
+    transient?: boolean;
+}): InstagramResponse;
+/** 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 declare const noToken: () => InstagramResponse;
+/** A token the twin never issued. */
+export declare const invalidToken: () => InstagramResponse;
+/** A token without the permission this edge needs (Graph code 10, "API Permission Denied"). */
+export declare const permissionDenied: (what: string) => InstagramResponse;
+/** An unknown node or edge (Graph's "Unsupported get request" family, code 100 subcode 33). */
+export declare const unsupported: (method: string, id: string) => InstagramResponse;
+/** A path the Graph API does not know. */
+export declare const unknownPath: (path: string) => InstagramResponse;
+export declare const invalidParam: (message: string, subcode?: number) => InstagramResponse;
+export declare const missingParam: (name: string) => InstagramResponse;
+/** Real Instagram Platform surface this twin does not model: refused by name, never answered as a success. */
+export declare const unmodeled: (what: string) => InstagramResponse;
+export declare const readOnlyRefusal: () => InstagramResponse;
+export declare function ok(body: unknown, status?: number): InstagramResponse;
+export declare const ruploadOk: () => InstagramResponse;
+/** The rupload failure envelope. `type` names are the twin's where the guide gives only its one
+ *  sample (`ProcessingFailedError`, "unauthorized user request"). */
+export declare function ruploadFailure(status: number, type: string, message: string, retriable?: boolean): InstagramResponse;