# v0.14.3 — Agent Action, Commerce Mandate, and Gateway Export Records

PEAC records what an external system reports happened when an agent
invokes an action, when a commerce mandate progresses through
authorization, capture, refund, settlement, or budget evaluation, and
when a payment gateway observes payment-submission, facilitator
timeout, or settlement-recovery events. Caller systems (agents,
harnesses, runtimes, payment gateways, facilitators, or downstream
reviewers) report what they observed; PEAC records that report through
a portable, signed interaction record that any party can verify
offline.

This release adds three new extension namespaces, three new schema
validators, three new normative profile specs, three new conformance
sections, three runnable examples, three operator recipes, and the
top-level `@peac/schema` barrel re-exports needed to consume each
profile through a single import path. No new public CLI verb. No new
publishable package. No wire format change.

## Highlights

- Three new `org.peacprotocol/*` extension namespaces:
  - `org.peacprotocol/agent-action` (6 `*-observed` type URIs)
  - `org.peacprotocol/commerce-mandate` (7 `*-observed` type URIs)
  - `org.peacprotocol/gateway-export` (8 `*-observed` type URIs)
- Three normative profile specs under `docs/specs/`.
- Conformance Sections 32 (`AGENT-ACT-001..010`), 33
  (`COMM-MAN-001..010`), and 34 (`GATE-EXP-001..010`).
- Three new cross-language parity corpus families bringing the total
  to 11 families.
- ACP mapper boundary fix (`packages/mappings-acp`) requiring
  `amount_minor: string` and explicit-finality semantics on
  delegated-payment observations.
- Three new generic-OSS-neutral runnable example packages with
  end-to-end `pnpm issue` + `pnpm verify` round-trips.
- Three new operator-facing verification recipes under
  `docs/SOLUTIONS/`.
- Pre-release dependency cleanup: protobufjs override pinned to the
  patched version through a private-example reachability path.

## New record surface: agent action

The `org.peacprotocol/agent-action` extension namespace records
observation of agent action events. Six receipt-type URIs cover the
major action-lifecycle event families:

```text
org.peacprotocol/agent-action-invoked-observed
org.peacprotocol/agent-action-delegated-observed
org.peacprotocol/agent-action-approved-observed
org.peacprotocol/agent-action-denied-observed
org.peacprotocol/agent-action-cancelled-observed
org.peacprotocol/agent-action-timed-out-observed
```

The `*-observed` suffix makes the observer scope explicit at the
record-type layer. PEAC records what the issuer reports happened.
Execution, scheduling, decision-making, and orchestration remain
upstream responsibilities. The validator emits stable error codes
under the `agent.action.*` namespace covering inline-content
rejection, opaque-reference grammar, required-field presence, event
kind, and timestamp formats.

## New record surface: commerce mandate

The `org.peacprotocol/commerce-mandate` extension namespace records
observation of commerce-lifecycle events scoped to a mandate. Seven
receipt-type URIs cover the major commerce event families:

```text
org.peacprotocol/commerce-mandate-observed
org.peacprotocol/commerce-authorization-observed
org.peacprotocol/commerce-capture-observed
org.peacprotocol/commerce-void-observed
org.peacprotocol/commerce-refund-observed
org.peacprotocol/commerce-settlement-observed
org.peacprotocol/commerce-budget-observed
```

Authorization, processing, settlement, mandate enforcement, finality
computation, budget evaluation, and rail validation remain upstream
responsibilities. The validator emits 16 stable error codes under the
`commerce.mandate.*` namespace. Money fields use a profile-local
non-negative-amount-minor refine wrapper over the shared
`AmountMinorStringSchema` (numeric, decimal, comma-formatted, empty,
or negative values reject). The single-canonical-money-field doctrine
holds: the validator rejects any `value_minor` or other
money-shaped key besides `amount_minor`. The
finality-synthesis boundary blocks `settlement_state` on any event
kind other than `commerce-settlement-observed`.

## New record surface: gateway export

The `org.peacprotocol/gateway-export` extension namespace records
payment-gateway observations spanning a 7-state settlement/recovery
model plus one facilitator-timeout trigger observation. Eight
receipt-type URIs cover the full surface:

```text
org.peacprotocol/gateway-payment-submitted-observed
org.peacprotocol/gateway-facilitator-timeout-observed
org.peacprotocol/gateway-settlement-unresolved-observed
org.peacprotocol/gateway-settlement-polling-observed
org.peacprotocol/gateway-settlement-confirmed-observed
org.peacprotocol/gateway-settlement-confirmed-late-observed
org.peacprotocol/gateway-settlement-failed-observed
org.peacprotocol/gateway-settlement-failed-orphaned-observed
```

Settlement, routing, on-chain verification, recovery policy, and
dispute resolution remain upstream responsibilities. The validator
emits 23 stable error codes under the `gateway.export.*` namespace
covering inline-payment-data rejection (19 forbidden top-level keys),
opaque-reference grammar, required-field presence, event kind,
amount-minor canonical form, optional EIP-3009 four-tuple references,
optional `valid_before_unix_seconds` (safe-integer-bounded),
timeout-profile enum (`datacenter` / `east_africa_3g` /
`west_africa_3g` / `custom`), polling-strategy enum, count and
millisecond bounds, UTF-8 byte limits via `TextEncoder`, and
`upstream_artifact_digest` (sha256-hex). Caller-reported labels carry
no PEAC inference about geography, network quality, or settlement
guarantees. A reviewer reading a `gateway-facilitator-timeout-observed`
record sees a discrete observable boundary signal that may precede
unresolved recovery; the record does not by itself claim that
recovery began.

## ACP mapper boundary fix

`packages/mappings-acp` now requires explicit-finality semantics for
delegated-payment observations used by the commerce-mandate profile.
The
`fromACPCheckoutSuccess` mapper now requires `amount_minor: string`
(replacing the prior `total_amount: number` field) and an explicit
`env` field. A new local `ACPMapperBoundaryError` class with 11
stable codes preserves source-of-error attribution at the mapper
layer. BigInt safe-integer guards run on every amount conversion. A
shared private `isValidHttpsResourceUri` helper applies across all
five ACP mapper paths (literal `https://`, non-empty hostname, reject
embedded credentials).

## Conformance and parity

Three new conformance sections add 30 requirement IDs total:

- Section 32 `AGENT-ACT-001..010` (agent-action validator contract)
- Section 33 `COMM-MAN-001..010` (commerce-mandate validator contract)
- Section 34 `GATE-EXP-001..010` (gateway-export validator contract)

Three new parity corpus families self-describe both wire-envelope
acceptance and extension-level expected error codes (matching the
v0.14.2 provisioning-lifecycle pattern):

- `specs/conformance/parity-corpus/agent-action/`
- `specs/conformance/parity-corpus/commerce-mandate/`
- `specs/conformance/parity-corpus/gateway-export/`

The cross-language parity floor now stands at 11 families.

## Examples and operator recipes

Three new runnable example packages, each with deterministic synthetic
fixtures and end-to-end `pnpm issue` + `pnpm verify` round-trips:

- [`examples/agent-action-records/`](../../examples/agent-action-records/)
  — 6 fixtures, one per agent-action event kind.
- [`examples/commerce-mandate-records/`](../../examples/commerce-mandate-records/)
  — 7 fixtures, one per commerce-lifecycle event kind.
- [`examples/gateway-export-records/`](../../examples/gateway-export-records/)
  — 8 fixtures covering 7 settlement/recovery states plus 1
  facilitator-timeout trigger observation.

Three new operator-facing recipes under
[`docs/SOLUTIONS/`](../SOLUTIONS/) walk through offline verification
of each profile's signed records.

## Repository hygiene

- `@peac/schema` top-level barrel adds 21 new exports (15 types + 6
  value exports) for the three new profile constants and validators,
  enabling single-import-path consumption from external packages.
- `tests/tooling/api-contract.test.ts` extension-key constants count
  bumped from 24 to 27 to track the three new observation surfaces.
- `apps/api/tests/report-format.test.ts` byte-stability test pinned
  to a fixed clock to remove a pre-existing 1ms timing race; no
  production report-format behavior change.
- `scripts/pack-install-smoke.sh` adds a profile-exports smoke that
  verifies the three new extension keys and validator functions
  through the packed `@peac/schema` tarball.
- `package.json` overrides: `protobufjs` pinned to exact `8.0.2`
  (closes 7 protobufjs Dependabot advisories across the
  `8.0.0..8.0.1` range); new defensive `@protobufjs/utf8: 1.1.1`
  override (closes `GHSA-q6x5-8v7m-xcrf` defensively against
  re-entry through another transitive path). Reachability is
  private-example-only
  via `@peac/example-telemetry-otel@0.0.0`; no published runtime
  package depends on protobufjs.

## Public surface

No new CLI command. No base Wire-format change. Existing schema
behavior is unchanged; the public schema surface is additive through
three extension validators and top-level `@peac/schema` exports. No
new publishable npm package. The 36-package publishable surface is
unchanged from v0.14.2.

## Compatibility

- Wire format: unchanged.
- Public API: additive only (new exports under `@peac/schema` for the
  three new profile constants and validators; new extension namespaces
  registered in `@peac/kernel` generated registries).
- Default observable behavior: unchanged for existing surfaces.

## Validation

`docs/releases/facts.json` records the canonical metric values for
this release.
