@flaks/onerecord 0.1.2

package/README.md

@@ -0,0 +1,253 @@
+# @flaks/onerecord
+
+Zero-dependency Zod-first TypeScript mapper for the IATA OneRecord cargo data model 3.2 and API spec 2.2.0.
+
+## What it is
+
+`@flaks/onerecord` provides round-trip-safe serialization and deserialization for
+32 OneRecord cargo data model classes. Each class ships with a Zod schema, an
+application-layer TypeScript type, a `JsonLd<T>` brand, `serialize` / `serializeStrict`
+/ `deserialize` functions, and a `Codec` bundle. A factory (`createMapper`) and a
+namespaced facade (`onerecord`) cover the two main consumption patterns. Safety
+primitives (depth, node, string, array, payload limits; prototype-pollution defense;
+IRI validation) run before Zod so that invalid JSON-LD graphs never reach schema
+evaluation. All 22 parse-error variants are typed as a discriminated union (`ParseError`)
+so callers handle every failure mode exhaustively.
+
+## Why use this library?
+
+Air cargo is migrating to OneRecord — IATA's JSON-LD-based replacement for
+EDIFACT / Cargo-IMP messaging. As of January 2026, roughly 8% of the
+industry has adopted; the standard is endorsed but the TypeScript tooling
+ecosystem is sparse. `@flaks/onerecord` fills that gap.
+
+Use this library if you're building cargo software that needs to:
+
+- **Accept** OneRecord JSON-LD from external endpoints with strict
+  validation (Zod schemas + cardinality + IRI + a pre-Zod safety pass).
+- **Emit** spec-compliant JSON-LD with stable round-trip semantics
+  (`serialize(deserialize(x)) == x` per spec §7.1).
+- **Refuse** malformed graphs early — depth bombs, prototype-pollution
+  attempts, empty arrays on the wire, circular references — before they
+  reach Zod or your downstream code.
+- **Type-check** every parse-failure path: `ParseError` is a 22-variant
+  discriminated union, so the compiler tells you when you've forgotten a
+  failure mode.
+
+Skip it if you want a generic JSON-LD or RDF toolkit; this is purpose-built
+for the IATA cargo ontology and the ONE Record API spec 2.2.0.
+
+## Status
+
+`v0.1.0` covers the 32 canonical cargo data model classes (Ring 1–5 plus
+the booking-flow classes) with full round-trip codecs, Zod schemas,
+snapshot tests, property-based round-trip tests, and pre-Zod safety
+primitives. The library is Apache-2.0 and ready for use within the v0.x
+stability policy described in [`MIGRATING.md`](MIGRATING.md).
+
+Spec compliance: cargo data model **3.2 (2025-07 endorsed standard)**, API
+spec **2.2.0**. A small number of deliberate divergences from canonical
+spec behavior are documented in
+[`docs/spec-deviations.md`](docs/spec-deviations.md); read that before
+adopting if your integration must match the spec verbatim.
+
+## Install
+
+```bash
+bun add git+https://github.com/tjo099/onerecord-mapper#v0.1.0
+```
+
+Pin to a specific tag for production use. Per `MIGRATING.md`, minor
+versions may introduce breaking changes documented in `CHANGELOG.md`;
+patch versions will not. A future v0.2.0 release will additionally
+publish to npm as the public scoped package `@flaks/onerecord`.
+
+## Usage
+
+### Round-trip with `WaybillCodec`
+
+```typescript
+import { WaybillCodec } from '@flaks/onerecord'
+
+// Deserialize raw JSON-LD from the wire
+const result = WaybillCodec.deserialize(rawJsonLd)
+if (result.ok) {
+  const waybill = result.value          // typed as Waybill (application object)
+  const jsonLd = WaybillCodec.serialize(waybill)  // back to JsonLd<Waybill>
+} else {
+  console.error(formatError(result.error))
+}
+```
+
+### `createMapper` with custom limits
+
+```typescript
+import { createMapper } from '@flaks/onerecord'
+
+const mapper = createMapper({
+  limits: { maxDepth: 12, maxNodes: 500, maxPayloadBytes: 512_000 },
+  iriStrategy: 'strict',
+  allowedSchemes: ['https'],
+})
+
+const result = mapper.deserialize.Waybill(rawJsonLd)
+const jsonLd  = mapper.serialize.Waybill(waybill)
+```
+
+### `onerecord` namespaced facade
+
+```typescript
+import { onerecord, formatError } from '@flaks/onerecord'
+
+// One-off operations, no factory state
+const result = onerecord.deserialize.Shipment(rawJsonLd)
+if (!result.ok) {
+  throw new Error(formatError(result.error))
+}
+const jsonLd = onerecord.serialize.Piece(piece)
+```
+
+## API overview
+
+### Per-class exports
+
+Each of the 32 classes exposes:
+
+| Export | Description |
+|---|---|
+| `<Class>Schema` | Zod schema for the application object |
+| `<Class>Codec` | `{ serialize, serializeStrict, deserialize }` bundle |
+| `serialize<Class>(obj)` | Returns `JsonLd<T>` |
+| `deserialize<Class>(raw)` | Returns `Result<T, ParseError>` |
+
+### Factory
+
+```typescript
+createMapper(opts: {
+  limits?: Partial<SafetyLimits>
+  iriStrategy?: 'strict' | 'lenient'
+  allowedSchemes?: string[]
+}): BoundMapper
+```
+
+Returns a mapper with bound `serialize.<Class>` and `deserialize.<Class>` methods
+using deep-frozen options set at creation time.
+
+### Facade
+
+```typescript
+onerecord.deserialize.<Class>(raw): Result<T, ParseError>
+onerecord.serialize.<Class>(obj): JsonLd<T>
+```
+
+No bound state; suitable for one-off operations and tree-shake-friendly imports.
+
+### Errors
+
+- `ParseError` — 22-variant discriminated union (`kind` field); covers
+  `zod_validation`, `cardinality_violation`, `invalid_iri`, `depth_limit_exceeded`,
+  `prototype_pollution_attempt`, `invalid_pointer`, and 16 more
+- `SerializationError` — `code: 'invalid_application_object' | 'iri_construction_failed'`
+- `formatError(e: ParseError): string` — human-readable message
+- `redactError(e: ParseError): ParseError` — strips PII from error payloads before logging
+
+### Booking state machine
+
+```typescript
+import { STATE_DIAGRAM, canTransition } from '@flaks/onerecord'
+
+canTransition(from, to)            // boolean predicate
+acceptBookingRequest(req)          // typed transition → BookingOption
+acceptBookingOption(opt)           // typed transition → Booking
+rejectBookingOption(opt)           // typed transition → BookingOption
+revokeBookingOption(opt)           // typed transition → BookingOption
+```
+
+### Operations (JSON-Patch per spec §6.5)
+
+```typescript
+import { applyChange, validateOperation, asJsonPointer } from '@flaks/onerecord'
+
+applyChange(codec, obj, change)         // returns Result<T, ParseError>
+validateOperation(op, allowedFields)    // validates op.s against allowed field list
+asJsonPointer(path)                     // typed JsonPointer helper
+```
+
+### FSU codes
+
+```typescript
+import { FSU_EVENT_CODES } from '@flaks/onerecord'
+// Record<string, FsuEventCode> — 26-code map per IATA XFSU spec
+```
+
+### Safety primitives
+
+```typescript
+import { DEFAULT_SAFETY_LIMITS, mergeLimits } from '@flaks/onerecord'
+// DEFAULT_SAFETY_LIMITS: SafetyLimits (depth, nodes, strings, arrays, payloadBytes)
+// mergeLimits(base, overrides): SafetyLimits
+```
+
+### IRI utilities
+
+```typescript
+import { safeIri, validateIri, defaultIriStrategy } from '@flaks/onerecord'
+// safeIri()             — Zod helper; lifts IRI failures into kind: 'invalid_iri'
+// validateIri(s)        — Result<SafeIri, ParseError>
+// defaultIriStrategy    — IriStrategy with https-only scheme enforcement
+```
+
+## Architecture notes
+
+- **Zero runtime dependencies** other than Zod (peer).
+- **Round-trip safety**: serialize(deserialize(x)) == x per spec §7.1 tolerance.
+  Deserialized application objects carry no `@context` or `@type` noise; `serialize`
+  reconstructs the canonical JSON-LD envelope.
+- **Pre-Zod safety pass**: before any schema evaluation, `preValidate` enforces
+  depth, node count, string length, array length, and payload-byte limits; detects
+  prototype-pollution keys (`__proto__`, `constructor`, `prototype`); and unwinds
+  JS-level circular references. Zod never sees a malformed graph.
+- **Empty arrays rejected** at any depth as `cardinality_violation`. The spec
+  mandates omitting a field rather than sending `[]`; this is enforced pre-Zod.
+- **Null-prototype output**: all deserialized graphs are built on `Object.create(null)`
+  objects. Consumer code cannot accidentally read or pollute `Object.prototype`
+  through a deserialized value.
+- **Branded types**: `SafeIri` (validated IRI string) and `JsonLd<T>` (serialized
+  graph) are distinct branded types. TypeScript prevents passing a raw string where
+  a `SafeIri` is required, and passing an application object where `JsonLd<T>` is
+  expected.
+
+## Tree-shaking
+
+For maximum bundle size optimization, import from the `/codecs` subpath:
+
+```typescript
+import { WaybillCodec } from '@flaks/onerecord/codecs'
+import { ShipmentCodec } from '@flaks/onerecord/codecs'
+```
+
+Type-only imports (zero runtime cost):
+
+```typescript
+import type { Waybill, ParseError } from '@flaks/onerecord/types'
+```
+
+## Version pins
+
+| Spec | Version |
+|---|---|
+| Cargo data model | 3.2 (2025-07 endorsed standard) |
+| API spec | 2.2.0 |
+
+## Development
+
+```bash
+bun install
+bun run test       # 518 passing + 10 skipped = 528 total
+bun run lint       # Biome
+bun run typecheck  # tsc --noEmit
+```
+
+## License
+
+[Apache-2.0](LICENSE)

package/SECURITY.md

@@ -0,0 +1,54 @@
+# Security Policy
+
+## Supported versions
+
+| Version | Supported |
+|---|---|
+| 0.1.x | Yes |
+| < 0.1 | No |
+
+## Reporting a vulnerability
+
+Please report security issues privately via [GitHub Private Vulnerability
+Reporting](https://github.com/tjo099/onerecord-mapper/security/advisories/new).
+Prefix the title with `[onerecord-mapper]`. Do not open a public issue for
+security-impacting bugs.
+
+We aim to acknowledge within 72 hours and ship a fix or mitigation within
+30 days for critical findings. Embargoed disclosure timelines will be
+coordinated with reporters as part of the advisory thread.
+
+## Maintainer signing key
+
+All release tags from v0.1.0 onward will be GPG-signed (see "Supply chain" below for current 0.0.x scaffold status). Verify a signed release with:
+
+```bash
+gh release view v0.1.0 --json tagName,assets
+git verify-tag v0.1.0
+```
+
+GPG fingerprint: `8033 2600 17B9 BAE5 BAD9  CA15 55BA BA8E ED15 8AD1`
+
+Key ID: `ed25519/55BABA8EED158AD1` (long), `ED158AD1` (short).
+Created 2026-04-27, expires 2028-04-26 (rotated before expiry).
+UID: `tjo099 <tjo099@gmail.com>`.
+
+Fetch and verify the maintainer public key (canonical source is the
+maintainer's GitHub profile):
+
+```bash
+curl -fsSL https://github.com/tjo099.gpg | gpg --import
+gpg --fingerprint 8033260017B9BAE5BAD9CA1555BABA8EED158AD1
+# expect: 8033 2600 17B9 BAE5 BAD9  CA15 55BA BA8E ED15 8AD1
+```
+
+Then verify a release tag with `git tag -v vX.Y.Z`.
+
+## Supply chain
+
+- All commits to `main` are intended to be GPG-signed (status: temporarily suspended during 0.0.x prerelease scaffold; see CHANGELOG. Will be re-enabled before v0.1.0 release tag).
+- Dependencies are audited via `bun audit` + OSV-Scanner on every PR.
+- SBOM (`syft`) is attached to every release starting v0.1.0.
+- SLSA provenance attestations are generated on release.
+- `.npmrc` and `bunfig.toml` set `ignore-scripts=true`.
+- Public API surface verified via attw (arethetypeswrong) on every PR.

package/dist/booking-flow/can-transition.d.ts

@@ -0,0 +1,3 @@
+import { type BookingAction, type BookingType, type Transition } from './state-diagram.js';
+export declare function canTransition(fromType: BookingType, fromStatus: string, action: BookingAction): Transition | null;
+//# sourceMappingURL=can-transition.d.ts.map

package/dist/booking-flow/can-transition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"can-transition.d.ts","sourceRoot":"","sources":["../../src/booking-flow/can-transition.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,WAAW,EAEhB,KAAK,UAAU,EAChB,MAAM,oBAAoB,CAAA;AAE3B,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,WAAW,EACrB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,aAAa,GACpB,UAAU,GAAG,IAAI,CAGnB"}

package/dist/booking-flow/can-transition.js

@@ -0,0 +1,7 @@
+// src/booking-flow/can-transition.ts
+import { STATE_DIAGRAM, } from './state-diagram.js';
+export function canTransition(fromType, fromStatus, action) {
+    const t = STATE_DIAGRAM[fromType]?.[fromStatus]?.[action];
+    return t ?? null;
+}
+//# sourceMappingURL=can-transition.js.map

package/dist/booking-flow/can-transition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"can-transition.js","sourceRoot":"","sources":["../../src/booking-flow/can-transition.ts"],"names":[],"mappings":"AAAA,qCAAqC;AACrC,OAAO,EAGL,aAAa,GAEd,MAAM,oBAAoB,CAAA;AAE3B,MAAM,UAAU,aAAa,CAC3B,QAAqB,EACrB,UAAkB,EAClB,MAAqB;IAErB,MAAM,CAAC,GAAG,aAAa,CAAC,QAAQ,CAAC,EAAE,CAAC,UAAU,CAAC,EAAE,CAAC,MAAM,CAAC,CAAA;IACzD,OAAO,CAAC,IAAI,IAAI,CAAA;AAClB,CAAC"}

package/dist/booking-flow/index.d.ts

@@ -0,0 +1,5 @@
+export { canTransition } from './can-transition.js';
+export { STATE_DIAGRAM } from './state-diagram.js';
+export type { BookingAction, BookingType, StateDiagram, Transition, } from './state-diagram.js';
+export { acceptBookingOption, acceptBookingRequest, rejectBookingOption, revokeBookingOption, } from './transitions.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/booking-flow/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/booking-flow/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAClD,YAAY,EACV,aAAa,EACb,WAAW,EACX,YAAY,EACZ,UAAU,GACX,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,kBAAkB,CAAA"}

package/dist/booking-flow/index.js

@@ -0,0 +1,5 @@
+// src/booking-flow/index.ts
+export { canTransition } from './can-transition.js';
+export { STATE_DIAGRAM } from './state-diagram.js';
+export { acceptBookingOption, acceptBookingRequest, rejectBookingOption, revokeBookingOption, } from './transitions.js';
+//# sourceMappingURL=index.js.map

package/dist/booking-flow/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/booking-flow/index.ts"],"names":[],"mappings":"AAAA,4BAA4B;AAC5B,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAOlD,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,kBAAkB,CAAA"}

package/dist/booking-flow/state-diagram.d.ts

@@ -0,0 +1,19 @@
+export type BookingType = 'BookingRequest' | 'BookingOption' | 'BookingOptionRequest' | 'Booking';
+export type BookingAction = 'accept' | 'reject' | 'revoke' | 'modify';
+export interface Transition {
+    readonly nextType: BookingType;
+    readonly nextStatus: string;
+    readonly terminal?: boolean;
+}
+type Cell = Transition | undefined;
+export interface StateDiagram {
+    readonly [fromType: string]: {
+        readonly [fromStatus: string]: {
+            readonly [action in BookingAction]?: Cell;
+        };
+    };
+}
+/** v2 (A1 risk #2): deepFreeze covers leaf Transition objects so STATE_DIAGRAM.X.Y.Z.accept.nextType = '...' fails at runtime. */
+export declare const STATE_DIAGRAM: StateDiagram;
+export {};
+//# sourceMappingURL=state-diagram.d.ts.map

package/dist/booking-flow/state-diagram.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-diagram.d.ts","sourceRoot":"","sources":["../../src/booking-flow/state-diagram.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,WAAW,GAAG,gBAAgB,GAAG,eAAe,GAAG,sBAAsB,GAAG,SAAS,CAAA;AACjG,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAErE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAA;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAC5B;AAED,KAAK,IAAI,GAAG,UAAU,GAAG,SAAS,CAAA;AAElC,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,QAAQ,EAAE,MAAM,GAAG;QAC3B,QAAQ,EAAE,UAAU,EAAE,MAAM,GAAG;YAC7B,QAAQ,EAAE,MAAM,IAAI,aAAa,CAAC,CAAC,EAAE,IAAI;SAC1C,CAAA;KACF,CAAA;CACF;AAED,kIAAkI;AAClI,eAAO,MAAM,aAAa,EAAE,YA6B1B,CAAA"}

package/dist/booking-flow/state-diagram.js

@@ -0,0 +1,34 @@
+// src/booking-flow/state-diagram.ts
+import { deepFreeze } from '../util/deep-freeze.js';
+/** v2 (A1 risk #2): deepFreeze covers leaf Transition objects so STATE_DIAGRAM.X.Y.Z.accept.nextType = '...' fails at runtime. */
+export const STATE_DIAGRAM = deepFreeze({
+    BookingRequest: {
+        REQUEST_PENDING: {
+            accept: { nextType: 'BookingOption', nextStatus: 'REQUEST_PENDING' },
+            reject: { nextType: 'BookingRequest', nextStatus: 'REQUEST_REJECTED', terminal: true },
+            revoke: { nextType: 'BookingRequest', nextStatus: 'REQUEST_REVOKED', terminal: true },
+        },
+    },
+    BookingOption: {
+        REQUEST_PENDING: {
+            accept: { nextType: 'BookingOptionRequest', nextStatus: 'REQUEST_PENDING' },
+            reject: { nextType: 'BookingOption', nextStatus: 'REQUEST_REJECTED', terminal: true },
+            revoke: { nextType: 'BookingOption', nextStatus: 'REQUEST_REVOKED', terminal: true },
+            modify: { nextType: 'BookingOption', nextStatus: 'REQUEST_PENDING' },
+        },
+    },
+    BookingOptionRequest: {
+        REQUEST_PENDING: {
+            accept: { nextType: 'Booking', nextStatus: 'REQUEST_ACCEPTED' },
+            reject: { nextType: 'BookingOptionRequest', nextStatus: 'REQUEST_REJECTED', terminal: true },
+            revoke: { nextType: 'BookingOptionRequest', nextStatus: 'REQUEST_REVOKED', terminal: true },
+            modify: { nextType: 'BookingOption', nextStatus: 'REQUEST_PENDING' },
+        },
+    },
+    Booking: {
+        REQUEST_ACCEPTED: {
+            revoke: { nextType: 'Booking', nextStatus: 'REQUEST_REVOKED', terminal: true },
+        },
+    },
+});
+//# sourceMappingURL=state-diagram.js.map

package/dist/booking-flow/state-diagram.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-diagram.js","sourceRoot":"","sources":["../../src/booking-flow/state-diagram.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAqBnD,kIAAkI;AAClI,MAAM,CAAC,MAAM,aAAa,GAAiB,UAAU,CAAC;IACpD,cAAc,EAAE;QACd,eAAe,EAAE;YACf,MAAM,EAAE,EAAE,QAAQ,EAAE,eAAe,EAAE,UAAU,EAAE,iBAAiB,EAAE;YACpE,MAAM,EAAE,EAAE,QAAQ,EAAE,gBAAgB,EAAE,UAAU,EAAE,kBAAkB,EAAE,QAAQ,EAAE,IAAI,EAAE;YACtF,MAAM,EAAE,EAAE,QAAQ,EAAE,gBAAgB,EAAE,UAAU,EAAE,iBAAiB,EAAE,QAAQ,EAAE,IAAI,EAAE;SACtF;KACF;IACD,aAAa,EAAE;QACb,eAAe,EAAE;YACf,MAAM,EAAE,EAAE,QAAQ,EAAE,sBAAsB,EAAE,UAAU,EAAE,iBAAiB,EAAE;YAC3E,MAAM,EAAE,EAAE,QAAQ,EAAE,eAAe,EAAE,UAAU,EAAE,kBAAkB,EAAE,QAAQ,EAAE,IAAI,EAAE;YACrF,MAAM,EAAE,EAAE,QAAQ,EAAE,eAAe,EAAE,UAAU,EAAE,iBAAiB,EAAE,QAAQ,EAAE,IAAI,EAAE;YACpF,MAAM,EAAE,EAAE,QAAQ,EAAE,eAAe,EAAE,UAAU,EAAE,iBAAiB,EAAE;SACrE;KACF;IACD,oBAAoB,EAAE;QACpB,eAAe,EAAE;YACf,MAAM,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,kBAAkB,EAAE;YAC/D,MAAM,EAAE,EAAE,QAAQ,EAAE,sBAAsB,EAAE,UAAU,EAAE,kBAAkB,EAAE,QAAQ,EAAE,IAAI,EAAE;YAC5F,MAAM,EAAE,EAAE,QAAQ,EAAE,sBAAsB,EAAE,UAAU,EAAE,iBAAiB,EAAE,QAAQ,EAAE,IAAI,EAAE;YAC3F,MAAM,EAAE,EAAE,QAAQ,EAAE,eAAe,EAAE,UAAU,EAAE,iBAAiB,EAAE;SACrE;KACF;IACD,OAAO,EAAE;QACP,gBAAgB,EAAE;YAChB,MAAM,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,iBAAiB,EAAE,QAAQ,EAAE,IAAI,EAAE;SAC/E;KACF;CACF,CAAC,CAAA"}

package/dist/booking-flow/transitions.d.ts

@@ -0,0 +1,9 @@
+import type { BookingOption } from '../classes/booking-option/schema.js';
+import type { BookingRequest } from '../classes/booking-request/schema.js';
+import type { Booking } from '../classes/booking/schema.js';
+import type { ParseResult } from '../result.js';
+export declare function acceptBookingRequest(req: BookingRequest): ParseResult<BookingOption>;
+export declare function acceptBookingOption(opt: BookingOption): ParseResult<Booking>;
+export declare function rejectBookingOption(opt: BookingOption, _reason?: string): ParseResult<BookingOption>;
+export declare function revokeBookingOption(opt: BookingOption, _reason?: string): ParseResult<BookingOption>;
+//# sourceMappingURL=transitions.d.ts.map

package/dist/booking-flow/transitions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transitions.d.ts","sourceRoot":"","sources":["../../src/booking-flow/transitions.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAA;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sCAAsC,CAAA;AAC1E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,8BAA8B,CAAA;AAE3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAmB/C,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,cAAc,GAAG,WAAW,CAAC,aAAa,CAAC,CAoBpF;AAED,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,aAAa,GAAG,WAAW,CAAC,OAAO,CAAC,CAqB5E;AAED,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,aAAa,EAClB,OAAO,CAAC,EAAE,MAAM,GACf,WAAW,CAAC,aAAa,CAAC,CAmB5B;AAED,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,aAAa,EAClB,OAAO,CAAC,EAAE,MAAM,GACf,WAAW,CAAC,aAAa,CAAC,CAa5B"}

package/dist/booking-flow/transitions.js

@@ -0,0 +1,94 @@
+// src/booking-flow/transitions.ts
+import { randomUUID } from 'node:crypto';
+import { CARGO_CONTEXT_IRI } from '../version.js';
+import { canTransition } from './can-transition.js';
+/**
+ * v3 (A3-R2 top-risk #2): acceptBookingOption DELIBERATELY skips the
+ * BookingOptionRequest intermediate and returns a Booking directly. This
+ * contradicts spec §5.4 STATE_DIAGRAM (which routes BookingOption.accept ->
+ * BookingOptionRequest), but matches spec §5.2 signature. Documented as a
+ * deliberate divergence; v0.2 will reconcile.
+ */
+const TENANT = 'transitions';
+const HOST = 'flaks.example';
+function makeId(type) {
+    return `https://${HOST}/${TENANT}/${type.toLowerCase()}/${randomUUID()}`;
+}
+export function acceptBookingRequest(req) {
+    const t = canTransition('BookingRequest', req.requestStatus, 'accept');
+    if (!t)
+        return {
+            ok: false,
+            error: {
+                kind: 'forbidden_state_transition',
+                from: `BookingRequest.${req.requestStatus}`,
+                to: 'accept',
+                path: '$',
+            },
+        };
+    const opt = {
+        '@context': CARGO_CONTEXT_IRI,
+        '@type': 'BookingOption',
+        '@id': makeId('BookingOption'),
+        forBookingRequest: req['@id'],
+        optionStatus: 'OPTION_PROPOSED',
+    };
+    return { ok: true, value: opt };
+}
+export function acceptBookingOption(opt) {
+    const t = canTransition('BookingOption', 'REQUEST_PENDING', 'accept');
+    if (!t)
+        return {
+            ok: false,
+            error: {
+                kind: 'forbidden_state_transition',
+                from: 'BookingOption.REQUEST_PENDING',
+                to: 'accept',
+                path: '$',
+            },
+        };
+    const booking = {
+        '@context': CARGO_CONTEXT_IRI,
+        '@type': 'Booking',
+        '@id': makeId('Booking'),
+        bookingStatus: 'REQUEST_ACCEPTED',
+        forBookingRequest: opt.forBookingRequest,
+        forBookingOption: opt['@id'],
+    };
+    return { ok: true, value: booking };
+}
+export function rejectBookingOption(opt, _reason) {
+    const t = canTransition('BookingOption', 'REQUEST_PENDING', 'reject');
+    if (!t)
+        return {
+            ok: false,
+            error: {
+                kind: 'forbidden_state_transition',
+                from: 'BookingOption.REQUEST_PENDING',
+                to: 'reject',
+                path: '$',
+            },
+        };
+    return {
+        ok: true,
+        value: {
+            ...opt,
+            optionStatus: 'OPTION_REJECTED',
+        },
+    };
+}
+export function revokeBookingOption(opt, _reason) {
+    const t = canTransition('BookingOption', 'REQUEST_PENDING', 'revoke');
+    if (!t)
+        return {
+            ok: false,
+            error: {
+                kind: 'forbidden_state_transition',
+                from: 'BookingOption.REQUEST_PENDING',
+                to: 'revoke',
+                path: '$',
+            },
+        };
+    return { ok: true, value: { ...opt, optionStatus: 'OPTION_REJECTED' } };
+}
+//# sourceMappingURL=transitions.js.map

package/dist/booking-flow/transitions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transitions.js","sourceRoot":"","sources":["../../src/booking-flow/transitions.ts"],"names":[],"mappings":"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"}

package/dist/classes/access-delegation/codec.d.ts

@@ -0,0 +1,4 @@
+import type { Codec } from '../shared/codec.js';
+import type { AccessDelegation, JsonLdAccessDelegation } from './schema.js';
+export declare const AccessDelegationCodec: Codec<AccessDelegation, JsonLdAccessDelegation, 'AccessDelegation'>;
+//# sourceMappingURL=codec.d.ts.map

package/dist/classes/access-delegation/codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../../../src/classes/access-delegation/codec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAA;AAE/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AAI3E,eAAO,MAAM,qBAAqB,EAAE,KAAK,CACvC,gBAAgB,EAChB,sBAAsB,EACtB,kBAAkB,CAOT,CAAA"}

package/dist/classes/access-delegation/codec.js

@@ -0,0 +1,11 @@
+import { deserializeAccessDelegation } from './deserialize.js';
+import { AccessDelegationSchema } from './schema.js';
+import { serializeAccessDelegation, serializeAccessDelegationStrict } from './serialize.js';
+export const AccessDelegationCodec = Object.freeze({
+    schema: AccessDelegationSchema,
+    serialize: serializeAccessDelegation,
+    serializeStrict: serializeAccessDelegationStrict,
+    deserialize: deserializeAccessDelegation,
+    type: 'AccessDelegation',
+});
+//# sourceMappingURL=codec.js.map

package/dist/classes/access-delegation/codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.js","sourceRoot":"","sources":["../../../src/classes/access-delegation/codec.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAA;AAE9D,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AACpD,OAAO,EAAE,yBAAyB,EAAE,+BAA+B,EAAE,MAAM,gBAAgB,CAAA;AAE3F,MAAM,CAAC,MAAM,qBAAqB,GAI9B,MAAM,CAAC,MAAM,CAAC;IAChB,MAAM,EAAE,sBAAsB;IAC9B,SAAS,EAAE,yBAAyB;IACpC,eAAe,EAAE,+BAA+B;IAChD,WAAW,EAAE,2BAA2B;IACxC,IAAI,EAAE,kBAAkB;CAChB,CAAC,CAAA"}

package/dist/classes/access-delegation/deserialize.d.ts

@@ -0,0 +1,5 @@
+import type { ParseResult } from '../../result.js';
+import type { DeserializeOpts } from '../../safety/limits.js';
+import type { AccessDelegation } from './schema.js';
+export declare function deserializeAccessDelegation(input: unknown, opts?: DeserializeOpts): ParseResult<AccessDelegation>;
+//# sourceMappingURL=deserialize.d.ts.map

package/dist/classes/access-delegation/deserialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deserialize.d.ts","sourceRoot":"","sources":["../../../src/classes/access-delegation/deserialize.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAG7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAGnD,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,OAAO,EACd,IAAI,GAAE,eAAoB,GACzB,WAAW,CAAC,gBAAgB,CAAC,CA2D/B"}

package/dist/classes/access-delegation/deserialize.js

@@ -0,0 +1,64 @@
+import { assertContextAllowed } from '../../context.js';
+import { findInvalidIriInIssues } from '../../iri/zod-safe-iri.js';
+import { preValidate } from '../../safety/pre-validate.js';
+import { findFirstEmptyArray, nullProtoClone, withMeta } from '../shared/parse-utils.js';
+import { AccessDelegationSchema } from './schema.js';
+export function deserializeAccessDelegation(input, opts = {}) {
+    // 1. Pre-Zod sanity
+    const preOpts = {};
+    if (opts.limits !== undefined)
+        preOpts.limits = opts.limits;
+    if (opts.payloadByteLength !== undefined)
+        preOpts.payloadByteLength = opts.payloadByteLength;
+    if (opts.meta !== undefined)
+        preOpts.meta = opts.meta;
+    const pre = preValidate(input, preOpts);
+    if (!pre.ok)
+        return pre;
+    // 2. @context allowlist
+    if (pre.value && typeof pre.value === 'object' && '@context' in pre.value) {
+        const ctxOpts = {};
+        if (opts.allowedContexts !== undefined)
+            ctxOpts.allowedContexts = opts.allowedContexts;
+        if (opts.meta !== undefined)
+            ctxOpts.meta = opts.meta;
+        const ctxR = assertContextAllowed(pre.value['@context'], ctxOpts);
+        if (!ctxR.ok)
+            return ctxR;
+    }
+    // 3. Empty-array rejection (v3 plan correction)
+    const empty = findFirstEmptyArray(pre.value, '$');
+    if (empty) {
+        return {
+            ok: false,
+            error: withMeta({
+                kind: 'cardinality_violation',
+                field: empty.field,
+                expected: '>=1 or omit',
+                got: 0,
+                path: empty.path,
+            }, opts.meta),
+        };
+    }
+    // 4. Zod parse, lift safeIri-tagged issues
+    const r = AccessDelegationSchema.safeParse(pre.value);
+    if (!r.success) {
+        const iriErr = findInvalidIriInIssues(r.error.issues, '$');
+        if (iriErr)
+            return { ok: false, error: withMeta(iriErr, opts.meta) };
+        return {
+            ok: false,
+            error: withMeta({
+                kind: 'zod_validation',
+                issues: r.error.issues.map((i) => ({
+                    path: i.path.length === 0 ? '$' : i.path.join('.'),
+                    message: i.message,
+                    code: i.code,
+                })),
+            }, opts.meta),
+        };
+    }
+    // 5. Null-prototype clone
+    return { ok: true, value: nullProtoClone(r.data) };
+}
+//# sourceMappingURL=deserialize.js.map

package/dist/classes/access-delegation/deserialize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deserialize.js","sourceRoot":"","sources":["../../../src/classes/access-delegation/deserialize.ts"],"names":[],"mappings":"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"}

package/dist/classes/access-delegation/index.d.ts

@@ -0,0 +1,6 @@
+export { AccessDelegationCodec } from './codec.js';
+export { deserializeAccessDelegation } from './deserialize.js';
+export { AccessDelegationSchema } from './schema.js';
+export type { AccessDelegation, JsonLdAccessDelegation } from './schema.js';
+export { serializeAccessDelegation, serializeAccessDelegationStrict } from './serialize.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/classes/access-delegation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/classes/access-delegation/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAA;AAClD,OAAO,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAA;AAC9D,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AACpD,YAAY,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AAC3E,OAAO,EAAE,yBAAyB,EAAE,+BAA+B,EAAE,MAAM,gBAAgB,CAAA"}