[Change] § 4.1 — Freeze a version's offered terms; changes create version n+1 and a revised entry #64

What kind of change?

Change a normative requirement (MUST / SHOULD / MAY)

Which section?

4 — Proposal

Current text

§ 4.1:

| `version` | Integer | derived | Monotonically increasing revision number |

`action: proposed \| countered \| accepted \| declined \| withdrawn`

Proposed text

Our lifecycle PR carries this text.

§ 4.1, version row:

Monotonically increasing revision number, starting at 1, held by the seller. Each version is a snapshot of the proposal's offered terms (§ 4.1.3). A version is frozen at the earliest of: the proposal's status leaving draft; a negotiation_history[] or assent[] entry naming it; a counterparty receiving it in any representation (§ 2.1). The offered terms of a frozen version MUST NOT change; a change to them creates version n+1. The values § 4.1.3 lists as not offered terms change without a new version.

New § 4.1.3, Offered terms and versions, condensed:

Offered terms are every value the seller writes, including the set of line_item_ids the version carries. status, the lifecycle, recorded, and asserted fields, the advisory fields of § 4.2, pricing[].min_rate, the buyer's writes, and values derived from them are not offered terms. They MAY change without a new version.

Each change to the offered terms of a frozen version MUST create version n+1. The seller MUST append exactly one negotiation_history[] entry with that version, actor: seller, and paths[] naming each changed field. Its action is published, or granted or countered when the change answers a buyer's request.

A line item in a frozen version MUST NOT be removed; it leaves by its status. A seller MUST keep every version that a negotiation_history[] or assent[] entry names retrievable by (proposal_id, version) while the proposal is retrievable.

The HistoryEntry.action values become published, requested, granted, countered, declined, and withdrawn, and fields_changed[] becomes paths[].

Why

§ 3 lets a seller revise a published proposal in place. Nothing says whether that makes a new version or an entry (#45, item 1). Both parties can hold "version 2" over different bytes.

#24 proposes a counter per revision. This says which changes count: every value the seller writes, prose included, because #45's billable term was prose. hold stays out, as @EvgenyAndroid showed and @premesh agreed, so a queue move creates no version.

Knock-on effects

The Summary Representation carries version (our shared types PR). An assent[] entry binds the version it names (our signing PR). Proposal in iab-agentic-primitives needs the same revision rule.

Would this break an implementation already built to this draft?

Yes — breaking

You are commenting as

Other — IAB Tech Lab member (Postindustria).

Before you submit

• I have read CONTRIBUTING.md and agree my contribution may be published under this repository's licence.
• This contains no confidential or commercially sensitive information.

Details and examples: Proposal versioning: full rationale and examples

Revised 2026-11-03: Rewritten to match our lifecycle PR. A revision logs published, not revised; fields_changed[] becomes paths[]; hold and advisory fields aren't offered terms.

Analyzed and generated with the help of Claude, fully reviewed by me.