@flaks/onerecord 0.1.2 → 0.3.0

package/CHANGELOG.md

@@ -4,11 +4,330 @@ All notable changes are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/), versioning follows
 [SemVer](https://semver.org/) per the policy in `MIGRATING.md`.
 
-## [0.1.1] - 2026-04-27 (install fix + open-sourcing pass)
-
-First public release. v0.1.0 was tagged but unconsumable via git URL
-(see "Critical install fix" below); v0.1.1 is the first version Tracks
-B and C should pin to.
+## [0.3.0] - 2026-05-17
+
+FWB-equivalence Path A: 10 new classes, schema rewrites for the core FWB
+classes, full IATA 3.2.0 conformance for the covered class set with documented
+deviations and 3.2.1-forward extensions. See `MIGRATING.md` for per-breaking-
+change migration guidance.
+
+### Added
+
+- **`Company`** class — concrete `:Organization` subtype; retires the abstract
+  `Organization` class. `Party.partyDetails` and all Organization-range fields
+  now point to `Company`.
+- **`WaybillLineItem`** class — FWB rate/charge line item.
+- **`OtherCharge`** class — FWB OCI/other-charge block.
+- **`CustomsInformation`** class — FWB customs information block.
+- **`Insurance`** class — FWB insurance details.
+- **`LineItemPackage`** class — FWB package-level line item.
+- **`ULD`** class — unit load device reference.
+- **`CO2Emissions`** class — carbon emissions per spec §D6.
+- **`RegulatedEntity`** class — security regulated entity (shipper/handler).
+- **`SecurityDeclaration`** class — security declaration per spec §8.
+- **Shared value sub-schemas**: `ValueSchema`, `CurrencyValueSchema`,
+  `DimensionsSchema` — used by all NEW value-typed properties in v0.3.0.
+- **FWB properties** on `Waybill`: `shipment`, `involvedParties`,
+  `waybillLineItems`, `otherCharges`, `carrierDeclarationPlace`,
+  `departureLocation`, `arrivalLocation`, `houseWaybills`, `masterWaybill`,
+  `billingDetails` (IRI ref only; `:BillingDetails` class not modelled — deviation #16).
+  `accountingInformation` — deprecated upstream (owl:deprecated true in
+  3.2-rc2 ~2861) — **deviation #15**.
+- **FWB properties** on `Shipment`: `pieces`, `waybill`, `involvedParties`,
+  `customsInformation`, `insurance`, `securityDeclarations` (accepted as
+  optional 3.2.1-forward extension — deviation #12).
+- **FWB properties** on `Piece`: `ofShipment`, `containedPieces`,
+  `securityDeclarations` (3.2.0-conformant via Piece restriction ~8260).
+- `CARGO_ONTOLOGY_VERSION` bumped from `'3.2'` to `'3.2.0'` (exact endorsed
+  version string). Legacy alias `'3.2'` remains accepted by
+  `assertOntologyVersion` and `checkServerInformation`.
+
+### Changed
+
+- **`Organization` class retired** — replaced by `Company`
+  (`:Company rdfs:subClassOf :Organization`; the only concrete org type shipped).
+  `Party.partyDetails` widened to accept `IRI | {@id}` (Person or Company).
+  `NI` added as accepted `Party.partyRole` value.
+- **`Waybill`**: dropped `shipmentInformation` (renamed to `shipment`);
+  dropped `totalGrossWeight` (the field already exists on `Shipment` — use that).
+- **`Shipment`**: dropped `pieceCount`, `totalVolume`, `containedPieces`
+  (renamed to `pieces`), `shipper`, `consignee` (moved to `involvedParties`).
+- **`waybillType` enum**: `DIRECT` added.
+- **`waybillPrefix`**: now accepts `[A-Z0-9]{1,3}` (editorial policy relaxation
+  — NOT a spec pattern; the ontology has only `xsd:string maxLength 3`).
+- **`waybillNumber`**: now accepts `[A-Z0-9]+` per 3.2-rc2 ontology pattern.
+- **`AccountNumber`**: `accountNumber`/`issuedBy`/`accountType` renamed to
+  `accountNumberType`/`textualValue`; `issuedBy` removed (wrong domain — belongs
+  to `:SecurityDeclaration`, not `:AccountNumber`).
+- **`CARGO_ONTOLOGY_VERSION`**: `'3.2'` → `'3.2.0'`. `assertOntologyVersion`
+  and `checkServerInformation` now use an exact-alias accepted set
+  (`'3.2'` ≡ `'3.2.0'`, `'3.2.1'` rejected — NOT prefix-tolerant).
+- **`FIELD_TYPES` map**: stale v0.2 entries removed (`Waybill.shipmentInformation`,
+  `Shipment.containedPieces`, `Shipment.consignee`, `Shipment.shipper`,
+  `Organization.address`, `Organization.contactPersons`,
+  `AccountNumber.issuedBy`); ~40 new entries added for v0.3.0 classes.
+- **Domain constraints** (`domain-constraints.ts`): stale v0.2 constraints
+  on `Waybill.shipmentInformation` and `Shipment.containedPieces` removed.
+  No spec basis post-Path-A; the corrected cross-node check
+  (Waybill↔Shipment inverse-property consistency) is deferred.
+
+### BREAKING CHANGES
+
+Consumers upgrading from v0.2.x must audit the following:
+
+1. **`Organization` class removed** — import `Company` instead. Any code
+   referencing `OrganizationSchema`, `OrganizationCodec`, `serializeOrganization`,
+   or `deserializeOrganization` will break.
+2. **`Waybill.shipmentInformation` removed** — use `Waybill.shipment`.
+3. **`Waybill.totalGrossWeight` removed** — field moved to `Shipment`.
+4. **`Shipment.pieceCount` removed** — no direct replacement (compute from `pieces.length`).
+5. **`Shipment.totalVolume` removed** — no direct replacement in v0.3.0.
+6. **`Shipment.containedPieces` removed** — use `Shipment.pieces`.
+7. **`Shipment.shipper` / `Shipment.consignee` removed** — use `Shipment.involvedParties`
+   filtered by `partyRole`.
+8. **`waybillType` enum**: `DIRECT` is now a valid value — exhaustive switches
+   must handle it.
+9. **`waybillPrefix`**: now accepts alphanumeric `[A-Z0-9]{1,3}` — do not
+   assume numeric-only downstream.
+10. **`waybillNumber`**: now accepts `[A-Z0-9]+` — do not assume numeric-only.
+11. **`AccountNumber` fields renamed**: `accountNumber` → `textualValue`,
+    `accountType` → `accountNumberType`; `issuedBy` removed.
+12. **`Party.partyDetails`** widened (additive for accept — a bare IRI still
+    validates; see MIGRATING.md for detail).
+13. **`CARGO_ONTOLOGY_VERSION`** changed from `'3.2'` to `'3.2.0'`. Any code
+    doing `=== '3.2'` on the constant will need updating.
+14. **`assertOntologyVersion('3.2.1')`** now throws (previously any mismatch
+    with `'3.2'` would throw; now the exact-alias set `{'3.2.0','3.2'}` is
+    accepted and everything else including `'3.2.1'` is rejected).
+15. **`domain_constraint_violation`** for `Waybill.shipmentInformation` /
+    `Shipment.containedPieces` no longer fires (those fields no longer exist).
+16. **`Party.partyRole`**: `'NI'` (also-notify, AWB box 7) is now an accepted
+    value — exhaustive `switch` statements over `partyRole` must handle it
+    (same migration class as `waybillType` `DIRECT`).
+
+### Spec deviations
+
+- **#12 (reworded)**: `Shipment.securityDeclarations` is a documented
+  3.2.1-forward extension — see `docs/spec-deviations.md#12`.
+- **#14 (new)**: Legacy `{unit,value}` shape on 3 pre-existing fields.
+- **#15 (new)**: `Waybill.accountingInformation` is `owl:deprecated` in 3.2-rc2.
+- **#16 (new)**: `BillingDetails` class not modelled in v0.3.0.
+
+## [0.2.0] - 2026-04-28
+
+First publicly verifiable release. Closes 3 of 5 v0.1.x spec
+deviations PLUS pulls forward 5 of the 6 newly-identified deviations
+(#6 partially, #7, #8, #9, #10) for net 7 of 11 deviations CLOSED
+or PARTIAL in v0.2.0. Adds 4 new opt-in `ParseError.kind` values
+that fire only through the dispatch path; default per-class
+deserializers stay v0.1.x-permissive (no breaking changes).
+
+### Added
+
+- **`acceptBookingOptionViaRequest(opt)`** — spec §5.4-correct booking
+  transition that returns the intermediate `BookingOptionRequest` state
+  instead of jumping straight to `Booking`. Closes deviation #1
+  partially (forwarder→carrier hop only; carrier-side acceptance flow
+  is v0.3 work).
+- **Graph-walk dispatcher** — opt-in cross-node integrity validation
+  via `createMapper({ graphWalk: true })` or
+  `onerecord.dispatch.deserialize.<Class>`. Emits all four reserved
+  ParseError kinds: `duplicate_id_in_graph`, `missing_id`,
+  `wrong_type_for_endpoint`, `missing_type`. Default per-class
+  deserializers unchanged. Closes deviation #2 for JSON-LD structural
+  integrity (domain-semantic checks remain deviation #6, deferred).
+- **`walkGraph` helper** at `src/safety/walk-graph.ts` — visitor-pattern
+  recursive walker shared by `preValidate` and `dispatchGraphWalk`.
+  Single traversal, no double-walk overhead.
+- **`FIELD_TYPES` map** at `src/dispatch/field-types.ts` — covers all
+  32 cargo classes with field-to-expected-type mappings; polymorphic
+  fields marked `'*'`.
+- **Property-based round-trip tests** for the 7 remaining Ring 1+2
+  classes (Shipment, Piece, Address, Person, Organization, Party,
+  AccountNumber). Joins the existing Waybill test. Total runtime ~1.6s.
+- **`PARSE_ERROR_KINDS.length === 26` lock test** — fails CI on
+  unexpected union drift. Bumped from 22 in v0.1.x with four new
+  kinds: `blank_node_forbidden` (#8), `iri_not_canonical` (#9),
+  `context_order_violation` (#10), `domain_constraint_violation` (#6).
+- **Contract test harness + 6 contract tests** at `test/contract/`
+  against the OLF-hosted reference NE:ONE Server. All 6 plan-specified
+  topics shipped: Waybill, Shipment, Piece, booking-flow, operations
+  (JSON-Patch via applyChange), notification (Subscription LO + endpoint
+  smoke). Includes Keycloak auth + defensive RDF-strict-mode
+  wire-format adapter (envelope shape, ObjectProperty `@id` wrapping,
+  xsd-typed literals, `@graph` response unwrap). Excluded from the
+  default `bun run test`; run via `bun run test:contract` after
+  starting the local NE:ONE stack.
+- **Skeleton bundled docker-compose** at `test/contract/docker-compose.neone.yml`
+  for in-memory-mode local stack. Realm config not bundled (OLF License
+  §4 review pending); fetch instructions in CONTRIBUTING.md.
+  Headless CI integration (release.yml NE:ONE gate, nightly job)
+  deferred to v0.3 — bundling realm + per-run reset is multi-day work.
+- **`MAINTENANCE.md`** — release playbook + signing key info + npm
+  credential policy + bus-factor note (R8 mitigation).
+- **Six newly-identified spec deviations (#6–#11)** documented:
+  - **#6 — domain-semantic cross-node validation**: PARTIAL closure
+    (root-level cardinality enforced via `domain_constraint_violation`;
+    Waybill.shipmentInformation REQUIRED, Shipment.containedPieces
+    REQUIRED ≥1). AWB consistency, total-pieces sums, and reference
+    resolvability still v0.3 work.
+  - **#7 — IRI dereferenceability**: CLOSED via opt-in helper
+    `dereferenceIri(iri, opts)` async utility. Library doesn't wire
+    into deserializers (would force network I/O); consumers call
+    when they need it.
+  - **#8 — blank-node rejection**: CLOSED. Pre-Zod check at
+    `src/safety/blank-node.ts` emits `blank_node_forbidden` for
+    `_:b0`-style `@id` values per spec §3.2.
+  - **#9 — IRI canonicalization**: CLOSED via opt-in dispatch
+    (`iri_not_canonical` for uppercase scheme/host or default port
+    per RFC 3987 + spec §3.2).
+  - **#10 — `@context` array-order**: CLOSED via opt-in dispatch
+    (`context_order_violation` when array @context's last element
+    is not in the allowlist; per JSON-LD 1.1 §3.7 last item is the
+    effective context).
+- **Spec deviation #11** — STATE_DIAGRAM source-state keys do not
+  match `BookingOption.optionStatus` enum; documents intentional
+  hardcode in the four `*BookingOption` transitions. Resolution
+  requires IATA §5.4 reconciliation; v0.3.
+
+### Changed
+
+- **FSU code fixture regenerated** with a real `sha256:` blob hash
+  (`f5f483a5...`) sourced from upstream IATA-Cargo via the new sibling
+  [`tjo099/onerecord-xlsx-tools`](https://github.com/tjo099/onerecord-xlsx-tools)
+  tool. v0.1.x's hand-pinned 26 codes diverged from the upstream working
+  draft by 6 codes in each direction. Per Phase 0 verification the
+  upstream set is adopted: removes CLR, FOO, FWB, OFD, RCM, RCV; adds
+  DOC, DPU, FIW, FOW, OCI, OSI. `FSU_EVENT_CODES` const updated to
+  match. Closes deviation #4.
+- Spec rev-2 wording corrected: the reference NE:ONE Server is hosted
+  by the **Open Logistics Foundation Working Group on Digital Air
+  Cargo**, not IATA-Cargo. OLF License v1.3 — unrestricted CI use
+  confirmed (R6 closure).
+
+### Deprecated
+
+- **`acceptBookingOption`** — marked `@deprecated`; removal in v0.3
+  unless IATA §5.4 reconciliation restores the §5.2 shortcut. Migrate
+  to `acceptBookingOptionViaRequest`.
+
+### Removed
+
+- **`xlsx` devDep** moved to the sibling
+  [`tjo099/onerecord-xlsx-tools`](https://github.com/tjo099/onerecord-xlsx-tools)
+  repo. Closes the two high-severity advisories on the main library's
+  surface (Prototype Pollution + ReDoS). `bun audit` now shows 2
+  remaining vitest-transitive moderates only.
+- `scripts/convert-iata-xlsx.ts` — moved to the sibling repo.
+
+### Fixed
+
+- v0.1.2 GitHub Release page backfilled (the auto-create step in
+  `release.yml` failed on the v0.1.2 publish before commit `d8acc2c`
+  added the explicit `git fetch --tags --force` step).
+- Re-enabled four `it.skip` placeholder tests in `test/deserialize-errors/`:
+  `forbidden_state_transition`, `operation_field_not_allowed`,
+  `prototype_pollution_attempt` + `invalid_pointer` (via `applyChange`),
+  and `change_partial_failure`. Plus the four graph-walk-emitted kinds
+  (`duplicate_id_in_graph`, `missing_id`, `missing_type`,
+  `wrong_type_for_endpoint`) — formerly placeholders, now real
+  assertions against `dispatchGraphWalk`.
+
+### Plan deviations (v0.2.0 work that diverged from the original plan)
+
+- **Phase 2 Task 2.1 reinterpreted (Path B)** — the plan proposed
+  reading `canTransition` source state from `opt.optionStatus`. The
+  Phase 2 readiness scan showed this would break every BookingOption
+  transition because STATE_DIAGRAM source-state keys don't align with
+  the schema's optionStatus enum. The hardcode is intentional pending
+  v0.3 reconciliation; deviation #11 documents the underlying issue.
+- **Phase 5 fully scoped** — all 6 contract test topics implemented
+  in v0.2.0 (Waybill, Shipment, Piece, booking-flow, operations,
+  notification). CI integration (release.yml NE:ONE gate, nightly
+  contract job) still deferred to v0.3 — bundling realm config +
+  per-run stack reset for headless runners is multi-day work; the
+  skeleton compose file is the v0.3 starting point. Run manually
+  before tagging via `bun run test:contract`.
+- **Phase 1 Task 1.5 location** — sibling repo cloned to
+  `F:/dev/onerecord-xlsx-tools/` (matching the maintainer's
+  `F:/dev/` convention) instead of the plan's `/tmp/`.
+- **Plan-vs-API drifts surfaced and corrected** — the plan's verbatim
+  test code for Tasks 1.2/1.3/1.4 used an obsolete Operations API
+  (`o`/`s`/`v` shorthand vs. real `op`/`path`/`value`;
+  `Change.operations` vs. real `Change.hasOperation`; `add`/`replace`
+  enum vs. real `ADD`/`DELETE`). Test bodies rewritten to match real
+  schemas. Plan's `findContainingClass` always-returns-undefined logic
+  bug fixed in `dispatchGraphWalk` (depth-1 wrong-type checks now fire).
+- **Test paths normalized** — `test/api-surface/` and `test/dispatch/`
+  in the plan's File Structure table actually live at
+  `test/unit/api-surface/` and replaced existing placeholders in
+  `test/deserialize-errors/`.
+
+## [0.1.2] - 2026-04-27 (npm publish — supersedes 0.1.1)
+
+`@flaks/onerecord` is now published to the public npm registry as a
+scoped public package. **This is the first version Tracks B + C
+should adopt.** v0.1.1's `prepare`-script approach to the git-URL
+install issue does not work on Bun (default "trusted dependencies"
+model blocks lifecycle scripts); v0.1.2 ships pre-built `dist/` in
+the registry tarball, making `bun add @flaks/onerecord` work
+zero-config across all package managers.
+
+### Install
+
+```bash
+npm install @flaks/onerecord
+# or
+bun add @flaks/onerecord
+# or
+pnpm add @flaks/onerecord
+```
+
+### Why npm publish moved earlier than the v0.2.0 plan
+
+The original v0.2.0 roadmap listed npm publish as one of several
+ecosystem-hardening items (alongside NE:ONE contract test, SBOM/SLSA,
+bundle-size assertion). After v0.1.0 + v0.1.1 git-URL distribution
+attempts proved unworkable for Bun consumers, npm publish moved into
+v0.1.2 as a hotfix. The remaining v0.2.0 items still apply.
+
+### Release pipeline fix
+
+- Add `fetch-tags: true` to the `actions/checkout` step in
+  `release.yml`. Without this, the runner's git tag object is
+  materialized as a lightweight ref (commit only, no signature
+  metadata), and `git tag -v` fails with `cannot verify a non-tag
+  object of type commit`. This is what caused the v0.1.1 release.yml
+  run to fail.
+
+### Package metadata
+
+- Added `keywords`, `homepage`, `bugs`, `author` fields to
+  `package.json` for npm registry display and search indexing.
+- Changed `publishConfig.access` from `restricted` to `public`.
+
+### Note on v0.1.1
+
+v0.1.1 remains tagged in git but is documented broken — `prepare`
+script alone does not work for Bun consumers. Do not pin to v0.1.1.
+v0.1.2 is the version Tracks B + C should adopt.
+
+## [0.1.1] - 2026-04-27 (install fix attempt — superseded by 0.1.2)
+
+**Tagged but functionally broken on Bun consumers.** This release
+attempted to fix the v0.1.0 git-URL install breakage by adding a
+`prepare` lifecycle script. The fix worked for npm consumers (which
+default-trust `prepare` for git installs) but failed on Bun, which
+default-blocks postinstall scripts via its "trusted dependencies"
+model. See `[0.1.2]` above for the actual fix (npm publish).
+
+The CHANGELOG content originally drafted under this version (open-
+sourcing pass items: GPG signing, governance scaffolding, public docs,
+public flip) shipped to `main` with this tag and is preserved on the
+v0.1.1 commit (`86dd181`). All of those items are also present in
+v0.1.2.
+
+Original v0.1.1 changelog content follows for historical reference:
 
 ### Critical install fix
 

package/MIGRATING.md

@@ -2,19 +2,205 @@
 
 This file documents one entry per minor release.
 
+## Migrating from v0.2.x to v0.3.0
+
+v0.3.0 is a **breaking release**. Review every item below before upgrading.
+
+### 1. `Organization` class retired → use `Company`
+
+`Organization` is removed. Import and use `Company` instead. Update all
+references to `OrganizationSchema`, `OrganizationCodec`, `serializeOrganization`,
+`deserializeOrganization`.
+
+```typescript
+// Before (v0.2.x)
+import { OrganizationCodec } from '@flaks/onerecord'
+// After (v0.3.0)
+import { CompanyCodec } from '@flaks/onerecord'
+```
+
+### 2. `Waybill.shipmentInformation` → `Waybill.shipment`
+
+```typescript
+// Before
+waybill.shipmentInformation = 'https://example/sh'
+// After
+waybill.shipment = 'https://example/sh'
+```
+
+### 3. `Shipment.containedPieces` → `Shipment.pieces`
+
+```typescript
+// Before
+shipment.containedPieces = ['https://example/p1']
+// After
+shipment.pieces = ['https://example/p1']
+```
+
+### 4. `Shipment.shipper` / `Shipment.consignee` → `Shipment.involvedParties`
+
+The `shipper` and `consignee` top-level fields on `Shipment` are removed.
+Use `Shipment.involvedParties` filtered by `partyRole`:
+
+```typescript
+const shipper = shipment.involvedParties?.find(p => p.partyRole === 'SHP')
+const consignee = shipment.involvedParties?.find(p => p.partyRole === 'CNE')
+```
+
+### 5. `Shipment.pieceCount` / `Shipment.totalVolume` removed
+
+No direct replacement in v0.3.0. Compute `pieceCount` from `pieces.length`
+if needed. `totalVolume` is deferred (no spec-correct successor in scope).
+
+### 6. `AccountNumber` field renames
+
+| v0.2.x field | v0.3.0 field | Notes |
+|---|---|---|
+| `accountNumber` | `textualValue` | String value of the account number |
+| `accountType` | `accountNumberType` | IRI ref to code value |
+| `issuedBy` | removed | Wrong domain; belongs to `:SecurityDeclaration` |
+
+### 7. `Party.partyDetails` widening — additive for accept
+
+`partyDetails` now accepts `Person | Company` (not `Person | Organization`).
+**This is additive for deserializing**: a bare IRI still validates. Code
+that checks `partyDetails['@type'] === 'Organization'` must be updated to
+`'Company'`. The new `NI` value is accepted for `partyRole`.
+
+### 8. `waybillNumber` and `waybillPrefix` regex relaxation
+
+- **`waybillNumber`**: now accepts `[A-Z0-9]+` **per the 3.2-rc2 ontology
+  pattern**. Do not assume numeric-only (`[0-9]+`) downstream.
+- **`waybillPrefix`**: now accepts up to 3 alphanumeric characters (`[A-Z0-9]{1,3}`)
+  as the library's **EDITORIAL policy** — the ontology only specifies
+  `xsd:string maxLength 3` with no character-class restriction. Do not assume
+  numeric-only downstream.
+
+### 9. `CARGO_ONTOLOGY_VERSION` constant changed
+
+The exported constant changed from `'3.2'` to `'3.2.0'`:
+
+```typescript
+// Before: CARGO_ONTOLOGY_VERSION === '3.2'
+// After:  CARGO_ONTOLOGY_VERSION === '3.2.0'
+```
+
+Any code doing `=== '3.2'` on the constant must be updated to `=== '3.2.0'`
+(or use `CARGO_ONTOLOGY_VERSION` indirectly).
+
+### 10. `assertOntologyVersion` + `checkServerInformation` — exact-alias peer-compat policy
+
+Both functions now use an **exact-alias accepted set**: `{'3.2.0', '3.2'}`.
+
+- `assertOntologyVersion('3.2.0')` — does NOT throw (canonical pin)
+- `assertOntologyVersion('3.2')` — does NOT throw (legacy alias ≡ 3.2.0)
+- `assertOntologyVersion('3.2.1')` — THROWS `incompatible_ontology_version`
+- `assertOntologyVersion('4.0')` — THROWS `incompatible_ontology_version`
+
+The accepted set is **NOT** prefix-tolerant (`'3.2.1'` is master-only and
+intentionally rejected). `checkServerInformation` follows the same rule:
+a server advertising `cargoOntologyVersion: '3.2.1'` will return
+`compatible: false`.
+
+### 11. `waybillType` enum: `DIRECT` added
+
+If your code has an exhaustive `switch` on `waybillType`, add a `'DIRECT'`
+case. TypeScript will surface this at compile time.
+
+### 12. `domain_constraint_violation` for stale fields no longer fires
+
+If your code expected `domain_constraint_violation` for a Waybill missing
+`shipmentInformation` or a Shipment missing `containedPieces`, those errors
+no longer fire — those fields don't exist in v0.3.0. Update your error
+handling to match the new field names (`shipment`, `pieces`).
+
+---
+
+## Migrating from v0.1.x to v0.2.0
+
+v0.2.0 is **non-breaking at the call-site level** for v0.1.x consumers.
+Existing imports, codecs, and `createMapper({ ... })` calls work
+unchanged. The release adds opt-in surfaces and one deprecation.
+
+### What's new (additive — adopt if useful)
+
+- **Graph-walk dispatcher** for cross-node integrity validation:
+  ```typescript
+  // Option A — namespaced facade
+  import { onerecord } from '@flaks/onerecord'
+  const r = onerecord.dispatch.deserialize.Waybill(input)
+
+  // Option B — bound mapper
+  import { createMapper } from '@flaks/onerecord'
+  const m = createMapper({ graphWalk: true })
+  const r = m.deserializeWaybill(input)
+  ```
+  Both emit `duplicate_id_in_graph`, `missing_id`, `wrong_type_for_endpoint`,
+  `missing_type` for cross-node violations on direct children of the
+  root. Default per-class deserializers (`WaybillCodec.deserialize`,
+  `onerecord.deserialize.Waybill`) are unchanged — graph-walk is opt-in.
+
+- **`acceptBookingOptionViaRequest`** — spec §5.4-correct booking flow
+  that returns the `BookingOptionRequest` intermediate state instead
+  of jumping straight to `Booking`:
+  ```typescript
+  import { acceptBookingOptionViaRequest } from '@flaks/onerecord'
+  const result = acceptBookingOptionViaRequest(opt)
+  // result.value is BookingOptionRequest, not Booking
+  ```
+
+### Deprecations (warn now, remove in v0.3)
+
+- **`acceptBookingOption`** is `@deprecated`. Migrate to
+  `acceptBookingOptionViaRequest` and chain through your persistence
+  layer's BookingOptionRequest → Booking transition. Removal in v0.3
+  unless an IATA §5.4 spec amendment restores the §5.2 shortcut.
+  TypeScript will surface the deprecation; runtime behavior is unchanged
+  through v0.2.x.
+
+### FSU code list — 6 codes changed in each direction
+
+The `FSU_EVENT_CODES` const + `test/fixtures/iata/xfsu-status-codes.json`
+were regenerated from the upstream IATA-Cargo working draft. Net count
+unchanged at 26, but **6 codes were dropped and 6 were added**:
+
+- Removed: CLR, FOO, FWB, OFD, RCM, RCV
+- Added:   DOC, DPU, FIW, FOW, OCI, OSI
+
+If your application enumerates FSU codes directly via `FsuCode` or
+`FSU_EVENT_CODES.<KEY>`, switch to the new keys. Audit before updating;
+this is the only behavior change that may break consumer code.
+
+### Bun-style consumers using `ignoreScripts`
+
+If your consumer project sets `bun install --ignoreScripts` or equivalent,
+v0.2.0 is unaffected — the library has no `prepare`/`postinstall` scripts.
+The `xlsx` devDep (which carried two high-severity advisories) was
+extracted to the sibling [`tjo099/onerecord-xlsx-tools`](https://github.com/tjo099/onerecord-xlsx-tools)
+repo in v0.2.0. Your `bun audit` against `@flaks/onerecord` should now
+show 0 findings from `xlsx` — only 2 vitest-transitive moderates remain.
+
 ## Migrating to v0.1.0
 
 v0.1.0 is the first minor release. There is no prior version to migrate from.
 
-### Install
+### Install (current — v0.1.2 onwards)
 
 ```bash
-bun add git+https://github.com/tjo099/onerecord-mapper#v0.1.0
+npm install @flaks/onerecord
+# or
+bun add @flaks/onerecord
 ```
 
-Pin to a specific tag in production. A future v0.2.0 release will
-additionally publish to npm as the public scoped package
-`@flaks/onerecord`; installing via git URL works today.
+Pin a minor range in production (e.g. `"@flaks/onerecord": "^0.1.0"`).
+
+### Older install paths (historical)
+
+- `v0.1.0` shipped as a git-URL install only. Do not use — `dist/` was
+  not in the tag. See CHANGELOG for details.
+- `v0.1.1` attempted a `prepare`-script fix for git-URL installs.
+  Does not work on Bun's default "trusted dependencies" model. Skipped
+  in favor of v0.1.2 npm publish.
 
 ### Recommended import patterns