@adhd/apigen-base-logical 0.0.1

package/lib/codecs/byte.d.ts

@@ -0,0 +1,13 @@
+import { LogicalTypeCodec } from '../contracts';
+
+/**
+ * @stable Codec for `{type: 'string', format: 'byte'}`.
+ *
+ * Canonical wire (DESIGN §3): base64 **standard** variant (RFC 4648 §4) with
+ * padding. Uses `+` and `/` — NOT the URL-safe `-` and `_` variant.
+ *
+ * Host type: `Uint8Array`. Encode uses Node.js `Buffer.from` with the
+ * `'base64'` option; decode reconstructs a `Uint8Array` from the standard
+ * base64 string.
+ */
+export declare const byteCodec: LogicalTypeCodec<Uint8Array>;

package/lib/codecs/date-time.d.ts

@@ -0,0 +1,11 @@
+import { LogicalTypeCodec } from '../contracts';
+
+/**
+ * @stable Codec for `{type: 'string', format: 'date-time'}`.
+ *
+ * Canonical wire (DESIGN §3): RFC 3339 UTC string with ≥ms precision.
+ * `Date.prototype.toJSON` already emits this format; `toISOString()` is the
+ * explicit, deterministic form. Decode validates that the wire is a string
+ * before constructing a `Date`.
+ */
+export declare const dateTimeCodec: LogicalTypeCodec<Date>;

package/lib/codecs/decimal.d.ts

@@ -0,0 +1,29 @@
+import { LogicalTypeCodec } from '../contracts';
+
+/**
+ * @stable Branded primitive type for decimal values (mode:'branded', DESIGN §14.2).
+ *
+ * In TS the default decimal host type is a branded string — zero third-party
+ * deps; consumers that need rich arithmetic can opt in to `decimal.js`
+ * (DESIGN §14.2, §18 resolved decision). The brand prevents accidental
+ * narrowing to `string` at call-sites while keeping the runtime cost zero.
+ */
+export type DecimalString = string & {
+    readonly __brand: 'DecimalString';
+};
+/**
+ * @stable Wrap a plain string as a `DecimalString` branded type.
+ *
+ * No validation here; the codec validates on decode. Use `makeDecimal` for
+ * constructing values from literals or from external strings.
+ */
+export declare function makeDecimal(value: string): DecimalString;
+/**
+ * @stable Codec for `{type: 'string', format: 'decimal'}`.
+ *
+ * Canonical wire (DESIGN §3): decimal string (e.g. `"123.456"`), never a
+ * float. In TS the host type is the {@link DecimalString} branded string.
+ * The encode passes the string through; decode validates the format and brands
+ * the result.
+ */
+export declare const decimalCodec: LogicalTypeCodec<DecimalString>;

package/lib/codecs/index.d.ts

@@ -0,0 +1,24 @@
+import { LogicalTypeRegistry } from '../registry';
+
+export { dateTimeCodec } from './date-time';
+export type {} from './date-time';
+export { int64Codec } from './int64';
+export { decimalCodec, makeDecimal } from './decimal';
+export type { DecimalString } from './decimal';
+export { byteCodec } from './byte';
+export { uuidCodec } from './uuid';
+export { numberSpecialCodec } from './number-special';
+/**
+ * @stable Register all well-known scalar codecs into `registry`.
+ *
+ * Idempotent when called with `{override:true}` — subsequent calls replace
+ * existing registrations without throwing. Useful in test setups that
+ * reconstruct a registry per test.
+ *
+ * @param registry - The target registry (mutable — must not be frozen).
+ * @param opts.override - When `true`, re-registration does not throw
+ *   `E_DUP_CODEC`. Default: `false`.
+ */
+export declare function registerWellKnown(registry: LogicalTypeRegistry, opts?: {
+    override?: boolean;
+}): void;

package/lib/codecs/int64.d.ts

@@ -0,0 +1,12 @@
+import { LogicalTypeCodec } from '../contracts';
+
+/**
+ * @stable Codec for `{type: 'string', format: 'int64'}`.
+ *
+ * Canonical wire (DESIGN §3): decimal string (e.g. `"9007199254740993"`).
+ * Avoids JS f64 precision loss for values beyond `Number.MAX_SAFE_INTEGER`.
+ *
+ * Host type: `bigint`. The encode uses `String(bigint)` which emits a decimal
+ * string. Decode uses `BigInt(string)` which is exact over the full int64 range.
+ */
+export declare const int64Codec: LogicalTypeCodec<bigint>;

package/lib/codecs/number-special.d.ts

@@ -0,0 +1,22 @@
+import { LogicalTypeCodec } from '../contracts';
+
+/**
+ * @stable Codec for non-finite JavaScript numbers: `NaN`, `Infinity`, and
+ * `-Infinity` (DESIGN §3 row 13).
+ *
+ * Canonical wire: string sentinels `"NaN"`, `"Infinity"`, `"-Infinity"`.
+ * `JSON.stringify` maps these to `null` by default — this codec overrides that.
+ *
+ * The schema is `{type: 'number'}` (no `format` key). The `matches` predicate
+ * therefore checks only `type:'number'`; the codec is the **last-resort** scalar
+ * for bare number nodes. The registry resolves codecs in insertion order, so
+ * callers should register well-known codecs before arbitrary number ones — but
+ * this codec's encode/decode only fire when the registry dispatches it.
+ *
+ * Note: ordinary finite numbers at a `{type:'number'}` node are passed through
+ * without codec involvement (the registry returns `undefined` when no format
+ * is present and this codec is not registered). When this codec IS registered,
+ * encode maps finite numbers to their numeric value (plain JSON passthrough is
+ * done by the walk; encode is only called when the codec wins the dispatch).
+ */
+export declare const numberSpecialCodec: LogicalTypeCodec<number>;

package/lib/codecs/uuid.d.ts

@@ -0,0 +1,10 @@
+import { LogicalTypeCodec } from '../contracts';
+
+/**
+ * @stable Codec for `{type: 'string', format: 'uuid'}`.
+ *
+ * Canonical wire (DESIGN §3): lowercase hyphenated RFC 4122 UUID.
+ * Host type: `string` (UUIDs are naturally strings in TS). The codec
+ * normalizes uppercase input on encode to lowercase and validates on decode.
+ */
+export declare const uuidCodec: LogicalTypeCodec<string>;

package/lib/contracts.d.ts

@@ -0,0 +1,60 @@
+import { LogicalTypeRegistry } from './registry';
+
+/** @stable Stable identifier for a logical type.
+ *  Scalars: the JSON-Schema `format` (e.g. "date-time"). Nominal/union: a
+ *  namespace-qualified id (e.g. "cli.User"). */
+export type LogicalTypeId = string;
+/** @stable */
+export type LogicalKind = 'scalar' | 'nominal' | 'union' | 'map' | 'set';
+/** @stable The wire alphabet — exactly JSON's value space. */
+export type Wire = string | number | boolean | null | Wire[] | {
+    [k: string]: Wire;
+};
+/** @stable A resolved (no-$ref-at-root) JSON Schema node. */
+export type SchemaNode = Readonly<Record<string, unknown>>;
+/** @stable Threaded through a transcode walk. */
+export interface TranscodeCtx {
+    readonly registry: LogicalTypeRegistry;
+    readonly resolve: (ref: string) => SchemaNode;
+    readonly seen: WeakSet<object>;
+    readonly path: string;
+    readonly mode: 'strict' | 'lossy';
+}
+/** @stable Host-agnostic codec. One per logical type. Pure, deterministic, total over its domain. */
+export interface LogicalTypeCodec<Host = unknown> {
+    readonly id: LogicalTypeId;
+    readonly kind: LogicalKind;
+    /** Canonical schema fragment this codec owns (scalar: {type,format}; nominal: object $def). */
+    readonly schema: SchemaNode;
+    /** Structural, cheap test: does this codec own `node`? (format match, or x-apigen-codec===id). */
+    matches(node: SchemaNode): boolean;
+    /** Host -> wire. MUST NOT mutate `value`; MUST be deterministic. */
+    encode(value: Host, node: SchemaNode, ctx: TranscodeCtx): Wire;
+    /** Wire -> host. MUST validate-then-construct; MUST be the inverse of `encode` across the vectors. */
+    decode(wire: Wire, node: SchemaNode, ctx: TranscodeCtx): Host;
+}
+/** @stable A language's handling of one logical type (drives codegen). `$` = the value being transformed. */
+export interface TemplateCell {
+    encode: string;
+    decode: string;
+    imports?: string[];
+    dep?: {
+        name: string;
+        version: string;
+    };
+    mode: 'native' | 'lib' | 'branded';
+    construct?: string;
+    toJSON?: string;
+}
+/** @stable Used ONLY where the schema cannot disambiguate (type:{} / any). Plain JSON otherwise.
+ *  Wire: { "$apigen": "<LogicalTypeId>", "v": <Wire> }. */
+export declare const ENVELOPE_KEY: "$apigen";
+export interface ApigenEnvelope {
+    readonly [ENVELOPE_KEY]: LogicalTypeId;
+    readonly v: Wire;
+}
+/** @stable Schema-walking transcoder (impl is a LATER state — interface only here). */
+export interface Transcoder {
+    encode(value: unknown, schema: SchemaNode, ctx?: Partial<TranscodeCtx>): Wire;
+    decode(wire: Wire, schema: SchemaNode, ctx?: Partial<TranscodeCtx>): unknown;
+}

package/lib/descriptor-ext.d.ts

@@ -0,0 +1,25 @@
+import { LogicalKind, LogicalTypeId, SchemaNode } from './contracts';
+
+/** @stable Reserved descriptor keywords (advisory; structure via format/$ref/oneOf is authoritative). */
+export declare const X_APIGEN_LOGICAL: "x-apigen-logical";
+export declare const X_APIGEN_CODEC: "x-apigen-codec";
+export declare const X_APIGEN_CTOR: "x-apigen-ctor";
+export declare const X_APIGEN_TOJSON: "x-apigen-tojson";
+/** @stable Bumped on any wire-table OR pinned-lib-version change. */
+export declare const LOGICAL_TYPE_VERSION: "0.1.0";
+/**
+ * @stable Read the advisory `x-apigen-logical` hint off a resolved schema node.
+ *
+ * Per invariant `[inv:hints-advisory]` the key is OPTIONAL: returns `undefined`
+ * (never throws) when the key is absent or carries an unrecognized value. The
+ * authoritative kind is derived from structure (format/$ref/oneOf); this is a
+ * dispatch accelerator only.
+ */
+export declare function logicalKindOf(node: SchemaNode): LogicalKind | undefined;
+/**
+ * @stable Read the advisory `x-apigen-codec` id off a resolved schema node.
+ *
+ * Per invariant `[inv:hints-advisory]` the key is OPTIONAL: returns `undefined`
+ * (never throws) when the key is absent or not a string.
+ */
+export declare function codecIdOf(node: SchemaNode): LogicalTypeId | undefined;

package/lib/emit.d.ts

@@ -0,0 +1,113 @@
+import { LogicalTypeRegistry } from './registry';
+import { LogicalTypeId, SchemaNode, TemplateCell } from './contracts';
+
+/**
+ * @stable Generate-time emitter (DESIGN §11 codegen-first, §4.4 walk algorithm).
+ *
+ * apigen always knows the schema at generate-time, so we do NOT ship a
+ * schema-interpreting runtime transcoder per host. Instead, the generator walks
+ * the JSON-Schema node ONCE and emits a string expression of direct, typed
+ * (de)hydration glue, splicing per-language {@link TemplateCell} columns.
+ *
+ * Everything here is a PURE function over `(schema, registry, template table)`:
+ * deterministic, no I/O, no globals. The emitted text is host-language source
+ * (the minimal column shipped here is TypeScript) — `emit.ts` itself never runs
+ * it.
+ */
+/**
+ * @stable A per-language template table: maps a {@link LogicalTypeId} (the id a
+ * codec is registered under) to that language's {@link TemplateCell}.
+ *
+ * The registry tells us WHICH logical type owns a node; the table tells us HOW
+ * the target language (de)hydrates it. Splitting the two keeps the walk
+ * language-agnostic — swap the table to retarget a host.
+ */
+export type TemplateTable = Readonly<Record<LogicalTypeId, TemplateCell>>;
+/**
+ * @stable Threaded through an emit walk. Mirrors the structural inputs of a
+ * transcode (`registry` + `$ref` resolver) but carries codegen-only state: the
+ * language `table`, a JSON-Pointer `path` for diagnostics, a cycle guard over
+ * resolved `$ref` targets, and a monotonic counter that mints collision-free
+ * lambda parameter names for nested `map`/`object` glue.
+ */
+export interface EmitCtx {
+    /** Resolves which logical type owns a node (format / `x-apigen-codec`). */
+    readonly registry: LogicalTypeRegistry;
+    /** The active per-language template table. */
+    readonly table: TemplateTable;
+    /** `$ref` → `$def` resolver (root-bound). See {@link rootRefResolver}. */
+    readonly resolve: (ref: string) => SchemaNode;
+    /** JSON Pointer to the current node, for diagnostics. */
+    readonly path: string;
+    /** Cycle guard over `$ref` strings already on the active path. */
+    readonly seenRefs: ReadonlySet<string>;
+    /** Mints fresh lambda parameter names (`x0`, `x1`, …) for nested glue. */
+    readonly mint: () => string;
+}
+/**
+ * @stable Thrown when the schema cannot be lowered to glue in `strict` codegen
+ * (e.g. a `$ref` to a `$def` the resolver does not know, or a codec-owned node
+ * with no matching column in the active template table).
+ */
+export declare class EmitError extends Error {
+    /** Stable, transport-neutral error code. */
+    readonly code: "E_EMIT";
+    /** JSON Pointer to the offending node. */
+    readonly path: string;
+    constructor(message: string, path: string);
+}
+/**
+ * @stable Build the default `$ref` resolver for a generate-time walk: standard
+ * JSON-Schema `#/$defs/<name>` (and legacy `#/definitions/<name>`) lookup
+ * against a `root` document.
+ *
+ * @param root The schema document holding `$defs` / `definitions`.
+ * @returns A resolver suitable for {@link EmitCtx.resolve}.
+ */
+export declare function rootRefResolver(root: SchemaNode): (ref: string) => SchemaNode;
+/**
+ * @stable Construct an {@link EmitCtx} with sensible defaults.
+ *
+ * @param registry Resolves the owning codec for a node.
+ * @param table The target-language template table.
+ * @param opts.root Schema document for the default `$ref` resolver.
+ * @param opts.resolve Explicit `$ref` resolver (overrides `root`).
+ */
+export declare function createEmitCtx(registry: LogicalTypeRegistry, table: TemplateTable, opts?: {
+    root?: SchemaNode;
+    resolve?: (ref: string) => SchemaNode;
+}): EmitCtx;
+/**
+ * @stable Emit the host→wire expression for `valueExpr` at `node`.
+ *
+ * @param valueExpr The source expression holding the host value (e.g. `"data"`).
+ * @param node The resolved JSON-Schema node describing `valueExpr`.
+ * @param ctx The emit context (registry + table + resolver).
+ * @returns A target-language expression producing the wire value.
+ */
+export declare function emitEncode(valueExpr: string, node: SchemaNode, ctx: EmitCtx): string;
+/**
+ * @stable Emit the wire→host expression for `wireExpr` at `node`.
+ *
+ * @param wireExpr The source expression holding the wire value.
+ * @param node The resolved JSON-Schema node describing the host shape.
+ * @param ctx The emit context (registry + table + resolver).
+ * @returns A target-language expression reconstructing the host value.
+ */
+export declare function emitDecode(wireExpr: string, node: SchemaNode, ctx: EmitCtx): string;
+/**
+ * @stable The runtime helper pair the envelope fallback (§4.5) compiles against.
+ * Emitted glue references `__apigenEnvelopeEncode` / `__apigenEnvelopeDecode`;
+ * a host prelude provides them. Exposed as source so a generator can inline a
+ * prelude and so the wire shape (`{ $apigen, v }`) is asserted in one place.
+ */
+export declare const ENVELOPE_HELPER_SOURCE: string;
+/**
+ * @stable A minimal TypeScript template table covering the well-known scalar
+ * columns from DESIGN §13.2 (date-time, int64/bigint, byte/bytes). Sufficient
+ * to drive and test the walk; the full per-language tables land in later states.
+ *
+ * Keyed by the {@link LogicalTypeId} a scalar codec registers under (its JSON
+ * Schema `format`).
+ */
+export declare const TS_TEMPLATE_TABLE: TemplateTable;

package/lib/hints.d.ts

@@ -0,0 +1,86 @@
+import { TemplateCell } from './contracts';
+
+/**
+ * @stable The ordered list of well-known scalar logical-type ids, derived
+ * from the canonical codec set.  Every language column in {@link TEMPLATE_CELLS}
+ * MUST have an entry for each of these ids.
+ */
+export declare const CANONICAL_LOGICAL_TYPE_IDS: readonly [string, string, string, string, string, string];
+/** @stable Union of the canonical well-known scalar ids. */
+export type CanonicalLogicalTypeId = (typeof CANONICAL_LOGICAL_TYPE_IDS)[number];
+/**
+ * @stable A fully-keyed per-language template table: maps every canonical
+ * logical-type id to its {@link TemplateCell}.
+ */
+export type LanguageTable = Record<CanonicalLogicalTypeId, TemplateCell>;
+/**
+ * @stable The host languages for which a template column exists in
+ * {@link TEMPLATE_CELLS}.  `'typescript'` and `'python'` are fully filled
+ * (§13.2 values verbatim).  `'rust'`, `'go'`, and `'java'` are scaffolded —
+ * structure complete, expressions use stable placeholders pending the
+ * `lt-host-*` states.
+ */
+export type HostLanguage = 'typescript' | 'python' | 'rust' | 'go' | 'java';
+/**
+ * @stable The template-cell registry: `[language][logicalTypeId] → TemplateCell`.
+ *
+ * TypeScript and Python columns are fully filled per DESIGN §13.2 (verbatim
+ * expressions).  Rust, Go, and Java columns are scaffolded — structure complete,
+ * expressions use `__SCAFFOLD_*__` placeholders pending `lt-host-*` states.
+ *
+ * Keyed by {@link HostLanguage}, then by the canonical {@link CanonicalLogicalTypeId}.
+ */
+export declare const TEMPLATE_CELLS: Readonly<Record<HostLanguage, LanguageTable>>;
+/**
+ * @stable Return the template table for `language` from {@link TEMPLATE_CELLS}.
+ *
+ * This is the typed accessor the emitter uses to swap target languages —
+ * identical to `TEMPLATE_CELLS[language]` but carries the return type.
+ */
+export declare function cellsFor(language: HostLanguage): LanguageTable;
+/**
+ * @stable Return only the cells (from `language`'s column) for the given
+ * logical-type `ids`.  Useful when the emitter needs a focused sub-table.
+ */
+export declare function depsForLogicalTypes(ids: ReadonlyArray<string>, language: HostLanguage): Array<{
+    id: string;
+    dep: {
+        name: string;
+        version: string;
+    };
+}>;
+/**
+ * @stable Return the TypeScript `format → {name, version}` dep map for the
+ * CANONICAL well-known scalar ids.
+ *
+ * Per-surface minimal-manifest guarantee (DESIGN §14.1): only logical types
+ * that actually carry a `dep` entry appear in the map.  Stdlib types
+ * (`date-time`, `int64`, `byte`, `uuid`, `number-special`) have no dep and
+ * are absent — a surface that never uses `Decimal` never pulls `decimal.js`.
+ *
+ * This is the authoritative source for the inline `TS_LOGICAL_TYPE_DEP_MAP`
+ * in `packages/apigen/cli/src/lib/commands/generate.ts` — import this instead.
+ *
+ * @returns A record keyed by canonical logical-type id (= JSON-Schema `format`).
+ */
+export declare function tsDepMap(): Readonly<Record<string, {
+    name: string;
+    version: string;
+}>>;
+/**
+ * @stable Completeness guard: assert that every canonical logical-type id has
+ * a cell in `language`'s column of {@link TEMPLATE_CELLS}.
+ *
+ * This is the programmatic form of §13.3 ("no empty cells"). Throws if any
+ * canonical id is missing — enforces: add a logical type → every declared
+ * language column must fill it or this guard fires.
+ *
+ * The optional `_tableOverride` parameter exists ONLY for test injection
+ * (DEBT-LT-007): it lets a test drive the production throw path against a
+ * simulated incomplete column WITHOUT monkey-patching the frozen TEMPLATE_CELLS.
+ * Production callers must never pass it — the default (reading from
+ * TEMPLATE_CELLS) is always correct for production use.
+ *
+ * @throws {Error} With the missing ids listed, if any canonical id lacks a cell.
+ */
+export declare function assertNoEmptyCells(language: HostLanguage, _tableOverride?: Partial<LanguageTable>): void;

package/lib/registry.d.ts

@@ -0,0 +1,37 @@
+import { LogicalTypeCodec, LogicalTypeId, SchemaNode } from './contracts';
+
+/** @stable Keyed by LogicalTypeId. Scalars register by `format`; nominal/union by qualified id. */
+export interface LogicalTypeRegistry {
+    /** Register a codec. Throws E_DUP_CODEC on duplicate id unless `{override:true}`. */
+    register(codec: LogicalTypeCodec, opts?: {
+        override?: boolean;
+    }): void;
+    /** Resolve the codec owning a RESOLVED schema node, or undefined for a plain JSON node. */
+    resolve(node: SchemaNode): LogicalTypeCodec | undefined;
+    /** Direct lookup (for $ref / discriminator resolution). */
+    get(id: LogicalTypeId): LogicalTypeCodec | undefined;
+    /** Introspection (codegen, debugging). */
+    ids(): readonly LogicalTypeId[];
+    /** Frozen snapshot, safe to share across dispatch calls. */
+    freeze(): LogicalTypeRegistry;
+}
+/** @stable E_DUP_CODEC carrier — thrown on duplicate codec registration without `{override:true}`. */
+export declare class CodecRegistryError extends Error {
+    /** Stable, transport-neutral error code for duplicate-codec registration. */
+    readonly code: "E_DUP_CODEC";
+    constructor(message: string);
+}
+/**
+ * @stable Factory: a registry pre-loaded with the well-known scalar codecs.
+ *
+ * NOTE: This is the MINIMAL contract-spine stub. It provides the keyed-by-id
+ * store and `register`/`get`/`ids`/`freeze`/`resolve` plumbing with
+ * `E_DUP_CODEC` duplicate-detection only. Well-known scalar auto-loading
+ * (`opts.wellKnown`) and structural `resolve(node)` dispatch are LATER states —
+ * here `resolve` performs the trivial structural match the codec advertises via
+ * `matches(node)` so the spine is internally consistent, and `wellKnown` is
+ * accepted but not yet populated.
+ */
+export declare function createRegistry(opts?: {
+    wellKnown?: boolean;
+}): LogicalTypeRegistry;

package/lib/runmode.d.ts

@@ -0,0 +1,97 @@
+import { LogicalTypeRegistry } from './registry';
+import { LogicalTypeCodec, SchemaNode, Transcoder } from './contracts';
+
+/**
+ * @stable Validate all `$ref` values in a schema tree against a `$defs` dictionary.
+ *
+ * Walks `schema` recursively (into `properties`, `items`, `oneOf`, `$ref`,
+ * `additionalProperties`, `propertyNames`) and throws if any `$ref` value
+ * does not resolve to a key in `defs`.  Call this during schema generation
+ * (e.g., from `generate-schemas.ts`) to surface unresolvable `$ref` values at
+ * build time instead of at first runtime invocation (BUG-APIGEN-CORE-001).
+ *
+ * @param schema - The root schema node to validate.
+ * @param defs   - Dictionary of named definitions keyed by full `$ref` URI
+ *                 (e.g., `"#/$defs/MyType"`). If omitted, no cross-schema
+ *                 validation is performed and only the structural walk runs.
+ *
+ * @throws {Error} When any `$ref` in `schema` cannot be resolved against `defs`.
+ *
+ * @example
+ * ```ts
+ * const defs = { '#/$defs/User': { type: 'object', properties: { ... } } };
+ * validateSchemaRefs({ $ref: '#/$defs/User' }, defs); // ok
+ * validateSchemaRefs({ $ref: '#/$defs/Missing' }, defs);  // throws
+ * ```
+ */
+export declare function validateSchemaRefs(schema: SchemaNode, defs?: Readonly<Record<string, SchemaNode>>): void;
+/**
+ * @stable Build a compile-once, schema-walking `Transcoder` over a frozen
+ * registry snapshot.
+ *
+ * The returned transcoder is the **in-process (run-mode) analog** of the
+ * generate-time emitter: it walks `schema` and the value in lockstep at
+ * runtime, applying the registered codec at any node the codec claims, and
+ * recursing through object properties, array items, `$ref`, and `oneOf`
+ * branches (DESIGN.md §4.4 / §11).
+ *
+ * Call `registry.freeze()` before passing it here to guarantee a stable,
+ * immutable view across concurrent dispatch calls.
+ *
+ * ## DEBT-LT-006 — registration-order sensitivity of `encodeSchemaless`
+ *
+ * For schema-less positions (nodes with no `type` or `format`), the
+ * `encodeSchemaless` function inside this module iterates `registry.ids()` in
+ * **insertion order** and returns the FIRST codec whose `encode()` succeeds.
+ * This is a first-match-wins policy.
+ *
+ * **Consequence:** a permissive custom codec registered BEFORE the canonical
+ * well-known codecs (date-time, int64, decimal, etc.) could shadow them at
+ * schema-less positions, producing incorrect envelopes.  The standard
+ * registration order (via `registerWellKnown()`) is safe because the
+ * well-known codecs are inserted first.  Custom codecs should be registered
+ * AFTER `registerWellKnown()` unless they intentionally take priority.
+ *
+ * A future `priority`/`weight` field on `LogicalTypeCodec` would make this
+ * explicit and order-independent.
+ *
+ * @example
+ * ```ts
+ * const registry = createRegistry();
+ * registry.register(myDateCodec);
+ * const transcoder = buildTranscoder(registry.freeze());
+ *
+ * const wire = transcoder.encode(new Date(), { type: 'string', format: 'date-time' });
+ * const host = transcoder.decode(wire, { type: 'string', format: 'date-time' });
+ * ```
+ */
+export declare function buildTranscoder(registry: LogicalTypeRegistry): Transcoder;
+/**
+ * @stable Optional-peer-dep lazy registration (DESIGN.md §14.2).
+ *
+ * Attempts to register a codec by calling `loader()`. If `loader` throws a
+ * module-not-found error (the backing lib is absent), the registration is
+ * silently skipped. Any other error is re-thrown so programming mistakes
+ * surface immediately.
+ *
+ * This lets a consumer who never uses `Decimal` never install `decimal.js`
+ * and never pay for it. If a surface *does* use the type and the lib is
+ * absent, the fail-fast guard (§15.1) catches it at startup.
+ *
+ * @param registry - The registry to register into.
+ * @param _id      - Logical type id (informational; the codec carries its own).
+ * @param loader   - Synchronous factory that returns the codec. May throw
+ *                   `MODULE_NOT_FOUND` when the backing lib is absent.
+ *
+ * @example
+ * ```ts
+ * tryRegister(registry, 'decimal', () => {
+ *   // eslint-disable-next-line @typescript-eslint/no-require-imports
+ *   const { Decimal } = require('decimal.js');
+ *   return buildDecimalCodec(Decimal);
+ * });
+ * ```
+ */
+export declare function tryRegister(registry: LogicalTypeRegistry, _id: string, loader: () => LogicalTypeCodec): void;
+export type { Transcoder, SchemaNode, TranscodeCtx, Wire } from './contracts';
+export type { LogicalTypeRegistry } from './registry';

package/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "@adhd/apigen-base-logical",
+  "version": "0.0.1",
+  "main": "./index.js",
+  "module": "./index.mjs",
+  "typings": "./index.d.ts"
+}