@volter/twin-linkedin 0.1.0

package/src/linkedin-conformance.ts

@@ -0,0 +1,73 @@
+// Conformance for the LinkedIn 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: create is a 201 with the URN in x-restli-id and no body, a read is the Post
+// schema, the finder pages as `{paging, elements}`, a delete is an idempotent 204, the version gate
+// answers the two quoted error bodies, and an unmodelled resource is the vendor's not-found.
+import { handleLinkedinTwinRequest } from './linkedin-twin.ts';
+
+export type LinkedinConformanceReport = { ok: boolean; checksRun: number; failures: string[] };
+
+export async function checkLinkedinConformance(options: { root?: string } = {}): Promise<LinkedinConformanceReport> {
+  const failures: string[] = [];
+  let checks = 0;
+  const check = (name: string, ok: boolean) => { checks += 1; if (!ok) failures.push(name); };
+  const root = options.root;
+  const api = { authorization: 'Bearer conformance-token-1', 'linkedin-version': '202609', 'x-restli-protocol-version': '2.0.0' };
+  const h = (method: string, path: string, body?: unknown, headers: Record<string, string> = api) =>
+    handleLinkedinTwinRequest({ method, path, headers, root, occurredAt: '2026-09-26T12:00:00.000Z', ...(body === undefined ? {} : { body: JSON.stringify(body) }) });
+
+  await h('POST', '/_twin/organizations', { id: '5515715', localizedName: 'Conformance Co', vanityName: 'conformance-co', followerCount: 42 }, {});
+  await h('POST', '/_twin/members', { id: 'confAdmin', localizedFirstName: 'Con', localizedLastName: 'Form', email: 'con@example.com' }, {});
+  await h('POST', '/_twin/organizationAcls', { organization: 'urn:li:organization:5515715', roleAssignee: 'urn:li:person:confAdmin', role: 'ADMINISTRATOR' }, {});
+  await h('POST', '/_twin/tokens', { token: 'conformance-token-1', member: 'urn:li:person:confAdmin', scopes: ['w_organization_social', 'r_organization_social', 'rw_organization_admin', 'openid', 'email', 'profile'] }, {});
+
+  const post = { author: 'urn:li:organization:5515715', commentary: 'Follow best practices #coding', visibility: 'PUBLIC', distribution: { feedDistribution: 'MAIN_FEED', targetEntities: [], thirdPartyDistributionChannels: [] }, lifecycleState: 'PUBLISHED', isReshareDisabledByAuthor: false };
+  const created = await h('POST', '/rest/posts', post);
+  const urn = created.headers?.['x-restli-id'] ?? '';
+  check('create answers 201, the URN in x-restli-id, no body', created.status === 201 && /^urn:li:share:\d{19}$/.test(urn) && created.body === null);
+
+  const got = await h('GET', `/rest/posts/${encodeURIComponent(urn)}`);
+  const g = got.body as any;
+  check('a read answers the Post schema, the hashtag as the little template', got.status === 200 && g.id === urn && g.author === post.author
+    && g.commentary === 'Follow best practices {hashtag|\\#|coding}' && g.lifecycleState === 'PUBLISHED' && g.lifecycleStateInfo?.isEditedByAuthor === false
+    && typeof g.createdAt === 'number' && g.publishedAt === g.createdAt && g.distribution?.feedDistribution === 'MAIN_FEED' && Object.keys(g).every((k) => !k.startsWith('_')));
+
+  const found = await h('GET', `/rest/posts?q=author&author=${encodeURIComponent(post.author)}&count=10`);
+  const f = found.body as any;
+  check('the author finder pages as {paging:{start,count,links}, elements}', found.status === 200 && f.paging?.start === 0 && f.paging?.count === 10
+    && Array.isArray(f.paging?.links) && f.elements?.length === 1 && f.elements[0].id === urn);
+
+  const deleted = await h('DELETE', `/rest/posts/${encodeURIComponent(urn)}`);
+  const again = await h('DELETE', `/rest/posts/${encodeURIComponent(urn)}`);
+  const gone = await h('GET', `/rest/posts/${encodeURIComponent(urn)}`);
+  check('delete is an idempotent 204 and the post is gone', deleted.status === 204 && again.status === 204 && gone.status === 404 && (gone.body as any).code === 'NOT_FOUND');
+
+  const noVersion = await h('GET', '/rest/posts?q=author', undefined, { authorization: api.authorization });
+  check('a missing Linkedin-Version is the docs\' 400 VERSION_MISSING body', noVersion.status === 400
+    && JSON.stringify(noVersion.body) === JSON.stringify({ status: 400, code: 'VERSION_MISSING', message: 'A version must be present. Please specify a version by adding the Linkedin-Version header.' }));
+  const oldVersion = await h('GET', '/rest/posts?q=author', undefined, { ...api, 'linkedin-version': '202401' });
+  check('an inactive version is 426 NONEXISTENT_VERSION', oldVersion.status === 426 && (oldVersion.body as any).code === 'NONEXISTENT_VERSION');
+
+  const noToken = await h('GET', '/rest/posts?q=author', undefined, { 'linkedin-version': '202609' });
+  check('no bearer is 401 EMPTY_ACCESS_TOKEN', noToken.status === 401 && (noToken.body as any).code === 'EMPTY_ACCESS_TOKEN');
+
+  const missing = await h('POST', '/rest/posts', { ...post, visibility: undefined });
+  check('a create without visibility is 400 MISSING_FIELD', missing.status === 400 && (missing.body as any).code === 'MISSING_FIELD');
+
+  const unknown = await h('GET', '/rest/adAccounts');
+  check('an unmodelled resource is the vendor\'s not-found, never a success', unknown.status === 404 && (unknown.body as any).code === 'NOT_FOUND');
+
+  const init = await h('POST', '/rest/videos?action=initializeUpload', { initializeUploadRequest: { owner: post.author, fileSizeBytes: 5_000_000, uploadCaptions: false, uploadThumbnail: false } });
+  const v = (init.body as any)?.value;
+  check('video initializeUpload answers 4 MB byte-range instructions on a /dms-uploads URL', init.status === 200 && /^urn:li:video:/.test(v?.video)
+    && v.uploadInstructions?.length === 2 && v.uploadInstructions[0].firstByte === 0 && v.uploadInstructions[0].lastByte === 4194303
+    && v.uploadInstructions[1].firstByte === 4194304 && v.uploadInstructions[1].lastByte === 4999999
+    && /\/dms-uploads\/[^/]+\/uploadedVideo\/0\?.*ut=[0-9a-f]{64}/.test(v.uploadInstructions[0].uploadUrl) && v.uploadToken === '');
+
+  const me = await h('GET', '/v2/userinfo', undefined, { authorization: api.authorization });
+  check('userinfo answers the member (sub, name, email) with no version header', me.status === 200 && (me.body as any).sub === 'confAdmin' && (me.body as any).email === 'con@example.com');
+
+  return { ok: failures.length === 0, checksRun: checks, failures };
+}

package/src/linkedin-connector.ts

@@ -0,0 +1,314 @@
+// LINKEDIN 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 → LinkedIn). A landed `linkedin.post.create` becomes `POST /rest/posts`; a landed
+// `linkedin.post.delete` becomes `DELETE /rest/posts/{urn}`. A post that carries a VIDEO names it on
+// its entry by local asset id and DIGEST (linkedin-twin.ts `_media`). The local video URN means
+// nothing at LinkedIn and an upload is not an entry of its own (linkedin-media.ts), so the adapter
+// reads the file's bytes off the blob seam by digest and uploads them through the Videos API as
+// LinkedIn documents it: `action=initializeUpload`, one PUT per upload instruction with exactly
+// that byte range, each to the signed URL LinkedIn returned (a PRESIGNED request — on
+// www.linkedin.com, not the API host, and sent without the credential; `presigned: true` on the
+// kernel executor), the ETags collected in order, `action=finalizeUpload`, then GET the video until
+// its status is AVAILABLE — bounded, and failing the entry on PROCESSING_FAILED or on the bound —
+// and only then the post, naming the video URN LinkedIn minted.
+//
+// AN IMAGE DOES NOT CROSS. LinkedIn's image upload PUT to www.linkedin.com/dms-uploads needs the
+// member's access token in Authorization; a presigned request carries no credential, and the
+// executor sends the credential only to the root's own origin. So a post with an image (or an
+// article with a thumbnail) fails its perform loudly and names why
+// (`linkedin.connector.perform_image_upload`, todo). The twin still takes the image locally, so the
+// preview and the local write are whole.
+//
+// THE PERFORM AND REFRESH PATHS ARE BUDGETED. The kernel hands the adapters its own executor (the
+// World's sealed credential), which knows nothing of LinkedIn's limits, so each adapter wraps it
+// (`budgetedLinkedinExecute`) in this pack's LinkedinBudget ledger: every API call is charged BEFORE it
+// goes out, a refusal THROWS without calling LinkedIn, 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. The presigned part uploads are not
+// API calls and pass through uncharged (linkedin-budget.ts says why); a perform bounds their number.
+//
+// REFRESH (LinkedIn → twin). The organizations the credential's member administers
+// (`organizationAcls?q=roleAssignee`), each organization with its follower count (`networkSizes`),
+// and each one's posts (`q=author`, paged),
+// OBSERVED through the kernel. A refused read throws; it is never an empty page folded over state.
+import { assertBudgetGuardIntact, observeResource } from '@volter/world-core';
+import type { PerformContext, PushOutcome, RemoteExecute, RemoteExecuteRequest, TwinAction } from '@volter/world-core';
+import { clearPerformVideo, readLinkedinBlob, readPerformVideo, writePerformVideo } from './linkedin-media.ts';
+import { LinkedinBudget, linkedinCallWeight } from './linkedin-budget.ts';
+
+const SERVICE = 'linkedin';
+
+/** The API version every call this adapter makes pins — the latest the twin models. */
+export const LINKEDIN_VERSION = '202609';
+
+const API_HEADERS = { accept: 'application/json', 'linkedin-version': LINKEDIN_VERSION, 'x-restli-protocol-version': '2.0.0' };
+
+/** The feed's video ceiling (Videos API: "File size: Between 75kb and 500MB"): at most 125 parts. */
+const MAX_PERFORM_VIDEO_BYTES = 500 * 1024 * 1024;
+
+/**
+ * The kernel executor, charged to this pack's LinkedinBudget: the check RESERVES before the call and
+ * throws (LinkedinBudgetError) 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. A presigned upload
+ * (not an API call) passes through uncharged.
+ */
+export function budgetedLinkedinExecute(execute: RemoteExecute, budget: LinkedinBudget = new LinkedinBudget()): RemoteExecute {
+  const guard = assertBudgetGuardIntact(budget, LinkedinBudget, 'budgetedLinkedinExecute');
+  return async (request) => {
+    if (request.presigned) return execute(request);
+    const weight = linkedinCallWeight(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;
+  };
+}
+
+/** How long a perform waits on LinkedIn's video processing before it fails the entry. */
+export const MAX_PROCESSING_WAIT_MS = 10 * 60_000;
+/** Between two status reads while a video processes: 2 s, doubling to 15 s. Each read costs one unit
+ *  of the 30-unit-a-minute burst, so the wait backs off instead of spending the burst (and the post
+ *  that must follow it) on status reads: at most 4 reads a minute once it has settled. */
+const PROCESSING_POLL_FIRST_MS = 2_000;
+const PROCESSING_POLL_MAX_MS = 15_000;
+
+/** The wait before the nth status re-read (n from 0) — the schedule the perform follows. */
+export function processingPollWait(n: number): number {
+  return Math.min(PROCESSING_POLL_MAX_MS, PROCESSING_POLL_FIRST_MS * 2 ** Math.max(0, n));
+}
+
+type Reply = { status: number; headers: Record<string, string>; body: string; json: Record<string, any> };
+
+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;
+}
+
+async function call(execute: RemoteExecute, label: string, request: RemoteExecuteRequest, expect: number[]): Promise<Reply> {
+  const res = await execute(request.presigned ? request : { ...request, headers: { ...API_HEADERS, ...(request.headers ?? {}) } });
+  if (!expect.includes(res.status)) throw new Error(`linkedin refused ${label}: HTTP ${res.status} ${res.body.slice(0, 300)}`);
+  let json: Record<string, any> = {};
+  if (res.body.trim() !== '') {
+    try { json = JSON.parse(res.body) as Record<string, any>; } catch { if (!request.presigned) throw new Error(`linkedin answered ${label} with a body that is not JSON: ${res.body.slice(0, 200)}`); }
+  }
+  return { status: res.status, headers: res.headers, body: res.body, json };
+}
+
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+/** The little-format hashtag template back to the `#tag` a create takes (linkedin-twin.ts stores
+ *  the template, as LinkedIn answers it). */
+export function untemplateHashtags(commentary: string): string {
+  return commentary.replace(/\{hashtag\|\\#\|([^}]+)\}/g, '#$1');
+}
+
+/** A video's bytes to LinkedIn: initialize, the presigned part PUTs, finalize, and the bounded wait
+ *  for AVAILABLE. Returns the video URN LinkedIn minted. */
+export async function uploadVideoToVendor(execute: RemoteExecute, owner: string, bytes: Uint8Array, thumbnail?: { bytes: Uint8Array; mediaType: string }, wait: (ms: number) => Promise<void> = sleep, onFinalized?: (video: string) => Promise<void>): Promise<string> {
+  if (bytes.length > MAX_PERFORM_VIDEO_BYTES) throw new Error(`linkedin: a ${bytes.length}-byte video is over the feed's 500 MB; not uploaded`);
+  const init = await call(execute, 'videos initializeUpload', {
+    method: 'POST', path: '/rest/videos?action=initializeUpload', headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ initializeUploadRequest: { owner, fileSizeBytes: bytes.length, uploadCaptions: false, uploadThumbnail: thumbnail !== undefined } }),
+  }, [200]);
+  const value = init.json.value ?? {};
+  const video = value.video;
+  const instructions = value.uploadInstructions;
+  if (typeof video !== 'string' || !/^urn:li:video:/.test(video) || !Array.isArray(instructions) || instructions.length === 0) {
+    throw new Error(`linkedin answered videos initializeUpload without a video and its upload instructions: ${init.body.slice(0, 300)}`);
+  }
+  const etags: string[] = [];
+  for (const [i, part] of (instructions as Array<Record<string, any>>).entries()) {
+    const first = Number(part.firstByte);
+    const last = Number(part.lastByte);
+    if (typeof part.uploadUrl !== 'string' || !Number.isInteger(first) || !Number.isInteger(last) || first < 0 || last < first || last >= bytes.length) {
+      throw new Error(`linkedin answered an unusable upload instruction ${i}: ${JSON.stringify(part).slice(0, 200)}`);
+    }
+    const put = await call(execute, `video part ${i} upload`, {
+      method: 'PUT', path: part.uploadUrl, presigned: true, headers: { 'content-type': 'application/octet-stream' }, body: bytes.subarray(first, last + 1),
+    }, [200, 201]);
+    const etag = headerOf(put.headers, 'etag');
+    if (!etag) throw new Error(`linkedin answered video part ${i} upload with no ETag`);
+    etags.push(etag);
+  }
+  if (thumbnail) {
+    if (typeof value.thumbnailUploadUrl !== 'string') throw new Error('linkedin answered initializeUpload with no thumbnailUploadUrl though a thumbnail was asked for');
+    await call(execute, 'video thumbnail upload', {
+      method: 'PUT', path: value.thumbnailUploadUrl, presigned: true, headers: { 'media-type-family': 'STILLIMAGE', 'content-type': 'application/octet-stream' }, body: thumbnail.bytes,
+    }, [200, 201]);
+  }
+  await call(execute, 'videos finalizeUpload', {
+    method: 'POST', path: '/rest/videos?action=finalizeUpload', headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ finalizeUploadRequest: { video, uploadToken: typeof value.uploadToken === 'string' ? value.uploadToken : '', uploadedPartIds: etags } }),
+  }, [200, 201, 204]);
+  if (onFinalized) await onFinalized(video);
+  return waitForVideo(execute, video, wait);
+}
+
+/** The bounded wait for a finalized video to be AVAILABLE, backing off between status reads. */
+export async function waitForVideo(execute: RemoteExecute, video: string, wait: (ms: number) => Promise<void> = sleep): Promise<string> {
+  const deadline = Date.now() + MAX_PROCESSING_WAIT_MS;
+  for (let n = 0; ; n += 1) {
+    const got = await call(execute, 'videos GET', { method: 'GET', path: `/rest/videos/${encodeURIComponent(video)}` }, [200]);
+    const status = got.json.status;
+    if (status === 'AVAILABLE') return video;
+    if (status === 'PROCESSING_FAILED') throw new Error(`linkedin failed to process ${video}: ${String(got.json.processingFailureReason ?? 'no reason given')}`);
+    if (status !== 'PROCESSING' && status !== 'WAITING_UPLOAD') throw new Error(`linkedin answered ${video} with an unknown status ${JSON.stringify(status)}`);
+    if (Date.now() > deadline) throw new Error(`linkedin was still processing ${video} after ${MAX_PROCESSING_WAIT_MS / 1000}s`);
+    await wait(processingPollWait(n));
+  }
+}
+
+/** The create body a stored post crosses as: its vendor fields, the video named by the vendor's URN. */
+export function postBodyForVendor(fields: Record<string, any>, videoUrn?: string): Record<string, unknown> {
+  const content = fields.content as Record<string, any> | undefined;
+  let crossing: Record<string, unknown> | undefined;
+  if (content?.media) crossing = { media: { ...content.media, id: videoUrn ?? content.media.id } };
+  else if (content?.article) crossing = { article: content.article };
+  return {
+    author: fields.author,
+    commentary: untemplateHashtags(String(fields.commentary ?? '')),
+    visibility: fields.visibility,
+    distribution: { feedDistribution: fields.distribution?.feedDistribution ?? 'MAIN_FEED', targetEntities: [], thirdPartyDistributionChannels: [] },
+    ...(crossing ? { content: crossing } : {}),
+    lifecycleState: 'PUBLISHED',
+    isReshareDisabledByAuthor: fields.isReshareDisabledByAuthor === true,
+  };
+}
+
+/**
+ * The perform adapter (runtime contract R18): what a World's deploy calls for each landed LinkedIn
+ * entry on a twin whose root is real. A seeded page, member, role or token is the twin's own record
+ * and crosses nothing.
+ */
+export async function performLinkedinAction(kernelExecute: RemoteExecute, action: TwinAction, ctx: PerformContext): Promise<PushOutcome> {
+  // one ledger per real credential (the sealed credential's keyed fingerprint), as X and YouTube key theirs:
+  // two World roots sealed with one credential spend one allowance
+  return performLinkedinActionWithin(new LinkedinBudget(ctx.credential !== undefined ? { token: ctx.credential } : ctx.root !== undefined ? { root: ctx.root } : {}), kernelExecute, action, ctx);
+}
+
+/** The perform, charged to a given budget: the box's ledger in production (`performLinkedinAction`),
+ *  a throwaway ledger where a verify must not spend the operator's allowance. */
+export async function performLinkedinActionWithin(budget: LinkedinBudget, kernelExecute: RemoteExecute, action: TwinAction, ctx: PerformContext, wait: (ms: number) => Promise<void> = sleep): Promise<PushOutcome> {
+  const execute = budgetedLinkedinExecute(kernelExecute, budget);
+  const fields = { ...(action.fields ?? {}) } as Record<string, any>;
+  const subjectId = action.subject?.id ?? '';
+  if ((action.operation ?? '').startsWith('linkedin.twin.')) {
+    return { externalId: ctx.resolve(action.subject?.type ?? 'organization', subjectId), data: { performed: false, reason: `${action.operation} is the twin's own record — nothing at LinkedIn to write` } };
+  }
+  if (action.operation === 'linkedin.post.delete') {
+    const target = ctx.resolve('post', subjectId);
+    // "Post deletions are idempotent": a 204 either way.
+    await call(execute, 'posts DELETE', { method: 'DELETE', path: `/rest/posts/${encodeURIComponent(target)}`, headers: { 'x-restli-method': 'DELETE' } }, [204]);
+    return { externalId: target, data: { deleted: true } };
+  }
+  if (action.operation !== 'linkedin.post.create') throw new Error(`linkedin cannot perform ${action.operation ?? 'this entry'} on ${subjectId}: no LinkedIn request expresses it`);
+
+  let videoUrn: string | undefined;
+  const media = fields._media as Record<string, any> | undefined;
+  if (media) {
+    if (media.kind !== 'video') {
+      throw new Error(`linkedin cannot perform ${subjectId}: its image must be uploaded to www.linkedin.com/dms-uploads WITH the API token in Authorization, and a presigned upload carries no credential (linkedin.connector.perform_image_upload)`);
+    }
+    const bytes = typeof media.sha256 === 'string' ? await readLinkedinBlob(media.sha256, ctx.root) : null;
+    if (!bytes) throw new Error(`linkedin cannot perform ${subjectId}: the bytes of urn:li:video:${String(media.id)} are not on this twin's blob seam`);
+    const thumbBytes = typeof media.thumbnail_sha256 === 'string' ? await readLinkedinBlob(media.thumbnail_sha256, ctx.root) : null;
+    if (typeof media.thumbnail_sha256 === 'string' && !thumbBytes) throw new Error(`linkedin cannot perform ${subjectId}: its video thumbnail's bytes are not on this twin's blob seam`);
+    // a retry of an entry whose video was finalized at the vendor posts THAT video: no second upload
+    const kept = await readPerformVideo(action.id, ctx.root);
+    if (kept && kept.sha256 === media.sha256) {
+      const got = await execute({ method: 'GET', path: `/rest/videos/${encodeURIComponent(kept.video)}`, headers: { ...API_HEADERS } });
+      let status: unknown;
+      if (got.status === 200) {
+        try { status = (JSON.parse(got.body || '{}') as Record<string, any>).status; } catch {
+          throw new Error(`linkedin answered the kept video ${kept.video} with a body that is not JSON: ${got.body.slice(0, 200)}; not uploading it again — perform again`);
+        }
+      }
+      if (status === 'AVAILABLE' || status === 'PROCESSING') videoUrn = await waitForVideo(execute, kept.video, wait);
+      else if (got.status !== 404 && status !== 'PROCESSING_FAILED') throw new Error(`linkedin answered the kept video ${kept.video} with HTTP ${got.status} ${got.body.slice(0, 200)}; not uploading it again — perform again`);
+    }
+    videoUrn ??= await uploadVideoToVendor(execute, String(fields.author), bytes, thumbBytes ? { bytes: thumbBytes, mediaType: String(media.thumbnail_media_type ?? 'image/jpeg') } : undefined, wait,
+      (video) => writePerformVideo(action.id, { video, sha256: String(media.sha256) }, ctx.root));
+  }
+  const created = await call(execute, 'posts CREATE', {
+    method: 'POST', path: '/rest/posts', headers: { 'content-type': 'application/json' }, body: JSON.stringify(postBodyForVendor(fields, videoUrn)),
+  }, [201]);
+  const urn = headerOf(created.headers, 'x-restli-id');
+  if (!urn || !/^urn:li:(share|ugcPost):\d+$/.test(urn)) throw new Error(`linkedin answered posts CREATE with no post URN in x-restli-id: ${JSON.stringify(created.headers).slice(0, 200)}`);
+  if (videoUrn) await clearPerformVideo(action.id, ctx.root);
+  return { externalId: urn, url: `https://www.linkedin.com/feed/update/${urn}/`, data: { ...(videoUrn ? { video: videoUrn } : {}) } };
+}
+
+// ── refresh ──────────────────────────────────────────────────────────────────────────────────
+
+/** How many pages of one organization's posts a refresh reads before it refuses to go on. */
+const MAX_PAGES = 50;
+
+let lastPollMs = 0;
+/** A MOVING observation instant, strictly increasing in the process — never a pinned constant. */
+function pollTimestamp(): string {
+  const now = Date.now();
+  lastPollMs = now > lastPollMs ? now : lastPollMs + 1;
+  return new Date(lastPollMs).toISOString();
+}
+
+/**
+ * The refresh adapter: the organizations the credential's member administers, and every post each
+ * one authored, observed into the parent log. Read-side only. A refusal throws.
+ */
+export async function syncLinkedinFromRemote(kernelExecute: RemoteExecute, opts: { root?: string; origin?: string; occurredAt?: string; budget?: LinkedinBudget; credential?: string } = {}): Promise<{ observed: number; organizations: number; posts: number }> {
+  // keyed like perform: by the credential's fingerprint when the caller has one, else by the root
+  const execute = budgetedLinkedinExecute(kernelExecute, opts.budget ?? new LinkedinBudget(opts.credential !== undefined ? { token: opts.credential } : opts.root !== undefined ? { root: opts.root } : {}));
+  const at = opts.occurredAt ?? pollTimestamp();
+  const observe = (type: string, id: string, fields: Record<string, unknown>) =>
+    observeResource(SERVICE, { type, id, fields }, { ...(opts.root !== undefined ? { root: opts.root } : {}), at });
+  const acls = await call(execute, 'organizationAcls FINDER roleAssignee', { method: 'GET', path: '/rest/organizationAcls?q=roleAssignee&role=ADMINISTRATOR&state=APPROVED&count=100' }, [200]);
+  if (!Array.isArray(acls.json.elements)) throw new Error(`linkedin answered organizationAcls with no elements: ${acls.body.slice(0, 200)}`);
+  const orgs = [...new Set((acls.json.elements as Array<Record<string, any>>).map((e) => String(e.organization ?? e.organizationTarget ?? '')).filter((o) => /^urn:li:organization:\d+$/.test(o)))];
+  let posts = 0;
+  for (const org of orgs) {
+    const id = org.split(':').pop()!;
+    const got = await call(execute, `organizations GET ${id}`, { method: 'GET', path: `/rest/organizations/${id}` }, [200]);
+    const o = got.json;
+    if (typeof o.localizedName !== 'string' || typeof o.vanityName !== 'string') throw new Error(`linkedin answered organization ${id} without its name: ${got.body.slice(0, 200)}`);
+    const size = await call(execute, `networkSizes GET ${id}`, { method: 'GET', path: `/rest/networkSizes/${encodeURIComponent(org)}?edgeType=COMPANY_FOLLOWED_BY_MEMBER` }, [200]);
+    if (typeof size.json.firstDegreeSize !== 'number') throw new Error(`linkedin answered networkSizes for ${org} without firstDegreeSize: ${size.body.slice(0, 200)}`);
+    observe('organization', id, {
+      localizedName: o.localizedName, vanityName: o.vanityName, followerCount: size.json.firstDegreeSize,
+      ...(Array.isArray(o.industries) ? { industries: o.industries } : {}),
+      ...(typeof o.localizedWebsite === 'string' ? { localizedWebsite: o.localizedWebsite } : {}),
+      ...(typeof o.localizedDescription === 'string' ? { localizedDescription: o.localizedDescription } : {}),
+      ...(typeof o.logoV2?.original === 'string' && /^urn:li:image:/.test(o.logoV2.original) ? { logo: o.logoV2.original } : {}),
+    });
+    for (let page = 0, start = 0; ; page += 1) {
+      if (page >= MAX_PAGES) throw new Error(`linkedin posts of ${org} exceeded ${MAX_PAGES} pages; refusing to page further`);
+      const res = await call(execute, `posts FINDER author ${org}`, { method: 'GET', path: `/rest/posts?q=author&author=${encodeURIComponent(org)}&count=100&start=${start}&sortBy=CREATED` }, [200]);
+      const elements = res.json.elements;
+      if (!Array.isArray(elements)) throw new Error(`linkedin answered the posts finder with no elements: ${res.body.slice(0, 200)}`);
+      for (const post of elements as Array<Record<string, any>>) {
+        if (typeof post.id !== 'string' || !/^urn:li:(share|ugcPost):\d+$/.test(post.id)) throw new Error(`linkedin answered a post with no LinkedIn-shaped id: ${JSON.stringify(post).slice(0, 200)}`);
+        const { id: postId, ...rest } = post;
+        observe('post', postId, rest);
+        posts += 1;
+      }
+      const next = Array.isArray(res.json.paging?.links) && (res.json.paging.links as Array<Record<string, any>>).some((l) => l.rel === 'next');
+      if (!next || elements.length === 0) break;
+      start += elements.length;
+    }
+  }
+  return { observed: orgs.length + posts, organizations: orgs.length, posts };
+}
+
+/**
+ * D7's consumer-facing entry point, the same read as the refresh adapter: everything readable from
+ * the organizations the credential's member administers, observed into the twin's log.
+ */
+export async function syncLinkedinFromReal(execute: RemoteExecute, opts: { root?: string; occurredAt?: string; budget?: LinkedinBudget; credential?: string } = {}): Promise<{ observed: number; organizations: number; posts: number }> {
+  return syncLinkedinFromRemote(execute, opts);
+}

package/src/linkedin-errors.ts

@@ -0,0 +1,58 @@
+// LinkedIn's error envelope for the versioned `/rest` surface.
+//
+// SHAPE. `{ status, code, message }` — the Marketing API's error body (learn.microsoft.com
+// /linkedin/marketing/error-responses, li-lms-2026-09): `status` the HTTP status, `code` the constant
+// category, `message` the description. Two samples on that page are quoted exactly here: the missing
+// version header (400 VERSION_MISSING) and an inactive version (426 NONEXISTENT_VERSION). The
+// per-resource codes (MISSING_FIELD, INVALID_VALUE_FOR_FIELD, INVALID_URN_TYPE, INVALID_URN_ID,
+// ACCESS_DENIED, NOT_FOUND, EMPTY_ACCESS_TOKEN, UNPROCESSABLE_ENTITY, MEDIA_ASSET_WAITING_UPLOAD,
+// MEDIA_ASSET_PROCESSING_FAILED, EXPIRED_UPLOAD_URL) are the Posts and Videos API pages' own
+// "API Error Details" tables.
+//
+// EVIDENCE BOUNDARY. `serviceErrorCode` is part of the envelope, but no page this build read gives
+// the number for these refusals, so it is omitted rather than invented
+// (`linkedin.errors.service_error_codes`). Message wording beyond the quoted samples states the
+// refusal plainly and is not claimed to be LinkedIn's (`linkedin.errors.message_wording`).
+
+export type LinkedinResponse = {
+  status: number;
+  body: unknown;
+  headers?: Record<string, string>;
+};
+
+const JSON_HEADERS = { 'content-type': 'application/json', 'x-restli-protocol-version': '2.0.0' };
+
+export function problem(status: number, code: string, message: string): LinkedinResponse {
+  return { status, body: { status, code, message }, headers: { ...JSON_HEADERS } };
+}
+
+export const versionMissing = (): LinkedinResponse =>
+  problem(400, 'VERSION_MISSING', 'A version must be present. Please specify a version by adding the Linkedin-Version header.');
+
+export const versionInactive = (version: string): LinkedinResponse =>
+  problem(426, 'NONEXISTENT_VERSION', `Requested version ${version} is not active`);
+
+export const emptyAccessToken = (): LinkedinResponse => problem(401, 'EMPTY_ACCESS_TOKEN', 'Empty oauth2_access_token');
+export const invalidAccessToken = (): LinkedinResponse => problem(401, 'INVALID_ACCESS_TOKEN', 'Invalid access token');
+export const accessDenied = (message: string): LinkedinResponse => problem(403, 'ACCESS_DENIED', message);
+export const notFound = (message = 'Not Found'): LinkedinResponse => problem(404, 'NOT_FOUND', message);
+export const missingField = (field: string): LinkedinResponse => problem(400, 'MISSING_FIELD', `${field} is required but missing`);
+export const invalidValue = (field: string, value: unknown): LinkedinResponse =>
+  problem(400, 'INVALID_VALUE_FOR_FIELD', `${field} cannot be set to ${typeof value === 'string' ? value : JSON.stringify(value)}`);
+export const invalidUrnType = (field: string, value: unknown, urnType: string): LinkedinResponse =>
+  problem(400, 'INVALID_URN_TYPE', `${field} value ${String(value)} must be a ${urnType} URN`);
+export const invalidUrnId = (value: unknown): LinkedinResponse => problem(400, 'INVALID_URN_ID', `This URN ID is invalid: ${String(value)}`);
+
+/** Real LinkedIn surface this twin does not model: refused by name, never answered as a success. */
+export const unmodeled = (what: string): LinkedinResponse =>
+  problem(422, 'UNPROCESSABLE_ENTITY', `[twin gap] ${what} is real LinkedIn surface this twin does not model`);
+
+export const readOnlyRefusal = (): LinkedinResponse => problem(405, 'METHOD_NOT_ALLOWED', 'This twin is read-only');
+
+export function ok(body: unknown, status = 200, headers: Record<string, string> = {}): LinkedinResponse {
+  return { status, body, headers: { ...JSON_HEADERS, ...headers } };
+}
+
+export function noContent(headers: Record<string, string> = {}): LinkedinResponse {
+  return { status: 204, body: '', headers: { 'x-restli-protocol-version': '2.0.0', ...headers } };
+}