@nodaro/shared 2.7.0 → 2.10.0

package/src/organizations/views.ts

@@ -0,0 +1,220 @@
+import type {
+  MemberStatus,
+  OrgKind,
+  OrgRole,
+  OrgSettings,
+  OrgStatus,
+  WorkspaceRole,
+  WorkspaceSettings,
+} from "./types.js"
+
+/**
+ * What the organization endpoints RETURN.
+ *
+ * `types.ts` carries what a client must send and the codes it must dispatch
+ * on; this carries the other half of the same wire contract — the shapes that
+ * come back. It lives here for the same reason: the SDK, the CLI, the app and
+ * any third-party integration all read these, and a shape described in three
+ * places is a shape that drifts in two of them.
+ *
+ * CONTRACT ONLY, like its sibling. There is no resolution logic here, no
+ * access rule, no vocabulary — a view names fields, it does not decide who
+ * may see them. Fields the server omits for a caller without the standing to
+ * see them are OPTIONAL here rather than nullable: absent means "not for
+ * you", `null` means "genuinely unset", and a client that cannot tell those
+ * apart will render the wrong thing.
+ */
+
+export interface OrganizationView {
+  id: string
+  slug: string
+  name: string
+  kind: OrgKind
+  status: OrgStatus
+  ownerUserId: string
+  settings: OrgSettings
+  termsAcceptedAt: string | null
+  createdAt: string
+  updatedAt: string
+  /** The CALLER's role. Absent on a read that did not establish membership. */
+  role?: OrgRole
+  memberStatus?: MemberStatus
+}
+
+export interface OrgMemberView {
+  userId: string
+  role: OrgRole
+  status: MemberStatus
+  joinedAt: string
+  email: string | null
+  displayName: string | null
+  avatarUrl: string | null
+}
+
+export interface WorkspaceView {
+  id: string
+  orgId: string
+  name: string
+  slug: string
+  description: string | null
+  settings: WorkspaceSettings
+  defaultProjectId: string | null
+  archived: boolean
+  archivedAt: string | null
+  createdAt: string
+  updatedAt: string
+  /** The CALLER's role. Absent on a read that did not establish membership. */
+  role?: WorkspaceRole
+  memberStatus?: MemberStatus
+}
+
+export interface WorkspaceMemberView {
+  userId: string
+  role: WorkspaceRole
+  displayName: string | null
+  avatarUrl: string | null
+  addedAt: string
+  /** Workspace admins only — absent for a plain member's read. */
+  status?: MemberStatus
+  creditCap?: number | null
+}
+
+/** Where an invitation stands. `expired` is derived from `expiresAt`, not stored. */
+export type InvitationState = "open" | "accepted" | "revoked" | "expired"
+
+export interface InvitationView {
+  id: string
+  orgId: string
+  workspaceId: string | null
+  email: string
+  orgRole: OrgRole
+  workspaceRole: WorkspaceRole | null
+  invitedBy: string | null
+  state: InvitationState
+  expiresAt: string
+  acceptedAt: string | null
+  revokedAt: string | null
+  createdAt: string
+}
+
+/**
+ * One row per address a create/resend was asked for.
+ *
+ * `link` is present whenever the address was NOT emailed — an install with no
+ * mail provider, or a delivery that failed. A client MUST surface it: the
+ * invitation exists either way, and without the link nobody can reach it.
+ */
+export interface InvitationDelivery {
+  email: string
+  status: "sent" | "link_only" | "failed"
+  link?: string
+}
+
+/**
+ * What an invitee sees BEFORE signing in — the one organization read that
+ * needs no token. `email` comes back masked, so the invitee can recognise
+ * their own address without the link disclosing it to whoever holds it.
+ */
+export interface InvitationPreview {
+  orgName: string
+  kind: OrgKind
+  vocabulary: Record<string, string>
+  inviterName: string | null
+  workspaceName: string | null
+  email: string
+  expiresAt: string
+  state: InvitationState
+}
+
+export interface JoinCodeView {
+  code: string
+  enabled: boolean
+  rotatedAt: string
+  rotatedBy: string | null
+}
+
+/**
+ * What `GET /v1/me` reports about the caller's memberships.
+ *
+ * Deliberately a SUMMARY, not the full views above: this is the payload every
+ * client loads on every session start, and it answers one question — what am
+ * I a member of, and what may I call each thing. Names, roles, and the
+ * resolved vocabulary are here because a switcher cannot render without them;
+ * descriptions, timestamps and default projects are not, because a switcher
+ * never shows them and `GET /v1/orgs/:id` exists.
+ *
+ * The settings block is narrowed to the three keys a CLIENT can act on. The
+ * rest of an organization's settings are enforced server-side, and shipping
+ * them here would invite a client to enforce them badly.
+ */
+export interface OrganizationSummary {
+  id: string
+  slug: string
+  name: string
+  kind: OrgKind
+  status: OrgStatus
+  /** The caller's own role and standing — always present in this payload. */
+  role: OrgRole
+  memberStatus: MemberStatus
+  settings: {
+    personal_space_enabled: boolean
+    allowed_email_domains: string[]
+    vocabulary_overrides: Record<string, string>
+  }
+  /** Resolved labels, so no client hard-codes "Class" or "Team". */
+  vocabulary: Record<string, string>
+}
+
+export interface WorkspaceSummary {
+  id: string
+  orgId: string
+  name: string
+  slug: string
+  role: WorkspaceRole
+  memberStatus: MemberStatus
+  archived: boolean
+}
+
+/**
+ * The organizations block on `GET /v1/me`.
+ *
+ * THREE distinct states, and a client that collapses them is wrong in a way
+ * users feel: the fields ABSENT means this install has no organizations at
+ * all; present and empty means the account belongs to none; and
+ * `organizationsUnavailable` means the lookup FAILED — in which case a
+ * client must KEEP whatever selection it already had, because telling someone
+ * their school vanished during a cache blip is worse than a stale switcher.
+ */
+export interface MeOrganizations {
+  organizations?: OrganizationSummary[]
+  workspaces?: WorkspaceSummary[]
+  lastWorkspaceId?: string | null
+  organizationsUnavailable?: boolean
+}
+
+/**
+ * One recorded action in an organization's audit log.
+ *
+ * `action` is an OPEN vocabulary and a client must not exhaust it: new
+ * actions are added as the product grows, and a switch that throws on an
+ * unknown one turns a new feature into a broken page. Render what you
+ * recognise, fall back to the raw string for the rest.
+ *
+ * `actor` is null for anything the system did on nobody's behalf.
+ */
+export interface OrgAuditEntry {
+  id: string
+  workspaceId: string | null
+  action: string
+  targetType: string | null
+  targetId: string | null
+  details: Record<string, unknown>
+  createdAt: string
+  actor: { userId: string; displayName: string | null; email: string | null } | null
+}
+
+/** A cursor-paged read. The cursor is part of the answer, not a side channel. */
+export interface OrgPage<T> {
+  data: T[]
+  nextCursor: string | null
+}

package/src/producer-types.ts

@@ -79,6 +79,12 @@ export const VIDEO_PRODUCER_TYPES: ReadonlySet<string> = new Set([
   "cinematic-avatar",
   // Assemble Narrated Video: fits N (clip, voice) blocks into one MP4 → video.
   "assemble-narrated-video",
+  // Still to Video: one still image + one audio track → MP4 (local FFmpeg,
+  // no provider). Emits generatedVideoUrl like every other ffmpeg video node.
+  "still-to-video",
+  // Slideshow: 2-100 stills + one optional audio track → MP4 (local FFmpeg,
+  // no provider). Same contract; images arrive via the image-collage lane.
+  "slideshow",
 ])
 
 /**

package/src/smart-cut-windows.ts

@@ -1,19 +1,12 @@
 /**
- * Smart-cut best-pair SEARCH WINDOWS — the shared bound + clamp for
+ * Smart-cut SEARCH WINDOWS — the shared bound + clamp for
  * generate-video-pro's `smartCutFramesPrev` / `smartCutFramesNext`.
  *
- * What they do: the best-pair matcher (the mode the node calls "legacy-8x8")
- * PSNR-compares the last N frames of a segment against the first M of the
- * next, ends the previous clip ON the best match and starts the next right
- * AFTER its twin — so the duplicated frame plays once and motion stays
- * continuous. N and M are those windows. Absent → the engine's own 8/8
- * default, which is byte-identical to the behavior before they were
- * exposed.
- *
- * Why wider helps: a continuation can re-enact a longer stretch of the
- * previous tail than 8 frames covers, and a match outside the window is
- * simply never found — the boundary silently falls back to the fixed
- * freeze-trims. recast pins 24/24 for exactly this reason.
+ * They bound how much of each side of a boundary the engine considers when
+ * it places the cut: N frames from the end of a segment and M from the start
+ * of the next. Absent → the engine's own default, byte-identical to the
+ * behavior before they were exposed. A boundary the engine cannot resolve
+ * inside the window falls back to the fixed freeze-trims; recast pins 24/24.
  *
  * Why a shared clamp: the canvas node (single-node Run) and the orchestrator
  * (workflow Run) are two independent send paths into the same engine route,
@@ -23,10 +16,8 @@
  * and the two paths cannot drift apart.
  */
 
-/** Widest window the UI offers. The engine route itself accepts up to 48;
- *  24 is the product cap — it already covers a full second of re-enactment
- *  at 24fps, and every frame added past the real overlap only costs match
- *  time and invites a spurious pairing. */
+/** Widest window the UI offers (the engine route itself accepts up to 48).
+ *  Past this, added frames only cost search time and invite a false match. */
 export const SMART_CUT_WINDOW_MAX = 24
 /** Narrowest meaningful window — one frame each side. */
 export const SMART_CUT_WINDOW_MIN = 1

package/src/suno-track-sources.ts

@@ -0,0 +1,23 @@
+/**
+ * Node types whose output carries Suno chaining ids (`sunoTrackId` /
+ * `sunoTaskId`) for a downstream Suno node (extend / separate / replace /
+ * add-vocals / …) to chain off.
+ *
+ * One set for the three readers — the canvas resolver, the orchestrator
+ * resolver, and the config panels' "Inherited" hint (#819). They used to keep
+ * their own copies and drifted: the canvas read ids off a `suno-separate`
+ * (whose output is stems, not a track) while the orchestrator ignored it, so
+ * the same graph resolved on one path and not the other. Structural
+ * vocabulary only — node type names, no prompt content.
+ */
+export const SUNO_TRACK_SOURCE_TYPES: ReadonlySet<string> = new Set([
+  "suno-generate",
+  "suno-cover",
+  "suno-extend",
+  "suno-mashup",
+  "suno-replace-section",
+  "suno-add-instrumental",
+  "suno-add-vocals",
+  "suno-convert-wav",
+  "suno-upload-extend",
+])

package/src/surround.ts

@@ -1,48 +1,25 @@
 /**
- * Surround continuation — shared single source of truth.
+ * Surround continuation — the shared WIRE CONTRACT.
  *
  * The Location 360° "look-around" builds each ring view (45°, 90°, …) as an
- * image-to-image continuation of the previous view. The platform forces
- * geometric continuity by handing the model a half-done frame: one edge holds
- * the previous view's carried pixels, the rest is flat gray, and the model is
- * asked to paint the gray region.
+ * image-to-image continuation of the previous one.
  *
- * This module owns the bits that are pure and reused across the route Zod
- * schema, the SDK input type, and the worker: the direction enum, the carried
- * fraction defaults, and the fill prompt. The geometry math + sharp compositing
- * + color harmonization live backend-side (they need `sharp`).
+ * This module owns only what the route Zod schema, the SDK input type, and the
+ * worker all need to agree on: the direction enum and the carried-fraction
+ * defaults. The fill prompt lives in `@nodaro/prompts` (never published) and
+ * the compositing/harmonization engine is private.
  */
 
 /**
- * The carry/paint axis for a continuation.
- *
- * PAN (horizontal — half-carry continuation):
- * - `right` — turning right: the new frame's LEFT edge continues the previous
- *   view's RIGHT edge, so the carried band sits on the LEFT, painted on the RIGHT.
- * - `left` — turning left: the new frame's RIGHT edge continues the previous
- *   view's LEFT edge, so the carried band sits on the RIGHT, painted on the LEFT.
- *   (Mirror of `right`. Lets studio chain BOTH ways from a keyframe, capping
- *   chain depth so quality doesn't compound down a long one-way chain.)
- *
- * TILT (vertical — thin-strip, subject-driven re-render):
- * - `up` — tilting straight up: render the open SKY overhead. A thin strip of
- *   the establishing shot's TOP edge is carried into the new frame's BOTTOM for
- *   a soft horizon transition; the rest is painted as sky (NOT a mirrored
- *   landscape).
- * - `down` — tilting straight down: render the GROUND below. A thin strip of the
- *   BOTTOM edge is carried into the new frame's TOP.
+ * The camera move a continuation represents: `right` / `left` pan the view
+ * horizontally, `up` / `down` tilt it vertically.
  */
 export const SURROUND_DIRECTIONS = ["right", "left", "up", "down"] as const
 export type SurroundDirection = (typeof SURROUND_DIRECTIONS)[number]
 
-/** Half the frame is carried for a horizontal pan (matches studio's composite). */
+/** Default carried fraction for a horizontal pan. */
 export const DEFAULT_CARRIED_FRACTION = 0.5
-/**
- * Tilts carry only a thin horizon strip. Carrying half of a horizontal frame is
- * exactly what makes the model echo/mirror the landscape vertically instead of
- * rendering what's actually overhead/underfoot — so tilts keep the carry small
- * and let the tilt prompt drive the subject.
- */
+/** Default carried fraction for a vertical tilt. */
 export const TILT_CARRIED_FRACTION = 0.12
 
 /** True for the vertical tilt directions (up/down), false for the pans. */
@@ -54,60 +31,3 @@ export function isTiltDirection(direction: SurroundDirection): boolean {
 export function defaultCarriedFraction(direction: SurroundDirection): number {
   return isTiltDirection(direction) ? TILT_CARRIED_FRACTION : DEFAULT_CARRIED_FRACTION
 }
-
-/** Which edge of the NEW frame holds the carried pixels vs the painted region. */
-const EDGE: Record<SurroundDirection, { carried: string; painted: string }> = {
-  right: { carried: "left", painted: "right" },
-  left: { carried: "right", painted: "left" },
-  up: { carried: "bottom", painted: "top" },
-  down: { carried: "top", painted: "bottom" },
-}
-
-/** What a tilt must actually render (NOT a continuation of the landscape). */
-const TILT_SUBJECT: Record<"up" | "down", { word: string; subject: string; where: string }> = {
-  up: {
-    word: "up",
-    subject: "the open sky directly overhead — sky, clouds, or (for an interior) the canopy or ceiling",
-    where: "overhead",
-  },
-  down: {
-    word: "down",
-    subject: "the ground directly below — terrain, floor, or water surface",
-    where: "below",
-  },
-}
-
-/**
- * Build the fill prompt the model receives alongside the half-carry composite.
- *
- * `userPrompt` (an optional scene hint from the caller) is woven in front. PAN
- * directions get the seamless-continuation prompt (with the anti-golden-hour
- * negative that fights the documented warm-regrade drift). TILT directions get a
- * subject-forcing prompt — render the sky / ground overhead / below, explicitly
- * NOT a mirrored landscape — which is what stops the vertical echo.
- */
-export function buildSurroundFillPrompt(direction: SurroundDirection, userPrompt?: string): string {
-  const scene = userPrompt && userPrompt.trim() ? `${userPrompt.trim()}. ` : ""
-  const { carried, painted } = EDGE[direction]
-
-  if (direction === "up" || direction === "down") {
-    const t = TILT_SUBJECT[direction]
-    return (
-      `${scene}` +
-      `This is a camera tilted straight ${t.word} from the same scene. The ${carried} strip holds real, finished pixels from the edge of the horizon view; the ${painted} region is flat gray and MUST be painted as ${t.subject}. ` +
-      `Render what is genuinely ${t.where} — do NOT repeat, mirror, or continue the landscape, and do NOT draw a horizon line or distant scenery in the painted region. ` +
-      `CRITICAL: keep the ${carried} strip unchanged and match the scene's EXACT lighting, time of day, white balance, and color grade — the same light as the ${carried} strip; no golden hour, no sunset, no warm relight, no cinematic regrade. ` +
-      `Blend smoothly into the ${carried} strip with no visible seam. No people, no text, no labels, no watermarks.`
-    )
-  }
-
-  // pan (right / left)
-  return (
-    `${scene}` +
-    `This is a partial frame: the ${carried} portion contains real, finished pixels and the ${painted} portion is flat gray that MUST be painted in. ` +
-    `Paint ONLY the ${painted} gray region as a natural, seamless continuation of the ${carried} portion — same scene, same perspective, continuing the horizon, geometry, and content across the boundary with no break. ` +
-    `Keep the ${carried} portion completely unchanged. ` +
-    `CRITICAL: do NOT change the lighting, exposure, white balance, or time of day. Match the ${carried} portion's EXACT light, color temperature, and contrast across the whole frame — if it is flat overcast daylight, keep flat overcast daylight. No golden hour, no sunset, no warm relight, no cinematic regrade. ` +
-    `The seam between the ${carried} and ${painted} portions must be invisible. No people, no text, no labels, no watermarks.`
-  )
-}

package/src/video-analysis-pricing.ts

@@ -9,14 +9,12 @@
  * `buildVideoAnalysisCreditId` + `/v1/credits/model-cost`) all derive from
  * these.
  *
- * The measured-rate constants and the $-derived `videoAnalysisBucketCredits`
- * formula that GENERATE these numbers live PRIVATELY in the
- * `@nodaroai/cloud-plugins` package (`src/plugins/video-analysis/cost.ts`) —
- * never in this public repo. They were first moved out of this package
- * (published Apache-2.0 on npm) per the 2026-07-06 public-flip IP audit S5,
- * then out of the app repo entirely alongside the rest of the video-analysis
- * node. A cross-check test in that private package guards this table so the
- * public numbers can't silently drift from the formula.
+ * The rate constants and the formula that GENERATE these numbers live
+ * PRIVATELY in the `@nodaroai/cloud-plugins` package — never in this public
+ * repo. They were first moved out of this package (published Apache-2.0 on
+ * npm), then out of the app repo entirely alongside the rest of the
+ * video-analysis node. A cross-check test in that private package guards
+ * this table so the public numbers can't silently drift from the formula.
  *
  * `VIDEO_ANALYSIS_BUCKET_CREDITS` below is the precomputed OUTPUT of that
  * private formula for every (model × bucket) combination — a plain credit
@@ -24,9 +22,8 @@
  * `VIDEO_CLIP_CREDITS` uses in `film-pricing.ts`. It is what the frontend's
  * client-side cost preview (`estimateNodeCredits` in
  * workflow-editor/types.ts) reads instead of calling the formula directly.
- * The formula's own test in `@nodaroai/cloud-plugins`
- * (`src/plugins/video-analysis/__tests__/cost.test.ts`) cross-checks this table
- * against it and fails on drift. There is deliberately NO app-side formula to
+ * The formula's own test in `@nodaroai/cloud-plugins` cross-checks this
+ * table against it and fails on drift. There is deliberately NO app-side formula to
  * check against — it was moved private in 2026-07 and the old backend test
  * went with it.
  *
@@ -65,27 +62,20 @@ export const VIDEO_ANALYSIS_WINDOW = { LEN: WINDOW_LEN, STRIDE: WINDOW_STRIDE, O
 // not 110). The plugin's cost test now covers sentinels as well, so this class
 // of drift fails CI instead of shipping.
 // REGENERATED 2026-07-31 with the smart-tier re-base (formula inputs moved in
-// the plugin: sampling 24→6 fps after a 43-run measurement found 6 equal on
-// content and strictly better on cast stability; the system-prompt and
-// per-window output-token constants trued-up to directly measured values).
-// Net effect: smart drops 27–47% per bucket — the 24 fps token spend was also
-// partly paying for media tokens the provider clamped and never counted — and
-// the economy rows tick up 3–6% from the prompt-token true-up.
+// the plugin: sampling 24→6 fps, which proved equal on content and better on
+// cast stability; system-prompt and per-window output-token constants updated).
+// Net effect: smart drops 27–47% per bucket, and the economy rows tick up 3–6%.
 //
-// REGENERATED 2026-08-03 — V1 hybrid-smart reprice (task A3), from the
-// plugin's own generator (`scripts/gen-va-buckets.mjs`) at
-// nodaroai/nodaro-cloud-plugins commit eef077d (branch fix/va-cost-trueup).
-// This is the V1 true-up of task P6's provisional judge/refine/frame-judge
-// constants, re-derived from a 2026-08-03 staging measurement and approved by
-// Tal (the constants themselves, like the rest of the $-derived formula, stay
-// private in the plugin repo — never in this public package). `smart` is now
-// a HYBRID plan — one native 6fps skeleton pass plus 2 fast + 2 pro donor
-// rolls, always refined (`selectionMode` does not apply to `smart`; it always
-// refines) — and every multi-roll tier now carries its own explicit
-// judge/refine terms instead of an implicit share of a single-pass budget.
-// This is the full, honest reprice Tal approved, including the economy tiers
-// (fast 33->185 @180s ends a below-cost combine exposure that existed at the
-// old price). Net effect, per bucket (every row rises):
+// REGENERATED 2026-08-03 — V1 hybrid-smart reprice, from the plugin's own
+// generator. This is the V1 true-up of the earlier provisional
+// judge/refine/frame-judge constants (the constants themselves, like the rest
+// of the formula, stay private in the plugin repo — never in this public
+// package). `smart` is now a multi-roll plan that always refines its merged
+// result (`selectionMode` does not apply to it), and every multi-roll tier
+// now carries its own explicit judge/refine terms instead of an implicit
+// share of a single-pass budget.
+// The economy tiers rise too (fast 33->185 @180s).
+// Net effect, per bucket (every row rises):
 //
 //   gemini-3-flash    60s   24->180   180s   33->185   360s   86-> 514   600s  143-> 846
 //   gemini-3.6-flash  60s   65->203   180s   92->218   360s  237-> 598   600s  395-> 986
@@ -119,9 +109,8 @@ export const VIDEO_ANALYSIS_BUCKET_CREDITS: Record<string, number> = {
   "video-analysis:mixed:180s": 289,
   "video-analysis:mixed:360s": 724,
   "video-analysis:mixed:600s": 1169,
-  // SMART — the accuracy tier, and since the 2026-08-03 hybrid re-plan a
-  // multi-roll plan like the others: one native 6fps skeleton pass plus 2
-  // fast + 2 pro donor rolls, always refined (`selectionMode` does not apply
+  // SMART — the accuracy tier, and since the 2026-08-03 re-plan a multi-roll
+  // plan like the others, always refined (`selectionMode` does not apply
   // here — smart always refines; it never offers a cheaper "choose" path).
   // Priced above the economy tiers because it genuinely costs more to run;
   // the only tier whose accuracy is validated against a hand-counted edit
@@ -168,7 +157,7 @@ export function videoAnalysisNumWindows(bucketSec: number): number {
  * Precomputed credit cost for the `video-audit` node ("AI Audit") — the same
  * pattern as `VIDEO_ANALYSIS_BUCKET_CREDITS` above: the OUTPUT of the private
  * `videoAuditBucketCredits` formula in `@nodaroai/cloud-plugins`
- * (`src/plugins/video-analysis/cost.ts`), a plain lookup table never a
+ * (in the plugin repo), a plain lookup table never a
  * formula, cross-checked against that package's own cost test. Shares the
  * SAME duration-bucket ladder as video-analysis (`VIDEO_ANALYSIS_DURATION_BUCKETS`
  * / `pickVideoAnalysisBucket`) — the audit re-watches the same clip, so it
@@ -195,7 +184,7 @@ export function videoAnalysisNumWindows(bucketSec: number): number {
  * `buildVideoAnalysisCreditId`.
  *
  * Values pasted verbatim from the plugin generator's output
- * (`scripts/gen-va-buckets.mjs`) at `@nodaroai/cloud-plugins` v0.102.0 —
+ * (the plugin repo's bucket generator) —
  * never hand computed. The plugin's cost test cross-checks every row.
  */
 export const VIDEO_AUDIT_BUCKET_CREDITS: Record<string, number> = {

package/src/workflow-export.ts

@@ -74,6 +74,45 @@ export interface WorkflowExportLocation {
   styleLock?: boolean | null
 }
 
+/** A media URL referenced from a node's data, located by node + field path. */
+export interface WorkflowMediaRef {
+  nodeId: string
+  nodeLabel?: string
+  /** Dot/bracket path inside `node.data`, e.g. `imageUrl` or `referenceImageUrls[1]`. */
+  field: string
+  url: string
+}
+
+/**
+ * Export-time portability analysis (#866). A bundle exported from a private
+ * host carries media URLs only that host can serve (`http://localhost:3000/
+ * storage/…`, a LAN address, a `.internal` name); imported anywhere else, the
+ * nodes fail at Run time with an opaque provider fetch error. The exporter
+ * lists those URLs here so the person exporting is told BEFORE sharing, and
+ * an importer can explain what will not load. Absent when every media URL is
+ * publicly routable.
+ */
+export interface WorkflowPortability {
+  unreachableMedia: WorkflowMediaRef[]
+}
+
+/**
+ * What the importer did about the bundle's media (#866). Publicly reachable
+ * media that is not already on the importing instance's own storage is
+ * copied there (`rehosted`) so the workflow runs from local copies; media on
+ * a host the importer cannot reach is left as-is and listed (`unreachable`);
+ * anything declined for another reason (too large, not a media type, over
+ * the per-import cap, upload failed) is listed with the reason (`skipped`).
+ */
+export interface WorkflowImportReport {
+  rehosted: number
+  unreachable: WorkflowMediaRef[]
+  skipped: Array<WorkflowMediaRef & { reason: string }>
+  /** Anything else the importer should know, e.g. copies were made but the
+   *  workflow could not be updated to use them. */
+  notes?: string[]
+}
+
 export interface WorkflowExport {
   version: 1
   exportedAt: string
@@ -87,6 +126,8 @@ export interface WorkflowExport {
     creatures?: WorkflowExportCreature[]
     locations: WorkflowExportLocation[]
   }
+  /** Present only when the bundle references media another instance cannot fetch. */
+  portability?: WorkflowPortability
 }
 
 /**