@adhd/apigen-base-logical 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,3 +1,25 @@
+## 0.1.1 (2026-08-07)
+
+
+### 🚀 Features
+
+- **apigen:** schema-driven worked examples for MCP tool descriptions + validation errors
+
+- **apigen-base-logical:** fill JAVA_COLUMN codec expressions (FEAT-APIGEN-001 1/3)
+
+
+### 🩹 Fixes
+
+- **apigen-java:** mirror PYTHON_MATRIX_SCRIPT's decode+invariant-diff negative-control algorithm exactly (FEAT-APIGEN-001 review)
+
+- **apigen-cli:** restore 2768 files mass-deleted by 0117eb22 (BUG-APIGEN-052)
+
+
+### ❤️  Thank You
+
+- parity-harness-self-test
+- pseudosky
+
 ## 0.0.6 (2026-07-25)
 
 

package/README.md

@@ -34,3 +34,39 @@ The `x-apigen-*` descriptor keys are **optional** dispatch accelerators —
 structure (`format`/`$ref`/`oneOf`) is authoritative. `logicalKindOf` and
 `codecIdOf` therefore return `undefined` (never throw) when a key is absent or
 malformed; correctness must never depend on a hint being present.
+
+## Schema example synthesis (shipped, unlike the contract-spine surface above)
+
+`synthesizeExample(schema)` / `renderExampleNote(schema)` — generates a
+concrete, plausible example value from any JSON Schema: walks `properties`/
+`required`, resolves `$ref` against the schema's own `definitions`/`$defs`,
+picks a `oneOf`/`anyOf` branch, merges `allOf`, and produces format-aware
+placeholders (`date-time`, `uuid`, `email`, `decimal`, `int64`, `byte`, etc.)
+that satisfy `ajv-formats`. Every synthesized shape round-trips through real
+AJV validation in this package's own tests.
+
+This exists to solve a concrete discoverability problem: an apigen-mounted
+MCP tool's description/error used to only describe the *shape* of a valid
+call ("all domain parameters go inside a `data` envelope"), never a *worked
+example* with real field names — so callers repeatedly got the call shape
+wrong on the first try. `renderExampleNote` is consumed by:
+
+- `@adhd/apigen-engine-runtime`'s `buildToolDescription` — appends a
+  synthesized example to every apigen-mounted tool's description.
+- `@adhd/apigen-engine-runtime`'s validate-Layer — appends the same
+  synthesized example to AJV validation-failure error messages, so a
+  rejected call comes back with both what was wrong *and* a working example.
+
+Because synthesis is schema-driven (not hand-written per tool), it covers
+every current and future apigen-mounted MCP tool automatically, including
+mount-derived tools (e.g. `apigen-plugin-batch`'s `_batch/<kind>` mounts)
+whose top-level shape differs from the `{data:{...}}` envelope regular
+extracted operations use — the synthesized example always reflects each
+tool's own real, advertised schema, never an assumed universal convention.
+
+```ts
+import { renderExampleNote } from '@adhd/apigen-base-logical';
+
+renderExampleNote(someOperation.input);
+// → 'Example: {"data":{"input":{"family":"<string>","title":"<string>","body":"<string>","repo":"<string>"}}}'
+```

package/index.d.ts

@@ -6,5 +6,7 @@ export { X_APIGEN_LOGICAL, X_APIGEN_CODEC, X_APIGEN_CTOR, X_APIGEN_TOJSON, LOGIC
 export { buildTranscoder, tryRegister, validateSchemaRefs } from './lib/runmode';
 export { dateTimeCodec, int64Codec, decimalCodec, makeDecimal, byteCodec, uuidCodec, numberSpecialCodec, registerWellKnown, } from './lib/codecs/index';
 export type { DecimalString } from './lib/codecs/index';
+export { synthesizeExample, renderExampleNote } from './lib/example';
+export type { JsonSchemaLike } from './lib/example';
 export { CANONICAL_LOGICAL_TYPE_IDS, TEMPLATE_CELLS, cellsFor, depsForLogicalTypes, tsDepMap, assertNoEmptyCells, } from './lib/hints';
 export type { CanonicalLogicalTypeId, HostLanguage, LanguageTable, } from './lib/hints';

package/index.js

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const l="$apigen";class C extends Error{constructor(o){super(o),this.code="E_DUP_CODEC",this.name="CodecRegistryError"}}function P(e){e==null||e.wellKnown;const o=new Map;return{register(n,r){if(o.has(n.id)&&!(r!=null&&r.override))throw new C(`E_DUP_CODEC: a codec is already registered for id "${n.id}"`);o.set(n.id,n)},resolve(n){for(const r of o.values())if(r.matches(n))return r},get(n){return o.get(n)},ids(){return[...o.keys()]},freeze(){const n=new Map(o),r={register(){throw new C("E_DUP_CODEC: registry is frozen and cannot accept new codecs")},resolve(d){for(const a of n.values())if(a.matches(d))return a},get(d){return n.get(d)},ids(){return[...n.keys()]},freeze(){return r}};return r}}}const $="x-apigen-logical",v="x-apigen-codec",j="x-apigen-ctor",M="x-apigen-tojson",R="0.1.0",G=["scalar","nominal","union","map","set"];function w(e){const o=e[$];return typeof o=="string"&&G.includes(o)?o:void 0}function B(e){const o=e[v];return typeof o=="string"?o:void 0}function T(e,o){return{registry:e,resolve:t=>{throw new Error(`[apigen-logical] $ref "${t}" cannot be resolved in run-mode without a descriptor root. Supply a resolve() in the ctx override to handle $ref.`)},seen:new WeakSet,path:"",mode:"strict",...o}}function p(e,o,t){const n=t.registry.resolve(o);if(n)return n.encode(e,o,t);const r=o.$ref;if(typeof r=="string"){const i=t.resolve(r);return p(e,i,t)}const d=o.oneOf;if(Array.isArray(d)){const i=U(e,d,o);return p(e,i,t)}const a=o.type;if(a==="array"){if(!Array.isArray(e))return D(e,o,t);const i=o.items;if(!i)return e.map(c=>u(c));const f=t.path;return Array.isArray(i)?e.map((c,_)=>{const s=i[_];return s===void 0?u(c):p(c,s,{...t,path:`${f}/${_}`})}):e.map((c,_)=>p(c,i,{...t,path:`${f}/${_}`}))}if(a==="object"){if(e===null||typeof e!="object"||Array.isArray(e))return D(e,o,t);const i=o.properties;if(!i)return u(e);const f=t.path,c={};for(const[_,s]of Object.entries(i)){const m=e[_];m!==void 0&&(c[_]=p(m,s,{...t,path:`${f}/${_}`}))}return c}return a==null?D(e,o,t):u(e)}function E(e,o,t){const n=t.registry.resolve(o);if(n)return n.decode(e,o,t);const r=o.$ref;if(typeof r=="string"){const i=t.resolve(r);return E(e,i,t)}const d=o.oneOf;if(Array.isArray(d)){const i=U(e,d,o);return E(e,i,t)}const a=o.type;if(a==="array"){if(!Array.isArray(e))return e;const i=o.items;if(!i)return e;const f=t.path;return Array.isArray(i)?e.map((c,_)=>{const s=i[_];return s===void 0?c:E(c,s,{...t,path:`${f}/${_}`})}):e.map((c,_)=>E(c,i,{...t,path:`${f}/${_}`}))}if(a==="object"){if(e===null||typeof e!="object"||Array.isArray(e))return e;const i=o.properties;if(!i)return e;const f=t.path,c={};for(const[_,s]of Object.entries(i)){const m=e[_];m!==void 0&&(c[_]=E(m,s,{...t,path:`${f}/${_}`}))}return c}return a==null?k(e,t):e}function U(e,o,t,n){const r=t.discriminator;if(r!=null&&r.propertyName){const d=e!==null&&typeof e=="object"?e[r.propertyName]:void 0;if(typeof d=="string"&&r.mapping){const a=r.mapping[d];if(a){const i=o.find(f=>f.$ref===a);if(i)return i}}}return o[0]??{}}function D(e,o,t){for(const n of t.registry.ids()){const r=t.registry.get(n);if(r)try{const d=r.encode(e,r.schema,t);return{[l]:n,v:d}}catch{}}return u(e)}function k(e,o){if(e!==null&&typeof e=="object"&&!Array.isArray(e)&&l in e){const t=e,n=t[l],r=o.registry.get(n);if(r)return r.decode(t.v,r.schema,o)}return e}function u(e){if(e===null||typeof e=="string"||typeof e=="number"||typeof e=="boolean")return e;if(Array.isArray(e))return e.map(u);if(typeof e=="object"){const o={};for(const[t,n]of Object.entries(e))n!==void 0&&(o[t]=u(n));return o}return null}function J(e,o){const t=new Set,n=[e];for(;n.length>0;){const r=n.pop();if(!r||t.has(r))continue;t.add(r);const d=r.$ref;if(typeof d=="string"){if(o){const s=o[d];if(!s){const m=Object.keys(o).join(", ")||"(none)";throw new Error(`[apigen-logical] $ref "${d}" cannot be resolved. Available $defs: ${m}`)}n.push(s)}continue}const a=r.oneOf;if(Array.isArray(a))for(const s of a)typeof s=="object"&&s!==null&&n.push(s);const i=r.properties;if(i)for(const s of Object.values(i))n.push(s);const f=r.items;if(Array.isArray(f))for(const s of f)typeof s=="object"&&s!==null&&n.push(s);else typeof f=="object"&&f!==null&&n.push(f);const c=r.additionalProperties;typeof c=="object"&&c!==null&&n.push(c);const _=r.propertyNames;typeof _=="object"&&_!==null&&n.push(_)}}function V(e){return{encode(o,t,n){const r=T(e,n);return p(o,t,r)},decode(o,t,n){const r=T(e,n);return E(o,t,r)}}}function Y(e,o,t){try{const n=t();e.register(n)}catch(n){if(K(n))return;throw n}}function K(e){return e===null||typeof e!="object"?!1:e.code==="MODULE_NOT_FOUND"}const h={id:"date-time",kind:"scalar",schema:{type:"string",format:"date-time"},matches(e){return e.type==="string"&&e.format==="date-time"},encode(e,o,t){return e.toISOString()},decode(e,o,t){if(typeof e!="string"){if(t.mode==="strict")throw new TypeError(`[date-time] expected a string on the wire at "${t.path}", got ${typeof e}`);return new Date(String(e))}if(t.mode==="strict"&&Number.isNaN(new Date(e).getTime()))throw new TypeError(`[date-time] invalid date-time string at "${t.path}": ${JSON.stringify(e)}`);return new Date(e)}},S={id:"int64",kind:"scalar",schema:{type:"string",format:"int64"},matches(e){return e.type==="string"&&e.format==="int64"},encode(e,o,t){return String(e)},decode(e,o,t){if(typeof e!="string"){if(t.mode==="strict")throw new TypeError(`[int64] expected a string on the wire at "${t.path}", got ${typeof e}`);try{return BigInt(Math.trunc(Number(e)))}catch{return BigInt(0)}}if(t.mode==="strict")return BigInt(e);if(/^-?\d+$/.test(e))try{return BigInt(e)}catch{return BigInt(0)}return BigInt(0)}};function W(e){return e}const N={id:"decimal",kind:"scalar",schema:{type:"string",format:"decimal"},matches(e){return e.type==="string"&&e.format==="decimal"},encode(e,o,t){return e},decode(e,o,t){if(typeof e!="string"){if(t.mode==="strict")throw new TypeError(`[decimal] expected a string on the wire at "${t.path}", got ${typeof e}`);return String(e)}if(t.mode==="strict"&&!/^-?\d+(\.\d+)?$/.test(e))throw new TypeError(`[decimal] wire value "${e}" at "${t.path}" is not a valid decimal string`);return e}},b={id:"byte",kind:"scalar",schema:{type:"string",format:"byte"},matches(e){return e.type==="string"&&e.format==="byte"},encode(e,o,t){return Buffer.from(e).toString("base64")},decode(e,o,t){if(typeof e!="string"){if(t.mode==="strict")throw new TypeError(`[byte] expected a base64 string on the wire at "${t.path}", got ${typeof e}`);return new Uint8Array(0)}if(t.mode==="strict"&&!/^[A-Za-z0-9+/]*={0,2}$/.test(e))throw new TypeError(`[byte] wire value at "${t.path}" is not standard base64 (format:byte): "${e}"`);return new Uint8Array(Buffer.from(e,"base64"))}},z=/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/,L={id:"uuid",kind:"scalar",schema:{type:"string",format:"uuid"},matches(e){return e.type==="string"&&e.format==="uuid"},encode(e,o,t){return e.toLowerCase()},decode(e,o,t){if(typeof e!="string"){if(t.mode==="strict")throw new TypeError(`[uuid] expected a string on the wire at "${t.path}", got ${typeof e}`);return String(e).toLowerCase()}if(t.mode==="strict"&&!z.test(e))throw new TypeError(`[uuid] wire value "${e}" at "${t.path}" is not a lowercase-hyphenated RFC 4122 UUID`);return e}},O="NaN",A="Infinity",g="-Infinity",X=new Set([O,A,g]),F={id:"number-special",kind:"scalar",schema:{type:"number"},matches(e){return e.type==="number"&&e.format===void 0},encode(e,o,t){return Number.isNaN(e)?O:e===1/0?A:e===-1/0?g:e},decode(e,o,t){if(typeof e=="number")return e;if(typeof e=="string"){if(e===O)return NaN;if(e===A)return 1/0;if(e===g)return-1/0;const n=Number(e);if(!Number.isNaN(n))return n}if(t.mode==="strict")throw new TypeError(`[number-special] unrecognized wire value at "${t.path}": ${JSON.stringify(e)}. Expected a number or one of ${[...X].join(", ")}.`);return NaN}},H=[h,S,N,b,L,F];function Z(e,o={}){for(const t of H)e.register(t,{override:o.override??!1})}const I=[h.id,S.id,N.id,b.id,L.id,F.id],q={"date-time":{encode:"$.toISOString()",decode:"new Date($)",mode:"native"},int64:{encode:"String($)",decode:"BigInt($)",mode:"native"},decimal:{encode:"$.toString()",decode:"new Decimal($)",imports:[],dep:{name:"decimal.js",version:"^10"},mode:"branded"},byte:{encode:"Buffer.from($).toString('base64')",decode:"new Uint8Array(Buffer.from($, 'base64'))",mode:"native"},uuid:{encode:"$.toLowerCase()",decode:"$",mode:"native"},"number-special":{encode:"numToWire($)",decode:"wireToNum($)",mode:"native"}},Q={"date-time":{encode:"$.isoformat()",decode:"datetime.fromisoformat($)",imports:["from datetime import datetime"],mode:"native"},int64:{encode:"str($)",decode:"int($)",mode:"native"},decimal:{encode:"str($)",decode:"Decimal($)",imports:["from decimal import Decimal"],mode:"native"},byte:{encode:"b64encode($).decode()",decode:"b64decode($)",imports:["from base64 import b64encode, b64decode"],mode:"native"},uuid:{encode:"str($)",decode:"UUID($)",imports:["from uuid import UUID"],mode:"native"},"number-special":{encode:"num_to_wire($)",decode:"wire_to_num($)",mode:"native"}},x={"date-time":{encode:"__SCAFFOLD_RUST_DATETIME_ENCODE__",decode:"__SCAFFOLD_RUST_DATETIME_DECODE__",imports:["use chrono::{DateTime, Utc};"],dep:{name:"chrono",version:"^0.4"},mode:"lib"},int64:{encode:"__SCAFFOLD_RUST_INT64_ENCODE__",decode:"__SCAFFOLD_RUST_INT64_DECODE__",imports:["use serde_with::DisplayFromStr;"],dep:{name:"serde_with",version:"^3"},mode:"lib"},decimal:{encode:"__SCAFFOLD_RUST_DECIMAL_ENCODE__",decode:"__SCAFFOLD_RUST_DECIMAL_DECODE__",imports:["use rust_decimal::Decimal;"],dep:{name:"rust_decimal",version:"^1"},mode:"lib"},byte:{encode:"__SCAFFOLD_RUST_BYTE_ENCODE__",decode:"__SCAFFOLD_RUST_BYTE_DECODE__",imports:["use serde_with::base64::Base64;"],dep:{name:"serde_with",version:"^3"},mode:"lib"},uuid:{encode:"__SCAFFOLD_RUST_UUID_ENCODE__",decode:"__SCAFFOLD_RUST_UUID_DECODE__",imports:["use uuid::Uuid;"],dep:{name:"uuid",version:"^1"},mode:"lib"},"number-special":{encode:"__SCAFFOLD_RUST_NUMSPECIAL_ENCODE__",decode:"__SCAFFOLD_RUST_NUMSPECIAL_DECODE__",mode:"native"}},ee={"date-time":{encode:"__SCAFFOLD_GO_DATETIME_ENCODE__",decode:"__SCAFFOLD_GO_DATETIME_DECODE__",imports:['"time"'],mode:"native"},int64:{encode:"__SCAFFOLD_GO_INT64_ENCODE__",decode:"__SCAFFOLD_GO_INT64_DECODE__",imports:['"strconv"'],mode:"native"},decimal:{encode:"__SCAFFOLD_GO_DECIMAL_ENCODE__",decode:"__SCAFFOLD_GO_DECIMAL_DECODE__",imports:['"github.com/shopspring/decimal"'],dep:{name:"github.com/shopspring/decimal",version:"v1"},mode:"lib"},byte:{encode:"__SCAFFOLD_GO_BYTE_ENCODE__",decode:"__SCAFFOLD_GO_BYTE_DECODE__",imports:['"encoding/base64"'],mode:"native"},uuid:{encode:"__SCAFFOLD_GO_UUID_ENCODE__",decode:"__SCAFFOLD_GO_UUID_DECODE__",imports:['"github.com/google/uuid"'],dep:{name:"github.com/google/uuid",version:"v1"},mode:"lib"},"number-special":{encode:"__SCAFFOLD_GO_NUMSPECIAL_ENCODE__",decode:"__SCAFFOLD_GO_NUMSPECIAL_DECODE__",mode:"native"}},te={"date-time":{encode:"__SCAFFOLD_JAVA_DATETIME_ENCODE__",decode:"__SCAFFOLD_JAVA_DATETIME_DECODE__",imports:["import java.time.Instant;"],dep:{name:"jackson-datatype-jsr310",version:"2.x"},mode:"lib"},int64:{encode:"__SCAFFOLD_JAVA_INT64_ENCODE__",decode:"__SCAFFOLD_JAVA_INT64_DECODE__",imports:["import com.fasterxml.jackson.annotation.JsonFormat;"],mode:"native"},decimal:{encode:"__SCAFFOLD_JAVA_DECIMAL_ENCODE__",decode:"__SCAFFOLD_JAVA_DECIMAL_DECODE__",imports:["import java.math.BigDecimal;"],mode:"native"},byte:{encode:"__SCAFFOLD_JAVA_BYTE_ENCODE__",decode:"__SCAFFOLD_JAVA_BYTE_DECODE__",mode:"native"},uuid:{encode:"__SCAFFOLD_JAVA_UUID_ENCODE__",decode:"__SCAFFOLD_JAVA_UUID_DECODE__",imports:["import java.util.UUID;"],mode:"native"},"number-special":{encode:"__SCAFFOLD_JAVA_NUMSPECIAL_ENCODE__",decode:"__SCAFFOLD_JAVA_NUMSPECIAL_DECODE__",mode:"native"}},y=Object.freeze({typescript:q,python:Q,rust:x,go:ee,java:te});function oe(e){return y[e]}function ne(e,o){const t=y[o],n=[];for(const r of e){const d=t[r];d!=null&&d.dep&&n.push({id:r,dep:d.dep})}return n}function re(){const e=y.typescript,o={};for(const t of I){const n=e[t].dep;n&&(o[t]=n)}return Object.freeze(o)}function ie(e,o){const t=o??y[e],n=[];for(const r of I)t[r]||n.push(r);if(n.length>0)throw new Error(`[hints] assertNoEmptyCells: language "${e}" is missing cells for: ${n.join(", ")}`)}exports.CANONICAL_LOGICAL_TYPE_IDS=I;exports.CodecRegistryError=C;exports.ENVELOPE_KEY=l;exports.LOGICAL_TYPE_VERSION=R;exports.TEMPLATE_CELLS=y;exports.X_APIGEN_CODEC=v;exports.X_APIGEN_CTOR=j;exports.X_APIGEN_LOGICAL=$;exports.X_APIGEN_TOJSON=M;exports.assertNoEmptyCells=ie;exports.buildTranscoder=V;exports.byteCodec=b;exports.cellsFor=oe;exports.codecIdOf=B;exports.createRegistry=P;exports.dateTimeCodec=h;exports.decimalCodec=N;exports.depsForLogicalTypes=ne;exports.int64Codec=S;exports.logicalKindOf=w;exports.makeDecimal=W;exports.numberSpecialCodec=F;exports.registerWellKnown=Z;exports.tryRegister=Y;exports.tsDepMap=re;exports.uuidCodec=L;exports.validateSchemaRefs=J;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const g="$apigen";class C extends Error{constructor(r){super(r),this.code="E_DUP_CODEC",this.name="CodecRegistryError"}}function G(e){e==null||e.wellKnown;const r=new Map;return{register(n,o){if(r.has(n.id)&&!(o!=null&&o.override))throw new C(`E_DUP_CODEC: a codec is already registered for id "${n.id}"`);r.set(n.id,n)},resolve(n){for(const o of r.values())if(o.matches(n))return o},get(n){return r.get(n)},ids(){return[...r.keys()]},freeze(){const n=new Map(r),o={register(){throw new C("E_DUP_CODEC: registry is frozen and cannot accept new codecs")},resolve(i){for(const c of n.values())if(c.matches(i))return c},get(i){return n.get(i)},ids(){return[...n.keys()]},freeze(){return o}};return o}}}const j="x-apigen-logical",R="x-apigen-codec",M="x-apigen-ctor",k="x-apigen-tojson",w="0.1.0",z=["scalar","nominal","union","map","set"];function B(e){const r=e[j];return typeof r=="string"&&z.includes(r)?r:void 0}function J(e){const r=e[R];return typeof r=="string"?r:void 0}function L(e,r){return{registry:e,resolve:t=>{throw new Error(`[apigen-logical] $ref "${t}" cannot be resolved in run-mode without a descriptor root. Supply a resolve() in the ctx override to handle $ref.`)},seen:new WeakSet,path:"",mode:"strict",...r}}function m(e,r,t){const n=t.registry.resolve(r);if(n)return n.encode(e,r,t);const o=r.$ref;if(typeof o=="string"){const s=t.resolve(o);return m(e,s,t)}const i=r.oneOf;if(Array.isArray(i)){const s=P(e,i,r);return m(e,s,t)}const c=r.type;if(c==="array"){if(!Array.isArray(e))return O(e,r,t);const s=r.items;if(!s)return e.map(a=>_(a));const u=t.path;return Array.isArray(s)?e.map((a,f)=>{const d=s[f];return d===void 0?_(a):m(a,d,{...t,path:`${u}/${f}`})}):e.map((a,f)=>m(a,s,{...t,path:`${u}/${f}`}))}if(c==="object"){if(e===null||typeof e!="object"||Array.isArray(e))return O(e,r,t);const s=r.properties;if(!s)return _(e);const u=t.path,a={};for(const[f,d]of Object.entries(s)){const p=e[f];p!==void 0&&(a[f]=m(p,d,{...t,path:`${u}/${f}`}))}return a}return c==null?O(e,r,t):_(e)}function l(e,r,t){const n=t.registry.resolve(r);if(n)return n.decode(e,r,t);const o=r.$ref;if(typeof o=="string"){const s=t.resolve(o);return l(e,s,t)}const i=r.oneOf;if(Array.isArray(i)){const s=P(e,i,r);return l(e,s,t)}const c=r.type;if(c==="array"){if(!Array.isArray(e))return e;const s=r.items;if(!s)return e;const u=t.path;return Array.isArray(s)?e.map((a,f)=>{const d=s[f];return d===void 0?a:l(a,d,{...t,path:`${u}/${f}`})}):e.map((a,f)=>l(a,s,{...t,path:`${u}/${f}`}))}if(c==="object"){if(e===null||typeof e!="object"||Array.isArray(e))return e;const s=r.properties;if(!s)return e;const u=t.path,a={};for(const[f,d]of Object.entries(s)){const p=e[f];p!==void 0&&(a[f]=l(p,d,{...t,path:`${u}/${f}`}))}return a}return c==null?Y(e,t):e}function P(e,r,t,n){const o=t.discriminator;if(o!=null&&o.propertyName){const i=e!==null&&typeof e=="object"?e[o.propertyName]:void 0;if(typeof i=="string"&&o.mapping){const c=o.mapping[i];if(c){const s=r.find(u=>u.$ref===c);if(s)return s}}}return r[0]??{}}function O(e,r,t){for(const n of t.registry.ids()){const o=t.registry.get(n);if(o)try{const i=o.encode(e,o.schema,t);return{[g]:n,v:i}}catch{}}return _(e)}function Y(e,r){if(e!==null&&typeof e=="object"&&!Array.isArray(e)&&g in e){const t=e,n=t[g],o=r.registry.get(n);if(o)return o.decode(t.v,o.schema,r)}return e}function _(e){if(e===null||typeof e=="string"||typeof e=="number"||typeof e=="boolean")return e;if(Array.isArray(e))return e.map(_);if(typeof e=="object"){const r={};for(const[t,n]of Object.entries(e))n!==void 0&&(r[t]=_(n));return r}return null}function K(e,r){const t=new Set,n=[e];for(;n.length>0;){const o=n.pop();if(!o||t.has(o))continue;t.add(o);const i=o.$ref;if(typeof i=="string"){if(r){const d=r[i];if(!d){const p=Object.keys(r).join(", ")||"(none)";throw new Error(`[apigen-logical] $ref "${i}" cannot be resolved. Available $defs: ${p}`)}n.push(d)}continue}const c=o.oneOf;if(Array.isArray(c))for(const d of c)typeof d=="object"&&d!==null&&n.push(d);const s=o.properties;if(s)for(const d of Object.values(s))n.push(d);const u=o.items;if(Array.isArray(u))for(const d of u)typeof d=="object"&&d!==null&&n.push(d);else typeof u=="object"&&u!==null&&n.push(u);const a=o.additionalProperties;typeof a=="object"&&a!==null&&n.push(a);const f=o.propertyNames;typeof f=="object"&&f!==null&&n.push(f)}}function W(e){return{encode(r,t,n){const o=L(e,n);return m(r,t,o)},decode(r,t,n){const o=L(e,n);return l(r,t,o)}}}function X(e,r,t){try{const n=t();e.register(n)}catch(n){if(q(n))return;throw n}}function q(e){return e===null||typeof e!="object"?!1:e.code==="MODULE_NOT_FOUND"}const A={id:"date-time",kind:"scalar",schema:{type:"string",format:"date-time"},matches(e){return e.type==="string"&&e.format==="date-time"},encode(e,r,t){return e.toISOString()},decode(e,r,t){if(typeof e!="string"){if(t.mode==="strict")throw new TypeError(`[date-time] expected a string on the wire at "${t.path}", got ${typeof e}`);return new Date(String(e))}if(t.mode==="strict"&&Number.isNaN(new Date(e).getTime()))throw new TypeError(`[date-time] invalid date-time string at "${t.path}": ${JSON.stringify(e)}`);return new Date(e)}},h={id:"int64",kind:"scalar",schema:{type:"string",format:"int64"},matches(e){return e.type==="string"&&e.format==="int64"},encode(e,r,t){return String(e)},decode(e,r,t){if(typeof e!="string"){if(t.mode==="strict")throw new TypeError(`[int64] expected a string on the wire at "${t.path}", got ${typeof e}`);try{return BigInt(Math.trunc(Number(e)))}catch{return BigInt(0)}}if(t.mode==="strict")return BigInt(e);if(/^-?\d+$/.test(e))try{return BigInt(e)}catch{return BigInt(0)}return BigInt(0)}};function V(e){return e}const N={id:"decimal",kind:"scalar",schema:{type:"string",format:"decimal"},matches(e){return e.type==="string"&&e.format==="decimal"},encode(e,r,t){return e},decode(e,r,t){if(typeof e!="string"){if(t.mode==="strict")throw new TypeError(`[decimal] expected a string on the wire at "${t.path}", got ${typeof e}`);return String(e)}if(t.mode==="strict"&&!/^-?\d+(\.\d+)?$/.test(e))throw new TypeError(`[decimal] wire value "${e}" at "${t.path}" is not a valid decimal string`);return e}},$={id:"byte",kind:"scalar",schema:{type:"string",format:"byte"},matches(e){return e.type==="string"&&e.format==="byte"},encode(e,r,t){return Buffer.from(e).toString("base64")},decode(e,r,t){if(typeof e!="string"){if(t.mode==="strict")throw new TypeError(`[byte] expected a base64 string on the wire at "${t.path}", got ${typeof e}`);return new Uint8Array(0)}if(t.mode==="strict"&&!/^[A-Za-z0-9+/]*={0,2}$/.test(e))throw new TypeError(`[byte] wire value at "${t.path}" is not standard base64 (format:byte): "${e}"`);return new Uint8Array(Buffer.from(e,"base64"))}},Z=/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/,I={id:"uuid",kind:"scalar",schema:{type:"string",format:"uuid"},matches(e){return e.type==="string"&&e.format==="uuid"},encode(e,r,t){return e.toLowerCase()},decode(e,r,t){if(typeof e!="string"){if(t.mode==="strict")throw new TypeError(`[uuid] expected a string on the wire at "${t.path}", got ${typeof e}`);return String(e).toLowerCase()}if(t.mode==="strict"&&!Z.test(e))throw new TypeError(`[uuid] wire value "${e}" at "${t.path}" is not a lowercase-hyphenated RFC 4122 UUID`);return e}},D="NaN",b="Infinity",S="-Infinity",H=new Set([D,b,S]),T={id:"number-special",kind:"scalar",schema:{type:"number"},matches(e){return e.type==="number"&&e.format===void 0},encode(e,r,t){return Number.isNaN(e)?D:e===1/0?b:e===-1/0?S:e},decode(e,r,t){if(typeof e=="number")return e;if(typeof e=="string"){if(e===D)return NaN;if(e===b)return 1/0;if(e===S)return-1/0;const n=Number(e);if(!Number.isNaN(n))return n}if(t.mode==="strict")throw new TypeError(`[number-special] unrecognized wire value at "${t.path}": ${JSON.stringify(e)}. Expected a number or one of ${[...H].join(", ")}.`);return NaN}},Q=[A,h,N,$,I,T];function x(e,r={}){for(const t of Q)e.register(t,{override:r.override??!1})}const ee=12;function te(e,r){const t=/^#\/(definitions|\$defs)\/(.+)$/.exec(e);if(!t)return;const[,n,o]=t,i=n==="$defs"?r.$defs:r.definitions;return i==null?void 0:i[decodeURIComponent(o)]}function F(e){return Array.isArray(e)&&e.length>0?e[0]:void 0}function re(e){if(Array.isArray(e.type))return e.type.find(r=>r!=="null")??e.type[0];if(typeof e.type=="string")return e.type;if(e.properties)return"object"}function ne(e){switch(e.format){case"date-time":return"1970-01-01T00:00:00.000Z";case"date":return"1970-01-01";case"time":return"00:00:00Z";case"uuid":return"00000000-0000-0000-0000-000000000000";case"email":return"user@example.com";case"uri":case"url":case"uri-reference":return"https://example.com";case"hostname":return"example.com";case"ipv4":return"127.0.0.1";case"ipv6":return"::1";case"decimal":return"0";case"int64":return"0";case"byte":return"";default:return"<string>"}}function U(e,r,t){const n=e.properties??{},o=e.required??[],i={};for(const c of o){const s=n[c];i[c]=s!==void 0?y(s,r,t+1):`<${c}>`}return i}function oe(e,r,t){const n=Array.isArray(e.items)?e.items[0]:e.items;return n?[y(n,r,t+1)]:[]}function y(e,r=e??{},t=0){if(!e||t>ee)return null;if(typeof e.$ref=="string"){const i=te(e.$ref,r);return i!==void 0?y(i,r,t+1):null}if(e.const!==void 0)return e.const;if(Array.isArray(e.enum)&&e.enum.length>0)return e.enum[0];if(Array.isArray(e.allOf)&&e.allOf.length>0){const i={},c=[];for(const s of e.allOf){Object.assign(i,s.properties??{});for(const u of s.required??[])c.includes(u)||c.push(u)}return U({...e,properties:i,required:c},r,t)}const n=F(e.oneOf)??F(e.anyOf);if(n)return y(n,r,t+1);switch(re(e)){case"object":return U(e,r,t);case"array":return oe(e,r,t);case"string":return ne(e);case"integer":case"number":return 0;case"boolean":return!1;case"null":return null;default:return null}}function ie(e){if(!e)return;const r=y(e);return`Example: ${JSON.stringify(r)}`}const v=[A.id,h.id,N.id,$.id,I.id,T.id],se={"date-time":{encode:"$.toISOString()",decode:"new Date($)",mode:"native"},int64:{encode:"String($)",decode:"BigInt($)",mode:"native"},decimal:{encode:"$.toString()",decode:"new Decimal($)",imports:[],dep:{name:"decimal.js",version:"^10"},mode:"branded"},byte:{encode:"Buffer.from($).toString('base64')",decode:"new Uint8Array(Buffer.from($, 'base64'))",mode:"native"},uuid:{encode:"$.toLowerCase()",decode:"$",mode:"native"},"number-special":{encode:"numToWire($)",decode:"wireToNum($)",mode:"native"}},ce={"date-time":{encode:"$.isoformat()",decode:"datetime.fromisoformat($)",imports:["from datetime import datetime"],mode:"native"},int64:{encode:"str($)",decode:"int($)",mode:"native"},decimal:{encode:"str($)",decode:"Decimal($)",imports:["from decimal import Decimal"],mode:"native"},byte:{encode:"b64encode($).decode()",decode:"b64decode($)",imports:["from base64 import b64encode, b64decode"],mode:"native"},uuid:{encode:"str($)",decode:"UUID($)",imports:["from uuid import UUID"],mode:"native"},"number-special":{encode:"num_to_wire($)",decode:"wire_to_num($)",mode:"native"}},de={"date-time":{encode:"__SCAFFOLD_RUST_DATETIME_ENCODE__",decode:"__SCAFFOLD_RUST_DATETIME_DECODE__",imports:["use chrono::{DateTime, Utc};"],dep:{name:"chrono",version:"^0.4"},mode:"lib"},int64:{encode:"__SCAFFOLD_RUST_INT64_ENCODE__",decode:"__SCAFFOLD_RUST_INT64_DECODE__",imports:["use serde_with::DisplayFromStr;"],dep:{name:"serde_with",version:"^3"},mode:"lib"},decimal:{encode:"__SCAFFOLD_RUST_DECIMAL_ENCODE__",decode:"__SCAFFOLD_RUST_DECIMAL_DECODE__",imports:["use rust_decimal::Decimal;"],dep:{name:"rust_decimal",version:"^1"},mode:"lib"},byte:{encode:"__SCAFFOLD_RUST_BYTE_ENCODE__",decode:"__SCAFFOLD_RUST_BYTE_DECODE__",imports:["use serde_with::base64::Base64;"],dep:{name:"serde_with",version:"^3"},mode:"lib"},uuid:{encode:"__SCAFFOLD_RUST_UUID_ENCODE__",decode:"__SCAFFOLD_RUST_UUID_DECODE__",imports:["use uuid::Uuid;"],dep:{name:"uuid",version:"^1"},mode:"lib"},"number-special":{encode:"__SCAFFOLD_RUST_NUMSPECIAL_ENCODE__",decode:"__SCAFFOLD_RUST_NUMSPECIAL_DECODE__",mode:"native"}},ae={"date-time":{encode:"__SCAFFOLD_GO_DATETIME_ENCODE__",decode:"__SCAFFOLD_GO_DATETIME_DECODE__",imports:['"time"'],mode:"native"},int64:{encode:"__SCAFFOLD_GO_INT64_ENCODE__",decode:"__SCAFFOLD_GO_INT64_DECODE__",imports:['"strconv"'],mode:"native"},decimal:{encode:"__SCAFFOLD_GO_DECIMAL_ENCODE__",decode:"__SCAFFOLD_GO_DECIMAL_DECODE__",imports:['"github.com/shopspring/decimal"'],dep:{name:"github.com/shopspring/decimal",version:"v1"},mode:"lib"},byte:{encode:"__SCAFFOLD_GO_BYTE_ENCODE__",decode:"__SCAFFOLD_GO_BYTE_DECODE__",imports:['"encoding/base64"'],mode:"native"},uuid:{encode:"__SCAFFOLD_GO_UUID_ENCODE__",decode:"__SCAFFOLD_GO_UUID_DECODE__",imports:['"github.com/google/uuid"'],dep:{name:"github.com/google/uuid",version:"v1"},mode:"lib"},"number-special":{encode:"__SCAFFOLD_GO_NUMSPECIAL_ENCODE__",decode:"__SCAFFOLD_GO_NUMSPECIAL_DECODE__",mode:"native"}},fe={"date-time":{encode:"$.toString()",decode:"Instant.parse($)",imports:["import java.time.Instant;"],dep:{name:"jackson-datatype-jsr310",version:"2.x"},mode:"lib"},int64:{encode:"@JsonFormat(shape = JsonFormat.Shape.STRING)",decode:"@JsonFormat(shape = JsonFormat.Shape.STRING)",imports:["import com.fasterxml.jackson.annotation.JsonFormat;"],mode:"native"},decimal:{encode:"@JsonSerialize(using = ToStringSerializer.class)",decode:"new BigDecimal($)",imports:["import java.math.BigDecimal;","import com.fasterxml.jackson.databind.annotation.JsonSerialize;","import com.fasterxml.jackson.databind.ser.std.ToStringSerializer;"],mode:"native"},byte:{encode:"$",decode:"$",mode:"native"},uuid:{encode:"$.toString()",decode:"UUID.fromString($)",imports:["import java.util.UUID;"],mode:"native"},"number-special":{encode:"@JsonSerialize(using = NumberSpecialSerializer.class)",decode:"@JsonDeserialize(using = NumberSpecialDeserializer.class)",imports:["import com.fasterxml.jackson.databind.annotation.JsonSerialize;","import com.fasterxml.jackson.databind.annotation.JsonDeserialize;"],mode:"native"}},E=Object.freeze({typescript:se,python:ce,rust:de,go:ae,java:fe});function ue(e){return E[e]}function pe(e,r){const t=E[r],n=[];for(const o of e){const i=t[o];i!=null&&i.dep&&n.push({id:o,dep:i.dep})}return n}function _e(){const e=E.typescript,r={};for(const t of v){const n=e[t].dep;n&&(r[t]=n)}return Object.freeze(r)}function me(e,r){const t=r??E[e],n=[];for(const o of v)t[o]||n.push(o);if(n.length>0)throw new Error(`[hints] assertNoEmptyCells: language "${e}" is missing cells for: ${n.join(", ")}`)}exports.CANONICAL_LOGICAL_TYPE_IDS=v;exports.CodecRegistryError=C;exports.ENVELOPE_KEY=g;exports.LOGICAL_TYPE_VERSION=w;exports.TEMPLATE_CELLS=E;exports.X_APIGEN_CODEC=R;exports.X_APIGEN_CTOR=M;exports.X_APIGEN_LOGICAL=j;exports.X_APIGEN_TOJSON=k;exports.assertNoEmptyCells=me;exports.buildTranscoder=W;exports.byteCodec=$;exports.cellsFor=ue;exports.codecIdOf=J;exports.createRegistry=G;exports.dateTimeCodec=A;exports.decimalCodec=N;exports.depsForLogicalTypes=pe;exports.int64Codec=h;exports.logicalKindOf=B;exports.makeDecimal=V;exports.numberSpecialCodec=T;exports.registerWellKnown=x;exports.renderExampleNote=ie;exports.synthesizeExample=y;exports.tryRegister=X;exports.tsDepMap=_e;exports.uuidCodec=I;exports.validateSchemaRefs=K;

package/index.mjs

@@ -1,73 +1,73 @@
-const l = "$apigen";
-class g extends Error {
-  constructor(o) {
-    super(o), this.code = "E_DUP_CODEC", this.name = "CodecRegistryError";
+const D = "$apigen";
+class C extends Error {
+  constructor(r) {
+    super(r), this.code = "E_DUP_CODEC", this.name = "CodecRegistryError";
   }
 }
-function z(e) {
+function x(e) {
   e == null || e.wellKnown;
-  const o = /* @__PURE__ */ new Map();
+  const r = /* @__PURE__ */ new Map();
   return {
-    register(n, r) {
-      if (o.has(n.id) && !(r != null && r.override))
-        throw new g(
+    register(n, o) {
+      if (r.has(n.id) && !(o != null && o.override))
+        throw new C(
           `E_DUP_CODEC: a codec is already registered for id "${n.id}"`
         );
-      o.set(n.id, n);
+      r.set(n.id, n);
     },
     resolve(n) {
-      for (const r of o.values())
-        if (r.matches(n))
-          return r;
+      for (const o of r.values())
+        if (o.matches(n))
+          return o;
     },
     get(n) {
-      return o.get(n);
+      return r.get(n);
     },
     ids() {
-      return [...o.keys()];
+      return [...r.keys()];
     },
     freeze() {
-      const n = new Map(o), r = {
+      const n = new Map(r), o = {
         register() {
-          throw new g(
+          throw new C(
             "E_DUP_CODEC: registry is frozen and cannot accept new codecs"
           );
         },
-        resolve(d) {
-          for (const a of n.values())
-            if (a.matches(d))
-              return a;
+        resolve(i) {
+          for (const c of n.values())
+            if (c.matches(i))
+              return c;
         },
-        get(d) {
-          return n.get(d);
+        get(i) {
+          return n.get(i);
         },
         ids() {
           return [...n.keys()];
         },
         freeze() {
-          return r;
+          return o;
         }
       };
-      return r;
+      return o;
     }
   };
 }
-const v = "x-apigen-logical", U = "x-apigen-codec", W = "x-apigen-ctor", K = "x-apigen-tojson", X = "0.1.0", j = [
+const R = "x-apigen-logical", P = "x-apigen-codec", ee = "x-apigen-ctor", te = "x-apigen-tojson", re = "0.1.0", M = [
   "scalar",
   "nominal",
   "union",
   "map",
   "set"
 ];
-function H(e) {
-  const o = e[v];
-  return typeof o == "string" && j.includes(o) ? o : void 0;
+function ne(e) {
+  const r = e[R];
+  return typeof r == "string" && M.includes(r) ? r : void 0;
 }
-function Z(e) {
-  const o = e[U];
-  return typeof o == "string" ? o : void 0;
+function oe(e) {
+  const r = e[P];
+  return typeof r == "string" ? r : void 0;
 }
-function h(e, o) {
+function h(e, r) {
   return {
     registry: e,
     resolve: (t) => {
@@ -78,228 +78,228 @@ function h(e, o) {
     seen: /* @__PURE__ */ new WeakSet(),
     path: "",
     mode: "strict",
-    ...o
+    ...r
   };
 }
-function p(e, o, t) {
-  const n = t.registry.resolve(o);
+function _(e, r, t) {
+  const n = t.registry.resolve(r);
   if (n)
-    return n.encode(e, o, t);
-  const r = o.$ref;
-  if (typeof r == "string") {
-    const i = t.resolve(r);
-    return p(e, i, t);
-  }
-  const d = o.oneOf;
-  if (Array.isArray(d)) {
-    const i = S(e, d, o);
-    return p(e, i, t);
-  }
-  const a = o.type;
-  if (a === "array") {
+    return n.encode(e, r, t);
+  const o = r.$ref;
+  if (typeof o == "string") {
+    const s = t.resolve(o);
+    return _(e, s, t);
+  }
+  const i = r.oneOf;
+  if (Array.isArray(i)) {
+    const s = N(e, i, r);
+    return _(e, s, t);
+  }
+  const c = r.type;
+  if (c === "array") {
     if (!Array.isArray(e))
-      return D(e, o, t);
-    const i = o.items;
-    if (!i)
-      return e.map((c) => u(c));
-    const f = t.path;
-    return Array.isArray(i) ? e.map((c, _) => {
-      const s = i[_];
-      return s === void 0 ? u(c) : p(c, s, { ...t, path: `${f}/${_}` });
+      return E(e, r, t);
+    const s = r.items;
+    if (!s)
+      return e.map((a) => m(a));
+    const u = t.path;
+    return Array.isArray(s) ? e.map((a, f) => {
+      const d = s[f];
+      return d === void 0 ? m(a) : _(a, d, { ...t, path: `${u}/${f}` });
     }) : e.map(
-      (c, _) => p(c, i, { ...t, path: `${f}/${_}` })
+      (a, f) => _(a, s, { ...t, path: `${u}/${f}` })
     );
   }
-  if (a === "object") {
+  if (c === "object") {
     if (e === null || typeof e != "object" || Array.isArray(e))
-      return D(e, o, t);
-    const i = o.properties;
-    if (!i)
-      return u(e);
-    const f = t.path, c = {};
-    for (const [_, s] of Object.entries(i)) {
-      const m = e[_];
-      m !== void 0 && (c[_] = p(m, s, {
+      return E(e, r, t);
+    const s = r.properties;
+    if (!s)
+      return m(e);
+    const u = t.path, a = {};
+    for (const [f, d] of Object.entries(s)) {
+      const p = e[f];
+      p !== void 0 && (a[f] = _(p, d, {
         ...t,
-        path: `${f}/${_}`
+        path: `${u}/${f}`
       }));
     }
-    return c;
+    return a;
   }
-  return a == null ? D(e, o, t) : u(e);
+  return c == null ? E(e, r, t) : m(e);
 }
-function E(e, o, t) {
-  const n = t.registry.resolve(o);
+function l(e, r, t) {
+  const n = t.registry.resolve(r);
   if (n)
-    return n.decode(e, o, t);
-  const r = o.$ref;
-  if (typeof r == "string") {
-    const i = t.resolve(r);
-    return E(e, i, t);
-  }
-  const d = o.oneOf;
-  if (Array.isArray(d)) {
-    const i = S(e, d, o);
-    return E(e, i, t);
-  }
-  const a = o.type;
-  if (a === "array") {
+    return n.decode(e, r, t);
+  const o = r.$ref;
+  if (typeof o == "string") {
+    const s = t.resolve(o);
+    return l(e, s, t);
+  }
+  const i = r.oneOf;
+  if (Array.isArray(i)) {
+    const s = N(e, i, r);
+    return l(e, s, t);
+  }
+  const c = r.type;
+  if (c === "array") {
     if (!Array.isArray(e))
       return e;
-    const i = o.items;
-    if (!i)
+    const s = r.items;
+    if (!s)
       return e;
-    const f = t.path;
-    return Array.isArray(i) ? e.map((c, _) => {
-      const s = i[_];
-      return s === void 0 ? c : E(c, s, { ...t, path: `${f}/${_}` });
+    const u = t.path;
+    return Array.isArray(s) ? e.map((a, f) => {
+      const d = s[f];
+      return d === void 0 ? a : l(a, d, { ...t, path: `${u}/${f}` });
     }) : e.map(
-      (c, _) => E(c, i, { ...t, path: `${f}/${_}` })
+      (a, f) => l(a, s, { ...t, path: `${u}/${f}` })
     );
   }
-  if (a === "object") {
+  if (c === "object") {
     if (e === null || typeof e != "object" || Array.isArray(e))
       return e;
-    const i = o.properties;
-    if (!i)
+    const s = r.properties;
+    if (!s)
       return e;
-    const f = t.path, c = {};
-    for (const [_, s] of Object.entries(i)) {
-      const m = e[_];
-      m !== void 0 && (c[_] = E(m, s, {
+    const u = t.path, a = {};
+    for (const [f, d] of Object.entries(s)) {
+      const p = e[f];
+      p !== void 0 && (a[f] = l(p, d, {
         ...t,
-        path: `${f}/${_}`
+        path: `${u}/${f}`
       }));
     }
-    return c;
+    return a;
   }
-  return a == null ? M(e, t) : e;
+  return c == null ? k(e, t) : e;
 }
-function S(e, o, t, n) {
-  const r = t.discriminator;
-  if (r != null && r.propertyName) {
-    const d = e !== null && typeof e == "object" ? e[r.propertyName] : void 0;
-    if (typeof d == "string" && r.mapping) {
-      const a = r.mapping[d];
-      if (a) {
-        const i = o.find((f) => f.$ref === a);
-        if (i)
-          return i;
+function N(e, r, t, n) {
+  const o = t.discriminator;
+  if (o != null && o.propertyName) {
+    const i = e !== null && typeof e == "object" ? e[o.propertyName] : void 0;
+    if (typeof i == "string" && o.mapping) {
+      const c = o.mapping[i];
+      if (c) {
+        const s = r.find((u) => u.$ref === c);
+        if (s)
+          return s;
       }
     }
   }
-  return o[0] ?? {};
+  return r[0] ?? {};
 }
-function D(e, o, t) {
+function E(e, r, t) {
   for (const n of t.registry.ids()) {
-    const r = t.registry.get(n);
-    if (r)
+    const o = t.registry.get(n);
+    if (o)
       try {
-        const d = r.encode(e, r.schema, t);
-        return { [l]: n, v: d };
+        const i = o.encode(e, o.schema, t);
+        return { [D]: n, v: i };
       } catch {
       }
   }
-  return u(e);
+  return m(e);
 }
-function M(e, o) {
-  if (e !== null && typeof e == "object" && !Array.isArray(e) && l in e) {
-    const t = e, n = t[l], r = o.registry.get(n);
-    if (r)
-      return r.decode(t.v, r.schema, o);
+function k(e, r) {
+  if (e !== null && typeof e == "object" && !Array.isArray(e) && D in e) {
+    const t = e, n = t[D], o = r.registry.get(n);
+    if (o)
+      return o.decode(t.v, o.schema, r);
   }
   return e;
 }
-function u(e) {
+function m(e) {
   if (e === null || typeof e == "string" || typeof e == "number" || typeof e == "boolean")
     return e;
   if (Array.isArray(e))
-    return e.map(u);
+    return e.map(m);
   if (typeof e == "object") {
-    const o = {};
+    const r = {};
     for (const [t, n] of Object.entries(e))
-      n !== void 0 && (o[t] = u(n));
-    return o;
+      n !== void 0 && (r[t] = m(n));
+    return r;
   }
   return null;
 }
-function q(e, o) {
+function ie(e, r) {
   const t = /* @__PURE__ */ new Set(), n = [e];
   for (; n.length > 0; ) {
-    const r = n.pop();
-    if (!r || t.has(r))
+    const o = n.pop();
+    if (!o || t.has(o))
       continue;
-    t.add(r);
-    const d = r.$ref;
-    if (typeof d == "string") {
-      if (o) {
-        const s = o[d];
-        if (!s) {
-          const m = Object.keys(o).join(", ") || "(none)";
+    t.add(o);
+    const i = o.$ref;
+    if (typeof i == "string") {
+      if (r) {
+        const d = r[i];
+        if (!d) {
+          const p = Object.keys(r).join(", ") || "(none)";
           throw new Error(
-            `[apigen-logical] $ref "${d}" cannot be resolved. Available $defs: ${m}`
+            `[apigen-logical] $ref "${i}" cannot be resolved. Available $defs: ${p}`
           );
         }
-        n.push(s);
+        n.push(d);
       }
       continue;
     }
-    const a = r.oneOf;
-    if (Array.isArray(a))
-      for (const s of a)
-        typeof s == "object" && s !== null && n.push(s);
-    const i = r.properties;
-    if (i)
-      for (const s of Object.values(i))
-        n.push(s);
-    const f = r.items;
-    if (Array.isArray(f))
-      for (const s of f)
-        typeof s == "object" && s !== null && n.push(s);
+    const c = o.oneOf;
+    if (Array.isArray(c))
+      for (const d of c)
+        typeof d == "object" && d !== null && n.push(d);
+    const s = o.properties;
+    if (s)
+      for (const d of Object.values(s))
+        n.push(d);
+    const u = o.items;
+    if (Array.isArray(u))
+      for (const d of u)
+        typeof d == "object" && d !== null && n.push(d);
     else
-      typeof f == "object" && f !== null && n.push(f);
-    const c = r.additionalProperties;
-    typeof c == "object" && c !== null && n.push(c);
-    const _ = r.propertyNames;
-    typeof _ == "object" && _ !== null && n.push(_);
+      typeof u == "object" && u !== null && n.push(u);
+    const a = o.additionalProperties;
+    typeof a == "object" && a !== null && n.push(a);
+    const f = o.propertyNames;
+    typeof f == "object" && f !== null && n.push(f);
   }
 }
-function Q(e) {
+function se(e) {
   return {
-    encode(o, t, n) {
-      const r = h(e, n);
-      return p(o, t, r);
+    encode(r, t, n) {
+      const o = h(e, n);
+      return _(r, t, o);
     },
-    decode(o, t, n) {
-      const r = h(e, n);
-      return E(o, t, r);
+    decode(r, t, n) {
+      const o = h(e, n);
+      return l(r, t, o);
     }
   };
 }
-function x(e, o, t) {
+function ce(e, r, t) {
   try {
     const n = t();
     e.register(n);
   } catch (n) {
-    if (P(n))
+    if (G(n))
       return;
     throw n;
   }
 }
-function P(e) {
+function G(e) {
   return e === null || typeof e != "object" ? !1 : e.code === "MODULE_NOT_FOUND";
 }
-const b = {
+const v = {
   id: "date-time",
   kind: "scalar",
   schema: { type: "string", format: "date-time" },
   matches(e) {
     return e.type === "string" && e.format === "date-time";
   },
-  encode(e, o, t) {
+  encode(e, r, t) {
     return e.toISOString();
   },
-  decode(e, o, t) {
+  decode(e, r, t) {
     if (typeof e != "string") {
       if (t.mode === "strict")
         throw new TypeError(
@@ -313,17 +313,17 @@ const b = {
       );
     return new Date(e);
   }
-}, N = {
+}, I = {
   id: "int64",
   kind: "scalar",
   schema: { type: "string", format: "int64" },
   matches(e) {
     return e.type === "string" && e.format === "int64";
   },
-  encode(e, o, t) {
+  encode(e, r, t) {
     return String(e);
   },
-  decode(e, o, t) {
+  decode(e, r, t) {
     if (typeof e != "string") {
       if (t.mode === "strict")
         throw new TypeError(
@@ -346,20 +346,20 @@ const b = {
     return BigInt(0);
   }
 };
-function ee(e) {
+function de(e) {
   return e;
 }
-const F = {
+const T = {
   id: "decimal",
   kind: "scalar",
   schema: { type: "string", format: "decimal" },
   matches(e) {
     return e.type === "string" && e.format === "decimal";
   },
-  encode(e, o, t) {
+  encode(e, r, t) {
     return e;
   },
-  decode(e, o, t) {
+  decode(e, r, t) {
     if (typeof e != "string") {
       if (t.mode === "strict")
         throw new TypeError(
@@ -373,17 +373,17 @@ const F = {
       );
     return e;
   }
-}, $ = {
+}, F = {
   id: "byte",
   kind: "scalar",
   schema: { type: "string", format: "byte" },
   matches(e) {
     return e.type === "string" && e.format === "byte";
   },
-  encode(e, o, t) {
+  encode(e, r, t) {
     return Buffer.from(e).toString("base64");
   },
-  decode(e, o, t) {
+  decode(e, r, t) {
     if (typeof e != "string") {
       if (t.mode === "strict")
         throw new TypeError(
@@ -397,17 +397,17 @@ const F = {
       );
     return new Uint8Array(Buffer.from(e, "base64"));
   }
-}, R = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/, L = {
+}, w = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/, L = {
   id: "uuid",
   kind: "scalar",
   schema: { type: "string", format: "uuid" },
   matches(e) {
     return e.type === "string" && e.format === "uuid";
   },
-  encode(e, o, t) {
+  encode(e, r, t) {
     return e.toLowerCase();
   },
-  decode(e, o, t) {
+  decode(e, r, t) {
     if (typeof e != "string") {
       if (t.mode === "strict")
         throw new TypeError(
@@ -415,35 +415,35 @@ const F = {
         );
       return String(e).toLowerCase();
     }
-    if (t.mode === "strict" && !R.test(e))
+    if (t.mode === "strict" && !w.test(e))
       throw new TypeError(
         `[uuid] wire value "${e}" at "${t.path}" is not a lowercase-hyphenated RFC 4122 UUID`
       );
     return e;
   }
-}, O = "NaN", C = "Infinity", A = "-Infinity", G = /* @__PURE__ */ new Set([
+}, O = "NaN", b = "Infinity", S = "-Infinity", z = /* @__PURE__ */ new Set([
   O,
-  C,
-  A
-]), I = {
+  b,
+  S
+]), U = {
   id: "number-special",
   kind: "scalar",
   schema: { type: "number" },
   matches(e) {
     return e.type === "number" && e.format === void 0;
   },
-  encode(e, o, t) {
-    return Number.isNaN(e) ? O : e === 1 / 0 ? C : e === -1 / 0 ? A : e;
+  encode(e, r, t) {
+    return Number.isNaN(e) ? O : e === 1 / 0 ? b : e === -1 / 0 ? S : e;
   },
-  decode(e, o, t) {
+  decode(e, r, t) {
     if (typeof e == "number")
       return e;
     if (typeof e == "string") {
       if (e === O)
         return NaN;
-      if (e === C)
+      if (e === b)
         return 1 / 0;
-      if (e === A)
+      if (e === S)
         return -1 / 0;
       const n = Number(e);
       if (!Number.isNaN(n))
@@ -451,36 +451,150 @@ const F = {
     }
     if (t.mode === "strict")
       throw new TypeError(
-        `[number-special] unrecognized wire value at "${t.path}": ${JSON.stringify(e)}. Expected a number or one of ${[...G].join(", ")}.`
+        `[number-special] unrecognized wire value at "${t.path}": ${JSON.stringify(e)}. Expected a number or one of ${[...z].join(", ")}.`
       );
     return NaN;
   }
-}, w = [
-  b,
-  N,
+}, B = [
+  v,
+  I,
+  T,
   F,
-  $,
   L,
-  I
+  U
 ];
-function te(e, o = {}) {
-  for (const t of w)
-    e.register(t, { override: o.override ?? !1 });
+function ae(e, r = {}) {
+  for (const t of B)
+    e.register(t, { override: r.override ?? !1 });
+}
+const J = 12;
+function Y(e, r) {
+  const t = /^#\/(definitions|\$defs)\/(.+)$/.exec(e);
+  if (!t)
+    return;
+  const [, n, o] = t, i = n === "$defs" ? r.$defs : r.definitions;
+  return i == null ? void 0 : i[decodeURIComponent(o)];
 }
-const T = [
-  b.id,
+function A(e) {
+  return Array.isArray(e) && e.length > 0 ? e[0] : void 0;
+}
+function W(e) {
+  if (Array.isArray(e.type))
+    return e.type.find((r) => r !== "null") ?? e.type[0];
+  if (typeof e.type == "string")
+    return e.type;
+  if (e.properties)
+    return "object";
+}
+function K(e) {
+  switch (e.format) {
+    case "date-time":
+      return "1970-01-01T00:00:00.000Z";
+    case "date":
+      return "1970-01-01";
+    case "time":
+      return "00:00:00Z";
+    case "uuid":
+      return "00000000-0000-0000-0000-000000000000";
+    case "email":
+      return "user@example.com";
+    case "uri":
+    case "url":
+    case "uri-reference":
+      return "https://example.com";
+    case "hostname":
+      return "example.com";
+    case "ipv4":
+      return "127.0.0.1";
+    case "ipv6":
+      return "::1";
+    case "decimal":
+      return "0";
+    case "int64":
+      return "0";
+    case "byte":
+      return "";
+    default:
+      return "<string>";
+  }
+}
+function $(e, r, t) {
+  const n = e.properties ?? {}, o = e.required ?? [], i = {};
+  for (const c of o) {
+    const s = n[c];
+    i[c] = s !== void 0 ? y(s, r, t + 1) : `<${c}>`;
+  }
+  return i;
+}
+function q(e, r, t) {
+  const n = Array.isArray(e.items) ? e.items[0] : e.items;
+  return n ? [y(n, r, t + 1)] : [];
+}
+function y(e, r = e ?? {}, t = 0) {
+  if (!e || t > J)
+    return null;
+  if (typeof e.$ref == "string") {
+    const i = Y(e.$ref, r);
+    return i !== void 0 ? y(i, r, t + 1) : null;
+  }
+  if (e.const !== void 0)
+    return e.const;
+  if (Array.isArray(e.enum) && e.enum.length > 0)
+    return e.enum[0];
+  if (Array.isArray(e.allOf) && e.allOf.length > 0) {
+    const i = {}, c = [];
+    for (const s of e.allOf) {
+      Object.assign(i, s.properties ?? {});
+      for (const u of s.required ?? [])
+        c.includes(u) || c.push(u);
+    }
+    return $(
+      { ...e, properties: i, required: c },
+      r,
+      t
+    );
+  }
+  const n = A(e.oneOf) ?? A(e.anyOf);
+  if (n)
+    return y(n, r, t + 1);
+  switch (W(e)) {
+    case "object":
+      return $(e, r, t);
+    case "array":
+      return q(e, r, t);
+    case "string":
+      return K(e);
+    case "integer":
+    case "number":
+      return 0;
+    case "boolean":
+      return !1;
+    case "null":
+      return null;
+    default:
+      return null;
+  }
+}
+function fe(e) {
+  if (!e)
+    return;
+  const r = y(e);
+  return `Example: ${JSON.stringify(r)}`;
+}
+const j = [
+  v.id,
   // 'date-time'
-  N.id,
+  I.id,
   // 'int64'
-  F.id,
+  T.id,
   // 'decimal'
-  $.id,
+  F.id,
   // 'byte'
   L.id,
   // 'uuid'
-  I.id
+  U.id
   // 'number-special'
-], B = {
+], X = {
   "date-time": {
     encode: "$.toISOString()",
     decode: "new Date($)",
@@ -519,7 +633,7 @@ const T = [
     decode: "wireToNum($)",
     mode: "native"
   }
-}, k = {
+}, V = {
   "date-time": {
     encode: "$.isoformat()",
     decode: "datetime.fromisoformat($)",
@@ -556,7 +670,7 @@ const T = [
     decode: "wire_to_num($)",
     mode: "native"
   }
-}, J = {
+}, Z = {
   "date-time": {
     // chrono::DateTime<Utc> serialises as RFC3339 via serde.
     encode: "__SCAFFOLD_RUST_DATETIME_ENCODE__",
@@ -600,7 +714,7 @@ const T = [
     decode: "__SCAFFOLD_RUST_NUMSPECIAL_DECODE__",
     mode: "native"
   }
-}, V = {
+}, H = {
   "date-time": {
     // time.Time serialises as RFC3339Nano via MarshalJSON.
     encode: "__SCAFFOLD_GO_DATETIME_ENCODE__",
@@ -641,78 +755,104 @@ const T = [
     decode: "__SCAFFOLD_GO_NUMSPECIAL_DECODE__",
     mode: "native"
   }
-}, Y = {
+}, Q = {
   "date-time": {
-    // Instant.toString() / Instant.parse() via jackson-datatype-jsr310.
-    encode: "__SCAFFOLD_JAVA_DATETIME_ENCODE__",
-    decode: "__SCAFFOLD_JAVA_DATETIME_DECODE__",
+    // Instant.toString() (RFC-3339/ISO-8601, UTC) / Instant.parse($) — the
+    // jackson-datatype-jsr310 module is registered on the shared ObjectMapper
+    // so java.time.Instant fields round-trip automatically, but the
+    // dispatcher-woven glue (which builds/reads JsonNode by hand rather than
+    // going through a field-annotated POJO) uses these expressions directly.
+    encode: "$.toString()",
+    decode: "Instant.parse($)",
     imports: ["import java.time.Instant;"],
     dep: { name: "jackson-datatype-jsr310", version: "2.x" },
     mode: "lib"
   },
   int64: {
-    // @JsonFormat(shape=STRING) on Long / BigInteger — stdlib Jackson.
-    encode: "__SCAFFOLD_JAVA_INT64_ENCODE__",
-    decode: "__SCAFFOLD_JAVA_INT64_DECODE__",
+    // Declarative, not expression-shaped: Jackson field annotation forces
+    // Long/long to serialise as a JSON string (avoids precision loss in
+    // JS/JSON-number consumers). mode:'native' — the "encode"/"decode"
+    // values below ARE the annotation text (identical on both sides; Jackson
+    // applies it symmetrically), not a `$`-substituted call expression.
+    encode: "@JsonFormat(shape = JsonFormat.Shape.STRING)",
+    decode: "@JsonFormat(shape = JsonFormat.Shape.STRING)",
     imports: ["import com.fasterxml.jackson.annotation.JsonFormat;"],
     mode: "native"
   },
   decimal: {
-    // @JsonSerialize(using=ToStringSerializer) on BigDecimal — stdlib Jackson.
-    encode: "__SCAFFOLD_JAVA_DECIMAL_ENCODE__",
-    decode: "__SCAFFOLD_JAVA_DECIMAL_DECODE__",
-    imports: ["import java.math.BigDecimal;"],
+    // Encode is declarative (field annotation forces BigDecimal -> JSON
+    // string via Jackson's stdlib ToStringSerializer, so scale/precision
+    // survive the wire); decode is a plain expression since BigDecimal has
+    // no matching stdlib deserializer-by-annotation for "parse from string".
+    encode: "@JsonSerialize(using = ToStringSerializer.class)",
+    decode: "new BigDecimal($)",
+    imports: [
+      "import java.math.BigDecimal;",
+      "import com.fasterxml.jackson.databind.annotation.JsonSerialize;",
+      "import com.fasterxml.jackson.databind.ser.std.ToStringSerializer;"
+    ],
     mode: "native"
   },
   byte: {
-    // byte[] serialises as base64 by default in Jackson.
-    encode: "__SCAFFOLD_JAVA_BYTE_ENCODE__",
-    decode: "__SCAFFOLD_JAVA_BYTE_DECODE__",
+    // byte[] <-> base64 String is Jackson's built-in default codec — no
+    // annotation, no wrapping expression. The dispatcher glue passes the
+    // value through unchanged; Jackson's ObjectMapper performs the base64
+    // transcoding when the JsonNode tree is built/read.
+    encode: "$",
+    decode: "$",
     mode: "native"
   },
   uuid: {
-    // UUID.toString() / UUID.fromString() — stdlib Java.
-    encode: "__SCAFFOLD_JAVA_UUID_ENCODE__",
-    decode: "__SCAFFOLD_JAVA_UUID_DECODE__",
+    // UUID.toString() / UUID.fromString($) — stdlib Java, no Jackson module.
+    encode: "$.toString()",
+    decode: "UUID.fromString($)",
     imports: ["import java.util.UUID;"],
     mode: "native"
   },
   "number-special": {
-    // Custom StdSerializer — stdlib Jackson.
-    encode: "__SCAFFOLD_JAVA_NUMSPECIAL_ENCODE__",
-    decode: "__SCAFFOLD_JAVA_NUMSPECIAL_DECODE__",
+    // NaN/Infinity/-Infinity have no native JSON representation; mirrors the
+    // TS numToWire/wireToNum inline helpers with a small custom Jackson
+    // StdSerializer/StdDeserializer pair, generated inline by
+    // renderDispatcherJava (class names below are the fixed contract the
+    // generator emits — apigen-plugin-java-javalin/src/lib/dispatcher-template.ts).
+    encode: "@JsonSerialize(using = NumberSpecialSerializer.class)",
+    decode: "@JsonDeserialize(using = NumberSpecialDeserializer.class)",
+    imports: [
+      "import com.fasterxml.jackson.databind.annotation.JsonSerialize;",
+      "import com.fasterxml.jackson.databind.annotation.JsonDeserialize;"
+    ],
     mode: "native"
   }
-}, y = Object.freeze({
-  typescript: B,
-  python: k,
-  rust: J,
-  go: V,
-  java: Y
+}, g = Object.freeze({
+  typescript: X,
+  python: V,
+  rust: Z,
+  go: H,
+  java: Q
 });
-function oe(e) {
-  return y[e];
+function ue(e) {
+  return g[e];
 }
-function ne(e, o) {
-  const t = y[o], n = [];
-  for (const r of e) {
-    const d = t[r];
-    d != null && d.dep && n.push({ id: r, dep: d.dep });
+function pe(e, r) {
+  const t = g[r], n = [];
+  for (const o of e) {
+    const i = t[o];
+    i != null && i.dep && n.push({ id: o, dep: i.dep });
   }
   return n;
 }
-function re() {
-  const e = y.typescript, o = {};
-  for (const t of T) {
+function me() {
+  const e = g.typescript, r = {};
+  for (const t of j) {
     const n = e[t].dep;
-    n && (o[t] = n);
+    n && (r[t] = n);
   }
-  return Object.freeze(o);
+  return Object.freeze(r);
 }
-function ie(e, o) {
-  const t = o ?? y[e], n = [];
-  for (const r of T)
-    t[r] || n.push(r);
+function _e(e, r) {
+  const t = r ?? g[e], n = [];
+  for (const o of j)
+    t[o] || n.push(o);
   if (n.length > 0)
     throw new Error(
       `[hints] assertNoEmptyCells: language "${e}" is missing cells for: ${n.join(
@@ -721,31 +861,33 @@ function ie(e, o) {
     );
 }
 export {
-  T as CANONICAL_LOGICAL_TYPE_IDS,
-  g as CodecRegistryError,
-  l as ENVELOPE_KEY,
-  X as LOGICAL_TYPE_VERSION,
-  y as TEMPLATE_CELLS,
-  U as X_APIGEN_CODEC,
-  W as X_APIGEN_CTOR,
-  v as X_APIGEN_LOGICAL,
-  K as X_APIGEN_TOJSON,
-  ie as assertNoEmptyCells,
-  Q as buildTranscoder,
-  $ as byteCodec,
-  oe as cellsFor,
-  Z as codecIdOf,
-  z as createRegistry,
-  b as dateTimeCodec,
-  F as decimalCodec,
-  ne as depsForLogicalTypes,
-  N as int64Codec,
-  H as logicalKindOf,
-  ee as makeDecimal,
-  I as numberSpecialCodec,
-  te as registerWellKnown,
-  x as tryRegister,
-  re as tsDepMap,
+  j as CANONICAL_LOGICAL_TYPE_IDS,
+  C as CodecRegistryError,
+  D as ENVELOPE_KEY,
+  re as LOGICAL_TYPE_VERSION,
+  g as TEMPLATE_CELLS,
+  P as X_APIGEN_CODEC,
+  ee as X_APIGEN_CTOR,
+  R as X_APIGEN_LOGICAL,
+  te as X_APIGEN_TOJSON,
+  _e as assertNoEmptyCells,
+  se as buildTranscoder,
+  F as byteCodec,
+  ue as cellsFor,
+  oe as codecIdOf,
+  x as createRegistry,
+  v as dateTimeCodec,
+  T as decimalCodec,
+  pe as depsForLogicalTypes,
+  I as int64Codec,
+  ne as logicalKindOf,
+  de as makeDecimal,
+  U as numberSpecialCodec,
+  ae as registerWellKnown,
+  fe as renderExampleNote,
+  y as synthesizeExample,
+  ce as tryRegister,
+  me as tsDepMap,
   L as uuidCodec,
-  q as validateSchemaRefs
+  ie as validateSchemaRefs
 };

package/lib/example.d.ts

@@ -0,0 +1,35 @@
+/** The minimal JSON-Schema-shaped structure this module reads. */
+export interface JsonSchemaLike {
+    type?: string | string[];
+    properties?: Record<string, JsonSchemaLike>;
+    required?: string[];
+    items?: JsonSchemaLike | JsonSchemaLike[];
+    enum?: unknown[];
+    const?: unknown;
+    format?: string;
+    oneOf?: JsonSchemaLike[];
+    anyOf?: JsonSchemaLike[];
+    allOf?: JsonSchemaLike[];
+    $ref?: string;
+    definitions?: Record<string, JsonSchemaLike>;
+    $defs?: Record<string, JsonSchemaLike>;
+    [key: string]: unknown;
+}
+/**
+ * Synthesize a minimal, AJV-plausible example value for `schema`.
+ *
+ * @param schema - The schema fragment to synthesize a value for.
+ * @param root - The document root `$ref`s in `schema` (and its descendants)
+ *   resolve against. Defaults to `schema` itself — correct for the common
+ *   case where `schema` IS the whole self-contained document (apigen always
+ *   composes schemas this way; see module doc).
+ * @param depth - Internal recursion guard; callers never need to pass this.
+ */
+export declare function synthesizeExample(schema: JsonSchemaLike | undefined, root?: JsonSchemaLike, depth?: number): unknown;
+/**
+ * Render `schema`'s synthesized example as a compact `Example: {...}` note,
+ * or `undefined` if there's nothing meaningful to show (schema absent).
+ * Shared rendering so every call site (tool descriptions, validation error
+ * messages) produces byte-identical example text for the same schema.
+ */
+export declare function renderExampleNote(schema: JsonSchemaLike | undefined): string | undefined;

package/lib/hints.d.ts

@@ -15,18 +15,22 @@ export type CanonicalLogicalTypeId = (typeof CANONICAL_LOGICAL_TYPE_IDS)[number]
 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.
+ * {@link TEMPLATE_CELLS}.  `'typescript'`, `'python'`, and `'java'` (FEAT-APIGEN-001
+ * slice 1/3, 2026-08-06) are fully filled (§13.2 values verbatim / real
+ * Jackson expressions — see the `JAVA_COLUMN` doc comments below).
+ * `'rust'` and `'go'` remain 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.
+ * TypeScript, Python, and Java columns are fully filled (TypeScript/Python
+ * per DESIGN §13.2 verbatim expressions; Java per FEAT-APIGEN-001 slice 1/3 —
+ * real Jackson annotation/expression glue, no `__SCAFFOLD_*__` left — see
+ * `JAVA_COLUMN` above). Rust and Go columns remain scaffolded — structure
+ * complete, expressions use `__SCAFFOLD_*__` placeholders pending `lt-host-*`
+ * states.
  *
  * Keyed by {@link HostLanguage}, then by the canonical {@link CanonicalLogicalTypeId}.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhd/apigen-base-logical",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "main": "./index.js",
   "module": "./index.mjs",
   "typings": "./index.d.ts"