@adcp/sdk 17.0.0-beta.0 → 17.0.0-beta.2

package/dist/lib/testing/storyboard/runner.mjs

@@ -726,7 +726,7 @@ function remapTaskCompletionOutputs(outputs) {
     return o;
   });
 }
-async function resolveTaskCompletionOutputs(taskResult, outputs, client, webhookReceiver, originatingTaskName) {
+async function resolveTaskCompletionOutputs(taskResult, outputs, client, webhookReceiver, originatingTaskName, responseAdcpVersion) {
   const hasTaskCompletionPath = outputs.some(
     (o) => typeof o.path === "string" && o.path.startsWith(TASK_COMPLETION_PATH_PREFIX)
   );
@@ -779,7 +779,10 @@ async function resolveTaskCompletionOutputs(taskResult, outputs, client, webhook
     if (winner.kind === "poll") {
       const polled = winner.result;
       if (polled.success === false) return { attempted: true, taskFailed: true };
-      return { attempted: true, data: normalizeTaskCompletionData(polled.data, originatingTaskName) };
+      return {
+        attempted: true,
+        data: normalizeTaskCompletionData(polled.data, originatingTaskName, responseAdcpVersion)
+      };
     }
     const waitResult = winner.result;
     if (waitResult.timed_out) {
@@ -787,7 +790,10 @@ async function resolveTaskCompletionOutputs(taskResult, outputs, client, webhook
     }
     const webhookBody = waitResult.webhook.body;
     if (webhookBody?.status === "completed") {
-      return { attempted: true, data: normalizeTaskCompletionData(webhookBody.result, originatingTaskName) };
+      return {
+        attempted: true,
+        data: normalizeTaskCompletionData(webhookBody.result, originatingTaskName, responseAdcpVersion)
+      };
     }
     return { attempted: true, taskFailed: true };
   } catch {
@@ -796,18 +802,19 @@ async function resolveTaskCompletionOutputs(taskResult, outputs, client, webhook
     if (timer) clearTimeout(timer);
   }
 }
-function normalizeTaskCompletionData(data, taskName) {
+function normalizeTaskCompletionData(data, taskName, adcpVersion) {
   if (data == null || typeof data !== "object" || Array.isArray(data)) return data;
   const original = data;
-  const compat = injectLegacyEnvelopeStatus(original, { toolName: taskName });
+  const compatOptions = { toolName: taskName, adcpVersion };
+  const compat = injectLegacyEnvelopeStatus(original, compatOptions);
   if (!("status" in original) && "status" in compat) {
     const { status: _status, ...rest } = compat;
-    return normalizeLegacyMediaBuyStatusForReturn(rest, { toolName: taskName });
+    return normalizeLegacyMediaBuyStatusForReturn(rest, compatOptions);
   }
   if ((taskName === "create_media_buy" || taskName === "update_media_buy") && typeof original.status === "string" && compat.status === "completed" && typeof compat.media_buy_status === "string") {
-    return normalizeLegacyMediaBuyStatusForReturn({ ...compat, status: original.status }, { toolName: taskName });
+    return normalizeLegacyMediaBuyStatusForReturn({ ...compat, status: original.status }, compatOptions);
   }
-  return normalizeLegacyMediaBuyStatusForReturn(compat, { toolName: taskName });
+  return normalizeLegacyMediaBuyStatusForReturn(compat, compatOptions);
 }
 function readEnvIntOrDefault(value, fallback) {
   if (!value) return fallback;
@@ -1945,9 +1952,10 @@ async function prepareStoryboardFixturesBody(agentUrl, storyboard, options) {
     options = snapshotPreparationOptions(options);
   }
   const callerOwnsClients = hasTestClientScope();
-  const preparationOptions = resolvePreparationRouteOptions(agentUrls[0], options);
+  const runOptions = options;
+  const preparationOptions = resolvePreparationRouteOptions(agentUrls[0], runOptions);
   const resolution = getOrCreateClientResolution(agentUrls[0], preparationOptions);
-  const client = resolution.client;
+  let client = resolution.client;
   const finishPreparation = (seeding, disposition) => {
     if (!scopeStillMatches()) {
       return refusePreparation(driftRefusal, seeding ?? void 0);
@@ -1957,6 +1965,45 @@ async function prepareStoryboardFixturesBody(agentUrl, storyboard, options) {
   options = preparationOptions;
   try {
     let profile = options._profile;
+    let discoveryStep;
+    let routingContext;
+    const failDiscovery = (step, failedProfile) => {
+      const failed = buildDiscoveryFailedResult(agentUrls, storyboard, step, failedProfile);
+      return finishPreparation(
+        { phase: failed.phases[0], allPassed: false, passedCount: 0, failedCount: 1 },
+        { status: "failed", detail: step.error ?? "agent discovery failed before fixture preparation" }
+      );
+    };
+    if (runOptions.agents && (storyboardCapabilityPredicates(storyboard).length > 0 || storyboard.required_tools?.length || storyboard.required_any_of_tools?.length)) {
+      try {
+        validateAgentsMap(agentUrl, storyboard, runOptions);
+        routingContext = await buildRoutingContext(storyboard, { ...runOptions, discovery_resilient: false });
+      } catch (error) {
+        const failedStep = error instanceof DiscoveryFailure ? error.step : void 0;
+        return await failDiscovery({
+          ...failedStep,
+          step: failedStep?.step ?? "Discover preparation topology",
+          passed: false,
+          duration_ms: failedStep?.duration_ms ?? 0,
+          error: redactOAuthUrlsInText(
+            error instanceof DiscoveryFailure ? `Discovery failed for agent "${error.agentKey}" (${redactOAuthUrlForOutput(error.url)}): ${error.underlying}` : error instanceof Error ? error.message : String(error)
+          )
+        });
+      }
+      for (const routeProfile of routingContext.profiles.values()) {
+        const failure = describeProfileDiscoveryFailure(
+          routeProfile,
+          runOptions._requireValidCapabilityEvidence === true,
+          runOptions._allowCapabilityDiagnostic === true
+        );
+        if (failure) return await failDiscovery(failure, routeProfile);
+      }
+      const firstKey = Object.keys(runOptions.agents)[0];
+      profile = routingContext.profiles.get(firstKey);
+      client = routingContext.clients.get(firstKey);
+      discoveryStep = routingContext.discoverySteps?.get(firstKey);
+      options = { ...options, _profile: profile, agentTools: normalizeAgentToolNames(profile.tools) };
+    }
     const suppliedFailure = profile && describeProfileDiscoveryFailure(
       profile,
       options._requireValidCapabilityEvidence === true,
@@ -1969,8 +2016,9 @@ async function prepareStoryboardFixturesBody(agentUrl, storyboard, options) {
         { status: "failed", detail: suppliedFailure.error ?? "agent discovery failed" }
       );
     }
-    if (!profile && !resolution.reusedShared) {
+    if (!profile) {
       const discovered = await getOrDiscoverStoryboardProfile(client, options);
+      discoveryStep = discovered.evidence ?? discovered.step;
       if (discovered.step.passed === false) {
         const failed = buildDiscoveryFailedResult(agentUrls, storyboard, discovered.step, discovered.profile);
         return await finishPreparation(
@@ -1991,6 +2039,80 @@ async function prepareStoryboardFixturesBody(agentUrl, storyboard, options) {
       };
     }
     if (!scopeStillMatches()) return await refusePreparation(driftRefusal);
+    let capabilityUnmet;
+    const applicabilityTools = routingContext ? [...new Set([...routingContext.profiles.values()].flatMap((p) => normalizeAgentToolNames(p.tools) ?? []))] : options.agentTools;
+    try {
+      if (routingContext && runOptions.agents) {
+        const dispatch = createRoutingDispatcher(routingContext, runOptions, runOptions.agents);
+        const defaultProfile = runOptions.default_agent ? routingContext.profiles.get(runOptions.default_agent) : void 0;
+        const rootDetails = storyboard.phases.flatMap(
+          (phase) => phase.steps.filter((step) => step.task !== VALIDATION_ONLY_TASK).map((step) => {
+            const selected = dispatch.nextFor(step);
+            const owner = runOptions.default_agent ? defaultProfile : selected.profile;
+            return evaluateStoryboardCapabilityGates(
+              storyboard,
+              owner,
+              normalizeAgentToolNames(owner?.tools),
+              runOptions.adcpVersion
+            );
+          })
+        );
+        capabilityUnmet = rootDetails.length > 0 && rootDetails.every((detail) => detail !== null) ? rootDetails[0] : null;
+      } else {
+        capabilityUnmet = evaluateStoryboardCapabilityGates(
+          storyboard,
+          profile,
+          options.agentTools,
+          options.adcpVersion
+        );
+      }
+    } catch (error) {
+      return await failDiscovery({
+        step: "Resolve preparation routes",
+        passed: false,
+        duration_ms: 0,
+        error: redactOAuthUrlsInText(error instanceof Error ? error.message : String(error))
+      });
+    }
+    const missingFamily = applicabilityTools && storyboard.required_any_of_tools?.find((family) => !hasAnyRequiredTool(family.tools, applicabilityTools));
+    const unmetDetail = capabilityUnmet ?? (missingFamily ? `missing_required_tool_family: needs ${missingFamily.tools.join(" or ")}` + (missingFamily.rationale ? ` (${missingFamily.rationale})` : "") : null) ?? (storyboard.required_tools?.length && applicabilityTools && !hasAnyRequiredTool(storyboard.required_tools, applicabilityTools) ? `agent does not advertise any of [${storyboard.required_tools.join(", ")}]` : null);
+    if (unmetDetail !== null) {
+      const observations = routingContext && runOptions.agents ? Object.entries(runOptions.agents).map(([key, entry]) => ({
+        key,
+        url: entry.url,
+        step: routingContext.discoverySteps?.get(key)
+      })) : [{ key: "discovery", url: agentUrls[0], step: discoveryStep }];
+      const steps = observations.map(({ key, url, step }) => ({
+        storyboard_id: storyboard.id,
+        phase_id: "discovery",
+        step_id: key,
+        title: step ? "Agent capability discovery" : "Supplied agent capability profile",
+        task: step?.task ?? "",
+        passed: true,
+        duration_ms: step?.duration_ms ?? 0,
+        validations: [],
+        context: {},
+        ...routingContext && { agent_url: redactOAuthUrlForOutput(url) },
+        extraction: step?.extraction ?? { path: "none" },
+        ...step?.request && { request: step.request },
+        ...step?.response_record && { response_record: step.response_record }
+      }));
+      return await finishPreparation(
+        {
+          phase: {
+            phase_id: "discovery",
+            phase_title: "Agent capability discovery",
+            passed: true,
+            duration_ms: steps.reduce((total, step) => total + step.duration_ms, 0),
+            steps
+          },
+          allPassed: true,
+          passedCount: steps.length,
+          failedCount: 0
+        },
+        { status: "unsupported", reason: "not_applicable", detail: unmetDetail }
+      );
+    }
     const context = createRunContext(storyboard, options).context;
     const seeding = await runControllerSeeding(client, storyboard, options, context);
     if (!seeding) {
@@ -5883,7 +6005,12 @@ async function executeStep(client, step, storyboardId, phaseId, context, allStep
   };
   const hasData = taskResult?.data !== void 0 && taskResult?.data !== null;
   if (passed && hasData && taskResult && !(effectiveStep.task === "sync_accounts" && request.dry_run === true)) {
-    const extracted = extractContextWithProvenance(effectiveStep.task, taskResult.data, step.id);
+    const extracted = extractContextWithProvenance(
+      effectiveStep.task,
+      taskResult.data,
+      step.id,
+      options._serverAdcpVersion ?? options.adcpVersion
+    );
     const conventionUnset = [];
     for (const group of extracted.clearGroups ?? []) {
       if (group.when && !group.when.values.includes(updatedContext[group.when.key])) continue;
@@ -5914,7 +6041,8 @@ async function executeStep(client, step, storyboardId, phaseId, context, allStep
       step.context_outputs,
       client,
       runState.webhookReceiver,
-      effectiveStep.task
+      effectiveStep.task,
+      options._serverAdcpVersion ?? options.adcpVersion
     );
     const extractionData = "data" in taskCompletionResolution ? taskCompletionResolution.data : hasData && taskResult ? taskResult.data : void 0;
     const remappedOutputs = remapTaskCompletionOutputs(step.context_outputs);

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

@@ -197,7 +197,7 @@ export interface UpstreamTrafficQueryResult {
  */
 export declare function runValidations(validations: StoryboardValidation[], context: ValidationContext): ValidationResult[];
 /** Capability semver emitted in run summaries and used for advisory expiry. */
-export declare const RUNNER_CAPABILITY_VERSION = "17.0.0-beta.0";
+export declare const RUNNER_CAPABILITY_VERSION = "17.0.0-beta.2";
 /** True when a failed validation contributes to the owning step's grade. */
 export declare function validationFailsStep(result: ValidationResult): boolean;
 /**

package/dist/lib/testing/storyboard/validations.d.ts

@@ -197,7 +197,7 @@ export interface UpstreamTrafficQueryResult {
  */
 export declare function runValidations(validations: StoryboardValidation[], context: ValidationContext): ValidationResult[];
 /** Capability semver emitted in run summaries and used for advisory expiry. */
-export declare const RUNNER_CAPABILITY_VERSION = "17.0.0-beta.0";
+export declare const RUNNER_CAPABILITY_VERSION = "17.0.0-beta.2";
 /** True when a failed validation contributes to the owning step's grade. */
 export declare function validationFailsStep(result: ValidationResult): boolean;
 /**

package/dist/lib/testing/storyboard/validations.js

@@ -295,8 +295,11 @@ function validateResponseSchemaForVersion(validation, ctx, taskResult) {
     return rest;
   })();
   const schema = import_response_schemas.TOOL_RESPONSE_SCHEMAS[taskName];
-  const dataForValidation = Array.isArray(dataWithoutMessage) ? dataWithoutMessage : (0, import_envelope_status_compat.injectLegacyEnvelopeStatus)(dataWithoutMessage, { toolName: taskName });
   const responseAdcpVersion = ctx.responseAdcpVersion ?? ctx.adcpVersion;
+  const dataForValidation = Array.isArray(dataWithoutMessage) ? dataWithoutMessage : (0, import_envelope_status_compat.injectLegacyEnvelopeStatus)(dataWithoutMessage, {
+    toolName: taskName,
+    adcpVersion: responseAdcpVersion
+  });
   const parseResult = schema?.safeParse(
     (0, import_response_schemas.prepareResponseForSchemaValidation)(taskName, dataForValidation, responseAdcpVersion)
   );

package/dist/lib/testing/storyboard/validations.mjs

@@ -276,8 +276,11 @@ function validateResponseSchemaForVersion(validation, ctx, taskResult) {
     return rest;
   })();
   const schema = TOOL_RESPONSE_SCHEMAS[taskName];
-  const dataForValidation = Array.isArray(dataWithoutMessage) ? dataWithoutMessage : injectLegacyEnvelopeStatus(dataWithoutMessage, { toolName: taskName });
   const responseAdcpVersion = ctx.responseAdcpVersion ?? ctx.adcpVersion;
+  const dataForValidation = Array.isArray(dataWithoutMessage) ? dataWithoutMessage : injectLegacyEnvelopeStatus(dataWithoutMessage, {
+    toolName: taskName,
+    adcpVersion: responseAdcpVersion
+  });
   const parseResult = schema?.safeParse(
     prepareResponseForSchemaValidation(taskName, dataForValidation, responseAdcpVersion)
   );

package/dist/lib/testing/test-controller.js

@@ -31,6 +31,7 @@ __export(test_controller_exports, {
 });
 module.exports = __toCommonJS(test_controller_exports);
 var import_client = require('./client.js');
+var import_errors = require('../errors/index.js');
 const TOOL_NAME = "comply_test_controller";
 const DEFAULT_SANDBOX_ACCOUNT = { brand: { domain: "test.example" }, operator: "test.example", sandbox: true };
 function buildAccount(options) {
@@ -84,6 +85,8 @@ async function detectController(client, profile, options) {
     }
     return { detected: false };
   } catch (error) {
+    if (error instanceof import_errors.ProtocolFeatureUnsupportedError && error.adcpError.details?.feature === "adcp_version")
+      throw error;
     (0, import_client.getLogger)().warn(
       { tool: TOOL_NAME, error: error instanceof Error ? error.message : String(error) },
       "comply_test_controller list_scenarios failed \u2014 treating as unavailable"

package/dist/lib/testing/test-controller.mjs

@@ -1,4 +1,5 @@
 import { getLogger, resolveAccount } from "./client.mjs";
+import { ProtocolFeatureUnsupportedError } from "../errors/index.mjs";
 const TOOL_NAME = "comply_test_controller";
 const DEFAULT_SANDBOX_ACCOUNT = { brand: { domain: "test.example" }, operator: "test.example", sandbox: true };
 function buildAccount(options) {
@@ -52,6 +53,8 @@ async function detectController(client, profile, options) {
     }
     return { detected: false };
   } catch (error) {
+    if (error instanceof ProtocolFeatureUnsupportedError && error.adcpError.details?.feature === "adcp_version")
+      throw error;
     getLogger().warn(
       { tool: TOOL_NAME, error: error instanceof Error ? error.message : String(error) },
       "comply_test_controller list_scenarios failed \u2014 treating as unavailable"

package/dist/lib/types/accept-proposal.d.ts

@@ -1101,26 +1101,22 @@ export type DayOfWeek = 'monday' | 'tuesday' | 'wednesday' | 'thursday' | 'frida
 export type DaypartTarget = {
     /**
      * Days of week this window applies to. Use multiple days for compact targeting (e.g., monday-friday in one object). For an overnight start_time/end_time window, each day names the day the window starts on.
-     *
-     * @minItems 1
      */
-    days: [DayOfWeek, ...DayOfWeek[]];
+    days: DayOfWeek[];
     /**
      * Start hour (inclusive), 0-23 in 24-hour format. 0 = midnight, 6 = 6:00am, 18 = 6:00pm. Whole-hour form: pair with end_hour; mutually exclusive with start_time and end_time.
+     * @minimum 0
+     * @maximum 23
+     * @format int
      */
-    start_hour?: number;
+    start_hour: number;
     /**
      * End hour (exclusive), 1-24 in 24-hour format. 10 = 10:00am, 24 = midnight. Must be greater than start_hour; whole-hour windows never cross midnight. Whole-hour form: pair with start_hour; mutually exclusive with start_time and end_time.
+     * @minimum 1
+     * @maximum 24
+     * @format int
      */
-    end_hour?: number;
-    /**
-     * Experimental in AdCP 3.3. Start of the window (inclusive) as a 24-hour HH:MM civil clock time on the entry's timezone clock, such as '19:30'. Use for windows that do not fall on whole hours (linear TV programme junctions, quarter-hour schedules). Pair with end_time; mutually exclusive with start_hour and end_hour. A window whose end_time is earlier than its start_time crosses midnight and belongs to the day it starts on. A product accepts only the finest time granularity it declares in overlay_support.daypart_targets.time_granularity; sellers MUST reject, never round, a clock time the product does not honor.
-     */
-    start_time?: string;
-    /**
-     * Experimental in AdCP 3.3. End of the window (exclusive) as a 24-hour HH:MM civil clock time, such as '23:00'. Pair with start_time; mutually exclusive with start_hour and end_hour. end_time earlier than start_time means the window crosses midnight and ends at end_time on the following civil day (for example, 22:00 to 02:00 runs from 22:00 on a listed day until 02:00 the next morning); '00:00' therefore ends the window at the midnight closing the start day. end_time MUST NOT equal start_time: a zero-length or full-day window is invalid, and a full day uses start_hour 0 with end_hour 24. Sellers MUST reject an equal pair with INVALID_REQUEST.
-     */
-    end_time?: string;
+    end_hour: number;
     /**
      * Civil-time clock used to evaluate this window. 'inventory_local' evaluates the hours in the seller-assigned local timezone of each inventory unit that can deliver the impression, such as a screen, venue, station, or publisher property; it never means the buyer, account, or server timezone. A concrete IANA timezone identifier (for example, 'America/New_York', 'CET', or 'UTC') evaluates one shared civil-time clock across the targeted inventory. Omission defaults to 'inventory_local'. Buyers that begin with a user or account preference MUST resolve it to a concrete IANA identifier before sending the daypart; 'user_timezone' and 'account_timezone' are not wire values. For each candidate delivery instant, convert the instant into this clock and compare its resulting local day and time of day with the half-open window: a skipped DST hour or interval has no matching instants, while both occurrences of a repeated hour or interval match. For an overnight start_time/end_time window, an instant matches when its local day is a listed day and its local time is at or after start_time, or when the local day before it is a listed day and its local time is before end_time. This delivery clock is independent of reporting_capabilities.timezone.
      */
@@ -1129,29 +1125,23 @@ export type DaypartTarget = {
      * Optional human-readable name for this time window (e.g., 'Morning Drive', 'Prime Time')
      */
     label?: string;
-} & ({} | {}) & {
+    start_time?: never;
+    end_time?: never;
+} | {
     /**
      * Days of week this window applies to. Use multiple days for compact targeting (e.g., monday-friday in one object). For an overnight start_time/end_time window, each day names the day the window starts on.
-     *
-     * @minItems 1
-     */
-    days: [DayOfWeek, ...DayOfWeek[]];
-    /**
-     * Start hour (inclusive), 0-23 in 24-hour format. 0 = midnight, 6 = 6:00am, 18 = 6:00pm. Whole-hour form: pair with end_hour; mutually exclusive with start_time and end_time.
-     */
-    start_hour?: number;
-    /**
-     * End hour (exclusive), 1-24 in 24-hour format. 10 = 10:00am, 24 = midnight. Must be greater than start_hour; whole-hour windows never cross midnight. Whole-hour form: pair with start_hour; mutually exclusive with start_time and end_time.
      */
-    end_hour?: number;
+    days: DayOfWeek[];
     /**
      * Experimental in AdCP 3.3. Start of the window (inclusive) as a 24-hour HH:MM civil clock time on the entry's timezone clock, such as '19:30'. Use for windows that do not fall on whole hours (linear TV programme junctions, quarter-hour schedules). Pair with end_time; mutually exclusive with start_hour and end_hour. A window whose end_time is earlier than its start_time crosses midnight and belongs to the day it starts on. A product accepts only the finest time granularity it declares in overlay_support.daypart_targets.time_granularity; sellers MUST reject, never round, a clock time the product does not honor.
+     * @pattern ^([01][0-9]|2[0-3]):[0-5][0-9]$
      */
-    start_time?: string;
+    start_time: string;
     /**
      * Experimental in AdCP 3.3. End of the window (exclusive) as a 24-hour HH:MM civil clock time, such as '23:00'. Pair with start_time; mutually exclusive with start_hour and end_hour. end_time earlier than start_time means the window crosses midnight and ends at end_time on the following civil day (for example, 22:00 to 02:00 runs from 22:00 on a listed day until 02:00 the next morning); '00:00' therefore ends the window at the midnight closing the start day. end_time MUST NOT equal start_time: a zero-length or full-day window is invalid, and a full day uses start_hour 0 with end_hour 24. Sellers MUST reject an equal pair with INVALID_REQUEST.
+     * @pattern ^([01][0-9]|2[0-3]):[0-5][0-9]$
      */
-    end_time?: string;
+    end_time: string;
     /**
      * Civil-time clock used to evaluate this window. 'inventory_local' evaluates the hours in the seller-assigned local timezone of each inventory unit that can deliver the impression, such as a screen, venue, station, or publisher property; it never means the buyer, account, or server timezone. A concrete IANA timezone identifier (for example, 'America/New_York', 'CET', or 'UTC') evaluates one shared civil-time clock across the targeted inventory. Omission defaults to 'inventory_local'. Buyers that begin with a user or account preference MUST resolve it to a concrete IANA identifier before sending the daypart; 'user_timezone' and 'account_timezone' are not wire values. For each candidate delivery instant, convert the instant into this clock and compare its resulting local day and time of day with the half-open window: a skipped DST hour or interval has no matching instants, while both occurrences of a repeated hour or interval match. For an overnight start_time/end_time window, an instant matches when its local day is a listed day and its local time is at or after start_time, or when the local day before it is a listed day and its local time is before end_time. This delivery clock is independent of reporting_capabilities.timezone.
      */
@@ -1160,7 +1150,9 @@ export type DaypartTarget = {
      * Optional human-readable name for this time window (e.g., 'Morning Drive', 'Prime Time')
      */
     label?: string;
-} & ({} | {});
+    start_hour?: never;
+    end_hour?: never;
+};
 
 /**
  * Seller-authored integrity pin over one third-party-published definition that a proposal's commercial_terms reference: a publisher-catalog format option, publisher-catalog placement, adagents.json collection, or data-provider signal. content_digest is the lowercase-hex SHA-256 of the RFC 8785 (JCS) serialization of the kind's closed projection of the published entry, defined normatively in docs/media-buy/specification.mdx#definition-pins. Pins live inside commercial_terms, so terms_digest covers the pin but not the definition it names: a published definition can change while terms_digest still verifies, and re-verifying the pin is what detects it. Request inputs never carry pins.

package/dist/lib/types/asset-instances.d.mts

@@ -31,4 +31,4 @@ export type AssetInstance = AssetVariant;
  * switch-case helpers.
  */
 export type AssetInstanceType = AssetInstance['asset_type'];
-export type { ImageAsset, VideoAsset, AudioAsset, TextAsset, HTMLAsset, URLAsset, CSSAsset, JavaScriptAsset, MarkdownAsset, VASTAsset, DAASTAsset, BriefAsset, VideoBriefAsset, CatalogAsset, WebhookAsset, ZipAsset, PublishedPostAsset, CardAsset, PixelTrackerAsset, VASTTrackerAsset, DAASTTrackerAsset, DisplayTagAsset, };
+export type { AssetVariant, ImageAsset, VideoAsset, AudioAsset, TextAsset, HTMLAsset, URLAsset, CSSAsset, JavaScriptAsset, MarkdownAsset, VASTAsset, DAASTAsset, BriefAsset, VideoBriefAsset, CatalogAsset, WebhookAsset, ZipAsset, PublishedPostAsset, CardAsset, PixelTrackerAsset, VASTTrackerAsset, DAASTTrackerAsset, DisplayTagAsset, };

package/dist/lib/types/asset-instances.d.ts

@@ -31,4 +31,4 @@ export type AssetInstance = AssetVariant;
  * switch-case helpers.
  */
 export type AssetInstanceType = AssetInstance['asset_type'];
-export type { ImageAsset, VideoAsset, AudioAsset, TextAsset, HTMLAsset, URLAsset, CSSAsset, JavaScriptAsset, MarkdownAsset, VASTAsset, DAASTAsset, BriefAsset, VideoBriefAsset, CatalogAsset, WebhookAsset, ZipAsset, PublishedPostAsset, CardAsset, PixelTrackerAsset, VASTTrackerAsset, DAASTTrackerAsset, DisplayTagAsset, };
+export type { AssetVariant, ImageAsset, VideoAsset, AudioAsset, TextAsset, HTMLAsset, URLAsset, CSSAsset, JavaScriptAsset, MarkdownAsset, VASTAsset, DAASTAsset, BriefAsset, VideoBriefAsset, CatalogAsset, WebhookAsset, ZipAsset, PublishedPostAsset, CardAsset, PixelTrackerAsset, VASTTrackerAsset, DAASTTrackerAsset, DisplayTagAsset, };

package/dist/lib/types/buy-products.d.ts

@@ -1177,26 +1177,22 @@ export type DayOfWeek = 'monday' | 'tuesday' | 'wednesday' | 'thursday' | 'frida
 export type DaypartTarget = {
     /**
      * Days of week this window applies to. Use multiple days for compact targeting (e.g., monday-friday in one object). For an overnight start_time/end_time window, each day names the day the window starts on.
-     *
-     * @minItems 1
      */
-    days: [DayOfWeek, ...DayOfWeek[]];
+    days: DayOfWeek[];
     /**
      * Start hour (inclusive), 0-23 in 24-hour format. 0 = midnight, 6 = 6:00am, 18 = 6:00pm. Whole-hour form: pair with end_hour; mutually exclusive with start_time and end_time.
+     * @minimum 0
+     * @maximum 23
+     * @format int
      */
-    start_hour?: number;
+    start_hour: number;
     /**
      * End hour (exclusive), 1-24 in 24-hour format. 10 = 10:00am, 24 = midnight. Must be greater than start_hour; whole-hour windows never cross midnight. Whole-hour form: pair with start_hour; mutually exclusive with start_time and end_time.
+     * @minimum 1
+     * @maximum 24
+     * @format int
      */
-    end_hour?: number;
-    /**
-     * Experimental in AdCP 3.3. Start of the window (inclusive) as a 24-hour HH:MM civil clock time on the entry's timezone clock, such as '19:30'. Use for windows that do not fall on whole hours (linear TV programme junctions, quarter-hour schedules). Pair with end_time; mutually exclusive with start_hour and end_hour. A window whose end_time is earlier than its start_time crosses midnight and belongs to the day it starts on. A product accepts only the finest time granularity it declares in overlay_support.daypart_targets.time_granularity; sellers MUST reject, never round, a clock time the product does not honor.
-     */
-    start_time?: string;
-    /**
-     * Experimental in AdCP 3.3. End of the window (exclusive) as a 24-hour HH:MM civil clock time, such as '23:00'. Pair with start_time; mutually exclusive with start_hour and end_hour. end_time earlier than start_time means the window crosses midnight and ends at end_time on the following civil day (for example, 22:00 to 02:00 runs from 22:00 on a listed day until 02:00 the next morning); '00:00' therefore ends the window at the midnight closing the start day. end_time MUST NOT equal start_time: a zero-length or full-day window is invalid, and a full day uses start_hour 0 with end_hour 24. Sellers MUST reject an equal pair with INVALID_REQUEST.
-     */
-    end_time?: string;
+    end_hour: number;
     /**
      * Civil-time clock used to evaluate this window. 'inventory_local' evaluates the hours in the seller-assigned local timezone of each inventory unit that can deliver the impression, such as a screen, venue, station, or publisher property; it never means the buyer, account, or server timezone. A concrete IANA timezone identifier (for example, 'America/New_York', 'CET', or 'UTC') evaluates one shared civil-time clock across the targeted inventory. Omission defaults to 'inventory_local'. Buyers that begin with a user or account preference MUST resolve it to a concrete IANA identifier before sending the daypart; 'user_timezone' and 'account_timezone' are not wire values. For each candidate delivery instant, convert the instant into this clock and compare its resulting local day and time of day with the half-open window: a skipped DST hour or interval has no matching instants, while both occurrences of a repeated hour or interval match. For an overnight start_time/end_time window, an instant matches when its local day is a listed day and its local time is at or after start_time, or when the local day before it is a listed day and its local time is before end_time. This delivery clock is independent of reporting_capabilities.timezone.
      */
@@ -1205,29 +1201,23 @@ export type DaypartTarget = {
      * Optional human-readable name for this time window (e.g., 'Morning Drive', 'Prime Time')
      */
     label?: string;
-} & ({} | {}) & {
+    start_time?: never;
+    end_time?: never;
+} | {
     /**
      * Days of week this window applies to. Use multiple days for compact targeting (e.g., monday-friday in one object). For an overnight start_time/end_time window, each day names the day the window starts on.
-     *
-     * @minItems 1
-     */
-    days: [DayOfWeek, ...DayOfWeek[]];
-    /**
-     * Start hour (inclusive), 0-23 in 24-hour format. 0 = midnight, 6 = 6:00am, 18 = 6:00pm. Whole-hour form: pair with end_hour; mutually exclusive with start_time and end_time.
-     */
-    start_hour?: number;
-    /**
-     * End hour (exclusive), 1-24 in 24-hour format. 10 = 10:00am, 24 = midnight. Must be greater than start_hour; whole-hour windows never cross midnight. Whole-hour form: pair with start_hour; mutually exclusive with start_time and end_time.
      */
-    end_hour?: number;
+    days: DayOfWeek[];
     /**
      * Experimental in AdCP 3.3. Start of the window (inclusive) as a 24-hour HH:MM civil clock time on the entry's timezone clock, such as '19:30'. Use for windows that do not fall on whole hours (linear TV programme junctions, quarter-hour schedules). Pair with end_time; mutually exclusive with start_hour and end_hour. A window whose end_time is earlier than its start_time crosses midnight and belongs to the day it starts on. A product accepts only the finest time granularity it declares in overlay_support.daypart_targets.time_granularity; sellers MUST reject, never round, a clock time the product does not honor.
+     * @pattern ^([01][0-9]|2[0-3]):[0-5][0-9]$
      */
-    start_time?: string;
+    start_time: string;
     /**
      * Experimental in AdCP 3.3. End of the window (exclusive) as a 24-hour HH:MM civil clock time, such as '23:00'. Pair with start_time; mutually exclusive with start_hour and end_hour. end_time earlier than start_time means the window crosses midnight and ends at end_time on the following civil day (for example, 22:00 to 02:00 runs from 22:00 on a listed day until 02:00 the next morning); '00:00' therefore ends the window at the midnight closing the start day. end_time MUST NOT equal start_time: a zero-length or full-day window is invalid, and a full day uses start_hour 0 with end_hour 24. Sellers MUST reject an equal pair with INVALID_REQUEST.
+     * @pattern ^([01][0-9]|2[0-3]):[0-5][0-9]$
      */
-    end_time?: string;
+    end_time: string;
     /**
      * Civil-time clock used to evaluate this window. 'inventory_local' evaluates the hours in the seller-assigned local timezone of each inventory unit that can deliver the impression, such as a screen, venue, station, or publisher property; it never means the buyer, account, or server timezone. A concrete IANA timezone identifier (for example, 'America/New_York', 'CET', or 'UTC') evaluates one shared civil-time clock across the targeted inventory. Omission defaults to 'inventory_local'. Buyers that begin with a user or account preference MUST resolve it to a concrete IANA identifier before sending the daypart; 'user_timezone' and 'account_timezone' are not wire values. For each candidate delivery instant, convert the instant into this clock and compare its resulting local day and time of day with the half-open window: a skipped DST hour or interval has no matching instants, while both occurrences of a repeated hour or interval match. For an overnight start_time/end_time window, an instant matches when its local day is a listed day and its local time is at or after start_time, or when the local day before it is a listed day and its local time is before end_time. This delivery clock is independent of reporting_capabilities.timezone.
      */
@@ -1236,7 +1226,9 @@ export type DaypartTarget = {
      * Optional human-readable name for this time window (e.g., 'Morning Drive', 'Prime Time')
      */
     label?: string;
-} & ({} | {});
+    start_hour?: never;
+    end_hour?: never;
+};
 
 /**
  * Restrict delivery to specific time windows. Each entry specifies days of week, an hour range, and an optional timezone that defaults to inventory_local. A concrete IANA zone uses one shared civil-time clock, while inventory_local evaluates each inventory unit in its seller-assigned local timezone. Entries are independent and MAY use different clocks.

package/dist/lib/types/check-governance.d.ts

@@ -1608,26 +1608,22 @@ export type DayOfWeek = 'monday' | 'tuesday' | 'wednesday' | 'thursday' | 'frida
 export type DaypartTarget = {
     /**
      * Days of week this window applies to. Use multiple days for compact targeting (e.g., monday-friday in one object). For an overnight start_time/end_time window, each day names the day the window starts on.
-     *
-     * @minItems 1
      */
-    days: [DayOfWeek, ...DayOfWeek[]];
+    days: DayOfWeek[];
     /**
      * Start hour (inclusive), 0-23 in 24-hour format. 0 = midnight, 6 = 6:00am, 18 = 6:00pm. Whole-hour form: pair with end_hour; mutually exclusive with start_time and end_time.
+     * @minimum 0
+     * @maximum 23
+     * @format int
      */
-    start_hour?: number;
+    start_hour: number;
     /**
      * End hour (exclusive), 1-24 in 24-hour format. 10 = 10:00am, 24 = midnight. Must be greater than start_hour; whole-hour windows never cross midnight. Whole-hour form: pair with start_hour; mutually exclusive with start_time and end_time.
+     * @minimum 1
+     * @maximum 24
+     * @format int
      */
-    end_hour?: number;
-    /**
-     * Experimental in AdCP 3.3. Start of the window (inclusive) as a 24-hour HH:MM civil clock time on the entry's timezone clock, such as '19:30'. Use for windows that do not fall on whole hours (linear TV programme junctions, quarter-hour schedules). Pair with end_time; mutually exclusive with start_hour and end_hour. A window whose end_time is earlier than its start_time crosses midnight and belongs to the day it starts on. A product accepts only the finest time granularity it declares in overlay_support.daypart_targets.time_granularity; sellers MUST reject, never round, a clock time the product does not honor.
-     */
-    start_time?: string;
-    /**
-     * Experimental in AdCP 3.3. End of the window (exclusive) as a 24-hour HH:MM civil clock time, such as '23:00'. Pair with start_time; mutually exclusive with start_hour and end_hour. end_time earlier than start_time means the window crosses midnight and ends at end_time on the following civil day (for example, 22:00 to 02:00 runs from 22:00 on a listed day until 02:00 the next morning); '00:00' therefore ends the window at the midnight closing the start day. end_time MUST NOT equal start_time: a zero-length or full-day window is invalid, and a full day uses start_hour 0 with end_hour 24. Sellers MUST reject an equal pair with INVALID_REQUEST.
-     */
-    end_time?: string;
+    end_hour: number;
     /**
      * Civil-time clock used to evaluate this window. 'inventory_local' evaluates the hours in the seller-assigned local timezone of each inventory unit that can deliver the impression, such as a screen, venue, station, or publisher property; it never means the buyer, account, or server timezone. A concrete IANA timezone identifier (for example, 'America/New_York', 'CET', or 'UTC') evaluates one shared civil-time clock across the targeted inventory. Omission defaults to 'inventory_local'. Buyers that begin with a user or account preference MUST resolve it to a concrete IANA identifier before sending the daypart; 'user_timezone' and 'account_timezone' are not wire values. For each candidate delivery instant, convert the instant into this clock and compare its resulting local day and time of day with the half-open window: a skipped DST hour or interval has no matching instants, while both occurrences of a repeated hour or interval match. For an overnight start_time/end_time window, an instant matches when its local day is a listed day and its local time is at or after start_time, or when the local day before it is a listed day and its local time is before end_time. This delivery clock is independent of reporting_capabilities.timezone.
      */
@@ -1636,29 +1632,23 @@ export type DaypartTarget = {
      * Optional human-readable name for this time window (e.g., 'Morning Drive', 'Prime Time')
      */
     label?: string;
-} & ({} | {}) & {
+    start_time?: never;
+    end_time?: never;
+} | {
     /**
      * Days of week this window applies to. Use multiple days for compact targeting (e.g., monday-friday in one object). For an overnight start_time/end_time window, each day names the day the window starts on.
-     *
-     * @minItems 1
-     */
-    days: [DayOfWeek, ...DayOfWeek[]];
-    /**
-     * Start hour (inclusive), 0-23 in 24-hour format. 0 = midnight, 6 = 6:00am, 18 = 6:00pm. Whole-hour form: pair with end_hour; mutually exclusive with start_time and end_time.
-     */
-    start_hour?: number;
-    /**
-     * End hour (exclusive), 1-24 in 24-hour format. 10 = 10:00am, 24 = midnight. Must be greater than start_hour; whole-hour windows never cross midnight. Whole-hour form: pair with start_hour; mutually exclusive with start_time and end_time.
      */
-    end_hour?: number;
+    days: DayOfWeek[];
     /**
      * Experimental in AdCP 3.3. Start of the window (inclusive) as a 24-hour HH:MM civil clock time on the entry's timezone clock, such as '19:30'. Use for windows that do not fall on whole hours (linear TV programme junctions, quarter-hour schedules). Pair with end_time; mutually exclusive with start_hour and end_hour. A window whose end_time is earlier than its start_time crosses midnight and belongs to the day it starts on. A product accepts only the finest time granularity it declares in overlay_support.daypart_targets.time_granularity; sellers MUST reject, never round, a clock time the product does not honor.
+     * @pattern ^([01][0-9]|2[0-3]):[0-5][0-9]$
      */
-    start_time?: string;
+    start_time: string;
     /**
      * Experimental in AdCP 3.3. End of the window (exclusive) as a 24-hour HH:MM civil clock time, such as '23:00'. Pair with start_time; mutually exclusive with start_hour and end_hour. end_time earlier than start_time means the window crosses midnight and ends at end_time on the following civil day (for example, 22:00 to 02:00 runs from 22:00 on a listed day until 02:00 the next morning); '00:00' therefore ends the window at the midnight closing the start day. end_time MUST NOT equal start_time: a zero-length or full-day window is invalid, and a full day uses start_hour 0 with end_hour 24. Sellers MUST reject an equal pair with INVALID_REQUEST.
+     * @pattern ^([01][0-9]|2[0-3]):[0-5][0-9]$
      */
-    end_time?: string;
+    end_time: string;
     /**
      * Civil-time clock used to evaluate this window. 'inventory_local' evaluates the hours in the seller-assigned local timezone of each inventory unit that can deliver the impression, such as a screen, venue, station, or publisher property; it never means the buyer, account, or server timezone. A concrete IANA timezone identifier (for example, 'America/New_York', 'CET', or 'UTC') evaluates one shared civil-time clock across the targeted inventory. Omission defaults to 'inventory_local'. Buyers that begin with a user or account preference MUST resolve it to a concrete IANA identifier before sending the daypart; 'user_timezone' and 'account_timezone' are not wire values. For each candidate delivery instant, convert the instant into this clock and compare its resulting local day and time of day with the half-open window: a skipped DST hour or interval has no matching instants, while both occurrences of a repeated hour or interval match. For an overnight start_time/end_time window, an instant matches when its local day is a listed day and its local time is at or after start_time, or when the local day before it is a listed day and its local time is before end_time. This delivery clock is independent of reporting_capabilities.timezone.
      */
@@ -1667,7 +1657,9 @@ export type DaypartTarget = {
      * Optional human-readable name for this time window (e.g., 'Morning Drive', 'Prime Time')
      */
     label?: string;
-} & ({} | {});
+    start_hour?: never;
+    end_hour?: never;
+};
 
 /**
  * Seller-authored integrity pin over one third-party-published definition that a proposal's commercial_terms reference: a publisher-catalog format option, publisher-catalog placement, adagents.json collection, or data-provider signal. content_digest is the lowercase-hex SHA-256 of the RFC 8785 (JCS) serialization of the kind's closed projection of the published entry, defined normatively in docs/media-buy/specification.mdx#definition-pins. Pins live inside commercial_terms, so terms_digest covers the pin but not the definition it names: a published definition can change while terms_digest still verifies, and re-verifying the pin is what detects it. Request inputs never carry pins.