DEV Community: Dimitrios S. Sfyris

Agent-Ready Commerce, Part 10: The Reference Architecture

Dimitrios S. Sfyris — Tue, 30 Jun 2026 16:20:32 +0000

The reference architecture for agent-ready commerce has one central rule:

Every external surface should be a projection of the same commerce decision spine.

A storefront, product feed, MCP-style tool, ACP- or UCP-style interaction, AP2-related payment flow, marketplace API, admin UI, support view, and future agent interface may all need different shapes of response.

Throughout this article, projection has a broad meaning: a surface-specific view of the same decision. Generated-claim projection is the strictest version of that idea because it decides whether specific language may be used, not just how a response should be shaped.

They should not produce different commercial meanings.

If one surface says a product is checkout-ready and another blocks checkout, the architecture has drifted.

If one adapter quotes a return policy and another says return-policy coverage is missing, the architecture has drifted.

If a generated summary says a product is ready to ship while eligibility says inventory is stale, the architecture has drifted.

If a payment artifact causes payment to proceed while checkout state is not valid for payment, the architecture has failed.

Agent-ready commerce is not a chatbot attached to a store. It is not only a product feed. It is not an adapter for a protocol. It is not a payment token. It is not generated product copy.

It is a commerce platform that can expose its facts, policies, actions, state transitions, authority boundaries, generated claims, and evidence to agents without losing control of commercial meaning.

That requires a decision-centered architecture.

Series context

This is the tenth and final article in the Agent-Ready Commerce series.

Part 1 introduced the broader architecture model:

Facts → Eligibility → Authority → State transition → Evidence → Audit

Part 2 focused on commercial truth. It argued that catalog data is not enough. A platform needs source-backed, freshness-aware product facts before agents or other systems can safely rely on product information.

Part 3 focused on action eligibility. It argued that “available” is too broad. A product may be discoverable but not checkout-ready, comparable but not policy-quotable, or checkout-ready for a human flow but not eligible for delegated payment.

Part 4 focused on policy structure. It argued that agents should not interpret free-text policy pages as executable rules. Policies need structured facts with applicability, evidence, lifecycle, conflicts, and quotability.

Part 5 focused on protocol adapters. It argued that ACP, UCP, MCP, AP2-related flows, feeds, tools, and future interfaces should translate domain decisions rather than becoming separate sources of commercial meaning.

Part 6 focused on checkout state. It argued that checkout is where agent-ready commerce crosses from answering into mutating commercial state. Checkout should therefore use explicit checkout state with controlled transitions, not a loose form endpoint.

Part 7 focused on delegated payment. It argued that a payment artifact is not enough. Delegated payment requires bounded authority over a specific checkout snapshot, amount, currency, merchant, actor, buyer, time window, evidence, and audit.

Part 8 focused on generated claims. It argued that generated commerce text should be treated as a derived claim that is projectable only with source, freshness, scope, surface, use, payload integrity, direct parent-projection binding, inherited refusal state, invalidation, expiry, and audit.

Part 9 focused on evidence and audit. It argued that agent-ready commerce needs canonical decision envelopes, hash-pinned evidence references, and meaningful event history, not just logs.

This final article connects the pieces into a reference architecture.

The central argument is that agent-ready commerce should be built around a shared decision spine:

Source systems
      ↓
Commercial truth
      ↓
Policy facts
      ↓
Action-specific eligibility
      ↓
Actor authority
      ↓
Checkout state
      ↓
Payment authority
      ↓
Generated-claim projection state
      ↓
Evidence and meaningful event history
      ↓
Protocol-safe projections
      ↓
Operator remediation

Protocols and channels sit at the edges. They do not own the meaning.

The architecture is not a topology

A reference architecture is not the same thing as a deployment diagram.

The system can be implemented as:

a modular monolith
a set of services
a workflow-based platform
an event-driven architecture
a hybrid

The deployment shape matters less than the semantic boundaries.

A small team may implement commercial truth, policy facts, eligibility, checkout, generated claims, and audit as modules inside one application.

A larger organization may split them into services.

Both can work.

The important questions are different:

Can adapters bypass eligibility?
Can feeds publish readiness without decision envelopes?
Can checkout proceed without policy coverage?
Can payment proceed without valid checkout state?
Can generated claims bypass review and allowed use?
Can policy summaries become quotable without policy facts?
Can admin UI compute readiness differently from the agent feed?
Can support explain why an agent refused an action?

If the answer to those questions is yes, the architecture will drift regardless of whether it is deployed as one service or twenty.

A well-structured monolith with clear domain boundaries is safer than a distributed system with duplicated rules.

The reference architecture is about ownership of meaning.

The decision spine

The decision spine is the ordered path the platform follows to turn operational data into one explainable commercial answer.

A simplified version:

Source systems
      ↓
Commercial truth
      ↓
Policy facts
      ↓
Action-specific eligibility
      ↓
Actor authority
      ↓
Checkout state
      ↓
Payment authority
      ↓
Generated-claim projection state
      ↓
Evidence and meaningful event history
      ↓
Protocol-safe projections
      ↓
Operator remediation

Each layer answers a different question.

Layer	Question
Source systems	What data exists in operational systems?
Commercial truth	Which facts can the platform currently rely on?
Policy facts	Which terms apply in this context, and are they quotable?
Action-specific eligibility	Which requested actions are valid now?
Actor authority	Who may request the action?
Checkout state	Is the requested mutation valid from the current state?
Payment authority	Is delegated payment inside the current mandate scope?
Generated-claim projection state	Which derived language is projectable for this use?
Evidence and events	Why was the decision made, and what meaningful change occurred?
Projection	What should this audience or protocol see?
Operator remediation	What must be fixed to unblock the path?

The spine gives every surface the same starting point. Agents, adapters, feeds, generated text, and checkout flows may present the result differently, but they do not reinterpret the underlying commerce state.

The output of the spine is a decision envelope: the shared record of what was requested, what the platform decided, why it decided it, and what may safely happen next.

For generated claims, the envelope acts as a capability rather than a raw text field. A claim is usable only while its source, freshness, scope, surface, allowed use, payload integrity, direct dependencies, and inherited refusal state remain attached.

The practical envelope view remains simple: eligibility, authority, checkout, payment, generated-claim projection state, freshness, evidence references, and next safe actions.

The contract also carries decisionId, version and rule-set identity, freshness horizons, hash-pinned evidence references, three decision hashes, and an explicit authenticator.

inputDependencyHash protects the decision identity and the inputs that were evaluated.
resultHash protects the conclusions, reasons, freshness result, and next actions.
decisionHash binds those hashes to the contract and schema.

This separation lets a recipient tell whether the inputs changed, the result changed, or the contract itself changed.

Canonical serialization means that the same normalized input produces the same bytes and therefore the same hashes. Object keys, set-like collections, and date-time values must be normalized. Every reason code must also be represented by a basis component. Hard blocks must override softer review, confirmation, or revalidation states, and contradictory sections such as allowed with blockers must be rejected.

The authenticator distinguishes a detached Ed25519 digital signature, a detached HMAC-SHA-256 message-authentication code, and visibly unsigned local-development output. At an external boundary, the projection path should capture any externally supplied or persisted envelope once into a detached, deeply frozen, JSON-compatible snapshot. Integrity verification, authenticator and trusted-key validation, surface binding, freshness evaluation, live action/subject/actor binding, and projection should all consume that same captured value. Action-bearing external surfaces must reject stale allowed output; administrative and support projections may expose stale context for diagnosis without authorizing execution. Before changing state, the platform should compare the decision's protected dependency hashes with current authoritative snapshots and require a fresh decision when a dependency is missing, changed, or expired.

A projection should receive the value prepared for its surface. It should not read raw claim text and decide locally whether the text is safe.

A claim refused for this use is different from a claim that never existed or was never grounded. If a new claim uses an upstream projection, it should bind that exact parent and request context. Any refusal or stale state from the parent should remain visible in the child.

The Travel Backpack end-to-end

Use the running example one final time:

Product: Travel Backpack
SKU: BAG-TRAVEL-42
Price: €129
Catalog status: active
Inventory status: in_stock
Category: Travel Bags

The commercial truth layer currently says:

Price: fresh
Inventory: stale
Return policy: missing for Travel Bags
Warranty policy: known
Shipping policy: known for EU, unknown for US
Generated description: pending review
Feed publication: last published yesterday

The action matrix is:

Action	Result
`discover`	allowed
`compare`	allowed
`quote_policy`	blocked
`add_to_cart`	requires_revalidation
`prepare_checkout`	blocked
`delegate_payment`	blocked
`show_generated_claim`	requires_review
`explain`	allowed from decision basis

Now suppose an agent asks:

Can you buy the Travel Backpack for the buyer if the total stays under €150?

A channel-first implementation may try to answer inside the adapter:

Product active?
Inventory says in_stock?
Price below €150?
Payment artifact present?
Proceed.

That is unsafe.

A decision-centered platform follows the spine:

Protocol request
      ↓
Canonical intent
      ↓
Commercial truth selection
      ↓
Policy coverage check
      ↓
Eligibility decision
      ↓
Checkout state decision
      ↓
Payment authority decision
      ↓
Evidence and audit
      ↓
Protocol-safe projection
      ↓
Operator tasks

The correct result is:

Delegated payment is blocked.

Reason:
Checkout state is not valid for payment.

Checkout blockers:
- inventory requires revalidation
- return-policy coverage is missing for Travel Bags

Payment:
not attempted

Operator tasks:
- revalidate inventory
- attach or approve return-policy coverage for Travel Bags

This answer is not produced by an adapter improvising.

It is produced by the platform’s decision path.

That is the architectural goal.

Source systems provide inputs, not truth

Source systems may include:

Catalog systems
PIM
ERP
Inventory services
Pricing systems
Promotion systems
Shipping systems
Tax systems
Policy documents
Merchant configuration
CMS
Payment providers
Order management
Identity and account systems
Support systems
Operator input

These systems contain important data. But their data is not automatically safe for agent use.

A catalog field may say the product is active. That does not mean checkout can be prepared.

An inventory source may say in_stock. That does not mean the inventory fact is fresh enough for payment or fulfillment.

A policy page may describe returns. That does not mean a quotable return-policy fact applies to this product, category, region, buyer type, and channel.

A payment provider may authorize a payment. That does not mean the order has been committed.

The ingestion layer should therefore convert source inputs into referenced facts.

type SourceRef = {
  system: string;
  objectType: string;
  objectId: string;
  sourceRef?: string;
  url?: string;
  sourceHash?: string;
  capturedAt: string;
};

type SourceBackedFact<TValue> = {
  factId: string;

  domain:
    | "product"
    | "price"
    | "inventory"
    | "shipping"
    | "returns"
    | "warranty"
    | "checkout"
    | "payment";

  subject: {
    productId?: string;
    sku?: string;
    categoryId?: string;
    region?: string;
    buyerType?: "consumer" | "business";
  };

  value: TValue;

  sourceRefs: SourceRef[];

  freshness: {
    status: "fresh" | "stale" | "expired" | "unknown";
    evaluatedAt: string;
    expiresAt?: string;
  };

  lifecycle: {
    status: "active" | "superseded" | "invalidated";
    validFrom: string;
    validTo?: string;
  };
};

This layer answers:

Where did the fact come from?
When was it captured?
Which source reference was used?
Is it still fresh?
Has it been superseded?
Is it scoped to this product, category, buyer, region, or channel?

Without this layer, every downstream decision becomes weaker.

Commercial truth is the first platform boundary

Commercial truth is the set of source-backed facts the platform can currently rely on.

It is not a copy of the catalog.

It is not the product page.

It is not generated copy.

It is a decision input.

For the Travel Backpack:

Catalog:
active
in_stock
€129

Commercial truth:
price fresh
inventory stale
return policy missing for Travel Bags
EU shipping known
US shipping unknown
generated description pending review

The difference is the architecture.

A product may be active but not checkout-ready.

A product may have a price but not a fresh enough price for payment.

A product may have a policy page but no quotable policy fact.

A product may have generated copy but no approved generated claim.

A commercial truth snapshot may look like this:

type AgentCommerceCommercialTruthSnapshot = {
  snapshotId: string;

  subject: {
    productId?: string;
    sku?: string;
    categoryId?: string;
  };

  selectedFacts: SourceBackedFact<unknown>[];

  missingFacts: Array<{
    domain: string;
    reason: string;
    requiredFor: string[];
  }>;

  conflicts: Array<{
    conflictId: string;
    domain: string;
    factIds: string[];
    resolution: "unresolved" | "resolved" | "ignored";
  }>;

  evaluatedAt: string;
};

The snapshot may be stored, cached, or computed on demand. The important property is consistency.

Feeds, adapters, checkout, generated claims, and admin UI should not each select different truth.

Policy facts are not policy pages

Policy pages communicate terms to humans.

Policy facts support machine decisions.

A policy layer should turn returns, shipping, warranty, cancellation, regional restrictions, and business-buyer rules into structured facts with applicability and quotability.

type PolicyFact = {
  policyFactId: string;

  domain:
    | "returns"
    | "shipping"
    | "warranty"
    | "cancellation"
    | "regional_restriction"
    | "business_buyer_rule";

  applicability: {
    productId?: string;
    categoryId?: string;
    region?: string;
    buyerType?: "consumer" | "business";
    channel?: "storefront" | "agent" | "marketplace" | "support";
  };

  value: unknown;

  quotability: {
    status: "quotable" | "not_quotable" | "requires_review";
    reason?: string;
  };

  sourceRefs: SourceRef[];

  lifecycle: {
    status: "active" | "superseded" | "invalidated";
    validFrom: string;
    validTo?: string;
  };

  freshness: {
    status: "fresh" | "stale" | "expired" | "unknown";
    evaluatedAt: string;
  };
};

For the Travel Backpack:

Warranty policy:
known

EU shipping:
known

US shipping:
unknown

Return policy for Travel Bags:
missing

A generated summary cannot fill that gap.

An adapter cannot quote a generic return page and treat it as applicable.

A checkout flow cannot assume return terms are available because the category has a public policy page somewhere.

The policy layer owns applicability and quotability.

That ownership prevents agents from over-quoting policy language.

Eligibility is action-specific

Eligibility prevents available from becoming an unsafe boolean.

The platform should evaluate actions separately:

discover
compare
quote_policy
add_to_cart
prepare_checkout
delegate_payment
complete_checkout
show_generated_claim
explain

Each action has different requirements.

type AgentCommerceDecisionAction =
  | "discover"
  | "compare"
  | "quote_policy"
  | "add_to_cart"
  | "prepare_checkout"
  | "delegate_payment"
  | "complete_checkout"
  | "show_generated_claim"
  | "explain";

type AgentCommerceDecisionEligibilitySection = {
  result:
    | "allowed"
    | "blocked"
    | "requires_review"
    | "requires_revalidation"
    | "requires_confirmation";
  blockerCodes: readonly string[];
  source: "product" | "policy" | "checkout" | "payment" | "operator" | "combined";
};

The canonical envelope carries this eligibility section beside actor authority, checkout state, payment authority, generated-claim projection state, freshness, the action-aware decision basis, rule-set identity, hashes, authenticator metadata, evidence references, and next safe actions.

For the Travel Backpack:

discover:
allowed

compare:
allowed

quote_policy:
blocked because return-policy coverage is missing

add_to_cart:
requires_revalidation because inventory is stale

prepare_checkout:
blocked because inventory is stale and return-policy coverage is missing

delegate_payment:
blocked because checkout state is not valid for payment

show_generated_claim:
action result requires_review; canonical claim status inherited_refusal
stale and review details remain visible in axes and blockers

explain:
allowed from the action-aware decision basis

This layer should be shared by every surface.

The feed should not compute action eligibility separately.

The adapter should not infer checkout readiness from product status.

The admin UI should not show a different readiness result from the agent feed.

Eligibility is the action boundary.

Authority is separate from eligibility

Eligibility answers:

Is this action valid in this commercial context?

Authority answers:

May this actor request this action?

Those are different questions.

A product may be eligible for checkout, but an agent may not be authorized to prepare checkout for a buyer.

A buyer may authorize an agent to buy an item, but checkout validation may still fail.

A payment artifact may exist, but mandate scope may not match the cart snapshot.

A support operator may view blockers but not request payment.

Authority belongs in its own layer.

type ActorContext = {
  actorId: string;
  actorType: "human" | "agent" | "system";
  buyerId?: string;
  buyerType?: "consumer" | "business";
};

type AuthorityDecision = {
  authorityDecisionId: string;

  actor: ActorContext;

  requestedAction:
    | "add_to_cart"
    | "prepare_checkout"
    | "delegate_payment"
    | "complete_checkout"
    | "create_payment_mandate"
    | "consume_payment_mandate"
    | "revoke_payment_mandate"
    | "complete_delegated_payment";

  target: {
    cartId?: string;
    checkoutId?: string;
    cartSnapshotId?: string;
    mandateId?: string;
  };

  result:
    | "allowed"
    | "blocked"
    | "requires_confirmation"
    | "expired"
    | "revoked";

  blockers: Array<{
    code: string;
    message: string;
    nextAction?: string;
  }>;

  evidenceRefs: Array<{ type: string; id: string; hash: string; hashAlgorithm: "sha256" }>;
  evaluatedAt: string;
};

Part 7 introduced the delegated payment authority question:

May this actor request this payment action for this buyer, merchant, checkout snapshot, amount, currency, and time window?

That question should not be answered inside a payment adapter.

It should be answered by the platform authority layer.

Checkout is the mutation boundary

Checkout is where the platform crosses from answering into mutating commercial state.

The reference architecture should treat checkout as explicit checkout state with controlled transitions, not as a form endpoint.

type AgentCommerceCheckoutLifecycleState =
  | "created"
  | "empty"
  | "requires_address"
  | "requires_shipping_option"
  | "requires_payment"
  | "requires_revalidation"
  | "blocked"
  | "payment_authorized"
  | "order_submitted"
  | "completed"
  | "declined"
  | "cancelled"
  | "expired"
  | "failed";

type AgentCommerceCheckoutOperation =
  | "create"
  | "read"
  | "update"
  | "confirm"
  | "complete"
  | "cancel"
  | "expire";

Adapters should not perform hidden checkout mutations.

They should map external requests into commands.

async function protocolAdapterHandler(req: ProtocolRequest) {
  const operation = mapToCheckoutOperation(req);
  const result = await checkout.handleOperation(operation);

  return projectCheckoutOperationResult(result);
}

The checkout transition model coordinates commercial truth, policy facts, eligibility, authority, cart snapshots, idempotency, expiry, payment state, evidence, and audit.

Each command should have one authoritative replay owner. A state-changing operation should hold a command fence through the business write, bind the exact committed response hash, and require the canonical checkout record to verify the same fence. If the business mutation commits but canonical persistence fails, the command remains reconciliation-required instead of becoming safe to replay.

It should not duplicate all of those domains internally.

For the Travel Backpack:

update:
requires revalidation

prepare_checkout:
blocked

delegate_payment:
blocked because checkout state is not valid for payment

This prevents payment or order logic from discovering too late that the cart was never eligible.

Payment authority binds to checkout snapshots

Payment authority should not be modeled as a token check.

It should be modeled as bounded authority over a specific checkout snapshot.

type AgentCommerceMandateRecord = {
  mandateId: string;

  status:
    | "ACTIVE"
    | "ACCEPTED"
    | "CONSUMED"
    | "REVOKED"
    | "EXPIRED";

  buyerId: string;

  actor: {
    actorId: string;
    actorType: "human" | "agent" | "system";
  };

  scope: {
    merchantId: string;
    cartSnapshotId: string;
    maxAmount: number;
    currency: string;
    allowedActions: Array<
      | "create_payment_mandate"
      | "consume_payment_mandate"
      | "revoke_payment_mandate"
      | "complete_delegated_payment"
    >;
  };

  confirmation: {
    required: boolean;
    satisfied: boolean;
    confirmationRef?: string;
  };

  lifecycle: {
    createdAt: string;
    expiresAt: string;
    revokedAt?: string;
    usedAt?: string;
  };

  evidenceRefs: Array<{ type: string; id: string; hash: string; hashAlgorithm: "sha256" }>;
};

Before payment execution, the platform checks:

checkout state
cart snapshot match
amount
currency
merchant
expiry
revocation
confirmation
actor authority
idempotency
payment attempt state

Immediately before the provider call, the platform should persist a dispatch intent bound to the execution, provider idempotency identity, current lease or fence, and canonical provider-command hash. An expired active execution after a timeout or crash requires reconciliation through provider lookup or a verified webhook; expiry alone is not permission to dispatch again.

For the Travel Backpack, delegated payment is blocked before provider execution because checkout state is not valid for payment. Payment authority remains not_evaluated, and payment dispatch remains false.

That causal chain is important:

delegate_payment blocked
      ↓
checkout state is not valid for payment
      ↓
prepare_checkout blocked
      ↓
inventory stale
return-policy coverage missing

Payment authority cannot make checkout state valid.

It can only authorize payment if checkout state is valid for payment and the request is inside the mandate scope.

Generated claims are derived projections

Generated text should not become a parallel truth layer.

Generated claims should be stored with dependencies, scope, review status, projection axes, invalidation, expiry, and audit.

type AxisStatus = "passed" | "failed" | "not_evaluated";
type GeneratedClaimAxis = {
  status: AxisStatus;
  blockerCodes: string[];
};
type GeneratedClaimStatus =
  | "allowed"
  | "requires_review"
  | "refused_here"
  | "inherited_refusal"
  | "stale"
  | "out_of_scope"
  | "absent";

type GeneratedCommerceClaimSummary = {
  claimId: string;
  kind: GeneratedClaimKind;
  status: GeneratedClaimStatus;
  scope: GeneratedClaimScope;
  allowedUses: GeneratedClaimUse[];

  axes: Record<
    "source" | "freshness" | "scope" | "surface" | "use" | "payload" | "taint",
    GeneratedClaimAxis
  >;

  dependencies: Array<{
    type: string;
    ref: string;
    hash: string;
    hashAlgorithm: "sha256";
  }>;

  inheritedRefusalCount: number;
  expiresAt?: string;
  auditRefs: string[];
};

The compact form keeps the article readable while preserving dependency pins, allowed uses, expiry, projection axes, and inherited refusal state. An allowed claim must declare at least one allowed use, and the projection gate should bind the exact claim ID, requested use, requested surface, required value hash, and observed projected value.

When a claim identity exists and several non-allowed conditions apply, the envelope derives one overall claim status in this order: inherited_refusal, refused_here, stale, out_of_scope, requires_review, then allowed. The status absent applies only when no claim identity exists. A passed or not_evaluated axis carries no blockers, while a failed axis carries at least one blocker.

When one generated claim is derived from another projected claim, the owning record should also retain canonical dependencyRefs and a child provenance hash. Each dependency reference should bind the parent projection, its source-envelope and evidence-pin hashes, source record, request context, status, requested surface and use, and refusal kind. After projection-hash verification and deterministic ordering, the child hash should cover every direct parent actually used, including usable parents.

For the Travel Backpack:

“Ready to ship and easy to return”
should be blocked.

Reason:
inventory is stale and return-policy coverage is missing.

A different generated sentence may be safe:

This product is discoverable and comparable, but checkout is blocked because inventory requires revalidation and return-policy coverage is missing.

That sentence is safe only if it is derived from the current eligibility decisions and checkout state and approved for that use. It must also be projected with fresh source pins, bound to the direct projections actually used, and free of inherited refusal that blocks this surface.

Generated claims are useful. They are not authoritative by themselves. When a dependency invalidates a claim, the prior authority descriptor should remain available for audit. Repairing the exact parent may make the claim ready for reassessment, but authority should return only after a fresh approved value, scope, evidence, allowed use, and owner decision.

A compact generated-claim section in the decision envelope can preserve the state without exposing raw claim text:

type AgentCommerceGeneratedClaimsSection = {
  allowed: boolean;
  status:
    | "allowed"
    | "requires_review"
    | "refused_here"
    | "inherited_refusal"
    | "stale"
    | "out_of_scope"
    | "absent";
  claimIds: string[];
  sourceFactRefs: string[];
  derivedFactRefs: string[];
  allowedUses: string[];
  axes: Record<
    | "source"
    | "freshness"
    | "scope"
    | "surface"
    | "use"
    | "payload"
    | "taint",
    {
      status: "passed" | "failed" | "not_evaluated";
      blockerCodes: string[];
    }
  >;
  blockerCodes: string[];
  inheritedRefusalCount: number;
};

The envelope carries derived references and inheritedRefusalCount directly. Approved-value, claim-text, and quote-text hashes may be represented through derived references and exposed by surface projections. Expiry is governed through the envelope’s freshness dependencies and horizons rather than through a separate generated-claim expiry field.

The main decision basis should remain action-aware. If delegate_payment is blocked because checkout is invalid, a pending generated description may remain visible in generatedClaims, but it should not become the reason for the payment decision unless the requested action depends on using that claim.

Evidence and audit are product infrastructure

Part 9 argued that agent-ready commerce needs evidence records and audit timelines.

The reference architecture should treat decision envelopes, evidence references, projections, invalidation events, and audit timelines as first-class product infrastructure.

A decision envelope should answer:

What was requested?
Who requested it?
What was targeted?
Which context applied?
What was decided?
Which blockers were returned?
Which evidence supported the result?
Which projection was sent?
Which audit event recorded it?

The canonical envelope carries a compact evidence reference:

type EvidenceRef = {
  type: EvidenceKind;
  id: string;
  hash: string;
  hashAlgorithm: "sha256";
};

A separately retrievable evidence record may carry version, visibility, capture time, source location, and access policy. Keeping those details outside the canonical reference avoids copying sensitive material into every projection while preserving a content or canonical-snapshot hash for verification.

Freshness dependencies have a different job. They identify product, price, inventory, policy, checkout, mandate, generated-claim, authority, payment, or evidence inputs whose change or expiry can invalidate the decision. A dependency need not be duplicated as evidence unless it points to a substantiating or replayable artifact.

Evidence should support:

buyer-safe explanations
agent-facing blocker codes
operator remediation
support timelines
audit review
scenario testing
adapter drift detection
claim invalidation
feed republishing

Without this layer, the platform may still respond. It cannot reliably explain why.

Adapters are projection boundaries

Protocol adapters should remain thin in the sense defined in Part 5.

They may own:

protocol parsing
schema validation
authentication context extraction
request normalization
canonical intent mapping
idempotency propagation
response projection
protocol-safe error mapping

They should not own:

product truth
policy interpretation
eligibility rules
checkout state and validation
payment authority
generated commercial claims
evidence decisions
operator remediation logic

A canonical intent helps preserve the boundary:

type CommerceIntent = {
  action:
    | "discover"
    | "compare"
    | "quote_policy"
    | "add_to_cart"
    | "prepare_checkout"
    | "delegate_payment"
    | "complete_checkout"
    | "show_generated_claim"
    | "explain";

  target: {
    productId?: string;
    sku?: string;
    cartId?: string;
    checkoutId?: string;
  };

  context: {
    region?: string;
    buyerType?: "consumer" | "business";
    channel: "storefront" | "agent" | "marketplace" | "support";
    currency?: string;
  };

  actor: ActorContext;

  idempotencyKey?: string;
  correlationId?: string;

  sourceProtocol?:
    | "internal_feed"
    | "mcp"
    | "acp"
    | "ucp"
    | "ap2"
    | "marketplace_api"
    | "admin";

  requestedAt: string;
};

The adapter maps external protocol language into this intent.

The domain evaluates the intent.

Before external projection, the boundary recomputes the canonical hashes, reconciles reasons and components, verifies the authenticator and trusted key, confirms that the envelope surface matches the target surface, and compares the protected requested action, subject, and actor with the live request. Action-bearing external surfaces reject stale allowed output. Administrative and support projections may expose stale context for diagnosis without authorizing execution. A stale blocked envelope may still be projected as a refusal so the recipient receives its explanation and remediation context.

Independently verifiable output should use Ed25519. HMAC is limited to an explicitly configured shared-secret boundary, and unsigned output is local-development only. Before changing state, the platform must also verify the latest checkout revision, mandate state, product decision, or another authoritative record used to approve the operation. A signed envelope can still be within its freshness window while referring to state that has already changed.

The adapter then projects the verified result back out.

This prevents semantic drift.

Feeds are projections too

Agent-facing feeds are not neutral exports.

They are projections of commercial truth, eligibility, generated claims, and allowed actions.

A feed item should not publish optimistic readiness.

For the Travel Backpack, an unsafe feed item would say:

Product active.
Price €129.
Inventory in_stock.
Checkout ready.

A safer feed item would say:

{
  "sku": "BAG-TRAVEL-42",
  "title": "Travel Backpack",
  "price": {
    "amount": 129,
    "currency": "EUR",
    "freshness": "fresh"
  },
  "actions": {
    "discover": "allowed",
    "compare": "allowed",
    "quotePolicy": "blocked",
    "addToCart": "requires_revalidation",
    "prepareCheckout": "blocked",
    "delegatePayment": "blocked",
    "showGeneratedClaim": "requires_review",
    "explain": "allowed"
  },
  "blockers": [
    "stale_inventory",
    "missing_return_policy"
  ],
  "generatedClaims": {
    "status": "inherited_refusal",
    "claimIds": [
      "generated_claim:cabin-size-compatible",
      "generated_claim:returns-comparison-paragraph"
    ],
    "allowedUses": [],
    "axes": {
      "source": { "status": "passed", "blockerCodes": [] },
      "freshness": {
        "status": "failed",
        "blockerCodes": ["stale_inventory"]
      },
      "scope": { "status": "passed", "blockerCodes": [] },
      "surface": { "status": "passed", "blockerCodes": [] },
      "use": {
        "status": "failed",
        "blockerCodes": ["generated_claim_requires_review"]
      },
      "payload": {
        "status": "not_evaluated",
        "blockerCodes": []
      },
      "taint": {
        "status": "failed",
        "blockerCodes": ["inherited_refusal"]
      }
    },
    "blockerCodes": [
      "generated_claim_requires_review",
      "inherited_refusal"
    ],
    "inheritedRefusalCount": 1
  },
  "publishedAt": "2026-06-28T09:00:00Z"
}

The feed is compact, but it preserves the decision model.

It should be refreshed or invalidated when dependencies change.

Otherwise, downstream agents may act on stale projections.

Operator workflows close the loop

Agent-readiness is not only a runtime problem.

Many blockers are operational:

missing policy coverage
stale inventory
unreviewed generated claims
conflicting policy facts
unsupported region
expired feed projection
invalidated checkout explanation
missing payment configuration
unresolved authority workflow

The architecture should include operator tasks as part of the system.

For the Travel Backpack:

Task:
Revalidate inventory for BAG-TRAVEL-42.

Task:
Attach or approve return-policy coverage for Travel Bags.

Task:
Review generated product description.

Impact:
Agents can discover and compare the product, but cannot quote return terms, prepare checkout, or proceed to delegated payment.

Operator workflows should connect to evidence.

One durable remediation stream can move through open, acknowledged, resolved, and reopened. Repeated observations should not create duplicate work, and a blocker that returns after resolution should reopen the same stream.

When an operator resolves a blocker, the platform should refresh affected decisions, invalidate old generated claims, republish feeds, and update audit timelines.

The loop is:

Decision blocked
      ↓
Evidence recorded
      ↓
Operator task created
      ↓
Operator resolves source issue
      ↓
Fact or policy updated
      ↓
Dependent decisions invalidated or recomputed
      ↓
Generated claims refreshed
      ↓
Feeds republished
      ↓
Audit timeline updated

This is how agent-ready commerce stays current.

Runtime path: policy question

Consider a request:

What is the return policy for the Travel Backpack?

A safe runtime path:

Adapter maps request to quote_policy intent.
      ↓
Commercial truth selects product and category.
      ↓
Policy layer checks returns applicability for Travel Bags.
      ↓
Return-policy fact is missing.
      ↓
Eligibility returns blocked.
      ↓
Generated policy summary is not used.
      ↓
Evidence records missing policy coverage.
      ↓
Protocol projection returns a safe blocked answer.
      ↓
Operator task is created or linked.

The response might be:

{
  "result": "blocked",
  "reason": "missing_return_policy",
  "message": "Return-policy terms are not available for this product category.",
  "nextAction": "operator_review_required"
}

The platform does not summarize a policy page.

It does not generate plausible return terms.

It does not quote a generic policy.

It preserves the policy boundary.

Runtime path: checkout request

Now consider:

Prepare checkout for the Travel Backpack for an EU consumer buyer.

A safe runtime path:

Adapter maps request to prepare_checkout intent.
      ↓
Commercial truth snapshot selected.
      ↓
Inventory freshness checked.
      ↓
Policy coverage checked.
      ↓
Eligibility evaluates prepare_checkout.
      ↓
Checkout transition model attempts the transition.
      ↓
Transition blocked.
      ↓
Evidence and audit recorded.
      ↓
Decision-derived explanation generated or selected.
      ↓
Protocol response projected.
      ↓
Operator tasks updated.

The result:

{
  "result": "blocked",
  "requestedAction": "prepare_checkout",
  "blockers": [
    {
      "code": "stale_inventory",
      "nextAction": "request_inventory_revalidation"
    },
    {
      "code": "missing_return_policy",
      "nextAction": "operator_policy_review_required"
    }
  ]
}

The checkout service does not discover the missing policy by accident near payment.

It uses the same decision model used by feeds, adapters, support, and admin.

Runtime path: delegated payment

Now consider:

Buy the Travel Backpack if the total stays under €150.

A safe runtime path:

Adapter maps request to delegate_payment intent.
      ↓
Platform checks checkout state.
      ↓
Checkout state is not valid for payment.
      ↓
Payment authority remains not_evaluated.
      ↓
Payment dispatch remains false, and the provider is not called.
      ↓
Evidence records checkout dependency.
      ↓
Protocol response explains blocked delegated payment.
      ↓
Operator tasks point to checkout blockers.

The response:

{
  "result": "blocked",
  "requestedAction": "delegate_payment",
  "reason": "invalid_checkout_state",
  "causedBy": [
    "stale_inventory",
    "missing_return_policy"
  ],
  "paymentAttempted": false
}

This preserves the causal chain.

Payment is not attempted because checkout state is not valid for payment.

The payment artifact does not bypass checkout.

Runtime path: generated claim publication

Consider a generated description:

This backpack is ready to ship and easy to return.

A safe runtime path:

Generated claim is created.
      ↓
Claim is segmented.
      ↓
Inventory clause depends on inventory freshness.
      ↓
Return clause depends on return-policy coverage.
      ↓
Inventory is stale.
      ↓
Return policy is missing.
      ↓
Claim is rejected or remains pending review.
      ↓
Audit records unsupported segments.
      ↓
Operator tasks link to inventory and policy blockers.

The claim should not enter the agent feed.

A safer generated explanation may be allowed:

This product is discoverable and comparable, but checkout is blocked because inventory requires revalidation and return-policy coverage is missing.

Only if it is derived from current eligibility decisions and checkout state.

This preserves the generated-claim boundary.

Cross-cutting invalidation

The reference architecture needs invalidation as a cross-cutting mechanism.

When a dependency changes, projections and claims may need refresh. If a claim was derived from another projected claim, changing the parent projection, evidence pin, or request context should change the child's provenance hash. Upstream refusal or stale-source state should also continue to affect the child.

Examples:

Price changes:
Invalidate price claims, feed projections, checkout snapshots, and affected mandates.

Inventory becomes stale:
Invalidate checkout readiness and availability claims.

Return-policy fact is approved:
Supersede missing_return_policy blockers and refresh quote_policy decisions.

Generated claim is rejected:
Remove it from feeds, block agent quotation, and mark dependent projections as carrying an inherited refusal.

Checkout session expires:
Invalidate payment authority decisions tied to that checkout.

Mandate is revoked:
Block payment execution and audit the revocation.

Adapter projection bug is fixed:
Republish affected feed items or protocol projections if necessary.

A simple invalidation event:

type InvalidationEvent = {
  invalidationId: string;

  targetRef: {
    kind: string;
    id: string;
  };

  reason:
    | "source_fact_changed"
    | "source_fact_expired"
    | "policy_fact_changed"
    | "policy_conflict_detected"
    | "eligibility_rule_changed"
    | "checkout_state_changed"
    | "authority_revoked"
    | "generated_claim_invalidated"
    | "projection_superseded"
    | "manual_review";

  causedBy: {
    kind: string;
    id: string;
  };

  occurredAt: string;
};

Invalidation prevents stale truth from continuing to act as current truth.

It also lets the platform explain why an answer changed.

Component responsibility map

A reference architecture should make ownership explicit.

Component	Owns	Does not own
Source systems	Raw operational data	Agent-facing decisions
Commercial truth	Selected reliable facts, source refs, freshness	Action eligibility
Policy facts	Applicability, quotability, conflicts	Generated summaries as authority
Eligibility	Action-specific validity	Actor permission
Delegated authority	Mandate scope, confirmation, consumption, revocation	Checkout validity
Checkout application owner	Human and agent checkout behavior, current state, events	Payment authority as a shortcut
Payment	Payment attempts and provider outcomes	Order commitment without checks
Order	Order state and commitment	Payment-provider interpretation
Transaction coordinator	Cross-aggregate correlation and meaningful events	Copies of checkout, mandate, payment, or order state
Generated claims	Derived claim lifecycle and projection gate	Source truth
Decision envelope	Canonical result, reasons, freshness, hashes, evidence	Business-rule invention
Protocol and surface adapters	Context mapping and projection	Commercial meaning
Admin and support surfaces	Merchant tasks and audience-safe explanations	Separate decision logic

This table is not a deployment prescription.

It prevents drift by giving each kind of commercial meaning one owner.

Architecture invariants

The architecture should enforce a small set of invariants.

These are more important than the deployment shape.

1. Source data is not automatically truth

Every source fact needs source references, freshness, scope, lifecycle, and conflict handling.

2. Product action status is action-specific

available: true is not enough. The platform must distinguish discovery, comparison, policy quotation, cart mutation, checkout preparation, delegated payment, checkout completion, generated-claim use, and explanation.

3. Policies must be applicable and quotable

Policy pages do not automatically become agent-quotable terms.

4. Eligibility and authority are separate

A valid action is not necessarily an authorized action.

An authorized actor does not make an invalid action valid.

5. Mutations go through state transitions

Cart, checkout, payment, and order changes should not be hidden inside adapters or request handlers. One replay owner and a monotonic command fence should prevent a committed mutation from being repeated when canonical persistence or the response path fails.

6. Payment authority is bounded

A token or artifact is evidence, not permission by itself.

Payment authority must match actor, buyer, merchant, amount, currency, checkout snapshot, lifecycle, confirmation, and state. Ambiguous provider execution must reconcile before redispatch, and confirmed capture must not be repeated when only order finalization remains.

7. Generated claims remain derived

Generated text should never become source truth, policy authority, checkout validation, or payment authority. A derived claim should bind every direct parent projection actually used, not only refused parents. It should reject any parent whose stored projection hash no longer matches its semantics. Parent repair may permit reassessment, but it must not restore authority automatically.

8. Decisions need evidence

Allowed and blocked decisions should reference the facts, policies, rules, states, authority records, claims, and projections that justify them. Canonical evidence references use explicit SHA-256 hashes, while freshness dependencies identify invalidation inputs and horizons.

9. Projections must preserve meaning

Adapters and feeds may change response shape. They should not change the domain decision. Canonical reasons must reconcile with their basis components, and an external projection should verify the hashes, authenticator, trusted key, surface, and freshness before returning the result.

10. Blockers should create remediation paths

Missing facts, stale facts, policy gaps, invalidated claims, and authority blockers should produce operator-visible work when actionable. Repeated observations should converge on one lifecycle, and resolved blockers should reopen when the same condition returns.

11. Verification and use must share one captured state

An externally supplied or persisted envelope should be captured once into a detached, deeply frozen, JSON-compatible snapshot. Integrity verification, request binding, freshness evaluation, projection, and execution evaluation should consume that same value rather than re-read caller-controlled state.

These invariants are the real architecture.

Where the architecture can go wrong

A reference architecture reduces drift, but it can still fail.

The architecture becomes a diagram only

If adapters still implement local readiness checks, the diagram does not matter. The domain decision path must be the easiest path to use.

Commercial truth becomes catalog copy

If truth does not include freshness, source references, missing facts, conflicts, and lifecycle, the platform will overtrust raw data.

Policy facts are skipped

If agents or adapters summarize policy pages directly, policy applicability and quotability are bypassed.

Eligibility becomes a boolean

If the platform exposes only available: true, it loses action-specific readiness.

Authority is treated as authentication

Knowing who the actor is does not mean the actor may request checkout mutation, payment authority, or buyer delegation.

Checkout remains endpoint-driven

If checkout mutations happen inside request handlers, the platform cannot reliably enforce state, idempotency, snapshots, expiry, or audit.

Payment artifacts become permission

If a token is treated as delegated authority, the platform may bypass mandate scope, checkout state, and cart snapshot matching.

Generated claims become truth

If generated text is read back as product or policy truth, the dependency direction has inverted. Recording direct parent projections only as descriptive IDs creates another failure: a changed usable parent or request context can leave a derived claim looking falsely unchanged.

Evidence is optional

If decisions can be made without evidence references, audit will be incomplete exactly when it matters.

Operator workflow is disconnected

If blockers do not create actionable tasks, agent-readiness becomes a runtime failure instead of an operational loop.

Feeds are optimistic

If feeds publish what the storefront hopes is true rather than what the decision layer allows, agents will act on stale or unsafe projections.

Verification and use read different state

If a boundary verifies one representation but later projects or acts on a mutable caller-controlled value, the authenticated state and the state actually used can diverge. The recipient should capture once and use the same immutable value throughout the trusted path.

Scenario tests for the reference architecture

The reference architecture should be tested with end-to-end scenarios, with component tests used to keep individual decisions precise.

A useful architecture test includes:

Input source facts
Policy coverage
Generated claim state
Actor context
Buyer context
Requested action
Expected eligibility decision
Expected authority decision
Expected state transition
Expected generated claim use
Expected generated-claim dependency refs and provenance hash
Expected evidence refs
Expected contract and schema versions
Expected rule-set hash and authenticator result
Expected protocol projection
Expected operator work item
Expected invalidation behavior

For the Travel Backpack:

Scenario	Expected architecture behavior
Agent asks to discover product	Allowed; product facts referenced
Agent asks to compare product	Allowed only on known facts
Agent asks for return policy	Blocked; missing Travel Bags return-policy fact
Agent asks to add to cart	Requires inventory revalidation
Agent asks to prepare checkout	Blocked; stale inventory and missing return policy
Agent asks delegated payment	Blocked; checkout state not valid; payment authority `not_evaluated`; payment not attempted
Generated claim says “ready to ship”	Blocked or pending because inventory is stale
EU shipping claim requested for US buyer	Blocked as out of scope
Same direct parent projections arrive in a different order	Derived dependency refs and provenance hash remain identical
Usable parent, evidence pin, or request context changes	Derived provenance hash changes even if the wording does not
Parent projection is altered without updating its hash	Derivation is rejected
Unrelated refused projection is not a dependency	The derived claim remains untainted
Operator approves return-policy coverage	Policy fact becomes active; affected decisions refreshed
Inventory revalidated	Inventory blocker superseded
Feed republished	Feed projects updated eligibility decisions
Adapter projects blocked checkout as success	Semantic test catches drift
Same normalized envelope input is repeated	The three canonical hashes remain identical
`decisionId` is modified after authentication	Integrity verification rejects the envelope
Soft eligibility result is combined with a hard authority, checkout, or payment block	Canonical result remains blocked
Business mutation commits but canonical checkout persistence fails	Command remains reconciliation-required; mutation is not replayed
Active payment execution expires after an ambiguous provider call	Reconciliation is required; payment is not redispatched
Parent policy or claim is repaired after dependent invalidation	Dependent becomes ready for reassessment; authority is not restored automatically
Surface, freshness, hash, or authenticator is modified	External projection is rejected
Live requested action, subject, or actor does not match the envelope	External projection is rejected
Caller-controlled envelope changes after its first read	Boundary uses one detached immutable snapshot; the verified result does not drift
Older signed envelope is presented after checkout, mandate, or product-decision state changes	Mutation is rejected because the envelope no longer matches the latest state that controls the operation
Buyer-safe explanation requested	Internal evidence redacted, blocker meaning and projection axes preserved
Audit reconstruction requested	Decision inputs, evidence refs, rule identity, and projections available

A simplified scenario type:

type ReferenceArchitectureScenario = {
  name: string;

  sourceFacts: string[];
  policyFacts: string[];
  generatedClaims: string[];

  intent: CommerceIntent;

  expectedEligibility: EligibilityDecision["result"];
  expectedAuthority?: AuthorityDecision["result"];
  expectedCheckoutState?: AgentCommerceCheckoutLifecycleState;

  expectedBlockerCodes: string[];
  expectedEvidenceKinds: string[];
  expectedEnvelopeSchemaVersion: "agent-commerce-decision-envelope-schema-v4";
  expectedReasonComponentReconciliation: boolean;
  expectedAuthenticatorResult: "valid" | "invalid";
  expectedProjection: string;
  expectedOperatorWorkItems: string[];
};

The goal is to test whether the architecture preserves meaning across layers.

The same scenario should not produce one answer in the feed, another in the tool adapter, another in checkout, and another in admin.

A practical implementation roadmap

A platform does not need to implement the full architecture at once.

A practical roadmap:

Define the action vocabulary.
Start with discover, compare, quote_policy, add_to_cart, prepare_checkout, delegate_payment, complete_checkout, show_generated_claim, and explain.
Build commercial truth snapshots.
Add source references, freshness, missing facts, conflicts, and lifecycle.
Structure policy facts.
Model returns, shipping, warranty, cancellation, regional restrictions, and business-buyer rules with applicability and quotability.
Add eligibility decisions.
Produce action-specific allowed, blocked, requires_review, requires_revalidation, and requires_confirmation decisions.
Keep adapters thin.
Map external protocol requests into canonical intents. Capture externally supplied or persisted envelopes once into a detached, deeply frozen, JSON-compatible snapshot, then use that same value for hash verification, reason/component reconciliation, authenticator and trusted-key validation, target-surface binding, live action/subject/actor binding, freshness evaluation, and projection. Before changing state, compare protected dependency hashes with current authoritative snapshots and require a fresh decision when a dependency is missing, changed, or expired.
Move checkout behind commands.
Introduce explicit checkout states, cart snapshots, idempotency, expiry, and transition audit.
Model payment authority.
Bind mandates to actor, buyer, merchant, amount, currency, cart snapshot, expiry, revocation, and confirmation.
Store generated claims as records.
Attach dependencies, scope, review status, allowed use, projection axes, inherited refusal state, value hashes, invalidation, expiry, and audit. For claims derived from projected claims, verify and bind every direct parent projection, including usable parents, into the child’s canonical provenance hash.
Add decision evidence.
Attach explicit SHA-256 content or canonical-snapshot evidence references to allowed and blocked decisions. Keep invalidation dependencies and their horizons distinct from replayable evidence.
Build operator remediation.
Create tasks from missing facts, stale facts, policy gaps, generated-claim review, checkout blockers, and authority blockers.
Publish feeds from decisions.
Do not publish readiness from catalog flags alone.
Add invalidation.
Refresh decisions, claims, feeds, and tasks when dependencies change.
Keep one coherent cross-surface semantic test suite.
Use the same scenario set across feeds, tools, adapters, checkout, payment, admin, and support. Test semantic parity, reason/component reconciliation, deterministic hashes, direct dependency-projection binding, verified-state identity, execution-time dependency revalidation, and external-boundary refusal without relying on broad response snapshots or route counts.

This roadmap builds the architecture in layers while reducing the highest-risk drift first. It should not turn every concept into a permanent subsystem.

The tradeoff

The reference architecture adds structure.

It requires facts, policy modeling, eligibility decisions, authority checks, checkout transition models, generated-claim lifecycle, evidence, audit, projections, invalidation, and operator workflows.

That is more work than adding an agent endpoint to an existing storefront.

For simple read-only product discovery, a lighter approach may be enough for a while.

Agent-ready commerce changes the threshold when agents can quote policies, compare products, prepare checkout, operate under buyer authority, explain payment refusal, or act across multiple protocols.

The tradeoff is between local integration speed and platform consistency.

A shortcut can make one adapter work.

A reference architecture keeps the platform from developing several incompatible versions of commercial truth.

The goal is not to make commerce rigid.

The goal is to make commercial decisions explicit enough that agents can use them safely.

The series in one model

The full series can be reduced to one chain:

Facts
      ↓
Commercial truth
      ↓
Policy facts
      ↓
Eligibility
      ↓
Authority
      ↓
State transition
      ↓
Generated claims
      ↓
Evidence
      ↓
Audit
      ↓
Adapters and projections
      ↓
Operator remediation

Each article strengthened one link.

Part 1 introduced the model.

Part 2 made facts source-backed and freshness-aware.

Part 3 made readiness action-specific.

Part 4 made policies machine-readable and quotability-aware.

Part 5 kept protocol adapters from owning commercial meaning.

Part 6 turned checkout into explicit state transitions.

Part 7 treated delegated payment as bounded authority over a checkout snapshot.

Part 8 treated generated text as derived claims with lifecycle, scoped projection, and direct parent-projection binding.

Part 9 made evidence and audit part of the product.

Part 10 connects those ideas into a complete reference architecture.

The architecture is not about letting agents do everything.

It is about making clear what agents may know, say, request, mutate, and pay for, and why.

Conclusion

Agent-ready commerce is a platform capability.

It is not a product feed alone. It is not a chatbot. It is not a protocol adapter. It is not a payment token. It is not generated product copy. It is not a single admin toggle.

It is a commerce architecture where facts, policies, eligibility, authority, checkout state, payment boundaries, generated claims, evidence, audit, projections, and operator workflows are connected.

For the Travel Backpack, the architecture gives a precise answer:

Discover:
allowed

Compare:
allowed on known facts

Quote return policy:
blocked because return-policy coverage is missing for Travel Bags

Add to cart:
requires inventory revalidation

Prepare checkout:
blocked because inventory is stale and return-policy coverage is missing

Delegate payment:
blocked because checkout state is not valid for payment
payment authority: not_evaluated
payment dispatch: not attempted

Generated claim:
show_generated_claim action: requires_review
canonical claim status: inherited_refusal; inheritedRefusalCount: 1

Operator tasks:
revalidate inventory
approve return-policy coverage
review generated claim

That is the difference between catalog availability and agent-ready commerce.

The platform does not need to guess.

The adapter does not need to invent rules.

The generated text does not become truth.

The payment artifact does not bypass checkout.

The audit trail can explain the decision.

That is the reference architecture this series has been building toward.

About the author

Written by Dimitrios S. Sfyris, Founder & Software Architect at AspectSoft.

AspectSoft designs and develops custom software platforms, e-commerce systems, SaaS infrastructure, integrations, analytics tools, and practical digital products.

You can also follow the AspectSoft LinkedIn page for updates on software platforms, commerce systems, AI tooling, and developer-focused products.

Agent-Ready Commerce, Part 9: Evidence and Audit Are Part of the Product

Dimitrios S. Sfyris — Tue, 30 Jun 2026 15:56:15 +0000

An agent-ready commerce platform does not only need to answer, refuse, or act.

It needs evidence explaining why it answered, refused, or acted.

That evidence cannot be reconstructed reliably from vague logs after something goes wrong. It has to be captured at the moment the platform makes the decision.

When an agent says a product can be compared, the platform should know which product facts supported the comparison.

When an agent refuses to quote a return policy, the platform should know which policy coverage was missing.

When checkout is blocked, the platform should know which facts, rules, policies, state transitions, or authority checks blocked it.

When delegated payment is refused, the platform should know whether the blocker was checkout validation, checkout state, mandate scope, cart snapshot mismatch, amount limit, currency mismatch, expiry, revocation, confirmation, provider state, or order commitment.

When a generated claim is quoted, the platform should know which facts, decisions, review status, allowed use, and expiry window made it safe at that time. The envelope should preserve that basis, while the audience-facing explanation should show only the detail the audience needs.

This is not ordinary logging.

Logs describe activity.

Evidence explains the basis of a decision.

Audit makes that explanation durable.

Agent-ready commerce needs evidence that survives beyond the request.

Series context

This is the ninth article in the Agent-Ready Commerce series.

Part 1 introduced the broader architecture model:

Facts → Eligibility → Authority → State transition → Evidence → Audit

Part 8 focused on generated claims. It argued that generated commerce text should be treated as a derived claim with dependencies, scope, review status, allowed use, invalidation, expiry, and audit, with each direct parent projection bound into the child’s canonical provenance.

This article focuses on evidence and audit.

The central argument is that evidence and audit are not backend observability details. They are product capabilities. Agent-ready commerce needs decision envelopes, evidence references, replayable inputs, protocol-safe explanations, recorded projection evidence, operator timelines, and audit trails because agents turn platform decisions into buyer-facing answers and commercial actions.

A safe platform follows this chain:

Request
      ↓
Decision
      ↓
Evidence record
      ↓
Protocol-safe explanation
      ↓
Projection or state transition
      ↓
Audit event
      ↓
Operator and support timeline

Without that chain, the platform may know what happened, but it cannot explain why it happened.

Logs are not evidence

Logs are useful.

They help engineers debug systems. They capture service calls, timings, warnings, exceptions, queue events, request identifiers, and operational details.

But logs are not enough for agent-ready commerce.

A log line such as:

checkout blocked for BAG-TRAVEL-42

does not explain the decision.

It does not say which checkout command was requested. It does not say which actor requested it. It does not say whether inventory was stale, which policy facts were missing, or which eligibility rule applied. It also omits the payment-authority state, the checkout state before the command, the returned blocker codes, and the explanation shown to the agent.

A better record answers:

Which action was requested?
Which actor requested it?
Which product, cart, checkout, claim, or mandate was targeted?
Which facts were selected?
Were those facts fresh?
Which policy facts applied?
Which required facts were missing?
Which rule identity evaluated the action?
Which authority record was checked?
Which state transition was attempted?
Which result was produced?
Which explanation was projected?
Which audit event recorded it?

That is evidence.

A useful distinction is:

Log:
A technical record that something happened.

Evidence:
A structured reference to the facts, policies, rules, states, authority records, generated claims, and decisions that justified the result.

Audit:
A durable history of decisions, projections, transitions, explanations, evidence use, invalidations, and remediation.

Logs support debugging.

Evidence supports decision trust.

Audit supports accountability, replay, support, remediation, and dispute handling.

Agent-ready commerce needs all three, but they are not the same layer.

The Travel Backpack example

Continue with the running example from Parts 2–8:

Product: Travel Backpack
SKU: BAG-TRAVEL-42
Price: €129
Catalog status: active
Inventory status: in_stock
Category: Travel Bags

The commercial truth layer currently says:

Price: fresh
Inventory: stale
Return policy: missing for Travel Bags
Warranty policy: known
Shipping policy: known for EU, unknown for US
Generated description: pending review
Feed publication: last published yesterday

From Part 3, the action matrix was:

Action	Result
`discover`	allowed
`compare`	allowed
`quote_policy`	blocked
`add_to_cart`	requires_revalidation
`prepare_checkout`	blocked
`delegate_payment`	blocked

Now suppose an agent asks:

Can you buy the Travel Backpack for the buyer if the total stays under €150?

The platform should not produce only this:

{
  "allowed": false
}

It should produce a decision with evidence.

A useful response may say:

Delegated payment is blocked because checkout state is not valid for payment.

Checkout cannot be prepared because:
- inventory requires revalidation
- return-policy coverage is missing for Travel Bags

Internally, the platform should preserve the decision path:

delegate_payment
      ↓ blocked because checkout state is not valid for payment

prepare_checkout
      ↓ blocked because inventory is stale
      ↓ blocked because return-policy coverage is missing

quote_policy
      ↓ blocked because no return-policy fact applies to Travel Bags

That evidence path matters because different users need different projections.

The buyer may need a concise explanation.

The agent may need structured blocker codes.

The operator may need remediation tasks.

Support may need a customer-safe timeline.

The auditor may need source facts, decision envelopes, rule identities, protocol projections, and timestamps.

The same decision needs multiple views, but it should come from one evidence chain.

Evidence belongs to allowed decisions too

Evidence should not be attached only to failures.

Blocked decisions are important because they explain refusal. Allowed decisions are equally important because they explain reliance.

If an agent is allowed to compare two products, the platform should know which product facts supported the comparison.

If an agent is allowed to quote warranty coverage, the platform should know which warranty policy fact applied.

If checkout is prepared, the platform should know which price, inventory, policy, shipping, tax, and cart snapshot records were used.

If delegated payment is allowed, the platform should know which mandate, cart snapshot, checkout state, amount, currency, merchant binding, expiry check, revocation check, and confirmation record supported the authority decision.

The audit question is not only:

Why did the platform block this?

It is also:

Why did the platform allow this?

A useful rule is:

If the platform can expose an answer or perform an action, it should know what evidence allowed it.

Otherwise, the system may be correct at runtime but unexplainable later.

Decision envelopes are the core artifact

A decision envelope connects the request, its context, the result, the supporting evidence, the explanation, and any meaningful event that followed.

It is canonical because every surface starts from this shared record instead of calculating a separate commercial answer.

A compact model:

type DecisionResult =
  | "allowed"
  | "blocked"
  | "requires_review"
  | "requires_revalidation"
  | "requires_confirmation";

type AgentCommerceDecisionEnvelopeAuthenticator =
  | {
      kind: "digital_signature";
      algorithm: "ed25519";
      format: "detached";
      keyId: string;
      verificationKeyRef: string;
      protectedHash: string;
      value: string;
      verifiable: true;
    }
  | {
      kind: "message_authentication_code";
      algorithm: "hmac-sha256";
      format: "detached";
      keyId: string;
      verificationKeyRef: string;
      protectedHash: string;
      value: string;
      verifiable: true;
    }
  | {
      kind: "unsigned";
      algorithm: "none";
      format: "none";
      protectedHash: string;
      verifiable: false;
      warning: "missing_platform_signing_key";
    };

type AgentCommerceDecisionEnvelope = {
  contractVersion: "agent-commerce-decision-envelope-v4";
  envelopeSchemaVersion: "agent-commerce-decision-envelope-schema-v4";
  decisionId: string;
  decisionHash: string;
  inputDependencyHash: string;
  resultHash: string;
  evaluatedAt: string;
  ruleSetVersion: string;
  ruleSetRef: string;
  ruleSetHash: string;
  authenticator: AgentCommerceDecisionEnvelopeAuthenticator;
  surface?: "feed" | "tool" | "checkout" | "admin" | "support" | "protocol";
  requestedAction: AgentCommerceDecisionAction;
  actor: {
    actorType: "agent" | "buyer" | "merchant" | "operator" | "system";
    agentId?: string;
    merchantId?: string;
  };
  subject: {
    productId?: string;
    variantId?: string;
    sku?: string;
    checkoutId?: string;
    mandateId?: string;
    orderId?: string;
  };
  basis: {
    status: DecisionResult;
    allowed: boolean;
    reasonCodes: readonly string[];
    components: readonly {
      code: string;
      source: "eligibility" | "authority" | "checkout" | "payment" | "generated_claim";
      field: string;
      value: string | number | boolean | null;
      contributesTo: "status" | "payment_dispatch" | "generated_claim_use";
    }[];
  };
  freshness: {
    evaluatedAt: string;
    validUntil: string | null;
    staleAfter: string | null;
    reasonCodes: readonly string[];
    dependencies: readonly {
      ref: string;
      kind: string;
      validUntil?: string | null;
      staleAfter?: string | null;
      hash?: string | null;
    }[];
  };
  evidenceRefs: readonly { type: string; id: string; hash: string; hashAlgorithm: "sha256" }[];
  nextSafeActions: readonly {
    action: string;
    owner: "system" | "operator" | "buyer" | "merchant";
    reasonCode: string;
  }[];
};

The complete envelope also carries input references, eligibility, authority, checkout, payment, and generated-claim projection state.

Its hashes divide responsibility clearly:

inputDependencyHash protects what was evaluated, including decisionId, surface, action, actor, subject, rules, evidence, and freshness dependencies.
resultHash protects what the platform concluded, including eligibility, authority, checkout, payment, generated claims, freshness, reasons, and next actions.
decisionHash binds those two hashes to the declared contract and schema.

The canonical serializer should produce the same bytes for the same normalized input. Object keys are stable, set-like collections are normalized, and valid date-time inputs are converted to one UTC representation before hashing. The canonical reason invariant is also exact: the set of basis.reasonCodes equals the set of basis.components[].code.

The authenticator protects that decision context according to its declared trust model. Before returning an external projection, the boundary should capture any externally supplied or persisted envelope once into a detached, deeply immutable representation. Hash recomputation, reason/component reconciliation, authenticator verification, trusted-key validation, surface binding, live-request binding, freshness evaluation, and projection should all consume that same captured value. A stale envelope must not be projected as allowed. A blocked envelope may still be projected as a refusal so the recipient receives its explanation and remediation context.

Before changing state, the platform should compare the decision's protected dependency hashes with current authoritative snapshots. A missing, changed, or expired dependency requires a fresh decision. An older envelope may still be signed and within its original freshness window even though it no longer describes the state that controls the operation.

An abbreviated illustrative prepare_checkout envelope might look like this:

{
  "contractVersion": "agent-commerce-decision-envelope-v4",
  "envelopeSchemaVersion": "agent-commerce-decision-envelope-schema-v4",
  "decisionId": "decision:travel-backpack:prepare-checkout",
  "decisionHash": "1111111111111111111111111111111111111111111111111111111111111111",
  "inputDependencyHash": "2222222222222222222222222222222222222222222222222222222222222222",
  "resultHash": "3333333333333333333333333333333333333333333333333333333333333333",
  "evaluatedAt": "2026-07-06T10:12:00.000Z",
  "ruleSetVersion": "agent-commerce-decision-rules-v4",
  "ruleSetRef": "ruleset:sha256:5555555555555555555555555555555555555555555555555555555555555555",
  "ruleSetHash": "5555555555555555555555555555555555555555555555555555555555555555",
  "authenticator": {
    "kind": "digital_signature",
    "algorithm": "ed25519",
    "format": "detached",
    "keyId": "platform-key:decision-envelope",
    "verificationKeyRef": "public-key:decision-envelope",
    "protectedHash": "1111111111111111111111111111111111111111111111111111111111111111",
    "value": "<base64url-ed25519-signature>",
    "verifiable": true
  },
  "surface": "checkout",
  "subject": {
    "productId": "product:travel-backpack",
    "checkoutId": "checkout:travel-backpack:example"
  },
  "actor": {
    "actorType": "agent",
    "agentId": "agent:reference-shopper",
    "merchantId": "merchant:travel-demo"
  },
  "requestedAction": "prepare_checkout",
  "freshness": {
    "evaluatedAt": "2026-07-06T10:12:00.000Z",
    "validUntil": "2026-07-06T10:15:00.000Z",
    "staleAfter": "2026-07-06T10:15:00.000Z",
    "reasonCodes": ["stale_inventory"],
    "dependencies": [
      {
        "ref": "inventory:travel-backpack:15",
        "kind": "inventory",
        "hash": "7777777777777777777777777777777777777777777777777777777777777777",
        "staleAfter": "2026-07-06T10:15:00.000Z"
      },
      {
        "ref": "policy:returns:travel-bags:missing",
        "kind": "policy",
        "hash": "8888888888888888888888888888888888888888888888888888888888888888"
      }
    ]
  },
  "basis": {
    "status": "blocked",
    "allowed": false,
    "reasonCodes": [
      "eligibility_blocked",
      "invalid_checkout_state",
      "missing_return_policy",
      "stale_inventory"
    ],
    "components": [
      {
        "code": "missing_return_policy",
        "source": "eligibility",
        "field": "eligibility.blockerCodes",
        "value": "missing_return_policy",
        "contributesTo": "status"
      },
      {
        "code": "stale_inventory",
        "source": "eligibility",
        "field": "eligibility.blockerCodes",
        "value": "stale_inventory",
        "contributesTo": "status"
      },
      {
        "code": "eligibility_blocked",
        "source": "eligibility",
        "field": "eligibility.result",
        "value": "blocked",
        "contributesTo": "status"
      },
      {
        "code": "invalid_checkout_state",
        "source": "checkout",
        "field": "checkout.validForRequestedAction",
        "value": false,
        "contributesTo": "status"
      }
    ]
  },
  "eligibility": {
    "result": "blocked",
    "blockerCodes": ["missing_return_policy", "stale_inventory"],
    "source": "combined"
  },
  "authority": {
    "result": "allowed",
    "blockerCodes": []
  },
  "checkout": {
    "state": "requires_revalidation",
    "validForRequestedAction": false,
    "blockerCodes": ["invalid_checkout_state", "missing_return_policy", "stale_inventory"]
  },
  "evidenceRefs": [
    {
      "type": "inventory_fact",
      "id": "inventory:travel-backpack:15",
      "hash": "9999999999999999999999999999999999999999999999999999999999999999",
      "hashAlgorithm": "sha256"
    },
    {
      "type": "policy_fact",
      "id": "policy:returns:travel-bags:missing",
      "hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "hashAlgorithm": "sha256"
    }
  ],
  "nextSafeActions": [
    {
      "action": "refresh_inventory_facts",
      "owner": "operator",
      "reasonCode": "stale_inventory"
    },
    {
      "action": "attach_return_policy_fact",
      "owner": "operator",
      "reasonCode": "missing_return_policy"
    }
  ]
}

This is more useful than a log message because it can support:

agent responses
operator tasks
protocol projections
support explanations
meaningful checkout and mandate events
scenario tests
replay analysis

The decision envelope becomes the platform’s stable explanation boundary.

Evidence should be referenced, not copied everywhere

Evidence does not mean copying every product record, policy page, checkout snapshot, mandate, provider response, and generated claim into every decision envelope or creating a parallel evidence table for each transition.

That creates duplication, privacy risk, and consistency problems.

A better model stores compact evidence references rather than copying full evidence records into every decision envelope. A canonical evidence reference contains the evidence type, identifier, explicit SHA-256 hash of the captured artifact or canonical snapshot, and hash algorithm.

Authorized systems can use those references to retrieve richer records. This matters for privacy and security. Payment authority records, buyer identity, provider responses, risk decisions, and support notes may contain sensitive information. The buyer-safe explanation should not expose the same detail as the internal audit view.

Evidence used by a canonical decision should be:

addressable
versioned
hash-pinned
permissioned
visible at the right audience level
captured at decision time

Evidence references and freshness dependencies serve different purposes.

An evidence reference, identified by (type, id), points to an artifact that can substantiate or replay the decision. A freshness dependency, identified by (kind, ref), points to an input whose change or expiry may invalidate the decision. The same artifact may serve both roles, but an identifier-only dependency should not be presented as content-pinned evidence. Conflicting hashes for the same evidence identity should fail rather than coexist.

This lets the platform preserve the explanation without exposing everything everywhere.

Evidence is a graph, not a flat list

Simple decisions may use a flat list of evidence references.

Complex commerce workflows need a dependency graph because one decision may rely on another decision, which in turn relies on several facts and policies.

For example:

delegate_payment decision
      depends on checkout_state
      depends on payment_mandate
      depends on cart_snapshot
      depends on authority_decision

checkout_state
      depends on prepare_checkout transition

prepare_checkout transition
      depends on product facts
      depends on inventory freshness
      depends on policy coverage
      depends on eligibility rules

policy coverage
      depends on policy facts
      depends on source documents
      depends on review decisions

A simplified evidence graph model:

type EvidenceEdgeType =
  | "derived_from"
  | "blocked_by"
  | "allowed_by"
  | "superseded_by"
  | "projected_as"
  | "invalidated_by"
  | "created_task"
  | "recorded_as";

type EvidenceRef = {
  type: string;
  id: string;
  hash: string;
  hashAlgorithm: "sha256";
};

type EvidenceEdge = {
  from: EvidenceRef;
  to: EvidenceRef;
  type: EvidenceEdgeType;
};

For the Travel Backpack:

delegate_payment decision
      blocked_by → checkout state requires_revalidation

checkout state requires_revalidation
      derived_from → prepare_checkout decision

prepare_checkout decision
      blocked_by → stale_inventory
      blocked_by → missing_return_policy

missing_return_policy
      created_task → approve return-policy coverage for Travel Bags

This graph lets the platform trace from a buyer-facing refusal back to the actual source of the refusal. It also prevents derived claims from laundering refusals: if one projected claim was refused for a surface or use, a later generated claim that depends on it should carry that upstream state.

At the generated-claim boundary, each direct edge should also have a canonical dependency reference. The reference binds the parent projection hash, source-envelope and evidence-pin hashes, source record, request-context hash, status, requested surface and use, and refusal kind.

The child provenance hash should cover all of those references, including usable parents, in deterministic order. This creates a dependency and audit edge; it does not replace content-pinned evidence.

That is stronger than storing isolated events or a descriptive lineage label.

It also helps explain changes over time. If return-policy coverage is later approved, the platform can show which old blockers were superseded, which generated claims were invalidated, and which feed projections were refreshed.

Explanations are projections of evidence

An explanation is not the same thing as the evidence record.

The evidence record may contain internal rule IDs, policy fact references, source hashes, payment provider references, risk flags, operator notes, and sensitive buyer information.

The explanation should expose only what is safe and useful for the audience.

Different audiences need different projections:

Audience	Needed explanation
Buyer	Clear, concise, safe reason
Agent	Structured blocker codes and next actions
Operator	Remediation details and affected products
Support	Customer-safe timeline and decision summary
Auditor	Full decision path, evidence refs, rule identities, timestamps
Engineer	Diagnostic details, traces, service calls

For the Travel Backpack, the buyer-safe explanation might be:

Checkout cannot be prepared for this item right now because availability must be revalidated and return terms are not available for this product category.

The agent-facing explanation might be:

{
  "result": "blocked",
  "blockers": [
    {
      "code": "stale_inventory",
      "nextAction": "request_inventory_revalidation"
    },
    {
      "code": "missing_return_policy",
      "nextAction": "operator_policy_review_required"
    }
  ]
}

The operator explanation might be:

BAG-TRAVEL-42 is blocked for checkout preparation.

Required remediation:
- Revalidate inventory.
- Attach or approve return-policy coverage for Travel Bags.

Impact:
Agents may discover and compare the product, but checkout preparation and delegated payment are blocked.

The audit view may include evidence references, rule identities, cart snapshots, timestamps, and the projection evidence recorded by the event that exposed the decision.

These are different explanations from the same evidence chain.

The platform should not generate each explanation independently. It should project them from the decision envelope.

Protocol-safe does not mean vague

Some teams avoid exposing evidence because they do not want to leak internal details.

That is reasonable.

But the solution should not be vague errors.

Weak protocol response:

{
  "error": "not_allowed"
}

Better protocol-safe response:

{
  "result": "blocked",
  "reason": "missing_return_policy",
  "message": "Return-policy terms are not available for this product category.",
  "nextAction": "operator_review_required"
}

This response does not expose internal policy record IDs, source documents, rule implementation, or operator notes. It preserves the domain meaning.

That matters because agents need to know what to do next.

A generic refusal may cause the agent to retry, ask the buyer the wrong question, or proceed with another unsafe assumption.

A structured refusal helps the agent recover correctly.

stale_inventory:
request revalidation

missing_return_policy:
operator remediation required

invalid_checkout_state:
do not request payment

mandate_expired:
request new authority

cart_snapshot_mismatch:
revalidate checkout or request new mandate

Protocol-safe responses should preserve blocker semantics whenever possible.

Recorded projections reveal adapter drift

Part 5 focused on adapter drift. Different adapters may start answering the same commercial question differently.

Evidence helps detect and prevent that drift.

If an MCP-style tool response, an ACP-style commerce response, an AP2-related payment response, an internal feed, and an admin UI all reference the same decision envelope, they can project different shapes while preserving the same meaning.

The response shape can differ.

The decision should not.

For the Travel Backpack:

Feed:
prepareCheckout = blocked

Policy tool:
return-policy quotation blocked

Commerce adapter:
checkout preparation blocked

Payment adapter:
delegated payment blocked because checkout state is not valid for payment

Admin UI:
inventory revalidation and return-policy coverage tasks required

All of these should trace back to compatible evidence. Before an external surface receives the projection, the boundary should verify envelope integrity, authenticator trust, target-surface binding, freshness, and the protected action, subject, and actor against the live request rather than trusting fields at face value. Independently verifiable projections should require a trusted Ed25519 signature. HMAC is appropriate only for an explicitly configured shared-secret boundary, and unsigned output should remain local-development only.

The meaningful event that exposes a decision can carry projection evidence showing how the canonical result was presented to a surface:

type ProtocolProjectionEvidence = {
  projectionId: string;
  decisionId: string;
  protocol:
    | "internal_feed"
    | "mcp"
    | "acp"
    | "ucp"
    | "ap2"
    | "marketplace_api"
    | "admin";

  audience:
    | "buyer"
    | "agent"
    | "operator"
    | "support"
    | "internal";

  projectedResult: string;
  projectedBlockerCodes: string[];
  redactedEvidenceRefs: EvidenceRef[];

  createdAt: string;
};

This supports a specific audit question:

The domain blocked checkout for two reasons. What did the agent actually receive?

That question cannot be answered from the domain decision alone.

A correct domain decision can become a misleading external answer if the adapter projects it badly.

Recorded projection evidence is also where scope survives the adapter. If a claim was grounded for discovery, the owning event should make that clear instead of letting the same language become checkout copy. If a claim exists but is refused for this surface, that refusal should be recorded differently from no claim being available.

Audit should therefore preserve projection context beside the decision, without requiring a separate projection table.

Blocked decisions are product signals

Systems often record successful transactions more carefully than blocked ones.

Agent-ready commerce needs blocked decisions to be first-class audit events.

Blocked decisions explain why the platform refused to answer, quote, mutate, or pay. They also identify operational work.

A blocked prepare_checkout transition should record:

requested command
actor
current checkout state
decision result
blockers
evidence refs
protocol projection
operator tasks created
timestamp

A blocked delegate_payment decision should record:

requested payment action
checkout state
mandate reference
cart snapshot
authority decision
blockers
evidence refs
payment not attempted
timestamp

A blocked generated claim should record:

claim text
unsupported segment
missing or stale dependency
allowed use requested
review state
invalidation reason
timestamp

Blocked events are not noise.

They are the platform’s safety model working.

If the audit trail records only success, it misses the most important part of agent-readiness.

Replayability requires snapshots, hashes, and stable references

Audit is weak if the platform cannot reconstruct the inputs to a decision.

Reconstruction does not always mean storing every full payload forever. A platform can use snapshots, hashes, and stable references.

Important inputs include:

product fact references
policy fact references
eligibility rule identity
authority record reference
cart snapshot
checkout state
payment mandate reference
generated claim reference
protocol request metadata
actor context
buyer context

A simplified replay input model:

type ReplayableDecisionInput = {
  decisionId: string;
  inputDependencyHash: string;

  productFactRefs: EvidenceRef[];
  policyFactRefs: EvidenceRef[];
  ruleSetRef: string;
  ruleSetHash: string;
  envelopeSchemaVersion: string;

  actorContextHash?: string;
  buyerContextHash?: string;

  cartSnapshotId?: string;
  checkoutStateId?: string;
  paymentMandateId?: string;

  requestMetadata: {
    protocol?: string;
    correlationId: string;
    idempotencyKey?: string;
    requestedAt: string;
  };
};

Hashes help detect whether inputs changed.

Stable references identify which facts, rules, states, and authority records were used.

Snapshots preserve mutable commercial state.

References allow controlled access to sensitive records.

Replayability does not mean every decision must be re-executed exactly in production. It means the platform can explain what inputs were used and, when needed, reproduce or approximate the decision path without turning audit into a separate rule system.

Where a transaction coordinator keeps one current spine plus meaningful events, the current record should carry a schema version, canonical hash, revision, and previous hash. Updates should use compare-and-set semantics, and the corresponding event should be appended in the same persistence transaction so the indexed state and audit history cannot drift silently.

Evidence freshness matters

Evidence can become stale.

A decision made yesterday may have been correct yesterday and unsafe today.

That is why evidence records should carry source-reference and time information.

type FreshnessState =
  | "fresh"
  | "stale"
  | "expired"
  | "superseded"
  | "unknown";

type EvidenceFreshness = {
  evidenceRef: EvidenceRef;
  freshness: FreshnessState;
  evaluatedAt: string;
  expiresAt?: string;
  supersededBy?: string;
};

For the Travel Backpack:

Price fact:
fresh at decision time

Inventory fact:
stale at decision time

Return-policy fact:
missing at decision time

Generated description:
pending review at decision time

The audit record should preserve the state at decision time.

The platform also needs to know whether an old decision can still be reused.

A feed projection from yesterday should not be treated as current checkout readiness if inventory freshness expired today.

Evidence freshness connects Part 2 commercial truth, Part 3 eligibility, Part 8 generated claims, and this article’s audit model.

For current projections, evidence references should include a durable source marker such as a source reference, checksum, or hash. Otherwise a changed policy can leave an old grounded status looking current.

Historical audit can still preserve what was true at the time. Current projection should check the source reference again before returning a surface-safe value.

Audit should support invalidation

When a source fact changes, dependent decisions and claims may need invalidation.

For example:

Return-policy fact added for Travel Bags
      ↓
Previous missing_return_policy blocker may be superseded
      ↓
Generated explanation about missing return policy may be invalidated
      ↓
Operator task may be resolved
      ↓
Feed projection may be refreshed

Audit should record that lifecycle.

type InvalidationEvent = {
  invalidationId: string;

  targetRef: EvidenceRef;

  reason:
    | "source_fact_changed"
    | "policy_fact_changed"
    | "decision_superseded"
    | "claim_invalidated"
    | "checkout_state_changed"
    | "authority_revoked"
    | "manual_review";

  causedBy: EvidenceRef;
  occurredAt: string;
};

This lets the platform answer:

Why did the agent answer differently today?

A good answer might be:

Yesterday, return-policy coverage for Travel Bags was missing, so checkout preparation was blocked.
Today, policy coverage was approved, inventory was revalidated, and the eligibility decision changed.

Without invalidation and audit, changing answers look inconsistent.

With evidence, they become explainable.

Generated claims must not cite themselves

Part 8 argued that generated claims are derived projections, not commercial truth.

Evidence and audit should enforce that.

A generated policy summary should not use another generated summary as its primary evidence.

A generated checkout explanation should not cite a previous generated explanation instead of checkout state and its blockers.

A generated recommendation should not cite a generated product description instead of product facts and buyer criteria.

This is evidence laundering.

The platform starts with a weak or derived statement, generates a more polished statement from it, and then treats the result as supported.

A safe rule is:

Generated claims may depend on other projected claims for lineage,
but each direct projection should be hash-bound with its source and request context,
and high-risk claims must ultimately trace back to source facts, policy facts, or domain decisions.

For the Travel Backpack, a claim such as:

This backpack can be returned within 30 days.

must trace to a quotable return-policy fact for Travel Bags.

If the only support is another generated summary, the claim should be blocked.

Operator timelines are product features

Evidence and audit are not only for engineers.

Operators need timelines.

For the Travel Backpack, an operator timeline might show:

09:00
Agent requested checkout preparation.

09:00
Checkout blocked.
Blockers:
- stale_inventory
- missing_return_policy

09:01
Operator task created:
Revalidate inventory for BAG-TRAVEL-42.

09:01
Operator task created:
Approve return-policy coverage for Travel Bags.

10:15
Inventory revalidated.

10:30
Return-policy coverage approved.

10:31
Eligibility refreshed.

10:32
Agent feed republished.

10:33
Checkout preparation allowed for EU consumer context.

That timeline is a product capability.

The underlying remediation record can use one compact lifecycle such as open, acknowledged, resolved, and reopened. Repeated observations of the same unresolved blocker should update the existing stream rather than create duplicate tasks, while a blocker that returns after resolution should reopen it.

It helps operators understand what changed, why agents behaved differently, and what remediation resolved the issue.

Without this timeline, operators work from scattered logs, stale feed data, screenshots, and support tickets.

Agent-readiness requires operational visibility because many blockers are not code defects. They are missing facts, stale facts, missing policy coverage, invalidated claims, unreviewed generated text, expired mandates, or stale projections.

Evidence should drive support responses

Support teams also need evidence.

A buyer may ask:

Why did the agent say it could not buy the backpack?

Support should not need to inspect internal logs manually.

The platform should provide a support-safe answer:

At the time of the request, checkout could not be prepared because inventory needed revalidation and return terms were not available for the Travel Bags category. Payment was not attempted.

That answer is derived from evidence, but redacted for support use.

Support may also need an internal view:

Decision ID:
decision_delegate_payment_001

Checkout state:
checkout_prepare_001

Blockers:
stale_inventory
missing_return_policy

Payment:
not attempted

Agent response:
blocked with invalid_checkout_state

Operator tasks:
inventory revalidation
return-policy coverage

This reduces ambiguity.

Evidence makes customer support part of the product, not an afterthought.

Privacy and retention must be designed

Evidence and audit can contain sensitive data.

Buyer identity, cart contents, payment authority, provider references, support notes, risk decisions, and protocol metadata may all require careful handling.

An evidence system should include:

visibility levels
access controls
redaction rules
retention policies
data minimization
hashing where full data is unnecessary
separation between public explanation and internal evidence

For example, a buyer-safe explanation should not expose internal rule IDs or payment provider references.

An operator view may not need full payment instrument details.

An audit view may need immutable references, not full sensitive payloads.

The goal is not to expose all evidence to everyone. The goal is to preserve the decision path while controlling who can see each part of it.

Evidence without access control creates risk.

Audit without retention rules becomes liability.

Where this model can go wrong

Evidence and audit improve trust, but they introduce their own failure modes.

Treating logs as audit

Logs are useful, but they are not structured decision envelopes. They may be incomplete, inconsistent, redacted incorrectly, or difficult to replay.

Recording outcomes but not inputs

An audit record that says blocked is not enough. The platform needs the facts, policies, rules, state, authority, and context that produced the result.

Recording evidence but not projections

A correct domain decision can become a misleading agent response if the adapter projects it badly. Projections should record the surface, use, source pin, freshness state, scope result, payload integrity result, and inherited refusal state.

Exposing too much evidence externally

Evidence should be permissioned. Buyer-safe, protocol-safe, operator, support, and internal views should differ.

Hiding too much behind generic errors

Over-redaction can make agents and operators unable to recover. Structured blocker codes should survive projection when safe.

Letting evidence become stale without invalidation

Old decisions, feed projections, and generated claims can become unsafe when dependencies change.

Treating generated claims as evidence

Generated claims are derived. High-risk claims should trace back to source facts or domain decisions. If they depend on another generated claim, they should inherit that claim’s projection state and retain a verified direct dependency-projection reference rather than treating the dependency as fresh evidence.

Failing to audit blocked decisions

Blocked decisions are where the safety model is visible. They should be recorded, not discarded.

Making audit unreadable

Audit records that only engineers can interpret will not help operators, support, or compliance reviewers. Different audiences need different views.

Making evidence too expensive to produce

If evidence capture is slow, unreliable, or difficult to integrate, teams will bypass it. Evidence capture should be part of the platform path, not optional paperwork.

Practical tests for evidence and audit

Evidence and audit should be tested directly.

A useful evidence test includes:

Request
Decision result
Expected evidence refs
Expected dependency projection refs
Expected derived provenance hash
Expected blocker codes
Expected projection
Expected audit event
Expected operator work item
Expected invalidation behavior

For the Travel Backpack:

Scenario	Expected evidence/audit behavior
Agent asks to discover product	Decision references approved discoverable product facts
Agent asks to quote return policy	Blocked decision references missing return-policy coverage
Agent asks to prepare checkout	Blocked decision references stale inventory and missing return policy
Agent asks delegated payment	Action blocked because checkout is invalid; payment authority `not_evaluated`; payment not attempted
Generated return claim is requested	Claim blocked because no quotable return-policy fact exists
Derived claim uses an allowed parent projection	Direct dependency ref and child provenance hash are recorded
Parent projection context or evidence pin changes	Child provenance changes and the prior derived claim is invalidated
Parent projection semantics are altered without a matching hash	Derivation is rejected before publication
Inventory is revalidated	Prior stale-inventory blocker is superseded
Return-policy coverage is approved	Operator work item resolved; policy evidence updated
Feed is republished	Projection references current decision envelopes
Adapter maps blocked decision to generic success	Scenario test fails
Buyer-safe explanation is requested	Internal evidence is redacted but blocker meaning is preserved
Audit reconstruction is requested	Decision input refs, rule identity, and snapshot hashes are available

A simplified expectation type:

type EvidenceAuditScenarioExpectation = {
  requestedAction: AgentCommerceDecisionAction;
  expectedResult: DecisionResult;
  expectedEvidenceKinds: EvidenceKind[];
  expectedBlockerCodes: string[];
  expectedProjectionRecorded: boolean;
  expectedAuditEvent: boolean;
  expectedOperatorWorkItem?: boolean;
};

The goal is not only to test the business result. The tests should repeat the same normalized input to confirm stable hashes and exact reason/component reconciliation. They should reject conflicting evidence identities and verify deterministic direct dependency-projection binding.

They should also prove that tampering with decision identity, surface, freshness, dependencies, hashes, or the authenticator is rejected at the appropriate boundary. Requested action, subject, or actor mismatches must also be rejected. An older envelope must not bypass the latest checkout, mandate, or product-decision state merely because it remains signed and within its freshness window. Audit persistence should separately prevent a stale record revision from silently overwriting newer state.

Together, these tests show whether the platform can explain and verify a decision from its recorded inputs, blockers, projections, dependencies, and audit events.

A practical implementation path

A platform can introduce evidence and audit incrementally.

Define decision envelopes.

Start with the shared actions: discover, compare, quote_policy, add_to_cart, prepare_checkout, delegate_payment, complete_checkout, show_generated_claim, and explain.

Define evidence references.

Use typed references for product facts, policy facts, eligibility rules, authority records, checkout state, cart snapshots, payment mandates, generated claims, and audit events.

Attach evidence to allowed and blocked decisions.

Do not record evidence only for failures.

Preserve blocker codes.

Use stable domain blocker codes such as stale_inventory, missing_return_policy, invalid_checkout_state, mandate_expired, and cart_snapshot_mismatch.

Preserve projection evidence.

Record or reconstruct, within the event or audit path that owns the decision, how the canonical envelope was presented to feeds, tools, commerce adapters, payment adapters, admin UI, and support views.

Add replayable inputs.

Store source references, hashes, snapshots, and rule-set identities where exact input reconstruction matters.

Add invalidation events.

When product facts, policy facts, eligibility rules, checkout state, payment authority, or generated claims change, record which decisions or projections are superseded.

Build audience-specific explanation views.

Separate buyer-safe, protocol-safe, operator, support, auditor, and engineer views.

Generate operator timelines.

Show blockers, remediation tasks, state changes, feed refreshes, and decision changes over time.

Test evidence paths.

Include evidence references, recorded projection evidence, meaningful audit events, and invalidation behavior in scenario tests.

This path makes evidence part of the platform rather than something reconstructed after incidents.

The tradeoff

Evidence and audit add structure.

They require decision envelopes, evidence references, snapshots, recorded projection evidence, redaction rules, retention rules, invalidation events, and audience-specific explanation views.

For a simple storefront, that may seem heavy.

Agent-ready commerce changes the threshold.

Once agents can answer buyer questions, quote policies, compare products, prepare checkout, operate under delegated authority, or explain payment refusal, the platform needs to explain the decision path from recorded inputs, blockers, and projections.

The tradeoff is between implementation simplicity and explainable trust.

Logs are easier to add.

Decision evidence is easier to rely on, audit, test, replay, project, and defend.

The goal is not to record everything forever. The goal is to record enough structured evidence to explain why the platform answered, refused, mutated state, or escalated at the time it happened.

The evidence layer

Evidence and audit are part of the product in agent-ready commerce.

They are not backend extras.

Agents turn platform decisions into buyer-facing answers and commercial actions. That makes the reasoning behind those decisions part of the user experience, the operator workflow, the support process, and the audit trail.

A safe platform keeps the chain explicit:

Request
      ↓
Decision
      ↓
Evidence record
      ↓
Protocol-safe explanation
      ↓
Projection or state transition
      ↓
Audit event
      ↓
Operator and support timeline

For the Travel Backpack, that means the platform can explain exactly why the product is discoverable and comparable but not policy-quotable, checkout-ready, or eligible for delegated payment.

It can point to stale inventory, missing return-policy coverage, current eligibility decisions, checkout state, payment authority decisions, generated-claim review status, and operator remediation tasks.

That is the difference between a system that merely responds and a system that can explain the basis of its response.

Next in the series

Part 10 will bring the architecture together:

Agent-Ready Commerce, Part 10: The Reference Architecture

That article will connect commercial truth, policy facts, eligibility, adapters, checkout state, payment authority, generated claims, evidence, audit, feeds, and operator workflows into a complete reference architecture for agent-ready commerce platforms.

About the author

Written by Dimitrios S. Sfyris, Founder & Software Architect at AspectSoft.

AspectSoft designs and develops custom software platforms, e-commerce systems, SaaS infrastructure, integrations, analytics tools, and practical digital products.

You can also follow the AspectSoft LinkedIn page for updates on software platforms, commerce systems, AI tooling, and developer-focused products.

Agent-Ready Commerce, Part 8: Generated Claims Need Review, Evidence, and Expiry

Dimitrios S. Sfyris — Tue, 30 Jun 2026 15:52:10 +0000

Generated commerce text becomes unsafe when the platform forgets that it is derived.

A product description, policy summary, comparison paragraph, recommendation explanation, checkout message, or payment explanation is not commercial truth. It is a projection of commercial truth into language.

That projection may be useful. It may be accurate. It may be reviewed. It may be approved for a specific use.

But it is still derived.

It depends on source facts, policy facts, eligibility decisions, checkout state, payment authority decisions, buyer context, region, channel, and time. If those dependencies change, the generated text may no longer be safe to show, quote, publish, or use in an agent-facing workflow.

The problem is not only hallucination.

A generated sentence can be fully grounded when it is created and still become unsafe later. A price changes. Inventory becomes stale. A policy fact is superseded. A checkout blocker is resolved. A mandate expires. A region becomes unsupported. A generated return summary remains in an agent feed after return-policy coverage was revoked.

That is a systems problem.

Generated claims need dependency management.

Series context

This is the eighth article in the Agent-Ready Commerce series.

Part 1 introduced the broader architecture model:

Facts → Eligibility → Authority → State transition → Evidence → Audit

This article focuses on generated commercial claims.

The central argument is that generated text should not be treated as free-floating content. It should be treated as a derived commercial claim that is projectable only when its source, freshness, scope, surface, use, payload integrity, and inherited refusal state allow it.

In earlier articles, projection mostly meant shaping one platform decision for a storefront, feed, protocol adapter, or admin view. Generated-claim projection is the stricter case: it controls whether language may be used at all.

A safe platform follows this chain:

Source facts and decisions
      ↓
Generated claim
      ↓
Evidence and source pin
      ↓
Review decision
      ↓
Projection gate
      ↓
Projection axes and inherited refusal state
      ↓
Publication or protocol projection
      ↓
Invalidation and expiry
      ↓
Audit

Without that chain, generated text becomes a hidden source of product truth, policy interpretation, checkout explanation, or payment authority.

A generated claim is a cached projection

A useful way to think about generated commerce text is as a cached projection: language produced from a particular set of facts and decisions at a particular time.

The platform has source-backed facts and decisions:

Product attributes
Price facts
Inventory facts
Policy facts
Eligibility decisions
Checkout state
Payment authority decisions

A generated claim turns some of those facts or decisions into language.

For example:

This backpack can ship within the EU.

That sentence may depend on:

Product: BAG-TRAVEL-42
Category: Travel Bags
Shipping policy: EU shipping known
Region: EU
Channel: agent
Review status: approved

The sentence is not the source of truth for EU shipping. It is a projection of the shipping policy fact into human-readable language.

That distinction matters.

If the EU shipping policy changes, the generated sentence should be invalidated or reviewed. If the buyer is in the US, the sentence should not be used. If the claim was approved for storefront display but not for agent quotation, an agent should not quote it.

Generated claims therefore need the same discipline as other projections:

What produced it?
What does it depend on?
Where does it apply?
Who approved it?
Where may it be used?
When does it expire?
What invalidates it?
Where was it published or quoted?

This goes beyond ordinary content management. The platform must know which facts and decisions the language depends on, so it can stop using the claim when those dependencies change.

The Travel Backpack example

Continue with the running example from Parts 2–7:

Product: Travel Backpack
SKU: BAG-TRAVEL-42
Price: €129
Catalog status: active
Inventory status: in_stock
Category: Travel Bags

The commercial truth layer currently says:

Price: fresh
Inventory: stale
Return policy: missing for Travel Bags
Warranty policy: known
Shipping policy: known for EU, unknown for US
Generated description: pending review
Feed publication: last published yesterday

From Part 3, the action matrix was:

Action	Result
`discover`	allowed
`compare`	allowed
`quote_policy`	blocked
`add_to_cart`	requires_revalidation
`prepare_checkout`	blocked
`delegate_payment`	blocked

Now consider several generated claims:

Claim	Status
“This backpack is in stock and ready to ship.”	Unsafe: inventory is stale and readiness is not established
“This backpack includes warranty coverage and can ship within the EU.”	Potentially safe only in EU scope if evidence and review are valid
“This backpack can be returned within 30 days.”	Unsafe: return-policy coverage is missing for Travel Bags
“This backpack is a good option for buyers looking for a travel bag under €150.”	Potentially safe as a match explanation, but not as checkout readiness
“Checkout cannot be prepared because inventory requires revalidation and return-policy coverage is missing.”	Potentially safe if derived from current checkout and eligibility decisions

These are all fluent sentences. Some are useful. Some are unsafe. Some are safe only in a narrow context.

The platform should not ask, “Is the generated text good?”

It should ask:

Which claim is being made?
Which facts or decisions support it?
Where does it apply?
Is it current?
Has it been reviewed?
Which uses are allowed?
What invalidates it?

That is the difference between generated copy and a generated commercial claim.

Generated claims are not all the same

A generated color description and a generated payment explanation should not follow the same rules.

Claim type matters because risk differs by domain.

Claim type	Example	Main dependency
Product description	“Includes a laptop sleeve.”	Product attributes
Price claim	“Available for €129.”	Price facts and currency
Availability claim	“In stock and ready to ship.”	Inventory freshness and shipping readiness
Policy summary	“Returns are accepted within 30 days.”	Applicable quotable policy facts
Comparison	“Larger than the City Backpack.”	Facts for both products
Recommendation	“Best option for short business trips.”	Buyer criteria and product facts
Checkout explanation	“Checkout is blocked because inventory is stale.”	Checkout state and blockers
Payment explanation	“Payment cannot proceed because the mandate expired.”	Payment authority decision

The risk increases when the claim affects buyer reliance, policy interpretation, checkout behavior, or payment authority.

A platform can allow lightweight workflows for low-risk internal drafts. But claims that can be quoted by agents, published into feeds, used in policy answers, or used near checkout and payment need stronger controls.

Two sources of generated claims

Generated commerce claims usually come from two different sources.

The first type is fact-derived.

Product facts
Policy facts
Catalog attributes
Inventory facts
Shipping facts
Price facts

Examples:

This backpack costs €129.
This backpack includes warranty coverage.
This backpack can ship within the EU.

The second type is decision-derived.

Eligibility decisions
Checkout state
Payment authority decisions
Operator remediation decisions

Examples:

Checkout cannot be prepared because inventory requires revalidation.
Delegated payment is blocked because checkout state is not valid for payment.
Return-policy quotation is blocked because no return-policy fact applies to Travel Bags.

This distinction matters because decision-derived claims should not be generated from raw facts alone.

A checkout explanation should come from checkout state and its blockers.

A payment explanation should come from the payment authority decision.

A policy quotation should come from quotable policy facts.

A protocol adapter should not ask a model to infer those explanations from logs, product fields, or policy pages. It should use the domain decision that already explains the result.

A safe model is:

Fact-derived claim:
Generated from source-backed facts.

Decision-derived claim:
Generated from domain decisions and blockers.

The source of the claim determines how it should be reviewed, invalidated, and audited.

A generated claim needs structure

A generated claim should be stored as a structured derived artifact, not only as text.

The goal is not to over-model every sentence. It is to prevent high-impact generated text from escaping the platform as untracked commercial language. The canonical decision envelope carries claim IDs, source and derived fact references, allowed uses, seven projection axes, blocker codes, and inherited refusal. Surface projections may additionally carry approved-value, claim-text, or quote-text hashes when the projected value itself must be pinned.

A useful model includes:

type AxisStatus = "passed" | "failed" | "not_evaluated";
type GeneratedClaimAxis = {
  status: AxisStatus;
  blockerCodes: string[];
};
type GeneratedClaimStatus =
  | "allowed"
  | "requires_review"
  | "refused_here"
  | "inherited_refusal"
  | "stale"
  | "out_of_scope"
  | "absent";

type GeneratedCommerceClaim = {
  claimId: string;
  kind: GeneratedClaimKind;
  text: string;

  status: GeneratedClaimStatus;
  scope: GeneratedClaimScope;
  allowedUses: GeneratedClaimUse[];

  sourceFactRefs: string[];
  derivedFactRefs: string[];
  dependencies: Array<{
    type: string;
    ref: string;
    hash: string;
    hashAlgorithm: "sha256";
  }>;

  axes: Record<
    "source" | "freshness" | "scope" | "surface" | "use" | "payload" | "taint",
    GeneratedClaimAxis
  >;
  blockerCodes: string[];

  inheritedRefusalCount: number;
  generatedAt: string;
  expiresAt?: string;
  generatedFrom?: {
    inputHash: string;
    generatedAt: string;
  };
  lifecycle?: {
    status: "active" | "requires_review" | "invalidated" | "expired";
    invalidatedAt?: string;
    reasonCode?: string;
  };
  approvedValueHash?: string | null;
  claimTextHash?: string | null;
  quoteTextHash?: string | null;
  auditRefs: string[];
};

This keeps the claim compact while preserving the important boundaries: source, freshness, scope, surface, use, payload integrity, and inherited refusal state. The full direct dependency lineage belongs to the owning generated-claim record, while the canonical decision envelope can expose the compact inheritedRefusalCount.

Derived claims should identify every direct parent projection they actually used

When a claim is derived from another projected claim, recording only the parent claim ID or the inherited-refusal count is not enough. The child should commit to every direct projection actually used in the derivation, including usable parents.

A compact provenance record can identify each direct parent with a stable reference and hash:

type GeneratedClaimDependencyProjectionRef = {
  projectionHash: string;
  sourceEnvelopeHash: string | null;
  sourceEvidencePinHash: string | null;
  sourceRecordKey: string | null;
  requestContextHash: string;
  status: "usable" | "refused_here" | "never_grounded";
  requestedSurface: string;
  requestedUse: string | null;
  refusalKind: string | null;
};

type DerivedGeneratedClaimProvenance = {
  recordKey: string | null;
  payloadHash: string;
  dependencyRefs: readonly GeneratedClaimDependencyProjectionRef[];
  provenanceTaint: {
    inheritedRefusals: readonly {
      sourceProjectionHash: string | null;
      sourceEnvelopeHash: string | null;
      sourceRecordKey: string | null;
      status: "refused_here" | "never_grounded";
      refusalKind: string;
      axis:
        | "source"
        | "freshness"
        | "scope"
        | "surface"
        | "use"
        | "payload"
        | "taint";
      blockerCodes: readonly string[];
    }[];
  };
  canonicalHash: string;
};

The parent projectionHash should cover the source-envelope and evidence-pin hashes, source record, requested surface and use, market, locale, jurisdiction, channel, projection status, refusal state, axes, blocker codes, and inherited lineage. The derived builder should verify every supplied projection hash and normalize dependency order by projectionHash. It should then include both usable and refused parents, together with the child payload hash, in the child canonicalHash.

This closes a gap that inherited-refusal propagation alone does not close. A usable parent can change while the child text remains identical. A request may also move from one surface, use, market, or locale to another. Either change should alter the child provenance hash rather than leaving the derived claim looking unchanged.

Taint should remain causal: only projections actually supplied as derivation dependencies should contribute inherited refusal. Multi-hop lineage should be deduplicated and preserved completely within an explicit bound. The reference implementation uses a 256-entry limit and fails construction above that limit instead of publishing a partial history.

Those fields matter because generated text can be correct in one context and unsafe in another.

A product description approved for a storefront may not be allowed in an agent feed.

A return-policy summary approved for EU consumer buyers may not be safe for US business buyers.

A payment explanation may be safe for support but not for buyer-facing copy.

The record answers the questions that matter:

What does the claim say?
Where does it apply?
Which facts or decisions support it?
Who or what reviewed it?
Where may it be used?
When does it expire?
What invalidates it?
Where has it been used?

In a decision-spine architecture, generated-claim state becomes part of the decision envelope:

generatedClaims.status
generatedClaims.claimIds
generatedClaims.sourceFactRefs
generatedClaims.allowedUses
generatedClaims.axes
generatedClaims.blockerCodes

That does not make generated text authoritative. It makes the claim's derived status visible to every projection, including whether the claim is usable here, refused for this use, not grounded, or internally carrying an inherited refusal.

The projection gate should default to refusal when required information is missing or unsafe. A claim cannot remain allowed when a required axis is failed or not_evaluated, blocker codes remain, inheritedRefusalCount is greater than zero, or no allowed use has been declared.

The gate should bind the exact claim ID, requested use, requested surface, required value hash, and observed projected value rather than treating claim existence as permission.

A derived claim should calculate inherited refusal from its dependency projections. It should also bind every direct projection used, including usable ones, into its canonical provenance hash so a caller cannot declare the child clean or omit a usable parent.

The claim state should also remain action-aware. If an envelope is deciding delegate_payment, it may still report that a generated description is pending. That claim status should not become the payment blocker unless delegated payment actually depends on using the description.

Evidence binding should be clause-level when risk is high

A generated paragraph may contain several commercial claims.

Consider this sentence:

This backpack is in stock, ships across Europe, and can be returned within 30 days.

It contains at least three assertions:

Inventory:
in stock

Shipping:
ships across Europe

Returns:
can be returned within 30 days

For the Travel Backpack:

Inventory:
stale

EU shipping:
known

Return policy:
missing for Travel Bags

The sentence should not be approved as a single block.

One clause may be supportable. Another may be stale. Another may be unsupported.

A high-risk generated claim can be segmented:

type ClaimSegmentSupportStatus =
  | "supported"
  | "unsupported"
  | "stale"
  | "conflicting"
  | "out_of_scope"
  | "requires_review";

type ClaimSegment = {
  segmentId: string;
  text: string;
  assertionType:
    | "product_attribute"
    | "price"
    | "inventory"
    | "shipping"
    | "returns"
    | "warranty"
    | "recommendation"
    | "checkout_state"
    | "payment_authority";

  supportStatus: ClaimSegmentSupportStatus;
  evidenceRefs: Array<{
    type: string;
    id: string;
    hash: string;
    hashAlgorithm: "sha256";
  }>;
};

For the example sentence, the platform might produce:

{
  "segments": [
    {
      "text": "This backpack is in stock",
      "assertionType": "inventory",
      "supportStatus": "stale",
      "evidenceRefs": [
        {
          "type": "inventory_fact",
          "id": "truth:BAG-TRAVEL-42:inventory",
          "hash": "1111111111111111111111111111111111111111111111111111111111111111",
          "hashAlgorithm": "sha256"
        }
      ]
    },
    {
      "text": "ships across Europe",
      "assertionType": "shipping",
      "supportStatus": "supported",
      "evidenceRefs": [
        {
          "type": "policy_fact",
          "id": "policy:shipping:eu",
          "hash": "2222222222222222222222222222222222222222222222222222222222222222",
          "hashAlgorithm": "sha256"
        }
      ]
    },
    {
      "text": "can be returned within 30 days",
      "assertionType": "returns",
      "supportStatus": "unsupported",
      "evidenceRefs": []
    }
  ]
}

This allows the platform to revise the text instead of approving a sentence that mixes safe and unsafe assertions.

Clause-level support is especially useful for policy summaries, checkout explanations, payment explanations, and recommendations.

Review is not one boolean

A review field such as approved: true is too weak.

Approved for what?

A generated product description may be approved for internal review but not for storefront display.

A generated policy summary may be approved for storefront display but not for agent quotation.

A generated checkout explanation may be approved only when it is derived from a current decision envelope.

A generated recommendation may be approved only for a specific buyer criterion.

Review should therefore produce allowed uses, but allowed use is only one axis. The projection also needs to preserve source, freshness, scope, surface, payload integrity, and inherited refusal state.

type ClaimReviewDecision = {
  claimId: string;
  approvedUses: GeneratedClaimUse[];
  rejectedUses: GeneratedClaimUse[];
  reviewerType: "human" | "rule" | "automated_validation";
  reviewerId: string;
  reviewedAt: string;
  notes?: string;
};

For the Travel Backpack:

Generated claim:
This backpack includes warranty coverage and can ship within the EU.

Review decision:
Approved for storefront display in EU context.
Approved for agent discovery in EU context.
Not approved for US shipping answers.
Not approved for checkout explanation.
Not approved for return-policy quotation.

That is much safer than a generic approval flag.

The question is not only whether the text is correct. The question is whether this surface has the right to project it from the current provenance state.

Scope prevents accidental overreach

Generated language often sounds more general than the facts that support it.

For example:

This backpack ships quickly.

That sentence hides too much.

Does it apply to EU buyers?

US buyers?

Business buyers?

Marketplace orders?

Support-assisted orders?

Products with stale inventory?

Only after checkout preparation?

A safer claim is scoped:

For EU consumer orders, this backpack has source-backed shipping coverage.

The claim record should keep the same scope, together with the facts, source pins, projection axes, and decisions that made the claim usable.

const euShippingClaim: GeneratedCommerceClaim = {
  claimId: "claim_shipping_eu_001",
  kind: "policy_summary",
  text: "This backpack can ship within the EU under the current shipping policy.",
  status: "allowed",
  scope: {
    sku: "BAG-TRAVEL-42",
    region: "EU",
    buyerType: "consumer",
    channel: "agent"
  },
  allowedUses: ["agent_discovery"],
  dependencies: [
    {
      type: "policy_fact",
      ref: "policy:shipping:eu",
      hash: "<sha256-of-canonical-policy-fact>",
      hashAlgorithm: "sha256"
    }
  ],
  axes: {
    source: { status: "passed", blockerCodes: [] },
    freshness: { status: "passed", blockerCodes: [] },
    scope: { status: "passed", blockerCodes: [] },
    surface: { status: "passed", blockerCodes: [] },
    use: { status: "passed", blockerCodes: [] },
    payload: { status: "passed", blockerCodes: [] },
    taint: { status: "passed", blockerCodes: [] }
  },
  sourceFactRefs: ["policy:shipping:eu"],
  derivedFactRefs: ["claim_text_hash:<sha256-hex>"],
  blockerCodes: [],
  inheritedRefusalCount: 0,
  generatedAt: "2026-06-28T09:00:00.000Z",
  generatedFrom: {
    inputHash: "<sha256-hex>",
    generatedAt: "2026-06-28T09:00:00.000Z"
  },
  lifecycle: {
    status: "active"
  },
  auditRefs: []
};

That claim should not be reused for a US buyer or a checkout explanation unless those uses have been evaluated separately. If the claim exists but is not allowed for the requested use, the platform should treat that as a refusal, not as if no claim existed.

Part 4 made this point for policy facts. Generated claims must inherit the same applicability discipline.

Claim status must not override action eligibility

An approved generated claim does not make an action eligible.

This is an important failure mode.

Suppose a generated product description is approved:

This backpack is designed for short trips and everyday travel.

That does not mean the product is checkout-ready.

Suppose an EU shipping summary is approved:

This backpack can ship within the EU.

That does not mean delegated payment can proceed.

Suppose a warranty statement is approved:

This backpack includes warranty coverage.

That does not create return-policy coverage.

Generated claim status and action eligibility are separate.

Claim approval:
May this sentence be used in this context?

Action eligibility:
May this commercial action occur in this context?

For the Travel Backpack:

Some generated claims may be approved.
Checkout preparation remains blocked.
Delegated payment remains blocked.

The platform should never infer action eligibility from approved generated text. It should use the eligibility layer.

Generated policy summaries are not policy authority

A generated policy summary can be useful.

It can help operators understand coverage. It can help agents answer concise questions. It can make long policy text easier to present.

But it is not policy authority.

The authority comes from structured policy facts with applicability, evidence, lifecycle, conflicts, and quotability.

For example:

Generated summary:
Travel Bags can be returned within 30 days.

If there is no active return-policy fact for Travel Bags, the summary should not be quotable.

A safe flow is:

Policy source
      ↓
Policy facts
      ↓
Applicability and quotability decision
      ↓
Generated summary
      ↓
Review and allowed use
      ↓
Agent response

The generated summary is downstream from quotability. It does not create quotability.

For the Travel Backpack, return-policy quotation is blocked because return-policy coverage is missing for Travel Bags. A generated return-policy summary cannot unblock it.

Recommendation claims need criteria

Recommendation text is easy to overstate.

A generated sentence such as:

This is the best backpack for business travelers.

is rarely safe without explicit criteria.

Best according to what?

Capacity?

Laptop compartment?

Weight?

Price?

Warranty?

Shipping speed?

Return policy?

Buyer preference?

Inventory readiness?

Valid checkout state?

A safer recommendation explanation is narrower:

This backpack matches the buyer’s requested category and price limit, but checkout is not ready because inventory requires revalidation and return-policy coverage is missing.

That sentence separates product match from checkout readiness.

A recommendation system should keep three things distinct:

Selection logic:
Why was this product selected?

Generated explanation:
How is the selection explained?

Commercial readiness:
Can the recommended product be acted on now?

A product can match buyer criteria and still be blocked for checkout.

Generated recommendation text should preserve that distinction.

Comparison claims need evidence for every side

A comparison claim depends on more than one product.

For example:

The Travel Backpack is larger than the City Backpack.

That requires source-backed capacity or dimension facts for both products. It also requires comparable units.

A comparison claim should not be approved if one side lacks evidence.

type ComparisonClaim = {
  claimId: string;
  productIds: string[];
  comparedAttributes: string[];
  sourceFactRefsByProduct: Record<string, string[]>;
  status: GeneratedCommerceClaimStatus;
};

A safe comparison flow checks:

Are the compared attributes known for all products?
Are the facts fresh enough?
Are the units comparable?
Is the comparison scoped correctly?
Are generated conclusions supported?

Generated comparison text should not fill missing attributes with plausible language.

If the platform lacks capacity data for one backpack, the generated comparison should either omit the claim or say that the comparison is incomplete.

Checkout explanations must come from decisions

Checkout explanations are high-risk because they explain why the platform allowed or blocked a mutation.

A generated checkout explanation should not infer reasons from product data or logs.

It should use the actual checkout state envelope.

Bad explanation:

Checkout failed because payment could not be processed.

if the real blocker was missing return-policy coverage.

Better explanation:

Checkout cannot be prepared because inventory requires revalidation and return-policy coverage is missing for Travel Bags.

That explanation should be derived from blockers produced by the checkout transition model.

A decision-derived claim can reference decision envelopes:

type DecisionDerivedClaim = GeneratedCommerceClaim & {
  decisionRefs: string[];
  blockerCodes: string[];
};

For the Travel Backpack:

{
  "kind": "checkout_explanation",
  "text": "Checkout cannot be prepared because inventory requires revalidation and return-policy coverage is missing for Travel Bags.",
  "decisionRefs": ["checkout_decision:prepare_checkout:BAG-TRAVEL-42"],
  "allowedUses": ["checkout_explanation", "internal_review"],
  "status": "APPROVED"
}

The explanation is not safe because it is generated. It is safe because it is bound to the decision that was authoritative.

Payment explanations must preserve authority boundaries

Part 7 separated checkout validation, checkout state, payment authority, payment execution, and order commitment.

Generated payment explanations must preserve those boundaries.

Unsafe explanation:

Payment failed.

when the real decision was:

Payment was not requested because delegated authority is missing.

Another unsafe explanation:

The agent is not allowed to pay.

when the real blocker was:

Checkout state is not valid for payment because return-policy coverage is missing.

A safe generated payment explanation should distinguish:

Checkout state not valid for payment
Authority missing
Mandate expired
Cart snapshot mismatch
Amount exceeds mandate
Provider declined
Payment ambiguous
Order commitment failed

Those states have different next actions.

Generated payment explanations should be derived from authority and payment state records, not from loosely summarized provider messages or logs.

Invalidation is as important as generation

Generated claims can become unsafe after approval.

A product price changes.

Inventory becomes stale.

A policy fact is superseded.

A policy conflict is detected.

A product category changes.

A generated description is rejected.

A checkout blocker is resolved.

A payment mandate expires.

A claim that was safe yesterday may be unsafe today.

Generated claims therefore need invalidation rules.

type ClaimInvalidationTrigger =
  | "source_fact_changed"
  | "source_fact_expired"
  | "policy_fact_changed"
  | "policy_conflict_detected"
  | "eligibility_rule_changed"
  | "product_scope_changed"
  | "review_revoked"
  | "decision_superseded"
  | "dependency_projection_changed"
  | "manual_invalidation";

Example:

Claim:
This backpack ships within the EU.

Dependency:
EU shipping policy fact.

Trigger:
EU shipping policy is superseded.

Result:
Claim becomes invalidated or requires review.

The platform should not depend on someone remembering to regenerate copy.

Invalidation should be part of the claim lifecycle. A changed usable parent projection, evidence pin, or request context should also invalidate the child because it changes the child’s canonical provenance even when the visible wording is unchanged.

The invalidated record should retain the prior authority descriptor and hash for audit. When the exact parent is repaired, a dependent claim may become ready for review again. It must not automatically regain publication, quotation, checkout, or payment authority. Reissue still requires the current approved value, scope, evidence, allowed use, and owner decision.

Expiry handles volatile dependencies

Not every dependency change is captured perfectly through events.

Some facts come from external feeds. Some facts have freshness windows. Some claims depend on volatile data such as price, inventory, delivery estimates, promotions, checkout state, or payment state.

Expiry provides a fallback boundary.

type ClaimLifecycle = {
  validFrom?: string;
  expiresAt?: string;
  invalidatedAt?: string;
  invalidationReason?: string;
};

Examples:

Inventory-related claim:
Expires quickly.

Price-related claim:
Expires when the price fact expires or changes.

Policy summary:
Expires when the policy fact is superseded or the review window ends.

Recommendation explanation:
Expires when buyer criteria, product facts, or eligibility changes.

Checkout explanation:
Expires when checkout state changes or is superseded.

Payment explanation:
Expires when the payment authority decision or payment state changes.

Expiry should not replace dependency-based invalidation. It complements it.

A generated commercial claim that never expires is a latent defect.

Agent feeds should carry claim status

If generated claims are published to agent-facing feeds, the feed should not hide claim lifecycle.

A feed item can include approved generated claims, but it should also carry projection status, scope, allowed use, source freshness, inherited refusal state, and expiry.

type GeneratedCommerceClaimSummary = {
  claimId: string;
  kind: GeneratedClaimKind;
  status: GeneratedClaimStatus;
  allowedUses: GeneratedClaimUse[];
  scope: GeneratedClaimScope;
  axes: Record<
    "source" | "freshness" | "scope" | "surface" | "use" | "payload" | "taint",
    GeneratedClaimAxis
  >;
  inheritedRefusalCount: number;
  expiresAt?: string;
  evidenceRefs: Array<{
    type: string;
    id: string;
    hash: string;
    hashAlgorithm: "sha256";
  }>;
};

For the Travel Backpack, the feed should not publish:

Ready to ship and easy to return.

Inventory is stale and return-policy coverage is missing.

The feed may publish something narrower:

Travel Backpack is discoverable and comparable on known product facts. Checkout is currently blocked because inventory requires revalidation and return-policy coverage is missing.

if that statement is derived from current eligibility decisions and checkout state and approved for agent use.

Agent feeds should not make a product look more ready than the eligibility layer allows.

Protocol adapters should not generate commercial claims on the fly

Part 5 argued that protocol adapters should translate domain decisions rather than own commercial meaning.

The same rule applies to generated claims.

A protocol adapter should not receive a request and ask a model to produce a fresh policy summary, checkout explanation, or recommendation without using the claim lifecycle.

Bad boundary:

async function policyToolAdapter(req: PolicyRequest) {
  const policyText = await policies.getPolicyPage(req.productId);

  return model.generate(
    `Summarize the return policy for this product: ${policyText}`
  );
}

This bypasses policy facts, quotability, review, scope, allowed use, and audit.

Better boundary:

async function policyToolAdapter(req: PolicyRequest) {
  const decision = await commerce.evaluateIntent({
    requestedAction: "quote_policy",
    productId: req.productId,
    context: req.context,
    actor: req.actor
  });

  const claim = await claims.getClaimEnvelopeForDecision(decision);

  return projectPolicyAnswer(decision, claim, {
    surface: "agent_tool",
    use: "quote_policy"
  });
}

The adapter can still project the response into protocol format. It should not invent the commercial claim.

Generated text belongs behind the same evidence and decision boundaries as the rest of the platform. A surface should receive a projected value only after the claim envelope has checked the requested use and carried forward any upstream refusal.

Operator tasks should come from claim failures

Generated-claim failures should create operator work when they are actionable.

For the Travel Backpack:

Generated description:
pending review

Return-policy summary:
blocked because no return-policy fact applies to Travel Bags

Inventory sentence:
invalidated because inventory freshness expired

Operator tasks might be:

Review generated product description for BAG-TRAVEL-42.

Attach or approve return-policy coverage for Travel Bags.

Regenerate or reapprove availability copy after inventory revalidation.

The task should include impact:

Impact:
Agents can discover and compare this product using known facts, but generated product description is not approved for agent publication.

Impact:
Agents cannot quote return terms or use return-policy summaries for Travel Bags until policy coverage is resolved.

This prevents generated-claim problems from remaining invisible until an agent produces an unsafe answer.

Audit should record claim creation and use

Audit should not only record that a claim was generated.

It should record how the claim was created, reviewed, published, invalidated, and used.

Useful audit events include:

Claim generated
Claim evidence bound
Claim review requested
Claim approved
Claim rejected
Claim published to feed
Claim quoted by agent
Claim used in checkout explanation
Claim used in payment explanation
Claim invalidated
Claim superseded

A useful audit trail can answer:

Which source facts supported this generated claim?
Was it approved?
Who or what approved it?
Where was it allowed to be used?
Was it still valid when the agent quoted it?
Which product, policy, eligibility, checkout, or payment decision did it depend on?
Why was it invalidated?
Which replacement claim superseded it?

This matters because generated text can affect buyer expectations.

If a buyer asks why an agent said a product could be returned, the platform should be able to trace the answer back to the policy fact or show that the claim should not have been quoted.

Without audit, generated claims become untraceable commercial statements.

Where this model can go wrong

Generated-claim architecture improves safety, but it introduces its own failure modes.

Treating generated copy as commercial truth

Generated text should express selected facts. It should not become the fact source.

If downstream systems read generated descriptions as truth, the platform has inverted the dependency.

Reviewing the paragraph but not the claims

A paragraph may contain supported, unsupported, stale, and out-of-scope clauses.

For high-risk domains, review should consider individual assertions, not just whether the paragraph sounds good.

Approving without allowed use

A claim approved for internal review may not be safe for agent quotation.

Review should specify where the claim may be used.

Ignoring scope

A shipping claim for EU buyers should not be used for US buyers.

A consumer return-policy summary should not automatically apply to business buyers.

Letting claims outlive their dependencies

If price, inventory, policy, eligibility, checkout state, or payment authority changes, dependent generated claims may need invalidation. Source references or hashes help old approvals expire when a source changes.

Summarizing policy text without quotability

A generated policy summary should not become quotable unless the underlying policy facts are applicable and quotable.

Generating checkout explanations from logs

Checkout explanations should come from current decision envelopes and blockers, not loosely summarized logs.

Generating payment explanations from provider messages only

Payment explanations must distinguish checkout validation, checkout state, payment authority, provider authorization, payment state, and order commitment.

Allowing adapters to generate claims directly

Adapters should translate approved decisions and claims. They should not bypass claim lifecycle by generating commercial text on demand.

Recording prompts but not evidence

A prompt is not sufficient audit evidence.

The platform needs source fact references, policy fact references, decision references, review state, allowed use, use context, and the source references or hashes that grounded the claim.

Projection axes and inherited refusal state should travel with the claim decision, but they should support the explanation rather than dominate it.

Practical tests for generated claims

Generated-claim tests should focus on the boundary between source-backed facts and derived language, not on snapshotting language quality.

A useful generated-claim test includes:

Input facts
Generated claim
Claim segments
Decision references
Direct dependency projections
Expected dependency refs and provenance hash
Scope
Review status
Allowed use
Invalidation trigger
Expected publication result
Expected decision envelope

For the Travel Backpack:

Scenario	Expected result
Generated claim says “ready to ship” while inventory is stale	Claim blocked or marked stale
Generated return-policy summary exists but no return-policy fact applies to Travel Bags	Claim not quotable
EU shipping claim requested for US buyer	Claim blocked as out of scope
Warranty claim generated from known warranty fact	Claim may be approved if scope and evidence are valid
Recommendation says “best for business travel” without buyer criteria or evidence	Claim requires review or rejection
Checkout explanation generated from current blockers	Claim may be approved for checkout explanation
Checkout blocker resolved after claim generation	Old blocker explanation invalidated or superseded
Price changes after price-based generated claim	Claim invalidated or requires regeneration
Policy fact superseded after summary approval	Summary invalidated; prior authority descriptor retained for audit
Exact parent fact is repaired after dependent invalidation	Dependent becomes ready for review; commercial authority is not restored automatically
Adapter requests policy answer directly from model	Scenario test fails because adapter bypasses claim service
Same usable parent projections are supplied in different order	Dependency refs and child provenance hash remain identical
A usable parent, evidence pin, or request context changes	Child provenance hash changes even when the text does not
A dependency projection is modified without updating its `projectionHash`	Derivation is rejected
An unrelated refused projection is not supplied as a dependency	The child remains untainted
Refused generated claim is used to derive new wording	Derived claim inherits refusal and remains blocked
Inherited refusal, staleness, and review apply together	Canonical status is `inherited_refusal`; subordinate detail remains in axes and blockers
Claim is marked allowed without an allowed use	Claim fails closed through the use axis
Capability request omits claim ID, requested use, surface, or required value binding	Projection is refused
`passed` or `not_evaluated` axis carries blockers, or `failed` carries none	Canonical state is rejected
Refused parent flows through child and grandchild	Multi-hop inherited refusal remains complete
Inherited-refusal lineage exceeds the explicit limit	Construction fails instead of truncating lineage

A simplified expectation type:

type GeneratedClaimScenarioExpectation = {
  claimKind: GeneratedClaimKind;

  expectedStatus: GeneratedCommerceClaimStatus;
  expectedInvalidated: boolean;

  expectedAllowedUses: GeneratedClaimUse[];
  expectedSupportStatuses: ClaimSupportStatus[];
  expectedBlockerCodes: string[];
  expectedDecisionRecord: boolean;
};

The purpose of these tests is not to snapshot generated copy.

It is to test that generated commercial claims cannot escape their source facts, scope, review status, allowed use, lifecycle, direct dependency projections, or inherited refusal state. The tests should prove that an allowed claim cannot survive a failed or unevaluated required axis, an empty allowed-use set, or an incomplete claim/use/surface/value binding.

They should also confirm canonical status precedence, axis/blocker coherence, deterministic dependency ordering, and that changing or tampering with a parent projection changes the child’s provenance.

For the Travel Backpack, the dangerous shortcut is clear:

Inventory is stale.
Return-policy coverage is missing.
A generated sentence says the product is ready to ship.
A generated return summary exists.

Expected meaning:

The generated shipping sentence cannot override stale inventory.
The generated return summary cannot become quotable without a return-policy fact.
Checkout remains blocked.
Delegated payment remains blocked.
The envelope carries generated-claim blocker codes and source fact references.

Generated language is allowed only when it can point back to approved source facts, current decisions, and an allowed use.

A practical implementation path

A platform can introduce generated-claim controls incrementally.

Define generated claim types.

Start with product descriptions, policy summaries, comparisons, recommendations, checkout explanations, and payment explanations.

Store generated claims as records.

Do not store high-risk generated text only as loose strings.

Attach and bind dependencies.

Record product facts, price facts, inventory facts, policy facts, eligibility decisions, checkout state, and payment authority decisions. When a claim depends on another projected claim, retain and hash-verify the direct dependency projection for every usable or refused parent and include those references in the child’s canonical provenance hash.

Add allowed-use controls.

Separate internal review, storefront display, agent discovery, agent comparison, policy quotation, checkout explanation, and payment explanation.

Add review workflow.

Use human review for high-risk claims and automated validation for lower-risk claims where appropriate.

Add scope.

Track product, category, region, buyer type, channel, and language.

Add invalidation triggers.

Invalidate claims when source facts, policy facts, eligibility decisions, checkout state, payment authority decisions, or review status change.

Add expiry.

Use expiry for claims based on volatile data such as price, inventory, delivery estimates, promotions, checkout state, or payment state.

Prevent adapter bypass.

Require protocol adapters to retrieve approved claims or decision-derived explanations instead of generating commercial text directly.

Audit claim lifecycle and use.

Record generation, evidence binding, review, approval, publication, quotation, invalidation, supersession, and use context.

This path allows teams to use generated content without letting it become uncontrolled commercial truth.

The tradeoff

Generated-claim lifecycle adds work.

It requires claim records, evidence references, review decisions, allowed-use controls, invalidation, expiry, testing, and audit.

For low-risk internal drafts, that may feel heavy. A merchant may want to generate product copy quickly and edit it manually.

Agent-ready commerce changes the threshold.

Once generated claims can be published to agent feeds, quoted by agents, used in policy summaries, used in checkout explanations, or used near payment decisions, the platform needs stronger controls.

The tradeoff is between content velocity and commercial reliability.

Loose generated text is faster to create.

Structured generated claims are easier to review, scope, invalidate, test, and audit.

The goal is not to make every generated sentence bureaucratic. The goal is to prevent generated text from becoming a hidden source of product truth, policy interpretation, checkout explanation, or payment authority.

The claim lifecycle

Generated commerce text is not just content.

In an agent-ready platform, generated text can become a buyer-facing commercial claim. It can describe products, summarize policies, compare options, recommend actions, explain checkout blockers, or describe payment authority.

That makes lifecycle as important as language quality.

The lifecycle should keep the chain explicit:

Source facts and decisions
      ↓
Generated claim
      ↓
Evidence binding
      ↓
Review decision
      ↓
Projection gate
      ↓
Projection axes and inherited refusal state
      ↓
Publication or protocol projection
      ↓
Invalidation and expiry
      ↓
Audit

For the Travel Backpack, this means generated claims must respect the current commercial state:

Inventory is stale.
Return-policy coverage is missing for Travel Bags.
EU shipping is known.
US shipping is unknown.
Generated description is pending review.
Checkout preparation is blocked.
Delegated payment is blocked.

A generated sentence cannot make unsupported claims safe.

It can only express supported claims within the scope, use, and lifecycle the platform has approved.

Next in the series

Part 9 will move from generated claims to evidence and audit:

Agent-Ready Commerce, Part 9: Evidence and Audit Are Part of the Product

That article will examine why agent-facing commerce needs decision envelopes, evidence references, replayable inputs, protocol-safe explanations, operator timelines, and audit trails as core product capabilities rather than backend logging details.

About the author

Written by Dimitrios S. Sfyris, Founder & Software Architect at AspectSoft.

AspectSoft designs and develops custom software platforms, e-commerce systems, SaaS infrastructure, integrations, analytics tools, and practical digital products.

You can also follow the AspectSoft LinkedIn page for updates on software platforms, commerce systems, AI tooling, and developer-focused products.

Agent-Ready Commerce, Part 7: Delegated Payment Needs More Than a Token

Dimitrios S. Sfyris — Mon, 29 Jun 2026 10:15:49 +0000

Delegated payment is not a question of whether a token exists.

The real question is whether this exact payment request is still inside the buyer's delegated authority at the moment of execution.

That distinction matters.

A token, signed message, mandate reference, payment artifact, or protocol payload may be technically valid: the signature verifies, the artifact has not expired, and the issuer is trusted. That still does not prove that the current cart, amount, currency, merchant, actor, and checkout state are authorized.

May this actor request this payment action for this buyer, merchant, checkout snapshot, amount, currency, and time window?

That question cannot be answered by token presence alone.

It depends on checkout state, cart snapshot integrity, amount limits, currency, merchant binding, actor authority, buyer authority, confirmation rules, expiry, revocation, payment-attempt state, evidence, and audit.

Agent-ready commerce needs delegated payment to be modeled as bounded authority, not as a credential that turns checkout into payment.

Series context

This is the seventh article in the Agent-Ready Commerce series.

Part 1 introduced the broader architecture model:

Facts → Eligibility → Authority → State transition → Evidence → Audit

This article focuses on payment authority.

The central argument is that delegated payment is a scoped authority decision over a specific checkout snapshot. A payment artifact may be evidence for that decision, but it is not the decision itself.

A safe platform follows this chain:

Payment artifact
      ↓
Mandate scope
      ↓
Checkout snapshot match
      ↓
Authority decision
      ↓
Payment execution
      ↓
Order commitment
      ↓
Evidence and audit

Each step answers a different question. Collapsing them into “token valid, proceed” creates unsafe payment behavior.

The exact question matters

Delegated payment should begin with a precise decision question.

Not:

Is the token valid?

Not:

Does the agent have a payment artifact?

Not:

Is there a saved payment method?

The question is:

May this actor request this payment action for this buyer, merchant, checkout snapshot, amount, currency, and time window?

Each part of the question carries meaning.

This actor matters because not every caller may act on behalf of the buyer.

This buyer matters because authority is tied to the party whose funds, account, or payment instrument will be used.

This merchant matters because permission to buy from one merchant does not automatically apply to another merchant or marketplace seller.

This checkout snapshot matters because carts can change.

This amount matters because a mandate may have a limit.

This currency matters because €150 is not the same authority as $150 or an automatically converted amount.

This time window matters because authority can expire or be revoked.

A delegated payment system should make these dimensions explicit instead of hiding them behind a generic authorization field.

Payment artifact, mandate, authority decision, and execution answer four different questions

Several payment-related concepts are often collapsed into one word. Separating them makes the payment boundary easier to reason about.

Concept	Meaning
Payment artifact	A token, signed payload, reference, or protocol object presented to the platform
Mandate	The bounded delegation the buyer or authority source granted
Authority decision	The platform’s payment-specific evaluation of whether the request is inside the mandate once actor authority and checkout validity permit evaluation
Execution	The provider-facing payment attempt

The artifact is evidence.

The mandate is scope.

The authority decision is the platform answer.

Execution is a state-changing action.

A valid artifact can support authority evaluation, but it cannot create product eligibility, repair incomplete checkout state, override stale inventory, or invent missing policy coverage.

That is why delegated payment belongs in the shared decision envelope as a payment section, not as an adapter-local flag:

payment.authorityResult
payment.blockerCodes
payment.paymentDispatchAttempted

The Travel Backpack example

Continue with the running example from Parts 2–6:

Product: Travel Backpack
SKU: BAG-TRAVEL-42
Price: €129
Catalog status: active
Inventory status: in_stock
Category: Travel Bags

The commercial truth layer currently says:

Price: fresh
Inventory: stale
Return policy: missing for Travel Bags
Warranty policy: known
Shipping policy: known for EU, unknown for US
Generated description: pending review
Feed publication: last published yesterday

From Part 3, the action matrix was:

Action	Result
`discover`	allowed
`compare`	allowed
`quote_policy`	blocked
`add_to_cart`	requires_revalidation
`prepare_checkout`	blocked
`delegate_payment`	blocked

From Part 6, checkout preparation is blocked because inventory is stale and return-policy coverage is missing.

Now suppose a buyer tells an agent:

Buy the Travel Backpack if the final total is under €150.

The agent may also carry a payment-related artifact that appears to authorize a purchase up to €150 in EUR.

Delegated payment should still be blocked.

The reason is not that the amount is too high. The product price is €129. The reason is that checkout state is not valid for payment.

The payment artifact cannot make stale inventory fresh. It cannot create return-policy coverage for Travel Bags. It cannot make unknown US shipping terms known. It cannot approve generated product text. It cannot turn a blocked checkout transition into a valid one.

The platform should answer:

Delegated payment is blocked because checkout state is not valid for payment.
Payment authority is not evaluated.
Payment dispatch is not attempted.

A safe causal chain is:

delegate_payment blocked
      ↓
checkout state is not valid for payment
      ↓
prepare_checkout is blocked
      ↓
inventory is stale
return-policy coverage is missing

That chain should remain visible in the decision, evidence, and audit trail.

Three kinds of authority

Delegated payment involves several kinds of authority, not one.

Buyer authority:
Did the buyer permit this actor to act?

Platform authority:
Does the platform allow this actor and action under its own rules?

Payment-provider authorization:
Did the payment provider authorize or accept the payment attempt?

These are different.

A buyer may authorize an agent to purchase an item, but the platform may still block the action because checkout state is not valid for payment.

The platform may allow the agent to request payment, but the payment provider may decline the payment attempt.

The payment provider may authorize a payment, but the platform may still fail to commit the order because final order checks fail.

The boundaries are:

Buyer authority is not checkout validation.
A valid checkout state is not provider authorization.
Provider authorization is not order commitment.

A safe delegated payment design does not collapse these states.

A token is not a mandate

A token may be part of a mandate, but it is not the mandate by itself.

A delegated payment mandate should answer:

Who is the buyer?
Which actor is allowed to act?
Which merchant is in scope?
Which checkout or cart snapshot is in scope?
What is the maximum amount?
Which currency is allowed?
Which payment actions are allowed?
When does the authority expire?
Can it be revoked?
Is human confirmation required?
Which evidence supports the authority?

A simplified TypeScript model might look like this:

type AgentCommerceMandateStatus =
  | "ACTIVE"
  | "ACCEPTED"
  | "CONSUMED"
  | "REVOKED"
  | "EXPIRED";

type AgentCommerceMandateAction =
  | "delegate_payment"
  | "complete_checkout";

type EvidenceRef = {
  type: string;
  id: string;
  hash: string;
  hashAlgorithm: "sha256";
};

type AgentCommerceMandateRecord = {
  mandateId: string;
  status: AgentCommerceMandateStatus;

  buyerId: string;

  actor: {
    actorId: string;
    actorType: "buyer" | "agent" | "operator" | "system";
  };

  scope: {
    merchantId: string;
    cartSnapshotId: string;
    maxAmount: number;
    currency: string;
    allowedActions: AgentCommerceMandateAction[];
  };

  confirmation: {
    required: boolean;
    satisfied: boolean;
    confirmationRef?: string;
  };

  lifecycle: {
    createdAt: string;
    expiresAt: string;
    revokedAt?: string;
    revokedReason?: string;
    usedAt?: string;
  };

  evidenceRefs: EvidenceRef[];
};

This is intentionally simplified. Real systems may need account-level rules, payer identities, payment instruments, billing addresses, risk checks, marketplace seller relationships, provider references, regional compliance rules, or contract terms.

The important property is scope.

Without scope, the platform cannot show that a payment request is still inside the buyer’s delegated authority.

The current mandate record should keep the scope that is valid now, while one meaningful mandate event history records creation, confirmation, consumption, revocation, expiry, and rejected use. Confirmation, checkout snapshot, amount, currency, merchant, and boundary hash are part of what the platform compares at execution time. A mandate valid for one snapshot should not silently authorize payment against a changed one.

Evaluate authority again at execution time

A delegated payment decision should reflect the current checkout, mandate, and payment request—not an earlier version of them.

It is not enough to evaluate authority when the agent starts the flow and assume it remains valid until payment. The cart may change. The checkout may expire. The mandate may be revoked. The amount may change. Currency may change. A required confirmation may no longer apply because the commercial state changed.

The platform should evaluate authority at the point of payment execution.

A simplified decision type:

type EvidenceRef = {
  type: string;
  id: string;
  hash: string;
  hashAlgorithm: "sha256";
};

type AgentCommercePaymentAuthorityVerdict = {
  decisionId: string;

  actorId: string;
  buyerId: string;
  merchantId: string;

  checkoutId: string;
  cartSnapshotId: string;
  mandateId: string;

  requestedAction: AgentCommerceMandateAction;
  requestedAmount: number;
  currency: string;

  result:
    | "allowed"
    | "blocked"
    | "requires_confirmation"
    | "requires_revalidation";

  blockers: Array<{
    code: string;
    message: string;
    nextAction?: string;
  }>;

  evidenceRefs: EvidenceRef[];
  evaluatedAt: string;
};

For the Travel Backpack:

const decision: AgentCommercePaymentAuthorityVerdict = {
  decisionId: "decision_001",
  actorId: "agent_123",
  buyerId: "buyer_456",
  merchantId: "merchant_001",
  checkoutId: "checkout_789",
  cartSnapshotId: "snapshot_abc",
  mandateId: "mandate_001",
  requestedAction: "delegate_payment",
  requestedAmount: 129,
  currency: "EUR",
  result: "blocked",
  blockers: [
    {
      code: "invalid_checkout_state",
      message:
        "Delegated payment cannot proceed because checkout preparation is blocked.",
      nextAction:
        "Resolve checkout blockers before requesting delegated payment."
    }
  ],
  evidenceRefs: [
    {
      type: "checkout_state",
      id: "checkout:checkout_789:state",
      hash: "<sha256-of-canonical-checkout-snapshot>",
      hashAlgorithm: "sha256"
    },
    {
      type: "eligibility_decision",
      id: "eligibility:BAG-TRAVEL-42:prepare_checkout",
      hash: "<sha256-of-canonical-eligibility-decision>",
      hashAlgorithm: "sha256"
    }
  ],
  evaluatedAt: "2026-06-28T09:00:00Z"
};

This decision does not need to reimplement checkout. It references the checkout state.

That is the point of the chain.

Payment authority depends on valid checkout state. It does not replace checkout validation.

Valid checkout state comes first

A delegated payment system should not evaluate payment authority in isolation from checkout state. If actor authority or checkout validity prevents that evaluation, payment authority should remain not_evaluated with no payment-specific blockers. The checkout or authority section retains the actual reason the operation cannot proceed.

The safer order is:

Commercial truth
      ↓
Eligibility
      ↓
Checkout state
      ↓
Payment authority
      ↓
Payment execution
      ↓
Order commitment

Payment authority should not bypass earlier checks.

A buyer may authorize an agent to buy the Travel Backpack up to €150. That does not mean:

Ignore stale inventory.
Ignore missing return policy.
Ignore unsupported shipping region.
Ignore generated-claim review.
Ignore checkout expiry.

It means:

If checkout state is valid for payment and the payment request matches the mandate scope, the actor may request payment within the mandate’s limits.

That is a narrower and safer statement.

The buyer can authorize an agent to act. The platform must still decide whether the action is commercially valid.

Cart snapshots are the evidence boundary

A mandate should bind to a checkout snapshot, not only to a cart ID.

A cart ID identifies a mutable container. It does not show that the cart contents, price, currency, shipping region, tax, policy coverage, or total are unchanged.

A cart snapshot records the commercial state that was evaluated.

type CartSnapshot = {
  snapshotId: string;
  cartId: string;

  items: Array<{
    sku: string;
    quantity: number;
    priceAmount: number;
    currency: string;
  }>;

  totals: {
    subtotal: number;
    shipping?: number;
    tax?: number;
    total: number;
    currency: string;
  };

  merchantId: string;

  context: {
    region?: string;
    buyerType?: "consumer" | "business";
    channel: "storefront" | "agent" | "marketplace";
  };

  factRefs: string[];
  policyFactRefs: string[];
  createdAt: string;
};

Before payment, the platform should verify:

Does the checkout use the same snapshot?
Do the items match?
Does the total remain within the mandate?
Does the currency match?
Does the merchant match?
Has the snapshot expired?

This prevents a critical failure mode:

Buyer authorizes one cart.
Cart changes.
Agent requests payment for the changed cart.
Platform treats the old authority as valid.

That should not be possible.

If the cart changes after authority is granted, the platform should require revalidation or a new mandate.

Amount limits need exact semantics

A buyer instruction such as “under €150” is not enough unless the platform defines what the amount includes.

Does the limit include shipping?

Does it include tax?

Does it include discounts?

Does it allow partial capture?

Does it allow a lower amount?

Does it allow multiple attempts?

Does it allow currency conversion?

A useful amount scope is explicit:

type AmountScope = {
  maxAmount: number;
  currency: string;

  includesShipping: boolean;
  includesTax: boolean;

  allowLowerAmount: boolean;
  allowPartialCapture: boolean;

  maxPaymentAttempts: number;
};

For the Travel Backpack:

Product price: €129
Buyer limit: €150
Currency: EUR

The product price alone is not enough.

If shipping and tax bring the final total to €153, the payment request is outside the mandate even though the product price is below the limit.

A safe decision:

Delegated payment blocked.
Reason: final checkout total exceeds the mandate amount limit.

That is not a product-truth issue. It is an authority-scope issue.

Currency is part of authority

Currency should not be treated as display metadata.

A mandate for €150 is not the same as a mandate for $150, £150, or an automatically converted amount.

If currency conversion is allowed, that should be explicit. If it is not explicit, currency mismatch should block delegated payment.

type CurrencyScope = {
  currency: string;
  conversionAllowed: boolean;
  conversionSource?: string;
  maxConvertedAmount?: number;
};

A conservative delegated payment decision:

Mandate currency: EUR
Checkout currency: USD
Result: blocked
Reason: currency mismatch

A platform may support approved conversion flows, but those flows need their own rules and evidence.

Implicit conversion is not a safe default for delegated payment.

Merchant binding matters

A payment mandate should bind to a merchant, marketplace, seller, or defined merchant group.

Permission to buy from one merchant does not automatically apply to another merchant.

type MerchantScope = {
  merchantId: string;
  marketplaceId?: string;
  allowedSellerIds?: string[];
};

In a direct commerce platform, merchant scope may be simple.

In a marketplace, it may be more complex. The mandate may apply to the marketplace operator, a specific seller, or a set of sellers. It may also interact with payment routing, invoicing, returns, fulfillment responsibility, and support.

The important rule is that merchant scope is checked before payment.

Mandate merchant: merchant_001
Checkout merchant: merchant_002
Result: blocked
Reason: merchant mismatch

A protocol artifact that is valid in general is not valid for every merchant.

Actor authority and buyer authority are separate

Delegated payment involves at least two identities:

The buyer whose funds, account, or payment instrument is used.
The actor requesting the payment action.

The actor may be a human, an agent, a system process, or another delegated entity.

The platform should not confuse the buyer’s ability to purchase with the actor’s authority to act.

The buyer may be eligible to buy, but the agent may not be authorized to request payment.

The agent may have authority to prepare checkout but not to authorize payment.

The agent may have authority for one cart snapshot but not another.

A platform should evaluate:

Buyer eligibility:
Can this buyer make this purchase?

Actor authority:
Can this actor request this payment action for this buyer?

Mandate scope:
Does the request match cart, amount, currency, merchant, time, and confirmation rules?

A simplified actor authority model:

type ActorAuthority = {
  actorId: string;
  buyerId: string;

  allowedActions: AgentCommerceMandateAction[];

  constraints: {
    merchantId?: string;
    cartSnapshotId?: string;
    maxAmount?: number;
    currency?: string;
  };

  status: "ACTIVE" | "ACCEPTED" | "EXPIRED" | "REVOKED";
};

The existence of a protocol request does not establish actor authority.

The platform must evaluate it.

Confirmation is authority evidence

Some delegated payment flows require human confirmation.

The buyer may allow an agent to prepare checkout but require confirmation before payment. Or the buyer may pre-authorize payment up to a limit without additional confirmation. Or confirmation may be required only when the cart, shipping, total, or policy terms change.

Confirmation should be modeled explicitly.

type ConfirmationRule = {
  required: boolean;

  requiredWhen?: Array<
    | "amount_changed"
    | "cart_changed"
    | "shipping_changed"
    | "policy_changed"
    | "risk_review_required"
  >;

  satisfiedAt?: string;
  confirmationRef?: string;
};

Examples:

No confirmation required:
Agent may request payment if the final total is within mandate scope.

Confirmation required:
Agent may prepare checkout, but buyer must approve before payment.

Conditional confirmation:
Buyer approval is required if the total increases or shipping changes.

A chat message such as “yes, buy it” should not become payment authority unless the platform records it as a structured confirmation tied to a specific snapshot, scope, and evidence reference.

Presentation is not authority.

Confirmation becomes authority evidence only when the platform captures it as such.

Expiry and revocation are first-class

A mandate should expire.

It should also be revocable.

Expiry handles time-based risk. Revocation handles buyer decisions, fraud signals, support actions, account restrictions, or business rules that invalidate authority before the expiry time.

type MandateLifecycle = {
  status: AgentCommerceMandateStatus;

  createdAt: string;
  expiresAt: string;

  revokedAt?: string;
  revokedReason?: string;

  usedAt?: string;
};

Before payment execution, the platform should check the current mandate status and compare the payment request with the mandate scope and evidence.

Mandate was active when checkout was prepared.
Mandate was revoked before payment was requested.
Result: blocked.

This should not depend on the agent’s memory, an adapter cache, or a stale protocol response.

One delegated-authority owner should own mandate state, scope, confirmation, consumption, revocation, and mandate events.

Payment execution is also a state transition

Requesting payment is not only an API call to a payment provider.

It is a state transition in the commerce platform.

A simplified checkout and payment path might look like this:

requires_payment
      ↓
payment_authorized
      ↓
order_submitted
      ↓
completed

A provider timeout or delayed webhook does not justify inventing a successful transition. The payment attempt can remain pending or ambiguous in the payment domain while the checkout stays at the last state supported by evidence.

Some platforms authorize and capture separately. Some capture immediately. Some support invoice flows, wallet flows, marketplace settlement, stored instruments, or manual review. The exact states vary.

The design rule is stable:

Payment execution should have explicit preconditions, outcomes, evidence, and audit.

A payment request should record:

Which checkout snapshot was used
Which mandate was evaluated
Which authority decision was produced
Which amount and currency were requested
Which provider request was made
Which response was received
Whether the result is final or ambiguous
Which audit event was recorded

This prevents the payment provider call from becoming an opaque side effect.

Provider authorization is not order commitment

A payment provider may authorize or accept a payment attempt. That still does not mean the order has been committed.

The platform may need to create the order, reserve or allocate inventory, write invoices, emit events, trigger fulfillment, update customer records, and produce audit evidence.

Order commitment should be its own transition.

Payment authorized
      ↓
Commit order command
      ↓
Final validation
      ↓
Order committed

Final validation may include:

Cart snapshot still matches
Payment result satisfies order rules
Inventory reservation is valid
Merchant and buyer are still eligible
No revocation occurred before commitment
No duplicate order exists for the same idempotency key

This separation matters because payment and order can fail independently.

Payment can be authorized but order creation can fail.

Order creation can succeed while fulfillment later fails.

Payment may need to be reversed if order commitment cannot complete.

These states should be explicit enough for recovery, support, and audit.

Idempotency is mandatory

Delegated payment operations must be idempotent.

Agent-facing systems retry. Protocol calls can time out. Payment providers may return ambiguous responses. Users may confirm twice. Agents may repeat a command after not receiving a result.

A payment command should include an idempotency key:

type PaymentCommand = {
  commandId: string;
  idempotencyKey: string;

  checkoutId: string;
  cartSnapshotId: string;
  mandateId: string;

  requestedAction: AgentCommerceMandateAction;
  requestedAmount: number;
  currency: string;

  requestedAt: string;
};

The platform should enforce idempotency at the payment-transition boundary, not only in the adapter.

Example:

First request:
complete_delegated_payment is submitted to the provider after checkout state, mandate scope, and payment authority pass.

Network response:
lost.

Retry with same idempotency key:
platform returns the existing payment attempt state instead of creating a second authorization.

Idempotency should be tied to the commercial command.

If cart snapshot, amount, currency, merchant, or mandate changes, the platform should not treat the new request as the same command.

Idempotency prevents duplicate execution. It should not hide meaningful changes.

Before calling the provider, the platform should persist a dispatch intent tied to the payment execution, provider idempotency key, current lease or fence, and canonical provider-command hash.

If the process loses the provider response, the outcome is unknown. Lease expiry does not make a retry safe. The execution should enter reconciliation and be resolved through provider lookup or a verified webhook before another dispatch can occur.

Ambiguous payment outcomes need explicit state

Payment systems can return ambiguous outcomes.

Examples:

Provider request timed out.
Provider accepted request but response was lost.
Payment is pending buyer action.
Payment is under review.
Authorization succeeded but capture failed.
Capture status is unknown.
Webhook has not arrived.

A delegated payment model needs states for these conditions.

type AgentCommercePaymentExecutionStateKey =
  | "CREATED"
  | "PAYMENT_AUTHORIZED"
  | "ORDER_SUBMITTED"
  | "COMPLETED"
  | "FAILED"
  | "BLOCKED"
  | "REQUIRES_RECONCILIATION";

The platform should not commit an order unless the payment state satisfies the platform’s order rules.

For example:

Payment execution requires reconciliation.
Order commitment is blocked until the payment result is resolved.

or:

Payment authorized.
Order may be committed if the platform allows authorization-before-capture.

The correct rule depends on the business and payment model. The important point is that ambiguous payment is not treated as success or failure without evidence.

If capture is confirmed but order finalization fails, recovery should resume from the existing payment execution and stable commercial idempotency identity. It should reuse an existing order result or complete order creation without dispatching payment again.

Protocol adapters should not interpret payment authority

Part 5 argued that adapters should translate domain decisions rather than own them. Delegated payment is where that boundary matters most.

An AP2-related adapter or any payment-oriented protocol adapter may receive a structured payment artifact. It may validate protocol shape. It may verify envelope requirements if that belongs at the protocol boundary. It may extract references and pass them into the platform.

It should not decide that payment is allowed.

Bad boundary:

async function paymentAdapter(req: ProtocolPaymentRequest) {
  if (req.paymentToken && req.amount <= req.paymentToken.maxAmount) {
    return payments.charge(req.paymentToken, req.amount);
  }

  return { error: "not_authorized" };
}

This ignores checkout state, cart snapshot, merchant binding, currency, expiry, revocation, confirmation, idempotency, and audit.

Better boundary:

async function paymentAdapter(req: ProtocolPaymentRequest) {
  const command = mapToPaymentCommand(req);

  const result = await paymentAuthority.evaluateAndExecute(command);

  return projectPaymentResult(result);
}

The adapter translates. The authority and payment domains decide.

This keeps payment semantics inside the platform instead of scattering them across protocol integrations.

Generated messages cannot become payment authority

Agent-facing systems may generate buyer-facing messages such as:

I found the Travel Backpack for €129 and can buy it for you.

or:

The total is under your €150 limit. Proceeding with payment.

These messages are not authority.

A generated statement does not establish buyer consent. It does not bind the cart snapshot. It does not verify currency. It does not satisfy confirmation unless the platform records confirmation as a domain event.

A safe model is:

Generated message:
Presentation or explanation.

Buyer confirmation:
Recorded authority event.

Payment mandate:
Structured scope created or updated from confirmation.

Payment decision:
Evaluation of mandate against checkout state.

Payment execution:
State transition using the decision.

If the buyer says “yes” in a conversation, the platform may treat that as input to a confirmation flow only if it captures the confirmation as structured evidence for a specific payment scope.

Free-text conversation is not enough unless the platform has a defined way to turn it into evidence.

Evidence should attach to authority decisions

A payment authority decision should be evidence-backed.

For an allowed decision, evidence may include:

Mandate record
Cart snapshot
Checkout state
Amount calculation
Currency
Merchant binding
Actor authority record
Confirmation record
Expiry check
Revocation check

For a blocked decision, evidence may include:

Expired mandate
Revoked authority
Cart snapshot mismatch
Amount exceeds limit
Currency mismatch
Merchant mismatch
Checkout state not valid for payment
Confirmation missing

A simplified evidence reference model:

type PaymentEvidenceRef = {
  type:
    | "payment_mandate"
    | "cart_snapshot"
    | "checkout_state"
    | "authority_record"
    | "confirmation_record"
    | "payment_attempt"
    | "provider_response"
    | "audit_event";
  id: string;
  hash: string;
  hashAlgorithm: "sha256";
};

The platform should be able to explain:

Why was delegated payment allowed?
Why was it blocked?
Which mandate was used?
Which cart snapshot was bound?
Which confirmation was satisfied?
Which provider response was received?

This is necessary for debugging, support, reconciliation, agent behavior, and audit.

For state-mutating and payment-blocking decisions, those evidence references should be hash-pinned rather than merely named.

A decision that blocks or permits payment is exactly where an unverifiable evidence reference is most expensive.

Audit should record the mandate path

Payment audit needs more detail than “payment attempted.”

A useful audit record includes:

Actor
Buyer
Merchant
Protocol or channel
Checkout ID
Cart snapshot ID
Mandate ID
Requested amount
Currency
Authority decision
Payment command
Idempotency key
Provider request reference
Provider response reference
Payment attempt state
Order commitment result
Evidence references
Timestamps

This allows the platform to answer:

Did the buyer authorize this payment?
Did the agent stay within the mandate?
Was the cart changed after authorization?
Did the total exceed the limit?
Was confirmation required?
Was confirmation satisfied?
Did the mandate expire before payment?
Was the payment retried?
Was the order committed once or twice?
Which adapter initiated the request?

Without this audit path, the platform may know that payment happened but not why it was allowed.

For delegated payment, that is not enough.

Operator remediation still matters

Not every delegated payment failure is a buyer or payment-provider problem.

Some blockers are operational:

Policy coverage missing
Inventory stale
Shipping terms unknown
Payment provider configuration missing
Merchant binding missing
Mandate cannot be evaluated
Confirmation workflow not configured
Webhook reconciliation failed

The platform should route actionable blockers to operator tasks.

For the Travel Backpack:

Delegated payment blocked:
checkout state is not valid for payment

Checkout blockers:
inventory stale
return-policy coverage missing

Operator task:

Resolve return-policy coverage for Travel Bags.

Impact:
Agents cannot prepare checkout or proceed to delegated payment for affected products.

Payment authority should not hide upstream blockers. It should preserve the causal chain so the right team fixes the right domain.

Where this model can go wrong

Delegated payment modeling improves safety, but it introduces its own failure modes.

Treating token validity as authority

A valid token is not enough. The platform must evaluate mandate scope, checkout state, cart snapshot, amount, currency, merchant, expiry, revocation, and confirmation.

Treating checkout validation as payment authority

A valid checkout state does not mean an actor may request payment. Payment authority is a separate domain.

Treating provider authorization as order commitment

A provider authorization may satisfy one payment condition. It does not mean the order has been committed or that final order checks can be skipped.

Binding authority to a mutable cart

If the mandate references only a cart ID, the cart may change after authorization. Authority should bind to a stable snapshot or require revalidation when the cart changes.

Ignoring amount semantics

A limit such as €150 must define whether shipping, tax, discounts, currency conversion, partial capture, and retries are allowed.

Ignoring currency

Currency mismatch should block payment unless conversion is explicitly modeled and authorized.

Ignoring merchant scope

A mandate for one merchant should not be usable for another merchant or seller unless the scope explicitly allows it.

Making confirmation a UI-only concept

Confirmation should be recorded as a domain event when it affects authority. A button click, chat response, or external approval should become structured evidence if it authorizes payment.

Handling idempotency only in the adapter

Payment idempotency must be enforced at the payment-transition boundary. Adapter-local deduplication is not enough.

Treating ambiguous provider responses as failure or success too early

Timeouts and pending responses need explicit payment-attempt states. Order commitment should wait for a payment state that satisfies platform rules.

Hiding upstream blockers

If delegated payment fails because checkout state is not valid for payment, the platform should preserve the checkout blocker. Otherwise agents and operators may retry payment when the real issue is policy, inventory, or checkout state.

Practical tests for delegated payment

Delegated payment should be tested with scenario flows, with provider calls used only after checkout and authority boundaries are clear.

A useful delegated-payment test includes:

Checkout state
Cart snapshot
Mandate scope
Actor
Buyer
Merchant
Amount
Currency
Expiry
Revocation
Confirmation
Payment attempt state
Expected authority decision
Expected paymentDispatchAttempted value
Expected payment attempt transition
Expected decision envelope

The Travel Backpack scenario is enough to catch the dangerous shortcut:

Price: €129, fresh
Inventory: stale
Return policy: missing
Payment artifact: present
Mandate limit: €150

The expected result is not:

price < mandate limit, so pay

The expected result is:

Delegated payment is blocked.
The checkout and decision basis preserve invalid_checkout_state, stale_inventory, and missing_return_policy.
The payment section reports `authorityResult: not_evaluated` with no payment blockers.
Payment dispatch is not attempted.

That test should use the same decision meaning as feed, tool, checkout, and admin projections. It does not need to simulate an entire payment provider. In this blocked scenario, the provider should never be reached.

A broader scenario set should emphasize negative cases because delegated payment safety depends more on correct refusal than on the happy path.

For the Travel Backpack:

Scenario	Expected result
Payment artifact present but checkout blocked	Delegated payment blocked; payment authority `not_evaluated`; checkout and basis preserve `invalid_checkout_state` and the upstream commercial blockers
Checkout state is valid but no mandate exists	Payment blocked with `mandate_missing`
Mandate exists but cart snapshot changed	Payment blocked with `cart_snapshot_mismatch`
Mandate limit €150, final total €153	Payment blocked with `amount_exceeds_mandate`
Mandate currency EUR, checkout currency USD	Payment blocked with `currency_mismatch`
Mandate merchant differs from checkout merchant	Payment blocked with `merchant_scope_violation`
Mandate expired before payment request	Payment blocked with `mandate_expired`
Mandate revoked before payment request	Payment blocked with `mandate_revoked`
Confirmation required but not satisfied	Payment returns `human_confirmation_required`
Confirmation satisfied and all scope checks pass	Payment may proceed to provider request
Provider response times out	Payment attempt enters ambiguous or pending state
Active execution lease expires after an ambiguous provider call	Execution requires reconciliation; payment is not redispatched
Verified provider lookup or webhook resolves the attempt	Existing execution moves to the corresponding final or pending state
Retry with same idempotency key	Existing payment attempt result is returned
Retry with different cart snapshot	New request is rejected or requires new mandate
Payment captured but order finalization fails	Payment is not redispatched; order completion resumes from the existing execution
Payment authorized but order commit fails	Order is not duplicated; recovery or reversal path is recorded

A simplified expectation type:

type DelegatedPaymentScenarioExpectation = {
  checkoutState: "requires_payment" | "blocked" | "expired";

  mandateStatus: AgentCommerceMandateStatus;

  expectedDecision:
    | "allowed"
    | "blocked"
    | "requires_confirmation"
    | "requires_revalidation";

  expectedBlockerCodes: string[];

  expectedAgentCommercePaymentExecutionStateKey?: AgentCommercePaymentExecutionStateKey;

  expectedDecisionRecord: boolean;
};

The safety of delegated payment depends more on correct refusal than on the happy path.

A practical implementation path

A platform can implement delegated payment authority incrementally.

Separate artifact parsing from authority decisions.
Adapters may parse protocol artifacts. The delegated-authority owner decides what they mean.
Define a mandate model.
Include buyer, actor, merchant, cart snapshot, amount, currency, allowed actions, expiry, revocation, confirmation, and evidence.
Bind mandates to checkout snapshots.
Do not rely only on mutable cart IDs.
Evaluate checkout before payment.
Payment authority should not bypass checkout validation.
Enforce amount, currency, and merchant scope.
These should be explicit checks, not assumptions.
Model confirmation as authority evidence.
If confirmation is required, record it as a structured event tied to a specific scope.
Add mandate lifecycle.
Support pending confirmation, active, expired, revoked, used, and rejected states.
Make payment execution idempotent.
Retries should not create duplicate authorizations, captures, or orders.
Model ambiguous payment outcomes.
Do not treat timeouts or missing provider responses as simple success or failure.
Audit the full decision path.
Record mandate, checkout snapshot, authority decision, payment attempt, provider response, order commitment, evidence, and idempotency keys.

This path makes delegated payment safer without requiring the platform to solve every payment architecture problem at once.

The tradeoff

Delegated payment authority adds structure.

It requires mandate modeling, scope checks, snapshot binding, expiry, revocation, confirmation events, idempotency, payment-attempt states, evidence, and audit.

For a human-only storefront, some of this may be unnecessary. A user can review the checkout form, enter payment details, and submit payment directly.

Agent-ready commerce changes the threshold.

Once an agent can act on behalf of a buyer, the platform must show that the requested payment is still inside the buyer’s delegated authority at execution time.

The tradeoff is between convenience and bounded authority.

A token is easy to pass around.

A mandate is easier to reason about, test, revoke, trace, and explain.

The goal is not to make payment unnecessarily complex. The goal is to prevent a payment artifact from being treated as broader permission than it represents.

The key distinction

Delegated payment needs more than a token.

A token may be evidence. It may be part of a protocol. It may be part of payment execution. But agent-ready commerce needs a bounded authority model that answers a precise question:

May this actor request this payment action for this buyer, merchant, checkout snapshot, amount, currency, and time window?

For the Travel Backpack, delegated payment remains blocked even if a payment artifact exists, because checkout state is not valid for payment. Inventory is stale. Return-policy coverage is missing for Travel Bags. US shipping is unknown. A payment token cannot resolve those upstream blockers.

A safe delegated payment model keeps the chain explicit:

Commercial truth
      ↓
Eligibility
      ↓
Checkout state
      ↓
Payment authority
      ↓
Payment execution
      ↓
Order commitment
      ↓
Evidence and audit

That structure prevents protocol artifacts, generated messages, or adapter shortcuts from becoming accidental payment authority.

Next in the series

Part 8 will move from payment authority to generated commercial claims:

Agent-Ready Commerce, Part 8: Generated Claims Need Review, Evidence, and Expiry

That article will examine generated product descriptions, policy summaries, comparisons, recommendations, and checkout explanations. It will show why they should remain derived claims with review status, source references, freshness, invalidation rules, and audit—not become automatic commercial truth.

About the author

Written by Dimitrios S. Sfyris, Founder & Software Architect at AspectSoft.

AspectSoft designs and develops custom software platforms, e-commerce systems, SaaS infrastructure, integrations, analytics tools, and practical digital products.

You can also follow the AspectSoft LinkedIn page for updates on software platforms, commerce systems, AI tooling, and developer-focused products.

Agent-Ready Commerce, Part 6: Checkout Is a State Machine, Not a Form

Dimitrios S. Sfyris — Mon, 29 Jun 2026 07:38:21 +0000

Checkout is the point where agent-ready commerce stops being mostly read-only.

Discovery can return a read-only projection. Comparison can answer a query. Policy quotation can return a controlled answer backed by source evidence. Checkout is different because it mutates commercial state.

A cart changes. A price may be selected or locked. Inventory may be revalidated or reserved. Shipping options may be calculated. Policy coverage may become a precondition. A checkout snapshot may be created. Payment authority may become relevant. An order may eventually be committed.

That is why checkout should not be modeled as a form endpoint in an agent-ready platform.

It should use explicit checkout state with controlled transitions.

The issue is not user interface style. A human-facing storefront may still present checkout as a familiar sequence of screens: address, shipping, review, payment, confirmation. The issue is the backend boundary. Once agents can add items, prepare checkout, retry operations, act under buyer authority, or approach delegated payment, checkout can no longer be treated as a loose collection of request handlers.

The platform needs to know the current cart or checkout state, the requested command, the facts evaluated, and the actor authorized. It also needs to record the resulting transition, the supporting evidence, and the meaningful checkout event.

Series context

This is the sixth article in the Agent-Ready Commerce series.

Part 1 introduced the broader architecture model:

Facts → Eligibility → Authority → State transition → Evidence → Audit

This article focuses on checkout state.

The central argument is that agent-ready checkout should be treated as a controlled mutation boundary. The platform needs explicit states and commands for cart mutation, validation, checkout preparation, payment authority, retries, expiry, order commitment, evidence, and audit.

Checkout is a mutation boundary

Earlier parts of the series separated several concerns:

Commercial truth says what is known.
Policy facts say which terms apply.
Eligibility says which actions are valid.
Authority says who may request them.
Adapters translate external protocol language.

Checkout is where those concerns start producing durable consequences.

A product being discoverable does not change the product. A comparison result does not reserve inventory. A policy quotation does not create a payment obligation. Checkout can.

Even early checkout operations can matter commercially. Adding an item to a cart may affect totals. Selecting a region may change shipping options. Preparing checkout may create a snapshot. Requesting payment may depend on a mandate. Committing an order may allocate inventory and create obligations for fulfillment, support, accounting, and audit.

That is why checkout needs stronger control than read-only actions.

A useful mental model is:

Read-only actions
      ↓
Cart mutation
      ↓
Checkout preparation
      ↓
Payment authority
      ↓
Order commitment

Each step increases the cost of being wrong.

If a comparison response is incomplete, the platform can correct the answer. If a checkout state transition is wrong, the system may need to unwind a cart, release inventory, cancel a payment attempt, issue a refund, or explain why an agent acted on a stale commercial state.

The boundary from query to mutation is where the architecture needs to become more explicit.

The Travel Backpack example

Continue with the running example from Parts 2–5:

Product: Travel Backpack
SKU: BAG-TRAVEL-42
Price: €129
Catalog status: active
Inventory status: in_stock
Category: Travel Bags

The commercial truth layer currently says:

Price: fresh
Inventory: stale
Return policy: missing for Travel Bags
Warranty policy: known
Shipping policy: known for EU, unknown for US
Generated description: pending review
Feed publication: last published yesterday

From Part 3, the action matrix was:

Action	Result
`discover`	allowed
`compare`	allowed
`quote_policy`	blocked
`add_to_cart`	requires_revalidation
`prepare_checkout`	blocked
`delegate_payment`	blocked
`show_generated_claim`	requires_review
`explain`	allowed

For a human storefront, the Travel Backpack may still appear on a product page. The user can see the title, image, price, and category. Depending on the platform’s risk tolerance, the UI may still allow the user to click “Add to cart” and defer stricter checks until later.

An agent-facing platform needs more precise behavior.

An agent may ask:

Add BAG-TRAVEL-42 to the buyer’s cart.
Prepare checkout for EU delivery.
Use delegated payment if the total remains under €150.

That is not one operation.

It contains at least three different commercial steps:

Cart mutation:
Add the product to a buyer context.

Checkout preparation:
Validate whether the cart can enter checkout.

Delegated payment:
Check whether an actor may proceed under a payment authority boundary.

Each step has different preconditions.

Adding the item may require product identity, current price handling, and inventory revalidation rules.

Preparing checkout may require fresh inventory, policy coverage, shipping context, buyer type, generated-claim constraints, and a stable cart snapshot.

Delegated payment may require valid checkout state, actor authority, mandate scope, amount limits, currency match, merchant binding, expiry, revocation checks, and possibly human confirmation.

A single checkout() function cannot express those boundaries safely unless it hides a transition model inside itself. If the transition model exists, it should be modeled explicitly.

A form endpoint hides the decision path

A conventional checkout implementation can easily become endpoint-driven.

A simplified handler might look like this:

async function submitCheckout(req: Request) {
  const cart = await carts.get(req.cartId);

  await carts.updateShippingAddress(cart.id, req.shippingAddress);
  await carts.recalculateTotals(cart.id);

  const paymentSession = await payments.createSession(cart);
  const order = await orders.place(cart, paymentSession);

  return order;
}

This example is intentionally simplified, but it shows the boundary problem. Several commercial transitions are compressed into one request handler.

The handler may work for a basic human checkout form. It is weak as an agent-facing mutation boundary because the system cannot easily answer:

Which cart snapshot was evaluated?
Was inventory fresh at the time checkout was prepared?
Which policy facts were required?
Was return-policy coverage missing?
Was checkout blocked before payment?
Did the actor have authority to prepare checkout?
Did the actor have authority to request payment?
Did the cart change after authority was granted?
Was this a retry of an earlier command?
Did a previous attempt create a payment session before the response failed?
Which evidence supported the transition?

These questions matter because agents and protocol adapters may call checkout operations directly. They may retry. They may operate asynchronously. They may ask whether checkout can advance before a human would normally reach the payment screen. They may carry payment authority artifacts from outside the platform.

A checkout form can hide state from the user.

The backend should not hide state from itself.

State is not just a status field

A checkout state is not merely a label such as pending or complete. It defines which commands are valid next and which conditions must hold before the state can change. A common implementation compromise is to add only a status field:

type CheckoutStatus = "active" | "completed" | "failed";

That is not enough.

A checkout can be active but not authorized to proceed. It can be valid but not prepared. It can be prepared but waiting for payment authority. It can have authority but fail snapshot matching. It can be blocked because policy coverage is missing. It can be expired. It can be cancelled. It can be awaiting revalidation.

Those are materially different states.

A more useful model names the commercial boundaries:

type AgentCommerceCheckoutLifecycleState =
  | "created"
  | "empty"
  | "requires_address"
  | "requires_shipping_option"
  | "requires_payment"
  | "requires_revalidation"
  | "blocked"
  | "payment_authorized"
  | "order_submitted"
  | "completed"
  | "declined"
  | "cancelled"
  | "expired"
  | "failed";

The exact names are less important than the distinction they create.

A created state can accept early checkout setup.

An empty state means no checkout-relevant cart items are present yet.

A requires_address or requires_shipping_option state means buyer input is still missing.

A requires_revalidation state means some fact or mutation invalidated prior readiness.

A blocked state means the platform has blockers that prevent checkout from moving forward.

A requires_payment state means the checkout context is valid enough to request payment or payment authority.

A payment_authorized state means payment has cleared the authority/provider boundary but the order is not final yet.

An order_submitted state means the transition crossed into order creation.

These states do not describe screens. They describe what the platform believes it can safely do next.

Commands should drive transitions

A checkout transition model should not be mutated by arbitrary updates. It should accept commands.

Commands represent requested state changes:

type AgentCommerceCheckoutOperation =
  | "create"
  | "read"
  | "update"
  | "confirm"
  | "complete"
  | "cancel"
  | "expire";

Each command has preconditions.

Operation	Example preconditions
`create`	Actor may start checkout, cart context is known, and the operation has an idempotency boundary
`update`	Checkout is mutable, buyer input or cart data can be changed, and affected facts can be revalidated
`confirm`	Required address, shipping, policy, pricing, and buyer context are valid enough to request payment
`complete`	Payment authority and provider/payment state satisfy order rules, cart snapshot matches, and order creation is idempotent
`cancel`	Checkout is not terminal and cancellation is still allowed
`expire`	Checkout is stale or time-limited and should no longer accept mutation

A command result should report the transition outcome:

type CheckoutLifecycleOperationRequest = {
  operation: AgentCommerceCheckoutOperation;
  checkoutId: string;
  actorId: string;
  idempotencyKey: string;
  context: {
    region?: string;
    buyerType?: "consumer" | "business";
    channel: "storefront" | "agent" | "marketplace";
    currency?: string;
  };
  payload: unknown;
};

type EvidenceRef = {
  type: string;
  id: string;
  hash: string;
  hashAlgorithm: "sha256";
};

type CheckoutLifecycleOperationResult = {
  accepted: boolean;
  previousState: AgentCommerceCheckoutLifecycleState;
  nextState: AgentCommerceCheckoutLifecycleState;
  blockers: Array<{
    code: string;
    message: string;
    nextAction?: string;
  }>;
  evidenceRefs: EvidenceRef[];
  auditEventId: string;
};

This is different from returning only an HTTP success or failure.

The HTTP request may succeed because the platform processed the command. The checkout command may still be rejected because the transition was not valid.

That distinction is important for agents. A blocked transition is not an infrastructure error. It is a domain answer.

Eligibility, authority, and transition are separate decisions

A checkout transition should not collapse eligibility, authority, and state.

They answer different questions.

Eligibility asks:

Is this action valid for this product, cart, buyer, region, channel, and current facts?

Authority asks:

Is this actor allowed to request this action?

State transition asks:

Given the current checkout state, can this command move the checkout to a new state?

All three can fail independently.

A product may be eligible for checkout, but the checkout session may be expired.

An actor may have authority to request checkout preparation, but the cart may be blocked because policy coverage is incomplete.

A checkout may be prepared, but delegated payment authority may be missing.

A payment authority may be present, but the cart snapshot may no longer match.

A checkout explanation can be valid for one checkout state and stale after the state changes. It should stay tied to the decision and evidence references that produced it.

A useful execution path is:

Command received
      ↓
Current checkout state loaded
      ↓
Commercial facts selected
      ↓
Eligibility evaluated
      ↓
Authority evaluated
      ↓
Transition preconditions evaluated
      ↓
State transition applied or blocked
      ↓
Evidence and audit recorded

This is where the Part 1 model becomes operational.

Facts → Eligibility → Authority → State transition → Evidence → Audit

Checkout is the first article in the series where the full chain becomes unavoidable.

Cart mutation is not harmless

Cart mutation is sometimes treated as low risk because the buyer has not paid yet.

That assumption is weak in agent-facing commerce.

A cart can become the basis for checkout preparation, payment authority, price display, policy quotation, tax calculation, promotion eligibility, or audit records. Once a cart is used as input to delegated payment, it is no longer just a temporary UI convenience.

The platform needs to distinguish mutable carts from validated snapshots.

A simple cart state model might be:

type CartState =
  | "mutable"
  | "requires_revalidation"
  | "validated"
  | "locked_for_checkout"
  | "expired";

In mutable, items can be added or removed.

In requires_revalidation, a cart change or stale fact means prior readiness can no longer be trusted.

In validated, the platform has checked the relevant facts for the current context.

In locked_for_checkout, the cart snapshot is being used for checkout preparation or payment authority.

In expired, the cart can no longer support payment or order commitment without revalidation.

For the Travel Backpack:

update:
requires revalidation because inventory is stale

prepare_checkout:
blocked because inventory is stale and return-policy coverage is missing

The platform should not silently move from item addition to validated checkout state. The transition should be explicit.

Snapshots are the payment boundary

Checkout needs snapshots because mutable carts are not stable enough for payment authority or order commitment.

A cart ID identifies a container. It does not show that the cart contents, price, currency, shipping region, taxes, policies, or total remain the same.

For agent-ready commerce, this matters because delegated payment usually depends on the buyer authorizing a bounded action.

For example:

Buy one Travel Backpack for up to €150 in EUR from this merchant.

That authority should apply to a specific commercial snapshot, not to any future contents of the same cart ID.

The same rule applies to evidence. If a checkout explanation, policy quotation, or payment authority decision depends on a snapshot, the source reference or hash should travel with it. A later cart with the same cart ID is not automatically the same evidence.

A cart snapshot might include:

type CartSnapshot = {
  snapshotId: string;
  cartId: string;
  items: Array<{
    sku: string;
    quantity: number;
    priceAmount: number;
    currency: string;
  }>;
  context: {
    region?: string;
    buyerType?: "consumer" | "business";
    channel: "storefront" | "agent" | "marketplace";
  };
  totals: {
    subtotal: number;
    shipping?: number;
    tax?: number;
    total: number;
    currency: string;
  };
  factRefs: string[];
  policyFactRefs: string[];
  createdAt: string;
};

A payment authority should reference the snapshot it applies to:

type PaymentAuthorityRef = {
  authorityId: string;
  cartSnapshotId: string;
  maxAmount: number;
  currency: string;
  merchantId: string;
  expiresAt: string;
};

Before payment, the platform should check:

Does the current cart snapshot match the authorized snapshot?
Is the amount within scope?
Is the currency unchanged?
Is the merchant unchanged?
Has the authority expired?
Has the authority been revoked?

This prevents a serious failure mode: the buyer authorizes one commercial state and the platform charges for another.

A mutable cart is not a mandate. A snapshot fixes the exact items, totals, currency, and other checkout inputs that the later payment decision is allowed to use.

Checkout preparation should be an explicit transition

prepare_checkout should not mean “create a checkout URL if possible.”

It should mean:

Evaluate whether this cart can enter a checkout-prepared state for this buyer context.

That transition should require:

Product identity
Price freshness
Inventory freshness
Policy coverage
Shipping region
Buyer type
Channel
Generated-claim constraints
Tax and total calculation readiness
Cart snapshot integrity
Actor authority for preparation

For the Travel Backpack, prepare_checkout should be blocked:

Reasons:
- inventory is stale
- return-policy coverage is missing for Travel Bags

A structured result might look like this:

const prepareCheckoutResult = {
  requestedAction: "prepare_checkout",
  operation: "confirm",
  previousState: "requires_revalidation",
  nextState: "blocked",
  accepted: false,
  blockers: [
    {
      code: "stale_inventory",
      message: "Inventory must be revalidated before checkout can be prepared.",
      nextAction: "Revalidate inventory from the inventory source."
    },
    {
      code: "missing_return_policy",
      message:
        "Return-policy coverage is missing for the Travel Bags category.",
      nextAction:
        "Attach or approve return-policy coverage for Travel Bags."
    }
  ],
  evidenceRefs: [
    {
      type: "inventory_fact",
      id: "truth:BAG-TRAVEL-42:inventory",
      hash: "<sha256-hex>",
      hashAlgorithm: "sha256"
    },
    {
      type: "policy_fact",
      id: "policy:travel_bags:returns",
      hash: "<sha256-hex>",
      hashAlgorithm: "sha256"
    }
  ]
};

That response gives the agent a clear boundary. It gives operators actionable remediation. It gives audit a reason.

A boolean such as eligibleForCheckoutStart: false does not do that.

Payment should not be the first hard validation point

Some checkout systems perform their strictest validation late, near payment or order placement.

That is too late for agent-facing commerce.

Final validation still matters. The platform should always recheck critical facts before payment or order commitment. But obvious blockers should be detected earlier.

If return-policy coverage is missing, the platform should not wait until payment to fail.

If inventory is stale, the platform should not ask for delegated payment first and then discover the cart cannot be prepared.

If US shipping policy is unknown, the platform should not let the agent proceed through a US checkout path and fail at the end with a generic payment or fulfillment error.

Earlier transitions should fail earlier.

For the Travel Backpack, the explainable sequence is:

quote_policy:
blocked for returns

prepare_checkout:
blocked because inventory is stale and return-policy coverage is missing

delegate_payment:
blocked because checkout state is not valid for payment

A late failure such as:

payment_failed

does not explain the real domain issue.

A better checkout model preserves the real blocker:

checkout_authority_missing:
inventory stale
return-policy coverage missing

Agents need that distinction because the next action differs. A payment failure may suggest retrying payment. A policy blocker suggests operator remediation. An inventory blocker suggests revalidation.

Payment authority is a dependency, not a shortcut

Delegated payment depends on checkout state, but it should not be collapsed into checkout state.

A checkout can be prepared and still lack payment authority.

A payment authority can be present and still not match the cart snapshot.

A payment authority can be valid for one amount and invalid for another.

A payment authority can expire or be revoked before use.

Payment-related transitions may also have their own path inside the checkout lifecycle.

A simplified payment-related state path might look like this:

requires_payment
      ↓
requires_payment
      ↓
payment_authorized
      ↓
payment_authorized
      ↓
order_submitted

For delegated payment, the platform should verify:

checkout state is valid
cart snapshot matches
amount is within the mandate
currency matches
merchant matches
authority has not expired
authority has not been revoked
actor is allowed to use the authority
required confirmation has been satisfied

This should happen before payment is requested.

The adapter may carry AP2-related or other payment-protocol artifacts. Those artifacts are inputs to the decision. They are not permission by themselves.

The checkout path should therefore consume the same decision envelope used by feeds, tools, admin, and support:

envelope.eligibility
envelope.authority
envelope.checkout
envelope.payment
envelope.evidenceRefs
envelope.nextSafeActions

Internally, the same envelope pins the decision to its inputs, result, and freshness horizon. Checkout does not need to display all of that; it needs to obey it.

The rule is simple:

If eligibility is blocked, checkout mutation is blocked.
If checkout state is not valid for payment, payment authority cannot repair it.
If payment authority is blocked, payment dispatch is not attempted.

This continues the boundary from Part 5:

Protocol validity is not payment authority.
Payment authority is not checkout state validation.
A valid checkout state is not order commitment.

A transition model makes those boundaries visible. The decision envelope keeps the same boundaries visible to adapters and support surfaces.

For checkout and delegated payment, canonical evidence references should carry explicit SHA-256 hashes of the captured artifact or canonical snapshot. Freshness dependencies separately identify the product, policy, checkout, mandate, payment, or generated-claim inputs whose change or expiry can invalidate the decision. That keeps a checkout response from looking current after one of those dependencies has changed without pretending that every dependency is itself a replayable evidence artifact.

Expiry is part of correctness

Checkout state should expire.

Prices can change. Inventory can change. Shipping availability can change. Policy coverage can change. Payment mandates can expire. Generated claims may be revoked. A cart snapshot may become too old to support payment or order commitment.

Expiry should be part of the checkout model, not a hidden timestamp checked inconsistently across handlers.

type CheckoutSession = {
  checkoutId: string;
  state: AgentCommerceCheckoutLifecycleState;
  cartSnapshotId: string;
  preparedAt?: string;
  expiresAt?: string;
  blockers: string[];
};

If a session expires, later commands should not treat it as current.

For example:

complete on expired checkout:
blocked

Reason:
Checkout session expired. Revalidation is required before checkout can be completed.

This is especially important for agent workflows because interactions may be asynchronous. An agent may prepare checkout, wait for buyer confirmation, then return after the snapshot is no longer valid.

The platform should not rely on the agent to remember expiry. It should enforce expiry at the state boundary.

Retries are part of the design

Agent-facing systems must assume retries.

A tool call may be repeated. A network response may be lost. A checkout preparation request may time out after the checkout session is created. A payment attempt may return an ambiguous result. An agent may call the same operation again after receiving no response.

Retry behavior should be designed, not discovered in production.

Each state-changing command should carry an idempotency key:

type CheckoutLifecycleOperationEnvelope = {
  commandId: string;
  idempotencyKey: string;
  operation: AgentCommerceCheckoutOperation;
  checkoutId: string;
  requestedAt: string;
};

If the same command is retried, the platform should return the same result when appropriate instead of creating a duplicate transition.

Example:

First request:
create returns checkout session chk_123.

Network response:
lost.

Retry with same idempotency key:
returns checkout session chk_123, not a second checkout session.

Idempotency belongs where the state transition occurs.

A protocol adapter can pass the key. The checkout service must enforce it.

If idempotency exists only in the adapter, duplicate transitions can still happen through another adapter, feed-triggered workflow, admin action, or retry path.

One command should also have one authoritative replay owner. That owner remembers whether the command has already run and which response belongs to it.

If the business mutation commits but the canonical checkout state or event write fails, the platform should keep a command fence bound to the exact response hash and require reconciliation. It must not discard ownership and replay the mutation as a new command. Reconciliation may clear the fence only after authoritative checkout state proves that it contains the same committed result.

Concurrency cannot be ignored

Checkout is also vulnerable to concurrent changes.

A buyer may modify the cart while an agent prepares checkout. Inventory may be revalidated while a payment authority is being attached. A promotion may expire while shipping is recalculated. An operator may update a policy while an agent is quoting terms.

A transition model does not eliminate concurrency problems, but it gives the platform a place to handle them.

Useful techniques include:

Cart snapshot identifiers
Optimistic concurrency checks
State transition guards
Command fencing and ownership renewal
Idempotency keys
Expiry timestamps
Final validation before payment or order commitment

For example, complete should fail if the cart snapshot used by the payment authority is not the current checkout snapshot.

complete:
blocked

Reason:
Cart snapshot changed after payment authority was granted.

This is not a generic technical conflict. It is a commercial safety rule.

The buyer authorized one thing. The cart now represents something else. The platform must not proceed silently.

State transitions need evidence

A checkout transition should record the evidence used to allow or block it.

For an allowed transition, evidence explains what the platform relied on.

For a blocked transition, evidence explains why the platform refused.

A requires_payment transition may reference:

price fact
inventory validation
policy coverage facts
shipping calculation
tax calculation
cart snapshot
eligibility decision
authority decision

A blocked prepare_checkout transition for the Travel Backpack may reference:

inventory stale fact
missing return-policy coverage
current cart snapshot
buyer context
eligibility decision

The checkout can keep one current record and append one meaningful event for an accepted or blocked command:

type CheckoutEvent = {
  eventId: string;
  checkoutId: string;
  operation: AgentCommerceCheckoutOperation;
  previousState: AgentCommerceCheckoutLifecycleState;
  nextState: AgentCommerceCheckoutLifecycleState;
  accepted: boolean;
  actorId: string;
  idempotencyKey: string;
  evidenceRefs: Array<{ type: string; id: string; hash: string; hashAlgorithm: "sha256" }>;
  reasonCodes: string[];
  occurredAt: string;
};

The current checkout record remains authoritative for present state. The event history preserves meaningful lifecycle changes, blocked commands, idempotency outcomes, and the evidence needed for agent responses, operator remediation, replay analysis, and customer support. Internal validations that do not change behavior do not need separate persistent records.

When checkout is blocked, the platform should not have to reconstruct the reason from logs. The event that owns the blocked command should already contain the reason.

Audit should record the decision path

An audit log that says “checkout failed” is not enough.

For agent-ready checkout, audit should capture the decision path:

Who or what requested the command
Which protocol or channel was used
Which cart snapshot was evaluated
Which product facts were used
Which policy facts were used
Which eligibility decision was produced
Which authority decision was produced
Which state transition was attempted
Whether the transition was accepted or blocked
Which blockers were returned
Which idempotency key was used
Which evidence records were attached

This allows the platform to answer questions such as:

Why did the agent say checkout could not proceed?
Was inventory stale?
Was a return policy missing?
Did the buyer authorize payment?
Did the cart change after authorization?
Did a retry create a duplicate operation?
Which adapter initiated the request?
Which event produced the final state?

Audit is not a logging afterthought. It is part of the safety model.

The Part 1 chain ends with audit because agent-facing actions need explainable history.

Blocked transitions should generate operator work

A blocked checkout transition should create or update operator tasks when the blocker is actionable.

For the Travel Backpack:

prepare_checkout:
blocked

Blockers:
- stale_inventory
- missing_return_policy

The platform can produce tasks:

Task 1:
Revalidate inventory for BAG-TRAVEL-42.

Impact:
Agents can discover and compare the product, but checkout preparation is blocked.

Task 2:
Attach or approve return-policy coverage for Travel Bags.

Impact:
Agents cannot quote return terms and checkout preparation is blocked if complete policy coverage is required.

This is better than leaving errors inside checkout logs.

Operator tasks connect runtime blockers to remediation. That matters because agent-readiness is partly operational. Products become blocked, stale, partially ready, or checkout-ready based on fixable commercial data.

The checkout transition model becomes one source of evidence for that operational layer.

Protocol adapters should not perform hidden transitions

Part 5 argued that adapters should translate domain decisions rather than own them. Checkout is where that boundary becomes critical.

A protocol adapter should not create a checkout session directly because an external request asked for one.

Bad boundary:

async function adapterHandler(req: ProtocolRequest) {
  const cart = await carts.get(req.cartId);
  const session = await payments.createCheckoutSession(cart);

  await carts.markCheckoutStarted(cart.id);

  return project(session);
}

This lets the adapter perform hidden transitions.

Better boundary:

async function adapterHandler(req: ProtocolRequest) {
  const operation = mapToCheckoutOperation(req);
  const result = await checkout.handleOperation(operation);

  return projectCheckoutOperationResult(result);
}

The adapter still has important work. It validates protocol shape, normalizes context, passes idempotency metadata, and projects the response.

But the checkout domain owns the mutation.

That prevents ACP, UCP, MCP, AP2-related flows, internal feeds, and future adapters from creating different checkout paths.

The transition model should coordinate, not replace domains

A checkout state model can also be overbuilt.

It should not become the place where every commerce rule is implemented directly.

A useful boundary is:

Commercial truth:
Provides selected source-backed product facts.

Policy facts:
Provide applicability and quotability.

Eligibility:
Decides whether actions are valid.

Delegated authority:
Decides whether the actor may request the action and whether mandate scope is satisfied.

Checkout application owner:
Coordinates the same checkout behavior for human and agent channels and controls current state plus meaningful events.

Payment:
Handles payment execution and provider interaction.

Transaction correlation:
Connects checkout, mandate, payment, and order events without becoming a second copy of their state.

The checkout application owner coordinates these decisions at the mutation boundary. It should not duplicate all of them internally.

If checkout reimplements eligibility differently from the feed, policy quotation, or admin readiness views, the platform reintroduces the semantic drift discussed in Part 5.

The checkout path should consume shared domain decisions and then decide whether a transition can occur from the current state.

State names should reflect business meaning

A checkout transition model should use state names that describe commercial meaning, not UI steps or handler names.

Weak state names:

step_1
step_2
payment_screen
submit_clicked
handler_complete

These describe implementation flow. They are not useful for agents, operators, or audit.

Better state names:

created
requires_address
requires_shipping_option
requires_revalidation
blocked
requires_payment
payment_authorized
order_submitted
completed
expired
cancelled
failed

These names communicate what the platform believes about the checkout.

A useful test is whether an operator or support engineer can understand the state without reading the UI code.

If the state name only makes sense as a page in a checkout form, it is probably not the right state for agent-ready commerce.

Not every validation deserves a persistent state

There is also a risk of over-modeling.

A platform should not create a persistent state for every internal check.

For example:

checking_price
checking_inventory
checking_policy
checking_tax
checking_shipping
checking_authority

These may be internal steps inside a transition, not durable states.

A practical rule:

Make it a state when different commands are allowed, blocked, required, retried, expired, or audited differently.
Keep it as transition logic when it is only an internal validation step.

For example, requires_revalidation is useful because it changes what can happen next. checking_policy may not be useful unless the system genuinely waits for asynchronous policy review.

Good state-machine design is not about maximizing the number of states. It is about naming the boundaries that affect behavior.

Where this model can go wrong

Explicit checkout state improves safety, but it introduces its own failure modes.

The transition model mirrors the UI

If states are based on screens, the model becomes fragile. Agent-facing checkout may not use the same screens as a human storefront. Protocol flows may skip visual steps entirely.

State should represent commercial readiness, not UI layout.

Too few states

A model with only active, submitted, and complete hides important differences.

A cart requiring revalidation is not the same as a checkout session waiting for payment authority. A blocked checkout is not the same as an expired checkout. A prepared checkout is not the same as a committed order.

Too few states recreate the original problem.

Too many states

A transition model with too many states becomes difficult to reason about. Engineers may not know which transitions are valid. Operators may not understand what the state means.

Persistent states should represent meaningful business boundaries, not every validation sub-step.

Hidden transitions inside adapters

If protocol adapters mutate checkout state directly, the transition model is bypassed. Different adapters may create different checkout paths.

All state changes should go through the checkout command boundary.

Eligibility is duplicated inside checkout

Checkout should consume eligibility decisions, not reimplement separate rules that contradict feeds, policy quotation, or admin surfaces.

Some final validation belongs in checkout, but the decision model should remain consistent.

Authority is treated as checkout state

Payment authority should not be reduced to checkout.authorized = true.

Authority has scope, expiry, revocation, amount limits, currency, merchant binding, actor identity, and confirmation requirements. Checkout can reference authority decisions. It should not oversimplify them.

Cart snapshots are not locked

If payment authority references a mutable cart, the buyer may authorize one thing and the platform may charge for another.

Snapshot identity should be explicit.

Retry behavior is unclear

If retries are not idempotent, duplicate checkout sessions, payment attempts, or order commits can occur.

Idempotency should be enforced at the state-transition boundary.

Expiry is implicit

If checkout expiry is hidden in timestamps or external payment sessions, the platform may accept stale transitions.

Expiry should be part of checkout state behavior.

Audit records only success

Blocked transitions are as important as successful transitions. They explain why agents could not proceed and what operators need to fix.

Audit should record attempted commands, decisions, blockers, evidence, and state transitions.

Practical tests for checkout state

Checkout state should be tested with scenario flows, with endpoint status assertions used to keep the result precise.

An endpoint assertion can show that a request returned 200, 409, or 422. A scenario test shows whether the right boundary made the decision, whether the state transition was valid, whether the same command is idempotent, and whether the decision path explains the result.

A useful scenario set includes:

Scenario	Expected result
Add item to draft cart when inventory is stale	Cart enters `requires_revalidation`
Prepare checkout with fresh price but stale inventory	Checkout preparation blocked or requires revalidation
Prepare checkout when required return-policy coverage is missing	Checkout preparation blocked
Revalidate inventory while required policy coverage remains missing	Checkout remains blocked for policy coverage
EU buyer, fresh inventory, complete policy coverage	Checkout can move to `requires_payment`
US buyer when US shipping policy is unknown	US checkout blocked or requires review
Delegated payment requested without authority	State moves to or remains `requires_payment`
Delegated payment authority present but cart snapshot changed	Payment request blocked
Retry `create` with the same idempotency key	Same result returned; no duplicate checkout session
Retry `complete` after an ambiguous response	Existing order result returned if already committed
Business mutation commits but canonical checkout persistence fails	Command remains reconciliation-required; retry does not repeat the mutation
Authoritative checkout state later contains the exact committed response hash	Reconciliation clears the command fence
Stale worker loses command-fence ownership before completion	Canonical completion is rejected
Checkout session expired before completion	Completion blocked; revalidation required

A simplified expectation type:

type CheckoutScenarioExpectation = {
  initialState: AgentCommerceCheckoutLifecycleState;
  operation: AgentCommerceCheckoutOperation;
  expectedAccepted: boolean;
  expectedNextState: AgentCommerceCheckoutLifecycleState;
  expectedBlockerCodes: string[];
  expectedMeaningfulEvent: boolean;
  expectedIdempotencyBehavior:
    | "new_event"
    | "same_result_returned"
    | "duplicate_rejected"
    | "existing_order_returned";
};

The value of these tests is not only correctness. It is preserving the meaning of the checkout lifecycle.

When a scenario fails, the team can see which boundary was violated: facts, eligibility, authority, transition, decision envelope, audit, or idempotency.

A practical implementation path

A platform does not need a large workflow engine to improve checkout safety.

A practical path is:

Name the mutation boundaries.
Start with created, empty, requires_address, requires_shipping_option, requires_payment, requires_revalidation, blocked, payment_authorized, order_submitted, completed, declined, cancelled, expired, and failed.
Move mutations behind lifecycle operations.
Use operations such as create, update, confirm, complete, cancel, and expire, then map protocol-specific commands onto those operations.
Define transition preconditions.
For each command, define required current state, eligibility checks, authority checks, and required facts.
Introduce cart snapshots.
Payment authority and checkout preparation should reference stable cart snapshots, not only mutable cart IDs.
Enforce idempotency at the transition boundary.
Adapters may pass idempotency keys, but the checkout service should enforce safe retry behavior.
Record one meaningful checkout event.
Allowed and blocked commands should append a meaningful event carrying the facts, policy coverage, eligibility and authority decisions, blockers, idempotency outcome, and evidence references needed to explain the transition.
Keep adapters outside mutation logic.
Adapters should map protocol requests to checkout commands and project results. They should not perform hidden transitions.
Generate operator tasks from blockers.
Missing policy, stale inventory, unsupported region, expired authority, and generated-claim review should produce actionable remediation when appropriate.
Test scenario flows.
Test state, command, facts, authority, expected transition, blockers, idempotency, and audit together.

This path moves checkout away from loosely coupled request handlers and toward a domain model that can support agent-facing actions.

The tradeoff

A checkout transition model adds structure.

It requires named states, commands, transition rules, idempotency handling, snapshots, hash-pinned evidence references, meaningful checkout events, and scenario tests.

For a simple storefront with low-risk products and no agent-facing checkout or delegated payment, this may be unnecessary. A conventional checkout flow may be sufficient.

Agent-ready commerce changes the threshold.

Once agents can prepare checkout, operate across protocols, retry tool calls, act under buyer authority, or approach payment delegation, checkout becomes a mutation boundary that must be explicit.

The tradeoff is between implementation convenience and mutation safety.

Request handlers are faster to write.

State transitions are easier to reason about, test, retry, audit, and integrate across protocols.

The goal is not to make checkout complicated. The goal is to stop hiding commercial mutations inside endpoints that cannot explain what happened.

The practical takeaway

Checkout is not only a form.

For agent-ready commerce, checkout is where commercial truth, policy coverage, action eligibility, actor authority, cart mutation, payment boundaries, evidence, and audit converge.

That convergence needs explicit state.

The Travel Backpack example shows why.

The product is active and in stock at the catalog level. It can be discovered. It can be compared. But inventory is stale, return-policy coverage is missing for Travel Bags, US shipping is unknown, and the generated description is pending review. The platform should not prepare checkout or allow delegated payment just because a protocol request asks for it.

A state-machine model makes the boundary explicit:

Cart mutation requires validation.
Checkout preparation requires fresh facts and policy coverage.
Delegated payment requires valid checkout state and payment authority.
Retries require idempotency.
Payment requires a stable cart snapshot.
Blocked transitions require evidence.
Audit records the decision path.

This keeps checkout aligned with the broader architecture model:

Facts → Eligibility → Authority → State transition → Evidence → Audit

Next in the series

Part 7 will move from checkout state to payment authority:

Agent-Ready Commerce, Part 7: Delegated Payment Needs More Than a Token

That article will examine why payment delegation requires mandate scope, cart snapshot integrity, amount limits, merchant binding, expiry, revocation, confirmation rules, evidence, and audit rather than treating a payment artifact as permission to charge.

About the author

Written by Dimitrios S. Sfyris, Founder & Software Architect at AspectSoft.

AspectSoft designs and develops custom software platforms, e-commerce systems, SaaS infrastructure, integrations, analytics tools, and practical digital products.

You can also follow the AspectSoft LinkedIn page for updates on software platforms, commerce systems, AI tooling, and developer-focused products.

Agent-Ready Commerce, Part 5: Keeping ACP, UCP, MCP, and AP2 Adapters Thin

Dimitrios S. Sfyris — Mon, 29 Jun 2026 06:58:44 +0000

Protocol adapters are one of the easiest places for agent-commerce architecture to drift.

An adapter begins with one responsibility: translate an external request into the platform's internal language. An MCP-style tool may ask for return terms. An ACP- or UCP-style interaction may ask whether checkout can be prepared. An AP2-related flow may carry payment-authority information. An internal feed may publish product capabilities.

Those are adapter concerns at the boundary.

The problem starts when the adapter does more than translate. It checks product availability from catalog fields. It interprets policy text. It decides whether checkout is ready. It treats a payment artifact as authority. It turns a domain blocker into a softer protocol response.

Each shortcut may solve an integration problem locally, but it also creates a second place where commercial meaning is decided.

When several adapters exist, those local decisions begin to diverge. The MCP tool may block return-policy quotation, an ACP or UCP adapter may expose the product as purchasable, the feed may publish it as checkout-ready, and the AP2-related flow may reject delegated payment.

At that point, the platform does not only have multiple integrations. It has multiple interpretations of the same commercial state.

This is the adapter problem in agent-ready commerce: semantic drift at the protocol boundary.

The adapter should know how to speak the protocol. It should not decide product truth, policy meaning, eligibility, checkout validation, checkout state, or payment authority. Those decisions belong inside the commerce platform, where they can be shared, evaluated, traced, and reused.

Series context

This is the fifth article in the Agent-Ready Commerce series.

Part 1 introduced the broader architecture model:

Facts → Eligibility → Authority → State transition → Evidence → Audit

Part 4 focused on policy structure. It argued that agents should not interpret free-text policy pages as executable rules. Returns, shipping, warranty, cancellation, regional restrictions, and business-buyer rules need structured policy facts with applicability, evidence, lifecycle, conflicts, and quotability.

This article focuses on protocol adapters.

The central argument is that ACP, UCP, MCP, AP2-related flows, internal feeds, marketplace APIs, and future agent-facing interfaces should not become separate commerce engines. They should translate external protocol language into canonical platform intent, call the same domain decision layer, and project the result back into protocol-specific shape.

In this article series, projection means response shaping at a protocol boundary. Later, generated-claim projection uses the same idea more strictly: the platform does not only shape a response, it decides whether a piece of language may be said at all.

The names of the protocols are less important than the boundary they create. Whether the surface is a tool interface, an agent-commerce protocol, a payment protocol, a marketplace API, or an internal feed, the same design rule applies:

The adapter may translate the decision.
It must not become the source of the decision.

The failure mode: semantic drift

Semantic drift happens when two parts of the system use the same words but no longer mean the same thing.

In a traditional commerce platform, this already happens with terms like active, available, in_stock, or sellable. One service interprets available as “visible on the storefront.” Another interprets it as “can be added to cart.” Another interprets it as “can be paid for.” The result is inconsistent behavior.

Agent-facing protocols make this risk more explicit because they introduce more external vocabularies.

One protocol may ask:

Can this product be purchased?

Another may ask:

Can checkout be prepared?

A tool interface may ask:

Return the return policy for this product.

A payment protocol may ask:

Can this agent request delegated payment for this cart?

A feed may publish:

checkoutEligible: true

Those requests may sound related, but they are not identical. If each adapter decides what the request means on its own, the platform accumulates slightly different interpretations of the same commercial reality.

For agent-ready commerce, that is the core adapter risk.

The adapter becomes a place where protocol vocabulary is translated directly into local business rules:

// Bad: the adapter invents purchase readiness.
function canPurchaseFromProtocolRequest(product: Product) {
  return product.active && product.inventoryStatus === "in_stock";
}

That code may be understandable inside one adapter. It is also incomplete. It ignores policy coverage, fact freshness, generated-claim review, regional restrictions, buyer type, checkout state, payment authority, and other decision inputs discussed in Parts 2–4.

Worse, another adapter may implement a different shortcut:

// Also bad: a second adapter creates a different meaning.
function canPrepareCheckoutForTool(product: Product) {
  return product.active && product.price.amount > 0;
}

Now the platform has two meanings for a checkout-related action. Neither may match the domain.

This is how semantic drift enters the system.

Thin adapters are about authority, not code size

The phrase “thin adapter” can be misleading.

A thin adapter is not necessarily a small file. It may parse the protocol, validate schemas, map errors, propagate idempotency, emit telemetry, extract authentication context, paginate results, shape responses, and handle compatibility mapping. “Thin” means that it does not decide commercial truth, eligibility, authority, checkout validity, or payment permission.

That is real work.

Thinness is not measured by line count. It is measured by authority.

A thin adapter does not own commercial meaning.

It does not decide whether a product fact is reliable. It does not interpret return policy text. It does not decide whether a policy claim is quotable. It does not determine whether checkout can advance. It does not infer payment authority from a protocol artifact. It does not turn a blocked domain decision into a softer answer because the protocol expects helpful output.

A thin adapter is allowed to know the protocol. It is not allowed to become the platform’s second commerce brain.

A better definition is:

A thin adapter owns protocol translation.
The domain owns commercial decisions.

That distinction allows the adapter to be substantial without making it dangerous.

The running example

Continue with the Travel Backpack example from Parts 2, 3, and 4:

Product: Travel Backpack
SKU: BAG-TRAVEL-42
Price: €129
Catalog status: active
Inventory status: in_stock
Category: Travel Bags

The commercial truth layer currently says:

Price: fresh
Inventory: stale
Return policy: missing for Travel Bags
Warranty policy: known
Shipping policy: known for EU, unknown for US
Generated description: pending review
Feed publication: last published yesterday

From Part 3, the action matrix was:

Action	Result
`discover`	allowed
`compare`	allowed
`quote_policy`	blocked
`add_to_cart`	requires_revalidation
`prepare_checkout`	blocked
`delegate_payment`	blocked

Part 4 added detail to the policy side:

Warranty policy: known and potentially quotable
EU shipping: known and potentially quotable
US shipping: unknown
Return policy for Travel Bags: missing

Now imagine five different external surfaces:

Internal agent product feed
MCP-style tool endpoint
ACP-style commerce interaction
AP2-style payment-related flow
Admin UI for operator remediation

Each surface may need a different response shape. That is normal.

The feed may need compact capability flags. The tool endpoint may need a structured answer for policy quotation. The commerce interaction may need a checkout-preparation response. The payment flow may need to know whether delegated payment can proceed. The admin UI may need blockers and remediation tasks.

The response shape can differ.

The underlying domain decision should not.

For the Travel Backpack, every surface should converge on the same commercial facts:

The product can be discovered.
The product can be compared on known facts.
Return-policy quotation is blocked.
US shipping quotation is blocked.
Checkout preparation is blocked.
Delegated payment is blocked.

If the product feed says checkout is available, the tool endpoint says return terms are unavailable, and the payment flow blocks delegated payment, the platform needs to explain why. If it cannot, the adapters are probably making decisions independently.

The adapter boundary

A useful adapter boundary has five steps:

External protocol request
      ↓
Protocol adapter
      ↓
Canonical intent
      ↓
Domain decision
      ↓
Protocol projection

Each step has a different responsibility.

The external protocol request is shaped by the protocol. It may contain protocol-specific fields, message envelopes, tool arguments, payment artifacts, request identifiers, actor claims, or conversation context.

The protocol adapter understands that external shape and maps it into the platform’s internal vocabulary.

The canonical intent describes what the caller is asking the commerce platform to evaluate or perform.

The domain decision evaluates commercial truth, policy facts, eligibility, authority, checkout state, and evidence.

The protocol projection converts the domain decision back into the external response format.

This is the spine of the article.

If the adapter skips canonical intent and calls random services directly, the protocol starts shaping the domain.

If the adapter creates the decision itself, the platform develops parallel business logic.

If the adapter hides the domain decision during projection, the external surface becomes difficult to debug and audit.

Canonical intent is the missing layer

A protocol action is not automatically a domain action. Protocol actions are external language. Canonical intent is the shared internal description of what the caller wants, independent of the protocol used to ask for it.

For example, one protocol may expose a tool called:

get_return_terms

Another may expose:

describe_policy

A third may ask for:

product.purchase_constraints

The platform should not implement three separate policy interpreters. It should map those requests into canonical intent:

quote_policy

A simple internal action vocabulary might look like this:

type AgentCommerceDecisionAction =
  | "discover"
  | "compare"
  | "quote_policy"
  | "add_to_cart"
  | "prepare_checkout"
  | "delegate_payment"
  | "complete_checkout"
  | "show_generated_claim"
  | "explain";

The adapter can map protocol-specific actions to these internal actions:

type ProtocolName =
  | "internal_feed"
  | "mcp"
  | "acp"
  | "ucp"
  | "ap2"
  | "marketplace_api"
  | "admin";

type ProtocolActionMapping = {
  protocol: ProtocolName;
  externalAction: string;
  internalAction: AgentCommerceDecisionAction;
};

const mappings: ProtocolActionMapping[] = [
  {
    protocol: "internal_feed",
    externalAction: "publish_product",
    internalAction: "discover"
  },
  {
    protocol: "mcp",
    externalAction: "get_return_terms",
    internalAction: "quote_policy"
  },
  {
    protocol: "acp",
    externalAction: "prepare_purchase",
    internalAction: "prepare_checkout"
  },
  {
    protocol: "ucp",
    externalAction: "create_checkout",
    internalAction: "prepare_checkout"
  },
  {
    protocol: "ap2",
    externalAction: "request_delegated_payment",
    internalAction: "delegate_payment"
  }
];

This mapping does not solve the whole problem, but it prevents an important failure mode. The protocol’s vocabulary does not become the platform’s business model by accident.

Canonical intent needs context

An action name alone is not enough.

The platform needs context to evaluate the action correctly.

For the Travel Backpack, quote_policy depends on policy domain, region, buyer type, and channel. EU shipping may be quotable. US shipping is unknown. Consumer terms may differ from business-buyer terms. Agent-channel quotation may be stricter than a human-readable storefront link.

A canonical request should therefore carry normalized context:

type BuyerType = "consumer" | "business";
type Channel = "storefront" | "agent" | "marketplace" | "support";

type ActorContext = {
  actorId: string;
  actorType: "human" | "agent" | "system";
  buyerId?: string;
  buyerType?: BuyerType;
  authorityRef?: string;
};

type CommerceIntent = {
  requestedAction: AgentCommerceDecisionAction;
  productId?: string;
  sku?: string;
  cartId?: string;
  policyDomain?: "returns" | "shipping" | "warranty" | "cancellation";
  context: {
    region?: string;
    currency?: string;
    buyerType?: BuyerType;
    channel: Channel;
  };
  actor: ActorContext;
  idempotencyKey?: string;
  correlationId?: string;
  requestedAt: string;
};

The adapter’s job is to build this object from protocol-specific input. The domain’s job is to evaluate it.

This is an important boundary. The adapter may normalize country = DE into region = EU if that mapping is part of platform infrastructure. It may extract actor identity. It may pass an authority reference. It may include an idempotency key. But it should not decide that the product is checkout-ready because the request contains a supported country and a valid-looking cart.

Context is input. It is not a decision.

A request or context hash proves only which input was evaluated. It does not prove that the relevant owner evaluated that input and returned allowed. The owner decision must be explicit, include its evidence and blockers, and be bound to the exact action, subject, scope, and freshness window.

Projection is not decision-making

After the domain evaluates an intent, the adapter has to return a protocol-specific response.

That response may look different for each protocol.

One protocol may need an error code. Another may need a tool result. Another may need a list of supported actions. Another may need a payment-related refusal. Another may need a feed item.

That is projection.

Projection is allowed.

Decision-making is not.

A canonical domain decision might look like this:

type AgentCommerceDecisionEnvelopeAuthenticator =
  | {
      kind: "digital_signature";
      algorithm: "ed25519";
      format: "detached";
      keyId: string;
      verificationKeyRef: string;
      protectedHash: string;
      value: string;
      verifiable: true;
    }
  | {
      kind: "message_authentication_code";
      algorithm: "hmac-sha256";
      format: "detached";
      keyId: string;
      verificationKeyRef: string;
      protectedHash: string;
      value: string;
      verifiable: true;
    }
  | {
      kind: "unsigned";
      algorithm: "none";
      format: "none";
      protectedHash: string;
      verifiable: false;
      warning: "missing_platform_signing_key";
    };

type AgentCommerceDecisionProjection = {
  envelopeSchemaVersion: "agent-commerce-decision-envelope-schema-v4";
  ruleSetRef: string;
  ruleSetHash: string;
  authenticator: AgentCommerceDecisionEnvelopeAuthenticator;
  decisionHash: string;
  inputDependencyHash: string;
  resultHash: string;
  requestedAction: AgentCommerceDecisionAction;
  allowed: boolean;
  status:
    | "allowed"
    | "blocked"
    | "requires_review"
    | "requires_revalidation"
    | "requires_confirmation";
  reasonCodes: readonly string[];
  freshness?: {
    evaluatedAt: string;
    validUntil: string | null;
    staleAfter: string | null;
    reasonCodes: readonly string[];
    dependencyCount: number;
    dependencyKinds: readonly string[];
  };
  nextSafeActions: readonly {
    action: string;
    owner: "system" | "operator" | "buyer" | "merchant";
    reasonCode: string;
  }[];
};

The canonical envelope carries the full subject, actor, freshness, basis, eligibility, authority, checkout, payment, generated-claim, evidence, rule-set, hash, authenticator, and declared-surface state. A surface projection may expose only the fields it needs, but it should preserve the canonical hashes, rule-set identity, authenticator, status, reasons, freshness, and next safe actions instead of rebuilding them. The trusted boundary verifies the envelope's declared surface before producing that projection.

Before an envelope crosses an external boundary, the projection path should capture externally supplied or persisted input once into a detached, deeply frozen, JSON-compatible snapshot. Hash recomputation, reason/component reconciliation, authenticator verification, trusted-key validation, surface binding, live-request binding, freshness evaluation, and projection should all consume that same captured value. Action-bearing external surfaces must reject stale allowed output. Administrative and support projections may expose stale context for diagnosis, but they do not authorize execution. A blocked envelope may still be projected as a refusal so the recipient receives its reason codes and next safe actions.

Independently verifiable output should require Ed25519. HMAC belongs only inside an explicitly configured shared-secret trust domain, and unsigned output should remain local-development only. Before changing state, the platform should compare the decision's protected dependency hashes with current authoritative snapshots. A missing, changed, or expired dependency requires a fresh decision even when the envelope remains signed and inside its original freshness window.

For the Travel Backpack, a return-policy quotation decision might be:

const decision: AgentCommerceDecisionProjection = {
  envelopeSchemaVersion: "agent-commerce-decision-envelope-schema-v4",
  ruleSetRef: "ruleset:sha256:<sha256-hex>",
  ruleSetHash: "<sha256-hex>",
  authenticator: {
    kind: "digital_signature",
    algorithm: "ed25519",
    format: "detached",
    keyId: "platform-key:decision-envelope",
    verificationKeyRef: "public-key:decision-envelope",
    protectedHash: "<sha256-hex>",
    value: "<base64url-signature>",
    verifiable: true
  },
  decisionHash: "<sha256-hex>",
  inputDependencyHash: "<sha256-hex>",
  resultHash: "<sha256-hex>",
  requestedAction: "quote_policy",
  allowed: false,
  status: "blocked",
  reasonCodes: ["missing_return_policy"],
  freshness: {
    evaluatedAt: "2026-07-06T10:12:00.000Z",
    validUntil: null,
    staleAfter: null,
    reasonCodes: [],
    dependencyCount: 1,
    dependencyKinds: ["policy"]
  },
  nextSafeActions: [
    {
      action: "attach_return_policy_fact",
      owner: "operator",
      reasonCode: "missing_return_policy"
    }
  ]
};

The MCP-style tool adapter may project that into a tool result. An ACP- or UCP-style adapter may project it into a commerce response. An internal feed may project it into quotePolicy: "blocked". An admin UI may project it into a remediation task.

Those projections may differ.

The domain decision should remain the same.

Thin projection has one job it cannot bend. It preserves scope. If a generated policy claim is safe for feed discovery, the adapter should not reuse it as checkout or support language. It should use the value returned for that surface, not reach back into the raw claim and reuse the language.

Capability is not permission

Agent-facing protocols often need some form of capability discovery. A caller may ask what operations the platform supports.

This creates another common source of drift.

There are at least three different concepts that are often collapsed into one field:

Protocol capability:
Can this interface express the operation?

Platform capability:
Does the platform support the operation at all?

Contextual readiness:
Is the operation currently valid for this product, buyer, region, channel, and actor?

These are not the same.

A platform may support delegated payment in general, but not for the current cart. A protocol may support policy quotation, but the product may not have quotable return terms. A feed may support checkout eligibility flags, but this product may be blocked because inventory is stale.

A bad adapter exposes global support as contextual readiness:

// Bad: global capability is treated as product action status.
const response = {
  canQuotePolicy: true,
  canPrepareCheckout: true,
  canDelegatePayment: true
};

A better model separates the layers:

type ProtocolCapability = {
  requestedAction: AgentCommerceDecisionAction;
  expressibleByProtocol: boolean;
};

type PlatformCapability = {
  requestedAction: AgentCommerceDecisionAction;
  supportedByPlatform: boolean;
};

type ContextualReadiness = {
  requestedAction: AgentCommerceDecisionAction;
  result: DecisionResult;
  blockers: DecisionBlocker[];
};

For the Travel Backpack:

Protocol can express checkout preparation.
The platform supports checkout preparation.
This product and context are not checkout-ready.

That distinction is essential.

If a protocol adapter exposes only canPrepareCheckout: true, the external agent may interpret it as readiness. If it exposes the contextual decision, the agent can behave correctly.

A bad adapter hides the actual failure

Consider this simplified adapter implementation:

async function preparePurchaseAdapter(request: ProtocolRequest) {
  const product = await catalog.getProduct(request.sku);

  if (!product.active || product.inventoryStatus === "out_of_stock") {
    return {
      status: "blocked",
      reason: "not_available"
    };
  }

  return {
    status: "ok",
    checkoutUrl: await checkout.createSession(product.id)
  };
}

This looks practical, but it has several problems.

It reads catalog state directly instead of commercial truth. It treats stock status as checkout readiness. It does not evaluate policy coverage. It does not check whether generated claims are approved. It does not consider buyer region, buyer type, or channel. It does not check authority. It mutates checkout state directly from the adapter. It reduces all blockers to not_available.

A better adapter does less commercial work:

async function preparePurchaseAdapter(request: ProtocolRequest) {
  const intent = mapProtocolRequestToIntent(request);

  const decision = await commerce.evaluateIntent(intent);

  return projectDecisionToProtocolResponse(decision);
}

That code is shorter, but the point is not shortness. The point is that the adapter no longer owns checkout validation.

The domain can now evaluate the same intent consistently across protocols.

A better domain path

For a state-changing operation such as checkout preparation, the domain path should be explicit and ergonomic:

Protocol request
      ↓
Adapter maps request to canonical intent
      ↓
Existing product, policy, checkout, payment, and authority decisions are loaded or evaluated
      ↓
Decision spine returns one envelope
      ↓
Adapter projects the envelope to protocol shape

The adapter should not need to know how stale inventory, missing policy coverage, checkout lifecycle, mandate scope, generated-claim status, and operator next actions all interact.

It should ask the platform for the shared decision envelope.

A simplified envelope contains:

eligibility
actor authority
checkout state
payment authority
generated-claim status
evidence references
next safe actions

For the Travel Backpack, the flow should block checkout because the required policy coverage is incomplete and inventory is stale. That decision should not depend on whether the request arrived through MCP, ACP, a feed-driven agent, or a future protocol.

The anti-pattern is predictable:

if (product.inStock && product.price.amount < 150 && paymentArtifact.present) {
  return { status: "ready_for_payment" };
}

That code is not malicious. It is what developers may be tempted to write when the local shortcut is easier than the shared domain path.

The reference architecture works only when the spine is the shortest safe path.

Correct producer path:

const envelope =
  buildAgentCommerceDecisionEnvelope(input);

The decision spine builds the canonical envelope. Surface adapters do not reconstruct the commercial decision.

Correct trusted-boundary path:

const liveRequest = {
  requestedAction: intent.requestedAction,
  subject: intent.subject,
  actor: authenticatedActor
};

const envelope =
  captureAgentCommerceDecisionEnvelope(externalEnvelope);

return projectTrustedAgentCommerceDecisionEnvelope(
  envelope,
  "tool",
  {
    ...trustContext,
    expectedRequest: liveRequest,
    now
  }
);

liveRequest is the normalized request context derived from the current protocol call and authenticated actor context. It contains the requested action, subject, and actor that the recipient expects to process. It must be constructed independently of the supplied envelope so the trusted boundary can detect replay, substitution, or context mismatch.

trustContext contains recipient-controlled verification material, trusted key identity, and authenticator policy. It is local configuration and must not be accepted from the supplied envelope.

For a state-changing operation:

const liveRequest = {
  requestedAction: intent.requestedAction,
  subject: intent.subject,
  actor: authenticatedActor
};

const envelope =
  captureAgentCommerceDecisionEnvelope(externalEnvelope);

const projection =
  projectTrustedAgentCommerceDecisionEnvelope(
    envelope,
    "checkout",
    {
      ...trustContext,
      expectedRequest: liveRequest,
      now
    }
  );

const execution =
  evaluateAgentCommerceDecisionExecution({
    envelope,
    currentDependencies,
    now
  });

if (!execution.permitted) {
  return execution;
}

return projection;

currentDependencies must come from the current authoritative domain owners rather than from the supplied envelope. This lets the application detect a price, inventory, policy, checkout, mandate, authority, payment, generated-claim, or evidence change that occurred after the decision was created.

The adapter does not decide whether stale inventory blocks payment. The feed does not infer policy quotability. Checkout does not repair missing commercial facts. Admin does not invent a different blocker taxonomy. The decision spine produces the canonical commercial decision, and each recipient projects that decision through the appropriate trusted boundary. Before a state-changing operation proceeds, the owning application also compares the protected dependencies with current authoritative state.

The adapter remains protocol-shaped. The commercial meaning remains domain-owned.

Tool descriptions are not commercial authority

Tool-based integrations introduce another subtle problem.

A tool may be described in natural language:

Use this tool to get the return policy for a product.

That description is useful for the agent. It is not a commercial guarantee.

If the platform cannot quote return policy for the Travel Backpack, the tool must be allowed to return a blocked result. The description should not imply that every product has quotable return terms.

A safer tool description is:

Use this tool to request quotable return-policy information for a product and buyer context. The tool may return a blocked result when active, source-backed policy coverage is missing, stale, conflicting, or not quotable.

This is less convenient, but it matches the system boundary.

The tool tells the agent what it can ask for. The domain decides what can be answered.

Without that distinction, tool descriptions become a soft form of policy. They promise behavior that the platform may not be able to support.

Payment artifacts are inputs, not authority

Payment-related protocols create higher-risk boundary problems because the adapter may receive artifacts that look authoritative: mandates, signed messages, payment instructions, buyer constraints, merchant identifiers, amount limits, or cart references.

Those artifacts matter. The adapter should preserve them and pass them into the platform.

But the adapter should not decide what they authorize.

A payment artifact is an input to authority evaluation. It is not authority by itself unless the authority domain says so.

For delegated payment, the platform may need to evaluate:

Is checkout state valid for this action?
Does the cart snapshot match the authorized cart?
Is the amount within the allowed limit?
Does the currency match?
Is the merchant within scope?
Has the authority expired?
Has it been revoked?
Is human confirmation required?
Is the actor allowed to request this transition?

A simplified readiness model might be:

type DelegatedPaymentReadiness = {
  checkoutAuthorityEstablished: boolean;
  authorityPresent: boolean;
  mandateWithinScope: boolean;
  cartSnapshotMatches: boolean;
  amountWithinLimit: boolean;
  currencyMatches: boolean;
  merchantMatches: boolean;
  notExpired: boolean;
  notRevoked: boolean;
  humanConfirmationSatisfied: boolean;
};

The adapter may validate that the protocol message is well-formed. It may verify envelope requirements if that belongs at the protocol edge. It may extract the authority reference. But it should not conclude that delegated payment is allowed merely because the artifact exists.

Protocol validity and commercial authority are different decisions.

This is one of the most important boundaries in the series.

Idempotency belongs where state changes

Agent-facing integrations will retry.

The adapter should propagate idempotency and correlation information, but state-changing idempotency belongs at the application service or state-transition boundary.

The adapter can build:

type IdempotencyContext = {
  idempotencyKey: string;
  correlationId: string;
  protocol: ProtocolName;
  externalRequestId?: string;
};

But it should not independently decide whether the mutation already happened.

Only the state-owning service can know whether a checkout session was created, whether inventory was reserved, whether payment was attempted, or whether a previous transition completed after the adapter lost the response.

The correct boundary is:

Adapter:
Extracts or creates idempotency context.

Application service:
Uses idempotency context when performing state transitions.

Audit:
Records the request, decision, and transition result.

If idempotency exists only in the adapter, retries can still create duplicate carts, duplicate checkout sessions, or inconsistent payment attempts through other surfaces.

Protocol errors must preserve domain meaning

Protocols often require simplified error categories.

Examples:

invalid_request
not_found
not_allowed
failed_precondition
conflict
internal_error

Those categories are useful, but they are not sufficient for commerce operations.

If the domain blocks checkout because return-policy coverage is missing, that reason should survive projection.

A weak adapter response is:

{
  "error": "not_allowed"
}

A better response is:

{
  "error": "failed_precondition",
  "reason": "missing_return_policy",
  "message": "Return-policy terms cannot be quoted for this product category."
}

The external response does not need to expose every internal evidence reference. Some details may be internal-only. But the adapter should not erase the blocker code.

Blocker codes are useful to agents, operators, logs, tests, and audits.

A protocol-level error says what happened at the interface. A domain blocker says why the commerce platform refused the action.

Both are needed.

Adapters should not convert blockers into fallback claims

Agent-facing systems create pressure to be helpful.

If return terms are missing, an adapter may be tempted to return:

The standard return policy is usually 30 days, but please check the merchant site.

That is not a translation. It is a new policy claim.

If US shipping is unknown, the adapter may be tempted to return EU shipping terms with a warning. If checkout is blocked, it may create a session and mark it as requiring review. If payment authority is incomplete, it may continue with a reduced scope.

Those behaviors may be valid in some business contexts, but they are domain decisions. They should be modeled explicitly and evaluated by the same decision layer.

A blocker should not be softened at the adapter because the adapter is closer to the agent.

For the Travel Backpack, if the return policy is missing for Travel Bags, the adapter should preserve that outcome:

Return-policy quotation is blocked because no active quotable return-policy fact applies to Travel Bags in this buyer context.

It may provide a next action. It may provide a source link if allowed. It may suggest contacting support. But it should not invent the return terms.

Internal feeds are adapters too

A feed may not feel like a protocol adapter because it is not interactive. It may simply publish products for downstream agents or search systems.

But a feed is still an external projection of domain state. It can drift.

If a feed publishes the Travel Backpack as checkout-ready while the checkout service would block it, downstream systems may make incorrect assumptions. If the feed includes generated descriptions that are pending review, agents may quote unapproved claims. If the feed includes a policy summary but policy quotability is blocked, the platform has exposed a claim it cannot support.

A feed item should therefore be a projection of domain decisions, not a shortcut around them.

A compact feed shape might be:

type AgentCommerceProductRecord = {
  productId: string;
  title: string;
  price: {
    amount: number;
    currency: string;
  };
  actions: {
    discover: DecisionResult;
    compare: DecisionResult;
    quotePolicy: DecisionResult;
    addToCart: DecisionResult;
    prepareCheckout: DecisionResult;
    delegatePayment: DecisionResult;
    showGeneratedClaim: DecisionResult;
    explain: DecisionResult;
  };
  generatedClaims: {
    status:
      | "allowed"
      | "requires_review"
      | "refused_here"
      | "inherited_refusal"
      | "stale"
      | "out_of_scope"
      | "absent";
  };
  publishedAt: string;
};

For the Travel Backpack:

{
  "productId": "BAG-TRAVEL-42",
  "actions": {
    "discover": "allowed",
    "compare": "allowed",
    "quotePolicy": "blocked",
    "addToCart": "requires_revalidation",
    "prepareCheckout": "blocked",
    "delegatePayment": "blocked",
    "showGeneratedClaim": "requires_review",
    "explain": "allowed"
  },
  "generatedClaims": {
    "status": "inherited_refusal"
  }
}

The show_generated_claim action result is requires_review, while the canonical generated-claim status is inherited_refusal. This feed does not expose every internal detail, but it preserves the important decision boundaries.

A feed can be compact without being optimistic.

Admin surfaces should use the same decisions

The admin UI is another place where drift can occur.

Operators may see one status while agents receive another. The admin UI may say a product is “agent-ready,” while the policy adapter blocks quotation and the checkout adapter blocks preparation. That creates operational confusion.

Admin surfaces should use the same domain decisions as protocol adapters, but project them differently.

For the Travel Backpack, an admin view might show:

Agent readiness:
Partially ready

Allowed:
- discover
- compare

Blocked:
- quote return policy
- quote US shipping
- prepare checkout
- delegated payment

Reasons:
- return-policy coverage missing for Travel Bags
- US shipping policy unknown
- inventory stale
- generated description pending review

Suggested actions:
- approve return-policy coverage for Travel Bags
- add or explicitly block US shipping coverage
- revalidate inventory
- review generated product description

That is the same underlying decision model as the adapters. The projection is different because the user is different.

Agents need safe responses.

Operators need remediation.

Auditors need evidence.

The domain decision should support all three.

The domain should not become protocol-shaped

Keeping adapters thin also protects the domain from the opposite failure: becoming shaped by the first protocol the platform supports.

A bad internal model looks like this:

type ProtocolShapedProductStatus = {
  acpPurchasable: boolean;
  mcpReturnToolEnabled: boolean;
  ap2PaymentReady: boolean;
  feedVisible: boolean;
};

This may seem convenient, but it couples the domain to external surfaces. The next protocol creates another field. A renamed tool requires domain changes. Protocol-specific concerns leak into core commerce logic.

A better internal model is protocol-neutral:

type AgentCommerceProductActionSnapshot = {
  productId: string;
  decisions: CommerceDecision[];
};

Adapters can project this profile into protocol-specific fields.

The domain should understand commercial actions:

discover
compare
quote_policy
add_to_cart
prepare_checkout
delegate_payment

It should not need to know every protocol’s field names, tool names, or response conventions.

This is the anti-corruption layer pattern applied to agent-ready commerce.

The adapter should not know too little

There is also an opposite mistake: making the adapter so thin that it becomes a blind pass-through.

A useful adapter must still understand the protocol enough to protect the domain from malformed or misleading input.

It should validate protocol schema. It should reject impossible shapes. It should normalize context. It should preserve request identifiers. It should avoid leaking internal-only evidence into public responses. It should translate domain blockers into protocol-safe language.

Thin does not mean ignorant.

The adapter must know enough to translate correctly. It must not know so much that it becomes the owner of commercial truth.

A useful rule is:

The adapter should know protocol semantics.
The domain should know commerce semantics.

When those responsibilities are reversed, either the adapter becomes a commerce engine or the domain becomes protocol-shaped.

Practical adapter tests should focus on drift

Adapter tests should focus on the failure that matters most: the same commercial scenario producing different meaning across surfaces.

The useful scenario is the Travel Backpack:

Price is fresh.
Inventory is stale.
Return-policy coverage is missing.
A payment artifact is present.

Expected meaning across feed, tool adapter, checkout, and admin:

Delegated payment is blocked.
Blocker codes include stale inventory and missing return policy.
Checkout state is not valid for payment for the requested action.
Payment authority: not_evaluated; no payment-specific blocker.
Payment dispatch: not attempted.
show_generated_claim action: requires_review; canonical claim status: inherited_refusal.
Admin next actions include revalidate inventory and attach or approve return-policy coverage.

The test should ignore generated copy, exact table ordering, route counts, and response snapshots. It should assert semantic agreement: blocker codes, causal meaning, scoped use, decision references, and blocked payment dispatch.

Boundary tests should reject a context hash presented as an owner verdict and a verdict bound to the wrong action, subject, actor, or scope. They should also reject a changed surface, a modified hash or authenticator, stale allowed output, unsigned external output, and HMAC output when no shared-secret trust domain is configured. A stale blocked projection may still carry the canonical refusal and remediation context, but it must not become allowed. Mutation tests should confirm that an older envelope cannot bypass the latest checkout revision, mandate state, or product decision merely because it is still signed and within its freshness window.

The goal is to stop a Friday-afternoon adapter shortcut from landing quietly.

Where this model can go wrong

Thin adapter architecture reduces drift, but it introduces its own failure modes.

The canonical intent becomes too generic

If the internal intent model is too vague, adapters will still need local interpretation.

For example:

action = "handle_request"

is not useful. The domain cannot evaluate meaningful eligibility from it.

The internal action vocabulary should be small, but not ambiguous.

The canonical intent becomes too protocol-specific

The opposite failure is copying protocol vocabulary into the domain.

If internal actions are named after protocol tools, the platform becomes coupled to the current integration surface. A second protocol will either distort the model or add duplicates.

Internal actions should be based on commercial meaning, not protocol naming.

The adapter hides too much information

Some adapters remove context to simplify the domain call. That can produce unsafe decisions.

If buyer type, region, channel, or authority references are missing, the domain may evaluate the action under defaults. Defaults may be wrong.

The adapter should normalize context, not discard it.

Domain blockers are treated as user-facing copy

Blocker messages are useful, but they may not be appropriate for every external response. Some evidence may be internal. Some messages may need protocol-safe wording.

The adapter may rewrite presentation. It should preserve meaning.

Projection widens a claim

A claim supported for one use can look reusable elsewhere because the language sounds close. That is still drift. Projection should preserve the scoped meaning it was given. If the claim is refused for this surface, that refusal should stay visible instead of disappearing as an empty answer.

The decision layer becomes a bottleneck

If every adapter calls the same decision layer, that layer must be reliable, observable, and performant. Otherwise all external surfaces suffer.

This is not a reason to duplicate logic in adapters. It is a reason to design the decision layer as platform infrastructure.

Protocol-specific security is ignored

Keeping commercial decisions in the domain does not mean the adapter skips protocol-level security.

The adapter may still need to validate signatures, request envelopes, authentication, replay constraints, or protocol-specific requirements before building canonical intent. Those checks are protocol boundary checks, not commercial decisions.

Payment artifacts are normalized too aggressively

A payment-related protocol may contain important details. If the adapter reduces the artifact to a boolean such as hasMandate: true, the authority service loses necessary information.

Normalize the artifact enough for the domain to consume it, but do not erase its constraints.

Admin tools become separate decision systems

Operators may need additional views, filters, and remediation actions. That does not mean the admin UI should compute agent-readiness independently.

Admin tools should project the same decisions with more operational detail.

Tests only cover one adapter

A single adapter can be correct in isolation while the platform is inconsistent across adapters.

Cross-adapter tests are necessary because semantic drift is a system property.

The tradeoff

Keeping adapters thin requires discipline.

It is often faster to implement a rule at the edge. The adapter has the request, the protocol schema, and the immediate integration pressure. A local fix can make the demo work.

The cost appears later.

A policy rule is duplicated. A checkout condition differs between surfaces. A payment artifact is treated as authority in one flow but only as evidence in another. A feed exposes capabilities that the checkout service would block. The admin UI cannot explain why agents behave differently from the product action status dashboard.

The tradeoff is between local speed and system consistency.

Adapter-local logic is faster to add.

Domain-owned decisions are easier to test, reuse, trace, and explain.

For ordinary integrations, adapter drift may be tolerable for a while. For agent-ready commerce, the threshold is lower because external agents can turn inconsistent responses into buyer-facing claims or attempted actions.

The platform should therefore make the correct path easier than the shortcut:

Map protocol request → build canonical intent → evaluate domain decision → project through the trusted boundary

If that path is hard, engineers will put logic in the adapter. The architecture should make the safe boundary convenient.

A practical implementation path

A platform does not need to solve every protocol problem at once.

A practical path is:

Define a small internal action vocabulary.
Use the shared v4 actions from Part 3: discover, compare, quote_policy, add_to_cart, prepare_checkout, delegate_payment, complete_checkout, show_generated_claim, and explain.
Define canonical intent.
Include product or cart identifiers, policy domain when relevant, region, currency, buyer type, channel, actor context, authority references, idempotency, and correlation metadata.
Define the shared decision envelope.
Return eligibility, authority, checkout state, payment authority, generated-claim status, evidence references, and next safe actions in one shape.
Add one trusted projection boundary.
External or persisted envelopes should pass through projectTrustedAgentCommerceDecisionEnvelope, or an equivalent recipient-owned boundary, before a surface response is returned. Low-level feed, tool, checkout, admin, and support mappings should remain internal and project from the captured envelope instead of recalculating commercial meaning.
Keep commercial truth, policy facts, eligibility, authority, checkout, and payment decisions outside adapters.
Adapters call domain or application use cases. They do not reimplement commerce rules.
Preserve blocker meaning during projection.
Protocol responses may be simplified, but blocker codes and causal meaning should not disappear.
Separate global capability from contextual permission.
Expose global support separately from contextual product or cart permission.
Propagate idempotency.
Adapters should pass idempotency and correlation information to state-owning services.
Test negative paths.
Missing policy, stale inventory, unsupported region, conflicting policy, pending generated claims, expired authority, and duplicate requests should all have expected behavior.
Add cross-adapter consistency tests.
The same product, action, and context should produce compatible decisions across ACP, UCP, MCP, AP2-related flows, feeds, marketplace APIs, and admin surfaces.

This path prevents the most damaging boundary mistakes without requiring a perfect protocol architecture upfront.

The boundary in one sentence

Agent-ready commerce will likely involve multiple external surfaces. Some will look like tool interfaces. Some will look like commerce protocols. Some will involve payment delegation. Some will be feeds. Some will be marketplace integrations. Some will be administrative views.

The platform should not let each surface become its own interpreter of commerce.

The risk is not that adapters are large. The risk is that they become authoritative.

A stable design keeps the decision chain inside the platform:

Commercial truth decides what is known.
Policy facts decide what terms apply.
Eligibility decides which actions are valid.
Authority decides who may request them.
Checkout services perform state transitions.
Evidence explains why the platform trusted the decision.
Audit records what happened.

Adapters translate those decisions into external protocol language.

For the Travel Backpack, every adapter should converge on the same meaning:

Discover: allowed
Compare: allowed
Return-policy quotation: blocked
US shipping quotation: blocked
Checkout preparation: blocked
Delegated payment: blocked

The protocol response can differ. The commercial decision should not.

That is the purpose of thin adapters in agent-ready commerce. They prevent ACP, UCP, MCP, AP2-related flows, feeds, tools, and future interfaces from becoming separate versions of product truth, policy interpretation, eligibility, checkout, and payment authority.

Next in the series

Part 6 will move from integration boundaries to state transitions:

Agent-Ready Commerce, Part 6: Checkout Is a State Machine, Not a Form

That article will examine why checkout preparation, cart mutation, inventory validation, policy coverage, payment authority, retries, and audit need explicit state transitions rather than loosely coupled request handlers.

About the author

Written by Dimitrios S. Sfyris, Founder & Software Architect at AspectSoft.

AspectSoft designs and develops custom software platforms, e-commerce systems, SaaS infrastructure, integrations, analytics tools, and practical digital products.

You can also follow the AspectSoft LinkedIn page for updates on software platforms, commerce systems, AI tooling, and developer-focused products.

Agent-Ready Commerce, Part 4: Making Policies Machine-Readable

Dimitrios S. Sfyris — Sun, 28 Jun 2026 16:38:05 +0000

The difficult policy question in agent-ready commerce is not whether the platform has a return policy page.

The difficult question is whether the platform can safely answer this:

Can an agent tell this buyer, in this region, for this product, through this channel, that this item can be returned under these conditions?

That is a different problem.

A public policy page may exist. A product page may link to it. A support team may understand the exceptions. A human buyer may be able to read the page and make a reasonable interpretation. None of that means an AI agent should treat the page as an authoritative decision source.

For agent-facing systems, policy has to move from text that humans interpret into structured commercial facts that systems can evaluate. Storing the words in a database is only the first step. The platform must also model where the policy applies, what evidence supports it, whether it is current, whether another rule takes precedence, and whether an agent may quote it.

A policy is not machine-readable just because it has been converted into JSON. A policy becomes machine-usable when the platform can answer:

What claim is being made?
Where does it apply?
Which source supports it?
Is the source current?
Does another source disagree?
Is the claim safe for an agent to quote?
Which actions does the claim support?

Series context

This is the fourth article in the Agent-Ready Commerce series.

Part 1 introduced the broader architecture model:

Facts → Eligibility → Authority → State transition → Evidence → Audit

Part 2 focused on commercial truth. It argued that catalog data is not enough. A platform needs source-backed, freshness-aware facts before agents or other systems can safely rely on product information.

This article focuses on policy structure.

The central argument is that agent-ready commerce platforms should not ask agents to interpret free-text policy pages as if they were executable rules. Returns, shipping, warranty, cancellation, regional restrictions, and business-buyer rules need to be modeled as policy facts with explicit scope and evidence. Those facts then feed eligibility decisions.

Policy pages are communication, not decision boundaries

A policy page is usually written to communicate terms to a human reader. It often combines general rules, exceptions, legal language, support instructions, category-specific notes, regional differences, and operational constraints in one document.

That is useful for a person. It is not a stable decision boundary for an agent.

Consider a return policy page that says:

Most products can be returned within 30 days of delivery, provided they are unused and returned in their original packaging. Some categories, clearance items, customized products, business orders, and international shipments may be subject to different terms.

A human can read this and understand that details may vary. An agent cannot safely turn that paragraph into a precise product-level claim without additional structure.

The paragraph does not answer:

Does this apply to Travel Bags?
Does it apply to SKU BAG-TRAVEL-42?
Does it apply to EU buyers?
Does it apply to US buyers?
Does it apply to business buyers?
Does it apply to marketplace orders?
Does a clearance campaign override it?
Is there a newer source?
Is the exception list complete?
Can the agent quote the 30-day window, or only link to the policy page?

If the platform does not answer those questions, the agent has to infer them. That moves policy interpretation into the wrong layer.

The platform owns commercial authority. The agent should not become the policy engine.

The useful unit is a policy claim

A policy claim is one specific statement with a defined scope, source, lifecycle, and allowed use. A better starting point is therefore to treat a policy as a set of claims.

A policy claim is a statement the platform may rely on under specific conditions.

For example:

Travel Bags sold to EU consumer buyers through the storefront or agent channel may be returned within 30 days if unused and in original packaging.

That is more useful than:

Return policy: 30 days

The second version looks structured, but it is not sufficiently scoped. It omits category, region, buyer type, channel, conditions, and source.

A policy claim needs at least six dimensions:

Domain:        returns, shipping, warranty, cancellation, restriction
Applicability: product, category, region, buyer type, channel
Value:         the actual rule or term
Evidence:      source documents, source records, review records, hashes
Lifecycle:     active, expired, superseded, draft, revoked
Quotability:  whether an agent may use the claim in generated language

For some systems, precedence should be added as a seventh dimension because overlapping policies are common.

This claim-based model is the main difference between a policy page and machine-readable policy.

A page says something.

A policy claim states one thing and keeps the conditions attached. Those conditions include scope, evidence, lifecycle, freshness, allowed use, and the surfaces on which the statement may appear.

Projection axes are the separate reasons a claim may or may not be usable in a specific output. The useful idea is simple: stale, out-of-scope, unsupported, and surface-refused claims should not collapse into one vague safe or unsafe flag.

The Travel Backpack example

Continue with the running example from Part 2 and Part 3:

Product: Travel Backpack
SKU: BAG-TRAVEL-42
Price: €129
Catalog status: active
Inventory status: in_stock
Category: Travel Bags

The commercial truth layer currently says:

Price: fresh
Inventory: stale
Return policy: missing for Travel Bags
Warranty policy: known
Shipping policy: known for EU, unknown for US
Generated description: pending review
Feed publication: last published yesterday

This is a useful example because the product is not obviously broken. A normal storefront can still render it. The product has a name, SKU, price, category, and stock status. A human can view the page.

The problem appears when the platform has to support agent actions.

An agent may ask:

Can I show this product to the buyer?
Can I compare it with similar backpacks?
Can I tell the buyer the return terms?
Can I quote EU shipping?
Can I quote US shipping?
Can I prepare checkout?
Can I proceed toward delegated payment?

The answers are not the same.

The product can be discovered. It can probably be compared on known product facts. EU shipping may be quotable if the EU shipping fact is active and source-backed. Warranty may be quotable if the warranty fact is known and approved.

But return-policy quotation should be blocked because the return policy is missing for the Travel Bags category. US shipping quotation should also be blocked because US shipping policy is unknown.

Checkout may be blocked if complete return and shipping policy coverage is required before checkout preparation. Delegated payment is blocked because checkout preparation is blocked and payment authority is a separate concern.

This is why policy structure matters. The product is not simply “available” or “unavailable.” Different policy facts support different actions.

Policy text and policy facts are different artifacts

A commerce platform may still need public policy pages. Buyers need readable explanations. Support teams need links. Legal and operations teams may require reviewed wording. Policy text is not going away.

The design issue is whether the same text is also treated as the system’s operational policy model.

In an agent-ready platform, it is safer to separate the artifacts:

Policy text:
Human-readable explanation of terms.

Policy fact:
Structured claim used by systems to evaluate actions.

Generated policy summary:
Derived language produced from policy facts or approved sources.

These artifacts can be linked, but they should not be confused.

A return policy page might include this sentence:

Eligible Travel Bags may be returned within 30 days if unused and returned in original packaging.

The corresponding policy fact could be represented like this:

type PolicyDomain =
  | "returns"
  | "shipping"
  | "warranty"
  | "cancellation"
  | "regional_restriction"
  | "business_buyer_rule";

type BuyerType = "consumer" | "business";
type Channel = "storefront" | "agent" | "marketplace" | "support";

type PolicyApplicability = {
  productIds?: string[];
  skuIds?: string[];
  categoryIds?: string[];
  regions?: string[];
  buyerTypes?: BuyerType[];
  channels?: Channel[];
};

type SourceRef = {
  sourceId: string;
  sourceType:
    | "policy_page"
    | "legal_document"
    | "admin_entry"
    | "commerce_backend"
    | "supplier_feed"
    | "operator_review";
  capturedAt: string;
  contentHash?: string;
  reviewedBy?: string;
};

type PolicyLifecycle = {
  status: "draft" | "active" | "superseded" | "expired" | "revoked";
  effectiveFrom: string;
  effectiveTo?: string;
  reviewedAt?: string;
  nextReviewDueAt?: string;
};

type Quotability = {
  status: "quotable" | "not_quotable" | "limited";
  allowedUses?: Array<"exact_value" | "summary" | "source_link_only">;
  reasons: string[];
};

type PolicyFact = {
  id: string;
  domain: PolicyDomain;
  appliesTo: PolicyApplicability;
  value: PolicyValue;
  sourceRefs: SourceRef[];
  lifecycle: PolicyLifecycle;
  quotability: Quotability;
};

The important part is not the exact TypeScript shape. The important part is that the fact contains the dimensions required for decision-making.

The fact does not merely say “30 days.” It says where that claim applies, what source supports it, whether the fact is active, and whether an agent may quote it.

Policy values should be typed by domain

A generic value: string field is usually not enough.

Different policy domains need different structures. A return policy is not shaped like a shipping policy. A warranty policy is not shaped like a regional restriction. A cancellation rule is not shaped like a business-buyer rule.

A simplified policy value model might look like this:

type PolicyValue =
  | ReturnPolicyValue
  | ShippingPolicyValue
  | WarrantyPolicyValue
  | CancellationPolicyValue
  | RegionalRestrictionValue
  | BusinessBuyerRuleValue;

type ReturnPolicyValue = {
  kind: "return_policy";
  returnWindowDays: number;
  conditions: Array<"unused" | "original_packaging" | "defective_only">;
  exclusions?: string[];
};

type ShippingPolicyValue = {
  kind: "shipping_policy";
  supportedRegions: string[];
  methods: Array<{
    code: string;
    label: string;
    estimatedDays?: {
      min: number;
      max: number;
    };
  }>;
  restrictions?: string[];
};

type WarrantyPolicyValue = {
  kind: "warranty_policy";
  durationMonths: number;
  coverage: string[];
  exclusions?: string[];
};

type CancellationPolicyValue = {
  kind: "cancellation_policy";
  allowedBeforeStatuses: Array<"paid" | "packed" | "shipped" | "fulfilled">;
  cutoffDescription?: string;
};

type RegionalRestrictionValue = {
  kind: "regional_restriction";
  restriction:
    | "not_sellable"
    | "not_shippable"
    | "requires_manual_review"
    | "source_link_only";
  reason: string;
};

type BusinessBuyerRuleValue = {
  kind: "business_buyer_rule";
  rule:
    | "consumer_terms_apply"
    | "business_terms_override"
    | "final_sale"
    | "manual_contract_required";
  notes?: string;
};

This structure prevents a common failure mode: reducing every policy into a short natural-language summary and then asking the agent to interpret it again.

If a return window matters, model the return window. If cancellation depends on order state, model the allowed states. If shipping depends on region, model the supported regions. If business buyers have different rules, represent that difference directly.

The goal is not to eliminate text. The goal is to keep system decisions from depending on unstructured text interpretation at runtime.

Applicability is where many policy models fail

The hardest part of policy modeling is often not the value. It is the scope.

A platform may know that a 30-day return policy exists. That still does not mean it applies to the Travel Backpack.

A policy can be scoped by:

Product
SKU
Category
Brand
Region
Buyer type
Sales channel
Marketplace
Campaign
Order value
Fulfillment method
Supplier
Effective date
Order state

The correct set depends on the business. A simple platform may only need category, region, buyer type, and channel. A marketplace or international commerce system may need more.

The risk is not that the platform lacks policy text. The risk is that the platform applies a true policy to the wrong context.

For the Travel Backpack, a useful return-policy fact would need to answer:

Does this return rule apply to category Travel Bags?
Does it apply to SKU BAG-TRAVEL-42?
Does it apply to EU buyers?
Does it apply to US buyers?
Does it apply to consumer buyers?
Does it apply to business buyers?
Does it apply when the product is sold through an agent channel?

If the platform cannot answer those questions, the fact may exist but not be usable.

That is why “policy exists” and “policy coverage exists for this action” should be treated as different states.

Coverage is not the same as permission

Coverage asks whether the platform has an applicable policy fact. Permission asks whether that fact may be used for the requested action. A missing policy fact should not automatically mean the policy outcome is negative.

If the return policy for Travel Bags is missing, that does not necessarily mean Travel Bags cannot be returned. It means the platform does not currently have a source-backed policy fact that supports a return-policy claim for that context.

This distinction matters because agent-facing systems should avoid converting unknown into false.

For the Travel Backpack:

Return policy missing for Travel Bags

does not mean:

This product is not returnable.

It means:

The platform cannot currently quote return terms for this product/category context.

Similarly:

US shipping policy unknown

does not necessarily mean:

This product cannot ship to the US.

It means:

The platform cannot currently quote US shipping terms or prepare US checkout without additional validation.

A useful policy coverage model might distinguish these states:

type PolicyCoverageStatus =
  | "known"
  | "missing"
  | "stale"
  | "conflicting"
  | "not_applicable"
  | "requires_review";

type PolicyCoverage = {
  productId: string;
  domain: PolicyDomain;
  context: {
    region: string;
    buyerType: BuyerType;
    channel: Channel;
  };
  status: PolicyCoverageStatus;
  selectedFactIds: string[];
  blockers: string[];
};

This allows eligibility decisions to be precise.

Known policy coverage may allow quotation or checkout. Missing coverage may block quotation. Conflicting coverage may create an operator task. Not applicable may be valid if the platform has explicit evidence that a domain does not apply.

Unknown is not enough. The reason for unknown matters.

Evidence should be attached to the claim, not reconstructed later

Policy facts need evidence because agent-facing claims must be traceable.

If an agent says:

This product has a 24-month warranty.

the platform should be able to explain which source supported the statement.

Evidence can come from different sources:

Public policy page
Legal document
Admin entry
Supplier feed
Commerce backend
Contract record
Operator review
Generated summary approval

The evidence reference should not be an afterthought. It should be part of the policy fact.

For example:

const warrantyFact: PolicyFact = {
  id: "policyfact_warranty_bag_travel_42_eu_consumer",
  domain: "warranty",
  appliesTo: {
    skuIds: ["BAG-TRAVEL-42"],
    regions: ["EU"],
    buyerTypes: ["consumer"],
    channels: ["storefront", "agent"]
  },
  value: {
    kind: "warranty_policy",
    durationMonths: 24,
    coverage: ["manufacturing_defects"],
    exclusions: ["normal_wear", "accidental_damage"]
  },
  sourceRefs: [
    {
      sourceId: "supplier_warranty_terms_2026_05",
      sourceType: "supplier_feed",
      capturedAt: "2026-06-10T08:30:00Z",
      contentHash: "sha256:..."
    },
    {
      sourceId: "ops_review_8841",
      sourceType: "operator_review",
      capturedAt: "2026-06-11T12:15:00Z",
      reviewedBy: "ops"
    }
  ],
  lifecycle: {
    status: "active",
    effectiveFrom: "2026-06-01T00:00:00Z",
    reviewedAt: "2026-06-11T12:15:00Z",
    nextReviewDueAt: "2026-09-01T00:00:00Z"
  },
  quotability: {
    status: "quotable",
    allowedUses: ["exact_value", "summary"],
    reasons: []
  }
};

This gives the platform a stable chain:

Claim → Source → Review → Quotability → Eligibility → Audit

That chain is more useful than storing policy text and hoping the agent interprets it correctly.

Freshness and lifecycle should be explicit

Policies change for reasons that are not always visible at the product level.

A shipping region can become unsupported. A supplier can update warranty terms. A return window can change during a campaign. A cancellation policy can change when fulfillment operations change. Business-buyer terms can be updated after contract review. A regional restriction can be added after a compliance decision.

A policy fact should therefore have a lifecycle, not only an updatedAt timestamp.

A timestamp says when a record changed. A lifecycle says whether the fact is valid for commercial use.

Useful lifecycle states include:

draft
active
superseded
expired
revoked

These states are not cosmetic. They affect agent actions.

A draft policy fact should not support quotation. An expired policy fact should not support checkout. A superseded policy fact may remain important for historical orders but should not be selected for new claims. A revoked policy fact may need to invalidate generated summaries and feed entries.

When policy authority is invalidated, the platform should retain the previous authority descriptor and hash for audit and bounded reassessment. Repairing the exact parent fact can make dependent claims or facts ready for review, but it should not restore quotation, checkout, or delegated-payment authority without a fresh owner decision.

For the Travel Backpack, suppose EU shipping was known yesterday but the carrier terms changed today. If the EU shipping fact is now stale or revoked, the platform should not keep quoting the old delivery terms because a feed entry still contains them.

This is why policy freshness belongs in commercial truth, not only in CMS publishing metadata.

Conflicts are domain events, not edge cases

Policy conflicts are common enough that the model should treat them as first-class.

Examples:

A public return page says Travel Bags can be returned within 30 days.
A category admin rule says Travel Bags are returnable only if unused.
A campaign rule says clearance items are final sale.
A product is currently in a clearance campaign.

This may be resolvable if precedence is explicit. The campaign rule may override the category rule. The category condition may refine the public page.

But if precedence is not explicit, the platform has a conflict. It should not allow an agent to pick one interpretation.

A conflict model can look like this:

type PolicyConflict = {
  id: string;
  domain: PolicyDomain;
  appliesTo: PolicyApplicability;
  conflictingFactIds: string[];
  conflictType:
    | "different_value"
    | "scope_overlap"
    | "missing_precedence"
    | "source_outdated"
    | "ambiguous_exception";
  severity: "warning" | "blocker";
  status: "open" | "resolved" | "accepted_risk";
  detectedAt: string;
};

A conflict should affect quotability and eligibility.

If return-policy sources disagree for Travel Bags, the product may still be discoverable. It may still be comparable on non-policy facts. But return-policy quotation should be blocked until the conflict is resolved or an approved precedence rule selects the winning fact.

The platform should prefer a blocked claim over an unsupported confident claim.

Precedence should be modeled, not remembered

Policy conflicts often arise because several valid policies overlap.

A platform may have:

Global policy
Regional policy
Channel policy
Buyer-type policy
Category policy
Product policy
Campaign policy
Order-specific override

If two policies apply, the system needs to know which one wins.

One possible precedence order is:

Order-specific override
Product-specific policy
Campaign-specific policy
Category policy
Buyer-type policy
Regional policy
Global policy

This order is not universal. The correct precedence model depends on the business, legal requirements, fulfillment model, and sales channels.

The architectural point is that precedence should not live in scattered conditionals or support-team memory. It should be part of the policy model.

When a selected fact wins, the platform should be able to explain why:

Selected policy:
Campaign-specific final-sale rule

Suppressed policy:
Category-level 30-day return rule

Reason:
Campaign-specific policy has higher precedence for products currently marked as clearance items.

When no precedence rule exists, the system should not silently choose. It should mark the claim as conflicting, block quotation, and create an operator task.

This is especially important for agents because natural language can hide uncertainty. A human support agent may know to be careful. An AI agent may produce a clean answer unless the platform gives it a structured blocker.

Quotability is not the same as truth

A policy fact can be true and applicable without being safe to quote. Quotability is the separate decision that allows the platform to expose the wording or an approved summary to a specific audience and use.

That sounds strange at first, but it reflects real commerce constraints.

A policy may be visible to humans as a general page but not precise enough for product-level quotation. A policy may be true for the storefront but not for marketplace orders. A policy may be correct for consumers but not business buyers. A policy may be under legal review. A policy may be generated from source material but not approved. A policy may be valid internally but should only be exposed through a source link.

Quotability controls how a policy fact can be used in agent-facing language.

This is where policy availability becomes claim projection. The platform is no longer asking only whether a policy fact exists. It is asking whether this exact claim may be projected into language for this use, surface, buyer context, and source state.

For example:

const returnPolicyCoverageForTravelBags = {
  productId: "BAG-TRAVEL-42",
  domain: "returns",
  context: {
    categoryId: "travel_bags",
    region: "EU",
    buyerType: "consumer",
    channel: "agent"
  },
  coverage: "missing",
  quotability: {
    status: "not_quotable",
    reasons: ["missing_return_policy"]
  }
};

This does not say that the product has no return rights. It says the platform cannot safely allow an agent to quote return terms for this product and context.

Quotability can also be limited:

const regionalRestrictionFact = {
  domain: "regional_restriction",
  appliesTo: {
    categoryIds: ["travel_bags"],
    regions: ["US"],
    channels: ["agent"]
  },
  value: {
    kind: "regional_restriction",
    restriction: "requires_manual_review",
    reason: "US shipping terms are not approved for agent quotation."
  },
  quotability: {
    status: "limited",
    allowedUses: ["source_link_only"],
    reasons: ["policy_facts_incomplete"]
  }
};

In that case, an agent may be allowed to say:

I cannot quote US shipping terms for this product. Please review the merchant’s shipping policy or contact support.

But it should not generate a specific shipping promise.

Quotability creates a boundary between what the platform knows, what it can show, and what an agent may say. It should not collapse every reason into one boolean. A claim can be fresh but out of scope, in scope but stale, usable for support but refused for agent quotation, or blocked because an upstream derived claim was refused.

Allowed-use matrix

Policy facts should support action-specific use.

A missing return policy should not necessarily remove a product from discovery. A stale shipping policy should not necessarily prevent comparison on product dimensions. A conflicting warranty policy should block warranty quotation but may not affect EU shipping quotation.

A simplified allowed-use matrix could look like this:

Action	Policy requirement	Missing policy	Stale policy	Conflicting policy
`discover`	Basic sellability and regional visibility	Usually allowed unless the missing policy affects visibility	Usually allowed if no policy claim is made	Allowed only if conflict does not affect visibility
`compare`	Facts used in comparison must be quotable	Allowed if comparison avoids missing policy domain	Allowed for non-policy comparison	Block policy-based comparison
`quote_policy`	Requested policy domain must be known, active, non-conflicting, and quotable	Blocked	Blocked or requires review	Blocked
`prepare_checkout`	Required checkout policy coverage must be complete for the context	Blocked if required policy is missing	Blocked or requires revalidation	Blocked
`delegate_payment`	Valid checkout state and payment authority must both exist	Blocked	Blocked	Blocked

For the Travel Backpack:

Action	Result	Reason
`discover`	Allowed	Product identity and basic catalog facts are known
`compare`	Allowed with limits	Product can be compared on known facts, but not on return terms
`quote_policy: returns`	Blocked	Return policy is missing for Travel Bags
`quote_policy: warranty`	Allowed if quotable	Warranty policy is known
`quote_policy: EU shipping`	Allowed if quotable	EU shipping policy is known
`quote_policy: US shipping`	Blocked	US shipping policy is unknown
`prepare_checkout`	Blocked	Return coverage is missing; inventory is stale from Part 3
`delegate_payment`	Blocked	Checkout state is not valid for payment; payment authority is separate

This is the same principle from Part 3 applied to policy. A product does not have one policy status. It has policy coverage per domain, context, and action.

Policy facts feed eligibility decisions

Policy facts are not an isolated content model. They are inputs to eligibility.

A useful flow is:

Policy sources
      ↓
Policy facts
      ↓
Commercial truth snapshot
      ↓
Eligibility decision
      ↓
Agent response, checkout state, feed projection, operator task

For example, when evaluating whether an agent may quote the return policy for the Travel Backpack, the eligibility layer might ask the policy layer:

Product: BAG-TRAVEL-42
Category: Travel Bags
Action: quote_policy
Policy domain: returns
Region: EU
Buyer type: consumer
Channel: agent

The policy layer may respond:

No active quotable return-policy fact applies to Travel Bags for EU consumer buyers through the agent channel.

The eligibility decision can then be structured:

type AgentCommerceDecisionAction =
  | "discover"
  | "compare"
  | "quote_policy"
  | "add_to_cart"
  | "prepare_checkout"
  | "delegate_payment"
  | "complete_checkout"
  | "show_generated_claim"
  | "explain";

type EligibilityDecision = {
  productId: string;
  requestedAction: AgentCommerceDecisionAction;
  context: {
    policyDomain?: PolicyDomain;
    region?: string;
    buyerType?: BuyerType;
    channel?: Channel;
  };
  result:
    | "allowed"
    | "blocked"
    | "requires_review"
    | "requires_revalidation"
    | "requires_confirmation";
  blockers: Array<{
    code: string;
    message: string;
    nextAction?: string;
  }>;
  evidenceRefs: SourceRef[];
  evaluatedAt: string;
};

const returnQuoteDecision: EligibilityDecision = {
  productId: "BAG-TRAVEL-42",
  requestedAction: "quote_policy",
  context: {
    policyDomain: "returns",
    region: "EU",
    buyerType: "consumer",
    channel: "agent"
  },
  result: "blocked",
  blockers: [
    {
      code: "missing_return_policy",
      message:
        "No active quotable return-policy fact applies to Travel Bags for EU consumer buyers through the agent channel.",
      nextAction:
        "Attach or approve return-policy coverage for the Travel Bags category."
    }
  ],
  evidenceRefs: [
    {
      sourceId: "policy:returns:travel-bags:missing",
      sourceType: "commerce_backend",
      capturedAt: "2026-06-28T09:00:00Z",
      contentHash: "<sha256-of-canonical-missing-coverage-snapshot>"
    }
  ],
  evaluatedAt: "2026-06-28T09:00:00Z"
};

This decision is more useful than a boolean.

The agent can avoid making an unsupported claim. The checkout service can block preparation. The admin UI can create a remediation task. The audit log can show why the product was not policy-quotable.

Operator tasks should describe commercial impact

Policy problems should not remain hidden inside validation errors.

A useful operator task does not merely say:

Missing return policy.

It explains the impact:

Return-policy coverage is missing for Travel Bags.

Affected product:
BAG-TRAVEL-42

Affected actions:
Agents can discover and compare the product, but cannot quote return terms.
Checkout preparation is blocked if complete policy coverage is required.

Suggested action:
Attach or approve a return-policy fact for Travel Bags, including region, buyer type, channel, effective dates, evidence, and quotability.

For US shipping, the task might say:

US shipping policy is unknown for Travel Bags.

Affected actions:
Agents cannot quote US shipping terms.
US checkout preparation is blocked or requires manual review, depending on checkout policy.

Suggested action:
Add US shipping coverage, explicitly mark US as unsupported, or route US orders to manual review.

This is one of the practical benefits of structured policy facts. They connect missing data to specific business capability.

Operators do not only need to know that data is incomplete. They need to know which agent actions are affected and what decision would unblock them.

Generated policy summaries are derived artifacts

Policy summaries are useful, but they should not become authority automatically.

An agent-facing system may want to say:

This product has known EU shipping terms and a known warranty. Return terms are not currently available for this category.

That kind of summary can improve user experience. The danger is treating generated language as the source of truth.

The safer direction is:

Authoritative source
      ↓
Structured policy facts
      ↓
Applicability and quotability decision
      ↓
Generated summary with source fact references
      ↓
Projection gate and projection axes
      ↓
Surface projection

The unsafe direction is:

Policy page
      ↓
Generated summary
      ↓
Agent authority

A generated summary should reference the facts it used and the uses for which it is allowed:

type AxisStatus = "passed" | "failed" | "not_evaluated";

type GeneratedPolicySummaryProjection = {
  id: string;
  productId: string;
  status:
    | "allowed"
    | "requires_review"
    | "refused_here"
    | "inherited_refusal"
    | "stale"
    | "out_of_scope"
    | "absent";
  sourceFactRefs: string[];
  derivedFactRefs: string[];
  allowedUses: Array<"feed" | "tool" | "checkout_explanation" | "support">;
  axes: Record<
    "source" | "freshness" | "scope" | "surface" | "use" | "payload" | "taint",
    AxisStatus
  >;
  inheritedRefusalCount: number;
  reviewStatus: "REVIEW_REQUIRED" | "APPROVED" | "BLOCKED";
  generatedAt: string;
  expiresAt?: string;
};

If the summary requires review, it should not be treated as an authoritative policy claim. If one of the underlying facts changes, the summary should be invalidated or regenerated.

When the platform builds the decision envelope, generated claims should appear as derived status rather than source truth:

generatedClaims.status
generatedClaims.claimIds
generatedClaims.sourceFactRefs
generatedClaims.allowedUses
generatedClaims.axes
generatedClaims.blockerCodes

That keeps the grounding discipline explicit: source data becomes a referenced fact; generated language is derived from approved facts; projection decides whether the claim is usable here, refused here, or not grounded for this use. If a summary depends on another refused projection, that refusal should travel with it internally.

The canonical envelope should also keep generated-claim state action-aware. A generated-claim blocker may explain quote_policy or comparison copy, but it should not falsely become the main reason for a delegated-payment decision unless the requested payment action actually depends on that claim.

Business-buyer rules deserve separate modeling

Business-buyer rules are easy to miss because many commerce systems begin with consumer flows.

But business purchases often have different terms:

Returns may be limited or unavailable.
Warranty may depend on contract terms.
Cancellation may require approval.
Payment may use invoices instead of card authorization.
Shipping terms may depend on account agreements.
VAT or tax handling may affect checkout.

A generic consumer return policy should not automatically apply to business buyers unless that is an explicit rule.

For example:

const businessBuyerReturnRule: PolicyFact = {
  id: "policyfact_business_returns_travel_bags_eu",
  domain: "business_buyer_rule",
  appliesTo: {
    categoryIds: ["travel_bags"],
    regions: ["EU"],
    buyerTypes: ["business"],
    channels: ["storefront", "agent"]
  },
  value: {
    kind: "business_buyer_rule",
    rule: "manual_contract_required",
    notes:
      "Business-buyer return terms are governed by account agreement or manual approval."
  },
  sourceRefs: [
    {
      sourceId: "business_terms_admin_2026_06",
      sourceType: "admin_entry",
      capturedAt: "2026-06-20T14:00:00Z"
    }
  ],
  lifecycle: {
    status: "active",
    effectiveFrom: "2026-06-20T00:00:00Z"
  },
  quotability: {
    status: "limited",
    allowedUses: ["source_link_only"],
    reasons: ["BUSINESS_TERMS_REQUIRE_ACCOUNT_CONTEXT"]
  }
};

For an agent, this means the consumer answer and the business-buyer answer may differ for the same SKU.

That difference belongs in the policy model, not in prompt instructions.

Cancellation is state-dependent policy

Cancellation policies are also different from static return policies because they often depend on order state.

A product may be cancellable before payment, after payment but before packing, or before dispatch. Once shipped, cancellation may become a return process instead.

A cancellation policy fact therefore needs to connect policy to state transition.

const cancellationFact: PolicyFact = {
  id: "policyfact_cancellation_standard_eu_consumer",
  domain: "cancellation",
  appliesTo: {
    regions: ["EU"],
    buyerTypes: ["consumer"],
    channels: ["storefront", "agent"]
  },
  value: {
    kind: "cancellation_policy",
    allowedBeforeStatuses: ["paid", "packed"],
    cutoffDescription:
      "Cancellation is allowed before the order is handed to the carrier."
  },
  sourceRefs: [
    {
      sourceId: "cancellation_policy_page",
      sourceType: "policy_page",
      capturedAt: "2026-06-12T09:00:00Z",
      contentHash: "sha256:..."
    }
  ],
  lifecycle: {
    status: "active",
    effectiveFrom: "2026-06-01T00:00:00Z"
  },
  quotability: {
    status: "quotable",
    allowedUses: ["summary"],
    reasons: []
  }
};

This matters because an agent may ask to cancel an order, but the answer depends on state.

Policy says what is allowed.

Execution checks the current order state.

Authority decides whether the actor may request cancellation.

Audit records the result.

Those boundaries should remain separate.

Regional restrictions should not be hidden inside shipping text

Regional restrictions are often mixed into shipping pages, product descriptions, marketplace settings, or fulfillment rules. That makes them easy to miss.

For agent-facing systems, regional restrictions should be explicit because they affect discovery, quotation, checkout, and payment.

A region may be:

Supported for discovery but not checkout
Supported for shipping but not returns
Supported for consumers but not business buyers
Unsupported because of carrier coverage
Unsupported because of legal restriction
Allowed only with manual review

A structured regional restriction can prevent overexposure.

For example:

const usShippingUnknown: PolicyCoverage = {
  productId: "BAG-TRAVEL-42",
  domain: "shipping",
  context: {
    region: "US",
    buyerType: "consumer",
    channel: "agent"
  },
  status: "missing",
  selectedFactIds: [],
  blockers: ["missing_shipping_policy"]
};

The result is not necessarily “do not show the product to US users.” The result may be:

Do not quote US shipping terms.
Do not prepare US checkout without revalidation or manual review.
Do not allow delegated payment for US checkout.

Again, the correct behavior depends on action eligibility.

Protocol adapters should remain thin

Agent-facing protocols and tool interfaces may require policy information in different shapes. A platform may eventually expose policy decisions through ACP- or UCP-style commerce surfaces, MCP tools, AP2-related payment flows, internal feeds, marketplace APIs, or other adapters.

The adapter should not become the policy interpreter.

A thin adapter asks the domain model:

Can this policy be quoted for this product and context?
Which facts support the answer?
Which blockers exist?
What action result should be exposed?

Then it translates the result into the protocol format.

The adapter should not parse policy pages, resolve conflicts, decide precedence, or determine quotability. If each protocol adapter performs its own policy interpretation, the platform will eventually provide inconsistent answers through different surfaces.

Deep protocol integration belongs in Part 5. For Part 4, the policy principle is enough:

Adapters translate policy decisions.
They do not own policy meaning.

Where this model can go wrong

Structured policy facts are useful, but they introduce their own failure modes.

Over-modeling before the business needs it

A platform does not need a full legal rules engine on day one. If the product range is small, regions are limited, and there are no agent-facing checkout actions, a simpler policy model may be enough.

A practical starting point is:

domain
applicability
value
source
lifecycle
quotability

More complex precedence, conflict resolution, campaign overrides, and contract-specific rules can be added when real requirements justify them.

The goal is not architectural completeness. The goal is to avoid letting agents infer commercial terms from ambiguous text.

Treating structured facts as automatically correct

A structured fact can still be wrong.

The category scope may be too broad. The region may be incorrect. The source may be outdated. The review may be missing. A condition may have been simplified too aggressively.

Structure makes facts easier to evaluate. It does not make them true by itself.

That is why source references, lifecycle, review, and audit remain necessary.

Removing too much nuance

Some policy text contains important nuance. Reducing it to a headline value can be dangerous.

For example:

Returns accepted within 30 days

is not equivalent to:

Returns accepted within 30 days if unused, in original packaging, not customized, not clearance, and not restricted by regional law.

A weak structured model can create false precision. It may appear machine-readable while omitting the conditions that actually matter.

Converting unknown into allowed

This is one of the highest-risk failures.

If US shipping is unknown, the system should not apply EU shipping terms by default. If business-buyer returns are unknown, the system should not silently apply consumer terms. If a category policy is missing, the system should not assume the global policy applies unless that inheritance is explicit and approved.

Defaults are policy decisions. They should be represented as policy facts or precedence rules, not hidden in code paths.

Letting generated summaries drift

Generated summaries become risky when underlying facts change.

If a summary says the Travel Backpack has EU shipping terms and a 24-month warranty, the summary should reference the fact IDs used to generate it. If those facts are superseded, the summary should be invalidated.

Otherwise the platform may keep publishing natural language that no longer matches the policy model.

Making quotability global

A fact may be quotable in one context and not another.

Warranty may be quotable for EU consumers but not business buyers. Shipping may be quotable for EU but not US. A policy may be quotable through support but not through an automated agent channel.

Quotability should be evaluated with applicability and the source reference that made it true. A claim grounded against one policy source should not stay quotable after that policy changes.

Turning the policy service into a god service

The policy layer should answer policy questions. It should not own all eligibility, checkout, authority, payment, and protocol behavior.

A clean boundary is:

Policy service:
which policy facts apply, whether they are fresh, whether they conflict, whether they are quotable

Eligibility service:
which actions are allowed for the product and context

Checkout service:
whether checkout state can advance

Authority service:
whether the actor may request the action

Protocol adapter:
how the decision is represented externally

Policy facts are critical inputs. They are not the entire commerce system.

Practical tests for policy facts

Policy tests should be scenario-led, with field-level assertions used to keep the result precise.

A useful case includes:

Product
Category
Region
Buyer type
Channel
Policy domain
Source state
Expected coverage
Expected quotability
Expected eligibility impact
Expected operator work item

For the Travel Backpack:

Scenario	Expected result
EU consumer, Travel Bags, return policy missing	Return quotation blocked; checkout blocked if return coverage is required
EU consumer, warranty known and quotable	Warranty quotation allowed
EU consumer, EU shipping known and quotable	EU shipping quotation allowed
US consumer, US shipping unknown	US shipping quotation blocked; checkout blocked or requires review
Business buyer, only consumer return policy exists	Business return quotation blocked
Conflicting return sources for Travel Bags	Return quotation blocked; conflict work item created
Generated return summary pending review	Summary cannot be used as authority
Category policy and campaign policy overlap without precedence	Quotation blocked; precedence work item created
Expired shipping policy remains linked from a page	Shipping quotation blocked until refreshed
Revoked warranty source remains in generated summary	Summary invalidated
Exact parent policy is repaired after a dependent claim was invalidated	Dependent becomes ready for review; authority is not restored automatically

A test expectation can be expressed like this:

type PolicyScenarioExpectation = {
  productId: string;
  context: {
    region: string;
    buyerType: BuyerType;
    channel: Channel;
  };
  domain: PolicyDomain;
  expectedCoverage: PolicyCoverageStatus;
  expectedQuotability: "quotable" | "not_quotable" | "limited";
  expectedEligibilityBlockers: string[];
  expectedOperatorWorkItems: string[];
};

The value is in testing the relationship between facts, context, action, and outcome.

A policy fact may look correct in isolation but fail when category inheritance, buyer type, region, channel, lifecycle, and quotability are evaluated together.

Policy-change tests are also important, but they do not need to expose internal version labels.

For example:

Given:
An EU shipping policy is active and quotable.

When:
The approved EU shipping terms are updated with different delivery estimates.

Then:
The previous shipping facts are superseded.
New shipping facts become the current approved facts.
Generated summaries based on the previous shipping terms are invalidated.
Agent feed projections are refreshed.
Eligibility decisions can explain which current policy source was used.

This is the level of behavior worth testing when policy facts support agent-facing claims. Rendering the policy page is not enough.

A practical implementation path

A platform can adopt this model incrementally.

The first version does not need to solve every policy problem. It can start with the claims that affect agent-facing actions.

A practical path is:

Define the policy domains that matter.
Start with returns, shipping, warranty, cancellation, regional restrictions, and business-buyer rules.
Model applicability.
At minimum, capture product or category, region, buyer type, and channel.
Attach evidence.
Every policy fact should reference a source, capture time, and ideally a source hash or review record.
Add lifecycle.
Distinguish active, draft, superseded, expired, and revoked facts.
Add quotability.
Do not allow agents to quote every visible policy by default.
Feed policy coverage into eligibility.
Use policy facts to decide quote_policy, prepare_checkout, and delegated-action eligibility.
Create operator tasks from gaps.
Missing, stale, conflicting, or non-quotable facts should produce remediation work with clear commercial impact.
Treat generated summaries as derived.
A generated summary should reference facts and source records. It should not become authority automatically.

This path keeps the model grounded. It avoids building a large rules engine before there is a reason, but it also avoids the unsafe default of treating policy pages as executable commercial truth.

The tradeoff

Structured policy modeling adds work.

It requires domain modeling, source references, lifecycle states, conflict detection, quotability rules, eligibility integration, operator workflows, and scenario tests.

For a simple storefront with limited regions and no agent-facing actions, a public policy page and manual support process may be sufficient.

Agent-ready commerce changes the threshold.

Once agents can compare products, quote terms, prepare checkout, or operate under delegated authority, policy ambiguity becomes a systems problem. A free-text page is no longer enough because the platform must decide which claims can be used, in which context, and for which action.

The tradeoff is between publishing convenience and operational reliability.

Free-text policy pages are easier to create.

Structured policy facts are easier to evaluate, test, audit, and connect to eligibility decisions.

The purpose of this model is not to replace human-readable policy. It is to prevent human-readable policy from being treated as a machine decision boundary without the structure required to support that role.

What this changes

Machine-readable policy is not just policy text stored in a structured format.

A policy becomes machine-usable when the platform can evaluate a specific claim in a specific context.

For the Travel Backpack, the platform should be able to say:

The warranty policy is known and quotable.
EU shipping is known and quotable.
US shipping is unknown and not quotable.
Return policy coverage is missing for Travel Bags.
Checkout is blocked if complete policy coverage is required.
Delegated payment is blocked because checkout preparation is blocked.

Those answers cannot be derived safely from a generic policy page at runtime. They require structured policy facts, applicability, evidence, lifecycle, conflict handling, quotability, and eligibility integration.

The useful distinction is:

Policy text communicates terms to humans.
Policy facts support system decisions.
Quotability controls what agents may say.
Eligibility controls what agents may do.
Evidence explains why the platform trusted the claim.

This keeps policy interpretation inside the commerce platform, where it can be reviewed, evaluated, and traced back to sources. It also keeps protocol adapters and AI-generated summaries from becoming accidental sources of commercial authority.

Next in the series

Part 5 will move from domain decisions to integration boundaries:

Agent-Ready Commerce, Part 5: Keeping ACP, UCP, MCP, and AP2 Adapters Thin

That article will examine how agent-facing protocol adapters should translate domain decisions without owning product truth, policy interpretation, eligibility, authority, checkout state, or payment semantics.

About the author

Written by Dimitrios S. Sfyris, Founder & Software Architect at AspectSoft.

AspectSoft designs and develops custom software platforms, e-commerce systems, SaaS infrastructure, integrations, analytics tools, and practical digital products.

You can also follow the AspectSoft LinkedIn page for updates on software platforms, commerce systems, AI tooling, and developer-focused products.

Agent-Ready Commerce, Part 3: Why “Available” Is Not Enough for AI Agents

Dimitrios S. Sfyris — Sun, 28 Jun 2026 16:28:05 +0000

Most e-commerce platforms have some version of product availability.

A product is active. It is in stock. It has a price. It can appear on the storefront.

For a human-facing e-commerce site, that model can be good enough for a long time. The storefront can render a product page, show an “Add to cart” button, and let checkout perform final validation later.

For agent-ready commerce, that model becomes too vague.

The problem is not that available is wrong. The problem is that it hides too many different decisions behind one word.

Available for what?

Discovery?

Comparison?

Policy quotation?

Cart insertion?

Checkout preparation?

Delegated payment?

Those actions do not carry the same risk, and they should not use the same rule.

Series context

This is the third article in the Agent-Ready Commerce series.

Part 1 introduced the broader model:

Facts → Eligibility → Authority → State transition → Evidence → Audit

Part 2 focused on the first part of that chain: commercial truth. A raw product record is not enough for agent-facing systems. The platform needs source-backed, freshness-aware product facts before software can safely act on product information.

This article focuses on the second part of the chain: eligibility.

The main idea is to answer four separate questions instead of hiding them behind available:

Commercial truth says what is known.
Eligibility says which actions are valid.
Authority says who is allowed to request them.
Execution performs the state change.

Keeping those layers separate prevents a valid fact from being mistaken for permission, and permission from being mistaken for successful execution.

The problem with generic availability

A typical product model might contain fields like this:

type Product = {
  id: string;
  title: string;
  active: boolean;
  inventoryStatus: "in_stock" | "low_stock" | "out_of_stock";
  price: {
    amount: number;
    currency: string;
  };
};

A simple availability check might look like this:

function isAvailable(product: Product) {
  return product.active && product.inventoryStatus !== "out_of_stock";
}

This is not a bad function. It answers a real question.

The issue is that the question is too broad.

If isAvailable(product) returns true, what exactly did the platform allow?

Can the product appear in search?

Can an agent recommend it?

Can an agent compare it with alternatives?

Can an agent quote its return policy?

Can an agent place it in a cart?

Can an agent prepare checkout?

Can an agent trigger a delegated payment flow?

A human-facing storefront may not need to separate all of those actions immediately. A page can render the product and rely on later validation to catch problems.

An agent-facing system needs a more precise contract. If an external agent sees available: true, it may reasonably assume that the product can be used in a commercial action. That is too much meaning for one boolean.

The platform needs action-specific eligibility.

A running example

Consider a product that appears simple from the catalog perspective:

Product: Travel Backpack
SKU: BAG-TRAVEL-42
Price: €129
Catalog status: active
Inventory status: in_stock
Category: Travel Bags

A storefront can render this product. It has a title, price, image, category, and inventory flag.

The commercial truth layer, however, may know more:

Price: fresh
Inventory: stale
Return policy: missing for Travel Bags
Warranty policy: known
Shipping policy: known for EU, unknown for US
Generated description: pending review
Feed publication: last published yesterday

A generic availability model might still say:

available = true

But that answer is not precise enough.

A better action-level view would be:

discover          allowed
compare           allowed
quote_policy      blocked
add_to_cart        requires_revalidation
prepare_checkout  blocked
delegate_payment  blocked

This is the important shift.

The product is not simply available or unavailable. It has different readiness levels for different actions.

A human user may still browse the product page. An agent may still discover and compare the product. But the platform should not allow policy quotation or checkout preparation until the missing and stale facts are resolved.

Actions need to be part of the domain model

The first step is to name the actions that matter at the agent boundary.

A platform does not need to expose every internal operation, but it should define the commercial actions agents may request.

For example:

type AgentCommerceDecisionAction =
  | "discover"
  | "compare"
  | "quote_policy"
  | "add_to_cart"
  | "prepare_checkout"
  | "delegate_payment"
  | "complete_checkout"
  | "show_generated_claim"
  | "explain";

These actions are not interchangeable.

discover means the product may appear in an agent-facing catalog, search result, or product feed.

compare means the product may be evaluated against alternatives using selected commercial facts.

quote_policy means the agent may describe policy terms such as returns, shipping, cancellation, or warranty.

add_to_cart means the agent may place the product into a draft cart or buyer-intent context.

prepare_checkout means the agent may start or prepare a checkout session.

delegate_payment means the agent may request payment within a bounded authority scope tied to the current checkout.

complete_checkout means the platform may finalize a valid checkout through payment and order submission when all state, authority, and idempotency requirements pass.

show_generated_claim means the platform may project approved generated language for the requested surface and use.

explain means the platform may return an explanation from the existing decision basis without recomputing the decision locally.

Once the actions are named, the platform can stop treating product availability as one global state.

Instead, it can ask:

Given the current product truth and request context,
is this specific action allowed?

That is a better question.

Different actions require different facts

Action eligibility should depend on commercial truth, but not every action requires the same facts.

A simplified requirement matrix might look like this:

Action             Required truth                         Example result
--------------------------------------------------------------------------------
discover           identity, visibility, media             allowed
compare            identity, price, comparable attributes   allowed
quote_policy       applicable policy coverage              blocked
add_to_cart         price, inventory signal                 requires_revalidation
prepare_checkout   fresh price, fresh inventory, policies   blocked
delegate_payment   valid checkout state, mandate, payment authority      blocked
complete_checkout   valid checkout, payment result, order transition      blocked
show_generated_claim   approved claim, scope, surface, use, evidence       requires_review
explain            existing decision basis and safe evidence               allowed

This matrix is more useful than a single available flag because it explains what each action depends on.

The travel backpack example becomes clearer:

discover
  Required: identity, visibility, media
  Result: allowed

compare
  Required: identity, price
  Result: allowed

quote_policy
  Required: return-policy coverage
  Result: blocked because return policy is missing for Travel Bags

add_to_cart
  Required: price, inventory signal
  Result: requires_revalidation because inventory is stale

prepare_checkout
  Required: fresh price, fresh inventory, applicable policies
  Result: blocked because inventory is stale and return policy is missing

delegate_payment
  Required: valid checkout state and payment authority
  Result: blocked because checkout is not ready, so payment is not attempted

This does not mean the product is broken. It means different capabilities have different readiness levels.

That distinction is essential for agent-ready systems.

Eligibility decisions should be structured

A boolean return value is rarely enough because it shows the outcome but not the reason, evidence, freshness, or safe next step.

This is too weak:

const checkoutAllowed = false;

It tells the caller the result, but it does not explain the decision or preserve enough meaning for other surfaces.

A more useful eligibility result includes action, subject, context, result, blocker codes, evidence references, and next safe actions. In a decision-spine architecture, that eligibility result becomes one section of a broader envelope rather than the whole answer.

type AgentCommerceDecisionEnvelopeAuthenticator =
  | {
      kind: "digital_signature";
      algorithm: "ed25519";
      format: "detached";
      keyId: string;
      verificationKeyRef: string;
      protectedHash: string;
      value: string;
      verifiable: true;
    }
  | {
      kind: "message_authentication_code";
      algorithm: "hmac-sha256";
      format: "detached";
      keyId: string;
      verificationKeyRef: string;
      protectedHash: string;
      value: string;
      verifiable: true;
    }
  | {
      kind: "unsigned";
      algorithm: "none";
      format: "none";
      protectedHash: string;
      verifiable: false;
      warning: "missing_platform_signing_key";
    };

type AgentCommerceDecisionEnvelope = {
  contractVersion: "agent-commerce-decision-envelope-v4";
  envelopeSchemaVersion: "agent-commerce-decision-envelope-schema-v4";
  decisionId: string;
  decisionHash: string;
  inputDependencyHash: string;
  resultHash: string;
  ruleSetVersion: string;
  ruleSetRef: string;
  ruleSetHash: string;
  authenticator: AgentCommerceDecisionEnvelopeAuthenticator;
  requestedAction: AgentCommerceDecisionAction;

  basis: {
    status:
      | "allowed"
      | "blocked"
      | "requires_revalidation"
      | "requires_review"
      | "requires_confirmation";
    allowed: boolean;
    reasonCodes: readonly string[];
    components: readonly {
      code: string;
      source: "eligibility" | "authority" | "checkout" | "payment" | "generated_claim";
      field: string;
      value: string | number | boolean | null;
      contributesTo: "status" | "payment_dispatch" | "generated_claim_use";
    }[];
  };

  eligibility: {
    result:
      | "allowed"
      | "blocked"
      | "requires_revalidation"
      | "requires_review"
      | "requires_confirmation";
    blockerCodes: readonly string[];
    source: "product" | "policy" | "checkout" | "payment" | "operator" | "combined";
  };

  evidenceRefs: readonly {
    type: string;
    id: string;
    hash: string;
    hashAlgorithm: "sha256";
  }[];

  nextSafeActions: readonly {
    action: string;
    owner: "system" | "operator" | "buyer" | "merchant";
    reasonCode: string;
  }[];
};

The full envelope also carries subject, actor, input references, freshness dependencies and horizons, authority, checkout, payment, and generated-claim projection state. inputDependencyHash covers decisionId, the requested surface and action, actor, subject, input references, rule-set identity, evaluation time, evidence pins, and freshness dependencies. resultHash covers the computed eligibility, authority, checkout, payment, generated-claim, freshness, basis, and next-action result. decisionHash binds the contract and schema to those two hashes.

The canonical basis keeps the result and its explanation together. Every code in basis.reasonCodes must appear in at least one basis.components[].code, and every component code must appear in the reason set. Several components may explain the same reason at different causal boundaries, but no reason can exist without a component.

The canonical result also needs an explicit precedence rule. A required hard block in authority, checkout, payment, or generated-claim use must dominate softer review, confirmation, or revalidation states. Contradictory sections—such as allowed with blocker codes, a valid checkout carrying checkout blockers, or payment dispatch attempted while payment authority is blocked—should be rejected rather than normalized into a plausible envelope.

When actor authority or checkout validity prevents payment evaluation, the payment section should remain not_evaluated with no payment-specific blockers. The upstream reasons remain in their owning sections and in the decision basis.

The authenticator states whether the envelope is protected by an Ed25519 digital signature, an HMAC-SHA-256 message-authentication code, or an explicitly unsigned local-development variant. The core eligibility idea remains simple: result, reason, evidence, and next safe action.

For the Travel Backpack, the prepare_checkout envelope can say:

basis.status = blocked
basis.reasonCodes = eligibility_blocked, invalid_checkout_state, missing_return_policy, stale_inventory
eligibility.result = blocked
checkout.validForRequestedAction = false
payment.paymentDispatchAttempted = false
nextSafeActions = revalidate inventory, attach return policy

The envelope can still pin this result to its inputs and freshness horizon, but the reader-facing decision remains easy to follow.

That structure prevents three common mistakes.

First, the feed cannot turn active and in_stock into checkout readiness.

Second, the adapter cannot treat an authenticated actor as evidence that the action itself is valid.

Third, the payment layer cannot treat a payment artifact as permission to bypass stale inventory or missing policy coverage.

Eligibility stays explicit, but it does not pretend to answer every question by itself.

Eligibility is not authority

Eligibility and authority are often confused.

They should not be.

Eligibility answers:

Is this action valid for this product under the current commercial conditions?

Authority answers:

Is this actor allowed to request this action?

Execution answers:

Can the system perform the state change now?

Those are separate checks.

For example, a product may be checkout-eligible, but a specific agent may not have permission to prepare checkout.

An agent may have a valid payment mandate, but the product may not be checkout-eligible because inventory is stale.

A checkout session may be eligible and authorized, but execution may fail because the state changed between validation and transition.

The separation looks like this:

Commercial truth
        ↓
Eligibility
        ↓
Authority
        ↓
Execution
        ↓
State transition

A command should pass through each layer.

type CommerceCommandReadiness = {
  eligibility: ActionEligibilityDecision;
  authority: AuthorityDecision;
  execution: ExecutionReadiness;
  executable: boolean;
};

type AuthorityDecision = {
  actorId: string;
  requestedAction: AgentCommerceDecisionAction;
  allowed: boolean;
  reason?: string;
  scopes: string[];
};

type ExecutionReadiness = {
  currentState: string;
  transitionAllowed: boolean;
  reason?: string;
};

This prevents one decision from doing too much work.

A product being eligible does not mean the actor is authorized.

An actor being authorized does not mean the product is eligible.

Both being true does not guarantee execution if the state transition is invalid.

This distinction becomes especially important for checkout and delegated payment.

Eligibility should consume commercial truth, not rebuild it

The eligibility layer should not rediscover product facts from raw catalog data. That would duplicate logic and create inconsistent behavior.

Instead, eligibility should consume a truth snapshot.

type AgentCommerceCommercialTruthSnapshot = {
  productId: string;
  truthRef: string;
  facts: {
    identity: "known" | "missing" | "stale" | "conflicting";
    price: "known" | "missing" | "stale" | "conflicting";
    inventory: "known" | "missing" | "stale" | "conflicting";
    policyCoverage: "known" | "missing" | "stale" | "conflicting";
    generatedClaims: "known" | "missing" | "REVIEW_REQUIRED" | "conflicting";
  };
};

Eligibility then applies action-specific requirements.

type ActionRequirement = {
  requestedAction: AgentCommerceDecisionAction;
  requiredFacts: Array<keyof AgentCommerceCommercialTruthSnapshot["facts"]>;
  blockedStatuses: Array<
    "missing" | "stale" | "conflicting" | "REVIEW_REQUIRED"
  >;
};

Example:

const actionRequirements: ActionRequirement[] = [
  {
    requestedAction: "discover",
    requiredFacts: ["identity"],
    blockedStatuses: ["missing", "conflicting"]
  },
  {
    requestedAction: "compare",
    requiredFacts: ["identity", "price"],
    blockedStatuses: ["missing", "conflicting"]
  },
  {
    requestedAction: "quote_policy",
    requiredFacts: ["policyCoverage"],
    blockedStatuses: ["missing", "stale", "conflicting"]
  },
  {
    requestedAction: "prepare_checkout",
    requiredFacts: ["price", "inventory", "policyCoverage"],
    blockedStatuses: ["missing", "stale", "conflicting"]
  }
];

The boundary is clean:

Commercial truth says:
Inventory is stale.

Eligibility says:
Stale inventory blocks checkout preparation.

Authority says:
This actor may or may not request checkout preparation.

Execution says:
The checkout state transition can or cannot happen now.

Each layer has a narrower responsibility.

Context matters

Product eligibility is rarely global.

A product may be eligible in one region and blocked in another. A shipping policy may exist for the EU but not for the US. A return policy may apply to consumers but not business buyers. A payment method may depend on currency. A marketplace channel may have stricter requirements than the merchant’s own storefront.

Eligibility should therefore include context.

type EligibilityContext = {
  region?: string;
  currency?: string;
  buyerType?: "consumer" | "business";
  channel?: "storefront" | "agent" | "marketplace";
  actorType?: "human" | "agent";
};

The same product can produce different decisions:

Context: EU consumer, agent channel
discover          allowed
compare           allowed
quote_policy      blocked: return policy missing
prepare_checkout  blocked: inventory stale

Context: US consumer, agent channel
discover          allowed
compare           allowed
quote_policy      blocked: return policy missing
prepare_checkout  blocked: inventory stale, shipping policy unknown

Context: business buyer, agent channel
discover          allowed
compare           allowed
quote_policy      blocked: business return terms missing
prepare_checkout  blocked: business policy coverage incomplete

A global available flag cannot express this.

Context-aware eligibility is more complex, but it avoids overexposing products in cases where the platform lacks the facts required for a specific buyer or market.

Eligibility should support degradation

Eligibility is not only a gate. It is also a way to degrade safely.

The product does not need to disappear from every agent surface because one high-risk action is blocked.

For the travel backpack, the platform can expose a capability profile:

discover          allowed
compare           allowed
quote_policy      blocked
add_to_cart        requires_revalidation
prepare_checkout  blocked
delegate_payment  blocked

This tells the agent and the operator exactly where the product stands.

A product with incomplete return-policy coverage may still be discoverable. A product with stale inventory may still be comparable. A product with an unreviewed generated description may still be shown if the agent uses approved catalog copy instead.

This is better than two extreme alternatives:

Too permissive:
Show the product as fully available even though checkout is unsafe.

Too conservative:
Remove the product entirely even though low-risk actions are still valid.

Action-specific eligibility allows the platform to preserve safe capabilities while blocking unsafe ones.

That is a more useful operational model.

Decision results should be more than allowed or blocked

Not every negative decision should be represented as blocked.

Some decisions require revalidation. Some require human review. Some require additional authority. Some are warnings rather than blockers.

A useful result type might be:

type EligibilityResult =
  | "allowed"
  | "blocked"
  | "requires_revalidation"
  | "requires_review"
  | "requires_confirmation";

For example:

discover
  result: allowed
  warning: generated description pending review, using approved catalog summary

add_to_cart
  result: requires_revalidation
  reason: inventory signal is stale

quote_policy
  result: blocked
  reason: return-policy coverage is missing

prepare_checkout
  result: blocked
  reason: inventory stale and policy coverage missing

This makes the system more expressive.

A product does not have to move directly from allowed to blocked. It can require revalidation, review, or warning-aware handling depending on the action.

Those result labels should stay attached to the action and context that produced them. A warning on discovery is not the same as a warning on checkout.

Rule identity should be explicit

Eligibility rules change.

A platform may decide that stale inventory is acceptable for cart insertion but not checkout. Later, high-demand categories may require fresh inventory even before cart insertion. A policy team may require return-policy coverage before comparison in certain regions. A marketplace channel may require stricter policy completeness than the storefront.

If eligibility decisions are stored, cached, published, or audited, the platform needs to know which rule set produced them.

type EligibilityRuleSetRef = {
  ruleSetVersion: string;
  ruleSetRef: `ruleset:sha256:${string}`;
  ruleSetHash: string;
  effectiveFrom: string;
  changeRef?: string;
};

A decision should reference both the human-readable rule-set version and the content-addressed identity:

type EligibilityDecisionMetadata = {
  truthRef: string;
  ruleSet: EligibilityRuleSetRef;
  evaluatedAt: string;
};

This helps distinguish two cases:

Case 1:
The product became blocked because inventory changed from fresh to stale.

Case 2:
The product became blocked because the eligibility rule changed.

Both are valid, but they mean different things operationally.

The first case may require inventory revalidation. The second may require merchant remediation, policy updates, or feed republishing.

Without traceable decisions, these cases become harder to explain.

Eligibility and feeds

An agent-facing product feed should not publish raw catalog availability as if it were action eligibility.

A feed item can include a compact action summary:

type AgentCommerceProductRecord = {
  id: string;
  title: string;
  price: {
    amount: number;
    currency: string;
    lastVerifiedAt: string;
  };
  actions: Partial<Record<
    AgentCommerceDecisionAction,
    "allowed" | "blocked" | "requires_revalidation" | "requires_review" | "requires_confirmation"
  >>;
  truthRef: string;
  decisionHash: string;
  validUntil: string | null;
  publishedAt: string;
};

For the travel backpack:

{
  "id": "bag_travel_42",
  "title": "Travel Backpack",
  "price": {
    "amount": 129,
    "currency": "EUR",
    "lastVerifiedAt": "2026-07-06T10:12:00.000Z"
  },
  "actions": {
    "discover": "allowed",
    "compare": "allowed",
    "quote_policy": "blocked",
    "add_to_cart": "requires_revalidation",
    "prepare_checkout": "blocked",
    "delegate_payment": "blocked",
    "show_generated_claim": "requires_review",
    "explain": "allowed"
  },
  "truthRef": "truth:travel-backpack:2026-07-06",
  "decisionHash": "1111111111111111111111111111111111111111111111111111111111111111",
  "validUntil": "2026-07-06T10:15:00.000Z",
  "publishedAt": "2026-07-06T10:12:00.000Z"
}

The feed does not need to expose every internal rule. It should expose enough for external systems to avoid unsafe assumptions.

The full blocker details can live behind a product-detail endpoint or eligibility endpoint.

This keeps the feed compact while preserving explainability.

Eligibility and protocol adapters

Protocol adapters should not invent eligibility rules.

This is a common source of drift.

One adapter calculates product visibility from catalog status. Another adapter calculates checkout readiness from inventory. The feed publisher uses a different rule. The admin UI shows a different status. The checkout service performs final validation again.

The result is inconsistent behavior.

A safer structure is:

Protocol request
        ↓
Protocol adapter
        ↓
Internal action mapping
        ↓
Eligibility service
        ↓
Domain decision
        ↓
Protocol-specific response

The adapter maps the external request to an internal action.

type ProtocolActionMapping = {
  protocol: "acp" | "ucp" | "mcp" | "ap2" | "internal_feed" | "admin";
  externalAction: string;
  internalAction: AgentCommerceDecisionAction;
};

The internal eligibility service owns the decision.

The adapter only translates the result into the protocol-specific shape.

This matters because different protocols may ask similar questions with different language:

Can this product be purchased?
Can checkout be prepared?
Is this item eligible for agent checkout?
Can this offer be fulfilled?
Is delegated payment supported?

The platform should not answer each of those questions with separate business logic.

It should map them to internal actions and evaluate those actions consistently.

Eligibility and checkout

Checkout should revalidate product action status, but it should not be the first place where readiness is understood.

If eligibility exists only inside checkout, then discovery, comparison, feeds, protocol adapters, and admin workflows cannot explain product action status before checkout starts.

A better structure is:

Commercial truth
        ↓
Action eligibility
        ↓
Checkout preparation
        ↓
Checkout state transition

Checkout preparation can consume eligibility decisions:

type CheckoutPreparationInput = {
  cartId: string;
  productDecisions: ActionEligibilityDecision[];
};

If any product is not checkout-eligible, checkout preparation can return structured blockers:

type CheckoutPreparationBlocker = {
  productId: string;
  code: string;
  message: string;
  nextAction?: string;
};

This does not remove the need for final checkout validation. Prices and inventory should still be revalidated at the transition boundary.

But it prevents checkout from becoming the only part of the system that knows whether a product is commercially ready.

Eligibility gives the rest of the platform a way to reason before checkout begins.

Eligibility and delegated payment

Delegated payment is not just a higher level of product availability.

It depends on several layers.

Commercial truth
        ↓
Product eligibility
        ↓
Valid checkout state
        ↓
Payment authority
        ↓
Payment execution

A product being checkout-eligible does not mean an agent can trigger payment.

Delegated payment also requires mandate boundaries, amount limits, currency match, merchant binding, cart snapshot integrity, expiry, revocation checks, and possibly human confirmation.

A simplified readiness model might look like this:

type DelegatedPaymentReadiness = {
  productEligibilityPassed: boolean;
  checkoutAuthorityEstablished: boolean;
  paymentMandatePresent: boolean;
  cartSnapshotMatches: boolean;
  amountWithinMandate: boolean;
  humanConfirmationSatisfied: boolean;
};

This prevents a dangerous shortcut:

Product is available → agent can pay

That shortcut should not exist.

The correct chain is narrower and safer:

Product facts are valid.
The product is eligible for checkout.
Checkout validation passes.
The actor has payment authority.
The payment command is executable.

Each statement belongs to a different layer.

Eligibility should produce operator tasks

Eligibility decisions should not only serve agents. They should also serve operators.

When many products fail the same eligibility check, the platform should turn those failures into grouped remediation tasks.

For example:

type EligibilityIssueGroup = {
  requestedAction: AgentCommerceDecisionAction;
  blockerCode: string;
  productIds: string[];
  impact: string;
  nextAction: string;
};

Operator-facing examples:

18 products are discoverable but not checkout-ready.

Reason:
Inventory freshness is stale.

Impact:
Agents can show these products, but checkout preparation is blocked.

Next action:
Revalidate inventory from the warehouse source.

Another example:

7 products are blocked from policy quotation.

Reason:
Return-policy coverage is missing.

Impact:
Agents should not quote return terms for these products.

Next action:
Attach or approve a return policy for the Travel Bags category.

This is where eligibility becomes operationally useful.

A generic validation error says something is wrong. An eligibility issue explains which commercial capability is affected.

That is the difference between debug output and an operator workflow.

Avoid boolean explosion

A common response to weak availability modeling is to add more booleans.

type Product = {
  active: boolean;
  inStock: boolean;
  agentVisible: boolean;
  comparable: boolean;
  policyQuotable: boolean;
  eligibleForCheckoutStart: boolean;
  paymentReady: boolean;
};

This is better than one boolean, but it still has problems.

Booleans do not explain themselves. They do not include blockers, context, evidence, rule identities, or next actions.

If eligibleForCheckoutStart is false, the platform still needs to answer:

Is the price stale?
Is inventory stale?
Is policy coverage missing?
Is the product blocked in this region?
Is generated content pending review?
Did the rule identity change?
Is checkout blocked only for agents or also for humans?

Booleans are useful as summaries, especially in feeds and dashboards. They should not be the authoritative model.

A better rule is:

Use booleans for projections.
Use shared decision envelopes for commercial meaning.

For example:

type AgentCommerceProductActionSnapshot = {
  productId: string;
  decisions: ActionEligibilityDecision[];
  summary: {
    discoverable: boolean;
    comparable: boolean;
    policyQuotable: boolean;
    checkoutEligible: boolean;
  };
};

The summary is convenient. The decisions are authoritative.

Determinism matters

Eligibility decisions should be deterministic for the same inputs.

Same truth reference
+ same context
+ same rule identity
= same eligibility decision

This matters for caching, debugging, audit trails, feed publication, and agent interactions.

If an agent sees a product as checkout-eligible in a feed, then another endpoint says it is blocked, the platform needs to explain why. A valid explanation might be that a new truth reference was generated or a rule changed. An invalid explanation is that different services used different hidden logic.

A deterministic eligibility decision should record:

Product ID
Truth reference
Context
Rule set reference
Decision result
Blockers
Evidence references
Evaluation timestamp

At the envelope boundary, deterministic behavior is stronger than repeating the same business result. The same normalized input, including the same evaluatedAt, should produce identical inputDependencyHash, resultHash, and decisionHash values. Object keys and set-like collections such as blocker codes, evidence references, freshness dependencies, allowed uses, and next safe actions should be normalized before hashing so ordering alone does not create drift. Valid date-time inputs should be normalized to one UTC representation before they enter the hash.

This does not mean decisions never change. They should change when facts change, context changes, rules change, or the evaluation time intentionally changes.

The point is that change should be explainable and reproducible.

Where this model can go wrong

Action eligibility improves precision, but it introduces its own risks.

1. Eligibility can become a god service

If every product, policy, checkout, payment, protocol, and admin rule gets pushed into one eligibility service, the service becomes too broad. It starts owning decisions that belong elsewhere.

A useful boundary is:

Eligibility decides whether a product/action is valid.
Authority decides whether an actor may request it.
Checkout decides whether a state transition can occur.
Payment decides whether financial authority exists.

2. Too many blocker codes can create noise

Structured blockers are useful, but a large uncontrolled list becomes hard to operate. Blocker codes should be stable, documented, and grouped by business impact.

3. Context can make caching harder

Context-aware decisions are more correct, but they are harder to cache. A decision for an EU consumer may not apply to a US buyer or business account.

4. Feed summaries can become stale

If action summaries are published to a feed, they need to reference the truth and eligibility decisions they came from. Otherwise, external systems may rely on stale action eligibility.

5. Protocol mappings can drift

If external protocol actions are mapped inconsistently to internal actions, eligibility decisions may appear inconsistent even if the domain service is correct.

6. The model can become too conservative

If every incomplete fact blocks every action, the platform may remove useful low-risk capabilities. Discovery and comparison should not always require the same evidence as checkout or payment.

7. The model can become too permissive

If high-risk actions reuse low-risk rules, agents may be allowed to proceed without enough evidence. Checkout and delegated payment should have stricter requirements than discovery.

These failure modes do not make action eligibility a bad idea. They define the engineering constraints around it.

Practical tests for action eligibility

Eligibility should be tested through a small number of semantic scenarios, with response-shape assertions used only where they clarify the decision.

The Travel Backpack scenario is enough to catch the most dangerous drift:

Product: Travel Backpack
Price: fresh
Inventory: stale
Return policy: missing
Payment artifact: present

Expected meaning:

discover          allowed
compare           allowed
quote_policy      blocked: missing_return_policy
add_to_cart        requires_revalidation: stale_inventory
prepare_checkout  blocked: stale_inventory, missing_return_policy
delegate_payment     blocked because checkout is not valid; upstream blockers remain visible in checkout and the decision basis
payment authority    not_evaluated; no payment-specific blockers
payment dispatch     false
show_generated_claim action result requires_review; canonical claim status inherited_refusal; inheritedRefusalCount: 1
explain           allowed from the decision basis

The same blocker-code meaning should survive projection into the feed, tool adapter, checkout path, and admin or support view. The tests should also assert exact reason/component reconciliation and repeat the same normalized input to confirm stable hashes. They should mutate decisionId to confirm identity tampering is detected. They should also reject contradictory allowed sections and any soft eligibility result that would otherwise hide a hard authority, checkout, or payment block.

The goal is to make one important semantic test hard to bypass: an adapter should not be able to quietly convert a blocked decision into success.

The main tradeoff

Action-specific eligibility adds complexity.

It introduces action vocabularies, rule sets, context objects, decision envelopes, blocker codes, evidence references, rule identities, and tests.

That is more work than a single available flag.

For a small storefront, this may be unnecessary. If the only user is a human browsing a simple catalog, a basic availability model may be enough.

Agent-ready commerce changes the threshold.

Once external agents can discover products, compare options, quote policies, prepare checkout, or act within delegated authority, raw availability becomes too weak as the platform contract.

The tradeoff is between simplicity and precision.

A single availability flag is simpler, but it hides risk.

Action-specific eligibility is more complex, but it makes the system explainable, safer, and more useful to agents, protocol adapters, checkout services, payment flows, and operators.

Design principles

A practical action eligibility model should follow several principles.

1. Name the actions

Do not rely on generic availability. Define the actions agents may perform.

2. Separate low-risk and high-risk actions

Discovery, comparison, policy quotation, checkout, and delegated payment should not share one rule.

3. Base eligibility on commercial truth

Eligibility should consume source-backed facts. It should not rediscover product state independently.

4. Return structured decisions

A decision should include result, blockers, warnings, evidence, context, rule identity, and evaluation time.

5. Keep eligibility separate from authority

Eligibility says whether the product/action is valid. Authority says whether the actor may request it.

6. Keep eligibility separate from execution

A product may be eligible, but the requested state transition may still be invalid at execution time.

7. Support context

Region, buyer type, channel, currency, and actor type can all affect eligibility.

8. Name the rule set

Eligibility decisions should record which rule set produced the result.

9. Use booleans only as projections

Boolean flags are useful for summaries, but decision objects should be authoritative.

10. Feed operator workflows

Blocked decisions should produce actionable tasks with business impact and next actions.

Conclusion

“Available” is too broad for agent-ready commerce.

A product can be visible but not comparable. Comparable but not policy-quotable. Policy-quotable but not checkout-ready. Checkout-ready but not eligible for delegated payment.

Those distinctions matter because agents need explicit action boundaries.

The platform should therefore expose action-specific eligibility decisions instead of relying on one product availability flag.

Commercial truth says what is known.
Eligibility says which actions are valid.
Authority says who may request them.
Execution performs the state change.

This separation keeps the system easier to reason about. It also creates better interfaces for agents, protocol adapters, feeds, checkout services, payment flows, and operator tools.

Next in the series

Part 4 will move from product actions to policy structure:

Agent-Ready Commerce, Part 4: Making Policies Machine-Readable

That article will examine how returns, shipping, warranty, cancellation, regional restrictions, and policy conflicts can be modeled as structured facts instead of free-text pages that agents are expected to interpret.

About the author

Written by Dimitrios S. Sfyris, Founder & Software Architect at AspectSoft.

AspectSoft designs and develops custom software platforms, e-commerce systems, SaaS infrastructure, integrations, analytics tools, and practical digital products.

You can also follow the AspectSoft LinkedIn page for updates on software platforms, commerce systems, AI tooling, and developer-focused products.

Agent-Ready Commerce, Part 2: From Product Pages to Commercial Truth

Dimitrios S. Sfyris — Sun, 28 Jun 2026 06:12:13 +0000

A product page is not a contract.

It is a presentation surface.

That distinction matters more once AI agents start interacting with commerce systems.

Traditional e-commerce platforms can rely on human interpretation. A human can read a product title, inspect images, compare delivery notes, scan a return policy, notice uncertainty, and decide whether to continue. A product page can be visually useful even when the underlying commercial state is incomplete, stale, or spread across several systems.

An AI agent needs a different interface. It should not need to scrape a product page, infer policy meaning from free text, guess whether inventory is fresh, or decide whether a price is reliable enough to quote. If the platform expects agents to recommend products, compare alternatives, prepare checkout, or act within delegated authority, then the platform needs to expose more than product presentation.

It needs to expose commercial truth.

Series context

This is the second article in the Agent-Ready Commerce series. Part 1 introduced the broader model:

Facts → Eligibility → Authority → State transition → Evidence → Audit

This article focuses on the first part of that chain: facts.

The central argument is simple: a raw product record is not enough for agent-ready commerce. The platform needs a source-backed, freshness-aware, action-supporting view of the product before agents can safely act on it.

Product pages hide too much state

A normal product page compresses many different concerns into one human-readable surface:

Product identity
Price
Inventory
Images
Description
Badges
Variants
Delivery estimate
Return policy snippet
Warranty information
Promotional copy
Reviews
Cross-sell modules
Checkout call to action

That compression is useful for presentation, but it hides distinctions that software needs. The page shows one experience; the platform may hold several facts with different sources, freshness, and confidence.

The page may show “In stock,” but the inventory value may be several hours old. It may show a price, but the pricing source may have changed since the last feed publication. It may show a return-policy sentence, but the policy may not apply to every category, region, or customer type. It may show marketing claims that are approved for humans to read, but not precise enough for agents to quote.

A human can tolerate some of this ambiguity. An agent should not be forced to.

A product page answers a presentation question:

How should this item be shown to a buyer?

An agent-facing product contract has to answer operational questions:

What is currently known about this item?
Where did that knowledge come from?
How fresh is it?
Is it complete enough for discovery?
Is it complete enough for comparison?
Is it complete enough for checkout?
Is it safe for an agent to quote?

Those are different questions. Treating the product page as the source of truth mixes them together.

A running example

Consider a product in a catalog:

Product: Travel Backpack
SKU: BAG-TRAVEL-42
Price: €129
Catalog status: active
Inventory status: in_stock
Category: Travel Bags

A simple storefront can render this product. It has a title, a price, an image, a category, and an inventory flag.

A basic product model might look like this:

type Product = {
  id: string;
  sku: string;
  title: string;
  description: string;
  price: {
    amount: number;
    currency: string;
  };
  inventory: {
    status: "in_stock" | "low_stock" | "out_of_stock";
    quantity?: number;
  };
  categoryId: string;
  imageUrls: string[];
  active: boolean;
};

This is enough to display a product card.

It is not enough to decide whether an AI agent can safely act on the product.

Suppose the real platform state looks like this:

Price: fresh, verified 5 minutes ago
Inventory: stale, last synced 18 hours ago
Return policy: missing for Travel Bags
Warranty policy: known
Shipping policy: known for EU, unknown for US
Generated description: pending review
Feed publication: last published yesterday

A human-facing storefront may still show the product. The commercial system, however, has several unresolved questions.

Can an agent discover this product? Probably yes.

Can an agent compare it with another backpack? Maybe yes, if comparison only needs identity, price, category, and basic attributes.

Can an agent quote the return policy? No, because return-policy coverage is missing for the category.

Can an agent prepare checkout? No, because inventory is stale.

Can an agent trigger delegated payment? No, because checkout preparation is blocked and delegated payment needs a separate payment-authority decision.

A single field like active: true cannot represent these distinctions.

This is the gap commercial truth is meant to fill.

Product data is not commercial truth

Product data describes the item.

Commercial truth describes what the platform is currently willing to rely on about the item for a specific decision. It does not mean that every known fact is complete, fresh, or suitable for every action.

Those are related, but not identical.

A catalog record may say:

const product = {
  id: "bag_travel_42",
  title: "Travel Backpack",
  price: {
    amount: 129,
    currency: "EUR"
  },
  inventory: {
    status: "in_stock"
  },
  active: true
};

A commercial truth summary might say:

type ProductTruthSummary = {
  productId: string;
  truthRef: string;
  facts: {
    identity: FactStatus;
    price: FactStatus;
    inventory: FactStatus;
    policyCoverage: FactStatus;
    media: FactStatus;
    generatedClaims: FactStatus;
  };
  overallStatus: "verified" | "incomplete" | "stale" | "conflicting";
};

type FactStatus = {
  status: "known" | "missing" | "stale" | "conflicting" | "unknown";
  sourceRefs: string[];
  lastVerifiedAt?: string;
};

For the backpack example, the truth summary could look like this:

const truth: ProductTruthSummary = {
  productId: "bag_travel_42",
  truthRef: "truth_2025_10_18_001",
  facts: {
    identity: {
      status: "known",
      sourceRefs: ["catalog_import_2025_10_18"],
      lastVerifiedAt: "2025-10-18T09:00:00Z"
    },
    price: {
      status: "known",
      sourceRefs: ["pricing_sync_2025_10_18_0905"],
      lastVerifiedAt: "2025-10-18T09:05:00Z"
    },
    inventory: {
      status: "stale",
      sourceRefs: ["warehouse_sync_2025_10_17_1500"],
      lastVerifiedAt: "2025-10-17T15:00:00Z"
    },
    policyCoverage: {
      status: "missing",
      sourceRefs: []
    },
    media: {
      status: "known",
      sourceRefs: ["media_library_2025_10_15"]
    },
    generatedClaims: {
      status: "unknown",
      sourceRefs: ["ai_description_draft_778"]
    }
  },
  overallStatus: "incomplete"
};

The commercial truth object does not replace the product. It qualifies it.

The product says what the item is.

The truth summary says how much confidence the platform has in the facts required to use that item in commerce workflows.

Source references are part of the model

Source references are not metadata decoration. They are part of the reliability model.

A price from a pricing service, an inventory value from a warehouse sync, a warranty statement from a policy document, and a description generated by an AI workflow should not be treated as equally authoritative.

A source reference can be modeled simply:

type SourceReference = {
  sourceId: string;
  sourceType:
    | "catalog_import"
    | "merchant_admin"
    | "pricing_system"
    | "inventory_system"
    | "policy_document"
    | "media_library"
    | "generated_content";
  sourceRef?: string;
  sourceHash?: string;
  observedAt: string;
};

The important point is that commercial facts should be traceable.

Without source references, the platform cannot easily answer basic operational questions:

Where did this price come from?
Was this inventory value synced or manually edited?
Was this policy claim approved or generated?
Did the source change after the feed was published?
Which source should be revalidated before checkout?

For human-facing commerce, missing traceability may create debugging pain. For agent-facing commerce, it also creates trust problems.

If an agent quotes a return policy or prepares checkout based on stale inventory, the platform needs to know which fact led to the decision and which source produced that fact.

This is why commercial truth should be evidence-aware from the beginning.

Freshness should be modeled per fact group

Freshness is often modeled too broadly.

A product is marked fresh or stale.

That is not precise enough.

Different facts have different risk profiles. Stale inventory is more dangerous than a stale product image. Stale price may block checkout but not discovery. Missing warranty information may block policy quotation but not product comparison. A generated description pending review may block agent quotation but not internal merchandising.

A better model tracks freshness by fact group:

type AgentCommerceProductFreshness = {
  identity: "fresh" | "stale" | "unknown";
  price: "fresh" | "stale" | "unknown";
  inventory: "fresh" | "stale" | "unknown";
  policyCoverage: "fresh" | "stale" | "unknown";
  media: "fresh" | "stale" | "unknown";
  generatedClaims: "fresh" | "stale" | "unknown";
};

For the backpack example:

const freshness: AgentCommerceProductFreshness = {
  identity: "fresh",
  price: "fresh",
  inventory: "stale",
  policyCoverage: "unknown",
  media: "fresh",
  generatedClaims: "unknown"
};

This allows the platform to make more useful decisions:

Discovery: allowed
Comparison: allowed
Policy quotation: blocked
Checkout preparation: blocked
Delegated payment: blocked

A single productIsFresh value would hide the reason. Fact-level freshness gives the platform a way to degrade gracefully instead of treating the product as either fully usable or fully unusable.

Truth should not decide everything

A commercial truth layer should describe what is known. It should not become responsible for every business decision.

This boundary is important.

Commercial truth answers:

What facts exist?
Where did they come from?
How fresh are they?
Are they complete?
Are they conflicting?

Eligibility answers:

Given those facts, which actions are allowed?

Those two layers should remain separate.

For example:

type TruthReadiness = {
  productId: string;
  facts: {
    price: "fresh";
    inventory: "stale";
    policyCoverage: "missing";
  };
};

The truth layer can produce that result without deciding what the agent may do.

The eligibility layer can then apply action-specific rules:

type AgentCommerceDecisionAction =
  | "discover"
  | "compare"
  | "quote_policy"
  | "add_to_cart"
  | "prepare_checkout"
  | "delegate_payment"
  | "complete_checkout"
  | "show_generated_claim"
  | "explain";

type EligibilityDecision = {
  productId: string;
  requestedAction: AgentCommerceDecisionAction;
  allowed: boolean;
  blockers: string[];
};

A simplified eligibility function might look like this:

function evaluateCheckoutReadiness(truth: TruthReadiness): EligibilityDecision {
  const blockers: string[] = [];

  if (truth.facts.price !== "fresh") {
    blockers.push("Price must be revalidated before checkout.");
  }

  if (truth.facts.inventory !== "fresh") {
    blockers.push("Inventory must be revalidated before checkout.");
  }

  if (truth.facts.policyCoverage === "missing") {
    blockers.push("Required policy coverage is missing.");
  }

  return {
    productId: truth.productId,
    requestedAction: "prepare_checkout",
    allowed: blockers.length === 0,
    blockers
  };
}

This separation prevents the truth layer from becoming a hidden monolith.

If a business later decides that stale inventory should still allow cart insertion but block checkout, that change belongs in eligibility rules, not in the definition of inventory truth.

A useful boundary is:

Truth describes the commercial facts.
Eligibility decides what those facts allow.

Action thresholds should differ

Not every action requires the same quality of truth.

Discovery may require only identity, visibility, media, and basic category information. Comparison may require price and comparable attributes. Policy quotation requires policy coverage and source references. Checkout preparation requires fresh price, fresh inventory, and applicable policies. Delegated payment requires even more: valid checkout state, cart-snapshot integrity, payment authority, and possibly human confirmation.

The same product can therefore have different readiness levels for different actions.

type ActionTruthRequirement = {
  requestedAction: AgentCommerceDecisionAction;
  requiredFacts: Array<
    | "identity"
    | "price"
    | "inventory"
    | "policyCoverage"
    | "media"
    | "generatedClaims"
  >;
};

Example requirements:

const requirements: ActionTruthRequirement[] = [
  {
    requestedAction: "discover",
    requiredFacts: ["identity", "media"]
  },
  {
    requestedAction: "compare",
    requiredFacts: ["identity", "price"]
  },
  {
    requestedAction: "quote_policy",
    requiredFacts: ["policyCoverage"]
  },
  {
    requestedAction: "prepare_checkout",
    requiredFacts: ["price", "inventory", "policyCoverage"]
  }
];

For the backpack example, the resulting matrix might be:

discover          allowed
compare           allowed
quote_policy      blocked: return policy missing
prepare_checkout  blocked: inventory stale, return policy missing
delegate_payment  blocked: checkout not ready; payment not attempted

This is more useful than marking the product as generally available or unavailable.

Agent-facing systems need to know what kind of action is safe. Operators need to know which missing facts block which commercial capabilities.

Derived facts need provenance

Some product facts are direct values. Others are derived.

Direct fact:

Price is €129.

Derived fact:

Product is visible to agents.

The second statement depends on rules. It might depend on catalog status, product category, merchant settings, policy completeness, feed publication status, generated claim review, and regional restrictions.

Derived facts should include provenance: a record of which source facts and rules produced the value.

type DerivedFact<T> = {
  value: T;
  derivedFrom: string[];
  computedAt: string;
  ruleRef: string;
  provenance: {
    sourceRefs: string[];
    freshness: "fresh" | "stale" | "unknown";
    inheritedBlockers: string[];
  };
};

For example:

type AgentVisibilityFact = DerivedFact<{
  visible: boolean;
  reason?: string;
}>;

A derived visibility fact might look like this:

const visibility: AgentVisibilityFact = {
  value: {
    visible: true
  },
  derivedFrom: [
    "catalog_status",
    "media_status",
    "merchant_agent_visibility_setting"
  ],
  computedAt: "2025-10-18T09:10:00Z",
  ruleRef: "agent_visibility:current",
  provenance: {
    sourceRefs: ["catalog:BAG-TRAVEL-42", "media:BAG-TRAVEL-42"],
    freshness: "fresh",
    inheritedBlockers: []
  }
};

This makes the result explainable rather than mysterious.

If the product disappears from the agent feed, the platform can inspect the rule and its inputs. It does not need to search through route handlers, frontend logic, feed jobs, and protocol adapters to discover where the decision was made.

Derived facts without provenance become another form of hidden state. If a derived fact depends on an upstream refusal, that refusal should remain visible rather than disappearing inside a new computed value.

Truth references and hashes support change detection

Agent-facing systems need to know when commercial truth changes.

A product may have been published to a feed yesterday. Since then, the price may have changed, inventory may have gone stale, or a policy source may have been updated.

A truth reference gives the platform a stable point to compare against:

type TruthRef = {
  productId: string;
  ref: string;
  generatedAt: string;
};

Hashes can help detect changes within specific scopes:

type TruthHash = {
  productId: string;
  scope: "identity" | "price" | "inventory" | "policy" | "media" | "full";
  hash: string;
  generatedAt: string;
};

A hash is a compact fingerprint of normalized content. It can show that the content changed, but it cannot explain whether that change matters commercially.

The canonical truth builder should calculate that hash from the normalized truth it owns. A caller-supplied hash may be verified, but it should not be accepted as the identity of a different set of facts.

The domain still needs to decide whether the change matters.

type TruthChangeSummary = {
  productId: string;
  changedScopes: Array<"identity" | "price" | "inventory" | "policy" | "media">;
  requiresFeedRepublish: boolean;
  requiresCheckoutRevalidation: boolean;
  requiresMerchantReview: boolean;
};

For example:

Price hash changed:
- requires feed republish
- requires checkout revalidation for open sessions

Media hash changed:
- may require feed republish
- does not require checkout revalidation

Policy hash changed:
- requires policy quotation revalidation
- may block checkout if policy coverage becomes incomplete

The hash detects change. The domain decides impact.

This separation matters because not every change is equal.

The same idea applies when source material becomes a claim or policy quotation. If that claim relies on a source, it should carry the source reference or hash, so a changed source can make it stale.

Agent-facing feeds should publish selected truth

A product feed for agents should not be a raw export of the catalog.

It should publish selected commercial truth and projected decision state.

A feed item might look like this:

type AgentCommerceProductRecord = {
  id: string;
  title: string;
  description: string;
  price: {
    amount: number;
    currency: string;
    lastVerifiedAt: string;
  };
  availability: {
    status: "in_stock" | "low_stock" | "out_of_stock" | "unknown";
    lastVerifiedAt?: string;
  };
  policySummary: {
    returnPolicyKnown: boolean;
    shippingPolicyKnown: boolean;
    warrantyPolicyKnown: boolean;
  };
  actions: {
    discoverable: boolean;
    comparable: boolean;
    checkoutEligible: boolean;
  };
  decision?: {
    envelopeSchemaVersion: string;
    ruleSetRef: string;
    ruleSetHash: string;
    decisionHash: string;
    inputDependencyHash: string;
    resultHash: string;
    authenticator: {
      kind: "digital_signature";
      algorithm: "ed25519";
      format: "detached";
      keyId: string;
      verificationKeyRef: string;
      protectedHash: string;
      value: string;
      verifiable: true;
    };
    requestedAction: AgentCommerceDecisionAction;
    status:
      | "allowed"
      | "blocked"
      | "requires_revalidation"
      | "requires_review"
      | "requires_confirmation";
    reasonCodes: string[];
    validUntil: string | null;
    staleAfter: string | null;
    nextSafeActions: Array<{ action: string; reasonCode: string }>;
  };
  truthRef: string;
  publishedAt: string;
};

This structure does not expose every internal field. It exposes the parts of commercial truth and decision state that are safe and useful by downstream systems.

The feed does not need to expose every field from the full envelope. Its decision projection should preserve the envelope schema, content-addressed rule-set identity, decisionHash, inputDependencyHash, resultHash, authenticator, and freshness horizon. The protected canonical envelope retains the declared feed surface, and the trusted feed boundary verifies that surface before projection. A downstream system can then verify which decision it received and determine when the projection should expire without relying on duplicated surface metadata.

That distinction keeps the architecture cleaner:

Catalog stores product data.
Commercial truth qualifies product data.
Eligibility and authority decide action meaning.
The decision envelope carries the result.
Feed publication projects selected fields.

If the feed is generated directly from the catalog, it can easily overstate what the platform knows. If the feed is generated from eligibility decisions alone, it can hide useful context.

Publishing selected commercial truth alongside a decision projection gives agents enough information without turning the feed into a second internal database or a second decision engine.

Tombstones make feed removals explicit

Feeds usually focus on current products, but removed products matter too.

If an agent saw a product yesterday and the product disappears today, absence is ambiguous. The product may have been deleted, temporarily unpublished, replaced by another SKU, blocked because of policy issues, or merged into a variant group.

A tombstone is a small feed record that explicitly says a previously published product was removed and why.

type ProductFeedTombstone = {
  productId: string;
  previousTruthRef: string;
  reason:
    | "deleted"
    | "unpublished"
    | "blocked"
    | "merged"
    | "replaced";
  replacementProductId?: string;
  removedAt: string;
};

This is useful for cached agent contexts.

If an external system still has a cached product reference, the platform can communicate that the product should no longer be used and why.

For example:

Product BAG-TRAVEL-42 was removed from the agent feed because checkout policy coverage became incomplete.

That is much safer than silently removing the item and relying on the external system to infer meaning from absence.

The important point is not to create a large feed-management subsystem. The important point is that the published feed should explain meaningful removals with the same commercial meaning the platform uses internally.

Commercial truth should create operator tasks

A commercial truth layer should serve both agents and operators.

When facts are stale, missing, or conflicting, the system should produce actionable remediation work.

For example:

type CommercialTruthIssue = {
  productId: string;
  scope: "price" | "inventory" | "policy" | "media" | "generatedClaims";
  severity: "info" | "warning" | "blocker";
  issue: string;
  impact: string;
  nextAction: string;
};

For the backpack example, the system might produce:

Issue:
Inventory freshness is stale.

Impact:
Product can remain discoverable, but checkout preparation is blocked.

Next action:
Revalidate inventory from the warehouse source.

and:

Issue:
Return-policy coverage is missing for the Travel Bags category.

Impact:
Agents should not quote return terms, and checkout preparation remains blocked.

Next action:
Attach or approve a return policy for the category.

This is more useful than a generic validation failure.

The operator needs to know which commercial capability is affected. The agent needs to know which action is blocked. The platform needs to record why.

A good commercial truth system connects all three.

Truth issue → Action impact → Operator task → Feed or eligibility recovery

AI-generated content cannot become truth automatically

Commercial truth also matters when AI is used to generate storefront content.

A model may generate product descriptions, category copy, landing-page sections, benefit claims, warranty statements, shipping summaries, or promotional language. Some of that content may be useful. None of it should automatically become commercial truth.

Generated content needs review boundaries.

A generated sentence may depend on commercial truth, but it is not itself commercial truth. It becomes projectable only after the platform can connect it back to approved sources and the surface where it will be used.

type GeneratedClaimAxisStatus = "passed" | "failed" | "not_evaluated";

type GeneratedClaimAxis = {
  status: GeneratedClaimAxisStatus;
  blockerCodes: string[];
};

type GeneratedCommerceClaimSummary = {
  claimId: string;
  claimType: "product" | "policy" | "shipping" | "warranty" | "promotion";
  status:
    | "allowed"
    | "requires_review"
    | "refused_here"
    | "inherited_refusal"
    | "stale"
    | "out_of_scope"
    | "absent";
  sourceRefs: string[];
  allowedUses: string[];
  axes: Record<
    "source" | "freshness" | "scope" | "surface" | "use" | "payload" | "taint",
    GeneratedClaimAxis
  >;
  inheritedRefusalCount: number;
  approvedValueHash?: string | null;
  claimTextHash?: string | null;
  publishBlocked: boolean;
};

For example, a generated description for the travel backpack might include:

Includes lifetime warranty and free international returns.

If the warranty source does not support that claim, and the return policy is missing for the category, the claim should not be published as agent-quotable truth.

The model generated text. It did not create authority.

That is an important distinction.

AI-generated commerce content should be treated as a draft until it can be projected from approved sources for a specific use and surface.

Commercial truth is input, not the final answer

Commercial truth should not try to answer every commerce question by itself.

It is the fact layer the decision spine consumes.

After the platform knows which facts are source-backed and fresh enough to rely on, it still has to evaluate policy coverage, action eligibility, actor authority, checkout state, payment authority, generated-claim status, and next safe actions. Those results should travel together in one decision envelope, with the scope and evidence references needed for feeds, tools, checkout, admin, and support to project the same meaning.

For example, the Travel Backpack can have a fresh price and still be blocked for delegated payment because inventory is stale and return-policy coverage is missing. A feed should not convert the fresh price into checkout readiness. A tool adapter should not treat in_stock as a complete answer. Checkout should not repair missing commercial facts because a payment artifact exists.

Commercial truth supplies the facts. The decision envelope carries the commerce answer.

Practical tests for the truth layer

Commercial truth should be tested with a small number of business scenarios, with field validation used to keep each result precise.

Useful scenarios include:

Product has fresh price, fresh inventory, and complete policy coverage.
Product has fresh price but stale inventory.
Product has fresh inventory but missing return policy.
Product has conflicting policy sources.
Product has generated claims pending review.
Product changed price after feed publication.
Product was removed after an agent feed was published.
Product has different policy coverage by region.

Each scenario should test both truth output and downstream impact.

type TruthScenarioExpectation = {
  truthStatus: "verified" | "incomplete" | "stale" | "conflicting";
  discoverable: boolean;
  comparable: boolean;
  policyQuotable: boolean;
  checkoutEligible: boolean;
  requiresFeedRepublish: boolean;
  operatorWorkItems: number;
};

For example:

Scenario:
Fresh price, stale inventory, missing return policy.

Expected:
discoverable = true
comparable = true
policyQuotable = false
checkoutEligible = false
requiresFeedRepublish = true
operatorWorkItems = 2

The point is to test the behavior that matters to agents and operators: whether the product facts lead to the right commercial decision.

Common failure modes

A commercial truth layer exists to prevent specific failure modes.

1. Raw catalog data leaks into agent feeds

If the feed is generated directly from catalog rows, stale or incomplete values may be exposed as if they were trustworthy.

2. Different surfaces compute truth differently

The storefront, feed publisher, protocol adapter, and admin UI may each calculate availability or visibility using different rules.

3. Stale facts block too much or too little

Without fact-level freshness, the system may block the entire product because one low-risk field is stale, or allow checkout even though a high-risk field is stale.

4. Derived facts become unexplained flags

A field like agentVisible is useful only if the platform can explain why it is true or false.

5. Feed removals become ambiguous

If deleted or blocked products simply disappear, external systems cannot distinguish removal from temporary absence.

6. Generated content becomes commercial authority

AI-generated copy may contain unsupported product, policy, shipping, warranty, or promotion claims unless grounding and review are explicit.

7. Operator tasks are disconnected from business impact

A validation error that says “policy missing” is less useful than an operational task explaining which agent action is blocked and how to fix it.

The main tradeoff

Commercial truth adds complexity.

It introduces more explicit facts, more source tracking, more scenario tests, and more ownership decisions. A small storefront may not need this layer. A simple e-commerce site can often rely on catalog data, page rendering, and checkout validation.

Agent-ready commerce changes the threshold.

Once external systems can discover products, compare options, quote terms, prepare checkout, or act within delegated authority, raw product data becomes too weak as the interface.

The platform needs a stronger answer to the question:

What are we willing to let software believe and act on?

That is the purpose of commercial truth.

It is not a replacement for checkout validation, payment authority, or policy enforcement. It is the factual foundation those layers depend on.

Design principles

A practical commercial truth layer should follow a few principles.

1. Separate presentation from truth

A product page is not a machine contract. It is a human-facing projection of commerce state.

2. Track sources for important facts

Prices, inventory, policies, generated claims, and availability decisions should be traceable to their sources.

3. Model freshness per fact group

Price, inventory, policy, media, and generated content do not carry the same risk. They should not share one generic freshness flag.

4. Keep truth separate from eligibility

Truth describes what is known. Eligibility decides which actions are allowed.

5. Preserve provenance for derived facts

Fields such as agentVisible, eligibleForCheckoutStart, or policyQuotable should be explainable.

6. Use hashes for change detection

Hashes can detect that something changed. Domain rules should decide whether the change affects feeds, checkout, review, or operator tasks.

7. Publish selected truth to feeds

Agent-facing feeds should not dump raw catalog records. They should expose a stable, safe subset of commercial truth.

8. Represent removals explicitly

Tombstones help external systems understand why a product is no longer available in a feed.

9. Connect truth issues to operator tasks

Missing or stale facts should produce actionable remediation work, not only validation errors.

10. Treat generated content as draft until grounded

AI-generated commerce claims should not become authoritative without source grounding or review.

The practical shift

Agent-ready commerce starts with facts, but not every product fact is ready for agent use.

A raw catalog record can render a storefront. It cannot always support recommendation, comparison, policy quotation, checkout preparation, or delegated payment.

The missing layer is commercial truth: a source-backed, freshness-aware view of what the platform currently knows about a product and how reliable that knowledge is.

Commercial truth does not decide every action. It provides the factual foundation for later decisions.

Catalog data says what the product is.
Commercial truth says what the platform can currently rely on.
Eligibility decides what actions are allowed.

That separation becomes important as commerce platforms expose more agent-facing surfaces. Product pages remain useful for humans, but agents need structured facts with provenance, freshness, and clear action impact.

Next in the series

Part 3 will move from facts to decisions:

Agent-Ready Commerce, Part 3: Why “Available” Is Not Enough for AI Agents

That article will examine action eligibility: why product availability is too broad, how different agent actions require different decision rules, and how eligibility connects commercial truth to safe commerce behavior.

About the author

Written by Dimitrios S. Sfyris, Founder & Software Architect at AspectSoft.

AspectSoft designs and develops custom software platforms, e-commerce systems, SaaS infrastructure, integrations, analytics tools, and practical digital products.

You can also follow the AspectSoft LinkedIn page for updates on software platforms, commerce systems, AI tooling, and developer-focused products.

Agent-Ready Commerce, Part 1: Building a Platform for the AI Era

Dimitrios S. Sfyris — Sat, 27 Jun 2026 20:54:42 +0000

AI agents are starting to change the assumptions behind commerce software.

For a long time, e-commerce platforms were designed around human interpretation. A product page could combine structured data, marketing copy, policy fragments, trust signals, pricing, availability indicators, and checkout calls to action. A human buyer could read those elements together and decide what they meant.

That model does not transfer cleanly to agentic commerce.

When an AI agent interacts with a commerce system, ambiguity becomes a system-design problem. The agent should not need to infer whether a product can be recommended, whether inventory is fresh, whether a policy applies, whether checkout is allowed, or whether payment authority exists. Those decisions need to be represented explicitly by the platform.

This article is the first in a technical series about designing an agent-ready commerce platform. The focus is not on adding a chatbot to an e-commerce UI. The focus is on the lower-level architecture required when external agents, tools, and protocols need to interact with commerce workflows safely.

The platform boundary is changing

Traditional e-commerce platforms expose experiences primarily through pages and user-driven flows:

Product page → Cart → Checkout → Payment → Order

That flow assumes a human is driving the process. The platform presents information, the user interprets it, and the user decides what to do next.

Agentic commerce introduces a different interaction model. A system may need to answer questions such as:

Which products are discoverable by agents?
Which product facts are fresh enough to use?
Which policies apply to a specific product, region, or checkout context?
Which actions are allowed for a product?
Is checkout preparation allowed?
Is delegated payment allowed?
Does the action require human confirmation?
What evidence supports the decision?
What should happen if an agent retries the same command?

These are not only API design questions. They are domain modeling questions.

A more useful mental model for agent-ready commerce is:

Facts → Eligibility → Authority → State transition → Evidence → Audit

This model is less familiar than the page-based e-commerce flow, but it captures the main architectural shift. A commerce platform that interacts with agents must expose more than products and endpoints. It must expose the conditions under which commercial actions are valid.

Product data is not the same as commercial truth

A common first step is to expose a structured product feed. That is necessary, but incomplete.

A basic product record might look like this:

type Product = {
  id: string;
  name: string;
  price: number;
  currency: string;
  inStock: boolean;
};

This structure is useful for rendering a storefront or indexing a catalog. It is not enough for an agent deciding whether a product can be recommended, compared, added to cart, or used in a checkout flow.

The missing layer is commercial truth: the platform’s current, source-backed understanding of the product as a commercial object.

For example:

type ProductTruthSummary = {
  productId: string;
  priceFreshness: "fresh" | "stale" | "unknown";
  inventoryFreshness: "fresh" | "stale" | "unknown";
  policyCoverage: "complete" | "partial" | "missing";
  sourceStatus: "verified" | "changed" | "unverified";
  agentVisible: boolean;
};

This structure separates raw product data from the confidence and completeness required to use that data in agent-facing decisions.

A product may exist in the catalog but still be unsuitable for agent discovery. A product may be discoverable but not checkout-ready. A product may be checkout-ready but not eligible for delegated payment. A product may have a fresh price but stale inventory. A product may have valid inventory but missing return-policy coverage.

A human can often work around those inconsistencies. An agent should not have to.

This is the first major design principle in agent-ready commerce:

Do not ask agents to infer commercial truth from presentation surfaces.
Expose commercial truth directly.

Availability is too broad

Many e-commerce systems use product availability as a broad gate. The product is active, in stock, and therefore available.

That approach breaks down once agent actions become more specific.

Consider a simple implementation:

function canCheckout(product: Product) {
  return product.active && product.inStock;
}

This function answers a narrow question, but the platform usually needs to answer several different questions:

Can the product appear in an agent-visible catalog?
Can the product be compared against alternatives?
Can the agent quote policies for it?
Can the agent add it to a cart?
Can the agent prepare checkout?
Can the agent delegate payment?
Does the product require human confirmation?

These actions do not have the same risk profile. Treating them as one availability decision makes the model too coarse.

A more explicit action model is easier to reason about:

type AgentCommerceDecisionAction =
  | "discover"
  | "compare"
  | "quote_policy"
  | "add_to_cart"
  | "prepare_checkout"
  | "delegate_payment"
  | "complete_checkout"
  | "show_generated_claim"
  | "explain";

Each action can then produce its own decision:

type ActionEligibilityDecision = {
  productId: string;
  requestedAction: AgentCommerceDecisionAction;
  allowed: boolean;
  blockers: Array<{
    code: string;
    severity: "info" | "warning" | "blocker";
    message: string;
    nextAction: string;
  }>;
};

The important part is not the exact TypeScript shape. The important part is the separation of concerns.

A product can be safe to discover but unsafe to purchase. It can be safe to compare but unsafe to quote because policy facts are incomplete. It can be safe to prepare checkout but unsafe for delegated payment because payment authority has not been established.

This creates a more reliable interface for agents and a more useful operational model for merchants.

Instead of returning a generic rejection, the platform can return a reason:

Product is discoverable but checkout is blocked because inventory freshness is stale.

That kind of response is useful to both the agent and the operator. The agent knows not to proceed. The operator knows what to fix.

Policies need to become structured facts

Policy text is another area where human-first assumptions leak into the system.

A human can read a returns page and interpret whether a product is likely covered. An agent should not rely on free-text interpretation when quoting commercial terms.

Policy data needs to be connected to products, categories, markets, and actions.

A simplified policy fact might look like this:

type PolicyFact = {
  policyType: "returns" | "shipping" | "warranty" | "cancellation";
  appliesTo: {
    productIds?: string[];
    categoryIds?: string[];
    region?: string;
  };
  status: "known" | "missing" | "stale" | "conflicting";
  summary: string;
  sourceRef: string;
  lastVerifiedAt: string;
};

This gives the platform a way to distinguish between several conditions that would otherwise collapse into vague policy text:

The policy is known and applies to the product.
The policy exists but is stale.
The policy exists but does not apply in the buyer’s region.
Two policy sources conflict.
The product is missing required policy coverage.
The policy can be shown to a human but should not be quoted by an agent.

The distinction matters because an incorrect policy claim is not just a technical bug. It can become a customer-support issue, a trust issue, or a compliance issue.

Agent-ready systems therefore need to treat policy facts as part of the commerce domain, not as static content attached to the storefront.

Protocol adapters should stay thin

Agent-commerce platforms are likely to interact with multiple external protocol surfaces. Some protocols focus on product discovery. Some focus on tool use. Some focus on checkout or payment authority. Some may be specific to a marketplace, assistant, payment provider, or agent runtime.

A common architecture mistake is to let each protocol adapter make its own business decisions.

For example:

ACP interaction decides checkout eligibility
UCP adapter decides cart or checkout capability
MCP tool decides product visibility
AP2-related payment adapter decides mandate validity
Admin UI calculates its own issue status
Feed publisher calculates another version of availability

That structure may work temporarily, but it tends to create contradictions. One surface says the product is available. Another says it is blocked. The admin UI shows a third status. The feed publisher uses a fourth rule.

A safer architecture keeps adapters thin:

External protocol
        ↓
Protocol adapter
        ↓
Internal domain command/query
        ↓
Canonical decision path
        ↓
Protocol-specific response

The adapter translates between external protocol shape and internal domain shape. It should not own the core decision.

This separation is especially important while agent-commerce protocols are still evolving. If the domain model is independent from the protocol adapter, new protocol versions can be supported without rewriting the business rules.

The platform can then maintain one internal answer to questions such as:

Is the product discoverable?
Is checkout allowed?
Is delegated payment allowed?
Which blockers apply?
Which evidence supports the result?

ACP- and UCP-style commerce surfaces, MCP tools, AP2-related payment flows, feeds, storefronts, admin tools, and support views can expose that answer in different formats, but the decision remains owned by the domain.

Using one shared decision envelope for every surface

A decision-centered architecture only works if each surface can ask the platform for the same commercial answer.

If the adapter shortcut is one line:

product.active && inventory.status == "in_stock" && price.amount < 150

and the domain path requires three calls across unrelated modules, the system is inviting local decision logic to reappear. Under pressure, a feed, checkout flow, or tool adapter will eventually choose the path that is easiest to reach.

That is why agent-ready commerce needs more than the right boxes on a diagram. It needs an ergonomic decision path.

The platform should make this the boring path:

Build or reuse the commerce decision.
Return one shared decision envelope.
Project that envelope to the surface.

A decision envelope is a structured record of the platform's answer for one requested action. It keeps the related decisions together without collapsing them into one boolean:

eligibility
actor authority
checkout state
payment authority
generated-claim projection state
freshness and hash-pinned evidence references
next safe actions

At the contract boundary, the envelope can also carry decisionId, contractVersion, envelopeSchemaVersion, content-addressed rule-set identity, inputDependencyHash, resultHash, decisionHash, and an explicit authenticator.

The three hashes answer different questions:

inputDependencyHash: Which action, subject, actor, rules, evidence, and freshness inputs were evaluated?
resultHash: Which eligibility, authority, checkout, payment, claim, and next-action results were produced?
decisionHash: Which contract and schema bind those inputs and results together?

The protected input boundary should include the decision identity, requested surface and action, actor, subject, inputs, evidence, freshness dependencies, and rule-set identity. A surface may omit internal detail, but an externally verifiable projection should preserve the rule-set identity, hashes, authenticator, and freshness information needed to validate the result.

At an external projection boundary, the platform should capture any externally supplied or persisted envelope once into a detached, deeply frozen, JSON-compatible snapshot. Hash recomputation, authenticator verification, request binding, freshness evaluation, and projection should all consume that same captured value rather than re-read caller-controlled state. The platform should then confirm the target surface, reject stale allowed output on action-bearing external surfaces, and compare the protected requested action, subject, and actor with the live request.

Administrative and support projections may expose stale context for diagnosis, but they do not authorize execution. Before changing state, the platform should compare the decision's protected dependency hashes with current authoritative checkout, mandate, product, policy, price, inventory, payment, authority, claim, or evidence snapshots as applicable. A missing, changed, or expired dependency requires a fresh decision even when the envelope is still signed and within its original freshness window.

A feed can project one part of the envelope. A tool adapter can project another. Checkout can use the same envelope before mutation. Admin and support can show the same blocker codes and remediation path.

The important point is not that every surface shows the same fields. It is that every surface starts from the same commercial meaning, and that meaning stays tied to the use and evidence that produced it.

Checkout is a lifecycle, not a single action

Checkout is often presented as a button in the UI, but backend systems already know that checkout is a lifecycle. Agentic commerce makes that lifecycle more explicit.

A checkout session may need to pass through several states:

type AgentCommerceCheckoutLifecycleState =
  | "created"
  | "empty"
  | "requires_address"
  | "requires_shipping_option"
  | "requires_payment"
  | "requires_revalidation"
  | "blocked"
  | "payment_authorized"
  | "order_submitted"
  | "completed"
  | "declined"
  | "cancelled"
  | "expired"
  | "failed";

Each transition has conditions. A draft session should not become validated unless prices, inventory, and policy constraints have been checked. A session should not move into payment authorization unless the required authority exists. A completed session should usually be terminal. A repeated command should be handled safely.

The checkout should keep one current state and append a meaningful event when an accepted or blocked command changes the lifecycle or must remain reconstructable:

type EvidenceRef = {
  type: string;
  id: string;
  hash: string;
  hashAlgorithm: "sha256";
};

type CheckoutEvent = {
  checkoutId: string;
  operation: "create" | "read" | "update" | "confirm" | "complete" | "cancel" | "expire";
  previousState: AgentCommerceCheckoutLifecycleState;
  nextState: AgentCommerceCheckoutLifecycleState;
  accepted: boolean;
  actorType: "buyer" | "agent" | "operator" | "system";
  reasonCodes: string[];
  evidenceRefs: EvidenceRef[];
  occurredAt: string;
};

This does not require a separate database row for every internal validation. The current checkout record answers, “Where is checkout now?” The event history answers, “Which meaningful command changed or failed to change it, and why?”

The key design point is that agents should not be allowed to move commerce state arbitrarily. They should submit commands, and the platform should decide whether the requested transition is valid.

That decision depends on facts, eligibility, authority, and current state.

This makes checkout a good example of the broader architecture pattern:

Agent request → Command validation → Authority check → Current-state decision → Meaningful checkout event

Payment authority is a separate domain

Payment authority is one of the areas where vague models become dangerous.

In a human-driven checkout flow, the user typically sees the final cart and authorizes payment directly. In an agent-driven or agent-assisted flow, the platform must be more precise about what authority the agent has.

A boolean such as paymentAllowed is not expressive enough.

A delegated payment flow needs boundaries:

type AgentCommerceMandateRecord = {
  mandateId: string;
  buyerId: string;
  actorId: string;
  merchantId: string;
  checkoutId: string;
  cartSnapshotHash: string;
  maxAmount: number;
  currency: string;
  allowedActions: Array<"delegate_payment" | "complete_checkout">;
  allowedProductIds: string[];
  expiresAt: string;
  confirmationStatus: "not_required" | "required" | "confirmed";
  consumedAt?: string;
  revokedAt?: string;
};

A payment attempt can then be evaluated against the mandate:

type AgentCommercePaymentAuthorityVerdict = {
  allowed: boolean;
  amountWithinLimit: boolean;
  currencyMatches: boolean;
  merchantMatches: boolean;
  productScopeMatches: boolean;
  cartSnapshotMatches: boolean;
  mandateNotExpired: boolean;
  mandateNotRevoked: boolean;
  humanConfirmationSatisfied: boolean;
};

This separates payment execution from payment authority.

Payment execution asks, “Can the provider process this request?”

Payment authority asks, “Is this exact request still inside the authority the buyer granted?”

A provider can accept a technically valid payment request even when the commerce platform should not have sent it. That is why the authority decision must come first.

Idempotency becomes part of the safety model

Agent-driven systems must assume retries.

A request can time out after the backend has already completed the operation. An agent may retry a command because it did not receive the previous response. A payment command may be submitted twice. A checkout mutation may be replayed.

Idempotency means that retrying the same command does not perform the commercial action twice. It is therefore not just an implementation detail. It is part of the safety model.

A command needs identity:

type AgentCommand = {
  commandId: string;
  idempotencyKey: string;
  actorId: string;
  actorType: "human" | "agent" | "system";
  action: string;
  payloadHash: string;
  requestedAt: string;
};

The platform should be able to answer:

Has this command been seen before?
Was the payload identical?
Did the previous execution complete?
Is it safe to return the previous result?
Is this a replay attempt?
Is the same idempotency key being reused with a different payload?

This is especially important for payment and checkout operations, where duplicate execution can create real financial or operational damage.

The operator view should not mirror the internal architecture

As the backend becomes more explicit, the internal state can become large: product facts, policy facts, feed health, checkout and mandate events, payment authority, protocol responses, transaction correlation, attribution records, privacy rules, and audit timelines.

Exposing all of that directly to operators usually creates a poor admin experience.

Operators need decisions and tasks, not a raw map of internal subsystems.

A task-oriented view is usually more useful:

type MerchantTask = {
  owner: "catalog" | "policy" | "checkout" | "payment" | "operations";
  status: "healthy" | "needs_attention" | "blocked";
  issue: string;
  nextAction: string;
  fixImpact: string;
  sampleRefs: string[];
};

The task model translates system state into operational work:

Inventory freshness is stale for 12 agent-visible products.
Checkout is blocked until the catalog source is revalidated.

That is more useful than exposing five different internal panels and expecting the operator to infer the business impact.

The admin UI should not leak the architecture unless the user needs to debug at that level. The default view should help the operator answer three questions:

What is wrong?
Why does it matter?
What should be fixed next?

AI-generated commerce content needs authority boundaries

AI-assisted store creation introduces a related problem.

Generating storefront content is not difficult. Generating commercially safe storefront content is harder.

A model can produce product descriptions, category pages, policy summaries, promotional text, and landing-page copy very quickly. But generated content should not automatically become commercial truth.

The platform needs to distinguish between generated content and approved claims.

In this series, projection means a surface-specific view of commercial truth. It is not a new source of truth. For generated text, projection is stricter: the platform returns whether a claim may be used for a specific surface and use, with its source and freshness state still attached.

For example:

type AxisStatus = "passed" | "failed" | "not_evaluated";
type GeneratedClaimStatus =
  | "allowed"
  | "requires_review"
  | "refused_here"
  | "inherited_refusal"
  | "stale"
  | "out_of_scope"
  | "absent";

type GeneratedCommerceClaimSummary = {
  claimId: string;
  claimType: "product" | "policy" | "shipping" | "warranty" | "promotion";
  status: GeneratedClaimStatus;
  sourceRefs: string[];
  axes: Record<
    "source" | "freshness" | "scope" | "surface" | "use" | "payload" | "taint",
    AxisStatus
  >;
  inheritedRefusalCount: number;
  approvedValueHash?: string | null;
  claimTextHash?: string | null;
  publishBlocked: boolean;
};

This prevents a generated storefront from publishing unsupported statements such as:

inaccurate warranty claims
unapproved discounts
unsupported shipping promises
unavailable product references
policy claims not backed by a source
external links that have not been reviewed

The same principle appears again: AI output should not become business authority automatically. It should be projected through explicit rules that keep source, freshness, scope, surface, and use attached to the text.

Maintainability is not separate from agent readiness

Agent-ready commerce adds concepts to the platform. Without clear ownership, those concepts can easily become scattered across routes, clients, UI components, protocol adapters, and helper files.

That creates a maintainability problem with commercial consequences.

If product eligibility is calculated in one API route, policy coverage in a frontend component, checkout validation in a payment adapter, and agent visibility in a feed publisher, the system will eventually contradict itself.

The architecture needs clear ownership:

Commercial truth owns selected source-backed facts.
Policy owns applicability and quotability.
Eligibility owns action-specific validity.
One checkout application owner coordinates human and agent checkout behavior.
One delegated-authority owner coordinates mandate scope, confirmation, consumption, and revocation.
Payment owns execution and provider interaction.
Order owns order state.
A transaction coordinator correlates checkout, mandate, payment, and order events without copying their state.
Protocol adapters translate decisions.
UI surfaces render decisions.

The deployment and folder structure can vary. The important rule is that reusable commercial meaning has one owner and every external surface projects from that meaning.

That keeps the core small. The durable business rails are these:

Product facts
Policy facts
Checkout state
Payment limits

Evidence, audit, attribution, protocol projection, and operator views should attach to those rails instead of becoming separate rule systems that every surface has to reimplement.

With a shared decision envelope, an adapter developer should not need to know every product, policy, checkout, and payment rule before building a feed or tool response. The developer asks the platform for the decision, then projects that decision to the required surface.

This is especially important in an AI-assisted development environment. Code is becoming easier to generate, which means duplication and architectural drift can happen faster. The limiting factor is not only implementation speed. It is the ability to keep the system coherent as it grows.

What this series will cover

This first article defines the main architectural problem: agent-ready commerce requires platforms to expose facts, eligibility, authority, state transitions, evidence, and operational tasks explicitly.

The rest of the series will go deeper into each area:

Agent-Ready Commerce, Part 1: Building a Platform for the AI Era
Agent-Ready Commerce, Part 2: From Product Pages to Commercial Truth
Agent-Ready Commerce, Part 3: Why “Available” Is Not Enough for AI Agents
Agent-Ready Commerce, Part 4: Making Policies Machine-Readable
Agent-Ready Commerce, Part 5: Keeping ACP, UCP, MCP, and AP2 Adapters Thin
Agent-Ready Commerce, Part 6: Checkout Is a State Machine, Not a Form
Agent-Ready Commerce, Part 7: Delegated Payment Needs More Than a Token
Agent-Ready Commerce, Part 8: Generated Claims Need Review, Evidence, and Expiry
Agent-Ready Commerce, Part 9: Evidence and Audit Are Part of the Product
Agent-Ready Commerce, Part 10: The Reference Architecture

The series is not intended to define a universal standard. Protocols, payment models, and agent runtimes are still evolving. The goal is to document the system boundaries that become important once AI agents are treated as real commerce actors rather than as chat interfaces attached to existing flows.

The core idea

Agent-ready commerce is not primarily a UI problem. It is not solved by adding an assistant to a storefront, and it is not solved by exposing a product feed alone.

The deeper challenge is architectural.

Commerce platforms need to make hidden assumptions explicit: product truth, policy coverage, action eligibility, checkout state, payment authority, mutation safety, generated-claim projection, provenance state, and operator remediation.

Human users can tolerate ambiguity in ways that agents should not be expected to. If agents are going to discover products, compare options, prepare checkout, or act within delegated authority, the platform needs to expose the rules of commerce in a form that software can evaluate.

That is the core idea behind agent-ready commerce:

Pages are for human interpretation.
Decision envelopes are for machine-safe action.

The rest of this series will examine how those decision envelopes and supporting layers work in practice.

About the author

Written by Dimitrios S. Sfyris, Founder & Software Architect at AspectSoft.

AspectSoft designs and develops custom software platforms, e-commerce systems, SaaS infrastructure, integrations, analytics tools, and practical digital products.

You can also follow the AspectSoft LinkedIn page for updates on software platforms, commerce systems, AI tooling, and developer-focused products.