@flaks/onerecord 0.1.2 → 0.3.0

package/dist/dispatch/domain-constraints.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Domain-semantic constraints that the Zod schemas mark as optional but spec
+ * §5.x requires. Used by `dispatchGraphWalk` to emit
+ * `domain_constraint_violation` for missing-but-required fields.
+ *
+ * Closes deviation #6 PARTIALLY (v0.2 — deferral F):
+ *  - graph-cardinality (this file) — EMPTY in v0.3.0: Path A removed the stale v0.2 constraints (Waybill.shipmentInformation / Shipment.containedPieces); see the explanatory note below
+ *  - AWB number consistency between Waybill ↔ embedded Shipments — v0.3
+ *  - total-pieces / total-weight sums between Shipment ↔ Pieces — v0.3
+ *  - reference resolvability for cross-graph IRIs — v0.3
+ *
+ * v0.3 (Path A): The v0.2 constraints on `Waybill.shipmentInformation` and
+ * `Shipment.containedPieces` have been REMOVED. Path A replaced
+ * `shipmentInformation` with `shipment` and `containedPieces` with `pieces`
+ * in the schema; the old field names have no 3.2.0 spec basis and are no
+ * longer part of the data model surface. The spec-correct cross-node check
+ * (Waybill↔Shipment inverse-property consistency via `Waybill.shipment` ↔
+ * `Shipment.waybill`) is deferred to v0.3's final-review task — the
+ * constraint framework would need bidirectional-reference resolution which
+ * is multi-node and out of this batch's scope.
+ *
+ * Opt-in via the dispatch path; default per-class deserializers stay
+ * schema-permissive.
+ */
+export interface DomainConstraint {
+    /** Field that must be present on the root LO. */
+    field: string;
+    /** Cardinality requirement (`required` = present + non-null). */
+    cardinality: 'required';
+    /** Spec section reference for the constraint. */
+    specRef: string;
+}
+export declare const DOMAIN_CONSTRAINTS: Readonly<Record<string, DomainConstraint[]>>;
+export interface DomainConstraintViolation {
+    className: string;
+    field: string;
+    expected: 'required';
+    specRef: string;
+}
+/**
+ * Validate root-level cardinality constraints for the given root class.
+ * Returns the FIRST missing-required-field violation, or undefined if all
+ * required fields are present.
+ *
+ * Only checks root-level constraints — nested LO-in-LO cardinality is
+ * deferred to v0.3 (alongside the other deviation #6 sub-items).
+ */
+export declare function checkDomainConstraints(rootClass: string, root: Record<string, unknown>): DomainConstraintViolation | undefined;
+//# sourceMappingURL=domain-constraints.d.ts.map

package/dist/dispatch/domain-constraints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain-constraints.d.ts","sourceRoot":"","sources":["../../src/dispatch/domain-constraints.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAA;IACb,iEAAiE;IACjE,WAAW,EAAE,UAAU,CAAA;IACvB,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAC,CAAqB,CAAA;AAEjG,MAAM,WAAW,yBAAyB;IACxC,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,UAAU,CAAA;IACpB,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,yBAAyB,GAAG,SAAS,CAuBvC"}

package/dist/dispatch/domain-constraints.js

@@ -0,0 +1,59 @@
+/**
+ * Domain-semantic constraints that the Zod schemas mark as optional but spec
+ * §5.x requires. Used by `dispatchGraphWalk` to emit
+ * `domain_constraint_violation` for missing-but-required fields.
+ *
+ * Closes deviation #6 PARTIALLY (v0.2 — deferral F):
+ *  - graph-cardinality (this file) — EMPTY in v0.3.0: Path A removed the stale v0.2 constraints (Waybill.shipmentInformation / Shipment.containedPieces); see the explanatory note below
+ *  - AWB number consistency between Waybill ↔ embedded Shipments — v0.3
+ *  - total-pieces / total-weight sums between Shipment ↔ Pieces — v0.3
+ *  - reference resolvability for cross-graph IRIs — v0.3
+ *
+ * v0.3 (Path A): The v0.2 constraints on `Waybill.shipmentInformation` and
+ * `Shipment.containedPieces` have been REMOVED. Path A replaced
+ * `shipmentInformation` with `shipment` and `containedPieces` with `pieces`
+ * in the schema; the old field names have no 3.2.0 spec basis and are no
+ * longer part of the data model surface. The spec-correct cross-node check
+ * (Waybill↔Shipment inverse-property consistency via `Waybill.shipment` ↔
+ * `Shipment.waybill`) is deferred to v0.3's final-review task — the
+ * constraint framework would need bidirectional-reference resolution which
+ * is multi-node and out of this batch's scope.
+ *
+ * Opt-in via the dispatch path; default per-class deserializers stay
+ * schema-permissive.
+ */
+export const DOMAIN_CONSTRAINTS = Object.freeze({});
+/**
+ * Validate root-level cardinality constraints for the given root class.
+ * Returns the FIRST missing-required-field violation, or undefined if all
+ * required fields are present.
+ *
+ * Only checks root-level constraints — nested LO-in-LO cardinality is
+ * deferred to v0.3 (alongside the other deviation #6 sub-items).
+ */
+export function checkDomainConstraints(rootClass, root) {
+    const constraints = DOMAIN_CONSTRAINTS[rootClass];
+    if (!constraints)
+        return undefined;
+    for (const c of constraints) {
+        const v = root[c.field];
+        if (v === undefined || v === null) {
+            return {
+                className: rootClass,
+                field: c.field,
+                expected: c.cardinality,
+                specRef: c.specRef,
+            };
+        }
+        if (Array.isArray(v) && v.length === 0) {
+            return {
+                className: rootClass,
+                field: c.field,
+                expected: c.cardinality,
+                specRef: c.specRef,
+            };
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=domain-constraints.js.map

package/dist/dispatch/domain-constraints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain-constraints.js","sourceRoot":"","sources":["../../src/dispatch/domain-constraints.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAWH,MAAM,CAAC,MAAM,kBAAkB,GAAiD,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;AASjG;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CACpC,SAAiB,EACjB,IAA6B;IAE7B,MAAM,WAAW,GAAG,kBAAkB,CAAC,SAAS,CAAC,CAAA;IACjD,IAAI,CAAC,WAAW;QAAE,OAAO,SAAS,CAAA;IAClC,KAAK,MAAM,CAAC,IAAI,WAAW,EAAE,CAAC;QAC5B,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAA;QACvB,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;YAClC,OAAO;gBACL,SAAS,EAAE,SAAS;gBACpB,KAAK,EAAE,CAAC,CAAC,KAAK;gBACd,QAAQ,EAAE,CAAC,CAAC,WAAW;gBACvB,OAAO,EAAE,CAAC,CAAC,OAAO;aACnB,CAAA;QACH,CAAC;QACD,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvC,OAAO;gBACL,SAAS,EAAE,SAAS;gBACpB,KAAK,EAAE,CAAC,CAAC,KAAK;gBACd,QAAQ,EAAE,CAAC,CAAC,WAAW;gBACvB,OAAO,EAAE,CAAC,CAAC,OAAO;aACnB,CAAA;QACH,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC"}

package/dist/dispatch/field-types.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Static map: '<Class>.<field>' -> expected `@type` of an embedded
+ * object or IRI-referenced node. Used by `dispatchGraphWalk` to emit
+ * `wrong_type_for_endpoint` when an embedded node's `@type` does not
+ * match the field's contract.
+ *
+ * Coverage: every cross-referencing field across the registered class set.
+ * Scalar fields and external-endpoint URLs
+ * (`Subscription.notificationEndpoint`, `ServerInformation.serverEndpoint`)
+ * are intentionally omitted — those don't resolve to a OneRecord type.
+ *
+ * Polymorphic fields are marked with `'*'`. The graph-walker treats
+ * `'*'` as "any logistics-object type accepted".
+ *
+ * Maintenance: when adding a new class or field that holds a
+ * cross-reference, also add the expected-type mapping here. The
+ * graph-walker only checks mapped fields, so omission is silent —
+ * a missing entry means "not validated".
+ */
+export declare const FIELD_TYPES: Readonly<Record<string, string>>;
+/**
+ * Look up the expected `@type` for a given (className, fieldName).
+ * Returns `undefined` for fields not in the map (= not validated by
+ * the graph-walker — either scalar or out-of-scope external URL).
+ * Returns `'*'` for polymorphic fields where any logistics-object
+ * `@type` is valid.
+ */
+export declare function expectedTypeFor(className: string, fieldName: string): string | undefined;
+//# sourceMappingURL=field-types.d.ts.map

package/dist/dispatch/field-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-types.d.ts","sourceRoot":"","sources":["../../src/dispatch/field-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA6HvD,CAAA;AAEF;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAExF"}

package/dist/dispatch/field-types.js

@@ -0,0 +1,135 @@
+/**
+ * Static map: '<Class>.<field>' -> expected `@type` of an embedded
+ * object or IRI-referenced node. Used by `dispatchGraphWalk` to emit
+ * `wrong_type_for_endpoint` when an embedded node's `@type` does not
+ * match the field's contract.
+ *
+ * Coverage: every cross-referencing field across the registered class set.
+ * Scalar fields and external-endpoint URLs
+ * (`Subscription.notificationEndpoint`, `ServerInformation.serverEndpoint`)
+ * are intentionally omitted — those don't resolve to a OneRecord type.
+ *
+ * Polymorphic fields are marked with `'*'`. The graph-walker treats
+ * `'*'` as "any logistics-object type accepted".
+ *
+ * Maintenance: when adding a new class or field that holds a
+ * cross-reference, also add the expected-type mapping here. The
+ * graph-walker only checks mapped fields, so omission is silent —
+ * a missing entry means "not validated".
+ */
+export const FIELD_TYPES = Object.freeze({
+    // Access-delegation
+    'AccessDelegationRequest.accessDelegation': 'AccessDelegation',
+    'AccessDelegation.delegatedTo': 'Party',
+    'AccessDelegation.delegatedFrom': 'Party',
+    // Account number
+    // (AccountNumber.issuedBy removed — :issuedBy is range :Person / domain :SecurityDeclaration,
+    //  not on :AccountNumber; do not repoint)
+    // Booking ecosystem
+    'Booking.forBookingRequest': 'BookingRequest',
+    'Booking.forBookingOption': 'BookingOption',
+    'BookingOption.forBookingRequest': 'BookingRequest',
+    'BookingOption.preferences': 'BookingPreferences',
+    'BookingOptionRequest.forBookingOption': 'BookingOption',
+    'BookingRequest.requestor': 'Party',
+    'BookingRequest.preferences': 'BookingPreferences',
+    'BookingSegment.transportMovement': 'TransportMovement',
+    'BookingSegment.loadingLocation': 'Location',
+    'BookingSegment.unloadingLocation': 'Location',
+    'BookingShipment.forShipment': 'Shipment',
+    // Change ecosystem
+    'Change.hasOperation': 'Operation', // embedded array, not IRI ref
+    'ChangeRequest.forLogisticsObject': '*', // polymorphic
+    'ChangeRequest.hasChange': 'Change',
+    // CO2Emissions
+    'CO2Emissions.calculationFor': '*', // polymorphic — TransportMovement or Shipment etc.
+    'TransportMovement.co2Emissions': 'CO2Emissions',
+    // Company (concrete :Organization subtype — only concrete org type shipped)
+    'Company.basedAtLocation': 'Location',
+    // Organization-range properties pin to 'Company': :Company rdfs:subClassOf :Organization and
+    // Company is the only concrete :Organization subtype this library ships post-Organization-
+    // retirement, so 'Company' is the correct (not over-strict) wrong_type_for_endpoint contract.
+    // Company.contactPersons → 'Person': ontology range is abstract :Actor, :Person rdfs:subClassOf
+    // :Actor, no NonHumanActor shipped, so 'Person' is the correct concrete contract.
+    'Company.contactPersons': 'Person',
+    'Company.parentOrganization': 'Company',
+    'Company.subOrganization': 'Company',
+    // CustomsInformation
+    'CustomsInformation.issuedForPiece': 'Piece',
+    'CustomsInformation.issuedForShipment': 'Shipment',
+    // Handling
+    'HandlingService.provider': 'Party',
+    'HandlingService.forShipment': 'Shipment',
+    // Insurance
+    'Insurance.coveringOrganization': 'Company',
+    'Insurance.insuredShipments': 'Shipment',
+    // LineItemPackage / ULD
+    'LineItemPackage.pieceReferences': 'Piece',
+    'WaybillLineItem.lineItemPackages': 'LineItemPackage',
+    'WaybillLineItem.uldReferences': 'ULD',
+    // Location ↔ Address
+    'Location.address': 'Address',
+    // Logistics event
+    'LogisticsEvent.eventLocation': 'Location',
+    'LogisticsEvent.relatedTransportMovement': 'TransportMovement',
+    // Notification
+    'Notification.relatedLogisticsObject': '*', // polymorphic
+    // Party (Organization retired; partyDetails is Person or Company)
+    'Party.partyDetails': '*', // polymorphic — Person or Company
+    'Party.accountNumbers': 'AccountNumber',
+    // Piece
+    'Piece.ofShipment': 'Shipment',
+    'Piece.containedPieces': 'Piece',
+    'Piece.securityDeclarations': 'SecurityDeclaration',
+    // Piece.packagingType omitted — :PackagingType is a codes class (enum), not a logistics object
+    // RegulatedEntity
+    'RegulatedEntity.owningOrganization': 'Company',
+    // SecurityDeclaration
+    'SecurityDeclaration.issuedForPiece': 'Piece',
+    'SecurityDeclaration.issuedBy': 'Person',
+    'SecurityDeclaration.regulatedEntityIssuer': 'RegulatedEntity',
+    'SecurityDeclaration.regulatedEntityAcceptor': 'RegulatedEntity',
+    'SecurityDeclaration.receivedFrom': 'RegulatedEntity',
+    'SecurityDeclaration.otherRegulatedEntities': 'RegulatedEntity',
+    // Shipment
+    'Shipment.pieces': 'Piece',
+    'Shipment.waybill': 'Waybill',
+    'Shipment.involvedParties': 'Party',
+    'Shipment.customsInformation': 'CustomsInformation',
+    'Shipment.insurance': 'Insurance',
+    'Shipment.securityDeclarations': 'SecurityDeclaration',
+    // Subscription
+    'SubscriptionRequest.subscription': 'Subscription',
+    'Subscription.topic': '*', // polymorphic — any logistics object class IRI
+    'Subscription.subscriber': 'Party',
+    // Transport movement
+    'TransportMovement.departureLocation': 'Location',
+    'TransportMovement.arrivalLocation': 'Location',
+    'TransportMovement.movementTimes': 'MovementTime',
+    // Verification
+    'VerificationRequest.verification': 'Verification',
+    'Verification.verifiedObject': '*', // polymorphic
+    // Waybill
+    'Waybill.shipment': 'Shipment',
+    'Waybill.involvedParties': 'Party',
+    'Waybill.waybillLineItems': 'WaybillLineItem',
+    'Waybill.otherCharges': 'OtherCharge',
+    'Waybill.carrierDeclarationPlace': 'Location',
+    'Waybill.departureLocation': 'Location',
+    'Waybill.arrivalLocation': 'Location',
+    'Waybill.houseWaybills': 'Waybill',
+    'Waybill.masterWaybill': 'Waybill',
+    // Waybill.billingDetails omitted — :BillingDetails not modelled in v0.3.0 (deviation #16)
+    'Waybill.referredBookingOption': 'BookingOption',
+});
+/**
+ * Look up the expected `@type` for a given (className, fieldName).
+ * Returns `undefined` for fields not in the map (= not validated by
+ * the graph-walker — either scalar or out-of-scope external URL).
+ * Returns `'*'` for polymorphic fields where any logistics-object
+ * `@type` is valid.
+ */
+export function expectedTypeFor(className, fieldName) {
+    return FIELD_TYPES[`${className}.${fieldName}`];
+}
+//# sourceMappingURL=field-types.js.map

package/dist/dispatch/field-types.js.map

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

package/dist/dispatch/graph-walk.d.ts

@@ -0,0 +1,23 @@
+import type { ParseResult } from '../result.js';
+/**
+ * Cross-node graph integrity analysis. Runs as a single walk via
+ * `walkGraph`'s visitor; emits at most one of:
+ *  - `duplicate_id_in_graph` — two distinct nodes share an `@id`.
+ *  - `missing_id` — a node embedded in a cross-reference position has no `@id`.
+ *  - `wrong_type_for_endpoint` — a node's `@type` does not match the
+ *    declared expected type for the field that references it.
+ *  - `missing_type` — a non-leaf node lacks `@type`.
+ *  - `iri_not_canonical` — an IRI string is not in canonical form
+ *    (lowercase scheme/host, no default port; RFC 3987 + spec §3.2).
+ *
+ * Returns `ok: true` if the graph is structurally sound (per spec §3.2 + §7.1).
+ *
+ * Does NOT replace per-class Zod schema validation — that runs after this
+ * pass succeeds, in `dispatch.deserialize.<Class>`.
+ *
+ * v0.2: containing-class tracking via path-keyed map of object @types,
+ * so `wrong_type_for_endpoint` and `missing_id` checks fire for all
+ * embedded references, not just direct children of the root.
+ */
+export declare function dispatchGraphWalk(input: unknown, rootClass: string): ParseResult<true>;
+//# sourceMappingURL=graph-walk.d.ts.map

package/dist/dispatch/graph-walk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-walk.d.ts","sourceRoot":"","sources":["../../src/dispatch/graph-walk.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAc,WAAW,EAAE,MAAM,cAAc,CAAA;AAO3D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,CAoItF"}

package/dist/dispatch/graph-walk.js

@@ -0,0 +1,207 @@
+import { walkGraph } from '../safety/walk-graph.js';
+import { checkContextOrder } from './context-order.js';
+import { checkDomainConstraints } from './domain-constraints.js';
+import { expectedTypeFor } from './field-types.js';
+import { checkIriCanonical, looksLikeIri } from './iri-canonical.js';
+/**
+ * Cross-node graph integrity analysis. Runs as a single walk via
+ * `walkGraph`'s visitor; emits at most one of:
+ *  - `duplicate_id_in_graph` — two distinct nodes share an `@id`.
+ *  - `missing_id` — a node embedded in a cross-reference position has no `@id`.
+ *  - `wrong_type_for_endpoint` — a node's `@type` does not match the
+ *    declared expected type for the field that references it.
+ *  - `missing_type` — a non-leaf node lacks `@type`.
+ *  - `iri_not_canonical` — an IRI string is not in canonical form
+ *    (lowercase scheme/host, no default port; RFC 3987 + spec §3.2).
+ *
+ * Returns `ok: true` if the graph is structurally sound (per spec §3.2 + §7.1).
+ *
+ * Does NOT replace per-class Zod schema validation — that runs after this
+ * pass succeeds, in `dispatch.deserialize.<Class>`.
+ *
+ * v0.2: containing-class tracking via path-keyed map of object @types,
+ * so `wrong_type_for_endpoint` and `missing_id` checks fire for all
+ * embedded references, not just direct children of the root.
+ */
+export function dispatchGraphWalk(input, rootClass) {
+    // context_order_violation (deviation #10 closure, deferral E): if the
+    // root @context is an array, verify the LAST element is allowed.
+    // Per JSON-LD 1.1 §3.7 later items override earlier ones for term
+    // definitions; the last item is the effective cargo-term context.
+    // String-form @context is delegated to assertContextAllowed (already
+    // runs in the per-class deserializer).
+    if (typeof input === 'object' && input !== null && '@context' in input) {
+        const ctx = input['@context'];
+        const orderR = checkContextOrder(ctx);
+        if (!orderR.ok && orderR.lastUnallowed !== undefined) {
+            return {
+                ok: false,
+                error: {
+                    kind: 'context_order_violation',
+                    got: ctx,
+                    lastUnallowed: orderR.lastUnallowed,
+                    path: '$["@context"]',
+                },
+            };
+        }
+    }
+    // domain_constraint_violation (deviation #6 partial closure, deferral F):
+    // root-level cardinality constraints from spec §5.x. v0.3 (Path A) removed
+    // the stale v0.2 constraints on Waybill.shipmentInformation /
+    // Shipment.containedPieces (Path A replaced those field names with shipment
+    // / pieces). Future expansion: AWB consistency, total-pieces/weight sums,
+    // and reference resolvability.
+    if (typeof input === 'object' && input !== null && !Array.isArray(input)) {
+        const violation = checkDomainConstraints(rootClass, input);
+        if (violation) {
+            return {
+                ok: false,
+                error: {
+                    kind: 'domain_constraint_violation',
+                    className: violation.className,
+                    field: violation.field,
+                    expected: violation.expected,
+                    specRef: violation.specRef,
+                    path: `$.${violation.field}`,
+                },
+            };
+        }
+    }
+    const seen = new Map(); // @id -> first path seen
+    // Path-keyed @type lookup: maps each object node's path to its declared
+    // (or root-defaulted) @type. Used to resolve the containing class when
+    // checking wrong_type_for_endpoint / missing_id at any depth.
+    const pathToType = new Map();
+    pathToType.set('$', rootClass);
+    let firstError;
+    const walkR = walkGraph(input, {}, (node, path, _depth) => {
+        if (firstError)
+            return; // short-circuit on first error
+        // iri_not_canonical: check every IRI-shaped string value in the
+        // graph (deviation #9 closure, deferral D). Runs before the
+        // object-only checks below because string values are visited
+        // separately by walkGraph.
+        if (typeof node === 'string' && looksLikeIri(node)) {
+            const r = checkIriCanonical(node);
+            if (!r.canonical && r.reason) {
+                firstError = {
+                    kind: 'iri_not_canonical',
+                    iri: node,
+                    reason: r.reason,
+                    path,
+                };
+            }
+            return;
+        }
+        if (typeof node !== 'object' || node === null || Array.isArray(node))
+            return;
+        const obj = node;
+        const id = typeof obj['@id'] === 'string' ? obj['@id'] : undefined;
+        const type = typeof obj['@type'] === 'string' ? obj['@type'] : undefined;
+        // Record this object's @type by path so children can find their
+        // containing class. Falls back to rootClass for the root path.
+        if (type)
+            pathToType.set(path, type);
+        // missing_type: every non-leaf node must declare @type
+        if (!type && hasObjectChildren(obj)) {
+            firstError = { kind: 'missing_type', path };
+            return;
+        }
+        const parentField = pathToParentField(path);
+        const containingClass = parentField ? containingClassFor(path, pathToType) : undefined;
+        // missing_id: nodes embedded in cross-reference positions must have @id.
+        // Cross-reference positions are fields in FIELD_TYPES for the containing class.
+        if (parentField && containingClass && !id && requiresId(parentField, containingClass)) {
+            firstError = {
+                kind: 'missing_id',
+                objectType: type ?? 'unknown',
+                path,
+            };
+            return;
+        }
+        // duplicate_id_in_graph
+        if (id) {
+            if (seen.has(id)) {
+                firstError = { kind: 'duplicate_id_in_graph', iri: id, path };
+                return;
+            }
+            seen.set(id, path);
+        }
+        // wrong_type_for_endpoint: embedded @type must match the field's
+        // expected class. Now checked at any depth — containing class
+        // resolved via the path-keyed @type map.
+        if (type && parentField && containingClass) {
+            const expected = expectedTypeFor(containingClass, parentField);
+            if (expected && expected !== '*' && expected !== type) {
+                firstError = {
+                    kind: 'wrong_type_for_endpoint',
+                    expected,
+                    got: type,
+                    path,
+                };
+            }
+        }
+    });
+    if (!walkR.ok)
+        return walkR; // safety-limit error
+    if (firstError)
+        return { ok: false, error: firstError };
+    return { ok: true, value: true };
+}
+function hasObjectChildren(obj) {
+    for (const v of Object.values(obj)) {
+        if (typeof v === 'object' && v !== null)
+            return true;
+    }
+    return false;
+}
+/**
+ * Path format: `$`, `$.<field>`, `$.<field>[<n>]`, `$.<field>.<sub>`,
+ * `$.<field>[<n>].<sub>`. Returns the immediate parent field name.
+ * Returns `undefined` for the root path `$`.
+ */
+function pathToParentField(path) {
+    if (path === '$')
+        return undefined;
+    const last = path.split('.').pop();
+    if (!last)
+        return undefined;
+    return last.replace(/\[\d+\]$/, ''); // strip array index suffix
+}
+/**
+ * Resolve the containing class for the node at `path` by looking up the
+ * @type recorded at the parent object's path. Skips array-index segments
+ * (those don't carry their own @type).
+ *
+ * Examples (rootClass = 'Waybill'):
+ *  - `$.shipment` → parent path `$` → 'Waybill'
+ *  - `$.shipment.involvedParties` → parent path `$.shipment`
+ *    → whatever @type was declared on that node (typically 'Shipment')
+ *  - `$.pieces[0]` → strip `[0]` then `.pieces` → '$' → 'Waybill' (via Shipment)
+ *    (the array container itself isn't an object node so we step past it)
+ *  - `$.pieces[0].dimensions` → parent path `$.pieces[0]`
+ *    → @type at that path (typically 'Piece')
+ */
+function containingClassFor(path, pathToType) {
+    if (path === '$')
+        return undefined;
+    // Strip the trailing `.field` or `[N]` segment to get the parent path.
+    const stripped = path.replace(/\[\d+\]$/, '');
+    const lastDot = stripped.lastIndexOf('.');
+    if (lastDot < 0)
+        return undefined;
+    let parentPath = stripped.slice(0, lastDot);
+    if (parentPath === '')
+        parentPath = '$';
+    return pathToType.get(parentPath);
+}
+/**
+ * A field requires `@id` on referenced nodes if it's in `FIELD_TYPES`
+ * for the given containing class (= the field points at another
+ * logistics-object node). Scalar fields and unmapped fields don't
+ * require `@id`.
+ */
+function requiresId(parentField, containingClass) {
+    return expectedTypeFor(containingClass, parentField) !== undefined;
+}
+//# sourceMappingURL=graph-walk.js.map

package/dist/dispatch/graph-walk.js.map

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

package/dist/dispatch/index.d.ts

@@ -0,0 +1,30 @@
+import { type ClassName } from '../factory-classes.js';
+import type { ParseResult } from '../result.js';
+/**
+ * Build the per-class deserialize map by wrapping each module's
+ * `deserialize<ClassName>` function with the graph-walk pre-pass.
+ *
+ * Failure of the graph-walk pre-pass returns the underlying ParseError
+ * untouched; per-class Zod validation only runs if the pre-pass passes.
+ */
+type DispatchDeserializeMap = {
+    readonly [C in ClassName]: (raw: unknown) => ParseResult<unknown>;
+};
+/**
+ * Opt-in dispatch facade per spec §13. Use:
+ *   import { dispatch } from '@flaks/onerecord'
+ *   const r = dispatch.deserialize.Waybill(input)
+ *
+ * Each per-class deserializer runs the graph-walk pre-pass before
+ * delegating to the per-class Zod schema. The default per-class
+ * deserializers (`WaybillCodec.deserialize`, `onerecord.deserialize.Waybill`)
+ * are unchanged — graph-walk is opt-in.
+ *
+ * For state-bound graph-walk (per-call limits, IRI strategy etc.), use
+ * `createMapper({ graphWalk: true })` instead.
+ */
+export declare const dispatch: Readonly<{
+    deserialize: Readonly<DispatchDeserializeMap>;
+}>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/dispatch/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/dispatch/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,SAAS,EAAE,MAAM,uBAAuB,CAAA;AAC/D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAG/C;;;;;;GAMG;AACH,KAAK,sBAAsB,GAAG;IAC5B,QAAQ,EAAE,CAAC,IAAI,SAAS,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,WAAW,CAAC,OAAO,CAAC;CAClE,CAAA;AAuBD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,QAAQ;;EAEnB,CAAA"}

package/dist/dispatch/index.js

@@ -0,0 +1,36 @@
+import { CLASSES } from '../factory-classes.js';
+import { dispatchGraphWalk } from './graph-walk.js';
+function buildDispatchDeserialize() {
+    const out = {};
+    for (const className of Object.keys(CLASSES)) {
+        const mod = CLASSES[className];
+        const fn = mod[`deserialize${className}`];
+        if (typeof fn !== 'function') {
+            throw new Error(`dispatch: deserialize${className} not found on module — check src/factory-classes.ts and src/classes/${className.toLowerCase()}/index.ts`);
+        }
+        out[className] = (raw) => {
+            const walkR = dispatchGraphWalk(raw, className);
+            if (!walkR.ok)
+                return walkR;
+            return fn(raw);
+        };
+    }
+    return out;
+}
+/**
+ * Opt-in dispatch facade per spec §13. Use:
+ *   import { dispatch } from '@flaks/onerecord'
+ *   const r = dispatch.deserialize.Waybill(input)
+ *
+ * Each per-class deserializer runs the graph-walk pre-pass before
+ * delegating to the per-class Zod schema. The default per-class
+ * deserializers (`WaybillCodec.deserialize`, `onerecord.deserialize.Waybill`)
+ * are unchanged — graph-walk is opt-in.
+ *
+ * For state-bound graph-walk (per-call limits, IRI strategy etc.), use
+ * `createMapper({ graphWalk: true })` instead.
+ */
+export const dispatch = Object.freeze({
+    deserialize: Object.freeze(buildDispatchDeserialize()),
+});
+//# sourceMappingURL=index.js.map

package/dist/dispatch/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/dispatch/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAkB,MAAM,uBAAuB,CAAA;AAE/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AAanD,SAAS,wBAAwB;IAC/B,MAAM,GAAG,GAAG,EAA+D,CAAA;IAC3E,KAAK,MAAM,SAAS,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAgB,EAAE,CAAC;QAC5D,MAAM,GAAG,GAAG,OAAO,CAAC,SAAS,CAA4B,CAAA;QACzD,MAAM,EAAE,GAAG,GAAG,CAAC,cAAc,SAAS,EAAE,CAE3B,CAAA;QACb,IAAI,OAAO,EAAE,KAAK,UAAU,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CACb,wBAAwB,SAAS,uEAAuE,SAAS,CAAC,WAAW,EAAE,WAAW,CAC3I,CAAA;QACH,CAAC;QACD,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,GAAY,EAAwB,EAAE;YACtD,MAAM,KAAK,GAAG,iBAAiB,CAAC,GAAG,EAAE,SAAS,CAAC,CAAA;YAC/C,IAAI,CAAC,KAAK,CAAC,EAAE;gBAAE,OAAO,KAAK,CAAA;YAC3B,OAAO,EAAE,CAAC,GAAG,CAAC,CAAA;QAChB,CAAC,CAAA;IACH,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC;IACpC,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,wBAAwB,EAAE,CAAC;CACvD,CAAC,CAAA"}

package/dist/dispatch/iri-canonical.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Per RFC 3987 + spec §3.2 the canonical IRI form requires:
+ *  - scheme in lowercase (`https` not `HTTPS`)
+ *  - host in lowercase (`example.com` not `EXAMPLE.COM`)
+ *  - no default port (omit `:443` for https, `:80` for http)
+ *
+ * Percent-encoding case (uppercase hex) is intentionally NOT checked
+ * here — modern URL parsers already normalize it, and the false-positive
+ * surface in v0.2 is too high.
+ *
+ * Used by `dispatchGraphWalk` to emit `iri_not_canonical` for non-canonical
+ * IRIs anywhere in the graph. Default deserializers (v0.1.x compat) do
+ * NOT run this check; it's only fired through the opt-in dispatch path.
+ */
+/** True if `s` looks like an IRI (has a `scheme:` prefix). */
+export declare function looksLikeIri(s: string): boolean;
+export type IriCanonicalReason = 'scheme_not_lowercase' | 'host_not_lowercase' | 'default_port';
+export interface IriCanonicalResult {
+    canonical: boolean;
+    reason?: IriCanonicalReason;
+}
+/**
+ * Check whether `s` is in canonical form per RFC 3987 + spec §3.2.
+ * Non-IRI strings (no scheme prefix) return `{ canonical: true }` —
+ * other validators (Zod schemas, safeIri) handle the malformed case.
+ */
+export declare function checkIriCanonical(s: string): IriCanonicalResult;
+//# sourceMappingURL=iri-canonical.d.ts.map

package/dist/dispatch/iri-canonical.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"iri-canonical.d.ts","sourceRoot":"","sources":["../../src/dispatch/iri-canonical.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,8DAA8D;AAC9D,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAE/C;AAED,MAAM,MAAM,kBAAkB,GAAG,sBAAsB,GAAG,oBAAoB,GAAG,cAAc,CAAA;AAE/F,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,OAAO,CAAA;IAClB,MAAM,CAAC,EAAE,kBAAkB,CAAA;CAC5B;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,GAAG,kBAAkB,CA+B/D"}