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

Fixes #19101

Clause-②: no

<sub>Rewritten short by the `domain:spec#5` seat (2026-09-24T01:31Z; one
count cut after record `5805815738`). The dev reports are on #19101
(`5805027961`, `5805539465`), and the seat ruling is `5805064236`.</sub>

A schema referenced through a `lazySchema` Proxy lost its authored
`.describe()` text in `z.toJSONSchema`. zod reads metadata from a
registry keyed on object identity; the node it holds is the Proxy, while
the description was registered on the real instance. The shipped JSON
Schemas were therefore built lazily and missed those descriptions. Under
`OS_EAGER_SCHEMAS=1`, where there is no Proxy, they were present.

## What changed

- `packages/spec/src/shared/lazy-schema.ts`: the facade's
`processJSONSchema` wrapper registers the real instance's metadata on
the Proxy in the registry the conversion reads. It does this once, never
over an existing entry, and leaves out `id`: aliasing `id` makes zod
throw "Duplicate schema id".
- Measured by the dev, lazy after the fix against eager, leaf by leaf,
with 0 diffs in each corpus:
  - the `openapi.json` components gain 2 descriptions;
  - the `os generate` IDE schema gains 445.

  Only `description` moves, and eager output is unchanged.
- Pins in `lazy-schema.test.ts`. Deleting the alias call turns 4 of them
red; deleting the `id` exclusion turns the `id` pin red.
- Changeset: `@objectstack/spec` patch.

## Not in this PR

- An eager run of `gen:openapi` still crashes on a `src` import cycle,
and the same cycle crashes the published `/api` and `/data` entries
under `OS_EAGER_SCHEMAS=1`: #19930.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_01Sfe5YjBLwB9J3y8fvm2xq1

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: objectstack-fleet[bot]

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

@@ -0,0 +1,17 @@
+---
+"@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. 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:
+
+- `@objectstack/spec/openapi.json`, and the `GET …/openapi.json` document served from it, gains 2 (`ListRecordResponse.data[]` and `BulkRequest.records[]`);
+- 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 unknown 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 unknown 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, 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 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>;