@adcp/sdk 16.2.0 → 16.4.0

package/dist/lib/testing/storyboard/protected-context.js

@@ -0,0 +1,301 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var protected_context_exports = {};
+__export(protected_context_exports, {
+  PROTECTED_CONTEXT_PREFIX: () => PROTECTED_CONTEXT_PREFIX,
+  ProtectedContextViolation: () => ProtectedContextViolation,
+  applyProtectedContextPatch: () => applyProtectedContextPatch,
+  assertWellFormedProtectedKey: () => assertWellFormedProtectedKey,
+  createProtectedContextWriter: () => createProtectedContextWriter,
+  detachProtectedValue: () => detachProtectedValue,
+  forwardProtectedContext: () => forwardProtectedContext,
+  freezeDeep: () => freezeDeep,
+  isProtectedContextKey: () => isProtectedContextKey,
+  listProtectedContextKeys: () => listProtectedContextKeys,
+  registerProtectedContext: () => registerProtectedContext
+});
+module.exports = __toCommonJS(protected_context_exports);
+const PROTECTED_CONTEXT_PREFIX = "__adcp_fixture_";
+const PROTECTED_KEY_PATTERN = /^__adcp_fixture_[A-Za-z0-9_]+$/;
+const PROTOTYPE_SENSITIVE_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+function isProtectedContextKey(key) {
+  return key.startsWith(PROTECTED_CONTEXT_PREFIX);
+}
+class ProtectedContextViolation extends Error {
+  code;
+  keys;
+  constructor(code, keys, detail) {
+    super(detail);
+    this.name = "ProtectedContextViolation";
+    this.code = code;
+    this.keys = [...keys];
+  }
+}
+const writers = /* @__PURE__ */ new WeakSet();
+function createProtectedContextWriter() {
+  const writer = Object.freeze({
+    kind: "adcp.storyboard.protected-context-writer"
+  });
+  writers.add(writer);
+  return writer;
+}
+function isTrustedWriter(writer) {
+  return writer !== void 0 && writers.has(writer);
+}
+const states = /* @__PURE__ */ new WeakMap();
+function registerProtectedContext(context, writer) {
+  if (!isTrustedWriter(writer)) {
+    throw new ProtectedContextViolation(
+      "unauthorized_write",
+      [],
+      "registerProtectedContext requires a runner-owned protected-context capability"
+    );
+  }
+  if (!states.has(context)) states.set(context, { committed: /* @__PURE__ */ new Set(), writer });
+}
+function forwardProtectedContext(from, to) {
+  const state = states.get(from);
+  if (!state) return;
+  const existing = states.get(to);
+  if (existing) {
+    for (const key of state.committed) existing.committed.add(key);
+    return;
+  }
+  states.set(to, { committed: new Set(state.committed), writer: state.writer });
+}
+function listProtectedContextKeys(context) {
+  return [...states.get(context)?.committed ?? []].sort();
+}
+function markUnavailableEntries(markUnavailable) {
+  if (markUnavailable === void 0) return [];
+  if (Array.isArray(markUnavailable)) return markUnavailable.map((key) => [key, "unavailable"]);
+  return Object.entries(markUnavailable);
+}
+function applyProtectedContextPatch(context, patch, options) {
+  const state = states.get(context);
+  const trusted = isTrustedWriter(options.writer) && state !== void 0 && state.writer === options.writer;
+  const setEntries = Object.entries(patch.set ?? {});
+  const unsetKeys = patch.unset ?? [];
+  const provenanceEntries = Object.entries(patch.setProvenance ?? {});
+  const provenanceUnset = patch.unsetProvenance ?? [];
+  const unavailableEntries = markUnavailableEntries(patch.markUnavailable);
+  const clearUnavailable = patch.clearUnavailable ?? [];
+  const prototypeKeys = [
+    ...setEntries.map(([key]) => key),
+    ...unsetKeys,
+    ...provenanceEntries.map(([key]) => key),
+    ...provenanceUnset,
+    ...unavailableEntries.map(([key]) => key),
+    ...clearUnavailable
+  ].filter((key) => PROTOTYPE_SENSITIVE_KEYS.has(key));
+  if (prototypeKeys.length > 0) {
+    throw new ProtectedContextViolation(
+      "reserved_key",
+      [...new Set(prototypeKeys)],
+      `${options.origin}: refused prototype-sensitive context key(s) ${[...new Set(prototypeKeys)].join(", ")}; these can rewrite the context's prototype and shadow reserved fixture keys. Rename them to anything other than __proto__, constructor or prototype.`
+    );
+  }
+  if (!trusted) {
+    const valueKeys = setEntries.map(([key]) => key).filter(isProtectedContextKey);
+    if (valueKeys.length > 0) {
+      throw new ProtectedContextViolation(
+        "unauthorized_write",
+        valueKeys,
+        `${options.origin}: cannot write reserved fixture-preparation context key(s) ${valueKeys.join(", ")}; the "${PROTECTED_CONTEXT_PREFIX}" namespace is owned by fixture preparation. Declare the value under fixture_resolution[].context_outputs instead, or rename the key.`
+      );
+    }
+    const deleteKeys = unsetKeys.filter(isProtectedContextKey);
+    if (deleteKeys.length > 0) {
+      throw new ProtectedContextViolation(
+        "unauthorized_delete",
+        deleteKeys,
+        `${options.origin}: cannot delete reserved fixture-preparation context key(s) ${deleteKeys.join(", ")}`
+      );
+    }
+    const metadataKeys = [
+      ...provenanceEntries.map(([key]) => key),
+      ...provenanceUnset,
+      ...unavailableEntries.map(([key]) => key),
+      ...clearUnavailable
+    ].filter(isProtectedContextKey);
+    if (metadataKeys.length > 0) {
+      throw new ProtectedContextViolation(
+        "unauthorized_metadata",
+        [...new Set(metadataKeys)],
+        `${options.origin}: cannot change provenance or availability metadata for reserved key(s) ${[...new Set(metadataKeys)].join(", ")}; suppressing a prepared capture is as damaging as overwriting it`
+      );
+    }
+  } else {
+    const recommitted = [
+      ...setEntries.map(([key]) => key),
+      ...unsetKeys,
+      ...provenanceUnset,
+      ...unavailableEntries.map(([key]) => key)
+    ].filter((key) => isProtectedContextKey(key) && state?.committed.has(key) === true);
+    if (recommitted.length > 0) {
+      throw new ProtectedContextViolation(
+        "already_committed",
+        recommitted,
+        `${options.origin}: reserved context key(s) ${recommitted.join(", ")} are already committed by fixture preparation and are immutable for the rest of the run`
+      );
+    }
+    for (const [key] of setEntries) {
+      if (isProtectedContextKey(key)) assertWellFormedProtectedKey(key, options.origin);
+    }
+  }
+  const mutatedKeys = [.../* @__PURE__ */ new Set([...setEntries.map(([key]) => key), ...unsetKeys])];
+  if (!Object.isExtensible(context)) {
+    const unsetSet = new Set(unsetKeys);
+    const added = mutatedKeys.filter((key) => !Object.hasOwn(context, key) || unsetSet.has(key));
+    if (added.length > 0) {
+      throw new ProtectedContextViolation(
+        "uncloneable_value",
+        added,
+        `${options.origin}: the storyboard context is not extensible, so key(s) ${added.join(", ")} cannot be written`
+      );
+    }
+  }
+  const locked = mutatedKeys.filter((key) => {
+    const descriptor = Object.getOwnPropertyDescriptor(context, key);
+    return descriptor !== void 0 && descriptor.configurable === false;
+  });
+  if (locked.length > 0) {
+    throw new ProtectedContextViolation(
+      "uncloneable_value",
+      locked,
+      `${options.origin}: context key(s) ${locked.join(", ")} are non-configurable and cannot be rewritten or removed`
+    );
+  }
+  const snapshots = /* @__PURE__ */ new Map();
+  for (const [key, value] of setEntries) {
+    if (!isProtectedContextKey(key)) continue;
+    let cloned;
+    try {
+      cloned = structuredClone(value);
+    } catch (error) {
+      throw new ProtectedContextViolation(
+        "uncloneable_value",
+        [key],
+        `${options.origin}: reserved context key "${key}" holds a value that cannot be detached (${error instanceof Error ? error.message : String(error)}); captures must be plain JSON-shaped data`
+      );
+    }
+    assertFreezable(cloned, key, options.origin);
+    snapshots.set(key, freezeDeep(cloned));
+  }
+  const provenanceSnapshots = /* @__PURE__ */ new Map();
+  for (const [key, entry] of provenanceEntries) {
+    if (!isProtectedContextKey(key)) continue;
+    let cloned;
+    try {
+      cloned = structuredClone(entry);
+    } catch (error) {
+      throw new ProtectedContextViolation(
+        "uncloneable_value",
+        [key],
+        `${options.origin}: provenance for reserved context key "${key}" cannot be detached (${error instanceof Error ? error.message : String(error)}); capture provenance must be plain JSON-shaped data`
+      );
+    }
+    assertFreezable(cloned, key, options.origin);
+    provenanceSnapshots.set(key, freezeDeep(cloned));
+  }
+  for (const key of unsetKeys) delete context[key];
+  for (const [key, value] of setEntries) {
+    Object.defineProperty(context, key, {
+      value: snapshots.has(key) ? snapshots.get(key) : value,
+      writable: true,
+      enumerable: true,
+      configurable: true
+    });
+    if (isProtectedContextKey(key)) state?.committed.add(key);
+  }
+  const sinks = options.sinks;
+  if (sinks?.provenance) {
+    for (const key of provenanceUnset) sinks.provenance.delete(key);
+    for (const [key, entry] of provenanceEntries) {
+      sinks.provenance.set(key, provenanceSnapshots.get(key) ?? entry);
+    }
+  }
+  if (sinks?.unavailable) {
+    for (const key of clearUnavailable) sinks.unavailable.delete(key);
+    for (const [key, reason] of unavailableEntries) sinks.unavailable.set(key, reason);
+  }
+}
+function assertWellFormedProtectedKey(key, location) {
+  if (PROTOTYPE_SENSITIVE_KEYS.has(key)) {
+    throw new ProtectedContextViolation(
+      "invalid_key",
+      [key],
+      `${location}: "${key}" is a prototype-sensitive key; rename it to anything other than __proto__, constructor or prototype`
+    );
+  }
+  if (!PROTECTED_KEY_PATTERN.test(key)) {
+    throw new ProtectedContextViolation(
+      "invalid_key",
+      [key],
+      `${location}: reserved capture key "${key}" must match ${PROTECTED_KEY_PATTERN.source} so whole-key $context.<key> substitution resolves it`
+    );
+  }
+}
+function assertFreezable(value, key, origin, seen = /* @__PURE__ */ new Set()) {
+  if (value === null || typeof value !== "object") return;
+  if (seen.has(value)) return;
+  seen.add(value);
+  if (Array.isArray(value)) {
+    for (const nested of value) assertFreezable(nested, key, origin, seen);
+    return;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) {
+    throw new ProtectedContextViolation(
+      "uncloneable_value",
+      [key],
+      `${origin}: reserved context key "${key}" holds a ${value.constructor?.name ?? "non-plain object"}, which Object.freeze cannot make immutable; captures must be plain JSON-shaped data`
+    );
+  }
+  for (const nested of Reflect.ownKeys(value)) {
+    assertFreezable(value[nested], key, origin, seen);
+  }
+}
+function freezeDeep(value) {
+  if (value === null || typeof value !== "object") return value;
+  if (Object.isFrozen(value)) return value;
+  Object.freeze(value);
+  for (const nested of Reflect.ownKeys(value)) {
+    freezeDeep(value[nested]);
+  }
+  return value;
+}
+function detachProtectedValue(value) {
+  if (value === null || typeof value !== "object") return value;
+  return structuredClone(value);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PROTECTED_CONTEXT_PREFIX,
+  ProtectedContextViolation,
+  applyProtectedContextPatch,
+  assertWellFormedProtectedKey,
+  createProtectedContextWriter,
+  detachProtectedValue,
+  forwardProtectedContext,
+  freezeDeep,
+  isProtectedContextKey,
+  listProtectedContextKeys,
+  registerProtectedContext
+});

package/dist/lib/testing/storyboard/protected-context.mjs

@@ -0,0 +1,267 @@
+const PROTECTED_CONTEXT_PREFIX = "__adcp_fixture_";
+const PROTECTED_KEY_PATTERN = /^__adcp_fixture_[A-Za-z0-9_]+$/;
+const PROTOTYPE_SENSITIVE_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+function isProtectedContextKey(key) {
+  return key.startsWith(PROTECTED_CONTEXT_PREFIX);
+}
+class ProtectedContextViolation extends Error {
+  code;
+  keys;
+  constructor(code, keys, detail) {
+    super(detail);
+    this.name = "ProtectedContextViolation";
+    this.code = code;
+    this.keys = [...keys];
+  }
+}
+const writers = /* @__PURE__ */ new WeakSet();
+function createProtectedContextWriter() {
+  const writer = Object.freeze({
+    kind: "adcp.storyboard.protected-context-writer"
+  });
+  writers.add(writer);
+  return writer;
+}
+function isTrustedWriter(writer) {
+  return writer !== void 0 && writers.has(writer);
+}
+const states = /* @__PURE__ */ new WeakMap();
+function registerProtectedContext(context, writer) {
+  if (!isTrustedWriter(writer)) {
+    throw new ProtectedContextViolation(
+      "unauthorized_write",
+      [],
+      "registerProtectedContext requires a runner-owned protected-context capability"
+    );
+  }
+  if (!states.has(context)) states.set(context, { committed: /* @__PURE__ */ new Set(), writer });
+}
+function forwardProtectedContext(from, to) {
+  const state = states.get(from);
+  if (!state) return;
+  const existing = states.get(to);
+  if (existing) {
+    for (const key of state.committed) existing.committed.add(key);
+    return;
+  }
+  states.set(to, { committed: new Set(state.committed), writer: state.writer });
+}
+function listProtectedContextKeys(context) {
+  return [...states.get(context)?.committed ?? []].sort();
+}
+function markUnavailableEntries(markUnavailable) {
+  if (markUnavailable === void 0) return [];
+  if (Array.isArray(markUnavailable)) return markUnavailable.map((key) => [key, "unavailable"]);
+  return Object.entries(markUnavailable);
+}
+function applyProtectedContextPatch(context, patch, options) {
+  const state = states.get(context);
+  const trusted = isTrustedWriter(options.writer) && state !== void 0 && state.writer === options.writer;
+  const setEntries = Object.entries(patch.set ?? {});
+  const unsetKeys = patch.unset ?? [];
+  const provenanceEntries = Object.entries(patch.setProvenance ?? {});
+  const provenanceUnset = patch.unsetProvenance ?? [];
+  const unavailableEntries = markUnavailableEntries(patch.markUnavailable);
+  const clearUnavailable = patch.clearUnavailable ?? [];
+  const prototypeKeys = [
+    ...setEntries.map(([key]) => key),
+    ...unsetKeys,
+    ...provenanceEntries.map(([key]) => key),
+    ...provenanceUnset,
+    ...unavailableEntries.map(([key]) => key),
+    ...clearUnavailable
+  ].filter((key) => PROTOTYPE_SENSITIVE_KEYS.has(key));
+  if (prototypeKeys.length > 0) {
+    throw new ProtectedContextViolation(
+      "reserved_key",
+      [...new Set(prototypeKeys)],
+      `${options.origin}: refused prototype-sensitive context key(s) ${[...new Set(prototypeKeys)].join(", ")}; these can rewrite the context's prototype and shadow reserved fixture keys. Rename them to anything other than __proto__, constructor or prototype.`
+    );
+  }
+  if (!trusted) {
+    const valueKeys = setEntries.map(([key]) => key).filter(isProtectedContextKey);
+    if (valueKeys.length > 0) {
+      throw new ProtectedContextViolation(
+        "unauthorized_write",
+        valueKeys,
+        `${options.origin}: cannot write reserved fixture-preparation context key(s) ${valueKeys.join(", ")}; the "${PROTECTED_CONTEXT_PREFIX}" namespace is owned by fixture preparation. Declare the value under fixture_resolution[].context_outputs instead, or rename the key.`
+      );
+    }
+    const deleteKeys = unsetKeys.filter(isProtectedContextKey);
+    if (deleteKeys.length > 0) {
+      throw new ProtectedContextViolation(
+        "unauthorized_delete",
+        deleteKeys,
+        `${options.origin}: cannot delete reserved fixture-preparation context key(s) ${deleteKeys.join(", ")}`
+      );
+    }
+    const metadataKeys = [
+      ...provenanceEntries.map(([key]) => key),
+      ...provenanceUnset,
+      ...unavailableEntries.map(([key]) => key),
+      ...clearUnavailable
+    ].filter(isProtectedContextKey);
+    if (metadataKeys.length > 0) {
+      throw new ProtectedContextViolation(
+        "unauthorized_metadata",
+        [...new Set(metadataKeys)],
+        `${options.origin}: cannot change provenance or availability metadata for reserved key(s) ${[...new Set(metadataKeys)].join(", ")}; suppressing a prepared capture is as damaging as overwriting it`
+      );
+    }
+  } else {
+    const recommitted = [
+      ...setEntries.map(([key]) => key),
+      ...unsetKeys,
+      ...provenanceUnset,
+      ...unavailableEntries.map(([key]) => key)
+    ].filter((key) => isProtectedContextKey(key) && state?.committed.has(key) === true);
+    if (recommitted.length > 0) {
+      throw new ProtectedContextViolation(
+        "already_committed",
+        recommitted,
+        `${options.origin}: reserved context key(s) ${recommitted.join(", ")} are already committed by fixture preparation and are immutable for the rest of the run`
+      );
+    }
+    for (const [key] of setEntries) {
+      if (isProtectedContextKey(key)) assertWellFormedProtectedKey(key, options.origin);
+    }
+  }
+  const mutatedKeys = [.../* @__PURE__ */ new Set([...setEntries.map(([key]) => key), ...unsetKeys])];
+  if (!Object.isExtensible(context)) {
+    const unsetSet = new Set(unsetKeys);
+    const added = mutatedKeys.filter((key) => !Object.hasOwn(context, key) || unsetSet.has(key));
+    if (added.length > 0) {
+      throw new ProtectedContextViolation(
+        "uncloneable_value",
+        added,
+        `${options.origin}: the storyboard context is not extensible, so key(s) ${added.join(", ")} cannot be written`
+      );
+    }
+  }
+  const locked = mutatedKeys.filter((key) => {
+    const descriptor = Object.getOwnPropertyDescriptor(context, key);
+    return descriptor !== void 0 && descriptor.configurable === false;
+  });
+  if (locked.length > 0) {
+    throw new ProtectedContextViolation(
+      "uncloneable_value",
+      locked,
+      `${options.origin}: context key(s) ${locked.join(", ")} are non-configurable and cannot be rewritten or removed`
+    );
+  }
+  const snapshots = /* @__PURE__ */ new Map();
+  for (const [key, value] of setEntries) {
+    if (!isProtectedContextKey(key)) continue;
+    let cloned;
+    try {
+      cloned = structuredClone(value);
+    } catch (error) {
+      throw new ProtectedContextViolation(
+        "uncloneable_value",
+        [key],
+        `${options.origin}: reserved context key "${key}" holds a value that cannot be detached (${error instanceof Error ? error.message : String(error)}); captures must be plain JSON-shaped data`
+      );
+    }
+    assertFreezable(cloned, key, options.origin);
+    snapshots.set(key, freezeDeep(cloned));
+  }
+  const provenanceSnapshots = /* @__PURE__ */ new Map();
+  for (const [key, entry] of provenanceEntries) {
+    if (!isProtectedContextKey(key)) continue;
+    let cloned;
+    try {
+      cloned = structuredClone(entry);
+    } catch (error) {
+      throw new ProtectedContextViolation(
+        "uncloneable_value",
+        [key],
+        `${options.origin}: provenance for reserved context key "${key}" cannot be detached (${error instanceof Error ? error.message : String(error)}); capture provenance must be plain JSON-shaped data`
+      );
+    }
+    assertFreezable(cloned, key, options.origin);
+    provenanceSnapshots.set(key, freezeDeep(cloned));
+  }
+  for (const key of unsetKeys) delete context[key];
+  for (const [key, value] of setEntries) {
+    Object.defineProperty(context, key, {
+      value: snapshots.has(key) ? snapshots.get(key) : value,
+      writable: true,
+      enumerable: true,
+      configurable: true
+    });
+    if (isProtectedContextKey(key)) state?.committed.add(key);
+  }
+  const sinks = options.sinks;
+  if (sinks?.provenance) {
+    for (const key of provenanceUnset) sinks.provenance.delete(key);
+    for (const [key, entry] of provenanceEntries) {
+      sinks.provenance.set(key, provenanceSnapshots.get(key) ?? entry);
+    }
+  }
+  if (sinks?.unavailable) {
+    for (const key of clearUnavailable) sinks.unavailable.delete(key);
+    for (const [key, reason] of unavailableEntries) sinks.unavailable.set(key, reason);
+  }
+}
+function assertWellFormedProtectedKey(key, location) {
+  if (PROTOTYPE_SENSITIVE_KEYS.has(key)) {
+    throw new ProtectedContextViolation(
+      "invalid_key",
+      [key],
+      `${location}: "${key}" is a prototype-sensitive key; rename it to anything other than __proto__, constructor or prototype`
+    );
+  }
+  if (!PROTECTED_KEY_PATTERN.test(key)) {
+    throw new ProtectedContextViolation(
+      "invalid_key",
+      [key],
+      `${location}: reserved capture key "${key}" must match ${PROTECTED_KEY_PATTERN.source} so whole-key $context.<key> substitution resolves it`
+    );
+  }
+}
+function assertFreezable(value, key, origin, seen = /* @__PURE__ */ new Set()) {
+  if (value === null || typeof value !== "object") return;
+  if (seen.has(value)) return;
+  seen.add(value);
+  if (Array.isArray(value)) {
+    for (const nested of value) assertFreezable(nested, key, origin, seen);
+    return;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) {
+    throw new ProtectedContextViolation(
+      "uncloneable_value",
+      [key],
+      `${origin}: reserved context key "${key}" holds a ${value.constructor?.name ?? "non-plain object"}, which Object.freeze cannot make immutable; captures must be plain JSON-shaped data`
+    );
+  }
+  for (const nested of Reflect.ownKeys(value)) {
+    assertFreezable(value[nested], key, origin, seen);
+  }
+}
+function freezeDeep(value) {
+  if (value === null || typeof value !== "object") return value;
+  if (Object.isFrozen(value)) return value;
+  Object.freeze(value);
+  for (const nested of Reflect.ownKeys(value)) {
+    freezeDeep(value[nested]);
+  }
+  return value;
+}
+function detachProtectedValue(value) {
+  if (value === null || typeof value !== "object") return value;
+  return structuredClone(value);
+}
+export {
+  PROTECTED_CONTEXT_PREFIX,
+  ProtectedContextViolation,
+  applyProtectedContextPatch,
+  assertWellFormedProtectedKey,
+  createProtectedContextWriter,
+  detachProtectedValue,
+  forwardProtectedContext,
+  freezeDeep,
+  isProtectedContextKey,
+  listProtectedContextKeys,
+  registerProtectedContext
+};

package/dist/lib/testing/storyboard/rejection-hints.js

@@ -128,7 +128,12 @@ function formatMessage(input) {
   const { contextKey, entry, rejectedValue, acceptedValues, requestField, currentTask } = input;
   const valueRepr = formatScalar(rejectedValue);
   const fieldRepr = requestField ? `\`${requestField}: ${valueRepr}\`` : `\`${valueRepr}\``;
-  const sourceDetail = entry.source_kind === "context_outputs" && entry.response_path ? `set by step \`${entry.source_step_id}\` from response path \`${entry.response_path}\`` : entry.source_task ? `set by step \`${entry.source_step_id}\` (convention extractor for \`${entry.source_task}\`)` : `set by step \`${entry.source_step_id}\``;
+  const sourceDetail = entry.source_kind === "fixture_preparation" ? (
+    // Naming a convention extractor here would point an implementor at
+    // machinery that was never involved; the useful pointer is the
+    // fixture handle whose pinned entity produced the value.
+    `pinned by fixture preparation${entry.fixture_handle ? ` for handle \`${entry.fixture_handle}\`` : ""}`
+  ) : entry.source_kind === "context_outputs" && entry.response_path ? `set by step \`${entry.source_step_id}\` from response path \`${entry.response_path}\`` : entry.source_task ? `set by step \`${entry.source_step_id}\` (convention extractor for \`${entry.source_task}\`)` : `set by step \`${entry.source_step_id}\``;
   const acceptedRepr = `[${acceptedValues.map(formatScalar).join(", ")}]`;
   const closing = buildClosing(entry.source_task, currentTask);
   return `Rejected ${fieldRepr} was extracted from \`$context.${contextKey}\` (${sourceDetail}). Seller's accepted values: ${acceptedRepr}. ` + closing;
@@ -142,14 +147,18 @@ function buildClosing(sourceTask, currentTask) {
   }
   return `Check that the seller's catalogs agree across tools.`;
 }
+const HINT_VALUE_MAX_CHARS = 200;
+function truncateForHint(rendered) {
+  return rendered.length <= HINT_VALUE_MAX_CHARS ? rendered : `${rendered.slice(0, HINT_VALUE_MAX_CHARS)}\u2026 (${rendered.length} chars)`;
+}
 function formatScalar(value) {
-  if (typeof value === "string") return value;
+  if (typeof value === "string") return truncateForHint(value);
   if (value === null) return "null";
   if (value === void 0) return "undefined";
   try {
-    return JSON.stringify(value);
+    return truncateForHint(JSON.stringify(value) ?? String(value));
   } catch {
-    return String(value);
+    return truncateForHint(String(value));
   }
 }
 function resolveErrorsList(data) {

package/dist/lib/testing/storyboard/rejection-hints.mjs

@@ -105,7 +105,12 @@ function formatMessage(input) {
   const { contextKey, entry, rejectedValue, acceptedValues, requestField, currentTask } = input;
   const valueRepr = formatScalar(rejectedValue);
   const fieldRepr = requestField ? `\`${requestField}: ${valueRepr}\`` : `\`${valueRepr}\``;
-  const sourceDetail = entry.source_kind === "context_outputs" && entry.response_path ? `set by step \`${entry.source_step_id}\` from response path \`${entry.response_path}\`` : entry.source_task ? `set by step \`${entry.source_step_id}\` (convention extractor for \`${entry.source_task}\`)` : `set by step \`${entry.source_step_id}\``;
+  const sourceDetail = entry.source_kind === "fixture_preparation" ? (
+    // Naming a convention extractor here would point an implementor at
+    // machinery that was never involved; the useful pointer is the
+    // fixture handle whose pinned entity produced the value.
+    `pinned by fixture preparation${entry.fixture_handle ? ` for handle \`${entry.fixture_handle}\`` : ""}`
+  ) : entry.source_kind === "context_outputs" && entry.response_path ? `set by step \`${entry.source_step_id}\` from response path \`${entry.response_path}\`` : entry.source_task ? `set by step \`${entry.source_step_id}\` (convention extractor for \`${entry.source_task}\`)` : `set by step \`${entry.source_step_id}\``;
   const acceptedRepr = `[${acceptedValues.map(formatScalar).join(", ")}]`;
   const closing = buildClosing(entry.source_task, currentTask);
   return `Rejected ${fieldRepr} was extracted from \`$context.${contextKey}\` (${sourceDetail}). Seller's accepted values: ${acceptedRepr}. ` + closing;
@@ -119,14 +124,18 @@ function buildClosing(sourceTask, currentTask) {
   }
   return `Check that the seller's catalogs agree across tools.`;
 }
+const HINT_VALUE_MAX_CHARS = 200;
+function truncateForHint(rendered) {
+  return rendered.length <= HINT_VALUE_MAX_CHARS ? rendered : `${rendered.slice(0, HINT_VALUE_MAX_CHARS)}\u2026 (${rendered.length} chars)`;
+}
 function formatScalar(value) {
-  if (typeof value === "string") return value;
+  if (typeof value === "string") return truncateForHint(value);
   if (value === null) return "null";
   if (value === void 0) return "undefined";
   try {
-    return JSON.stringify(value);
+    return truncateForHint(JSON.stringify(value) ?? String(value));
   } catch {
-    return String(value);
+    return truncateForHint(String(value));
   }
 }
 function resolveErrorsList(data) {

package/dist/lib/testing/storyboard/runner.d.mts

@@ -5,6 +5,7 @@
  * - runStoryboard(): run all phases/steps sequentially
  * - runStoryboardStep(): run a single step (stateless, LLM-friendly)
  */
+import { PreparedStoryboardFixtures } from './prepared-fixtures.mjs';
 import type { RequiresCapabilityPredicate, Storyboard, StoryboardStep, StoryboardContext, StoryboardRunOptions, StoryboardResult, StoryboardPhaseResult, StoryboardStepResult, StoryboardStepPreview, StrictValidationSummary, SchemaValidationError } from './types.mjs';
 import type { TestStepResult } from '../types.mjs';
 export declare function applyStoryboardVersionOptions(storyboard: Storyboard, options: StoryboardRunOptions): StoryboardRunOptions;
@@ -161,6 +162,29 @@ export declare function signingCoverageUnverified(steps: readonly SigningCoverag
  * called from `runStoryboard` when discovery throws.
  */
 export declare function buildDiscoveryFailedResult(agentUrls: string[], storyboard: Storyboard, discoveryStep: TestStepResult): StoryboardResult;
+/**
+ * Resolve a storyboard's fixture graph once and return reusable, immutable
+ * prepared state.
+ *
+ * This is the public form of what `executeStoryboardPass` already does
+ * internally, promoted so the standalone step runner and hosted step routes
+ * stop falling back to literal authored handles. The returned state carries
+ * the pinned seller identities, the declaration-local captures from the
+ * SAME selected graph, the retained collection witnesses, the resolution
+ * evidence, any coverage gaps, and the terminal preparation disposition.
+ *
+ * The state is deliberately process-local: its trust is a live object
+ * identity, and its credential fingerprint is keyed by a per-process random
+ * HMAC key. It will not survive serialization, and it is not meant to — a
+ * frozen JSON snapshot carries no evidence that its grant is still live.
+ * Hosted multi-process reuse belongs behind an authenticated reference
+ * lookup with the authorizer hook. See `docs/guides/COLLECTION-FIXTURE-FOUNDATION.md`.
+ *
+ * A failed or unsatisfied preparation is returned, not thrown: the terminal
+ * disposition is part of the evidence and must be carried forward verbatim
+ * so a retry cannot hide it behind a freshly discovered alternative.
+ */
+export declare function prepareStoryboardFixtures(agentUrl: string | string[], storyboard: Storyboard, options?: StoryboardRunOptions): Promise<PreparedStoryboardFixtures>;
 /**
  * Walk every response_schema validation and aggregate the strict/lenient
  * delta. Always returns a summary; `observable: false` signals "run had