@adcp/sdk 16.2.0 → 16.3.0

package/dist/lib/testing/storyboard/prepared-fixtures.d.mts

@@ -0,0 +1,471 @@
+/**
+ * Reusable fixture-preparation state, its binding identity, and the
+ * every-lookup authorization gate.
+ *
+ * `prepareStoryboardFixtures` (in `runner.ts`) resolves a storyboard's
+ * fixture graph once and returns a `PreparedStoryboardFixtures`. Both the
+ * full runner and the standalone step runner can then execute against that
+ * pinned selection instead of re-discovering — or, in the standalone case
+ * today, silently transmitting literal authored handles.
+ *
+ * Two boundaries live here, and they are deliberately independent:
+ *
+ * **1. Binding coherence (portable, SDK-owned).** Prepared state is pinned
+ * to the storyboard content, the resolved seller route, the exact schema
+ * artifact in use, the contract version, the account/sandbox scope, a
+ * nonsecret credential identity, and the run id. Reuse under a different
+ * binding is a terminal failure, not a silent re-pick: retrying must not be
+ * able to launder a failed preparation into a freshly discovered alternative.
+ *
+ * **2. Authorization (hosted, NOT implemented here).** Resolving a principal
+ * from a session, storing grants, and revoking them are host duties. This
+ * module mandates the integration shape — an authorizer consulted on *every*
+ * lookup, before any snapshot is disclosed and before any dependent wire
+ * call — and fails closed when a reference is supplied without one. It does
+ * not implement a grant service, and nothing here should be read as claiming
+ * that an SDK-local check substitutes for one.
+ *
+ * ## What is deliberately NOT authority
+ *
+ * An opaque or sealed reference, a successful decryption, a caller-supplied
+ * `context_provenance` map, a principal string in caller JSON, a
+ * seller-authored authorization boolean, or a structurally identical frozen
+ * object are all reachable from untrusted input. None of them produce the
+ * runtime capability this module requires. The capability is object identity
+ * held in a module-private `WeakSet`: a `structuredClone`, a JSON round-trip,
+ * or a hand-built look-alike is rejected, which is what stops "I have state
+ * that looks prepared" from becoming "I am authorized".
+ *
+ * ## Process scope, stated plainly
+ *
+ * Because the capability is a live object identity and the credential
+ * fingerprint is keyed by a per-process random HMAC key, prepared state is
+ * **not portable across processes**. That is a deliberate limit, not an
+ * oversight: a frozen JSON snapshot that survived a process boundary carries
+ * no evidence that its grant is still live. Multi-process and durable reuse
+ * require authenticated reconstruction, or a host-side reference lookup that
+ * re-checks live scope — see `docs/guides/COLLECTION-FIXTURE-FOUNDATION.md`.
+ */
+import type { CollectionSelectionWitness } from './collection-selection.mjs';
+import type { FixtureBindingRegistry } from './fixture-resolution.mjs';
+import type { ContextProvenanceEntry, FixtureResolutionCoverageGap, FixtureResolutionRecord, Storyboard, StoryboardPhaseResult } from './types.mjs';
+/**
+ * Version of the prepared-state contract itself. A prepared state produced
+ * under one contract version is never consumed under another: an older
+ * runner must fail closed rather than reinterpret bindings it does not
+ * understand.
+ */
+export declare const PREPARED_FIXTURES_CONTRACT_VERSION = "1.0.0";
+/** Identity of the schema artifact validation resolved against. */
+export interface PreparedSchemaArtifact {
+    /** AdCP version the run pinned. */
+    adcp_version: string;
+    /** Bundle key the loader resolved that version to. */
+    bundle_key: string;
+    /** True when a caller-supplied external bundle was authoritative. */
+    external: boolean;
+    /**
+     * Digest over the bundle tree's file inventory (relative path, byte size,
+     * mtime) at the moment that root was FIRST resolved in this process.
+     *
+     * It detects reuse against a different resolved bundle root — the case a
+     * `withExternalSchemaRoot` scope or a version change produces. It does NOT
+     * detect in-place mutation of a root already observed: the digest is
+     * cached per root for the process lifetime, so prepared and current
+     * bindings would both read the same cached value. It is also not a
+     * publisher-signed content digest. Treat it as bundle identity at first
+     * observation, nothing stronger.
+     */
+    digest: string;
+}
+/** Nonsecret binding identity. Never contains a credential. */
+export interface PreparedFixtureBinding {
+    storyboard_id: string;
+    /** SHA-256 over the canonicalized storyboard document. */
+    storyboard_digest: string;
+    /**
+     * Resolved seller route(s), with credential material removed.
+     *
+     * A route URL can carry userinfo or query-string tokens, and this binding
+     * is handed to the host authorizer (which a host will reasonably log for
+     * audit) and exposed on the public accessor. The raw form must not
+     * survive. Diff fidelity is preserved by `agent_route_fingerprint`, so two
+     * routes differing only in credentials still refuse reuse.
+     */
+    agent_urls: string[];
+    /**
+     * The ONE route preparation actually contacted, positionally.
+     *
+     * `agent_urls` is sorted and `agent_route_fingerprint` sorts by key, so
+     * neither records which of several routes the graph was pinned against.
+     * Diffed, so a state pinned from one seller cannot be reused by a run
+     * that would dispatch its pinned entities to another.
+     */
+    fixture_agent_url: string;
+    /** Keyed fingerprint over the RAW routes, so redaction cannot merge two. */
+    agent_route_fingerprint: string;
+    schema_artifact: PreparedSchemaArtifact;
+    contract_version: string;
+    /**
+     * Resolved account scope the graph was prepared under, taken from the same
+     * `resolveAccount` the discovery call uses, so a run that switches account
+     * cannot inherit another account's pinned catalog.
+     *
+     * Today `resolveAccount` derives `operator` from `brand.domain`, so this
+     * is effectively the brand domain — one dimension, not two. Note also that
+     * an unbranded run falls back to the SDK's default brand, which means all
+     * unbranded runs share one scope. Multi-tenant hosts must not rely on this
+     * field alone for isolation; that is what the authorizer is for.
+     */
+    account_scope: string;
+    /**
+     * The brand the graph was DISCOVERED under, canonicalized.
+     *
+     * Separate from `account_scope` because discovery resolves it separately:
+     * `context.brand` wins over the account's brand, which wins over the
+     * SDK default. A graph pinned against one advertiser's catalog must not be
+     * reused under another's, and the authorizer needs a field it can refuse
+     * on rather than two byte-identical payloads.
+     */
+    brand_scope: string;
+    /**
+     * The account the STEP's request will actually carry, when the step
+     * authors one that overrides the context account.
+     *
+     * `resolveMediaBuyAccount` lets an authored `sample_request.account` with
+     * an `account_id` or `operator` win over `context.account`, so
+     * `account_scope` alone can describe an account the request never uses.
+     * Absent when the step authors no overriding identity — then
+     * `account_scope` is the effective one.
+     *
+     * NOT diffed, for the same reason `step_credential_fingerprint` is not:
+     * it is per-step, so a preparation (which has no step) would mismatch
+     * every step that sets it. It needs no diff to be safe — an authored
+     * account lives in the storyboard body, which `storyboard_digest`
+     * already pins. It is here so the authorizer is told the truth about
+     * which account the call is about to transact under.
+     */
+    request_account_scope?: string;
+    /** Sandbox flag in scope. */
+    sandbox: boolean;
+    /**
+     * Caller-declared nonsecret principal. Supplied via
+     * `options.prepared_fixtures_principal`; absent when the caller did not
+     * declare one, which a host authorizer may itself choose to refuse.
+     */
+    principal?: string;
+    /**
+     * HMAC fingerprint of the transport credential under a per-process random
+     * key. It detects a credential change between preparation and reuse while
+     * disclosing nothing about the credential and remaining useless outside
+     * this process. Never a token, never reversible, never an authorization.
+     */
+    credential_fingerprint: string;
+    /**
+     * Effective credential for the STEP about to execute, including its own
+     * `auth` directive. Present only when the step in scope DECLARES its own
+     * `auth`; a step that inherits the run credential produces no field, so an
+     * absent value means "inherits", not "no step".
+     *
+     * Deliberately NOT part of `BINDING_FIELDS`: preparation has no step, so
+     * diffing it would refuse every legitimate reuse. It exists so the host
+     * authorizer can see what the step will actually dispatch with — the
+     * `security_baseline` probes deliberately dispatch unauthenticated or
+     * with an invalid key — and refuse on its own terms. Like the run
+     * fingerprint it is an HMAC under a per-process key, never the credential.
+     */
+    step_credential_fingerprint?: string;
+    /**
+     * Nonsecret companion to `step_credential_fingerprint`: whether the step
+     * dispatches with NO credential, with one it authored itself, or with the
+     * credential of the specialism route it is dispatched to. The fingerprint
+     * is keyed per process, so a host can see that it changed but not what it
+     * is; this is the value an authorizer can branch on.
+     */
+    step_auth_kind?: 'none' | 'override' | 'routed';
+    /**
+     * `<specialism key>@<redacted url>` the step actually dispatches to, when
+     * the run uses per-specialism routing.
+     *
+     * `agent_urls` is the sorted set of EVERY route in the run and says
+     * nothing about which one this step uses, so an authorizer scoping a
+     * grant to one seller had no field to refuse on. Also NOT diffed —
+     * preparation has no step.
+     */
+    step_route?: string;
+    /** Identity of the preparation run. */
+    run_id: string;
+}
+/**
+ * Why a lookup was refused. Surfaces verbatim as the `actual` of the
+ * `prepared_fixtures_authorization` validation, so this union IS the
+ * output contract a report consumer can switch on.
+ */
+export type PreparedFixturesRefusalCode = 'untrusted_state' | 'binding_mismatch' | 'authorizer_required' | 'authorizer_denied' | 'contract_version_mismatch'
+/**
+ * Caller-supplied `context`, `context_provenance` or
+ * `response_derived_not_applicable_context_keys` carried a reserved or
+ * prototype-sensitive key. Raised by the runner's pre-contact screen
+ * rather than by `resolvePreparedFixtures`, but it grades through the
+ * same validation, so a consumer typing on this union would otherwise
+ * meet a value the union does not admit.
+ */
+ | 'unauthorized_metadata';
+export interface PreparedFixturesRefusal {
+    code: PreparedFixturesRefusalCode;
+    detail: string;
+}
+/** Context handed to the host authorizer on every lookup. */
+export interface PreparedFixturesLookup {
+    /** Nonsecret binding recorded at preparation time. */
+    binding: PreparedFixtureBinding;
+    /** Nonsecret binding observed right now, after routing and auth overrides. */
+    current: PreparedFixtureBinding;
+    /** Storyboard step about to execute, when the lookup is per-step. */
+    step_id?: string;
+    /**
+     * Which gate asked.
+     *
+     * A run makes one `run` lookup, one `pass` lookup per pass, and one `step`
+     * lookup per step. A host implementing "every lookup is a fresh grant use"
+     * literally — consume-once token, nonce, strict counter — needs to tell
+     * them apart rather than seeing byte-identical payloads.
+     */
+    gate?: 'run' | 'pass' | 'step';
+    /** Opaque reference the caller presented, when reuse came through one. */
+    reference?: string;
+}
+/**
+ * A host authorizer's answer. `authorized` must be literally `true`.
+ *
+ * **`detail` is echoed to the caller** when the refusal came from DIRECT
+ * state — it is the only specific diagnostic a legitimate operator gets,
+ * which is why it is not swallowed. It is your text, so keep
+ * infrastructure addresses, scoped keys and credential material out of
+ * it. A refusal that came through an opaque REFERENCE never echoes it:
+ * a denial reading "not yours" would confirm the reference existed.
+ */
+export type PreparedFixturesDecision = {
+    authorized: true;
+} | {
+    authorized: false;
+    detail: string;
+};
+/**
+ * Host-supplied authorization resolver, consulted on EVERY lookup.
+ *
+ * Implementations must resolve the principal/tenant/org and run from trusted
+ * server session state (never from the request body), re-check the current
+ * grant, revocation and expiry, and re-check effective per-step credential
+ * scope after any routing or auth override. A decision made at preparation
+ * time is not reusable: a grant revoked after a successful prior step must
+ * fail the next one.
+ */
+export type PreparedFixturesAuthorizer = (lookup: PreparedFixturesLookup) => PreparedFixturesDecision | Promise<PreparedFixturesDecision>;
+/**
+ * A reference to prepared state held in the host's authenticated run scope.
+ *
+ * The SDK cannot resolve one on its own — it has no session, no tenant and
+ * no grant store — so a reference without a `resolve` hook fails closed.
+ */
+export interface PreparedFixturesReference {
+    /** Opaque host-owned identifier. Not authority by itself. */
+    ref: string;
+    /**
+     * Host resolver returning the in-process prepared state for `ref`. Invoked
+     * on every lookup, so the host sees each use and can refuse a revoked one.
+     */
+    resolve: (ref: string) => PreparedStoryboardFixtures | undefined | Promise<PreparedStoryboardFixtures | undefined>;
+}
+/** Per-handle state the resolver pinned, exposed read-only. */
+export interface PreparedFixtureSelection {
+    handle: string;
+    fixture_type: FixtureResolutionRecord['fixture_type'];
+    product_handle?: string;
+    seller_ids: NonNullable<FixtureResolutionRecord['seller_ids']>;
+}
+export interface PreparedStoryboardFixturesInit {
+    binding: PreparedFixtureBinding;
+    bindings?: FixtureBindingRegistry;
+    resolutions: FixtureResolutionRecord[];
+    coverageGaps: FixtureResolutionCoverageGap[];
+    captures: Record<string, unknown>;
+    captureProvenance: Record<string, ContextProvenanceEntry>;
+    witnesses: Record<string, CollectionSelectionWitness>;
+    /** Terminal preparation outcome, carried forward verbatim on reuse. */
+    disposition: PreparedFixturesDisposition;
+    phase?: StoryboardPhaseResult;
+}
+export type PreparedFixturesDisposition = 
+/** Every declared fixture resolved; captures are published. */
+{
+    status: 'resolved';
+}
+/** A declared strategy ladder exhausted with no binding. */
+ | {
+    status: 'unsatisfied';
+    detail: string;
+}
+/** Discovery, schema validation or setup failed. Terminal. */
+ | {
+    status: 'failed';
+    detail: string;
+}
+/** The agent cannot be graded for this storyboard's fixtures. */
+ | {
+    status: 'unsupported';
+    detail: string;
+};
+/**
+ * Immutable prepared fixture state.
+ *
+ * Instances are produced only by `prepareStoryboardFixtures`. The public
+ * accessors (`binding`, `disposition`, `resolutions`, `coverageGaps`,
+ * `selections`, `captures`, `captureProvenance`, `witnesses`) hand back
+ * detached clones, so a consumer that mutates what it reads cannot reach the
+ * pinned selection. `phase` is cloned on ingestion as well as on read, so
+ * the object the constructor was handed is not the canonical copy either.
+ */
+export declare class PreparedStoryboardFixtures {
+    #private;
+    /** Nonsecret binding identity. Detached copy. */
+    get binding(): PreparedFixtureBinding;
+    get disposition(): PreparedFixturesDisposition;
+    /** Machine-readable per-handle resolution evidence. Detached copy. */
+    get resolutions(): FixtureResolutionRecord[];
+    /** Coverage gaps observed during preparation. Detached copy. */
+    get coverageGaps(): FixtureResolutionCoverageGap[];
+    /** Pinned seller identities per handle. Detached copy. */
+    get selections(): PreparedFixtureSelection[];
+    /** Reserved-namespace captures. Detached copy. */
+    get captures(): Record<string, unknown>;
+    /** Capture provenance. Detached copy. */
+    get captureProvenance(): Record<string, ContextProvenanceEntry>;
+    /** Retained collection witnesses per handle. Detached copy. */
+    get witnesses(): Record<string, CollectionSelectionWitness>;
+    /**
+     * 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(): StoryboardPhaseResult | undefined;
+}
+/**
+ * Pair prepared state with its authorizer, so neither can be supplied
+ * without the other.
+ *
+ * `prepared_fixtures` and `prepared_fixtures_authorizer` are both optional
+ * on `StoryboardRunOptions`, which means the one thing the guide calls a
+ * requirement rather than optional hardening compiles clean when omitted —
+ * every hosted integrator discovered it by running it. Spread the result
+ * and the compiler asks for the authorizer:
+ *
+ * ```ts
+ * const result = await runStoryboardStep(agentUrl, storyboard, stepId, {
+ *   ...options,
+ *   ...withPreparedFixtures(prepared, authorize),
+ * });
+ * ```
+ *
+ * The raw fields still work; this is ergonomics, not enforcement. The
+ * enforcement is the fail-closed refusal in `resolvePreparedFixtures`.
+ */
+export declare function withPreparedFixtures(state: PreparedStoryboardFixtures | PreparedFixturesReference, authorizer: PreparedFixturesAuthorizer): {
+    prepared_fixtures: PreparedStoryboardFixtures | PreparedFixturesReference;
+    prepared_fixtures_authorizer: PreparedFixturesAuthorizer;
+};
+/**
+ * True only for a state produced by this process's
+ * `prepareStoryboardFixtures`. A JSON-rehydrated copy, a `structuredClone`,
+ * a hand-built object with the same public shape, and a direct `new` call
+ * all return false.
+ */
+export declare function isTrustedPreparedFixtures(value: unknown): value is PreparedStoryboardFixtures;
+/**
+ * SHA-256 over the canonicalized storyboard document.
+ *
+ * Deliberately NOT memoized by object identity. A `Storyboard` is a mutable
+ * plain object, and caching its digest would preserve the authorized value
+ * after a later edit to a request or a fixture declaration — defeating the
+ * exact detection this field exists for. The cost is ~1.5 ms on a large
+ * storyboard, paid per lookup, which is negligible against wire time and
+ * nowhere near worth a stale integrity check.
+ */
+export declare function digestStoryboard(storyboard: Storyboard): string;
+/** Resolve the schema artifact identity currently in effect. */
+export declare function resolveSchemaArtifact(adcpVersion?: string): PreparedSchemaArtifact;
+export interface BuildPreparedBindingInput {
+    storyboard: Storyboard;
+    agentUrls: string[];
+    adcpVersion?: string;
+    accountScope: string;
+    brandScope: string;
+    /** Account the step's own request authors, when it overrides the context. */
+    requestAccountScope?: string;
+    /** `[specialism key, url]` pairs, when the run uses per-specialism routing. */
+    agentRouteMap?: Array<[string, string]>;
+    sandbox: boolean;
+    /** Effective step credential, when a step is in scope. */
+    stepCredential?: string;
+    /** Whether that step drops the credential entirely, overrides it, or inherits a route's. */
+    stepAuthKind?: 'none' | 'override' | 'routed';
+    /** `<specialism key>@<redacted url>` this step dispatches to, when routed. */
+    stepRoute?: string;
+    principal?: string;
+    credential: string;
+    runId?: string;
+}
+export declare function buildPreparedBinding(input: BuildPreparedBindingInput): PreparedFixtureBinding;
+/**
+ * Compare a prepared binding against the binding observed right now.
+ *
+ * `run_id` is deliberately excluded: it identifies the preparation, and the
+ * whole point of reuse is that later steps share it. Everything else must
+ * match exactly — a different route, account, sandbox flag, schema artifact,
+ * credential or storyboard body means the pinned graph describes a different
+ * world than the one about to be called.
+ */
+export declare function diffPreparedBinding(prepared: PreparedFixtureBinding, current: PreparedFixtureBinding): string[];
+export interface ResolvePreparedFixturesInput {
+    /** Direct in-process state, or a host reference. */
+    supplied: PreparedStoryboardFixtures | PreparedFixturesReference | undefined;
+    /** Binding observed now, after routing and per-step auth overrides. */
+    current: PreparedFixtureBinding;
+    /** Host authorizer. REQUIRED for any reuse; absence fails closed. */
+    authorizer?: PreparedFixturesAuthorizer;
+    /** Step about to execute, for per-step authorization. */
+    stepId?: string;
+    /** Which gate is asking. */
+    gate?: 'run' | 'pass' | 'step';
+}
+export type ResolvePreparedFixturesResult = {
+    ok: true;
+    state: PreparedStoryboardFixtures;
+} | {
+    ok: false;
+    refusal: PreparedFixturesRefusal;
+};
+/**
+ * Resolve and authorize prepared state for ONE lookup.
+ *
+ * Called before every step that could consume prepared state — not once at
+ * run start. Ordering matters and is load-bearing:
+ *
+ *   1. Establish that the object is genuinely this process's prepared state.
+ *   2. Ask the host authorizer, which re-checks live grant and revocation.
+ *   3. Only then re-check binding coherence against the CURRENT effective
+ *      route, account, sandbox, schema artifact and credential.
+ *
+ * The authorizer runs BEFORE the binding diff, not after. In the hosted
+ * reference flow the host resolver answers for any reference it holds, so
+ * diffing first would answer an unauthorized caller's enumerated reference
+ * with a mismatch report describing someone else's principal, routes,
+ * account and credential fingerprint — and turn the fingerprint into a
+ * credential-confirmation oracle. For the same reason the refusal detail
+ * names only the FIELDS that differ, never their values.
+ *
+ * Only after all three does any snapshot become readable. A refusal returns
+ * before the caller can read captures and before any dependent wire call.
+ */
+export declare function resolvePreparedFixtures(input: ResolvePreparedFixturesInput): Promise<ResolvePreparedFixturesResult | undefined>;