@adcp/sdk 16.1.0 → 16.3.0

package/dist/lib/testing/storyboard/prepared-fixtures.mjs

@@ -0,0 +1,389 @@
+import { createHash, createHmac, randomBytes, randomUUID } from "node:crypto";
+import { readdirSync, statSync } from "node:fs";
+import path from "node:path";
+import { getActiveSchemaArtifactLocation } from "../../validation/schema-loader.mjs";
+import { ADCP_VERSION } from "../../version.mjs";
+const PREPARED_FIXTURES_CONTRACT_VERSION = "1.0.0";
+const REFERENCE_REFUSAL_DETAIL = "prepared fixture state was refused by the configured authorizer";
+const trustedStates = /* @__PURE__ */ new WeakSet();
+const registries = /* @__PURE__ */ new WeakMap();
+function freezeDeepLocal(value) {
+  if (value === null || typeof value !== "object") return value;
+  if (Object.isFrozen(value)) return value;
+  Object.freeze(value);
+  for (const nested of Object.values(value)) freezeDeepLocal(nested);
+  return value;
+}
+const CONSTRUCTION_TOKEN = /* @__PURE__ */ Symbol("adcp.preparedStoryboardFixtures");
+class PreparedStoryboardFixtures {
+  #binding;
+  #resolutions;
+  #coverageGaps;
+  #captures;
+  #captureProvenance;
+  #witnesses;
+  #disposition;
+  #phase;
+  /**
+   * @internal Constructed only by `prepareStoryboardFixtures`. The token is
+   * module-private, so an external `new` call cannot satisfy it.
+   */
+  constructor(init, token) {
+    if (token !== CONSTRUCTION_TOKEN) {
+      throw new Error(
+        "PreparedStoryboardFixtures cannot be constructed directly; call prepareStoryboardFixtures() to produce prepared state"
+      );
+    }
+    this.#binding = freezeDeepLocal(structuredClone(init.binding));
+    if (init.bindings) registries.set(this, init.bindings);
+    this.#resolutions = Object.freeze(structuredClone(init.resolutions));
+    this.#coverageGaps = Object.freeze(structuredClone(init.coverageGaps));
+    this.#captures = Object.freeze(structuredClone(init.captures));
+    this.#captureProvenance = Object.freeze(structuredClone(init.captureProvenance));
+    this.#witnesses = Object.freeze(structuredClone(init.witnesses));
+    this.#disposition = freezeDeepLocal(structuredClone(init.disposition));
+    this.#phase = init.phase === void 0 ? void 0 : structuredClone(init.phase);
+    trustedStates.add(this);
+    Object.freeze(this);
+  }
+  /** Nonsecret binding identity. Detached copy. */
+  get binding() {
+    return structuredClone(this.#binding);
+  }
+  get disposition() {
+    return structuredClone(this.#disposition);
+  }
+  /** Machine-readable per-handle resolution evidence. Detached copy. */
+  get resolutions() {
+    return structuredClone(this.#resolutions);
+  }
+  /** Coverage gaps observed during preparation. Detached copy. */
+  get coverageGaps() {
+    return structuredClone(this.#coverageGaps);
+  }
+  /** Pinned seller identities per handle. Detached copy. */
+  get selections() {
+    return this.#resolutions.filter((record) => record.seller_ids !== void 0).map((record) => ({
+      handle: record.handle,
+      fixture_type: record.fixture_type,
+      ...record.product_handle && { product_handle: record.product_handle },
+      seller_ids: structuredClone(record.seller_ids)
+    }));
+  }
+  /** Reserved-namespace captures. Detached copy. */
+  get captures() {
+    return structuredClone(this.#captures);
+  }
+  /** Capture provenance. Detached copy. */
+  get captureProvenance() {
+    return structuredClone(this.#captureProvenance);
+  }
+  /** Retained collection witnesses per handle. Detached copy. */
+  get witnesses() {
+    return structuredClone(this.#witnesses);
+  }
+  /**
+   * Detached copy of the synthetic pre-flight phase, for attachment to a
+   * full run's report. A live reference would let a report consumer mutate
+   * the preparation's own evidence — including a failed or no-match
+   * disposition's raw failure detail.
+   */
+  get phase() {
+    return this.#phase === void 0 ? void 0 : structuredClone(this.#phase);
+  }
+}
+Object.freeze(PreparedStoryboardFixtures.prototype);
+function readPreparedBindingRegistry(state) {
+  return registries.get(state);
+}
+function preparedBindingRegistryFor(state) {
+  return readPreparedBindingRegistry(state);
+}
+function createPreparedStoryboardFixtures(init) {
+  return new PreparedStoryboardFixtures(init, CONSTRUCTION_TOKEN);
+}
+function withPreparedFixtures(state, authorizer) {
+  return { prepared_fixtures: state, prepared_fixtures_authorizer: authorizer };
+}
+function isTrustedPreparedFixtures(value) {
+  return value instanceof PreparedStoryboardFixtures && trustedStates.has(value);
+}
+const CREDENTIAL_FINGERPRINT_KEY = randomBytes(32);
+function fingerprintCredential(secret) {
+  return createHmac("sha256", CREDENTIAL_FINGERPRINT_KEY).update(secret).digest("hex").slice(0, 32);
+}
+function redactRouteCredentials(raw) {
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    return raw;
+  }
+  url.username = "";
+  url.password = "";
+  for (const key of [...url.searchParams.keys()]) {
+    if (/(token|secret|key|password|credential|signature|auth)/i.test(key)) {
+      url.searchParams.set(key, "[redacted]");
+    }
+  }
+  url.hash = "";
+  return url.toString();
+}
+function canonicalize(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+  if (Array.isArray(value)) return `[${value.map(canonicalize).join(",")}]`;
+  const entries = Object.entries(value).filter(([, nested]) => nested !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+  return `{${entries.map(([key, nested]) => `${JSON.stringify(key)}:${canonicalize(nested)}`).join(",")}}`;
+}
+function digestStoryboard(storyboard) {
+  return createHash("sha256").update(canonicalize(storyboard)).digest("hex");
+}
+const schemaDigestCache = /* @__PURE__ */ new Map();
+function digestSchemaRoot(root) {
+  const cached = schemaDigestCache.get(root);
+  if (cached !== void 0) return cached;
+  const lines = [`root\0${root}`];
+  const walk = (dir, rel) => {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      lines.push(`${rel || "."}\0unreadable-dir`);
+      return;
+    }
+    for (const entry of entries.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)) {
+      const absolute = path.join(dir, entry.name);
+      const relative = rel ? `${rel}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        walk(absolute, relative);
+        continue;
+      }
+      try {
+        const stat = statSync(absolute);
+        lines.push(`${relative}\0${stat.size}\0${stat.mtimeMs}`);
+      } catch {
+        lines.push(`${relative}\0unreadable`);
+      }
+    }
+  };
+  walk(root, "");
+  const digest = createHash("sha256").update(lines.join("\n")).digest("hex");
+  schemaDigestCache.set(root, digest);
+  return digest;
+}
+function resolveSchemaArtifact(adcpVersion = ADCP_VERSION) {
+  const location = getActiveSchemaArtifactLocation(adcpVersion);
+  return {
+    adcp_version: adcpVersion,
+    bundle_key: location.bundle_key,
+    external: location.external,
+    digest: digestSchemaRoot(location.root)
+  };
+}
+function buildPreparedBinding(input) {
+  return {
+    storyboard_id: input.storyboard.id,
+    storyboard_digest: digestStoryboard(input.storyboard),
+    agent_urls: [...input.agentUrls].sort().map(redactRouteCredentials),
+    // The route the GRAPH was pinned against, positionally — preparation
+    // contacts exactly one agent, `agentUrls[0]`, and nothing else in the
+    // binding records which one that was. `agent_urls` is sorted and
+    // `agent_route_fingerprint` sorts by key, both deliberately
+    // order-insensitive, so two runs whose `agents` maps differ only in
+    // insertion order produced byte-identical bindings while preparation
+    // had actually read seller B's catalog for one and seller A's for the
+    // other. Reuse across them sent B's pinned product_id to A.
+    fixture_agent_url: redactRouteCredentials(input.agentUrls[0] ?? ""),
+    // Covers the specialism→URL PAIRING, not just the URL set. Sorting the
+    // set alone meant swapping two specialisms' routes left the fingerprint
+    // unchanged while every per-specialism credential went to a different
+    // seller.
+    agent_route_fingerprint: fingerprintCredential(
+      JSON.stringify([
+        [...input.agentUrls].sort(),
+        input.agentRouteMap ? [...input.agentRouteMap].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0) : null,
+        // The RAW positional first url — the one preparation contacts.
+        // `fixture_agent_url` beside it is redacted for the authorizer to
+        // read, so two routes differing only in userinfo or a credential
+        // query parameter render identically there and would have
+        // collapsed into one binding.
+        input.agentUrls[0] ?? null
+      ])
+    ),
+    schema_artifact: resolveSchemaArtifact(input.adcpVersion ?? ADCP_VERSION),
+    contract_version: PREPARED_FIXTURES_CONTRACT_VERSION,
+    account_scope: input.accountScope,
+    brand_scope: input.brandScope,
+    ...input.requestAccountScope !== void 0 && { request_account_scope: input.requestAccountScope },
+    sandbox: input.sandbox,
+    ...input.principal !== void 0 && { principal: input.principal },
+    credential_fingerprint: fingerprintCredential(input.credential),
+    ...input.stepCredential !== void 0 && {
+      step_credential_fingerprint: fingerprintCredential(input.stepCredential)
+    },
+    ...input.stepAuthKind !== void 0 && { step_auth_kind: input.stepAuthKind },
+    // Independent of the credential: a routed step whose credential happens
+    // to equal the run's still dispatches to one specific seller.
+    ...input.stepRoute !== void 0 && { step_route: input.stepRoute },
+    run_id: input.runId ?? randomUUID()
+  };
+}
+const BINDING_FIELDS = [
+  "storyboard_id",
+  "storyboard_digest",
+  "agent_urls",
+  "agent_route_fingerprint",
+  "fixture_agent_url",
+  "schema_artifact",
+  "contract_version",
+  "account_scope",
+  "brand_scope",
+  "sandbox",
+  "principal",
+  "credential_fingerprint"
+];
+function diffPreparedBinding(prepared, current) {
+  const mismatches = [];
+  for (const field of BINDING_FIELDS) {
+    if (canonicalize(prepared[field]) !== canonicalize(current[field])) mismatches.push(field);
+  }
+  return mismatches;
+}
+function isReference(value) {
+  return typeof value === "object" && value !== null && typeof value.ref === "string" && typeof value.resolve === "function";
+}
+async function resolvePreparedFixtures(input) {
+  const supplied = input.supplied;
+  if (supplied === void 0) return void 0;
+  const authorizer = input.authorizer;
+  if (!authorizer) {
+    return {
+      ok: false,
+      refusal: {
+        code: "authorizer_required",
+        detail: isReference(supplied) ? "prepared_fixtures was supplied as an opaque reference, but no prepared_fixtures_authorizer was configured. An opaque reference is never authorization: supply an authorizer, because the SDK has no session and no grant store and cannot decide whether this reference is still yours." : "prepared_fixtures reuse requires prepared_fixtures_authorizer. Trusted object identity proves the state came from prepareStoryboardFixtures in this process; it does not establish a current grant, and binding coherence cannot observe revocation. Supply an authorizer that re-checks live grant state on every lookup. If this run genuinely has no grant model (single-tenant CLI, local dev), either drop prepared_fixtures and let the runner re-resolve, or pass prepared_fixtures_authorizer: () => ({ authorized: true }) as an explicit, reviewable decision. See docs/guides/COLLECTION-FIXTURE-FOUNDATION.md section 4."
+      }
+    };
+  }
+  let state = supplied;
+  let reference;
+  if (isReference(supplied)) {
+    reference = supplied.ref;
+    try {
+      state = await supplied.resolve(supplied.ref);
+    } catch {
+      state = void 0;
+    }
+  }
+  const refuseReference = async () => {
+    try {
+      await authorizer({
+        // Cloned, and cloned SEPARATELY, exactly as the authorized path
+        // does: handing the same object twice would let an authorizer
+        // detect `binding === current` by reference.
+        //
+        // That closes the object-IDENTITY distinction and nothing more.
+        // The VALUES still differ by path — a resolving reference carries
+        // the stored preparation binding, this one carries a second copy
+        // of `current` — so an authorizer that deep-compares them can
+        // still tell a missing reference from a present one. That is not
+        // the oracle this branch exists to close: the authorizer IS the
+        // host, it owns the store it would be learning about, and it
+        // cannot be given a fabricated stored binding without being lied
+        // to. What is closed is the oracle available to the CALLER, who
+        // sees only the refusal: identical text, identical machine code,
+        // identical validation shape, same authorizer call count.
+        binding: structuredClone(input.current),
+        current: structuredClone(input.current),
+        ...input.stepId !== void 0 && { step_id: input.stepId },
+        ...input.gate !== void 0 && { gate: input.gate },
+        ...reference !== void 0 && { reference }
+      });
+    } catch {
+    }
+    return { ok: false, refusal: { code: "authorizer_denied", detail: REFERENCE_REFUSAL_DETAIL } };
+  };
+  if (!isTrustedPreparedFixtures(state)) {
+    if (reference !== void 0) return refuseReference();
+    return {
+      ok: false,
+      refusal: {
+        code: "untrusted_state",
+        detail: "prepared fixture state was not produced by prepareStoryboardFixtures in this process; a rehydrated, cloned or caller-constructed look-alike carries no preparation authority"
+      }
+    };
+  }
+  const binding = state.binding;
+  if (binding.contract_version !== PREPARED_FIXTURES_CONTRACT_VERSION) {
+    if (reference !== void 0) return refuseReference();
+    return {
+      ok: false,
+      refusal: {
+        code: "contract_version_mismatch",
+        detail: `prepared state declares contract version ${binding.contract_version}; this runner implements ${PREPARED_FIXTURES_CONTRACT_VERSION}`
+      }
+    };
+  }
+  let authorized = false;
+  let decisionDetail;
+  try {
+    const decision = await authorizer({
+      binding: structuredClone(binding),
+      current: structuredClone(input.current),
+      ...input.stepId !== void 0 && { step_id: input.stepId },
+      ...input.gate !== void 0 && { gate: input.gate },
+      ...reference !== void 0 && { reference }
+    });
+    authorized = decision?.authorized === true;
+    const detail = decision?.detail;
+    decisionDetail = typeof detail === "string" ? detail : void 0;
+  } catch {
+    return { ok: false, refusal: { code: "authorizer_denied", detail: REFERENCE_REFUSAL_DETAIL } };
+  }
+  if (!authorized) {
+    if (reference !== void 0) {
+      return { ok: false, refusal: { code: "authorizer_denied", detail: REFERENCE_REFUSAL_DETAIL } };
+    }
+    return {
+      ok: false,
+      refusal: {
+        code: "authorizer_denied",
+        // `detail` is optional, so an absent one must not render as the
+        // string "undefined" — a difference in text is a difference a
+        // caller can measure.
+        detail: decisionDetail !== void 0 && decisionDetail.length > 0 ? `prepared fixture state was refused by the configured authorizer: ${decisionDetail}` : REFERENCE_REFUSAL_DETAIL
+      }
+    };
+  }
+  const mismatches = diffPreparedBinding(binding, input.current);
+  if (mismatches.length > 0) {
+    if (reference !== void 0) {
+      return { ok: false, refusal: { code: "authorizer_denied", detail: REFERENCE_REFUSAL_DETAIL } };
+    }
+    return {
+      ok: false,
+      refusal: {
+        code: "binding_mismatch",
+        // Field names only. The values are another principal's identity when
+        // the caller guessed a reference, and `credential_fingerprint` must
+        // never reach operator-visible text at all.
+        detail: `prepared fixture state does not match the current run scope; differing binding field(s): ${mismatches.join(", ")}`
+      }
+    };
+  }
+  return { ok: true, state };
+}
+export {
+  PREPARED_FIXTURES_CONTRACT_VERSION,
+  PreparedStoryboardFixtures,
+  buildPreparedBinding,
+  createPreparedStoryboardFixtures,
+  diffPreparedBinding,
+  digestStoryboard,
+  fingerprintCredential,
+  isTrustedPreparedFixtures,
+  preparedBindingRegistryFor,
+  resolvePreparedFixtures,
+  resolveSchemaArtifact,
+  withPreparedFixtures
+};

package/dist/lib/testing/storyboard/protected-context.d.mts

@@ -0,0 +1,127 @@
+/**
+ * Protected storyboard-context namespace and the single atomic write funnel
+ * that guards it.
+ *
+ * Fixture preparation publishes the selected product, its scoped pricing and
+ * its collection witnesses into storyboard context so later steps can build
+ * requests from the entity that was actually pinned. Those values decide what
+ * gets purchased, so nothing downstream may replace, delete or shadow them:
+ * not caller-supplied `options.context`, not storyboard defaults, not a
+ * convention extractor, not an authored `context_outputs` entry, not a
+ * generator alias, not a task-completion capture, not creative-prefix
+ * cleanup, and not a seller response.
+ *
+ * Three properties, each load-bearing:
+ *
+ *  1. **Reserved flat namespace.** Keys under `__adcp_fixture_` are writable
+ *     only with a runner-owned capability. The prefix is flat so existing
+ *     whole-key `$context.<key>` substitution keeps working unchanged; no
+ *     nested-token syntax is introduced.
+ *  2. **Atomic whole-patch validation.** A patch touching a protected key
+ *     without the capability is rejected before *any* map changes, so a
+ *     partially-applied write can never leave context and provenance
+ *     disagreeing. Values, deletions, provenance entries and
+ *     unavailable-output markers all commit through the same call —
+ *     protecting values alone would let a caller suppress a prepared capture
+ *     by marking it unavailable, or rewrite its provenance. Prototype-
+ *     sensitive keys are refused outright for every writer, and writes use
+ *     `Object.defineProperty` so no inherited setter is ever invoked.
+ *  3. **Detached immutable snapshots.** Committed values are deep-cloned on
+ *     ingestion and deep-frozen, and every read for request building or
+ *     diagnostics hands back a fresh clone. Guarding map assignment alone is
+ *     not enough: `injectContext`/`deepReplace` hand out `context[key]` by
+ *     reference today, so a mutated request object can otherwise reach back
+ *     into the snapshot it was built from.
+ *
+ * The capability is a runtime object identity held in a module-private
+ * `WeakSet`. It is deliberately not a string, a `source_kind`, a provenance
+ * entry or a boolean: all of those are reachable from caller JSON. A
+ * structurally-cloned or JSON-rehydrated copy of a capability is not the
+ * capability, which is what keeps "I have a frozen object that looks right"
+ * from being authority.
+ */
+import type { ContextProvenanceEntry, StoryboardContext } from './types.mjs';
+/** Reserved flat prefix for preparation-produced context keys. */
+export declare const PROTECTED_CONTEXT_PREFIX = "__adcp_fixture_";
+/** True for any key inside the reserved namespace, well-formed or not. */
+export declare function isProtectedContextKey(key: string): boolean;
+export type ProtectedContextViolationCode = 'unauthorized_write' | 'unauthorized_delete' | 'unauthorized_metadata' | 'already_committed' | 'reserved_key' | 'uncloneable_value' | 'invalid_key';
+/** Thrown by the funnel; never partially applied. */
+export declare class ProtectedContextViolation extends Error {
+    readonly code: ProtectedContextViolationCode;
+    readonly keys: readonly string[];
+    constructor(code: ProtectedContextViolationCode, keys: readonly string[], detail: string);
+}
+/**
+ * Runner-owned write capability. Opaque by construction: the only way to
+ * obtain one that the funnel accepts is to call `createProtectedContextWriter`
+ * inside this process.
+ */
+export interface ProtectedContextWriter {
+    readonly kind: 'adcp.storyboard.protected-context-writer';
+}
+export declare function createProtectedContextWriter(): ProtectedContextWriter;
+/** Register a context object as protected under `writer`. Idempotent. */
+export declare function registerProtectedContext(context: StoryboardContext, writer: ProtectedContextWriter): void;
+/**
+ * Carry protection onto a clone. Call wherever the runner shallow-copies or
+ * adopts a context object, alongside `forwardAliasCache`.
+ */
+export declare function forwardProtectedContext(from: StoryboardContext, to: StoryboardContext): void;
+/** Keys already committed on this context, for evidence and diagnostics. */
+export declare function listProtectedContextKeys(context: StoryboardContext): string[];
+export interface ProtectedContextSinks {
+    /** Per-key provenance the runner reports back to callers. */
+    provenance?: Map<string, ContextProvenanceEntry>;
+    /** Keys a skipped/ungraded step marked as unavailable, with their reason. */
+    unavailable?: Map<string, string>;
+}
+export interface ProtectedContextPatch {
+    /** Values to write. */
+    set?: Readonly<Record<string, unknown>>;
+    /** Keys to remove. */
+    unset?: readonly string[];
+    /** Provenance entries to write. */
+    setProvenance?: Readonly<Record<string, ContextProvenanceEntry>>;
+    /** Provenance entries to remove. */
+    unsetProvenance?: readonly string[];
+    /** Keys to mark unavailable (reason keyed by the same key). */
+    markUnavailable?: Readonly<Record<string, string>> | readonly string[];
+    /** Keys whose unavailable marker should be cleared. */
+    clearUnavailable?: readonly string[];
+}
+export interface ApplyProtectedContextOptions {
+    writer?: ProtectedContextWriter;
+    sinks?: ProtectedContextSinks;
+    /**
+     * Where this patch came from, used verbatim in the violation message so an
+     * operator can see which funnel attempted the write.
+     */
+    origin: string;
+}
+/**
+ * The sole commit point for storyboard-context values, deletions, provenance
+ * and unavailable-output metadata.
+ *
+ * Validates the whole patch first. A forbidden write, delete or metadata
+ * change throws `ProtectedContextViolation` and leaves every map exactly as
+ * it was — including the ordinary, unprotected keys in the same patch, so a
+ * rejected batch never half-lands.
+ */
+export declare function applyProtectedContextPatch(context: StoryboardContext, patch: ProtectedContextPatch, options: ApplyProtectedContextOptions): void;
+/** Authoring-time guard for a declaration-produced reserved key. */
+export declare function assertWellFormedProtectedKey(key: string, location: string): void;
+/**
+ * Deep-freeze in place. Applied to the canonical snapshot after cloning, so
+ * the value the runner holds cannot be mutated even by code that reached it
+ * through an ordinary context read.
+ */
+export declare function freezeDeep<T>(value: T): T;
+/**
+ * Detached view of a protected value for request building or diagnostics.
+ *
+ * Request builders legitimately mutate the objects they are handed, so a
+ * frozen snapshot cannot be passed through directly; a clone is both safe to
+ * mutate and unable to write back.
+ */
+export declare function detachProtectedValue(value: unknown): unknown;

package/dist/lib/testing/storyboard/protected-context.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Protected storyboard-context namespace and the single atomic write funnel
+ * that guards it.
+ *
+ * Fixture preparation publishes the selected product, its scoped pricing and
+ * its collection witnesses into storyboard context so later steps can build
+ * requests from the entity that was actually pinned. Those values decide what
+ * gets purchased, so nothing downstream may replace, delete or shadow them:
+ * not caller-supplied `options.context`, not storyboard defaults, not a
+ * convention extractor, not an authored `context_outputs` entry, not a
+ * generator alias, not a task-completion capture, not creative-prefix
+ * cleanup, and not a seller response.
+ *
+ * Three properties, each load-bearing:
+ *
+ *  1. **Reserved flat namespace.** Keys under `__adcp_fixture_` are writable
+ *     only with a runner-owned capability. The prefix is flat so existing
+ *     whole-key `$context.<key>` substitution keeps working unchanged; no
+ *     nested-token syntax is introduced.
+ *  2. **Atomic whole-patch validation.** A patch touching a protected key
+ *     without the capability is rejected before *any* map changes, so a
+ *     partially-applied write can never leave context and provenance
+ *     disagreeing. Values, deletions, provenance entries and
+ *     unavailable-output markers all commit through the same call —
+ *     protecting values alone would let a caller suppress a prepared capture
+ *     by marking it unavailable, or rewrite its provenance. Prototype-
+ *     sensitive keys are refused outright for every writer, and writes use
+ *     `Object.defineProperty` so no inherited setter is ever invoked.
+ *  3. **Detached immutable snapshots.** Committed values are deep-cloned on
+ *     ingestion and deep-frozen, and every read for request building or
+ *     diagnostics hands back a fresh clone. Guarding map assignment alone is
+ *     not enough: `injectContext`/`deepReplace` hand out `context[key]` by
+ *     reference today, so a mutated request object can otherwise reach back
+ *     into the snapshot it was built from.
+ *
+ * The capability is a runtime object identity held in a module-private
+ * `WeakSet`. It is deliberately not a string, a `source_kind`, a provenance
+ * entry or a boolean: all of those are reachable from caller JSON. A
+ * structurally-cloned or JSON-rehydrated copy of a capability is not the
+ * capability, which is what keeps "I have a frozen object that looks right"
+ * from being authority.
+ */
+import type { ContextProvenanceEntry, StoryboardContext } from './types';
+/** Reserved flat prefix for preparation-produced context keys. */
+export declare const PROTECTED_CONTEXT_PREFIX = "__adcp_fixture_";
+/** True for any key inside the reserved namespace, well-formed or not. */
+export declare function isProtectedContextKey(key: string): boolean;
+export type ProtectedContextViolationCode = 'unauthorized_write' | 'unauthorized_delete' | 'unauthorized_metadata' | 'already_committed' | 'reserved_key' | 'uncloneable_value' | 'invalid_key';
+/** Thrown by the funnel; never partially applied. */
+export declare class ProtectedContextViolation extends Error {
+    readonly code: ProtectedContextViolationCode;
+    readonly keys: readonly string[];
+    constructor(code: ProtectedContextViolationCode, keys: readonly string[], detail: string);
+}
+/**
+ * Runner-owned write capability. Opaque by construction: the only way to
+ * obtain one that the funnel accepts is to call `createProtectedContextWriter`
+ * inside this process.
+ */
+export interface ProtectedContextWriter {
+    readonly kind: 'adcp.storyboard.protected-context-writer';
+}
+export declare function createProtectedContextWriter(): ProtectedContextWriter;
+/** Register a context object as protected under `writer`. Idempotent. */
+export declare function registerProtectedContext(context: StoryboardContext, writer: ProtectedContextWriter): void;
+/**
+ * Carry protection onto a clone. Call wherever the runner shallow-copies or
+ * adopts a context object, alongside `forwardAliasCache`.
+ */
+export declare function forwardProtectedContext(from: StoryboardContext, to: StoryboardContext): void;
+/** Keys already committed on this context, for evidence and diagnostics. */
+export declare function listProtectedContextKeys(context: StoryboardContext): string[];
+export interface ProtectedContextSinks {
+    /** Per-key provenance the runner reports back to callers. */
+    provenance?: Map<string, ContextProvenanceEntry>;
+    /** Keys a skipped/ungraded step marked as unavailable, with their reason. */
+    unavailable?: Map<string, string>;
+}
+export interface ProtectedContextPatch {
+    /** Values to write. */
+    set?: Readonly<Record<string, unknown>>;
+    /** Keys to remove. */
+    unset?: readonly string[];
+    /** Provenance entries to write. */
+    setProvenance?: Readonly<Record<string, ContextProvenanceEntry>>;
+    /** Provenance entries to remove. */
+    unsetProvenance?: readonly string[];
+    /** Keys to mark unavailable (reason keyed by the same key). */
+    markUnavailable?: Readonly<Record<string, string>> | readonly string[];
+    /** Keys whose unavailable marker should be cleared. */
+    clearUnavailable?: readonly string[];
+}
+export interface ApplyProtectedContextOptions {
+    writer?: ProtectedContextWriter;
+    sinks?: ProtectedContextSinks;
+    /**
+     * Where this patch came from, used verbatim in the violation message so an
+     * operator can see which funnel attempted the write.
+     */
+    origin: string;
+}
+/**
+ * The sole commit point for storyboard-context values, deletions, provenance
+ * and unavailable-output metadata.
+ *
+ * Validates the whole patch first. A forbidden write, delete or metadata
+ * change throws `ProtectedContextViolation` and leaves every map exactly as
+ * it was — including the ordinary, unprotected keys in the same patch, so a
+ * rejected batch never half-lands.
+ */
+export declare function applyProtectedContextPatch(context: StoryboardContext, patch: ProtectedContextPatch, options: ApplyProtectedContextOptions): void;
+/** Authoring-time guard for a declaration-produced reserved key. */
+export declare function assertWellFormedProtectedKey(key: string, location: string): void;
+/**
+ * Deep-freeze in place. Applied to the canonical snapshot after cloning, so
+ * the value the runner holds cannot be mutated even by code that reached it
+ * through an ordinary context read.
+ */
+export declare function freezeDeep<T>(value: T): T;
+/**
+ * Detached view of a protected value for request building or diagnostics.
+ *
+ * Request builders legitimately mutate the objects they are handed, so a
+ * frozen snapshot cannot be passed through directly; a clone is both safe to
+ * mutate and unable to write back.
+ */
+export declare function detachProtectedValue(value: unknown): unknown;