@adcp/sdk 16.0.0 → 16.1.0

package/dist/lib/core/TaskExecutor.mjs

@@ -614,6 +614,10 @@ class TaskExecutor {
    * @internal
    */
   async observeExternalTaskStatus(taskId, status, result, identity = {}) {
+    const task = this.activeTasks.get(taskId);
+    if (task && (identity.serverTaskId !== void 0 && task.serverTaskId !== void 0 && identity.serverTaskId !== task.serverTaskId || identity.taskType !== void 0 && identity.taskType !== task.taskName)) {
+      throw new ConfigurationError("The pushed task identity does not match the tracked operation.");
+    }
     if (!["completed", "failed", "rejected", "canceled", "governance-denied", "aborted"].includes(status)) {
       return { settled: false, result };
     }
@@ -642,7 +646,9 @@ class TaskExecutor {
       this.pendingExternalTaskObservations.set(taskId, pending);
       return { settled: false, queued: true };
     }
-    this.updateTaskStatus(taskId, status, result);
+    if (task && task.serverTaskId === void 0 && identity.serverTaskId !== void 0)
+      task.serverTaskId = identity.serverTaskId;
+    if (task && !TERMINAL_TASK_STATUSES.has(task.status)) this.updateTaskStatus(taskId, status, result);
     return { settled: false, result };
   }
   /** Whether this process can safely settle or reject a durable callback for the operation. */
@@ -770,6 +776,9 @@ class TaskExecutor {
       this.requireDeferredSettlementOperationRouting(this.config.deferredStorage, true);
     }
     const taskId = getTaskOperationId(options) ?? randomUUID();
+    if (this.activeTasks.has(taskId) || this.compactedTaskIds.has(taskId) || this.deferredTerminalPublicationTaskIds.has(taskId) || this.closedExternalTaskSettlementTaskIds.has(taskId) || this.externalTaskSettlementHandlers.has(taskId)) {
+      throw new ConfigurationError("operationId is already in use by this client; track the existing task instead.");
+    }
     const startTime = Date.now();
     const workingTimeout = this.config.workingTimeout || 12e4;
     const wireAdcpVersion = options.wireAdcpVersion ?? this.config.wireAdcpVersion;
@@ -1045,12 +1054,14 @@ class TaskExecutor {
       );
       throwIfAborted(postDispatchOptions.signal);
       const respStatus = this.responseParser.getStatus(response);
+      taskState.serverTaskId = this.responseParser.getTaskId(response);
       await this.config.onActivity?.({
         type: "protocol_response",
         operation_id: taskId,
         agent_id: agent.id,
         context_id: options.contextId,
         task_id: taskId,
+        server_task_id: taskState.serverTaskId,
         task_type: taskName,
         status: respStatus,
         payload: response,
@@ -1225,6 +1236,9 @@ class TaskExecutor {
   }
   async handleAsyncResponse(agent, taskId, taskName, params, response, messages, inputHandler, options = {}, debugLogs = [], startTime = Date.now(), deferTerminalTaskStatus = false, persistPausedContinuation = true, serverVersion = "v3", deferredClientContext, requireDeferredSettlementResumeAuthorization = false) {
     const status = this.responseParser.getStatus(response);
+    const serverTaskId = this.responseParser.getTaskId(response);
+    const task = this.activeTasks.get(taskId);
+    if (task && serverTaskId) task.serverTaskId = serverTaskId;
     switch (status) {
       case ADCP_STATUS.COMPLETED:
         const completedData = this.extractResponseData(response, debugLogs, taskName, serverVersion);
@@ -1580,8 +1594,70 @@ class TaskExecutor {
       debug_logs: debugLogs
     };
   }
+  /** Rebuild the polling continuation for seller work persisted by the caller. */
+  trackTask(agent, request) {
+    if (typeof request.taskId !== "string" || !request.taskId.trim()) {
+      throw new TypeError("taskId must be a non-empty seller task id.");
+    }
+    if (typeof request.taskType !== "string" || !request.taskType.trim()) {
+      throw new TypeError("taskType must be a non-empty tool name.");
+    }
+    const operationId = getTaskOperationId(request) ?? randomUUID();
+    const existing = this.activeTasks.get(operationId);
+    if (existing && (existing.serverTaskId !== request.taskId || existing.taskName !== request.taskType || existing.agent.id !== agent.id || existing.agent.protocol !== agent.protocol || existing.status === "pending")) {
+      throw new ConfigurationError(
+        "operationId is already tracked by this client for a different or dispatching task."
+      );
+    }
+    if (this.deferredTerminalPublicationTaskIds.has(operationId) || this.closedExternalTaskSettlementTaskIds.has(operationId) || this.externalTaskSettlementHandlers.has(operationId)) {
+      throw new ConfigurationError("This operation requires its original continuation or durable settlement recovery.");
+    }
+    const startTime = existing?.startTime ?? Date.now();
+    if (!existing)
+      this.activeTasks.set(operationId, {
+        taskId: operationId,
+        serverTaskId: request.taskId,
+        taskName: request.taskType,
+        status: "submitted",
+        messages: [],
+        startTime,
+        attempt: 0,
+        maxAttempts: 0,
+        options: {},
+        agent: { id: agent.id, name: agent.name, protocol: agent.protocol },
+        serverVersion: "v3"
+      });
+    if (!existing) this.compactIntermediateTaskState(operationId, "submitted");
+    const continuation = this.createSubmittedContinuation(
+      agent,
+      operationId,
+      request.taskType,
+      request.taskId,
+      void 0,
+      snapshotTransportOptions(request.transport ?? this.config.transport),
+      {
+        ...this.buildMetadata({
+          taskId: operationId,
+          taskName: request.taskType,
+          agent,
+          startTime,
+          status: "submitted"
+        }),
+        serverTaskId: request.taskId,
+        a2aTaskId: request.cancelOnAbort === true ? request.a2aTaskId : void 0
+      },
+      false,
+      "v3",
+      this.config.wireAdcpVersion,
+      this.config.versionEnvelope,
+      request.signal
+    );
+    return { ...continuation, operationId };
+  }
   /** Build polling closures around one authoritative seller work handle. */
-  createSubmittedContinuation(agent, taskId, taskName, serverTaskId, webhookUrl, pollingTransport, metadata, deferTerminalTaskStatus, serverVersion, wireAdcpVersion, versionEnvelope) {
+  createSubmittedContinuation(agent, taskId, taskName, serverTaskId, webhookUrl, pollingTransport, metadata, deferTerminalTaskStatus, serverVersion, wireAdcpVersion, versionEnvelope, pollingSignal) {
+    const registeredTask = this.activeTasks.get(taskId);
+    const canPublish = (status) => registeredTask !== void 0 && this.activeTasks.get(taskId) === registeredTask && !TERMINAL_TASK_STATUSES.has(registeredTask.status) && registeredTask.status !== status;
     return {
       taskId: serverTaskId,
       webhookUrl,
@@ -1591,25 +1667,27 @@ class TaskExecutor {
           agent,
           serverTaskId,
           transportSnapshot,
-          void 0,
+          pollingSignal,
           taskName,
           serverVersion,
           wireAdcpVersion,
-          versionEnvelope
+          versionEnvelope,
+          taskId
         )).task;
-        if (!deferTerminalTaskStatus && ["completed", "failed", "rejected", "canceled"].includes(task.status)) {
+        if (!deferTerminalTaskStatus && ["completed", "failed", "rejected", "canceled"].includes(task.status) && canPublish(task.status)) {
           this.updateTaskStatus(taskId, task.status, task.result, task.error);
         }
-        return task;
+        return { ...task, operationId: taskId, serverTaskId };
       },
       waitForCompletion: async (pollInterval = 6e4, signal, requireExactTaskIdentity = false) => {
         void requireExactTaskIdentity;
+        const completionSignal = pollingSignal && signal ? AbortSignal.any([pollingSignal, signal]) : signal ?? pollingSignal;
         const completed = await this.pollTaskCompletion(
           agent,
           serverTaskId,
           pollInterval,
           pollingTransport,
-          signal,
+          completionSignal,
           metadata.a2aTaskId,
           taskName,
           taskId,
@@ -1617,7 +1695,9 @@ class TaskExecutor {
           wireAdcpVersion,
           versionEnvelope
         );
-        if (!deferTerminalTaskStatus || !TERMINAL_TASK_STATUSES.has(completed.status)) {
+        if ((!deferTerminalTaskStatus || !TERMINAL_TASK_STATUSES.has(completed.status)) && // Cancellation, identity mismatches, missing tasks, and malformed
+        // responses establish observation failure, not seller task failure.
+        (!TERMINAL_TASK_STATUSES.has(completed.status) || isAuthoritativePolledTerminal(completed)) && canPublish(completed.status)) {
           this.updateTaskStatus(taskId, completed.status, completed.data, completed.error);
         }
         return completed;
@@ -1630,7 +1710,9 @@ class TaskExecutor {
    * local task publication only after those final wrappers return.
    */
   attachSettledContinuationTaskStatus(taskId, result) {
+    const registeredTask = this.activeTasks.get(taskId);
     const publish = (status, data, error, identity) => {
+      if (registeredTask === void 0 || this.activeTasks.get(taskId) !== registeredTask) return;
       this.publishSettledTaskStatus(taskId, status, data, error, false, identity);
     };
     if (result.submitted) {
@@ -2261,7 +2343,7 @@ class TaskExecutor {
       return [];
     }
   }
-  async getTaskStatusWithRawResponse(agent, taskId, transport, signal, expectedTaskType, serverVersion, wireAdcpVersion, versionEnvelope) {
+  async getTaskStatusWithRawResponse(agent, taskId, transport, signal, expectedTaskType, serverVersion, wireAdcpVersion, versionEnvelope, operationId) {
     const toolName = agent.protocol === "mcp" ? "tasks_get" : "tasks/get";
     const response = await ProtocolClient.callTool(
       agent,
@@ -2280,7 +2362,8 @@ class TaskExecutor {
         signal,
         onTransportActivity: this.config.onTransportActivity,
         transportActivityContext: {
-          taskId
+          taskId,
+          ...operationId !== void 0 && { operationId }
         }
       }
     );
@@ -2312,12 +2395,13 @@ class TaskExecutor {
       wireOptions?.versionEnvelope
     )).task;
   }
-  async pollTaskCompletion(agent, taskId, pollInterval = 6e4, transport, signal, a2aCancellationTaskId, expectedTaskType, metadataTaskId = taskId, serverVersion, wireAdcpVersion, versionEnvelope) {
+  async pollTaskCompletion(agent, taskId, pollInterval = 6e4, transport, signal, a2aCancellationTaskId, expectedTaskType, metadataTaskId, serverVersion, wireAdcpVersion, versionEnvelope) {
     const transportSnapshot = snapshotTransportOptions(transport ?? this.config.transport);
     if (!Number.isFinite(pollInterval) || pollInterval < 0 || pollInterval > MAX_TIMER_DELAY_MS) {
       throw new RangeError(`pollInterval must be a finite non-negative number <= ${MAX_TIMER_DELAY_MS}`);
     }
     const pollStartTime = Date.now();
+    const correlationId = metadataTaskId ?? taskId;
     const withServerTaskId = (metadata) => ({
       ...metadata,
       serverTaskId: taskId
@@ -2345,8 +2429,8 @@ class TaskExecutor {
           error: `tasks/get polling was cancelled before a terminal state was observed: ${reason}`,
           metadata: withServerTaskId(
             this.buildMetadata({
-              taskId: metadataTaskId,
-              taskName: "unknown",
+              taskId: correlationId,
+              taskName: expectedTaskType ?? "unknown",
               agent,
               startTime: pollStartTime,
               status: "failed"
@@ -2365,11 +2449,15 @@ class TaskExecutor {
           expectedTaskType,
           serverVersion,
           wireAdcpVersion,
-          versionEnvelope
+          versionEnvelope,
+          metadataTaskId
         );
         status = pollResult.task;
         rawResponse = pollResult.rawResponse;
       } catch (err) {
+        if (signal?.aborted && agent.protocol === "a2a" && a2aCancellationTaskId && isAbortOrTimeoutError(err)) {
+          continue;
+        }
         if (err instanceof TaskBindingMismatchError) {
           return attachMatch({
             success: false,
@@ -2377,8 +2465,8 @@ class TaskExecutor {
             error: err.message,
             metadata: withServerTaskId(
               this.buildMetadata({
-                taskId: metadataTaskId,
-                taskName: "unknown",
+                taskId: correlationId,
+                taskName: expectedTaskType ?? "unknown",
                 agent,
                 startTime: pollStartTime,
                 status: "failed",
@@ -2395,8 +2483,8 @@ class TaskExecutor {
             error: `Task ${taskId} is no longer queryable \u2014 it may have been completed and evicted by the seller before this poll arrived. Consider using push notifications (reporting_webhook) instead of polling, or configuring a longer task retention TTL on the seller.`,
             metadata: withServerTaskId(
               this.buildMetadata({
-                taskId: metadataTaskId,
-                taskName: "unknown",
+                taskId: correlationId,
+                taskName: expectedTaskType ?? "unknown",
                 agent,
                 startTime: pollStartTime,
                 status: "failed"
@@ -2411,13 +2499,15 @@ class TaskExecutor {
           success: false,
           status: "failed",
           error: "The seller returned a task outside the requested durable task identity.",
-          metadata: this.buildMetadata({
-            taskId,
-            taskName: "unknown",
-            agent,
-            startTime: pollStartTime,
-            status: "failed"
-          })
+          metadata: withServerTaskId(
+            this.buildMetadata({
+              taskId: correlationId,
+              taskName: expectedTaskType ?? "unknown",
+              agent,
+              startTime: pollStartTime,
+              status: "failed"
+            })
+          )
         });
       }
       if (status.status === ADCP_STATUS.COMPLETED) {
@@ -2430,7 +2520,7 @@ class TaskExecutor {
               data: status.result,
               metadata: withServerTaskId(
                 this.buildMetadata({
-                  taskId: metadataTaskId,
+                  taskId: correlationId,
                   taskName: status.taskType,
                   agent,
                   responseTimeMs: Date.now() - status.createdAt,
@@ -2449,11 +2539,11 @@ class TaskExecutor {
             data: status.result,
             error: this.extractOperationError(status.result),
             adcpError: asyncResultErr,
-            errorInstance: this.buildErrorInstance(metadataTaskId, asyncResultErr),
+            errorInstance: this.buildErrorInstance(correlationId, asyncResultErr),
             correlationId: extractCorrelationId(status.result),
             metadata: withServerTaskId(
               this.buildMetadata({
-                taskId: metadataTaskId,
+                taskId: correlationId,
                 taskName: status.taskType,
                 agent,
                 responseTimeMs: Date.now() - status.createdAt,
@@ -2473,11 +2563,11 @@ class TaskExecutor {
             data: status.result,
             error: status.error || status.message || `Task ${status.status}`,
             adcpError: asyncFailedErr,
-            errorInstance: this.buildErrorInstance(metadataTaskId, asyncFailedErr),
+            errorInstance: this.buildErrorInstance(correlationId, asyncFailedErr),
             correlationId: extractCorrelationId(status.result),
             metadata: withServerTaskId(
               this.buildMetadata({
-                taskId: metadataTaskId,
+                taskId: correlationId,
                 taskName: status.taskType,
                 agent,
                 responseTimeMs: Date.now() - status.createdAt,
@@ -2495,7 +2585,7 @@ class TaskExecutor {
           data: status.result,
           metadata: withServerTaskId(
             this.buildMetadata({
-              taskId: metadataTaskId,
+              taskId: correlationId,
               taskName: status.taskType,
               agent,
               responseTimeMs: Date.now() - status.createdAt,
@@ -2512,8 +2602,8 @@ class TaskExecutor {
           error: `tasks/get returned an unrecognizable response (parsed status: "unknown", taskId: "${status.taskId}"). The seller may not implement tasks/get as an AdCP skill, or its response did not match any supported envelope shape (flat AdCP, MCP structuredContent, or A2A DataPart artifact).`,
           metadata: withServerTaskId(
             this.buildMetadata({
-              taskId: metadataTaskId,
-              taskName: "unknown",
+              taskId: correlationId,
+              taskName: expectedTaskType ?? "unknown",
               agent,
               startTime: pollStartTime,
               status: "failed",
@@ -4497,6 +4587,8 @@ class TaskExecutor {
       task.status = status;
       const taskInfo = {
         taskId: task.taskId,
+        operationId: task.taskId,
+        serverTaskId: task.serverTaskId,
         status,
         taskType: task.taskName,
         createdAt: task.startTime,
@@ -4511,6 +4603,7 @@ class TaskExecutor {
         agent_id: task.agent.id,
         context_id: void 0,
         task_id: task.taskId,
+        server_task_id: task.serverTaskId,
         task_type: task.taskName,
         status,
         payload: result ?? (error ? { error } : void 0),
@@ -4525,7 +4618,7 @@ class TaskExecutor {
         task.options = {};
         delete task.pendingInput;
         setTimeout(() => {
-          this.cleanupTerminalTaskInspectionState(taskId);
+          if (this.activeTasks.get(taskId) === task) this.cleanupTerminalTaskInspectionState(taskId);
         }, 3e4).unref();
       }
     }

package/dist/lib/core/task-deadline.d.mts

@@ -6,6 +6,8 @@ type DeadlineTaskOptions<TOptions extends TaskOptions = TaskOptions> = TOptions
     [TASK_OPERATION_ID]: string;
     [TASK_DEADLINE_ERROR]?: TaskTimeoutError;
 };
+/** Give a child dispatch its own correlation id while retaining the parent deadline and cancellation. */
+export declare function childTaskOptions(options?: TaskOptions): TaskOptions;
 export declare function getTaskOperationId(options: TaskOptions | undefined): string | undefined;
 export declare function attachTaskDeadlineIdempotencyKey(options: TaskOptions, idempotencyKey: string): void;
 export declare function attachTaskDeadlineGovernanceRecovery(options: TaskOptions, recovery: GovernanceOutcomeRecovery): void;

package/dist/lib/core/task-deadline.d.ts

@@ -6,6 +6,8 @@ type DeadlineTaskOptions<TOptions extends TaskOptions = TaskOptions> = TOptions
     [TASK_OPERATION_ID]: string;
     [TASK_DEADLINE_ERROR]?: TaskTimeoutError;
 };
+/** Give a child dispatch its own correlation id while retaining the parent deadline and cancellation. */
+export declare function childTaskOptions(options?: TaskOptions): TaskOptions;
 export declare function getTaskOperationId(options: TaskOptions | undefined): string | undefined;
 export declare function attachTaskDeadlineIdempotencyKey(options: TaskOptions, idempotencyKey: string): void;
 export declare function attachTaskDeadlineGovernanceRecovery(options: TaskOptions, recovery: GovernanceOutcomeRecovery): void;

package/dist/lib/core/task-deadline.js

@@ -20,6 +20,7 @@ var task_deadline_exports = {};
 __export(task_deadline_exports, {
   attachTaskDeadlineGovernanceRecovery: () => attachTaskDeadlineGovernanceRecovery,
   attachTaskDeadlineIdempotencyKey: () => attachTaskDeadlineIdempotencyKey,
+  childTaskOptions: () => childTaskOptions,
   getTaskOperationId: () => getTaskOperationId,
   withTaskDeadline: () => withTaskDeadline
 });
@@ -29,8 +30,24 @@ var import_errors = require('../errors/index.js');
 var import_abort = require('../protocols/abort.js');
 const TASK_OPERATION_ID = /* @__PURE__ */ Symbol("adcp.taskOperationId");
 const TASK_DEADLINE_ERROR = /* @__PURE__ */ Symbol("adcp.taskDeadlineError");
+function childTaskOptions(options) {
+  const child = { ...options };
+  delete child.operationId;
+  delete child[TASK_OPERATION_ID];
+  return child;
+}
 function getTaskOperationId(options) {
-  return options?.[TASK_OPERATION_ID];
+  const operationId = options?.operationId;
+  if (operationId !== void 0 && (typeof operationId !== "string" || !/^(?!\.+$)[A-Za-z0-9_.:-]{1,255}$/.test(operationId) || operationId.startsWith("delivery_route:"))) {
+    throw new TypeError(
+      "operationId must contain 1\u2013255 letters, digits, underscores, periods, colons, or hyphens; dot-only IDs and the delivery_route: prefix are reserved."
+    );
+  }
+  const internalId = options?.[TASK_OPERATION_ID];
+  if (internalId !== void 0 && operationId !== void 0 && internalId !== operationId) {
+    throw new TypeError("operationId does not match the operation already assigned to this call.");
+  }
+  return internalId ?? operationId;
 }
 function attachTaskDeadlineIdempotencyKey(options, idempotencyKey) {
   const error = options[TASK_DEADLINE_ERROR];
@@ -44,7 +61,7 @@ function attachTaskDeadlineGovernanceRecovery(options, recovery) {
 }
 async function withTaskDeadline(options, run) {
   const existing = options;
-  const taskId = existing?.[TASK_OPERATION_ID] ?? (0, import_node_crypto.randomUUID)();
+  const taskId = getTaskOperationId(existing) ?? (0, import_node_crypto.randomUUID)();
   const timeout = options?.timeout;
   const baseOptions = { ...options, timeout: void 0, [TASK_OPERATION_ID]: taskId };
   (0, import_abort.throwIfAborted)(options?.signal);
@@ -68,6 +85,7 @@ async function withTaskDeadline(options, run) {
 0 && (module.exports = {
   attachTaskDeadlineGovernanceRecovery,
   attachTaskDeadlineIdempotencyKey,
+  childTaskOptions,
   getTaskOperationId,
   withTaskDeadline
 });

package/dist/lib/core/task-deadline.mjs

@@ -3,8 +3,24 @@ import { TaskTimeoutError } from "../errors/index.mjs";
 import { MAX_TIMER_DELAY_MS, throwIfAborted, withAbortSignal } from "../protocols/abort.mjs";
 const TASK_OPERATION_ID = /* @__PURE__ */ Symbol("adcp.taskOperationId");
 const TASK_DEADLINE_ERROR = /* @__PURE__ */ Symbol("adcp.taskDeadlineError");
+function childTaskOptions(options) {
+  const child = { ...options };
+  delete child.operationId;
+  delete child[TASK_OPERATION_ID];
+  return child;
+}
 function getTaskOperationId(options) {
-  return options?.[TASK_OPERATION_ID];
+  const operationId = options?.operationId;
+  if (operationId !== void 0 && (typeof operationId !== "string" || !/^(?!\.+$)[A-Za-z0-9_.:-]{1,255}$/.test(operationId) || operationId.startsWith("delivery_route:"))) {
+    throw new TypeError(
+      "operationId must contain 1\u2013255 letters, digits, underscores, periods, colons, or hyphens; dot-only IDs and the delivery_route: prefix are reserved."
+    );
+  }
+  const internalId = options?.[TASK_OPERATION_ID];
+  if (internalId !== void 0 && operationId !== void 0 && internalId !== operationId) {
+    throw new TypeError("operationId does not match the operation already assigned to this call.");
+  }
+  return internalId ?? operationId;
 }
 function attachTaskDeadlineIdempotencyKey(options, idempotencyKey) {
   const error = options[TASK_DEADLINE_ERROR];
@@ -18,7 +34,7 @@ function attachTaskDeadlineGovernanceRecovery(options, recovery) {
 }
 async function withTaskDeadline(options, run) {
   const existing = options;
-  const taskId = existing?.[TASK_OPERATION_ID] ?? randomUUID();
+  const taskId = getTaskOperationId(existing) ?? randomUUID();
   const timeout = options?.timeout;
   const baseOptions = { ...options, timeout: void 0, [TASK_OPERATION_ID]: taskId };
   throwIfAborted(options?.signal);
@@ -41,6 +57,7 @@ async function withTaskDeadline(options, run) {
 export {
   attachTaskDeadlineGovernanceRecovery,
   attachTaskDeadlineIdempotencyKey,
+  childTaskOptions,
   getTaskOperationId,
   withTaskDeadline
 };

package/dist/lib/identity-3.3/schemas.draft.js

@@ -242,7 +242,7 @@ var schemas_draft_default = [
         properties: {
           grantee: {
             $ref: "#/definitions/domain",
-            description: "Domain of the organization receiving the grant. Its agents resolve to this domain through its own trust.json."
+            description: "Registrable domain (eTLD+1) of the organization receiving the grant, under the pinned Public Suffix List snapshot, ICANN and private sections (spec R3a step 1). Its agents resolve to this domain through its own trust.json. A host below a registrable domain (t1.vendor.example) is not one, and neither is a public suffix itself (github.io); alice.github.io is one, because github.io is in the private section. A grant whose grantee is not a registrable domain covers no claim, and its scopes still count for exclusive_grants, as L2 \xA7Grants in trust records describes (docs/building/by-layer/L2/accounts-and-agents.mdx). A pattern can't evaluate the Public Suffix List, so verifiers apply the rule. To limit a grant to some of the grantee's agents, list them in agents[]."
           },
           agents: {
             type: "array",

package/dist/lib/identity-3.3/schemas.draft.mjs

@@ -219,7 +219,7 @@ var schemas_draft_default = [
         properties: {
           grantee: {
             $ref: "#/definitions/domain",
-            description: "Domain of the organization receiving the grant. Its agents resolve to this domain through its own trust.json."
+            description: "Registrable domain (eTLD+1) of the organization receiving the grant, under the pinned Public Suffix List snapshot, ICANN and private sections (spec R3a step 1). Its agents resolve to this domain through its own trust.json. A host below a registrable domain (t1.vendor.example) is not one, and neither is a public suffix itself (github.io); alice.github.io is one, because github.io is in the private section. A grant whose grantee is not a registrable domain covers no claim, and its scopes still count for exclusive_grants, as L2 \xA7Grants in trust records describes (docs/building/by-layer/L2/accounts-and-agents.mdx). A pattern can't evaluate the Public Suffix List, so verifiers apply the rule. To limit a grant to some of the grantee's agents, list them in agents[]."
           },
           agents: {
             type: "array",

package/dist/lib/identity-3.3/trust.d.mts

@@ -34,6 +34,14 @@ export declare class TrustMembershipError extends IdentityAuthorizationError {
 }
 /** Schema plus semantic checks; publication never includes identity keys. */
 export declare function validateTrustRecord(value: unknown): asserts value is TrustRecord;
+/**
+ * Publication rules beyond the schema: every grant's `grantee` is a
+ * registrable domain and every `agents[].url` parses as an agent origin. A
+ * relying party ignores a grant that breaks either, so publishing one grants
+ * nothing while still making `grants[]` exhaustive for its scopes.
+ */
+export declare function assertPublishableTrustRecord(record: TrustRecord): void;
+/** Validate ({@link assertPublishableTrustRecord}) and copy a trust record for publication. */
 export declare function createTrustRecord(record: TrustRecord): TrustRecord;
 export type TrustFetchResult = {
     status: 'present';

package/dist/lib/identity-3.3/trust.d.ts

@@ -34,6 +34,14 @@ export declare class TrustMembershipError extends IdentityAuthorizationError {
 }
 /** Schema plus semantic checks; publication never includes identity keys. */
 export declare function validateTrustRecord(value: unknown): asserts value is TrustRecord;
+/**
+ * Publication rules beyond the schema: every grant's `grantee` is a
+ * registrable domain and every `agents[].url` parses as an agent origin. A
+ * relying party ignores a grant that breaks either, so publishing one grants
+ * nothing while still making `grants[]` exhaustive for its scopes.
+ */
+export declare function assertPublishableTrustRecord(record: TrustRecord): void;
+/** Validate ({@link assertPublishableTrustRecord}) and copy a trust record for publication. */
 export declare function createTrustRecord(record: TrustRecord): TrustRecord;
 export type TrustFetchResult = {
     status: 'present';

package/dist/lib/identity-3.3/trust.js

@@ -32,6 +32,7 @@ __export(trust_exports, {
   TrustEvaluator: () => TrustEvaluator,
   TrustMembershipError: () => TrustMembershipError,
   TrustRecordUnavailableError: () => TrustRecordUnavailableError,
+  assertPublishableTrustRecord: () => assertPublishableTrustRecord,
   authorizeDemandGrant: () => authorizeDemandGrant,
   createTrustRecord: () => createTrustRecord,
   validateIdentity33Schema: () => validateIdentity33Schema,
@@ -110,8 +111,34 @@ function validateTrustRecord(value) {
     origins.add(origin);
   }
 }
-function createTrustRecord(record) {
+function registrableGrantee(grantee) {
+  try {
+    return (0, import_etld.eTldPlusOne)(grantee) === grantee ? grantee : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function grantAgentOrigin(url) {
+  try {
+    return (0, import_canonicalize.canonicalAgentOrigin)(url);
+  } catch {
+    return void 0;
+  }
+}
+function assertPublishableTrustRecord(record) {
   validateTrustRecord(record);
+  for (const grant of record.grants ?? []) {
+    if (registrableGrantee(grant.grantee) === void 0)
+      throw new TypeError(
+        `Grant grantee "${grant.grantee}" is not a registrable domain; name the organization's registrable domain and narrow with agents[]`
+      );
+    for (const agent of grant.agents ?? [])
+      if (grantAgentOrigin(agent.url) === void 0)
+        throw new TypeError(`Grant agents[] URL "${agent.url}" is not a valid agent origin`);
+  }
+}
+function createTrustRecord(record) {
+  assertPublishableTrustRecord(record);
   return structuredClone(record);
 }
 class TrustEvaluator {
@@ -308,13 +335,15 @@ function authorityGroup(operator) {
   const provider = (0, import_tldts.parse)(operator).domain;
   return `private:${provider ?? operator}`;
 }
+function grantsScope(grant, scope) {
+  return grant.scopes.some(
+    (granted) => granted === "*" || granted === scope || granted === "adcp:all" && scope.startsWith("adcp:")
+  );
+}
 function grantMatches(grant, target, claim, now) {
-  if ((0, import_etld.eTldPlusOne)(grant.grantee) !== target) return false;
-  if (!grant.scopes.some(
-    (scope) => scope === "*" || scope === claim.scope || scope === "adcp:all" && claim.scope.startsWith("adcp:")
-  ))
-    return false;
-  if (grant.agents && !grant.agents.some((agent) => (0, import_canonicalize.canonicalAgentOrigin)(agent.url) === (0, import_canonicalize.canonicalAgentOrigin)(claim.signerOrigin)))
+  if (registrableGrantee(grant.grantee) !== target) return false;
+  if (!grantsScope(grant, claim.scope)) return false;
+  if (grant.agents && !grant.agents.some((agent) => grantAgentOrigin(agent.url) === (0, import_canonicalize.canonicalAgentOrigin)(claim.signerOrigin)))
     return false;
   const brands = grant.profiles?.adcp?.brands;
   if (brands && !brands.includes("*") && (!claim.brand.brand_id || !brands.includes(claim.brand.brand_id)))
@@ -361,11 +390,10 @@ async function authorizeDemandGrant(claim, options) {
       if (second) return result("trust", [brand, account, operator], [first[0], second]);
     }
   }
-  const covered = (record.record.grants ?? []).some(
-    (g) => ((0, import_etld.eTldPlusOne)(g.grantee) === account || selfOperated && (0, import_etld.eTldPlusOne)(g.grantee) === operator) && g.scopes.some(
-      (scope) => scope === "*" || scope === claim.scope || scope === "adcp:all" && claim.scope.startsWith("adcp:")
-    )
-  );
+  const covered = (record.record.grants ?? []).some((g) => {
+    const grantee = registrableGrantee(g.grantee);
+    return grantee !== void 0 && (grantee === account || selfOperated && grantee === operator) && grantsScope(g, claim.scope);
+  });
   if (!covered && !record.record.exclusive_grants && await options.sellerAuthorization?.(claim))
     return result("seller", [brand, account, operator]);
   throw new IdentityAuthorizationError("grant_absent");
@@ -376,6 +404,7 @@ async function authorizeDemandGrant(claim, options) {
   TrustEvaluator,
   TrustMembershipError,
   TrustRecordUnavailableError,
+  assertPublishableTrustRecord,
   authorizeDemandGrant,
   createTrustRecord,
   validateIdentity33Schema,