@hodeinavarro/odoo-rpc-ts 0.2.0

package/src/records/recordModel.ts

@@ -0,0 +1,211 @@
+/**
+ * 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";
+import type { HasId } from "./typed.ts";
+
+/**
+ * Per-field compilation metadata: how {@link ./spec.ts} renders each field. The
+ * relation `child` is typed loosely (`RecordSpec<any, any>`) because `Schema` is
+ * invariant in its type parameter — a precisely-typed child spec is not
+ * assignable to a widened one, so the metadata graph is deliberately erased. The
+ * precise types live on {@link RecordSpec.schema} for decode; this metadata is
+ * only ever walked structurally by the pure compiler.
+ */
+export type FieldMeta =
+  | { readonly kind: "scalar" }
+  // oxlint-disable-next-line no-explicit-any -- Schema is invariant; see above.
+  | { readonly kind: "many2one"; readonly child: RecordSpec<any, any> }
+  | {
+      readonly kind: "one2many";
+      // oxlint-disable-next-line no-explicit-any -- Schema is invariant; see above.
+      readonly child: RecordSpec<any, any>;
+      readonly limit: number | undefined;
+    };
+
+/**
+ * A declared record model: its Odoo model name, the row decode `schema` (the
+ * whole nested graph), the per-field compilation `fields`, and whether it
+ * declares any relation (the version gate keys on this). Build one with
+ * {@link defineRecord}.
+ */
+export interface RecordSpec<A extends HasId, I = A> {
+  readonly model: string;
+  readonly schema: Schema.Codec<A, I>;
+  readonly fields: Readonly<Record<string, FieldMeta>>;
+  /** `true` iff at least one declared field is a many2one/one2many relation. */
+  readonly hasRelations: boolean;
+}
+
+/** A declared many2one relation field — nests a child {@link RecordSpec}. */
+export interface Many2OneDecl<A extends HasId, I> {
+  readonly _decl: "many2one";
+  readonly spec: RecordSpec<A, I>;
+}
+
+/** A declared one2many/many2many relation field — nests a child {@link RecordSpec}. */
+export interface One2ManyDecl<A extends HasId, I> {
+  readonly _decl: "one2many";
+  readonly spec: RecordSpec<A, I>;
+  readonly limit: number | undefined;
+}
+
+/**
+ * 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 = <A extends HasId, I>(spec: RecordSpec<A, I>): Many2OneDecl<A, I> => ({
+  _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 = <A extends HasId, I>(
+  spec: RecordSpec<A, I>,
+  options?: { readonly limit?: number },
+): One2ManyDecl<A, I> => ({ _decl: "one2many", spec, limit: options?.limit });
+
+/**
+ * A field of a {@link defineRecord} declaration: a scalar schema or a relation.
+ * The relation members are `any`-parameterized because `Schema` (inside the
+ * nested child spec) is invariant — a precisely-typed `Many2One(Company)` is not
+ * assignable to a widened `Many2OneDecl<HasId, unknown>`. Field-level types are
+ * recovered structurally by {@link FieldType}/{@link FieldEncoded} via `infer`.
+ */
+export type FieldInput =
+  | Schema.Top
+  // oxlint-disable-next-line no-explicit-any -- Schema invariance; see above.
+  | Many2OneDecl<any, any>
+  // oxlint-disable-next-line no-explicit-any -- Schema invariance; see above.
+  | One2ManyDecl<any, any>;
+
+/** The decoded (`Type`) value a declared field yields. */
+type FieldType<T> = T extends Many2OneDecl<infer A, infer _I>
+  ? A | null
+  : T extends One2ManyDecl<infer A, infer _I>
+    ? ReadonlyArray<A>
+    : T extends Schema.Top
+      ? T["Type"]
+      : never;
+
+/** The wire (`Encoded`) value a declared field maps from. */
+type FieldEncoded<T> = T extends Many2OneDecl<infer _A, infer I>
+  ? I | false
+  : T extends One2ManyDecl<infer _A, infer I>
+    ? ReadonlyArray<I>
+    : T extends Schema.Top
+      ? T["Encoded"]
+      : never;
+
+/** The decoded row type of a declaration `F` — always carries `id: number`. */
+export type RowType<F extends Record<string, FieldInput>> = {
+  readonly id: number;
+} & { readonly [K in keyof F]: FieldType<F[K]> };
+
+/** The wire row type of a declaration `F`. */
+export type RowEncoded<F extends Record<string, FieldInput>> = {
+  readonly id: number;
+} & { readonly [K in keyof F]: FieldEncoded<F[K]> };
+
+const isRelationDecl = (
+  value: FieldInput,
+  // oxlint-disable-next-line no-explicit-any -- Schema invariance; see FieldInput.
+): value is Many2OneDecl<any, any> | One2ManyDecl<any, any> =>
+  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: RecordSpec<any, any>): Schema.Top =>
+  Schema.Union([child.schema, Schema.Literal(false)]).pipe(
+    Schema.decodeTo(
+      Schema.NullOr(Schema.toType(child.schema)),
+      SchemaTransformation.transform({
+        decode: (wire: unknown) => (wire === false ? null : wire),
+        encode: (value: unknown) => (value === null ? (false as const) : 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 = <F extends Record<string, FieldInput>>(
+  model: string,
+  fields: F,
+): RecordSpec<RowType<F>, RowEncoded<F>> => {
+  const structFields: Record<string, Schema.Top> = { id: Schema.Number };
+  const meta: Record<string, FieldMeta> = { 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) as unknown as Schema.Codec<RowType<F>, RowEncoded<F>>;
+  const hasRelations = Object.values(meta).some((m) => m.kind !== "scalar");
+
+  return { model, schema, fields: meta, hasRelations };
+};

package/src/records/related.ts

@@ -0,0 +1,80 @@
+/**
+ * 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.ts";
+
+/** 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 const refId = (ref: RefOrId): number | null => {
+  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 = <Row>(
+  rows: ReadonlyArray<Row>,
+  accessor: (row: Row) => RefOrId,
+): ReadonlyArray<number> => {
+  const seen = new Set<number>();
+  const out: number[] = [];
+  for (const row of rows) {
+    const id = refId(accessor(row));
+    if (id !== null && !seen.has(id)) {
+      seen.add(id);
+      out.push(id);
+    }
+  }
+  return out;
+};
+
+/**
+ * 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 const makeRelatedMap = <A extends { readonly id: number }>(
+  rows: ReadonlyArray<A>,
+): RelatedMap<A> => {
+  const byId = new Map<number, A>();
+  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,
+  };
+};

package/src/records/relations.ts

@@ -0,0 +1,192 @@
+/**
+ * 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";
+
+// --- many2one references ----------------------------------------------------
+
+/**
+ * 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 const Many2OneRefValue: Schema.Codec<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: Schema.Codec<Many2OneRefValue, readonly [number, string]> =
+  Many2OneWirePair.pipe(
+    Schema.decodeTo(
+      Many2OneRefValue,
+      SchemaTransformation.transform({
+        decode: ([id, name]) => ({ id, name }),
+        encode: ({ id, name }) => [id, name] as const,
+      }),
+    ),
+  );
+
+/** 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: Schema.Codec<
+  Many2OneRefValue | null,
+  readonly [number, string] | false
+> = 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 as const) : ([value.id, value.name] as const)),
+    }),
+  ),
+);
+
+// --- 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: number, width: number): string => n.toString().padStart(width, "0");
+
+const formatUtcDate = (date: Date): string =>
+  `${pad(date.getUTCFullYear(), 4)}-${pad(date.getUTCMonth() + 1, 2)}-${pad(date.getUTCDate(), 2)}`;
+
+const formatUtcDateTime = (date: Date): string =>
+  `${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: unknown, message: string): SchemaIssue.InvalidValue =>
+  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.Codec<Date, string> = 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.Codec<Date, string> = 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.Codec<Date, string>,
+): Schema.Codec<Date | null, string | false> =>
+  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 as const)
+            : SchemaParser.encodeUnknownEffect(base)(value, options),
+      }),
+    ),
+  );
+
+/** {@link OdooDate} with Odoo's `false` empty decoding to `null`. */
+export const OdooDateOrNull: Schema.Codec<Date | null, string | false> = orFalseNull(OdooDate);
+
+/** {@link OdooDateTime} with Odoo's `false` empty decoding to `null`. */
+export const OdooDateTimeOrNull: Schema.Codec<Date | null, string | false> =
+  orFalseNull(OdooDateTime);

package/src/records/spec.ts

@@ -0,0 +1,96 @@
+/**
+ * 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.ts";
+import type { HasId } from "./typed.ts";
+
+/** 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 {
+  readonly path: ReadonlyArray<string>;
+  constructor(path: ReadonlyArray<string>) {
+    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 {
+  readonly model: string;
+  constructor(model: string) {
+    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 = <A extends HasId, I>(spec: RecordSpec<A, I>): boolean =>
+  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: RecordSpec<any, any>,
+  ancestors: ReadonlyArray<RecordSpec<any, any>>,
+): Record<string, unknown> => {
+  if (ancestors.includes(spec)) {
+    throw new RecordSpecCycleError([...ancestors.map((a) => a.model), spec.model]);
+  }
+  const nextAncestors = [...ancestors, spec];
+  const out: Record<string, unknown> = {};
+
+  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 = <A extends HasId, I>(
+  spec: RecordSpec<A, I>,
+): Record<string, unknown> => compile(spec, []);