fix(spec): a lazySchema reference keeps its authored description in z.toJSONSchema

zod reads .describe()/.meta() from its registry by node identity; a lazy
reference is the Proxy while the metadata sits on the real instance, so
every lazy conversion dropped the description an eager run keeps. The
_zod facade now aliases the real instance's metadata (less id) onto the
Proxy in the registry the conversion reads.

Claude-Session: https://claude.ai/code/session_01Sfe5YjBLwB9J3y8fvm2xq1
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

.changeset/19101-lazy-schema-keeps-describe.md

@@ -0,0 +1,18 @@
+---
+"@objectstack/spec": patch
+---
+
+JSON Schemas converted from a `lazySchema()` reference now carry the `description` the schema authored, the same as an `OS_EAGER_SCHEMAS=1` run (#19101).
+
+Clause-②: no
+
+zod reads `.describe()` / `.meta()` from its registry by node identity. A lazily built schema is referenced through a Proxy, while the metadata sits on the real instance behind it, so `z.toJSONSchema` found nothing and dropped the text. The published result depended on the evaluation mode, and every runtime producer runs lazily. The Proxy now answers the real instance's metadata to that lookup, less `id`, which stays on the real instance so that zod's duplicate-id refusal is never triggered.
+
+What changes: descriptions reappear. Nothing else does. Measured lazy against eager, leaf by leaf, across the four affected surfaces:
+
+- `@objectstack/spec/openapi.json`, and the `GET …/openapi.json` document served from it, gains 2 (`ListRecordResponse.data[]` and `BulkRequest.records[]`);
+- the `/meta/types` JSON Schemas gain 170 across 11 of 26 types;
+- the `os generate` IDE schema gains 445;
+- the approval-node and schemaless node-config schemas are unchanged.
+
+No other key differs in any of them, and the eager outputs are byte-identical before and after. The accept set does not change: `description` is an annotation, never a validation keyword.

packages/spec/src/shared/lazy-schema.test.ts

@@ -1,5 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
 import { describe, it, expect, vi } from 'vitest';
 import { z } from 'zod';
 import { lazySchema } from './lazy-schema';
@@ -117,3 +119,100 @@ describe('lazySchema × z.toJSONSchema identity', () => {
     expect((schema as any)._zod).toBe((schema as any)._zod);
   });
 });
+
+/**
+ * #19101 — a schema referenced through the Proxy converts with the SAME
+ * metadata as the eager instance. zod reads `.describe()` / `.meta()` from its
+ * registry by node identity; the node is the Proxy, the metadata sits on the
+ * real instance, so before the facade aliased it every lazy reference lost its
+ * `description` while `OS_EAGER_SCHEMAS=1` (no Proxy at all) kept it.
+ */
+describe('lazySchema × z.toJSONSchema metadata (#19101)', () => {
+  it('a lazy reference converts exactly like the eager instance — nested and as the root', () => {
+    const factory = () => z.record(z.string(), z.unknown()).describe('lazy-described record');
+    const lazy = lazySchema(factory);
+    const eager = factory();
+    expect(z.toJSONSchema(z.object({ rows: z.array(lazy) }))).toEqual(
+      z.toJSONSchema(z.object({ rows: z.array(eager) })),
+    );
+    expect(z.toJSONSchema(lazy)).toEqual(z.toJSONSchema(eager));
+  });
+
+  it("the real instance's own describe wins over the one it inherits from its parent", () => {
+    const Base = z.string().describe('inherited');
+    const lazy = lazySchema(() => Base.describe('own'));
+    const json = z.toJSONSchema(z.object({ v: lazy })) as { properties: { v: { description?: string } } };
+    expect(json.properties.v.description).toBe('own');
+  });
+
+  it('`id` is NOT aliased onto the Proxy — aliasing it makes zod throw "Duplicate schema id"', () => {
+    const Leaf: z.ZodType<any> = lazySchema(() =>
+      z.object({ x: z.string() }).meta({ id: 'LazySchemaIdProbe19101', description: 'probe' }),
+    );
+    const Doc = z.object({ a: (Leaf as any).optional(), b: z.lazy(() => Leaf) });
+    const json = z.toJSONSchema(Doc) as { properties: { b: { description?: string } } };
+    expect(json.properties.b.description).toBe('probe');
+    expect(z.globalRegistry.get(Leaf)?.id).toBeUndefined();
+  });
+});
+
+/**
+ * The same property on the real contract, against a REAL eager run: a child
+ * process imports the spec with `OS_EAGER_SCHEMAS=1` (no Proxy anywhere) and
+ * prints the conversions; this process converts the same schemas lazily. The
+ * child enters through `kernel/metadata-type-schemas.ts`, because an eager
+ * load that starts at `api/` or `data/` dies on the filter.zod → strict-object
+ * → suggestions.zod → field.zod cycle filed as #19930.
+ *
+ * Measured at the fix (lazy before → after, eager unchanged): the nine OpenAPI
+ * components gain 2 descriptions, every `/meta/types` schema 170, the
+ * `os generate` IDE schema 445; description is the only key that moved.
+ */
+describe('lazy == eager on the real contract (#19101)', () => {
+  const PKG_ROOT = fileURLToPath(new URL('../..', import.meta.url));
+  const CONTRACT = new URL('../api/contract.zod.ts', import.meta.url).href;
+  const METADATA_TYPES = new URL('../kernel/metadata-type-schemas.ts', import.meta.url).href;
+  const OPTS = { unrepresentable: 'any' } as const;
+  // tsx compiles .ts to CJS, so a namespace may arrive under `default`.
+  const pick = (mod: any, key: string): any => mod[key] ?? mod.default?.[key];
+
+  it('RecordDataSchema inside ListRecordResponse, and the `dataset` /meta/types schema', async () => {
+    const eager = JSON.parse(
+      execFileSync(
+        process.execPath,
+        ['--import', 'tsx', '--input-type=module', '-e',
+          `import ${JSON.stringify(METADATA_TYPES)};
+           const { z } = await import('zod');
+           const pick = (mod, key) => mod[key] ?? mod.default?.[key];
+           const contract = await import(${JSON.stringify(CONTRACT)});
+           const types = await import(${JSON.stringify(METADATA_TYPES)});
+           const opts = ${JSON.stringify(OPTS)};
+           process.stdout.write(JSON.stringify({
+             listRecordResponse: z.toJSONSchema(pick(contract, 'ListRecordResponseSchema'), opts),
+             dataset: z.toJSONSchema(pick(types, 'getMetadataTypeSchema')('dataset'), opts),
+           }));`],
+        {
+          cwd: PKG_ROOT,
+          env: { ...process.env, OS_EAGER_SCHEMAS: '1' },
+          encoding: 'utf8',
+          maxBuffer: 64 * 1024 * 1024,
+          stdio: ['ignore', 'pipe', 'pipe'],
+        },
+      ),
+    );
+
+    const contract = await import('../api/contract.zod');
+    const types = await import('../kernel/metadata-type-schemas');
+    const lazy = JSON.parse(JSON.stringify({
+      listRecordResponse: z.toJSONSchema(pick(contract, 'ListRecordResponseSchema'), OPTS),
+      dataset: z.toJSONSchema(pick(types, 'getMetadataTypeSchema')('dataset'), OPTS),
+    }));
+
+    // The named leaf first, for a failure that says what went missing.
+    const declared = pick(contract, 'RecordDataSchema').description;
+    expect(typeof declared === 'string' && declared.length > 0).toBe(true);
+    expect(eager.listRecordResponse.properties.data.items.description).toBe(declared);
+    expect(lazy.listRecordResponse.properties.data.items.description).toBe(declared);
+    expect(lazy).toStrictEqual(eager);
+  }, 60_000);
+});

packages/spec/src/shared/lazy-schema.ts

@@ -2,6 +2,19 @@
 
 import type { z } from 'zod';
 
+/** The slice of zod's metadata registry (`$ZodRegistry`) the facade uses. */
+interface MetadataRegistryLike {
+  get(schema: unknown): Record<string, unknown> | undefined;
+  has(schema: unknown): boolean;
+  add(schema: unknown, meta: Record<string, unknown>): unknown;
+}
+
+/** The slice of zod's `toJSONSchema` context a `processJSONSchema` hook receives. */
+interface JsonSchemaHookContext {
+  seen?: Map<unknown, unknown>;
+  metadataRegistry?: MetadataRegistryLike;
+}
+
 /**
  * Wrap a Zod schema constructor so its body is only evaluated on first use.
  *
@@ -52,6 +65,17 @@ export function lazySchema<T extends z.ZodTypeAny>(factory: () => T): T {
    * the real instance before delegating, so both identities resolve to the
    * same entry. If the real instance was already traversed under its own
    * identity it keeps its entry (alias, never clobber).
+   *
+   * The same wrapper aliases the real instance's METADATA onto the Proxy
+   * (#19101). zod reads a node's `.describe()` / `.meta()` with
+   * `ctx.metadataRegistry.get(node)` right after this hook returns — a
+   * WeakMap keyed on identity — and the node it holds is the Proxy while the
+   * metadata was registered on the real instance, so every lazySchema
+   * referenced by identity lost its authored `description` in lazy mode and
+   * kept it under `OS_EAGER_SCHEMAS=1`, where no Proxy exists. The two modes
+   * then published different JSON Schemas from one source: the OpenAPI
+   * artifact, `/meta/types` and the `os generate` IDE schema all shipped the
+   * lazy, description-less answer.
    */
   let zodFacade: object | undefined;
   const makeZodFacade = (real: T): object | undefined => {
@@ -63,18 +87,41 @@ export function lazySchema<T extends z.ZodTypeAny>(factory: () => T): T {
     return Object.create(realZod as object, {
       processJSONSchema: {
         enumerable: true,
-        value: (ctx: { seen?: Map<unknown, unknown> }, json: unknown, params: unknown) => {
+        value: (ctx: JsonSchemaHookContext, json: unknown, params: unknown) => {
           const seen = ctx?.seen;
           if (seen && typeof seen.get === 'function') {
             const entry = seen.get(proxy);
             if (entry !== undefined && !seen.has(real)) seen.set(real, entry);
           }
-          return delegate(ctx, json, params);
+          const emitted = delegate(ctx, json, params);
+          aliasMetadataOntoProxy(ctx?.metadataRegistry, real);
+          return emitted;
         },
       },
     }) as object;
   };
 
+  /**
+   * Register the real instance's metadata under the Proxy identity in the
+   * registry this conversion reads, once, and only when nothing is registered
+   * under the Proxy already (alias, never clobber). The registry merges a
+   * node's `_zod.parent` chain on read, which the Proxy shares with the real
+   * instance, so the Proxy then answers exactly what the real instance does —
+   * less `id`.
+   */
+  const aliasMetadataOntoProxy = (registry: MetadataRegistryLike | undefined, real: T): void => {
+    if (!registry || typeof registry.get !== 'function' || typeof registry.has !== 'function'
+      || typeof registry.add !== 'function' || registry.has(proxy)) {
+      return;
+    }
+    const meta = registry.get(real);
+    if (!meta) return;
+    const aliased: Record<string, unknown> = { ...meta };
+    // `id` stays un-aliased: the Proxy and the real instance both enter one conversion's seen map, and zod throws "Duplicate schema id" when two of its nodes share an id.
+    delete aliased.id;
+    if (Object.keys(aliased).length > 0) registry.add(proxy, aliased);
+  };
+
   const proxy = new Proxy(target as object, {
     get(_t, prop) {
       const real = resolve() as unknown as Record<PropertyKey, unknown>;