@hraness/ghostget 0.17.2

package/src/client.ts

@@ -0,0 +1,2726 @@
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { types as nodeTypes } from "node:util";
+
+import { canonicalJson, sha256 } from "./canonical-json";
+import type {
+  CapabilityReadRequest,
+  InvokeCapabilityOptions,
+  InvokeCapabilitySyncOptions,
+  ReadCapabilityOptions,
+  ReadProjectionCacheResult,
+  ReadProjectionCacheOutcome,
+  ReadProjectionPublication,
+  RevalidateCapabilityOptions,
+  RevalidatedCapability,
+  RevalidatedCapabilityCurrent,
+  GhostgetClientInvocationResult,
+  GhostgetClientLocalCliContractIdentity,
+  GhostgetClientLocalCliToolIdentity,
+  GhostgetClientPortableOperationIdentity,
+  GhostgetClientReadFailure,
+  GhostgetClientRunReceipt,
+} from "./client-types";
+import {
+  isProviderPluginOperationName,
+  isProviderPluginSurfaceId,
+  PROVIDER_PLUGIN_ID_MAX_LENGTH,
+  PROVIDER_PLUGIN_OPERATION_NAME_MAX_LENGTH,
+} from "./provider-plugin-identifiers";
+import { parsePortableOperationIdentityV1 } from "./provider-plugin-portable-identity";
+
+type JsonRecord = Record<string, unknown>;
+type ReadProjectionCacheHit = Extract<
+  ReadProjectionCacheResult,
+  { readonly status: "hit" }
+>;
+
+const MAX_INPUT_BYTES = 1024 * 1024;
+const MAX_OUTPUT_BYTES = 20 * 1024 * 1024;
+const MAX_ERROR_BYTES = 8 * 1024;
+const MAX_RUN_RECEIPT_ERROR_BYTES = 12 * 1024;
+const MAX_FRESH_FOR_MS = 365 * 24 * 60 * 60 * 1_000;
+const MAX_INPUT_DEPTH = 64;
+const MAX_INPUT_NODES = 100_000;
+const abortSignalAbortedGetter = (() => {
+  const descriptor = Object.getOwnPropertyDescriptor(
+    AbortSignal.prototype,
+    "aborted",
+  );
+  const getter = descriptor === undefined
+    ? undefined
+    : Reflect.get(descriptor, "get") as unknown;
+  return typeof getter !== "function"
+    ? undefined
+    : (value: unknown): unknown => Reflect.apply(getter, value, []);
+})();
+
+type JsonSnapshot =
+  | null
+  | boolean
+  | number
+  | string
+  | readonly JsonSnapshot[]
+  | { readonly [key: string]: JsonSnapshot };
+
+type PreparedRequest = {
+  readonly adapterId: string;
+  readonly operationId: string;
+  readonly authId?: string;
+  readonly input: string;
+};
+
+const PUBLIC_WEB_SESSION_AUTHORITY_KIND = "public-web-session";
+
+type PublicWebSessionAuthority = {
+  readonly schemaVersion: 1;
+  readonly id: string;
+  readonly kind: typeof PUBLIC_WEB_SESSION_AUTHORITY_KIND;
+  readonly subject: string;
+};
+
+function publicWebSessionAuthority(
+  request: Pick<PreparedRequest, "adapterId" | "operationId">,
+): PublicWebSessionAuthority {
+  const coordinate = Object.freeze({
+    adapter: request.adapterId,
+    operation: request.operationId,
+  });
+  return Object.freeze({
+    schemaVersion: 1,
+    id: `public-${sha256(canonicalJson(coordinate)).slice(0, 32)}`,
+    kind: PUBLIC_WEB_SESSION_AUTHORITY_KIND,
+    subject: `public:${request.adapterId}:${request.operationId}`,
+  });
+}
+
+function expectedRequestAuthId(
+  request: PreparedRequest,
+  authKind: string,
+): string {
+  if (authKind === PUBLIC_WEB_SESSION_AUTHORITY_KIND) {
+    if (request.authId !== undefined) {
+      throw new Error("Ghostget public invocation unexpectedly accepted an auth locator");
+    }
+    return publicWebSessionAuthority(request).id;
+  }
+  return request.authId ?? request.adapterId;
+}
+
+type PreparedCommand = {
+  readonly arguments: readonly string[];
+  readonly input: string;
+};
+
+type PreparedChildEnvironment = Readonly<Record<string, string>>;
+
+type PreparedClientOptions = {
+  readonly cwd: string;
+  readonly environment: PreparedChildEnvironment;
+  readonly freshForMs?: number;
+  readonly now?: Date;
+  readonly headed?: boolean;
+  readonly signal?: AbortSignal;
+};
+
+type ProjectionIdentity =
+  | {
+      readonly status: "ready";
+      readonly key: string;
+      readonly authIdentity: string;
+      readonly authHash: string;
+      readonly inputHash: string;
+    }
+  | {
+      readonly status: "unbound";
+      readonly authIdentity: string;
+      readonly authHash: string;
+      readonly inputHash: string;
+    };
+
+type ExecutionIdentity = {
+  readonly adapter: {
+    readonly id: string;
+    readonly version: string;
+    readonly hash: string;
+  };
+  readonly operation: string;
+} & (
+  | {
+      readonly schemaVersion: 2;
+      readonly transport: "browser";
+    }
+  | {
+      readonly schemaVersion: 3;
+      readonly transport: "provider-api";
+      readonly providerContractHash: string;
+    }
+  | {
+      readonly schemaVersion: 4;
+      readonly transport: "web-session-api";
+      readonly webSessionContractHash: string;
+    }
+  | {
+      readonly schemaVersion: 5;
+      readonly transport: "reviewed-template-api";
+      readonly reviewedTemplateContractHash: string;
+    }
+  | {
+      readonly schemaVersion: 6;
+      readonly transport: "portable-provider-plugin";
+      readonly portablePluginContract: GhostgetClientPortableOperationIdentity;
+    }
+  | {
+      readonly schemaVersion: 7;
+      readonly transport: "local-cli";
+      readonly localCliContract: GhostgetClientLocalCliContractIdentity;
+    }
+);
+
+type PreviewExecutionIdentity = {
+  readonly adapter: ExecutionIdentity["adapter"];
+  readonly operation: string;
+} & (
+  | { readonly transport: "browser" }
+  | { readonly transport: "provider-api" }
+  | { readonly transport: "web-session-api" }
+  | { readonly transport: "reviewed-template-api" }
+  | { readonly transport: "local-cli" }
+  | {
+      readonly transport: "portable-provider-plugin";
+      readonly portablePluginContract: GhostgetClientPortableOperationIdentity;
+    }
+);
+
+function isRecord(value: unknown): value is JsonRecord {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isUnknownArray(value: unknown): value is readonly unknown[] {
+  return Array.isArray(value);
+}
+
+function record(value: unknown, label: string): JsonRecord {
+  if (
+    !isRecord(value)
+    || nodeTypes.isProxy(value)
+    || (
+      Object.getPrototypeOf(value) !== Object.prototype
+      && Object.getPrototypeOf(value) !== null
+    )
+  ) throw new Error(`${label} must be a plain data object`);
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  if (Reflect.ownKeys(descriptors).some((key) => typeof key !== "string")) {
+    throw new Error(`${label} must be a plain data object`);
+  }
+  const result: JsonRecord = {};
+  for (const [key, descriptor] of Object.entries(descriptors)) {
+    if (!descriptor.enumerable || !("value" in descriptor)) {
+      throw new Error(`${label} must be a plain data object`);
+    }
+    Object.defineProperty(result, key, {
+      configurable: true,
+      enumerable: true,
+      value: descriptor.value,
+      writable: true,
+    });
+  }
+  return result;
+}
+
+function assertExactKeys(
+  value: JsonRecord,
+  required: readonly string[],
+  optional: readonly string[],
+  label: string,
+): void {
+  const allowed = new Set([...required, ...optional]);
+  const keys = Object.keys(value);
+  if (
+    required.some((key) => !Object.hasOwn(value, key))
+    || keys.some((key) => !allowed.has(key))
+  ) throw new Error(`${label} is malformed`);
+}
+
+const clientReadFailureRetryDisposition = Object.freeze({
+  "target-unavailable": "do-not-retry",
+  "auth-repair-required": "repair-auth",
+  "account-mismatch": "do-not-retry",
+  "provider-throttled": "retry-once-after-60s",
+  "provider-temporary": "retry-once-after-60s",
+  "operation-timeout": "retry-once-after-60s",
+  "contract-drift": "do-not-retry",
+  "cleanup-required": "do-not-retry",
+} as const satisfies Readonly<Record<
+  GhostgetClientReadFailure["category"],
+  GhostgetClientReadFailure["retryDisposition"]
+>>);
+
+function parseClientReadFailure(value: unknown): GhostgetClientReadFailure {
+  const failure = record(value, "Ghostget read failure");
+  assertExactKeys(
+    failure,
+    ["category", "retryDisposition"],
+    [],
+    "Ghostget read failure",
+  );
+  const category = failure.category;
+  if (
+    typeof category !== "string"
+    || !Object.hasOwn(clientReadFailureRetryDisposition, category)
+  ) throw new Error("Ghostget read failure category is malformed");
+  const retryDisposition = clientReadFailureRetryDisposition[
+    category as GhostgetClientReadFailure["category"]
+  ];
+  if (failure.retryDisposition !== retryDisposition) {
+    throw new Error("Ghostget read failure retry disposition is inconsistent");
+  }
+  return Object.freeze({ category, retryDisposition }) as GhostgetClientReadFailure;
+}
+
+/**
+ * Clone caller-owned input from property descriptors. Accessors are rejected
+ * without being invoked, and a shared object is inspected at most once.
+ */
+function snapshotJson(value: unknown, label: string): JsonSnapshot {
+  let nodes = 0;
+  const ancestors = new WeakSet<object>();
+  const completed = new WeakMap<object, JsonSnapshot>();
+  const visit = (candidate: unknown, depth: number): JsonSnapshot => {
+    nodes += 1;
+    if (nodes > MAX_INPUT_NODES || depth > MAX_INPUT_DEPTH) {
+      throw new Error(`${label} exceeds its structural bound`);
+    }
+    if (
+      candidate === null
+      || typeof candidate === "boolean"
+      || typeof candidate === "string"
+    ) return candidate;
+    if (typeof candidate === "number") {
+      if (!Number.isFinite(candidate)) {
+        throw new Error(`${label} must contain only JSON data`);
+      }
+      return candidate;
+    }
+    if (typeof candidate !== "object") {
+      throw new Error(`${label} must contain only JSON data`);
+    }
+    if (nodeTypes.isProxy(candidate)) {
+      throw new Error(`${label} must not contain proxies`);
+    }
+    const prior = completed.get(candidate);
+    if (prior !== undefined) return prior;
+    if (ancestors.has(candidate)) throw new Error(`${label} must not be circular`);
+    ancestors.add(candidate);
+    try {
+      if (Array.isArray(candidate)) {
+        if (Object.getPrototypeOf(candidate) !== Array.prototype) {
+          throw new Error(`${label} arrays must use the standard prototype`);
+        }
+        const descriptors = Object.getOwnPropertyDescriptors(candidate) as unknown as
+          Readonly<Record<string, PropertyDescriptor>>;
+        const descriptorKeys = Reflect.ownKeys(descriptors);
+        if (descriptorKeys.some((key) => typeof key !== "string")) {
+          throw new Error(`${label} arrays have unsupported symbol fields`);
+        }
+        const lengthDescriptor = descriptors.length;
+        if (
+          lengthDescriptor === undefined
+          || !("value" in lengthDescriptor)
+          || typeof lengthDescriptor.value !== "number"
+          || !Number.isSafeInteger(lengthDescriptor.value)
+          || lengthDescriptor.value < 0
+        ) throw new Error(`${label} arrays are malformed`);
+        const length = lengthDescriptor.value;
+        const keys = descriptorKeys.filter(
+          (key): key is string => typeof key === "string" && key !== "length",
+        );
+        if (
+          keys.length !== length
+          || keys.some((key, index) => key !== String(index))
+        ) throw new Error(`${label} arrays must be dense data arrays`);
+        const cloned: JsonSnapshot[] = [];
+        for (let index = 0; index < length; index += 1) {
+          const descriptor = descriptors[String(index)];
+          if (
+            descriptor === undefined
+            || !descriptor.enumerable
+            || !("value" in descriptor)
+          ) throw new Error(`${label} arrays must contain only data elements`);
+          cloned.push(visit(descriptor.value, depth + 1));
+        }
+        const snapshot = Object.freeze(cloned);
+        completed.set(candidate, snapshot);
+        return snapshot;
+      }
+      const prototype = Object.getPrototypeOf(candidate) as unknown;
+      if (prototype !== Object.prototype && prototype !== null) {
+        throw new Error(`${label} objects must use a plain prototype`);
+      }
+      const descriptors = Object.getOwnPropertyDescriptors(candidate);
+      const descriptorKeys = Reflect.ownKeys(descriptors);
+      if (descriptorKeys.some((key) => typeof key !== "string")) {
+        throw new Error(`${label} objects have unsupported symbol fields`);
+      }
+      const cloned: JsonRecord = {};
+      for (const key of (descriptorKeys as string[]).sort((left, right) =>
+        left.localeCompare(right))) {
+        const descriptor = descriptors[key];
+        if (
+          descriptor === undefined
+          || !descriptor.enumerable
+          || !("value" in descriptor)
+        ) throw new Error(`${label} objects must contain only data properties`);
+        Object.defineProperty(cloned, key, {
+          value: visit(descriptor.value, depth + 1),
+          enumerable: true,
+          configurable: false,
+          writable: false,
+        });
+      }
+      const snapshot = Object.freeze(cloned) as JsonSnapshot;
+      completed.set(candidate, snapshot);
+      return snapshot;
+    } finally {
+      ancestors.delete(candidate);
+    }
+  };
+  return visit(value, 0);
+}
+
+function safeString(value: unknown, label: string, maximum = 512): string {
+  if (
+    typeof value !== "string"
+    || value.length < 1
+    || value.length > maximum
+    || value.trim() !== value
+    || [...value].some((character) => {
+      const code = character.codePointAt(0) ?? -1;
+      return code <= 0x1f || code === 0x7f;
+    })
+  ) throw new Error(`${label} is malformed`);
+  return value;
+}
+
+function providerOperationName(value: unknown, label: string): string {
+  const operation = safeString(
+    value,
+    label,
+    PROVIDER_PLUGIN_OPERATION_NAME_MAX_LENGTH,
+  );
+  if (!isProviderPluginOperationName(operation)) {
+    throw new Error(`${label} is malformed`);
+  }
+  return operation;
+}
+
+function providerSurfaceId(value: unknown, label: string): string {
+  const surface = safeString(value, label, PROVIDER_PLUGIN_ID_MAX_LENGTH);
+  if (!isProviderPluginSurfaceId(surface)) {
+    throw new Error(`${label} is malformed`);
+  }
+  return surface;
+}
+
+function boundedUtf8String(
+  value: unknown,
+  label: string,
+  maximumBytes: number,
+): string {
+  if (
+    typeof value !== "string"
+    || Buffer.byteLength(value, "utf8") > maximumBytes
+  ) throw new Error(`${label} is malformed`);
+  return value;
+}
+
+function digest(value: unknown, label: string): string {
+  const text = safeString(value, label, 64);
+  if (!/^[a-f0-9]{64}$/u.test(text)) throw new Error(`${label} is malformed`);
+  return text;
+}
+
+function safeInteger(
+  value: unknown,
+  label: string,
+  minimum: number,
+  maximum: number,
+): number {
+  if (!Number.isSafeInteger(value) || typeof value !== "number" || value < minimum || value > maximum) {
+    throw new Error(`${label} is malformed`);
+  }
+  return value;
+}
+
+function timestamp(value: unknown, label: string): string {
+  const text = safeString(value, label, 64);
+  const date = new Date(text);
+  if (!Number.isFinite(date.getTime()) || date.toISOString() !== text) {
+    throw new Error(`${label} is malformed`);
+  }
+  return text;
+}
+
+function boundedMessage(value: string): string {
+  const bytes = Buffer.from(value, "utf8");
+  if (bytes.byteLength <= MAX_ERROR_BYTES) return value.trim();
+  return `${bytes.subarray(0, MAX_ERROR_BYTES).toString("utf8").trim()}…`;
+}
+
+function cliSourcePath(): string {
+  const besideSource = fileURLToPath(new URL("./cli.ts", import.meta.url));
+  if (existsSync(besideSource)) return besideSource;
+  const packagedSource = fileURLToPath(new URL("../src/cli.ts", import.meta.url));
+  if (existsSync(packagedSource)) return packagedSource;
+  throw new Error("the installed Ghostget CLI source is unavailable");
+}
+
+function requireBunRuntime(): void {
+  if (typeof process.versions.bun !== "string") {
+    throw new Error("@hraness/ghostget/client requires Bun to run the installed Ghostget CLI");
+  }
+}
+
+function environmentName(value: string): string {
+  if (value.length < 1 || value.includes("=") || value.includes("\0")) {
+    throw new Error("Ghostget client environment name is malformed");
+  }
+  return value;
+}
+
+function defineEnvironmentValue(
+  environment: Record<string, string>,
+  key: string,
+  value: string,
+): void {
+  Object.defineProperty(environment, key, {
+    value,
+    enumerable: true,
+    configurable: true,
+    writable: true,
+  });
+}
+
+function snapshotChildEnvironment(
+  overrides: unknown,
+): PreparedChildEnvironment {
+  const environment = Object.create(null) as Record<string, string>;
+  for (const [key, value] of Object.entries(process.env)) {
+    if (typeof value === "string") defineEnvironmentValue(environment, key, value);
+  }
+  if (overrides === undefined) return Object.freeze(environment);
+  if (
+    !isRecord(overrides)
+    || nodeTypes.isProxy(overrides)
+    || (
+      Object.getPrototypeOf(overrides) !== Object.prototype
+      && Object.getPrototypeOf(overrides) !== null
+    )
+  ) {
+    throw new Error(
+      "Ghostget client environment must use a plain, non-proxy object",
+    );
+  }
+  const descriptors = Object.getOwnPropertyDescriptors(overrides);
+  const keys = Reflect.ownKeys(descriptors);
+  if (keys.some((key) => typeof key !== "string")) {
+    throw new Error("Ghostget client environment has unsupported symbol fields");
+  }
+  for (const key of (keys as string[]).sort((left, right) =>
+    left.localeCompare(right))) {
+    const descriptor = descriptors[key];
+    if (descriptor === undefined || !("value" in descriptor)) {
+      throw new Error(
+        "Ghostget client environment must contain only data properties",
+      );
+    }
+    if (!descriptor.enumerable) {
+      throw new Error(
+        "Ghostget client environment properties must be enumerable",
+      );
+    }
+    const name = environmentName(key);
+    if (descriptor.value === undefined) {
+      delete environment[name];
+    } else if (
+      typeof descriptor.value !== "string"
+      || descriptor.value.includes("\0")
+    ) {
+      throw new Error("Ghostget client environment value is malformed");
+    } else {
+      defineEnvironmentValue(environment, name, descriptor.value);
+    }
+  }
+  return Object.freeze(environment);
+}
+
+function isBrandedAbortSignal(value: unknown): value is AbortSignal {
+  if (
+    nodeTypes.isProxy(value)
+    || typeof value !== "object"
+    || value === null
+    || abortSignalAbortedGetter === undefined
+  ) return false;
+  if (Object.getPrototypeOf(value) !== AbortSignal.prototype) return false;
+  try {
+    return typeof abortSignalAbortedGetter(value) === "boolean";
+  } catch {
+    return false;
+  }
+}
+
+type ClientOptionsMode = "read" | "revalidation" | "invoke-async" | "invoke-sync";
+
+function snapshotClientOptions(
+  optionsValue: unknown,
+  mode: ClientOptionsMode,
+): PreparedClientOptions {
+  if (
+    !isRecord(optionsValue)
+    || nodeTypes.isProxy(optionsValue)
+    || (
+      Object.getPrototypeOf(optionsValue) !== Object.prototype
+      && Object.getPrototypeOf(optionsValue) !== null
+    )
+  ) throw new Error("Ghostget client options must use a plain, non-proxy object");
+  const descriptors = Object.getOwnPropertyDescriptors(optionsValue);
+  const keys = Reflect.ownKeys(descriptors);
+  if (keys.some((key) => typeof key !== "string")) {
+    throw new Error("Ghostget client options have unsupported symbol fields");
+  }
+  const allowed = new Set(mode === "read"
+    ? ["environment", "freshForMs", "now"]
+    : mode === "revalidation"
+      ? ["environment", "freshForMs", "now", "headed", "signal"]
+      : mode === "invoke-async"
+        ? ["environment", "headed", "signal"]
+        : ["environment", "headed"]);
+  for (const key of keys as string[]) {
+    const descriptor = descriptors[key];
+    if (descriptor === undefined || !allowed.has(key)) {
+      throw new Error("Ghostget client options contain an unsupported field");
+    }
+    if (!("value" in descriptor)) {
+      throw new Error("Ghostget client options must contain only data properties");
+    }
+  }
+  const option = (key: string): unknown => descriptors[key]?.value;
+  const freshForMsValue = option("freshForMs");
+  const nowValue = option("now");
+  const headedValue = option("headed");
+  const signalValue = option("signal");
+  const freshForMs = freshForMsValue === undefined
+    ? undefined
+    : safeInteger(
+        freshForMsValue,
+        "Ghostget client freshness window",
+        0,
+        MAX_FRESH_FOR_MS,
+      );
+  let now: Date | undefined;
+  if (nowValue !== undefined) {
+    if (
+      nodeTypes.isProxy(nowValue)
+      || !(nowValue instanceof Date)
+      || Object.getPrototypeOf(nowValue) !== Date.prototype
+    ) throw new Error("Ghostget client observation time is invalid");
+    let time: number;
+    try {
+      time = Date.prototype.getTime.call(nowValue);
+    } catch {
+      throw new Error("Ghostget client observation time is invalid");
+    }
+    if (!Number.isFinite(time)) {
+      throw new Error("Ghostget client observation time is invalid");
+    }
+    now = new Date(time);
+  }
+  if (headedValue !== undefined && typeof headedValue !== "boolean") {
+    throw new Error("Ghostget client headed option is malformed");
+  }
+  if (
+    signalValue !== undefined
+    && !isBrandedAbortSignal(signalValue)
+  ) throw new Error("Ghostget client abort signal is malformed");
+  return Object.freeze({
+    cwd: process.cwd(),
+    environment: snapshotChildEnvironment(option("environment")),
+    ...(freshForMs === undefined ? {} : { freshForMs }),
+    ...(now === undefined ? {} : { now }),
+    ...(headedValue === undefined ? {} : { headed: headedValue }),
+    ...(signalValue === undefined ? {} : { signal: signalValue }),
+  });
+}
+
+function prepareRequest(requestValue: CapabilityReadRequest): PreparedRequest {
+  const snapshot = snapshotJson(
+    requestValue,
+    "Ghostget client request",
+  );
+  const request = record(snapshot, "Ghostget client request");
+  assertExactKeys(
+    request,
+    ["adapterId", "operationId"],
+    ["authId", "input"],
+    "Ghostget client request",
+  );
+  const adapterId = safeString(
+    request.adapterId,
+    "Ghostget client adapter ID",
+    64,
+  );
+  const operationId = providerOperationName(
+    request.operationId,
+    "Ghostget client operation ID",
+  );
+  const authId = Object.hasOwn(request, "authId")
+    ? safeString(request.authId, "Ghostget client auth ID", 64)
+    : undefined;
+  const rawInput = Object.hasOwn(request, "input") ? request.input : {};
+  if (!isRecord(rawInput)) throw new Error("input must be a JSON object");
+  const input = canonicalJson(rawInput);
+  if (Buffer.byteLength(input, "utf8") > MAX_INPUT_BYTES) {
+    throw new Error("Ghostget client input exceeds its byte bound");
+  }
+  return Object.freeze({
+    adapterId,
+    operationId,
+    ...(authId === undefined ? {} : { authId }),
+    input,
+  });
+}
+
+function preparedCommand(
+  request: PreparedRequest,
+  options: {
+    readonly cacheOnly: boolean;
+    readonly projectionIdentityOnly: boolean;
+    readonly preview?: boolean;
+    readonly headed: boolean;
+  },
+): PreparedCommand {
+  return Object.freeze({
+    arguments: Object.freeze([
+      cliSourcePath(),
+      "invoke",
+      request.adapterId,
+      request.operationId,
+      "--input",
+      "-",
+      ...(request.authId === undefined ? [] : ["--auth", request.authId]),
+      ...(options.cacheOnly ? ["--cache-only"] : []),
+      ...(options.projectionIdentityOnly
+        ? ["--projection-identity-only"]
+        : []),
+      ...(options.preview === true ? ["--preview"] : []),
+      ...(options.headed ? ["--headed"] : []),
+      "--json",
+    ]),
+    input: request.input,
+  });
+}
+
+function preparedCapabilitiesCommand(request: PreparedRequest): PreparedCommand {
+  return Object.freeze({
+    arguments: Object.freeze([
+      cliSourcePath(),
+      "capabilities",
+      request.adapterId,
+      "--json",
+    ]),
+    input: "",
+  });
+}
+
+function parseOutput(text: string, label: string): JsonRecord {
+  if (Buffer.byteLength(text, "utf8") > MAX_OUTPUT_BYTES) {
+    throw new Error(`${label} exceeds its byte bound`);
+  }
+  try {
+    return record(JSON.parse(text) as unknown, label);
+  } catch (error) {
+    if (error instanceof Error && error.message === `${label} must be an object`) throw error;
+    throw new Error(`${label} is malformed`);
+  }
+}
+
+function runCacheCommand(
+  command: PreparedCommand,
+  options: PreparedClientOptions,
+): { readonly code: number; readonly output: JsonRecord } {
+  requireBunRuntime();
+  const result = spawnSync(process.execPath, command.arguments, {
+    cwd: options.cwd,
+    env: options.environment,
+    input: command.input,
+    encoding: "utf8",
+    maxBuffer: MAX_OUTPUT_BYTES,
+  });
+  if (result.error !== undefined) throw result.error;
+  const code = result.status ?? 3;
+  const stdout = String(result.stdout ?? "");
+  const stderr = String(result.stderr ?? "");
+  if (stdout.trim().length === 0) {
+    throw new Error(
+      boundedMessage(stderr) || `Ghostget cache lookup exited ${code}`,
+    );
+  }
+  if (code !== 0 && code !== 3) {
+    throw new Error(
+      boundedMessage(stderr) || `Ghostget cache lookup exited ${code}`,
+    );
+  }
+  return Object.freeze({
+    code,
+    output: parseOutput(stdout, "Ghostget cache response"),
+  });
+}
+
+function runIdentityCommand(
+  command: PreparedCommand,
+  options: PreparedClientOptions,
+  label: string,
+  responseLabel = `${label} response`,
+): JsonRecord {
+  requireBunRuntime();
+  const result = spawnSync(process.execPath, command.arguments, {
+    cwd: options.cwd,
+    env: options.environment,
+    input: command.input,
+    encoding: "utf8",
+    maxBuffer: MAX_OUTPUT_BYTES,
+  });
+  if (result.error !== undefined) throw result.error;
+  const code = result.status ?? 3;
+  const stdout = String(result.stdout ?? "");
+  const stderr = String(result.stderr ?? "");
+  if (stdout.trim().length === 0 || code !== 0) {
+    throw new Error(
+      boundedMessage(stderr)
+        || `${label} exited ${code}`,
+    );
+  }
+  return parseOutput(stdout, responseLabel);
+}
+
+function runProjectionIdentityCommand(
+  command: PreparedCommand,
+  options: PreparedClientOptions,
+): JsonRecord {
+  return runIdentityCommand(
+    command,
+    options,
+    "Ghostget projection identity preflight",
+    "Ghostget projection identity response",
+  );
+}
+
+function observeProjectionIdentity(
+  request: PreparedRequest,
+  options: PreparedClientOptions,
+): ProjectionIdentity {
+  const value = runProjectionIdentityCommand(
+    preparedCommand(request, {
+      cacheOnly: false,
+      projectionIdentityOnly: true,
+      headed: false,
+    }),
+    options,
+  );
+  if (
+    value.ok !== true
+    || value.source !== "projection-identity"
+  ) throw new Error("Ghostget projection identity response is malformed");
+  if (value.status === "ready") {
+    assertExactKeys(
+      value,
+      [
+        "ok",
+        "source",
+        "status",
+        "authIdentity",
+        "authHash",
+        "inputHash",
+        "projection",
+      ],
+      [],
+      "Ghostget projection identity response",
+    );
+    const projection = record(
+      value.projection,
+      "Ghostget projection identity",
+    );
+    assertExactKeys(
+      projection,
+      ["key"],
+      [],
+      "Ghostget projection identity",
+    );
+    return Object.freeze({
+      status: "ready",
+      key: digest(projection.key, "Ghostget projection identity key"),
+      authIdentity: digest(
+        value.authIdentity,
+        "Ghostget projection auth identity",
+      ),
+      authHash: digest(value.authHash, "Ghostget projection auth hash"),
+      inputHash: digest(
+        value.inputHash,
+        "Ghostget projection validated input hash",
+      ),
+    });
+  }
+  if (value.status === "unbound") {
+    assertExactKeys(
+      value,
+      [
+        "ok",
+        "source",
+        "status",
+        "authIdentity",
+        "authHash",
+        "inputHash",
+      ],
+      [],
+      "Ghostget projection identity response",
+    );
+    return Object.freeze({
+      status: "unbound",
+      authIdentity: digest(
+        value.authIdentity,
+        "Ghostget projection auth identity",
+      ),
+      authHash: digest(value.authHash, "Ghostget projection auth hash"),
+      inputHash: digest(
+        value.inputHash,
+        "Ghostget projection validated input hash",
+      ),
+    });
+  }
+  throw new Error("Ghostget projection identity response is malformed");
+}
+
+function projectionIdentitiesMatch(
+  before: ProjectionIdentity,
+  after: ProjectionIdentity,
+): boolean {
+  return before.status === "ready"
+    ? after.status === "ready"
+      && after.key === before.key
+      && after.authIdentity === before.authIdentity
+      && after.authHash === before.authHash
+      && after.inputHash === before.inputHash
+    : after.status === "unbound"
+      && after.authIdentity === before.authIdentity
+      && after.authHash === before.authHash
+      && after.inputHash === before.inputHash;
+}
+
+function parseExecutionPreview(
+  value: JsonRecord,
+  request: PreparedRequest,
+): PreviewExecutionIdentity {
+  const portable = value.transport === "portable-provider-plugin";
+  assertExactKeys(
+    value,
+    [
+      "ok",
+      "status",
+      "requiresConfirmation",
+      "adapter",
+      "operation",
+      "risk",
+      "sideEffect",
+      "input",
+      "auth",
+      "identityBinding",
+      "transport",
+      ...(portable ? ["portablePluginContract"] : []),
+    ],
+    [],
+    "Ghostget execution identity preview",
+  );
+  if (
+    value.ok !== true
+    || value.status !== "preview"
+    || value.requiresConfirmation !== false
+    || value.risk !== "R1"
+  ) throw new Error("Ghostget execution identity preview is malformed");
+  const adapterValue = record(
+    value.adapter,
+    "Ghostget execution identity preview adapter",
+  );
+  const auth = record(value.auth, "Ghostget execution identity preview auth");
+  const binding = record(
+    value.identityBinding,
+    "Ghostget execution identity preview binding",
+  );
+  assertExactKeys(
+    adapterValue,
+    ["id", "version", "hash"],
+    [],
+    "Ghostget execution identity preview adapter",
+  );
+  assertExactKeys(
+    auth,
+    ["id", "kind", "realmFingerprint"],
+    [],
+    "Ghostget execution identity preview auth",
+  );
+  assertExactKeys(
+    binding,
+    ["status", "subject", "accountActor", "requestedActor"],
+    [],
+    "Ghostget execution identity preview binding",
+  );
+  const adapter = Object.freeze({
+    id: safeString(
+      adapterValue.id,
+      "Ghostget execution identity preview adapter ID",
+      64,
+    ),
+    version: safeString(
+      adapterValue.version,
+      "Ghostget execution identity preview adapter version",
+      64,
+    ),
+    hash: digest(
+      adapterValue.hash,
+      "Ghostget execution identity preview adapter hash",
+    ),
+  });
+  const operation = providerOperationName(
+    value.operation,
+    "Ghostget execution identity preview operation",
+  );
+  if (adapter.id !== request.adapterId || operation !== request.operationId) {
+    throw new Error("Ghostget execution identity preview route is malformed");
+  }
+  const authKind = safeString(
+    auth.kind,
+    "Ghostget execution identity preview auth kind",
+    64,
+  );
+  if (
+    safeString(auth.id, "Ghostget execution identity preview auth ID", 64)
+      !== expectedRequestAuthId(request, authKind)
+  ) throw new Error("Ghostget execution identity preview auth is malformed");
+  const realmFingerprint = safeString(
+    auth.realmFingerprint,
+    "Ghostget execution identity preview auth fingerprint",
+    16,
+  );
+  if (!/^[a-f0-9]{16}$/u.test(realmFingerprint)) {
+    throw new Error("Ghostget execution identity preview auth fingerprint is malformed");
+  }
+  if (authKind === PUBLIC_WEB_SESSION_AUTHORITY_KIND) {
+    const authority = publicWebSessionAuthority(request);
+    if (
+      value.transport !== "web-session-api"
+      || realmFingerprint
+        !== sha256(canonicalJson(authority)).slice(0, 16)
+      || binding.status !== "public"
+      || binding.subject !== authority.subject
+      || binding.accountActor !== null
+      || binding.requestedActor !== null
+    ) {
+      throw new Error(
+        "Ghostget execution identity preview public authority is malformed",
+      );
+    }
+  }
+  safeString(
+    value.sideEffect,
+    "Ghostget execution identity preview side effect",
+    64,
+  );
+  const transport = value.transport;
+  if (transport === "portable-provider-plugin") {
+    const portablePluginContract = parsePortableOperationIdentity(
+      value.portablePluginContract,
+    );
+    if (
+      portablePluginContract.adapterId !== adapter.id
+      || portablePluginContract.operation !== operation
+    ) throw new Error("Ghostget execution identity preview route is malformed");
+    return Object.freeze({
+      adapter,
+      operation,
+      transport,
+      portablePluginContract,
+    });
+  }
+  if (
+    transport !== "browser"
+    && transport !== "provider-api"
+    && transport !== "web-session-api"
+    && transport !== "reviewed-template-api"
+    && transport !== "local-cli"
+  ) throw new Error("Ghostget execution identity preview transport is malformed");
+  return Object.freeze({ adapter, operation, transport });
+}
+
+function parseCatalogExecutionIdentity(
+  value: JsonRecord,
+  request: PreparedRequest,
+  preview: Exclude<
+    PreviewExecutionIdentity,
+    { readonly transport: "browser" | "portable-provider-plugin" }
+  >,
+): ExecutionIdentity {
+  assertExactKeys(
+    value,
+    ["ok", "adapters"],
+    [],
+    "Ghostget execution identity catalog",
+  );
+  if (value.ok !== true || !isUnknownArray(value.adapters)) {
+    throw new Error("Ghostget execution identity catalog is malformed");
+  }
+  if (value.adapters.length !== 1) {
+    throw new Error("Ghostget execution identity catalog is ambiguous");
+  }
+  const adapterValue = record(
+    value.adapters[0],
+    "Ghostget execution identity catalog adapter",
+  );
+  assertExactKeys(
+    adapterValue,
+    [
+      "id",
+      "version",
+      "displayName",
+      "surfaceId",
+      "origins",
+      "manifestHash",
+      "operations",
+    ],
+    [],
+    "Ghostget execution identity catalog adapter",
+  );
+  const adapter = Object.freeze({
+    id: safeString(
+      adapterValue.id,
+      "Ghostget execution identity catalog adapter ID",
+      64,
+    ),
+    version: safeString(
+      adapterValue.version,
+      "Ghostget execution identity catalog adapter version",
+      64,
+    ),
+    hash: digest(
+      adapterValue.manifestHash,
+      "Ghostget execution identity catalog adapter hash",
+    ),
+  });
+  if (
+    adapter.id !== request.adapterId
+    || adapter.id !== preview.adapter.id
+    || adapter.version !== preview.adapter.version
+    || adapter.hash !== preview.adapter.hash
+    || !isUnknownArray(adapterValue.operations)
+  ) throw new Error("Ghostget execution identity preflights disagreed");
+  const operations = adapterValue.operations.filter(
+    (candidate): candidate is JsonRecord => (
+      isRecord(candidate) && candidate.id === request.operationId
+    ),
+  );
+  if (operations.length !== 1) {
+    throw new Error("Ghostget execution identity catalog operation is ambiguous");
+  }
+  const operation = operations[0]!;
+  const commonKeys = [
+    "id",
+    "description",
+    "risk",
+    "sideEffect",
+    "idempotency",
+    "dedupeWindowMs",
+    "transport",
+    "input",
+  ] as const;
+  if (
+    operation.risk !== "R1"
+    || operation.transport !== preview.transport
+  ) throw new Error("Ghostget execution identity preflights disagreed");
+  const common = Object.freeze({
+    adapter,
+    operation: preview.operation,
+  });
+  if (preview.transport === "provider-api") {
+    assertExactKeys(
+      operation,
+      [
+        ...commonKeys,
+        "provider",
+        "providerAction",
+        "providerContractVersion",
+        "providerContractHash",
+        "requiredScopeSets",
+        "coverage",
+        "implementation",
+      ],
+      [],
+      "Ghostget execution identity provider capability",
+    );
+    const catalogSurface = providerSurfaceId(
+      adapterValue.surfaceId,
+      "Ghostget execution identity catalog surface",
+    );
+    const provider = providerSurfaceId(
+      operation.provider,
+      "Ghostget execution identity provider surface",
+    );
+    const providerAction = providerOperationName(
+      operation.providerAction,
+      "Ghostget execution identity provider action",
+    );
+    safeInteger(
+      operation.providerContractVersion,
+      "Ghostget execution identity provider contract version",
+      1,
+      1_000_000,
+    );
+    if (
+      provider !== catalogSurface
+      || providerAction !== preview.operation
+    ) throw new Error("Ghostget execution identity provider route is malformed");
+    return Object.freeze({
+      ...common,
+      schemaVersion: 3 as const,
+      transport: "provider-api" as const,
+      providerContractHash: digest(
+        operation.providerContractHash,
+        "Ghostget execution identity provider contract hash",
+      ),
+    });
+  }
+  if (preview.transport === "web-session-api") {
+    assertExactKeys(
+      operation,
+      [
+        ...commonKeys,
+        "site",
+        "webSessionAction",
+        "webSessionContractVersion",
+        "webSessionContractHash",
+        "state",
+        "implementation",
+      ],
+      [],
+      "Ghostget execution identity web-session capability",
+    );
+    const catalogSurface = providerSurfaceId(
+      adapterValue.surfaceId,
+      "Ghostget execution identity catalog surface",
+    );
+    const site = providerSurfaceId(
+      operation.site,
+      "Ghostget execution identity web-session surface",
+    );
+    const webSessionAction = providerOperationName(
+      operation.webSessionAction,
+      "Ghostget execution identity web-session action",
+    );
+    safeInteger(
+      operation.webSessionContractVersion,
+      "Ghostget execution identity web-session contract version",
+      1,
+      1_000_000,
+    );
+    if (
+      site !== catalogSurface
+      || webSessionAction !== preview.operation
+    ) throw new Error("Ghostget execution identity web-session route is malformed");
+    return Object.freeze({
+      ...common,
+      schemaVersion: 4 as const,
+      transport: "web-session-api" as const,
+      webSessionContractHash: digest(
+        operation.webSessionContractHash,
+        "Ghostget execution identity web-session contract hash",
+      ),
+    });
+  }
+  if (preview.transport === "local-cli") {
+    assertExactKeys(
+      operation,
+      [
+        ...commonKeys,
+        "surface",
+        "localCliAction",
+        "localCliContractVersion",
+        "localCliContractHash",
+        "localCliTool",
+        "state",
+        "implementation",
+      ],
+      [],
+      "Ghostget execution identity local CLI capability",
+    );
+    const catalogSurface = providerSurfaceId(
+      adapterValue.surfaceId,
+      "Ghostget execution identity catalog surface",
+    );
+    const localCliContract = parseLocalCliContractIdentity({
+      surface: operation.surface,
+      action: operation.localCliAction,
+      version: operation.localCliContractVersion,
+      hash: operation.localCliContractHash,
+      tool: operation.localCliTool,
+    });
+    if (
+      localCliContract.surface !== catalogSurface
+      || localCliContract.action !== preview.operation
+    ) {
+      throw new Error("Ghostget execution identity local CLI route is malformed");
+    }
+    return Object.freeze({
+      ...common,
+      schemaVersion: 7 as const,
+      transport: "local-cli" as const,
+      localCliContract,
+    });
+  }
+  assertExactKeys(
+    operation,
+    [
+      ...commonKeys,
+      "state",
+      "reviewedTemplateContractVersion",
+      "reviewedTemplateContractHash",
+    ],
+    ["instructions", "reviewedAt", "evidenceSha256", "origin"],
+    "Ghostget execution identity reviewed-template capability",
+  );
+  safeInteger(
+    operation.reviewedTemplateContractVersion,
+    "Ghostget execution identity reviewed-template contract version",
+    1,
+    Number.MAX_SAFE_INTEGER,
+  );
+  return Object.freeze({
+    ...common,
+    schemaVersion: 5 as const,
+    transport: "reviewed-template-api" as const,
+    reviewedTemplateContractHash: digest(
+      operation.reviewedTemplateContractHash,
+      "Ghostget execution identity reviewed-template contract hash",
+    ),
+  });
+}
+
+function observeExecutionIdentity(
+  request: PreparedRequest,
+  options: PreparedClientOptions,
+): ExecutionIdentity {
+  // Preview owns the portable wrapper identity. The targeted catalog view
+  // supplies built-in contract hashes that preview intentionally omits. Keep
+  // this receipt fence separate from the opaque projection-key fence because
+  // a cache publication error carries no projection key to compare.
+  const preview = parseExecutionPreview(
+    runIdentityCommand(
+      preparedCommand(request, {
+        cacheOnly: false,
+        projectionIdentityOnly: false,
+        preview: true,
+        headed: false,
+      }),
+      options,
+      "Ghostget execution identity preview",
+    ),
+    request,
+  );
+  if (preview.transport === "portable-provider-plugin") {
+    return Object.freeze({
+      adapter: preview.adapter,
+      operation: preview.operation,
+      schemaVersion: 6 as const,
+      transport: preview.transport,
+      portablePluginContract: preview.portablePluginContract,
+    });
+  }
+  if (preview.transport === "browser") {
+    return Object.freeze({
+      adapter: preview.adapter,
+      operation: preview.operation,
+      schemaVersion: 2 as const,
+      transport: preview.transport,
+    });
+  }
+  return parseCatalogExecutionIdentity(
+    runIdentityCommand(
+      preparedCapabilitiesCommand(request),
+      options,
+      "Ghostget execution identity catalog preflight",
+    ),
+    request,
+    preview,
+  );
+}
+
+function receiptExecutionIdentity(
+  receipt: GhostgetClientRunReceipt,
+): ExecutionIdentity {
+  const common = Object.freeze({
+    adapter: receipt.adapter,
+    operation: receipt.operation,
+  });
+  if (receipt.schemaVersion === 2) {
+    return Object.freeze({
+      ...common,
+      schemaVersion: receipt.schemaVersion,
+      transport: receipt.transport,
+    });
+  }
+  if (receipt.schemaVersion === 3) {
+    return Object.freeze({
+      ...common,
+      schemaVersion: receipt.schemaVersion,
+      transport: receipt.transport,
+      providerContractHash: receipt.providerContractHash,
+    });
+  }
+  if (receipt.schemaVersion === 4) {
+    return Object.freeze({
+      ...common,
+      schemaVersion: receipt.schemaVersion,
+      transport: receipt.transport,
+      webSessionContractHash: receipt.webSessionContractHash,
+    });
+  }
+  if (receipt.schemaVersion === 5) {
+    return Object.freeze({
+      ...common,
+      schemaVersion: receipt.schemaVersion,
+      transport: receipt.transport,
+      reviewedTemplateContractHash: receipt.reviewedTemplateContractHash,
+    });
+  }
+  if (receipt.schemaVersion === 6) return Object.freeze({
+    ...common,
+    schemaVersion: receipt.schemaVersion,
+    transport: receipt.transport,
+    portablePluginContract: receipt.portablePluginContract,
+  });
+  return Object.freeze({
+    ...common,
+    schemaVersion: receipt.schemaVersion,
+    transport: receipt.transport,
+    localCliContract: receipt.localCliContract,
+  });
+}
+
+function executionIdentitiesMatch(
+  left: ExecutionIdentity,
+  right: ExecutionIdentity,
+): boolean {
+  return canonicalJson(left) === canonicalJson(right);
+}
+
+function runLiveCommand(
+  command: PreparedCommand,
+  options: PreparedClientOptions,
+): Promise<JsonRecord> {
+  requireBunRuntime();
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, command.arguments, {
+      cwd: options.cwd,
+      env: options.environment,
+      stdio: ["pipe", "pipe", "pipe"],
+      ...(options.signal === undefined ? {} : { signal: options.signal }),
+    });
+    const stdout: Buffer[] = [];
+    const stderr: Buffer[] = [];
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    let settled = false;
+    const fail = (error: unknown): void => {
+      if (settled) return;
+      settled = true;
+      reject(error instanceof Error ? error : new Error(String(error)));
+    };
+    child.stdout.on("data", (chunkValue: Buffer | string) => {
+      const chunk = Buffer.isBuffer(chunkValue) ? chunkValue : Buffer.from(chunkValue);
+      stdoutBytes += chunk.byteLength;
+      if (stdoutBytes > MAX_OUTPUT_BYTES) {
+        child.kill();
+        fail(new Error("Ghostget live response exceeds its byte bound"));
+        return;
+      }
+      stdout.push(chunk);
+    });
+    child.stderr.on("data", (chunkValue: Buffer | string) => {
+      const chunk = Buffer.isBuffer(chunkValue) ? chunkValue : Buffer.from(chunkValue);
+      stderrBytes += chunk.byteLength;
+      if (stderrBytes <= MAX_ERROR_BYTES) stderr.push(chunk);
+    });
+    child.on("error", fail);
+    child.on("close", (code, signal) => {
+      if (settled) return;
+      const output = Buffer.concat(stdout).toString("utf8");
+      const error = boundedMessage(Buffer.concat(stderr).toString("utf8"));
+      if (output.trim().length === 0) {
+        fail(new Error(error || `Ghostget live invocation exited ${code ?? signal ?? "unknown"}`));
+        return;
+      }
+      if (code !== 0 && code !== 3 && code !== 5) {
+        fail(new Error(error || `Ghostget live invocation exited ${code ?? signal ?? "unknown"}`));
+        return;
+      }
+      let parsed: JsonRecord;
+      try {
+        parsed = parseOutput(output, "Ghostget live response");
+      } catch (parseError) {
+        fail(parseError);
+        return;
+      }
+      settled = true;
+      resolve(parsed);
+    });
+    child.stdin.on("error", fail);
+    child.stdin.end(command.input);
+  });
+}
+
+function runLiveCommandSync(
+  command: PreparedCommand,
+  options: PreparedClientOptions,
+): JsonRecord {
+  requireBunRuntime();
+  const result = spawnSync(process.execPath, command.arguments, {
+    cwd: options.cwd,
+    env: options.environment,
+    input: command.input,
+    encoding: "utf8",
+    maxBuffer: MAX_OUTPUT_BYTES,
+  });
+  if (result.error !== undefined) throw result.error;
+  const code = result.status ?? 3;
+  const stdout = String(result.stdout ?? "");
+  const stderr = String(result.stderr ?? "");
+  if (stdout.trim().length === 0) {
+    throw new Error(
+      boundedMessage(stderr)
+        || `Ghostget live invocation exited ${String(code)}`,
+    );
+  }
+  if (code !== 0 && code !== 3 && code !== 5) {
+    throw new Error(
+      boundedMessage(stderr)
+        || `Ghostget live invocation exited ${String(code)}`,
+    );
+  }
+  return parseOutput(stdout, "Ghostget live response");
+}
+
+function parseFreshness(
+  value: unknown,
+  options: PreparedClientOptions,
+  ageMs: number,
+): ReadProjectionCacheHit["freshness"] {
+  const freshnessValue = record(value, "Ghostget cache freshness");
+  assertExactKeys(
+    freshnessValue,
+    ["state", "freshForMs"],
+    [],
+    "Ghostget cache freshness",
+  );
+  const childState = freshnessValue.state;
+  if (childState !== "fresh" && childState !== "stale" && childState !== "unclassified") {
+    throw new Error("Ghostget cache freshness state is malformed");
+  }
+  if (options.freshForMs === undefined) {
+    if (freshnessValue.freshForMs !== null) {
+      throw new Error("Ghostget cache freshness window is malformed");
+    }
+    return Object.freeze({ state: childState, freshForMs: null });
+  }
+  const freshForMs = safeInteger(
+    options.freshForMs,
+    "Ghostget client freshness window",
+    0,
+    MAX_FRESH_FOR_MS,
+  );
+  return Object.freeze({
+    state: ageMs <= freshForMs ? "fresh" : "stale",
+    freshForMs,
+  });
+}
+
+function validateReadOptions(options: PreparedClientOptions): Date {
+  const now = options.now ?? new Date();
+  if (!(now instanceof Date) || !Number.isFinite(now.getTime())) {
+    throw new Error("Ghostget client observation time is invalid");
+  }
+  if (options.freshForMs !== undefined) {
+    safeInteger(
+      options.freshForMs,
+      "Ghostget client freshness window",
+      0,
+      MAX_FRESH_FOR_MS,
+    );
+  }
+  return now;
+}
+
+function parseCacheResult(
+  value: JsonRecord,
+  options: PreparedClientOptions,
+  now: Date,
+): ReadProjectionCacheResult {
+  if (value.source !== "cache") throw new Error("Ghostget cache response has the wrong source");
+  const projection = record(value.projection, "Ghostget cache projection");
+  if (value.status === "cache-miss") {
+    assertExactKeys(
+      value,
+      ["ok", "source", "status", "projection"],
+      [],
+      "Ghostget cache miss",
+    );
+    assertExactKeys(
+      projection,
+      ["key"],
+      [],
+      "Ghostget cache miss projection",
+    );
+    if (value.ok !== false) throw new Error("Ghostget cache miss has the wrong success state");
+    const key = digest(projection.key, "Ghostget cache key");
+    return Object.freeze({ status: "miss", key });
+  }
+  if (value.status !== "cached" || value.ok !== true || !("output" in value)) {
+    throw new Error("Ghostget cache response has an unsupported outcome");
+  }
+  assertExactKeys(
+    value,
+    ["ok", "source", "status", "projection", "output"],
+    [],
+    "Ghostget cache response",
+  );
+  assertExactKeys(
+    projection,
+    [
+      "key",
+      "dataRevision",
+      "createdAt",
+      "dataChangedAt",
+      "validatedAt",
+      "runId",
+      "ageMs",
+      "freshness",
+    ],
+    [],
+    "Ghostget cache projection",
+  );
+  const key = digest(projection.key, "Ghostget cache key");
+  const validatedAt = timestamp(projection.validatedAt, "Ghostget cache validation time");
+  const childAgeMs = safeInteger(projection.ageMs, "Ghostget cache age", 0, Number.MAX_SAFE_INTEGER);
+  const ageMs = options.now === undefined
+    ? childAgeMs
+    : Math.max(0, now.getTime() - new Date(validatedAt).getTime());
+  return Object.freeze({
+    status: "hit" as const,
+    source: "cache" as const,
+    key,
+    output: value.output,
+    dataRevision: digest(projection.dataRevision, "Ghostget cache data revision"),
+    createdAt: timestamp(projection.createdAt, "Ghostget cache creation time"),
+    dataChangedAt: timestamp(projection.dataChangedAt, "Ghostget cache data-change time"),
+    validatedAt,
+    runId: safeString(projection.runId, "Ghostget cache run ID", 64),
+    ageMs,
+    freshness: parseFreshness(projection.freshness, options, ageMs),
+  });
+}
+
+function parsePublication(value: unknown): ReadProjectionPublication {
+  const publication = record(value, "Ghostget cache publication");
+  assertExactKeys(
+    publication,
+    ["key", "dataRevision", "validatedAt", "dataChangedAt", "disposition"],
+    ["currentDataRevision"],
+    "Ghostget cache publication",
+  );
+  const disposition = publication.disposition;
+  if (
+    disposition !== "created"
+    && disposition !== "changed"
+    && disposition !== "unchanged"
+    && disposition !== "superseded"
+  ) throw new Error("Ghostget cache publication disposition is malformed");
+  if (
+    (disposition === "superseded")
+    !== Object.hasOwn(publication, "currentDataRevision")
+  ) throw new Error("Ghostget cache publication current revision is malformed");
+  return Object.freeze({
+    key: digest(publication.key, "Ghostget cache publication key"),
+    dataRevision: digest(publication.dataRevision, "Ghostget cache publication data revision"),
+    validatedAt: timestamp(publication.validatedAt, "Ghostget cache publication validation time"),
+    dataChangedAt: timestamp(publication.dataChangedAt, "Ghostget cache publication data-change time"),
+    disposition,
+    ...(publication.currentDataRevision === undefined
+      ? {}
+      : {
+          currentDataRevision: digest(
+            publication.currentDataRevision,
+            "Ghostget current cache data revision",
+          ),
+        }),
+  });
+}
+
+function parseCacheOutcome(value: unknown): ReadProjectionCacheOutcome {
+  const outcome = record(value, "Ghostget cache outcome");
+  if (outcome.status === "stored") {
+    assertExactKeys(
+      outcome,
+      ["status", "publication"],
+      [],
+      "Ghostget cache outcome",
+    );
+    return Object.freeze({ status: "stored", publication: parsePublication(outcome.publication) });
+  }
+  if (outcome.status === "retained" && outcome.reason === "live-read-failed") {
+    assertExactKeys(outcome, ["status", "reason"], [], "Ghostget cache outcome");
+    return Object.freeze({ status: "retained", reason: "live-read-failed" });
+  }
+  if (outcome.status === "miss" && outcome.reason === "no-cached-snapshot") {
+    assertExactKeys(outcome, ["status", "reason"], [], "Ghostget cache outcome");
+    return Object.freeze({ status: "miss", reason: "no-cached-snapshot" });
+  }
+  if (
+    outcome.status === "skipped"
+    && outcome.reason === "auth-subject-unbound"
+  ) {
+    assertExactKeys(outcome, ["status", "reason"], [], "Ghostget cache outcome");
+    return Object.freeze({ status: "skipped", reason: outcome.reason });
+  }
+  if (outcome.status === "error") {
+    assertExactKeys(outcome, ["status", "message"], [], "Ghostget cache outcome");
+    return Object.freeze({ status: "error", message: safeString(outcome.message, "Ghostget cache error", MAX_ERROR_BYTES) });
+  }
+  throw new Error("Ghostget cache outcome is malformed");
+}
+
+function parseReceiptStatus(
+  value: unknown,
+): GhostgetClientRunReceipt["status"] {
+  if (value !== "succeeded" && value !== "failed") {
+    throw new Error("Ghostget live receipt status is malformed");
+  }
+  return value;
+}
+
+function parsePortableOperationIdentity(
+  value: unknown,
+): GhostgetClientPortableOperationIdentity {
+  return parsePortableOperationIdentityV1(value);
+}
+
+function parseLocalCliToolIdentity(
+  value: unknown,
+): GhostgetClientLocalCliToolIdentity {
+  const strictRecord = (candidate: unknown, label: string): JsonRecord => {
+    if (
+      typeof candidate !== "object"
+      || candidate === null
+      || Array.isArray(candidate)
+      || nodeTypes.isProxy(candidate)
+      || (
+        Object.getPrototypeOf(candidate) !== Object.prototype
+        && Object.getPrototypeOf(candidate) !== null
+      )
+    ) throw new Error(`${label} is malformed`);
+    const descriptors = Object.getOwnPropertyDescriptors(candidate);
+    if (Reflect.ownKeys(descriptors).some((key) => typeof key !== "string")) {
+      throw new Error(`${label} is malformed`);
+    }
+    const result: JsonRecord = {};
+    for (const [key, descriptor] of Object.entries(descriptors)) {
+      if (!descriptor.enumerable || !("value" in descriptor)) {
+        throw new Error(`${label} is malformed`);
+      }
+      result[key] = descriptor.value;
+    }
+    return result;
+  };
+  const strictArray = (candidate: unknown, label: string): readonly unknown[] => {
+    if (
+      !Array.isArray(candidate)
+      || nodeTypes.isProxy(candidate)
+      || Object.getPrototypeOf(candidate) !== Array.prototype
+      || candidate.length > 16
+    ) throw new Error(`${label} is malformed`);
+    const descriptors = Object.getOwnPropertyDescriptors(candidate);
+    if (
+      Reflect.ownKeys(descriptors).some((key) => typeof key !== "string")
+      || Object.keys(descriptors).length !== candidate.length + 1
+    ) throw new Error(`${label} is malformed`);
+    return Object.freeze(Array.from({ length: candidate.length }, (_unused, index) => {
+      const descriptor = descriptors[String(index)];
+      if (descriptor === undefined || !descriptor.enumerable || !("value" in descriptor)) {
+        throw new Error(`${label} is malformed`);
+      }
+      return descriptor.value;
+    }));
+  };
+  const exactHttpsUrl = (candidate: unknown, label: string): string => {
+    const source = safeString(candidate, label, 2_000);
+    let parsed: URL;
+    try {
+      parsed = new URL(source);
+    } catch {
+      throw new Error(`${label} is malformed`);
+    }
+    if (
+      parsed.protocol !== "https:"
+      || parsed.username !== ""
+      || parsed.password !== ""
+      || parsed.hash !== ""
+      || parsed.search !== ""
+      || parsed.href !== source
+    ) throw new Error(`${label} is malformed`);
+    return source;
+  };
+  const wellFormedVisible = (candidate: string): boolean => {
+    for (let index = 0; index < candidate.length; index += 1) {
+      const code = candidate.charCodeAt(index);
+      if (code <= 0x1f || (code >= 0x7f && code <= 0x9f)) return false;
+      if (code >= 0xd800 && code <= 0xdbff) {
+        if (index + 1 >= candidate.length) return false;
+        const next = candidate.charCodeAt(index + 1);
+        if (next < 0xdc00 || next > 0xdfff) return false;
+        index += 1;
+      } else if (code >= 0xdc00 && code <= 0xdfff) {
+        return false;
+      }
+    }
+    return true;
+  };
+  const token = (candidate: unknown, label: string): string => {
+    const parsed = safeString(candidate, label, 64);
+    if (!/^[a-z0-9](?:[a-z0-9._+-]{0,62}[a-z0-9])?$/u.test(parsed)) {
+      throw new Error(`${label} is malformed`);
+    }
+    return parsed;
+  };
+  const tool = strictRecord(value, "Ghostget local CLI tool identity");
+  assertExactKeys(
+    tool,
+    [
+      "schemaVersion",
+      "id",
+      "implementation",
+      "versionScheme",
+      "version",
+      "artifacts",
+    ],
+    [
+      "sourceUrl",
+      "releaseCommit",
+      "releaseManifestSha256",
+      "releaseManifestUrl",
+    ],
+    "Ghostget local CLI tool identity",
+  );
+  const artifactValues = strictArray(
+    tool.artifacts,
+    "Ghostget local CLI tool artifact table",
+  );
+  if (tool.schemaVersion !== 1) {
+    throw new Error("Ghostget local CLI tool identity is malformed");
+  }
+  if (artifactValues.length < 1) {
+    throw new Error("Ghostget local CLI tool artifact table is malformed");
+  }
+  const artifacts = artifactValues.map((artifactValue, index) => {
+    const artifact = strictRecord(
+      artifactValue,
+      `Ghostget local CLI tool artifact ${index}`,
+    );
+    assertExactKeys(
+      artifact,
+      ["platform", "arch", "executableSha256"],
+      ["archiveSha256", "downloadUrl"],
+      `Ghostget local CLI tool artifact ${index}`,
+    );
+    const archiveSha256 = artifact.archiveSha256 === undefined
+      ? undefined
+      : digest(
+          artifact.archiveSha256,
+          `Ghostget local CLI tool artifact ${index} archive hash`,
+        );
+    const downloadUrl = artifact.downloadUrl === undefined
+      ? undefined
+      : exactHttpsUrl(
+          artifact.downloadUrl,
+          `Ghostget local CLI tool artifact ${index} download URL`,
+        );
+    if ((archiveSha256 === undefined) !== (downloadUrl === undefined)) {
+      throw new Error("Ghostget local CLI tool artifact archive provenance is malformed");
+    }
+    return Object.freeze({
+      platform: token(
+        artifact.platform,
+        `Ghostget local CLI tool artifact ${index} platform`,
+      ),
+      arch: token(
+        artifact.arch,
+        `Ghostget local CLI tool artifact ${index} architecture`,
+      ),
+      executableSha256: digest(
+        artifact.executableSha256,
+        `Ghostget local CLI tool artifact ${index} executable hash`,
+      ),
+      ...(archiveSha256 === undefined ? {} : { archiveSha256 }),
+      ...(downloadUrl === undefined ? {} : { downloadUrl }),
+    });
+  });
+  const coordinates = artifacts.map((artifact) =>
+    `${artifact.platform}\0${artifact.arch}`);
+  if (
+    new Set(coordinates).size !== coordinates.length
+    || coordinates.some((coordinate, index) =>
+      index > 0 && coordinates[index - 1]! >= coordinate)
+  ) throw new Error("Ghostget local CLI tool artifact table is not canonical");
+  const sourceUrl = tool.sourceUrl === undefined
+    ? undefined
+    : exactHttpsUrl(tool.sourceUrl, "Ghostget local CLI tool source URL");
+  const releaseManifestSha256 = tool.releaseManifestSha256 === undefined
+    ? undefined
+    : digest(
+        tool.releaseManifestSha256,
+        "Ghostget local CLI tool release manifest hash",
+      );
+  const releaseManifestUrl = tool.releaseManifestUrl === undefined
+    ? undefined
+    : exactHttpsUrl(
+        tool.releaseManifestUrl,
+        "Ghostget local CLI tool release manifest URL",
+      );
+  if (
+    (releaseManifestSha256 === undefined)
+      !== (releaseManifestUrl === undefined)
+  ) throw new Error("Ghostget local CLI tool release manifest provenance is malformed");
+  if (tool.versionScheme !== "semver" && tool.versionScheme !== "opaque") {
+    throw new Error("Ghostget local CLI tool version scheme is malformed");
+  }
+  if (
+    typeof tool.version !== "string"
+    || tool.version.length < 1
+    || tool.version.length > 128
+  ) throw new Error("Ghostget local CLI tool version is malformed");
+  const version = tool.version;
+  if (
+    !wellFormedVisible(version)
+    || (
+      tool.versionScheme === "semver"
+      && !/^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?:(?:0|[1-9]\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/u.test(version)
+    )
+  ) {
+    throw new Error("Ghostget local CLI tool version is malformed");
+  }
+  const hasReleaseCommit = tool.releaseCommit !== undefined;
+  const releaseCommit = hasReleaseCommit
+    ? safeString(
+        tool.releaseCommit,
+        "Ghostget local CLI tool release commit",
+        40,
+      )
+    : undefined;
+  if (
+    releaseCommit !== undefined
+    && !/^[a-f0-9]{40}$/u.test(releaseCommit)
+  ) throw new Error("Ghostget local CLI tool release commit is malformed");
+  const implementation = safeString(
+    tool.implementation,
+    "Ghostget local CLI tool implementation",
+    256,
+  );
+  if (!/^[A-Za-z0-9](?:[A-Za-z0-9._/+:-]{0,254}[A-Za-z0-9])?$/u.test(implementation)) {
+    throw new Error("Ghostget local CLI tool implementation is malformed");
+  }
+  return Object.freeze({
+    schemaVersion: 1,
+    id: token(tool.id, "Ghostget local CLI tool ID"),
+    implementation,
+    versionScheme: tool.versionScheme,
+    version,
+    ...(releaseCommit === undefined ? {} : { releaseCommit }),
+    ...(releaseManifestSha256 === undefined
+      ? {}
+      : { releaseManifestSha256, releaseManifestUrl: releaseManifestUrl! }),
+    ...(sourceUrl === undefined ? {} : { sourceUrl }),
+    artifacts: Object.freeze(artifacts),
+  });
+}
+
+function parseLocalCliContractIdentity(
+  value: unknown,
+): GhostgetClientLocalCliContractIdentity {
+  const identity = record(value, "Ghostget local CLI contract identity");
+  assertExactKeys(
+    identity,
+    ["surface", "action", "version", "hash", "tool"],
+    [],
+    "Ghostget local CLI contract identity",
+  );
+  const surface = providerSurfaceId(
+    identity.surface,
+    "Ghostget local CLI surface",
+  );
+  const action = providerOperationName(
+    identity.action,
+    "Ghostget local CLI action",
+  );
+  return Object.freeze({
+    surface,
+    action,
+    version: safeInteger(
+      identity.version,
+      "Ghostget local CLI contract version",
+      1,
+      1_000_000,
+    ),
+    hash: digest(identity.hash, "Ghostget local CLI contract hash"),
+    tool: parseLocalCliToolIdentity(identity.tool),
+  });
+}
+
+function parseLiveReceipt(
+  value: unknown,
+  request: PreparedRequest,
+  expectedInputHash: string,
+): GhostgetClientRunReceipt {
+  const receipt = record(value, "Ghostget live receipt");
+  const commonKeys = [
+    "schemaVersion",
+    "runId",
+    "planDigest",
+    "adapter",
+    "operation",
+    "risk",
+    "inputHash",
+    "auth",
+    "transport",
+    "status",
+    "dispatchStarted",
+    "dispatch",
+    "startedAt",
+    "finishedAt",
+    "finalOrigin",
+    "error",
+  ] as const;
+  if (receipt.schemaVersion === 2 && receipt.transport === "browser") {
+    assertExactKeys(receipt, commonKeys, [], "Ghostget live receipt");
+  } else if (
+    receipt.schemaVersion === 3
+    && receipt.transport === "provider-api"
+  ) {
+    assertExactKeys(
+      receipt,
+      [...commonKeys, "providerContractHash"],
+      [],
+      "Ghostget live receipt",
+    );
+  } else if (
+    receipt.schemaVersion === 4
+    && receipt.transport === "web-session-api"
+  ) {
+    assertExactKeys(
+      receipt,
+      [...commonKeys, "webSessionContractHash"],
+      [],
+      "Ghostget live receipt",
+    );
+  } else if (
+    receipt.schemaVersion === 5
+    && receipt.transport === "reviewed-template-api"
+  ) {
+    assertExactKeys(
+      receipt,
+      [...commonKeys, "reviewedTemplateContractHash"],
+      [],
+      "Ghostget live receipt",
+    );
+  } else if (
+    receipt.schemaVersion === 6
+    && receipt.transport === "portable-provider-plugin"
+  ) {
+    assertExactKeys(
+      receipt,
+      [...commonKeys, "portablePluginContract"],
+      [],
+      "Ghostget live receipt",
+    );
+  } else if (
+    receipt.schemaVersion === 7
+    && receipt.transport === "local-cli"
+  ) {
+    assertExactKeys(
+      receipt,
+      [...commonKeys, "localCliContract"],
+      [],
+      "Ghostget live receipt",
+    );
+  } else {
+    throw new Error("Ghostget live receipt schema and transport are malformed");
+  }
+  const adapter = record(receipt.adapter, "Ghostget live receipt adapter");
+  const auth = record(receipt.auth, "Ghostget live receipt auth");
+  const dispatch = record(receipt.dispatch, "Ghostget live receipt dispatch");
+  assertExactKeys(
+    adapter,
+    ["id", "version", "hash"],
+    [],
+    "Ghostget live receipt adapter",
+  );
+  assertExactKeys(
+    auth,
+    ["id", "hash", "kind"],
+    [],
+    "Ghostget live receipt auth",
+  );
+  assertExactKeys(
+    dispatch,
+    ["planned", "started", "verified"],
+    [],
+    "Ghostget live receipt dispatch",
+  );
+  if (receipt.risk !== "R1") {
+    throw new Error("Ghostget live receipt risk is malformed");
+  }
+  const authKind = auth.kind;
+  if (
+    authKind !== "browser-profile"
+    && authKind !== "cookie-source"
+    && authKind !== "cookies-file"
+    && authKind !== "linked-device-store"
+    && authKind !== "oauth-token-file"
+    && authKind !== PUBLIC_WEB_SESSION_AUTHORITY_KIND
+  ) throw new Error("Ghostget live receipt auth kind is malformed");
+  if (receipt.dispatchStarted !== false) {
+    throw new Error("Ghostget live receipt dispatch state is malformed");
+  }
+  const planned = safeInteger(
+    dispatch.planned,
+    "Ghostget live receipt planned dispatch count",
+    0,
+    Number.MAX_SAFE_INTEGER,
+  );
+  const started = safeInteger(
+    dispatch.started,
+    "Ghostget live receipt started dispatch count",
+    0,
+    Number.MAX_SAFE_INTEGER,
+  );
+  const verified = safeInteger(
+    dispatch.verified,
+    "Ghostget live receipt verified dispatch count",
+    0,
+    Number.MAX_SAFE_INTEGER,
+  );
+  if (planned !== 0 || started !== 0 || verified !== 0) {
+    throw new Error("Ghostget live receipt dispatch counts are inconsistent");
+  }
+  const status = parseReceiptStatus(receipt.status);
+  const finalOrigin = receipt.finalOrigin === null
+    ? null
+    : safeString(receipt.finalOrigin, "Ghostget live receipt final origin", 4_096);
+  const error = receipt.error === null
+    ? null
+    : boundedUtf8String(
+        receipt.error,
+        "Ghostget live receipt error",
+        MAX_RUN_RECEIPT_ERROR_BYTES,
+      );
+  if (receipt.planDigest !== null) {
+    throw new Error("Ghostget live receipt plan digest is malformed");
+  }
+  const startedAt = timestamp(receipt.startedAt, "Ghostget live receipt start time");
+  const finishedAt = timestamp(receipt.finishedAt, "Ghostget live receipt finish time");
+  if (startedAt > finishedAt) {
+    throw new Error("Ghostget live receipt finished before it started");
+  }
+  const common = Object.freeze({
+    runId: safeString(receipt.runId, "Ghostget live receipt run ID", 64),
+    planDigest: null,
+    adapter: Object.freeze({
+      id: safeString(adapter.id, "Ghostget live receipt adapter ID", 64),
+      version: safeString(adapter.version, "Ghostget live receipt adapter version", 64),
+      hash: digest(adapter.hash, "Ghostget live receipt adapter hash"),
+    }),
+    operation: providerOperationName(
+      receipt.operation,
+      "Ghostget live receipt operation",
+    ),
+    risk: "R1" as const,
+    inputHash: digest(receipt.inputHash, "Ghostget live receipt input hash"),
+    auth: Object.freeze({
+      id: safeString(auth.id, "Ghostget live receipt auth ID", 64),
+      hash: digest(auth.hash, "Ghostget live receipt auth hash"),
+      kind: authKind,
+    }),
+    status,
+    dispatchStarted: false as const,
+    dispatch: Object.freeze({
+      planned: 0 as const,
+      started: 0 as const,
+      verified: 0 as const,
+    }),
+    startedAt,
+    finishedAt,
+    finalOrigin,
+    error,
+  });
+  if (
+    common.adapter.id !== request.adapterId
+    || common.operation !== request.operationId
+  ) throw new Error("Ghostget live receipt route does not match its request");
+  if (
+    common.auth.id !== expectedRequestAuthId(request, common.auth.kind)
+  ) {
+    throw new Error("Ghostget live receipt auth does not match its request");
+  }
+  if (common.auth.kind === PUBLIC_WEB_SESSION_AUTHORITY_KIND) {
+    const authority = publicWebSessionAuthority(request);
+    if (
+      receipt.schemaVersion !== 4
+      || receipt.transport !== "web-session-api"
+      || common.auth.hash !== sha256(canonicalJson(authority))
+    ) {
+      throw new Error("Ghostget live receipt public authority is malformed");
+    }
+  }
+  if (common.inputHash !== expectedInputHash) {
+    throw new Error("Ghostget live receipt input does not match its request");
+  }
+  if (receipt.schemaVersion === 2 && receipt.transport === "browser") {
+    return Object.freeze({ ...common, schemaVersion: 2 as const, transport: "browser" as const });
+  }
+  if (receipt.schemaVersion === 3 && receipt.transport === "provider-api") {
+    return Object.freeze({
+      ...common,
+      schemaVersion: 3 as const,
+      transport: "provider-api" as const,
+      providerContractHash: digest(
+        receipt.providerContractHash,
+        "Ghostget live receipt provider contract hash",
+      ),
+    });
+  }
+  if (receipt.schemaVersion === 4 && receipt.transport === "web-session-api") {
+    return Object.freeze({
+      ...common,
+      schemaVersion: 4 as const,
+      transport: "web-session-api" as const,
+      webSessionContractHash: digest(
+        receipt.webSessionContractHash,
+        "Ghostget live receipt web-session contract hash",
+      ),
+    });
+  }
+  if (
+    receipt.schemaVersion === 5
+    && receipt.transport === "reviewed-template-api"
+  ) {
+    return Object.freeze({
+      ...common,
+      schemaVersion: 5 as const,
+      transport: "reviewed-template-api" as const,
+      reviewedTemplateContractHash: digest(
+        receipt.reviewedTemplateContractHash,
+        "Ghostget live receipt reviewed-template contract hash",
+      ),
+    });
+  }
+  if (
+    receipt.schemaVersion === 6
+    && receipt.transport === "portable-provider-plugin"
+  ) {
+    const portablePluginContract = parsePortableOperationIdentity(
+      receipt.portablePluginContract,
+    );
+    if (
+      portablePluginContract.adapterId !== common.adapter.id
+      || portablePluginContract.operation !== common.operation
+    ) {
+      throw new Error("Ghostget live portable contract route is malformed");
+    }
+    return Object.freeze({
+      ...common,
+      schemaVersion: 6 as const,
+      transport: "portable-provider-plugin" as const,
+      portablePluginContract,
+    });
+  }
+  if (receipt.schemaVersion === 7 && receipt.transport === "local-cli") {
+    const localCliContract = parseLocalCliContractIdentity(
+      receipt.localCliContract,
+    );
+    if (localCliContract.action !== common.operation) {
+      throw new Error("Ghostget live local CLI contract route is malformed");
+    }
+    return Object.freeze({
+      ...common,
+      schemaVersion: 7 as const,
+      transport: "local-cli" as const,
+      localCliContract,
+    });
+  }
+  throw new Error("Ghostget live receipt schema and transport are malformed");
+}
+
+function parseLiveResult(
+  value: JsonRecord,
+  request: PreparedRequest,
+  expectedInputHash: string,
+): {
+  readonly live: GhostgetClientInvocationResult;
+  readonly cache: ReadProjectionCacheOutcome;
+} {
+  assertExactKeys(
+    value,
+    ["ok", "source", "status", "runId", "replayed", "receipt", "output", "cache"],
+    ["readFailure"],
+    "Ghostget live response",
+  );
+  if (value.source !== "live") throw new Error("Ghostget live response has the wrong source");
+  const receipt = parseLiveReceipt(value.receipt, request, expectedInputHash);
+  const status = safeString(value.status, "Ghostget live status", 32);
+  const responseRunId = safeString(value.runId, "Ghostget live run ID", 64);
+  const expectedOk = receipt.status === "succeeded";
+  if (
+    status !== receipt.status
+    || receipt.runId !== responseRunId
+    || value.ok !== expectedOk
+  ) {
+    throw new Error("Ghostget live response is not bound to its receipt");
+  }
+  if (typeof value.replayed !== "boolean" || !("output" in value)) {
+    throw new Error("Ghostget live response is incomplete");
+  }
+  const cache = parseCacheOutcome(value.cache);
+  const cacheMatchesReceipt = receipt.status === "succeeded"
+    ? cache.status === "stored"
+      || cache.status === "error"
+      || cache.status === "skipped"
+    : cache.status === "retained"
+      || cache.status === "miss"
+      || cache.status === "error"
+      || cache.status === "skipped";
+  if (!cacheMatchesReceipt) {
+    throw new Error(
+      "Ghostget live cache outcome is inconsistent with its receipt",
+    );
+  }
+  const live: GhostgetClientInvocationResult = receipt.status === "failed"
+    ? (() => {
+        if (value.output !== null) {
+          throw new Error("Ghostget failed live response retained an output");
+        }
+        return Object.freeze({
+          status: "failed" as const,
+          receipt: receipt as GhostgetClientRunReceipt & {
+            readonly status: "failed";
+          },
+          output: null,
+          replayed: value.replayed,
+          readFailure: parseClientReadFailure(value.readFailure),
+        });
+      })()
+    : (() => {
+        if (value.readFailure !== undefined) {
+          throw new Error("Ghostget successful live response included a read failure");
+        }
+        return Object.freeze({
+          status: "succeeded" as const,
+          receipt: receipt as GhostgetClientRunReceipt & {
+            readonly status: "succeeded";
+          },
+          output: value.output,
+          replayed: value.replayed,
+        });
+      })();
+  return Object.freeze({
+    live,
+    cache,
+  });
+}
+
+function assertLiveInvocationFences(
+  request: PreparedRequest,
+  options: PreparedClientOptions,
+  executionIdentityBefore: ExecutionIdentity,
+  identityBefore: ProjectionIdentity,
+  parsed: Readonly<{
+    live: GhostgetClientInvocationResult;
+    cache: ReadProjectionCacheOutcome;
+  }>,
+  activity: "invocation" | "revalidation",
+): void {
+  const identityAfter = observeProjectionIdentity(request, options);
+  if (!projectionIdentitiesMatch(identityBefore, identityAfter)) {
+    throw new Error(
+      `Ghostget projection identity changed while ${activity} was running; the live result was discarded`,
+    );
+  }
+  if (!executionIdentitiesMatch(
+    executionIdentityBefore,
+    receiptExecutionIdentity(parsed.live.receipt),
+  )) {
+    throw new Error(
+      `Ghostget execution identity changed while ${activity} was running; the live result was discarded`,
+    );
+  }
+  if (parsed.live.receipt.auth.hash !== identityBefore.authHash) {
+    throw new Error(
+      `Ghostget projection identity changed while ${activity} was running; the live result was discarded`,
+    );
+  }
+  if (identityBefore.status === "unbound") {
+    if (parsed.cache.status !== "skipped") {
+      throw new Error(
+        `Ghostget projection identity changed while ${activity} was running; the live result was discarded`,
+      );
+    }
+    return;
+  }
+  if (
+    parsed.cache.status === "skipped"
+    || (
+      parsed.cache.status === "stored"
+      && parsed.cache.publication.key !== identityBefore.key
+    )
+  ) {
+    throw new Error(
+      `Ghostget projection identity changed while ${activity} was running; the live result was discarded`,
+    );
+  }
+}
+
+export function readCachedCapability(
+  request: CapabilityReadRequest,
+  options: ReadCapabilityOptions = {},
+): ReadProjectionCacheResult {
+  const preparedOptions = snapshotClientOptions(options, "read");
+  const now = validateReadOptions(preparedOptions);
+  const prepared = prepareRequest(request);
+  return readCachedPreparedCapability(prepared, preparedOptions, now);
+}
+
+function readCachedPreparedCapability(
+  request: PreparedRequest,
+  options: PreparedClientOptions,
+  now: Date,
+): ReadProjectionCacheResult {
+  const command = preparedCommand(request, {
+    cacheOnly: true,
+    projectionIdentityOnly: false,
+    headed: false,
+  });
+  return parseCacheResult(
+    runCacheCommand(command, options).output,
+    options,
+    now,
+  );
+}
+
+function selectCurrentCapability(
+  cachedBefore: ReadProjectionCacheResult | null,
+  cachedAfter: ReadProjectionCacheResult | null,
+  parsed: Pick<RevalidatedCapability, "live" | "cache">,
+): RevalidatedCapabilityCurrent {
+  const before = cachedBefore?.status === "hit" ? cachedBefore : null;
+  const after = cachedAfter?.status === "hit" ? cachedAfter : null;
+  if (parsed.live.status === "failed") return after;
+  if (parsed.cache.status === "stored") {
+    if (after !== null) return after;
+    if (parsed.cache.publication.disposition === "superseded") return null;
+    return Object.freeze({ source: "live", output: parsed.live.output });
+  }
+  if (parsed.cache.status === "error") {
+    const cacheAdvanced = after !== null
+      && (
+        before === null
+        || after.runId !== before.runId
+        || after.dataRevision !== before.dataRevision
+        || after.validatedAt !== before.validatedAt
+      );
+    if (cacheAdvanced) return after;
+  }
+  return Object.freeze({ source: "live", output: parsed.live.output });
+}
+
+async function runRevalidation(
+  request: PreparedRequest,
+  options: PreparedClientOptions,
+  executionIdentityBefore: ExecutionIdentity,
+  identityBefore: ProjectionIdentity,
+  cachedBefore: ReadProjectionCacheResult | null,
+  observationTime: Date,
+): Promise<RevalidatedCapability> {
+  const parsed = parseLiveResult(
+    await runLiveCommand(
+      preparedCommand(request, {
+        cacheOnly: false,
+        projectionIdentityOnly: false,
+        headed: options.headed ?? false,
+      }),
+      options,
+    ),
+    request,
+    identityBefore.inputHash,
+  );
+  // Identity preflights do not decode projection payloads, so corrupt local
+  // data can still be repaired by a live read. Every process receives one
+  // frozen options/environment snapshot. Both the projection key and unbound
+  // auth token include Ghostget's auth incarnation and detect A-to-B-to-A
+  // mutations.
+  assertLiveInvocationFences(
+    request,
+    options,
+    executionIdentityBefore,
+    identityBefore,
+    parsed,
+    "revalidation",
+  );
+  if (identityBefore.status === "unbound") {
+    return Object.freeze({
+      cachedBefore: null,
+      cachedAfter: null,
+      current: selectCurrentCapability(null, null, parsed),
+      ...parsed,
+    });
+  }
+  let cachedAfter: ReadProjectionCacheResult | null = null;
+  try {
+    cachedAfter = readCachedPreparedCapability(
+      request,
+      options,
+      observationTime,
+    );
+  } catch {
+    // The identity-only preflight remains authoritative when a corrupt cache
+    // payload could not be decoded before or after live repair.
+  }
+  if (
+    (cachedBefore !== null && cachedBefore.key !== identityBefore.key)
+    || (cachedAfter !== null && cachedAfter.key !== identityBefore.key)
+  ) {
+    throw new Error(
+      "Ghostget projection identity changed while revalidation was running; the live result was discarded",
+    );
+  }
+  return Object.freeze({
+    cachedBefore,
+    cachedAfter,
+    current: selectCurrentCapability(cachedBefore, cachedAfter, parsed),
+    ...parsed,
+  });
+}
+
+type CachedBeforeSource =
+  | { readonly status: "provided"; readonly value: ReadProjectionCacheResult | null }
+  | { readonly status: "lookup" };
+
+function scheduleRevalidation(
+  request: PreparedRequest,
+  options: PreparedClientOptions,
+  observationTime: Date,
+  cachedBeforeSource: CachedBeforeSource,
+): Promise<RevalidatedCapability> {
+  // Promise callbacks run after the public API returns. Keep every identity
+  // and live subprocess behind this boundary while retaining the exact frozen
+  // request, options, observation time, and any cache-only SWR result.
+  return Promise.resolve().then(() => {
+    const executionIdentityBefore = observeExecutionIdentity(request, options);
+    const identityBefore = observeProjectionIdentity(request, options);
+    let cachedBefore = cachedBeforeSource.status === "provided"
+      ? cachedBeforeSource.value
+      : null;
+    if (
+      cachedBeforeSource.status === "lookup"
+      && identityBefore.status === "ready"
+    ) {
+      try {
+        cachedBefore = readCachedPreparedCapability(
+          request,
+          options,
+          observationTime,
+        );
+      } catch {
+        // A valid identity preflight fences live repair even when the encrypted
+        // projection itself is corrupt or temporarily unreadable.
+      }
+    }
+    if (
+      cachedBefore !== null
+      && (
+        identityBefore.status !== "ready"
+        || cachedBefore.key !== identityBefore.key
+      )
+    ) {
+      throw new Error(
+        "Ghostget projection identity changed before revalidation started",
+      );
+    }
+    return runRevalidation(
+      request,
+      options,
+      executionIdentityBefore,
+      identityBefore,
+      cachedBefore,
+      observationTime,
+    );
+  });
+}
+
+/**
+ * Invoke one semantic R1 read through the installed CLI and return only the
+ * already-validated live receipt/output envelope. The promise defers every
+ * subprocess until after this function returns.
+ */
+export function invokeCapability(
+  request: CapabilityReadRequest,
+  options: InvokeCapabilityOptions = {},
+): Promise<GhostgetClientInvocationResult> {
+  const preparedOptions = snapshotClientOptions(options, "invoke-async");
+  const prepared = prepareRequest(request);
+  return Promise.resolve().then(async () => {
+    const executionIdentityBefore = observeExecutionIdentity(
+      prepared,
+      preparedOptions,
+    );
+    const identityBefore = observeProjectionIdentity(prepared, preparedOptions);
+    const parsed = parseLiveResult(
+      await runLiveCommand(
+        preparedCommand(prepared, {
+          cacheOnly: false,
+          projectionIdentityOnly: false,
+          headed: preparedOptions.headed ?? false,
+        }),
+        preparedOptions,
+      ),
+      prepared,
+      identityBefore.inputHash,
+    );
+    assertLiveInvocationFences(
+      prepared,
+      preparedOptions,
+      executionIdentityBefore,
+      identityBefore,
+      parsed,
+      "invocation",
+    );
+    return parsed.live;
+  });
+}
+
+/**
+ * Synchronous live invocation for CLI applications whose command surface is
+ * synchronous. It uses the same exact request snapshot, receipt parser, cache
+ * outcome validation, and before/after identity fences as the async client.
+ */
+export function invokeCapabilitySync(
+  request: CapabilityReadRequest,
+  options: InvokeCapabilitySyncOptions = {},
+): GhostgetClientInvocationResult {
+  const preparedOptions = snapshotClientOptions(options, "invoke-sync");
+  const prepared = prepareRequest(request);
+  const executionIdentityBefore = observeExecutionIdentity(
+    prepared,
+    preparedOptions,
+  );
+  const identityBefore = observeProjectionIdentity(prepared, preparedOptions);
+  const parsed = parseLiveResult(
+    runLiveCommandSync(
+      preparedCommand(prepared, {
+        cacheOnly: false,
+        projectionIdentityOnly: false,
+        headed: preparedOptions.headed ?? false,
+      }),
+      preparedOptions,
+    ),
+    prepared,
+    identityBefore.inputHash,
+  );
+  assertLiveInvocationFences(
+    prepared,
+    preparedOptions,
+    executionIdentityBefore,
+    identityBefore,
+    parsed,
+    "invocation",
+  );
+  return parsed.live;
+}
+
+export function revalidateCapability(
+  request: CapabilityReadRequest,
+  options: RevalidateCapabilityOptions = {},
+): Promise<RevalidatedCapability> {
+  const preparedOptions = snapshotClientOptions(options, "revalidation");
+  const now = validateReadOptions(preparedOptions);
+  const prepared = prepareRequest(request);
+  return scheduleRevalidation(
+    prepared,
+    preparedOptions,
+    now,
+    { status: "lookup" },
+  );
+}
+
+/**
+ * Read the current exact projection synchronously through Ghostget's installed
+ * cache-only command, then start one semantic R1 revalidation through the same
+ * CLI safety kernel. No provider runtime is bundled into this client module.
+ */
+export function staleWhileRevalidateCapability(
+  request: CapabilityReadRequest,
+  options: RevalidateCapabilityOptions = {},
+): {
+  readonly cached: ReadProjectionCacheResult | null;
+  readonly revalidation: Promise<RevalidatedCapability>;
+} {
+  const preparedOptions = snapshotClientOptions(options, "revalidation");
+  const now = validateReadOptions(preparedOptions);
+  const prepared = prepareRequest(request);
+  let cached: ReadProjectionCacheResult | null = null;
+  try {
+    cached = readCachedPreparedCapability(prepared, preparedOptions, now);
+  } catch {
+    // Cache corruption or an unbound subject must not suppress the separately
+    // scheduled live path.
+  }
+  return Object.freeze({
+    cached,
+    revalidation: scheduleRevalidation(
+      prepared,
+      preparedOptions,
+      now,
+      { status: "provided", value: cached },
+    ),
+  });
+}
+
+export type {
+  CapabilityReadRequest,
+  InvokeCapabilityOptions,
+  InvokeCapabilitySyncOptions,
+  ReadCapabilityOptions,
+  ReadProjectionCacheResult,
+  ReadProjectionCacheOutcome,
+  ReadProjectionPublication,
+  RevalidateCapabilityOptions,
+  RevalidatedCapability,
+  RevalidatedCapabilityCurrent,
+  GhostgetClientEnvironment,
+  GhostgetClientInvocationResult,
+  GhostgetClientPortableOperationIdentity,
+  GhostgetClientReadFailure,
+  GhostgetClientRunReceipt,
+  GhostgetClientRunReceiptCommon,
+} from "./client-types";