@fabricorg/experience-runtime 0.2.0

package/dist/contracts.d.ts

@@ -0,0 +1,95 @@
+interface ExperienceScope {
+    tenantId: string;
+    spaceId: string;
+    actorId: string;
+    actorType: string;
+}
+interface RenderPlanFragment {
+    id: string;
+    component?: string;
+    props?: Record<string, unknown>;
+    slot?: string;
+    events?: readonly string[];
+    offlineEvents?: readonly string[];
+    bindings?: readonly string[];
+    children?: readonly RenderPlanFragment[];
+}
+interface ScopedRenderPlan {
+    formatVersion: 1;
+    planId: string;
+    application: string;
+    channel: string;
+    releaseDigest: string;
+    assemblyDigest: string;
+    treeId: string;
+    root: RenderPlanFragment;
+    tokenSet: {
+        name: string;
+        version: string;
+    };
+    expiresAt: string;
+}
+interface ExperienceIntentRequest {
+    planId: string;
+    fragmentId: string;
+    eventName: string;
+    parameters: Record<string, unknown>;
+    idempotencyKey?: string;
+}
+/**
+ * A replay of an action captured while disconnected.
+ *
+ * The marker and the capture moment travel with the request rather than by
+ * adapter convention. An adapter that forwarded a replay as an ordinary intent
+ * would skip the Host's offline eligibility and reconciliation rules, and
+ * capture-authority evidence stamped at receipt cannot truthfully attest when
+ * the operator actually acted.
+ */
+interface ExperienceReplayRequest extends ExperienceIntentRequest {
+    executionReason: "offline_replay";
+    /** RFC 3339 instant the action was captured on the device. */
+    capturedAt: string;
+    idempotencyKey: string;
+}
+interface ExperienceReadRequest {
+    planId: string;
+    fragmentId: string;
+    bindingName: string;
+    parameters?: Record<string, unknown>;
+}
+interface ExperienceGatewayClient {
+    invoke(request: ExperienceIntentRequest): Promise<unknown>;
+    replay?(request: ExperienceReplayRequest): Promise<ExperienceInvocationOutcome>;
+    read(request: ExperienceReadRequest): Promise<{
+        data: unknown;
+        stale?: boolean;
+    }>;
+}
+/**
+ * What a governed submission comes back as.
+ *
+ * The Host reports a refusal by *returning* `reconciliation_required` with the
+ * reason, not by throwing: a lapsed authority is a business outcome rather than
+ * an error. Anything reading only the exception path will count a refusal as a
+ * success.
+ */
+interface ExperienceInvocationOutcome {
+    status?: string;
+    reconciliation?: {
+        kind?: string;
+        message?: string;
+    };
+    /** Present when an adapter's own outcome could not be determined. */
+    adapterReconciliation?: unknown;
+    [key: string]: unknown;
+}
+interface ExperienceSession {
+    readonly plan: ScopedRenderPlan;
+    invoke(fragmentId: string, eventName: string, parameters: Record<string, unknown>, idempotencyKey?: string): Promise<unknown>;
+    read(fragmentId: string, bindingName: string, parameters?: Record<string, unknown>): Promise<{
+        data: unknown;
+        stale?: boolean;
+    }>;
+}
+
+export type { ExperienceGatewayClient, ExperienceIntentRequest, ExperienceInvocationOutcome, ExperienceReadRequest, ExperienceReplayRequest, ExperienceScope, ExperienceSession, RenderPlanFragment, ScopedRenderPlan };

package/dist/contracts.js

@@ -0,0 +1 @@
+//# sourceMappingURL=contracts.js.map

package/dist/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/offline.cjs

@@ -0,0 +1,231 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// offline.ts
+var offline_exports = {};
+__export(offline_exports, {
+  createMemoryOfflineCaptureStore: () => createMemoryOfflineCaptureStore,
+  createOfflineCaptureQueue: () => createOfflineCaptureQueue
+});
+module.exports = __toCommonJS(offline_exports);
+function createOfflineCaptureQueue(options) {
+  if (options.store.protection !== "encrypted-at-rest" && !options.allowEphemeralStore) {
+    throw new Error("Production offline capture requires an encrypted-at-rest store.");
+  }
+  if (!options.gateway.replay) throw new Error("Offline capture requires a gateway replay adapter.");
+  const fragments = indexFragments(options.plan.root);
+  const now = options.now ?? (() => /* @__PURE__ */ new Date());
+  return {
+    async capture(fragmentId, eventName, parameters, idempotencyKey) {
+      const fragment = fragments.get(fragmentId);
+      if (!fragment?.offlineEvents?.includes(eventName)) {
+        throw new Error(`Fragment event "${fragmentId}.${eventName}" is not offline-capturable.`);
+      }
+      if (!idempotencyKey || idempotencyKey.length > 256) throw new Error("Offline capture requires a bounded stable idempotency key.");
+      const capturedAt = now();
+      const captureExpiry = capturedAt.getTime() + (options.captureTtlMs ?? 864e5);
+      const planExpiry = Date.parse(options.plan.expiresAt);
+      if (!Number.isFinite(planExpiry) || planExpiry <= capturedAt.getTime()) throw new Error("Offline capture requires an unexpired render plan.");
+      const safeParameters = cloneOfflineParameters(parameters);
+      const captureId = options.nextCaptureId();
+      if (!captureId.trim()) throw new Error("Offline capture id is required.");
+      const record = {
+        captureId,
+        planId: options.plan.planId,
+        releaseDigest: options.plan.releaseDigest,
+        fragmentId,
+        eventName,
+        parameters: safeParameters,
+        idempotencyKey,
+        capturedAt: capturedAt.toISOString(),
+        expiresAt: new Date(Math.min(captureExpiry, planExpiry)).toISOString()
+      };
+      await options.store.put(record);
+      return record;
+    },
+    async replay() {
+      let completed = 0;
+      let failed = 0;
+      const parked = [];
+      const expired = [];
+      const reconciled = [];
+      for (const record of await options.store.list()) {
+        if (Date.parse(record.expiresAt) <= now().getTime()) {
+          await options.store.remove(record.captureId);
+          expired.push(record);
+          continue;
+        }
+        const request = {
+          planId: record.planId,
+          fragmentId: record.fragmentId,
+          eventName: record.eventName,
+          parameters: record.parameters,
+          idempotencyKey: record.idempotencyKey,
+          executionReason: "offline_replay",
+          capturedAt: record.capturedAt
+        };
+        try {
+          const outcome = await options.gateway.replay(request);
+          await options.store.remove(record.captureId);
+          const disposition = dispositionOf(outcome);
+          const actionInvocationId = typeof outcome?.actionInvocationId === "string" ? outcome.actionInvocationId : void 0;
+          if (disposition.kind === "attention") {
+            reconciled.push({
+              record,
+              status: disposition.status,
+              ...actionInvocationId === void 0 ? {} : { actionInvocationId },
+              certainty: disposition.certainty,
+              reason: disposition.reason
+            });
+          } else if (disposition.kind === "parked") {
+            parked.push({ record, ...actionInvocationId === void 0 ? {} : { actionInvocationId } });
+          } else {
+            completed += 1;
+          }
+        } catch (error) {
+          if (isSettledReplayFailure(error)) {
+            await options.store.remove(record.captureId);
+            reconciled.push({ record, status: "not_delivered", certainty: "refused", reason: messageOf(error) });
+          } else {
+            failed += 1;
+          }
+        }
+      }
+      return { completed, parked, failed, expired, reconciled };
+    }
+  };
+}
+function cloneOfflineParameters(parameters) {
+  let nodes = 0;
+  const visit = (value, depth, key) => {
+    nodes += 1;
+    if (nodes > 1e4 || depth > 20) throw new Error("Offline capture parameters exceed structural limits.");
+    if (key !== void 0 && /(?:authorization|bearer|cookie|credential|password|secret|token|claims?)/i.test(key)) {
+      throw new Error(`Offline capture parameters may not contain credential or claim field "${key}".`);
+    }
+    if (value === null || typeof value === "string" || typeof value === "boolean") return;
+    if (typeof value === "number" && Number.isFinite(value)) return;
+    if (Array.isArray(value)) {
+      value.forEach((entry) => visit(entry, depth + 1));
+      return;
+    }
+    if (value && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype) {
+      for (const [childKey, child] of Object.entries(value)) visit(child, depth + 1, childKey);
+      return;
+    }
+    throw new Error("Offline capture parameters must contain only portable JSON values.");
+  };
+  visit(parameters, 0);
+  const serialized = JSON.stringify(parameters);
+  if (new TextEncoder().encode(serialized).byteLength > 65536) throw new Error("Offline capture parameters exceed the 65536-byte limit.");
+  return structuredClone(parameters);
+}
+function indexFragments(root) {
+  const result = /* @__PURE__ */ new Map();
+  const visit = (fragment) => {
+    result.set(fragment.id, fragment);
+    for (const child of fragment.children ?? []) visit(child);
+  };
+  visit(root);
+  return result;
+}
+function createMemoryOfflineCaptureStore() {
+  const records = /* @__PURE__ */ new Map();
+  return {
+    protection: "ephemeral",
+    async put(record) {
+      if (records.has(record.captureId)) throw new Error(`Offline capture "${record.captureId}" already exists.`);
+      records.set(record.captureId, structuredClone(record));
+    },
+    async list() {
+      return [...records.values()].map((record) => structuredClone(record));
+    },
+    async remove(captureId) {
+      records.delete(captureId);
+    }
+  };
+}
+function messageOf(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function dispositionOf(outcome) {
+  if (!outcome || typeof outcome !== "object") {
+    return {
+      kind: "attention",
+      status: "no_outcome",
+      certainty: "unknown",
+      reason: "the replay adapter returned no outcome, so whether the action was applied is unknown"
+    };
+  }
+  const status = typeof outcome.status === "string" ? outcome.status : "";
+  const reason = outcome.reconciliation?.message ?? outcome.reconciliation?.kind ?? (typeof outcome.error === "string" ? outcome.error : status);
+  switch (status) {
+    case "pending":
+    case "running":
+    case "completed":
+      return { kind: "delivered" };
+    case "waiting_for_approval":
+      return { kind: "parked" };
+    case "reconciliation_required":
+      return {
+        kind: "attention",
+        status,
+        certainty: outcome.adapterReconciliation === void 0 ? "refused" : "unknown",
+        reason
+      };
+    case "blocked_by_policy":
+    case "validation_failed":
+      return { kind: "attention", status, certainty: "refused", reason };
+    case "failed":
+      return { kind: "attention", status, certainty: "unknown", reason };
+    default:
+      return { kind: "attention", status: status || "unknown", certainty: "unknown", reason };
+  }
+}
+function isSettledReplayFailure(error) {
+  return [
+    // The action was never offline-eligible.
+    /not eligible for offline replay/i,
+    // The plan no longer grants, no longer exists, or was never this actor's.
+    /is not granted by the render plan/i,
+    // A plan minted against a superseded deployment. Same class as the
+    // assembly mismatch on the line below it, and equally permanent.
+    /does not match the registered action version/i,
+    /render plan was not found/i,
+    /render plan has expired/i,
+    /scope does not match/i,
+    /belongs to a different application assembly/i,
+    // A capture only gets older, so an age refusal can never come good. This
+    // one is independent of the capture TTL, so nothing else retires it.
+    /capturedAt is older than/i,
+    // Malformed beyond repair: passes the grammar, names no real instant.
+    /capturedAt is not a parseable instant/i,
+    /capturedAt must be an RFC 3339/i
+    // Deliberately absent: a capture dated in the future comes good as real
+    // time advances, and a gateway missing its replay window is a
+    // deployment mistake somebody will fix. Discarding either would destroy
+    // work that a clock correction or a config change would have replayed.
+  ].some((pattern) => pattern.test(messageOf(error)));
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createMemoryOfflineCaptureStore,
+  createOfflineCaptureQueue
+});
+//# sourceMappingURL=offline.cjs.map

package/dist/offline.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../offline.ts"],"sourcesContent":["import type {\n\tExperienceGatewayClient,\n\tExperienceInvocationOutcome,\n\tExperienceReplayRequest,\n\tRenderPlanFragment,\n\tScopedRenderPlan,\n} from \"./contracts\";\n\nexport interface OfflineCaptureRecord {\n\tcaptureId: string;\n\tplanId: string;\n\treleaseDigest: string;\n\tfragmentId: string;\n\teventName: string;\n\tparameters: Record<string, unknown>;\n\tidempotencyKey: string;\n\tcapturedAt: string;\n\texpiresAt: string;\n}\n\nexport interface OfflineCaptureStore {\n\tprotection: \"encrypted-at-rest\" | \"ephemeral\";\n\tput(record: OfflineCaptureRecord): Promise<void>;\n\tlist(): Promise<readonly OfflineCaptureRecord[]>;\n\tremove(captureId: string): Promise<void>;\n}\n\n/** A delivered capture whose outcome a person needs to see. */\nexport interface OfflineReconciliation {\n\trecord: OfflineCaptureRecord;\n\t/** The status the platform returned, so a caller can tell these apart. */\n\tstatus: string;\n\t/**\n\t * The invocation the platform recorded, when it got that far.\n\t *\n\t * `recordExternalReconciliation` needs it, so an outcome of `unknown` that\n\t * omits it cannot be reconciled from this summary — which is the whole\n\t * reason the entry exists.\n\t */\n\tactionInvocationId?: string;\n\t/**\n\t * Whether the effect is known not to have happened, or is simply unknown.\n\t * An adapter that timed out mid-charge is `unknown`: telling an operator it\n\t * was refused would be as wrong as telling them it succeeded.\n\t */\n\tcertainty: \"refused\" | \"unknown\";\n\treason: string;\n}\n\n/** A delivered capture waiting on a human. */\nexport interface OfflineParked {\n\trecord: OfflineCaptureRecord;\n\tactionInvocationId?: string;\n}\n\nexport interface OfflineReplaySummary {\n\t/** Delivered and progressing: the platform has the invocation. */\n\tcompleted: number;\n\t/**\n\t * Delivered and parked awaiting a human decision.\n\t *\n\t * Carries the records, because a bare count leaves nobody able to say which\n\t * action somebody now has to approve.\n\t */\n\tparked: OfflineParked[];\n\t/** Never delivered, and worth another attempt. Still queued. */\n\tfailed: number;\n\t/**\n\t * Outlived the capture TTL or the render plan before it could be sent.\n\t *\n\t * Also carries its records: a capture that expired never reached the\n\t * platform, so this is work the operator did that nobody has.\n\t */\n\texpired: OfflineCaptureRecord[];\n\t/**\n\t * Delivered, and something a person needs to see: refused, invalid, or an\n\t * outcome nobody can determine. Also covers a delivery that can never\n\t * succeed, since retrying one only delays the moment somebody is told.\n\t */\n\treconciled: OfflineReconciliation[];\n}\n\nexport interface OfflineCaptureQueue {\n\tcapture(fragmentId: string, eventName: string, parameters: Record<string, unknown>, idempotencyKey: string): Promise<OfflineCaptureRecord>;\n\treplay(): Promise<OfflineReplaySummary>;\n}\n\nexport function createOfflineCaptureQueue(options: {\n\tplan: ScopedRenderPlan;\n\tstore: OfflineCaptureStore;\n\tgateway: ExperienceGatewayClient;\n\tnextCaptureId(): string;\n\tnow?: () => Date;\n\tcaptureTtlMs?: number;\n\tallowEphemeralStore?: boolean;\n}): OfflineCaptureQueue {\n\tif (options.store.protection !== \"encrypted-at-rest\" && !options.allowEphemeralStore) {\n\t\tthrow new Error(\"Production offline capture requires an encrypted-at-rest store.\");\n\t}\n\tif (!options.gateway.replay) throw new Error(\"Offline capture requires a gateway replay adapter.\");\n\tconst fragments = indexFragments(options.plan.root);\n\tconst now = options.now ?? (() => new Date());\n\treturn {\n\t\tasync capture(fragmentId, eventName, parameters, idempotencyKey) {\n\t\t\tconst fragment = fragments.get(fragmentId);\n\t\t\tif (!fragment?.offlineEvents?.includes(eventName)) {\n\t\t\t\tthrow new Error(`Fragment event \"${fragmentId}.${eventName}\" is not offline-capturable.`);\n\t\t\t}\n\t\t\tif (!idempotencyKey || idempotencyKey.length > 256) throw new Error(\"Offline capture requires a bounded stable idempotency key.\");\n\t\t\tconst capturedAt = now();\n\t\t\tconst captureExpiry = capturedAt.getTime() + (options.captureTtlMs ?? 86_400_000);\n\t\t\tconst planExpiry = Date.parse(options.plan.expiresAt);\n\t\t\tif (!Number.isFinite(planExpiry) || planExpiry <= capturedAt.getTime()) throw new Error(\"Offline capture requires an unexpired render plan.\");\n\t\t\tconst safeParameters = cloneOfflineParameters(parameters);\n\t\t\tconst captureId = options.nextCaptureId();\n\t\t\tif (!captureId.trim()) throw new Error(\"Offline capture id is required.\");\n\t\t\tconst record: OfflineCaptureRecord = {\n\t\t\t\tcaptureId,\n\t\t\t\tplanId: options.plan.planId,\n\t\t\t\treleaseDigest: options.plan.releaseDigest,\n\t\t\t\tfragmentId,\n\t\t\t\teventName,\n\t\t\t\tparameters: safeParameters,\n\t\t\t\tidempotencyKey,\n\t\t\t\tcapturedAt: capturedAt.toISOString(),\n\t\t\t\texpiresAt: new Date(Math.min(captureExpiry, planExpiry)).toISOString(),\n\t\t\t};\n\t\t\tawait options.store.put(record);\n\t\t\treturn record;\n\t\t},\n\t\tasync replay() {\n\t\t\tlet completed = 0;\n\t\t\tlet failed = 0;\n\t\t\tconst parked: OfflineParked[] = [];\n\t\t\tconst expired: OfflineCaptureRecord[] = [];\n\t\t\tconst reconciled: OfflineReconciliation[] = [];\n\t\t\tfor (const record of await options.store.list()) {\n\t\t\t\tif (Date.parse(record.expiresAt) <= now().getTime()) {\n\t\t\t\t\tawait options.store.remove(record.captureId);\n\t\t\t\t\texpired.push(record);\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tconst request: ExperienceReplayRequest = {\n\t\t\t\t\tplanId: record.planId,\n\t\t\t\t\tfragmentId: record.fragmentId,\n\t\t\t\t\teventName: record.eventName,\n\t\t\t\t\tparameters: record.parameters,\n\t\t\t\t\tidempotencyKey: record.idempotencyKey,\n\t\t\t\t\texecutionReason: \"offline_replay\",\n\t\t\t\t\tcapturedAt: record.capturedAt,\n\t\t\t\t};\n\t\t\t\ttry {\n\t\t\t\t\tconst outcome = await options.gateway.replay!(request);\n\n\t\t\t\t\t// Anything returned means the platform durably holds the\n\t\t\t\t\t// invocation, so the capture has done its job either way and\n\t\t\t\t\t// leaves the queue. What differs is whether a person needs to\n\t\t\t\t\t// hear about it, which is decided over the whole status set\n\t\t\t\t\t// rather than the two that were obviously refusals.\n\t\t\t\t\tawait options.store.remove(record.captureId);\n\t\t\t\t\tconst disposition = dispositionOf(outcome);\n\t\t\t\t\tconst actionInvocationId = typeof outcome?.actionInvocationId === \"string\"\n\t\t\t\t\t\t? outcome.actionInvocationId\n\t\t\t\t\t\t: undefined;\n\t\t\t\t\tif (disposition.kind === \"attention\") {\n\t\t\t\t\t\treconciled.push({\n\t\t\t\t\t\t\trecord,\n\t\t\t\t\t\t\tstatus: disposition.status,\n\t\t\t\t\t\t\t...(actionInvocationId === undefined ? {} : { actionInvocationId }),\n\t\t\t\t\t\t\tcertainty: disposition.certainty,\n\t\t\t\t\t\t\treason: disposition.reason,\n\t\t\t\t\t\t});\n\t\t\t\t\t} else if (disposition.kind === \"parked\") {\n\t\t\t\t\t\tparked.push({ record, ...(actionInvocationId === undefined ? {} : { actionInvocationId }) });\n\t\t\t\t\t} else {\n\t\t\t\t\t\tcompleted += 1;\n\t\t\t\t\t}\n\t\t\t\t} catch (error) {\n\t\t\t\t\t// Only genuine throws reach here: the plan expired, the\n\t\t\t\t\t// scope no longer matches, the event is not offline-eligible.\n\t\t\t\t\t// Those are settled, and retrying one only delays the moment\n\t\t\t\t\t// somebody is told. Anything unrecognised stays transient, so\n\t\t\t\t\t// an unfamiliar failure is retried rather than discarded.\n\t\t\t\t\tif (isSettledReplayFailure(error)) {\n\t\t\t\t\t\tawait options.store.remove(record.captureId);\n\t\t\t\t\t\t// Never delivered, and never will be. The effect certainly\n\t\t\t\t\t\t// did not happen, which is more than can be said for a\n\t\t\t\t\t\t// delivery whose outcome came back unknown.\n\t\t\t\t\t\treconciled.push({ record, status: \"not_delivered\", certainty: \"refused\", reason: messageOf(error) });\n\t\t\t\t\t} else {\n\t\t\t\t\t\tfailed += 1;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn { completed, parked, failed, expired, reconciled };\n\t\t},\n\t};\n}\n\nfunction cloneOfflineParameters(parameters: Record<string, unknown>): Record<string, unknown> {\n\tlet nodes = 0;\n\tconst visit = (value: unknown, depth: number, key?: string): void => {\n\t\tnodes += 1;\n\t\tif (nodes > 10_000 || depth > 20) throw new Error(\"Offline capture parameters exceed structural limits.\");\n\t\tif (key !== undefined && /(?:authorization|bearer|cookie|credential|password|secret|token|claims?)/i.test(key)) {\n\t\t\tthrow new Error(`Offline capture parameters may not contain credential or claim field \"${key}\".`);\n\t\t}\n\t\tif (value === null || typeof value === \"string\" || typeof value === \"boolean\") return;\n\t\tif (typeof value === \"number\" && Number.isFinite(value)) return;\n\t\tif (Array.isArray(value)) {\n\t\t\tvalue.forEach((entry) => visit(entry, depth + 1));\n\t\t\treturn;\n\t\t}\n\t\tif (value && typeof value === \"object\" && Object.getPrototypeOf(value) === Object.prototype) {\n\t\t\tfor (const [childKey, child] of Object.entries(value)) visit(child, depth + 1, childKey);\n\t\t\treturn;\n\t\t}\n\t\tthrow new Error(\"Offline capture parameters must contain only portable JSON values.\");\n\t};\n\tvisit(parameters, 0);\n\tconst serialized = JSON.stringify(parameters);\n\tif (new TextEncoder().encode(serialized).byteLength > 65_536) throw new Error(\"Offline capture parameters exceed the 65536-byte limit.\");\n\treturn structuredClone(parameters);\n}\n\nfunction indexFragments(root: RenderPlanFragment): Map<string, RenderPlanFragment> {\n\tconst result = new Map<string, RenderPlanFragment>();\n\tconst visit = (fragment: RenderPlanFragment): void => {\n\t\tresult.set(fragment.id, fragment);\n\t\tfor (const child of fragment.children ?? []) visit(child);\n\t};\n\tvisit(root);\n\treturn result;\n}\n\nexport function createMemoryOfflineCaptureStore(): OfflineCaptureStore {\n\tconst records = new Map<string, OfflineCaptureRecord>();\n\treturn {\n\t\tprotection: \"ephemeral\",\n\t\tasync put(record) {\n\t\t\tif (records.has(record.captureId)) throw new Error(`Offline capture \"${record.captureId}\" already exists.`);\n\t\t\trecords.set(record.captureId, structuredClone(record));\n\t\t},\n\t\tasync list() {\n\t\t\treturn [...records.values()].map((record) => structuredClone(record));\n\t\t},\n\t\tasync remove(captureId) {\n\t\t\trecords.delete(captureId);\n\t\t},\n\t};\n}\n\nfunction messageOf(error: unknown): string {\n\treturn error instanceof Error ? error.message : String(error);\n}\n\ntype ReplayDisposition =\n\t| { kind: \"delivered\" }\n\t| { kind: \"parked\" }\n\t| { kind: \"attention\"; status: string; certainty: \"refused\" | \"unknown\"; reason: string };\n\n/**\n * Read a returned outcome across the platform's whole status set.\n *\n * Enumerating the statuses that looked like refusals left the rest falling\n * through to \"applied\", which is how a validation failure got reported to an\n * operator as success. The switch covers every `ActionStatus`, and the default\n * arm surfaces anything else rather than counting it a success — the status\n * arrives as a string over a transport, so this is a runtime guarantee and not\n * a compile-time one.\n *\n * There is no \"already applied\" branch. A key that legitimately repeats returns\n * the original invocation without complaint, and a genuine idempotency conflict\n * means the key was reused for a materially different command, so that capture\n * was never applied and must not be discarded.\n */\nfunction dispositionOf(outcome: ExperienceInvocationOutcome | undefined): ReplayDisposition {\n\t// An adapter that returns nothing has told us nothing. Reading that as\n\t// success is the failure this whole switch exists to prevent, and an absent\n\t// outcome deserves at least the suspicion an empty one gets.\n\tif (!outcome || typeof outcome !== \"object\") {\n\t\treturn {\n\t\t\tkind: \"attention\",\n\t\t\tstatus: \"no_outcome\",\n\t\t\tcertainty: \"unknown\",\n\t\t\treason: \"the replay adapter returned no outcome, so whether the action was applied is unknown\",\n\t\t};\n\t}\n\tconst status = typeof outcome.status === \"string\" ? outcome.status : \"\";\n\tconst reason = outcome.reconciliation?.message\n\t\t?? outcome.reconciliation?.kind\n\t\t?? (typeof outcome.error === \"string\" ? outcome.error : status);\n\n\tswitch (status) {\n\t\tcase \"pending\":\n\t\tcase \"running\":\n\t\tcase \"completed\":\n\t\t\treturn { kind: \"delivered\" };\n\t\tcase \"waiting_for_approval\":\n\t\t\treturn { kind: \"parked\" };\n\t\tcase \"reconciliation_required\":\n\t\t\t// An adapter whose outcome could not be determined also arrives here.\n\t\t\t// The external effect may well have happened, so calling it refused\n\t\t\t// would be as wrong as calling it applied.\n\t\t\treturn {\n\t\t\t\tkind: \"attention\",\n\t\t\t\tstatus,\n\t\t\t\tcertainty: outcome.adapterReconciliation === undefined ? \"refused\" : \"unknown\",\n\t\t\t\treason,\n\t\t\t};\n\t\tcase \"blocked_by_policy\":\n\t\tcase \"validation_failed\":\n\t\t\t// Both are decided before any effect: policy refuses at the gate and\n\t\t\t// validation refuses the parameters.\n\t\t\treturn { kind: \"attention\", status, certainty: \"refused\", reason };\n\t\tcase \"failed\":\n\t\t\t// Not the same. A handler or adapter step can fail after earlier\n\t\t\t// steps succeeded and the domain transaction committed, so telling an\n\t\t\t// operator this was refused could be as wrong as calling it applied.\n\t\t\treturn { kind: \"attention\", status, certainty: \"unknown\", reason };\n\t\tdefault:\n\t\t\t// An unfamiliar status is surfaced rather than counted as success.\n\t\t\treturn { kind: \"attention\", status: status || \"unknown\", certainty: \"unknown\", reason };\n\t}\n}\n\n/**\n * A thrown failure the platform will never accept on a later attempt.\n *\n * Deliberately narrow, and matched on what the gateway and runtime actually\n * throw. Anything else is transient, because keeping a capture costs a retry\n * and discarding one costs the operator their work.\n */\nfunction isSettledReplayFailure(error: unknown): boolean {\n\treturn [\n\t\t// The action was never offline-eligible.\n\t\t/not eligible for offline replay/i,\n\t\t// The plan no longer grants, no longer exists, or was never this actor's.\n\t\t/is not granted by the render plan/i,\n\t\t// A plan minted against a superseded deployment. Same class as the\n\t\t// assembly mismatch on the line below it, and equally permanent.\n\t\t/does not match the registered action version/i,\n\t\t/render plan was not found/i,\n\t\t/render plan has expired/i,\n\t\t/scope does not match/i,\n\t\t/belongs to a different application assembly/i,\n\t\t// A capture only gets older, so an age refusal can never come good. This\n\t\t// one is independent of the capture TTL, so nothing else retires it.\n\t\t/capturedAt is older than/i,\n\t\t// Malformed beyond repair: passes the grammar, names no real instant.\n\t\t/capturedAt is not a parseable instant/i,\n\t\t/capturedAt must be an RFC 3339/i,\n\t\t// Deliberately absent: a capture dated in the future comes good as real\n\t\t// time advances, and a gateway missing its replay window is a\n\t\t// deployment mistake somebody will fix. Discarding either would destroy\n\t\t// work that a clock correction or a config change would have replayed.\n\t].some((pattern) => pattern.test(messageOf(error)));\n}\n"],"mappings":"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","names":[]}

package/dist/offline.d.cts

@@ -0,0 +1,87 @@
+import { ScopedRenderPlan, ExperienceGatewayClient } from './contracts.cjs';
+
+interface OfflineCaptureRecord {
+    captureId: string;
+    planId: string;
+    releaseDigest: string;
+    fragmentId: string;
+    eventName: string;
+    parameters: Record<string, unknown>;
+    idempotencyKey: string;
+    capturedAt: string;
+    expiresAt: string;
+}
+interface OfflineCaptureStore {
+    protection: "encrypted-at-rest" | "ephemeral";
+    put(record: OfflineCaptureRecord): Promise<void>;
+    list(): Promise<readonly OfflineCaptureRecord[]>;
+    remove(captureId: string): Promise<void>;
+}
+/** A delivered capture whose outcome a person needs to see. */
+interface OfflineReconciliation {
+    record: OfflineCaptureRecord;
+    /** The status the platform returned, so a caller can tell these apart. */
+    status: string;
+    /**
+     * The invocation the platform recorded, when it got that far.
+     *
+     * `recordExternalReconciliation` needs it, so an outcome of `unknown` that
+     * omits it cannot be reconciled from this summary — which is the whole
+     * reason the entry exists.
+     */
+    actionInvocationId?: string;
+    /**
+     * Whether the effect is known not to have happened, or is simply unknown.
+     * An adapter that timed out mid-charge is `unknown`: telling an operator it
+     * was refused would be as wrong as telling them it succeeded.
+     */
+    certainty: "refused" | "unknown";
+    reason: string;
+}
+/** A delivered capture waiting on a human. */
+interface OfflineParked {
+    record: OfflineCaptureRecord;
+    actionInvocationId?: string;
+}
+interface OfflineReplaySummary {
+    /** Delivered and progressing: the platform has the invocation. */
+    completed: number;
+    /**
+     * Delivered and parked awaiting a human decision.
+     *
+     * Carries the records, because a bare count leaves nobody able to say which
+     * action somebody now has to approve.
+     */
+    parked: OfflineParked[];
+    /** Never delivered, and worth another attempt. Still queued. */
+    failed: number;
+    /**
+     * Outlived the capture TTL or the render plan before it could be sent.
+     *
+     * Also carries its records: a capture that expired never reached the
+     * platform, so this is work the operator did that nobody has.
+     */
+    expired: OfflineCaptureRecord[];
+    /**
+     * Delivered, and something a person needs to see: refused, invalid, or an
+     * outcome nobody can determine. Also covers a delivery that can never
+     * succeed, since retrying one only delays the moment somebody is told.
+     */
+    reconciled: OfflineReconciliation[];
+}
+interface OfflineCaptureQueue {
+    capture(fragmentId: string, eventName: string, parameters: Record<string, unknown>, idempotencyKey: string): Promise<OfflineCaptureRecord>;
+    replay(): Promise<OfflineReplaySummary>;
+}
+declare function createOfflineCaptureQueue(options: {
+    plan: ScopedRenderPlan;
+    store: OfflineCaptureStore;
+    gateway: ExperienceGatewayClient;
+    nextCaptureId(): string;
+    now?: () => Date;
+    captureTtlMs?: number;
+    allowEphemeralStore?: boolean;
+}): OfflineCaptureQueue;
+declare function createMemoryOfflineCaptureStore(): OfflineCaptureStore;
+
+export { type OfflineCaptureQueue, type OfflineCaptureRecord, type OfflineCaptureStore, type OfflineParked, type OfflineReconciliation, type OfflineReplaySummary, createMemoryOfflineCaptureStore, createOfflineCaptureQueue };

package/dist/offline.d.ts

@@ -0,0 +1,87 @@
+import { ScopedRenderPlan, ExperienceGatewayClient } from './contracts.js';
+
+interface OfflineCaptureRecord {
+    captureId: string;
+    planId: string;
+    releaseDigest: string;
+    fragmentId: string;
+    eventName: string;
+    parameters: Record<string, unknown>;
+    idempotencyKey: string;
+    capturedAt: string;
+    expiresAt: string;
+}
+interface OfflineCaptureStore {
+    protection: "encrypted-at-rest" | "ephemeral";
+    put(record: OfflineCaptureRecord): Promise<void>;
+    list(): Promise<readonly OfflineCaptureRecord[]>;
+    remove(captureId: string): Promise<void>;
+}
+/** A delivered capture whose outcome a person needs to see. */
+interface OfflineReconciliation {
+    record: OfflineCaptureRecord;
+    /** The status the platform returned, so a caller can tell these apart. */
+    status: string;
+    /**
+     * The invocation the platform recorded, when it got that far.
+     *
+     * `recordExternalReconciliation` needs it, so an outcome of `unknown` that
+     * omits it cannot be reconciled from this summary — which is the whole
+     * reason the entry exists.
+     */
+    actionInvocationId?: string;
+    /**
+     * Whether the effect is known not to have happened, or is simply unknown.
+     * An adapter that timed out mid-charge is `unknown`: telling an operator it
+     * was refused would be as wrong as telling them it succeeded.
+     */
+    certainty: "refused" | "unknown";
+    reason: string;
+}
+/** A delivered capture waiting on a human. */
+interface OfflineParked {
+    record: OfflineCaptureRecord;
+    actionInvocationId?: string;
+}
+interface OfflineReplaySummary {
+    /** Delivered and progressing: the platform has the invocation. */
+    completed: number;
+    /**
+     * Delivered and parked awaiting a human decision.
+     *
+     * Carries the records, because a bare count leaves nobody able to say which
+     * action somebody now has to approve.
+     */
+    parked: OfflineParked[];
+    /** Never delivered, and worth another attempt. Still queued. */
+    failed: number;
+    /**
+     * Outlived the capture TTL or the render plan before it could be sent.
+     *
+     * Also carries its records: a capture that expired never reached the
+     * platform, so this is work the operator did that nobody has.
+     */
+    expired: OfflineCaptureRecord[];
+    /**
+     * Delivered, and something a person needs to see: refused, invalid, or an
+     * outcome nobody can determine. Also covers a delivery that can never
+     * succeed, since retrying one only delays the moment somebody is told.
+     */
+    reconciled: OfflineReconciliation[];
+}
+interface OfflineCaptureQueue {
+    capture(fragmentId: string, eventName: string, parameters: Record<string, unknown>, idempotencyKey: string): Promise<OfflineCaptureRecord>;
+    replay(): Promise<OfflineReplaySummary>;
+}
+declare function createOfflineCaptureQueue(options: {
+    plan: ScopedRenderPlan;
+    store: OfflineCaptureStore;
+    gateway: ExperienceGatewayClient;
+    nextCaptureId(): string;
+    now?: () => Date;
+    captureTtlMs?: number;
+    allowEphemeralStore?: boolean;
+}): OfflineCaptureQueue;
+declare function createMemoryOfflineCaptureStore(): OfflineCaptureStore;
+
+export { type OfflineCaptureQueue, type OfflineCaptureRecord, type OfflineCaptureStore, type OfflineParked, type OfflineReconciliation, type OfflineReplaySummary, createMemoryOfflineCaptureStore, createOfflineCaptureQueue };