@hodeinavarro/odoo-rpc-ts 0.2.0

package/dist/records/recordModel.js

@@ -0,0 +1,101 @@
+/**
+ * Declared record models — the SPEC tier of the records design ("declared
+ * prefetch" over the 17+ `specification` protocol; the classic tier in
+ * `typed.ts`/`related.ts` speaks the 16+ `[id, name]`-pair protocol instead).
+ * A `RecordSpec`
+ * declares a model's field graph with `effect/Schema`: scalars decode directly,
+ * relations declared with {@link Many2One}/{@link One2Many} carry a nested child
+ * `RecordSpec`. From one declaration we derive BOTH:
+ *
+ *   1. a row {@link RecordSpec.schema} that strict-decodes the NESTED wire shape
+ *      the 17+ `web_search_read`/`web_read` `specification` protocol returns
+ *      (a many2one as a `{ id, ...declared }` dict or `false`; an x2many as a
+ *      nested list), and
+ *   2. the field {@link RecordSpec.fields} metadata that {@link ./spec.ts} compiles
+ *      into that `specification` payload.
+ *
+ * No I/O lives here — this is pure declaration. The single round trip that turns
+ * a spec into rows is in `OdooClient.searchTyped`/`readTyped`/`saveTyped`.
+ *
+ * MANY2ONE VALUE SHAPE (decision, records design 2026-07-10). A declared
+ * many2one decodes to a FLAT struct `{ id, ...declaredChildFields } | null`, not
+ * a `{ id, value }` wrapper. In TS, `| null` already carries "is it set?", and a
+ * flat struct exposes `.id` and every declared child field as directly-typed
+ * properties (`company.name`) with no `__getattr__`-style proxy and no extra
+ * `.value` hop — strictly better inference and ergonomics than a wrapper. This
+ * deliberately diverges from the Python design's `.value` recommendation, which
+ * existed to model presence separately from the record; TS does not need it.
+ */
+import { Schema, SchemaTransformation } from "effect";
+/**
+ * Declare a many2one field: `company_id: Many2One(Company)`. Decodes the nested
+ * `{ id, ...Company fields }` wire dict to `Company | null` (Odoo's `false`
+ * empty → `null`). Note it does NOT accept the classic `[id, name]` pair — under
+ * a `specification` the server returns a dict, so a leaked pair is drift, not a
+ * silent decode.
+ */
+export const Many2One = (spec) => ({
+    _decl: "many2one",
+    spec,
+});
+/**
+ * Declare an x2many field: `child_ids: One2Many(Contact)` or
+ * `One2Many(Contact, { limit: 20 })`. Decodes the nested list to
+ * `ReadonlyArray<Contact>`; `limit`, when given, rides the compiled
+ * `specification` so the server bounds the co-recordset.
+ */
+export const One2Many = (spec, options) => ({ _decl: "one2many", spec, limit: options?.limit });
+const isRelationDecl = (value) => typeof value === "object" && value !== null && "_decl" in value;
+/**
+ * The nullable-many2one nested schema: the child dict, or Odoo's `false` empty
+ * → `null`. Strict: a classic `[id, name]` pair (or any non-dict) fails decode,
+ * surfacing as {@link SchemaDriftError} at the client boundary rather than being
+ * cast past.
+ */
+// oxlint-disable-next-line no-explicit-any -- Schema invariance; see FieldInput.
+const many2oneFieldSchema = (child) => Schema.Union([child.schema, Schema.Literal(false)]).pipe(Schema.decodeTo(Schema.NullOr(Schema.toType(child.schema)), SchemaTransformation.transform({
+    decode: (wire) => (wire === false ? null : wire),
+    encode: (value) => (value === null ? false : value),
+})));
+/**
+ * Build a {@link RecordSpec} from a model name and a field declaration. `id`
+ * (`Schema.Number`) is added automatically and always compiled into the
+ * `specification`, so every declared record and every relation subtree carries
+ * its id — the key downstream joins and re-reads rely on.
+ *
+ * ```ts
+ * const Company = defineRecord("res.company", { name: Schema.String });
+ * const Partner = defineRecord("res.partner", {
+ *   name: Schema.String,
+ *   company_id: Many2One(Company),
+ *   child_ids: One2Many(Partner_contact, { limit: 20 }),
+ * });
+ * ```
+ */
+export const defineRecord = (model, fields) => {
+    const structFields = { id: Schema.Number };
+    const meta = { id: { kind: "scalar" } };
+    for (const [name, decl] of Object.entries(fields)) {
+        if (isRelationDecl(decl)) {
+            if (decl._decl === "many2one") {
+                structFields[name] = many2oneFieldSchema(decl.spec);
+                meta[name] = { kind: "many2one", child: decl.spec };
+            }
+            else {
+                structFields[name] = Schema.Array(decl.spec.schema);
+                meta[name] = { kind: "one2many", child: decl.spec, limit: decl.limit };
+            }
+        }
+        else {
+            structFields[name] = decl;
+            meta[name] = { kind: "scalar" };
+        }
+    }
+    // The dynamic Struct build cannot preserve the precise mapped type; we recover
+    // it via the RowType/RowEncoded projection, which is exactly what the loop
+    // constructs field-for-field.
+    const schema = Schema.Struct(structFields);
+    const hasRelations = Object.values(meta).some((m) => m.kind !== "scalar");
+    return { model, schema, fields: meta, hasRelations };
+};
+//# sourceMappingURL=recordModel.js.map

package/dist/records/recordModel.js.map

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

package/dist/records/related.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Pure join helpers for explicit relation traversal (the classic tier). No I/O: given
+ * already-decoded rows and a field accessor, collect the distinct related ids to
+ * fetch, and key decoded related rows by id for O(1) joins. The batched `read`
+ * itself lives in {@link ./typed.ts}; everything here is inert data shaping.
+ */
+import type { Many2OneRefValue } from "./relations.js";
+/** A many2one field's decoded value: a ref, a bare id, or empty. */
+export type RefOrId = Many2OneRefValue | number | null | undefined;
+/**
+ * The related id a {@link RefOrId} points at, or `null` when empty. A ref value
+ * carries `.id`; a bare number is itself the id. Anything else is out of
+ * contract and yields `null` (the caller's runtime guard rejects true misuse
+ * before this is reached — see {@link ./typed.ts}).
+ */
+export declare const refId: (ref: RefOrId) => number | null;
+/**
+ * The distinct, non-null related ids reachable through `accessor` across all
+ * `rows`, in first-seen order. This is the exact id set a single batched `read`
+ * must cover — an empty result means ZERO round trips are needed.
+ */
+export declare const collectRefIds: <Row>(rows: ReadonlyArray<Row>, accessor: (row: Row) => RefOrId) => ReadonlyArray<number>;
+/**
+ * A snapshot of decoded related rows keyed by id. Inert: it holds data and never
+ * fetches. `get` accepts a many2one ref, a bare id, or `null`/`undefined` and
+ * returns the joined row or `null` — a pure lookup, never a round trip.
+ */
+export interface RelatedMap<A> {
+    /** Join a many2one value (ref/id/empty) to its decoded related row, or `null`. */
+    readonly get: (ref: RefOrId) => A | null;
+    /** The number of distinct related rows held. */
+    readonly size: number;
+}
+/**
+ * Build a {@link RelatedMap} from decoded related rows, keyed by each row's
+ * `id`. The rows come straight from a single batched `read`, so a duplicate id
+ * cannot occur; last-write-wins is a harmless invariant, not a policy.
+ */
+export declare const makeRelatedMap: <A extends {
+    readonly id: number;
+}>(rows: ReadonlyArray<A>) => RelatedMap<A>;
+//# sourceMappingURL=related.d.ts.map

package/dist/records/related.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"related.d.ts","sourceRoot":"","sources":["../../src/records/related.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,oEAAoE;AACpE,MAAM,MAAM,OAAO,GAAG,gBAAgB,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;AAEnE;;;;;GAKG;AACH,eAAO,MAAM,KAAK,QAAS,OAAO,KAAG,MAAM,GAAG,IAQ7C,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,GAAG,QACzB,aAAa,CAAC,GAAG,CAAC,YACd,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,KAC9B,aAAa,CAAC,MAAM,CAWtB,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,kFAAkF;IAClF,QAAQ,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,CAAC,GAAG,IAAI,CAAC;IACzC,gDAAgD;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,SAAS;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,QACxD,aAAa,CAAC,CAAC,CAAC,KACrB,UAAU,CAAC,CAAC,CAYd,CAAC"}

package/dist/records/related.js

@@ -0,0 +1,51 @@
+/**
+ * The related id a {@link RefOrId} points at, or `null` when empty. A ref value
+ * carries `.id`; a bare number is itself the id. Anything else is out of
+ * contract and yields `null` (the caller's runtime guard rejects true misuse
+ * before this is reached — see {@link ./typed.ts}).
+ */
+export const refId = (ref) => {
+    if (ref === null || ref === undefined) {
+        return null;
+    }
+    if (typeof ref === "number") {
+        return ref;
+    }
+    return typeof ref === "object" && typeof ref.id === "number" ? ref.id : null;
+};
+/**
+ * The distinct, non-null related ids reachable through `accessor` across all
+ * `rows`, in first-seen order. This is the exact id set a single batched `read`
+ * must cover — an empty result means ZERO round trips are needed.
+ */
+export const collectRefIds = (rows, accessor) => {
+    const seen = new Set();
+    const out = [];
+    for (const row of rows) {
+        const id = refId(accessor(row));
+        if (id !== null && !seen.has(id)) {
+            seen.add(id);
+            out.push(id);
+        }
+    }
+    return out;
+};
+/**
+ * Build a {@link RelatedMap} from decoded related rows, keyed by each row's
+ * `id`. The rows come straight from a single batched `read`, so a duplicate id
+ * cannot occur; last-write-wins is a harmless invariant, not a policy.
+ */
+export const makeRelatedMap = (rows) => {
+    const byId = new Map();
+    for (const row of rows) {
+        byId.set(row.id, row);
+    }
+    return {
+        get: (ref) => {
+            const id = refId(ref);
+            return id === null ? null : (byId.get(id) ?? null);
+        },
+        size: byId.size,
+    };
+};
+//# sourceMappingURL=related.js.map

package/dist/records/related.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"related.js","sourceRoot":"","sources":["../../src/records/related.ts"],"names":[],"mappings":"AAWA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,GAAY,EAAiB,EAAE;IACnD,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtC,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5B,OAAO,GAAG,CAAC;IACb,CAAC;IACD,OAAO,OAAO,GAAG,KAAK,QAAQ,IAAI,OAAO,GAAG,CAAC,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAC/E,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAC3B,IAAwB,EACxB,QAA+B,EACR,EAAE;IACzB,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,EAAE,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;QAChC,IAAI,EAAE,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;YACjC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACb,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC,CAAC;AAcF;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAC5B,IAAsB,EACP,EAAE;IACjB,MAAM,IAAI,GAAG,IAAI,GAAG,EAAa,CAAC;IAClC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;IACxB,CAAC;IACD,OAAO;QACL,GAAG,EAAE,CAAC,GAAG,EAAE,EAAE;YACX,MAAM,EAAE,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;YACtB,OAAO,EAAE,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC,CAAC;QACrD,CAAC;QACD,IAAI,EAAE,IAAI,CAAC,IAAI;KAChB,CAAC;AACJ,CAAC,CAAC"}

package/dist/records/relations.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Pure relation & temporal value schemas — the decode vocabulary for typed
+ * records. No I/O: these are `effect/Schema` definitions a caller composes into
+ * a row schema. They transform Odoo's on-the-wire shapes (classic `[id, name]`
+ * many2one pairs, `false` empties, naive datetime strings) into ergonomic,
+ * fully-typed domain values, failing loudly as schema drift on anything else.
+ */
+import { Schema } from "effect";
+/**
+ * A decoded many2one reference: the related record's id and its display label,
+ * as Odoo carries them together in a classic `search_read`/`read` payload. The
+ * label is already present, so the common "show the name" case needs ZERO extra
+ * round trips — see {@link ../typed.ts | TypedRecordSet.fetchRelated} for when
+ * you need more than the label.
+ */
+export interface Many2OneRefValue {
+    readonly id: number;
+    readonly name: string;
+}
+/** The decoded-value schema for a {@link Many2OneRefValue}. */
+export declare const Many2OneRefValue: Schema.Codec<Many2OneRefValue>;
+/**
+ * Decode a present many2one from its wire `[id, name]` pair to a
+ * {@link Many2OneRefValue}. Use {@link Many2OneRefOrNull} for a field that can
+ * be empty (Odoo sends `false`, not `null`, for an unset many2one).
+ *
+ * WIRE FACT: the `[id, name]` pair requires the classic `_classic_read` load
+ * (the `search_read`/`read` default). A context that changes the load (e.g. a
+ * future `load=None`) shifts the shape; strict decode then surfaces it as
+ * {@link SchemaDriftError} rather than casting past it.
+ */
+export declare const Many2OneRefFromWire: Schema.Codec<Many2OneRefValue, readonly [number, string]>;
+/** Ergonomic alias for {@link Many2OneRefFromWire} (the present-ref schema). */
+export declare const Many2OneRef: Schema.Codec<Many2OneRefValue, readonly [number, string], never, never>;
+/**
+ * Decode a nullable many2one: the wire `[id, name]` pair → {@link Many2OneRefValue},
+ * or Odoo's `false` empty → `null`. This is the schema a row declares for a
+ * many2one that can be unset, e.g. `company_id: Many2OneRefOrNull`.
+ */
+export declare const Many2OneRefOrNull: Schema.Codec<Many2OneRefValue | null, readonly [number, string] | false>;
+/**
+ * Odoo `Date` field: `"YYYY-MM-DD"` → a `Date` at UTC midnight of that day.
+ *
+ * A `Date` is an instant, and Odoo's `Date` carries no time or zone. We anchor
+ * it at UTC midnight and NEVER localize — reading back `getUTCFullYear()`/
+ * `getUTCMonth()`/`getUTCDate()` reproduces the exact wire day on any host,
+ * whereas the local accessors could roll a day depending on the runner's tz.
+ * Decision (records design, 2026-07-10): decode as UTC, documented, never
+ * silently localized.
+ */
+export declare const OdooDate: Schema.Codec<Date, string>;
+/**
+ * Odoo `Datetime` field: `"YYYY-MM-DD HH:MM:SS"` → a `Date` parsed as UTC.
+ *
+ * Odoo stores and transmits datetimes as naive strings that are UTC by
+ * convention. A JS `Date` is a single instant, so parsing the wire string AS
+ * UTC is the faithful, non-localizing choice: it names the same instant Odoo
+ * meant, with no host-tz shift. We never apply the session tz here — that is a
+ * presentation concern the caller owns. Decision (records design, 2026-07-10).
+ */
+export declare const OdooDateTime: Schema.Codec<Date, string>;
+/** {@link OdooDate} with Odoo's `false` empty decoding to `null`. */
+export declare const OdooDateOrNull: Schema.Codec<Date | null, string | false>;
+/** {@link OdooDateTime} with Odoo's `false` empty decoding to `null`. */
+export declare const OdooDateTimeOrNull: Schema.Codec<Date | null, string | false>;
+//# sourceMappingURL=relations.d.ts.map

package/dist/records/relations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relations.d.ts","sourceRoot":"","sources":["../../src/records/relations.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAkB,MAAM,EAAmD,MAAM,QAAQ,CAAC;AAIjG;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,+DAA+D;AAC/D,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,KAAK,CAAC,gBAAgB,CAG1D,CAAC;AAKH;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,KAAK,CAAC,gBAAgB,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CASvF,CAAC;AAEJ,gFAAgF;AAChF,eAAO,MAAM,WAAW,yEAAsB,CAAC;AAK/C;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,KAAK,CAC1C,gBAAgB,GAAG,IAAI,EACvB,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,KAAK,CASlC,CAAC;AAuBF;;;;;;;;;GASG;AACH,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAmB/C,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAmBnD,CAAC;AA6BF,qEAAqE;AACrE,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,EAAE,MAAM,GAAG,KAAK,CAAyB,CAAC;AAE/F,yEAAyE;AACzE,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,EAAE,MAAM,GAAG,KAAK,CAC9C,CAAC"}

package/dist/records/relations.js

@@ -0,0 +1,119 @@
+/**
+ * Pure relation & temporal value schemas — the decode vocabulary for typed
+ * records. No I/O: these are `effect/Schema` definitions a caller composes into
+ * a row schema. They transform Odoo's on-the-wire shapes (classic `[id, name]`
+ * many2one pairs, `false` empties, naive datetime strings) into ergonomic,
+ * fully-typed domain values, failing loudly as schema drift on anything else.
+ */
+import { Effect, Option, Schema, SchemaIssue, SchemaParser, SchemaTransformation } from "effect";
+/** The decoded-value schema for a {@link Many2OneRefValue}. */
+export const Many2OneRefValue = Schema.Struct({
+    id: Schema.Number,
+    name: Schema.String,
+});
+/** Odoo's on-the-wire many2one shape: the classic `[id, name]` pair. */
+const Many2OneWirePair = Schema.Tuple([Schema.Number, Schema.String]);
+/**
+ * Decode a present many2one from its wire `[id, name]` pair to a
+ * {@link Many2OneRefValue}. Use {@link Many2OneRefOrNull} for a field that can
+ * be empty (Odoo sends `false`, not `null`, for an unset many2one).
+ *
+ * WIRE FACT: the `[id, name]` pair requires the classic `_classic_read` load
+ * (the `search_read`/`read` default). A context that changes the load (e.g. a
+ * future `load=None`) shifts the shape; strict decode then surfaces it as
+ * {@link SchemaDriftError} rather than casting past it.
+ */
+export const Many2OneRefFromWire = Many2OneWirePair.pipe(Schema.decodeTo(Many2OneRefValue, SchemaTransformation.transform({
+    decode: ([id, name]) => ({ id, name }),
+    encode: ({ id, name }) => [id, name],
+})));
+/** Ergonomic alias for {@link Many2OneRefFromWire} (the present-ref schema). */
+export const Many2OneRef = Many2OneRefFromWire;
+/** The wire shape of a nullable many2one: the `[id, name]` pair or `false`. */
+const Many2OneWireOrFalse = Schema.Union([Many2OneWirePair, Schema.Literal(false)]);
+/**
+ * Decode a nullable many2one: the wire `[id, name]` pair → {@link Many2OneRefValue},
+ * or Odoo's `false` empty → `null`. This is the schema a row declares for a
+ * many2one that can be unset, e.g. `company_id: Many2OneRefOrNull`.
+ */
+export const Many2OneRefOrNull = Many2OneWireOrFalse.pipe(Schema.decodeTo(Schema.NullOr(Many2OneRefValue), SchemaTransformation.transform({
+    decode: (wire) => (wire === false ? null : { id: wire[0], name: wire[1] }),
+    encode: (value) => (value === null ? false : [value.id, value.name]),
+})));
+// --- dates & datetimes ------------------------------------------------------
+// Odoo Date is `"YYYY-MM-DD"`; Datetime is `"YYYY-MM-DD HH:MM:SS"`, both naive.
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const DATETIME_RE = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/;
+const pad = (n, width) => n.toString().padStart(width, "0");
+const formatUtcDate = (date) => `${pad(date.getUTCFullYear(), 4)}-${pad(date.getUTCMonth() + 1, 2)}-${pad(date.getUTCDate(), 2)}`;
+const formatUtcDateTime = (date) => `${formatUtcDate(date)} ${pad(date.getUTCHours(), 2)}:${pad(date.getUTCMinutes(), 2)}:${pad(date.getUTCSeconds(), 2)}`;
+/** A decode/encode failure as a v4 schema issue on the offending value. */
+const invalid = (value, message) => new SchemaIssue.InvalidValue(Option.some(value), { message });
+/**
+ * Odoo `Date` field: `"YYYY-MM-DD"` → a `Date` at UTC midnight of that day.
+ *
+ * A `Date` is an instant, and Odoo's `Date` carries no time or zone. We anchor
+ * it at UTC midnight and NEVER localize — reading back `getUTCFullYear()`/
+ * `getUTCMonth()`/`getUTCDate()` reproduces the exact wire day on any host,
+ * whereas the local accessors could roll a day depending on the runner's tz.
+ * Decision (records design, 2026-07-10): decode as UTC, documented, never
+ * silently localized.
+ */
+export const OdooDate = Schema.String.pipe(Schema.decodeTo(Schema.Date, SchemaTransformation.transformOrFail({
+    decode: (input) => {
+        if (!DATE_RE.test(input)) {
+            return Effect.fail(invalid(input, "expected YYYY-MM-DD"));
+        }
+        const ms = Date.parse(`${input}T00:00:00Z`);
+        return Number.isNaN(ms)
+            ? Effect.fail(invalid(input, "not a valid calendar date"))
+            : Effect.succeed(new Date(ms));
+    },
+    encode: (date) => Number.isNaN(date.getTime())
+        ? Effect.fail(invalid(date, "invalid Date"))
+        : Effect.succeed(formatUtcDate(date)),
+})));
+/**
+ * Odoo `Datetime` field: `"YYYY-MM-DD HH:MM:SS"` → a `Date` parsed as UTC.
+ *
+ * Odoo stores and transmits datetimes as naive strings that are UTC by
+ * convention. A JS `Date` is a single instant, so parsing the wire string AS
+ * UTC is the faithful, non-localizing choice: it names the same instant Odoo
+ * meant, with no host-tz shift. We never apply the session tz here — that is a
+ * presentation concern the caller owns. Decision (records design, 2026-07-10).
+ */
+export const OdooDateTime = Schema.String.pipe(Schema.decodeTo(Schema.Date, SchemaTransformation.transformOrFail({
+    decode: (input) => {
+        if (!DATETIME_RE.test(input)) {
+            return Effect.fail(invalid(input, "expected YYYY-MM-DD HH:MM:SS"));
+        }
+        const ms = Date.parse(`${input.replace(" ", "T")}Z`);
+        return Number.isNaN(ms)
+            ? Effect.fail(invalid(input, "not a valid calendar datetime"))
+            : Effect.succeed(new Date(ms));
+    },
+    encode: (date) => Number.isNaN(date.getTime())
+        ? Effect.fail(invalid(date, "invalid Date"))
+        : Effect.succeed(formatUtcDateTime(date)),
+})));
+/**
+ * Lift a `Codec<Date, string>` into one that also accepts Odoo's `false`
+ * empty, decoding it to `null`. Shared by the date and datetime nullable
+ * variants so the false↔null seam lives in exactly one place. Delegation to
+ * the base codec runs through `SchemaParser.*Effect`, which fails with a
+ * `SchemaIssue.Issue` directly — the v4 analogue of v3's
+ * `ParseResult.decodeUnknown` delegation.
+ */
+const orFalseNull = (base) => Schema.Union([Schema.String, Schema.Literal(false)]).pipe(Schema.decodeTo(Schema.NullOr(Schema.Date), SchemaTransformation.transformOrFail({
+    decode: (wire, options) => wire === false
+        ? Effect.succeed(null)
+        : SchemaParser.decodeUnknownEffect(base)(wire, options),
+    encode: (value, options) => value === null
+        ? Effect.succeed(false)
+        : SchemaParser.encodeUnknownEffect(base)(value, options),
+})));
+/** {@link OdooDate} with Odoo's `false` empty decoding to `null`. */
+export const OdooDateOrNull = orFalseNull(OdooDate);
+/** {@link OdooDateTime} with Odoo's `false` empty decoding to `null`. */
+export const OdooDateTimeOrNull = orFalseNull(OdooDateTime);
+//# sourceMappingURL=relations.js.map

package/dist/records/relations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relations.js","sourceRoot":"","sources":["../../src/records/relations.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAgBjG,+DAA+D;AAC/D,MAAM,CAAC,MAAM,gBAAgB,GAAmC,MAAM,CAAC,MAAM,CAAC;IAC5E,EAAE,EAAE,MAAM,CAAC,MAAM;IACjB,IAAI,EAAE,MAAM,CAAC,MAAM;CACpB,CAAC,CAAC;AAEH,wEAAwE;AACxE,MAAM,gBAAgB,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;AAEtE;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAC9B,gBAAgB,CAAC,IAAI,CACnB,MAAM,CAAC,QAAQ,CACb,gBAAgB,EAChB,oBAAoB,CAAC,SAAS,CAAC;IAC7B,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IACtC,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,CAAU;CAC9C,CAAC,CACH,CACF,CAAC;AAEJ,gFAAgF;AAChF,MAAM,CAAC,MAAM,WAAW,GAAG,mBAAmB,CAAC;AAE/C,+EAA+E;AAC/E,MAAM,mBAAmB,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,gBAAgB,EAAE,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAEpF;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAG1B,mBAAmB,CAAC,IAAI,CAC1B,MAAM,CAAC,QAAQ,CACb,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC,EAC/B,oBAAoB,CAAC,SAAS,CAAC;IAC7B,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1E,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAE,KAAe,CAAC,CAAC,CAAE,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,CAAW,CAAC;CAC3F,CAAC,CACH,CACF,CAAC;AAEF,+EAA+E;AAE/E,gFAAgF;AAChF,MAAM,OAAO,GAAG,qBAAqB,CAAC;AACtC,MAAM,WAAW,GAAG,uCAAuC,CAAC;AAE5D,MAAM,GAAG,GAAG,CAAC,CAAS,EAAE,KAAa,EAAU,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;AAEpF,MAAM,aAAa,GAAG,CAAC,IAAU,EAAU,EAAE,CAC3C,GAAG,GAAG,CAAC,IAAI,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC;AAEpG,MAAM,iBAAiB,GAAG,CAAC,IAAU,EAAU,EAAE,CAC/C,GAAG,aAAa,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC,IAAI,GAAG,CACzF,IAAI,CAAC,aAAa,EAAE,EACpB,CAAC,CACF,EAAE,CAAC;AAEN,2EAA2E;AAC3E,MAAM,OAAO,GAAG,CAAC,KAAc,EAAE,OAAe,EAA4B,EAAE,CAC5E,IAAI,WAAW,CAAC,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;AAEhE;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,QAAQ,GAA+B,MAAM,CAAC,MAAM,CAAC,IAAI,CACpE,MAAM,CAAC,QAAQ,CACb,MAAM,CAAC,IAAI,EACX,oBAAoB,CAAC,eAAe,CAAC;IACnC,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE;QAChB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YACzB,OAAO,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,qBAAqB,CAAC,CAAC,CAAC;QAC5D,CAAC;QACD,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,KAAK,YAAY,CAAC,CAAC;QAC5C,OAAO,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;YACrB,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,2BAA2B,CAAC,CAAC;YAC1D,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;IACnC,CAAC;IACD,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CACf,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;QAC1B,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;QAC5C,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;CAC1C,CAAC,CACH,CACF,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,YAAY,GAA+B,MAAM,CAAC,MAAM,CAAC,IAAI,CACxE,MAAM,CAAC,QAAQ,CACb,MAAM,CAAC,IAAI,EACX,oBAAoB,CAAC,eAAe,CAAC;IACnC,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE;QAChB,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YAC7B,OAAO,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,8BAA8B,CAAC,CAAC,CAAC;QACrE,CAAC;QACD,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;QACrD,OAAO,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;YACrB,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,+BAA+B,CAAC,CAAC;YAC9D,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;IACnC,CAAC;IACD,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CACf,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;QAC1B,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;QAC5C,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;CAC9C,CAAC,CACH,CACF,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,WAAW,GAAG,CAClB,IAAgC,EACW,EAAE,CAC7C,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CACvD,MAAM,CAAC,QAAQ,CACb,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAC1B,oBAAoB,CAAC,eAAe,CAAC;IACnC,MAAM,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,CACxB,IAAI,KAAK,KAAK;QACZ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC;QACtB,CAAC,CAAC,YAAY,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,OAAO,CAAC;IAC3D,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,CACzB,KAAK,KAAK,IAAI;QACZ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,KAAc,CAAC;QAChC,CAAC,CAAC,YAAY,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,OAAO,CAAC;CAC7D,CAAC,CACH,CACF,CAAC;AAEJ,qEAAqE;AACrE,MAAM,CAAC,MAAM,cAAc,GAA8C,WAAW,CAAC,QAAQ,CAAC,CAAC;AAE/F,yEAAyE;AACzE,MAAM,CAAC,MAAM,kBAAkB,GAC7B,WAAW,CAAC,YAAY,CAAC,CAAC"}

package/dist/records/spec.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Pure compilation of a declared {@link RecordSpec} into the Odoo `web_read`/
+ * `web_search_read` `specification` payload (17+). No I/O: given the field graph,
+ * emit `{ field: field_spec }` where a scalar is `{}`, a many2one is
+ * `{ fields: <nested> }`, and an x2many is `{ fields: <nested>, limit? }`. The
+ * server resolves each relation once over the whole co-recordset, so a compiled
+ * spec is exactly ONE batched round trip — no N+1.
+ *
+ * CYCLES. Eager child specs cannot form an object cycle in a strict language
+ * (you cannot reference a `RecordSpec` inside its own `defineRecord` call), so a
+ * cyclic declaration is inexpressible by construction and the normal path is
+ * total. We still guard defensively by RecordSpec IDENTITY along the ancestor
+ * chain — a spec forced into a cycle (via mutation / `any`) would otherwise
+ * recurse forever; instead it throws {@link RecordSpecCycleError}, which the
+ * client surfaces as a defect (a declaration bug, never a runtime condition). A
+ * finite DAG that references the same MODEL through two distinct specs is fine —
+ * only a repeated spec object is a cycle.
+ */
+import type { RecordSpec } from "./recordModel.js";
+import type { HasId } from "./typed.js";
+/** A declared record graph that references itself — a declaration bug, not a
+ * runtime fault. Thrown by {@link compileSpecification}; the client turns it into
+ * an `Effect` defect. */
+export declare class RecordSpecCycleError extends Error {
+    readonly path: ReadonlyArray<string>;
+    constructor(path: ReadonlyArray<string>);
+}
+/** A declared record with no compilable fields — an empty `specification` would
+ * ask the server for nothing. Thrown by {@link compileSpecification}. */
+export declare class EmptyRecordSpecError extends Error {
+    readonly model: string;
+    constructor(model: string);
+}
+/** `true` iff the spec declares at least one relation field (gate key). */
+export declare const hasRelations: <A extends HasId, I>(spec: RecordSpec<A, I>) => boolean;
+/**
+ * Compile a declared {@link RecordSpec} into its nested `specification` payload.
+ * Pure and total for the by-construction-acyclic normal case; throws
+ * {@link RecordSpecCycleError} on a forced cycle and {@link EmptyRecordSpecError}
+ * on an empty declaration. The client runs it under `Effect.sync`, so either
+ * throw becomes a precise defect.
+ */
+export declare const compileSpecification: <A extends HasId, I>(spec: RecordSpec<A, I>) => Record<string, unknown>;
+//# sourceMappingURL=spec.d.ts.map

package/dist/records/spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.d.ts","sourceRoot":"","sources":["../../src/records/spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC;;yBAEyB;AACzB,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACrC,YAAY,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,EAQtC;CACF;AAED;yEACyE;AACzE,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,YAAY,KAAK,EAAE,MAAM,EAOxB;CACF;AAED,2EAA2E;AAC3E,eAAO,MAAM,YAAY,GAAI,CAAC,SAAS,KAAK,EAAE,CAAC,QAAQ,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,OACb,CAAC;AAiC9D;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAAI,CAAC,SAAS,KAAK,EAAE,CAAC,QAC/C,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,KACrB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAsB,CAAC"}

package/dist/records/spec.js

@@ -0,0 +1,63 @@
+/** A declared record graph that references itself — a declaration bug, not a
+ * runtime fault. Thrown by {@link compileSpecification}; the client turns it into
+ * an `Effect` defect. */
+export class RecordSpecCycleError extends Error {
+    path;
+    constructor(path) {
+        super(`RecordSpec declaration cycle: ${path.join(" -> ")} -> ${path[path.length - 1]}. ` +
+            `A relation subtree references a record spec already on its ancestor chain; ` +
+            `the specification would be infinite. Declared record graphs must be finite.`);
+        this.name = "RecordSpecCycleError";
+        this.path = path;
+    }
+}
+/** A declared record with no compilable fields — an empty `specification` would
+ * ask the server for nothing. Thrown by {@link compileSpecification}. */
+export class EmptyRecordSpecError extends Error {
+    model;
+    constructor(model) {
+        super(`RecordSpec for "${model}" compiles to an empty specification (no fields). ` +
+            `A declared record must request at least its id.`);
+        this.name = "EmptyRecordSpecError";
+        this.model = model;
+    }
+}
+/** `true` iff the spec declares at least one relation field (gate key). */
+export const hasRelations = (spec) => Object.values(spec.fields).some((m) => m.kind !== "scalar");
+const compile = (
+// oxlint-disable-next-line no-explicit-any -- Schema is invariant; the compiler
+// walks the erased metadata graph structurally (see FieldMeta).
+spec, ancestors) => {
+    if (ancestors.includes(spec)) {
+        throw new RecordSpecCycleError([...ancestors.map((a) => a.model), spec.model]);
+    }
+    const nextAncestors = [...ancestors, spec];
+    const out = {};
+    for (const [name, meta] of Object.entries(spec.fields)) {
+        if (meta.kind === "scalar") {
+            out[name] = {};
+        }
+        else if (meta.kind === "many2one") {
+            out[name] = { fields: compile(meta.child, nextAncestors) };
+        }
+        else {
+            out[name] = {
+                fields: compile(meta.child, nextAncestors),
+                ...(meta.limit !== undefined ? { limit: meta.limit } : {}),
+            };
+        }
+    }
+    if (Object.keys(out).length === 0) {
+        throw new EmptyRecordSpecError(spec.model);
+    }
+    return out;
+};
+/**
+ * Compile a declared {@link RecordSpec} into its nested `specification` payload.
+ * Pure and total for the by-construction-acyclic normal case; throws
+ * {@link RecordSpecCycleError} on a forced cycle and {@link EmptyRecordSpecError}
+ * on an empty declaration. The client runs it under `Effect.sync`, so either
+ * throw becomes a precise defect.
+ */
+export const compileSpecification = (spec) => compile(spec, []);
+//# sourceMappingURL=spec.js.map

package/dist/records/spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.js","sourceRoot":"","sources":["../../src/records/spec.ts"],"names":[],"mappings":"AAqBA;;yBAEyB;AACzB,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IACpC,IAAI,CAAwB;IACrC,YAAY,IAA2B;QACrC,KAAK,CACH,iCAAiC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI;YAChF,6EAA6E;YAC7E,6EAA6E,CAChF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED;yEACyE;AACzE,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IACpC,KAAK,CAAS;IACvB,YAAY,KAAa;QACvB,KAAK,CACH,mBAAmB,KAAK,oDAAoD;YAC1E,iDAAiD,CACpD,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF;AAED,2EAA2E;AAC3E,MAAM,CAAC,MAAM,YAAY,GAAG,CAAqB,IAAsB,EAAW,EAAE,CAClF,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC;AAE9D,MAAM,OAAO,GAAG;AACd,gFAAgF;AAChF,gEAAgE;AAChE,IAA0B,EAC1B,SAA8C,EACrB,EAAE;IAC3B,IAAI,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,oBAAoB,CAAC,CAAC,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACjF,CAAC;IACD,MAAM,aAAa,GAAG,CAAC,GAAG,SAAS,EAAE,IAAI,CAAC,CAAC;IAC3C,MAAM,GAAG,GAA4B,EAAE,CAAC;IAExC,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACvD,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC3B,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;QACjB,CAAC;aAAM,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YACpC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,aAAa,CAAC,EAAE,CAAC;QAC7D,CAAC;aAAM,CAAC;YACN,GAAG,CAAC,IAAI,CAAC,GAAG;gBACV,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,aAAa,CAAC;gBAC1C,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC3D,CAAC;QACJ,CAAC;IACH,CAAC;IAED,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,oBAAoB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC7C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAClC,IAAsB,EACG,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC"}

package/dist/records/typed.d.ts

@@ -0,0 +1,71 @@
+/**
+ * `TypedRecordSet` — an immutable, decoded snapshot of rows bound to its
+ * `(rpc, model)` origin, with explicit, batched relation traversal — the
+ * CLASSIC tier of the records design (the classic `[id, name]`-pair protocol,
+ * works on 16+; the spec tier in `recordModel.ts` needs 17+). Traversal is always ONE `read` per relation per
+ * recordset — never per row — so the N+1 storm is structurally impossible: there
+ * is no per-record fetch API to misuse. The snapshot is never mutated; a fetch
+ * produces a fresh {@link RelatedMap}, and the caller joins explicitly.
+ */
+import { Effect, Schema } from "effect";
+import type { Rpc } from "../rpc.js";
+import type { TransportCallError } from "../transport.js";
+import { type RelatedMap } from "./related.js";
+import type { Many2OneRefValue } from "./relations.js";
+/** A decoded row must carry its `id` — every traversal and join keys on it. */
+export type HasId = {
+    readonly id: number;
+};
+/**
+ * The field names of `Row` whose decoded value is a many2one reference
+ * (`Many2OneRefValue | null`) — the only fields a relation can be traversed
+ * through. A compile-time constraint: passing any other key to
+ * {@link TypedRecordSet.fetchRelated}/`joinRelated` is a type error, not a
+ * runtime surprise.
+ */
+export type Many2OneRefField<Row> = {
+    readonly [K in keyof Row]: Row[K] extends Many2OneRefValue | null ? K : never;
+}[keyof Row];
+/**
+ * An immutable snapshot of typed rows with explicit relation traversal. Obtain
+ * one from `OdooClient.searchRecordsTyped`; it is bound to the `Rpc` seam and
+ * model it was read from so `fetchRelated` can batch a co-model `read`.
+ */
+export interface TypedRecordSet<Row extends HasId> extends Iterable<Row> {
+    /** The model these rows were read from. */
+    readonly model: string;
+    /** The decoded rows, in server order. Immutable. */
+    readonly rows: ReadonlyArray<Row>;
+    /** Each row's `id`, in row order. */
+    readonly ids: ReadonlyArray<number>;
+    /** The number of rows. */
+    readonly length: number;
+    /**
+     * Fetch the related records behind a many2one `field` in ONE batched `read`
+     * over the distinct, non-null ids across the whole snapshot, decoded through
+     * `schema`. Returns a {@link RelatedMap} keyed by related id — a fresh
+     * snapshot; the recordset is never back-filled.
+     *
+     * ZERO round trips when no row references a related record (all empty). The
+     * batched-single-read guarantee is the entire point of this API and is
+     * asserted in the tests, not merely documented.
+     */
+    readonly fetchRelated: <K extends Many2OneRefField<Row>, A extends HasId, I = A>(field: K, relatedModel: string, schema: Schema.Codec<A, I>, fields?: ReadonlyArray<string>) => Effect.Effect<RelatedMap<A>, TransportCallError>;
+    /**
+     * Like {@link fetchRelated}, but returns each row paired with its joined
+     * related record (`null` when the many2one is empty or unresolved). One
+     * explicit, batched call — named to keep "this is a fetch" legible at the call
+     * site.
+     */
+    readonly joinRelated: <K extends Many2OneRefField<Row>, A extends HasId, I = A>(field: K, relatedModel: string, schema: Schema.Codec<A, I>, fields?: ReadonlyArray<string>) => Effect.Effect<ReadonlyArray<readonly [Row, A | null]>, TransportCallError>;
+}
+/** The subset of the {@link Rpc} service {@link TypedRecordSet} depends on. */
+type RpcSeam = Pick<typeof Rpc.Service, "callKw">;
+/**
+ * Construct a {@link TypedRecordSet} over already-decoded rows. Internal: the
+ * public entry point is `OdooClient.searchRecordsTyped`, which owns the initial
+ * `search_read` decode and passes the resulting rows here.
+ */
+export declare const make: <Row extends HasId>(rpc: RpcSeam, model: string, rows: ReadonlyArray<Row>) => TypedRecordSet<Row>;
+export {};
+//# sourceMappingURL=typed.d.ts.map

package/dist/records/typed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typed.d.ts","sourceRoot":"","sources":["../../src/records/typed.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAExC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,EAAiC,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAC9E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,+EAA+E;AAC/E,MAAM,MAAM,KAAK,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5C;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,CAAC,GAAG,IAAI;IAClC,QAAQ,EAAE,CAAC,IAAI,MAAM,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,SAAS,gBAAgB,GAAG,IAAI,GAAG,CAAC,GAAG,KAAK;CAC9E,CAAC,MAAM,GAAG,CAAC,CAAC;AAEb;;;;GAIG;AACH,MAAM,WAAW,cAAc,CAAC,GAAG,SAAS,KAAK,CAAE,SAAQ,QAAQ,CAAC,GAAG,CAAC;IACtE,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,GAAG,CAAC,CAAC;IAClC,qCAAqC;IACrC,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACpC,0BAA0B;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB;;;;;;;;;OASG;IACH,QAAQ,CAAC,YAAY,EAAE,CAAC,CAAC,SAAS,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC,SAAS,KAAK,EAAE,CAAC,GAAG,CAAC,EAC7E,KAAK,EAAE,CAAC,EACR,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,MAAM,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,KAC3B,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,kBAAkB,CAAC,CAAC;IAEtD;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,SAAS,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC,SAAS,KAAK,EAAE,CAAC,GAAG,CAAC,EAC5E,KAAK,EAAE,CAAC,EACR,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,MAAM,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,KAC3B,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,SAAS,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,EAAE,kBAAkB,CAAC,CAAC;CACjF;AAED,+EAA+E;AAC/E,KAAK,OAAO,GAAG,IAAI,CAAC,OAAO,GAAG,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;AAoClD;;;;GAIG;AACH,eAAO,MAAM,IAAI,GAAI,GAAG,SAAS,KAAK,OAC/B,OAAO,SACL,MAAM,QACP,aAAa,CAAC,GAAG,CAAC,KACvB,cAAc,CAAC,GAAG,CAyDpB,CAAC"}