@ultimat3/schema 19.2.0 → 19.3.1

package/CLAUDE.md

@@ -140,6 +140,17 @@ Gotchas:
   different instant per host `TZ`, and `coerceQuery` puts it one query parameter from the wire.
   A date-only string carries no clock time and is UTC by spec, so it still parses.
 - Adding a `SchemaKind` means updating `json-schema.ts` and `coerce.ts` in the same commit.
+- **`ToJsonSchemaOptions.dialect` is a closed vocabulary read with `Object.hasOwn`** (`As of
+  2026-09-06`). `DIALECTS[dialect]` on an object literal answered the `Object` FUNCTION for
+  `dialect: 'constructor'` — measured: `$schema` held it, `JSON.stringify` dropped the key in
+  silence, and every consumer that does not serialise (the MCP tool schema, the OpenAPI writer
+  that spreads this document) carried a function. It is a field on a PUBLIC entry point, so the
+  key is caller data. `bun run proto-index` could not see the read until its null-prototype
+  exemption became per TABLE: `convert`'s unrelated `Object.create(null)` exempted the whole file.
+  The refusal is `X_SCHEMA_UNSUPPORTED` — the same question that code already answers, and a code
+  is stable forever once shipped — and it fires whether or not `includeDialect` would have emitted
+  the value, because a rule a caller learns half of is a rule they learn wrong. The rejected value
+  is `describeValue`d in the `cause` and whole in `meta`, never echoed.
 - **Prefer a new `SchemaNode` FIELD to a new `SchemaKind`.** Every consumer that switches on `kind`
   has a `default:` that degrades quietly — `json-schema.ts` emits `{}`, `coerce.ts` passes the raw
   value through, `@ultimat3/action`'s `sample-input.ts` answers `null` — and they live in packages

package/README.md

@@ -155,6 +155,7 @@ swap. `introspect()` is what OpenAPI/MCP generation needs; a provider without it
 ```ts
 toJsonSchema(publishPost);                    // OpenAPI 3.1 (2020-12)
 toMcpInputSchema(publishPost);                // MCP tools/list (draft-07, no $schema)
+toJsonSchema(publishPost, { dialect: 'x' });  // X_SCHEMA_UNSUPPORTED — the two spellings are closed
 parse(publishPost, coerceQuery(publishPost, url.searchParams));
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/schema",
-  "version": "19.2.0",
+  "version": "19.3.1",
   "description": "Ultimate's validation seam: Standard Schema interface, the t namespace, JSON Schema output",
   "license": "MIT",
   "type": "module",

package/src/json-schema.ts

@@ -1,9 +1,13 @@
 // Single responsibility: SchemaNode -> JSON Schema. Load-bearing: OpenAPI request/response
 // bodies and MCP tool `inputSchema` are both this function's output, so an agent's view of an
-// action and an HTTP client's view can never drift.
+// action and an HTTP client's view can never drift. Where the projection and the PARSER differ,
+// the published document states the narrower of the two — see `date` and `record` below.
 
+import { describeValue } from './describe-value';
+import { SchemaUnsupportedError } from './errors';
 import { CURRENCY_CODE_PATTERN, MAX_MONEY_SCALE } from './money-value';
 import { requiredKeys, type SchemaNode, type SchemaRefinement } from './node';
+import { PROTOTYPE_KEYS } from './prototype-keys';
 import { introspect } from './provider';
 
 export type JsonSchemaType =
@@ -37,6 +41,10 @@ export interface JsonSchema {
   readonly properties?: Readonly<Record<string, JsonSchema>>;
   readonly required?: readonly string[];
   readonly additionalProperties?: boolean | JsonSchema;
+  /** What a record's KEYS must satisfy. Draft-06 and later, so it is honest in both dialects. */
+  readonly propertyNames?: JsonSchema;
+  /** Negation. Emitted only inside `propertyNames`, to publish a closed set of refused keys. */
+  readonly not?: JsonSchema;
   readonly items?: JsonSchema;
   readonly anyOf?: readonly JsonSchema[];
   readonly discriminator?: JsonSchemaDiscriminator;
@@ -177,6 +185,15 @@ function convert(node: SchemaNode): JsonSchema {
       return annotate(numberNode(node));
     case 'boolean':
       return annotate({ type: 'boolean' });
+    // Narrower than the parser, deliberately. `dateSchema` also accepts a `number` — epoch
+    // milliseconds — as a coercion convenience for a value that never crossed a wire as JSON, and
+    // publishing `anyOf: [{ type: 'string', format: 'date-time' }, { type: 'number' }]` would tell
+    // every generated client, every agent reading a tool schema and every OpenAPI consumer that an
+    // epoch number is a supported spelling of an instant. It is not one: it carries no zone, it is
+    // ambiguous about seconds versus milliseconds, and `t.date`'s own refusal says ISO-8601. So
+    // the contract publishes the one spelling a caller should send, and the parser stays the more
+    // permissive of the two — the safe direction, where the boundary accepts a value the document
+    // did not promise rather than promising one it refuses.
     case 'date':
       return annotate({ type: 'string', format: 'date-time' });
     case 'enum':
@@ -201,6 +218,13 @@ function convert(node: SchemaNode): JsonSchema {
       return annotate({
         type: 'object',
         additionalProperties: node.valueNode === undefined ? true : convert(node.valueNode),
+        // The key rule, published rather than left implicit: `recordSchema` refuses
+        // `__proto__` / `constructor` / `prototype` by name, and without this the document
+        // advertised them — an OpenAPI body, a generated client and an MCP tool all sending a key
+        // the boundary answers with a 422. `propertyNames` is draft-06 and later, so the one
+        // emission is valid in both dialects this file publishes; the names come from
+        // `prototype-keys.ts`, which the parser reads too, so the two views cannot drift.
+        propertyNames: { not: { enum: PROTOTYPE_KEYS } },
       });
     case 'money':
       return annotate({
@@ -253,12 +277,39 @@ function convert(node: SchemaNode): JsonSchema {
   }
 }
 
+/**
+ * The dialect a caller asked for, or a refusal. `Object.hasOwn`, never the read alone: `dialect` is
+ * a field on this file's public entry point, so it is CALLER data, and `DIALECTS['constructor']`
+ * answers the `Object` function — measured, `$schema` held that function, `JSON.stringify` dropped
+ * the key in silence, and every consumer that does not serialise (the MCP tool schema, the OpenAPI
+ * writer that spreads this document) carried it. `bun run proto-index` could not see the read: the
+ * unrelated `Object.create(null)` in `convert` above exempted this whole FILE until that rule
+ * became per-table.
+ *
+ * `X_SCHEMA_UNSUPPORTED` rather than a new code: this is the same question `toJsonSchema` already
+ * answers with it — a document this package cannot publish — and a code is stable forever once
+ * shipped, so a fourth one for one option would be a fourth thing to document.
+ */
+function dialectUri(dialect: string): string {
+  if (Object.hasOwn(DIALECTS, dialect)) return DIALECTS[dialect as JsonSchemaDialect];
+  throw new SchemaUnsupportedError({
+    // `describeValue`, never the value: this cause is folded into a log line and an HTTP problem
+    // document, and the two spellings that WORK are what a caller needs, not their own back.
+    cause: `a json schema dialect must be '2020-12' or 'draft-07'; got ${describeValue(dialect)}`,
+    fix: "toJsonSchema(schema, { dialect: '2020-12' })   # or 'draft-07' for an MCP tool schema",
+    meta: { dialect },
+  });
+}
+
 /** Convert any schema the active provider can introspect. */
 export function toJsonSchema(schema: unknown, options?: ToJsonSchemaOptions): JsonSchema {
   const converted = convert(introspect(schema));
-  const dialect = options?.dialect ?? '2020-12';
+  // Resolved BEFORE `includeDialect` is read: a dialect nothing publishes is a caller mistake
+  // whether or not this document happens to emit `$schema`, and a refusal that fires for one flag
+  // and not the other is a rule a caller learns the wrong half of.
+  const uri = dialectUri(options?.dialect ?? '2020-12');
   return {
-    ...(options?.includeDialect === false ? {} : { $schema: DIALECTS[dialect] }),
+    ...(options?.includeDialect === false ? {} : { $schema: uri }),
     ...(options?.title === undefined ? {} : { title: options.title }),
     ...converted,
   };

package/src/prototype-keys.ts

@@ -0,0 +1,19 @@
+// Single responsibility: which record keys reach an object's prototype instead of its own
+// properties. One definition, because the rule that REFUSES a key (`validators.ts`) and the
+// document that PUBLISHES the refusal (`json-schema.ts`) must name the same closed set — the same
+// reason `char-count.ts` owns the unit a length is counted in.
+
+/**
+ * A record's keys are the caller's, so `{"__proto__":{…}}` on a `{}` literal set the OUTPUT's
+ * prototype: `Object.keys` answered `[]` while `settings[k] ?? fallback` handed a handler the
+ * attacker's value for a key that was never sent. `recordSchema` refuses these by name AND builds
+ * on a null prototype — the null prototype alone would keep `__proto__` as a silent own key nobody
+ * declared — and `json-schema.ts` emits them as a `propertyNames` constraint, so OpenAPI, the
+ * typed client and an MCP tool schema advertise exactly what the boundary accepts rather than
+ * promising keys it answers with a 422.
+ */
+export const PROTOTYPE_KEYS: readonly string[] = ['__proto__', 'constructor', 'prototype'];
+
+/** The membership test the parser applies. A list is what the projection publishes; this is the
+ * same fact asked the other way, so neither side builds its own `Set`. */
+export const isPrototypeKey = (key: string): boolean => PROTOTYPE_KEYS.includes(key);

package/src/validators.ts

@@ -23,6 +23,7 @@ import { discriminatedUnionSchema } from './discriminated-union';
 import { isZonelessDateTime } from './iso-date';
 import { type MoneyValue, moneySchema } from './money-value';
 import type { SchemaNode } from './node';
+import { isPrototypeKey, PROTOTYPE_KEYS } from './prototype-keys';
 import type { InferInput, InferOutput, StandardIssue } from './standard';
 import { isIanaZoneName } from './time-zone-name';
 
@@ -275,15 +276,6 @@ export function unionSchema<S extends readonly [AnySchema, ...AnySchema[]]>(
   });
 }
 
-/**
- * Keys that reach an object's prototype rather than its own properties. A record's keys are the
- * caller's, so `{"__proto__":{…}}` on a `{}` literal set the OUTPUT's prototype: `Object.keys`
- * answered `[]` while `settings[k] ?? fallback` handed a handler the attacker's value for a key
- * that was never sent. Refused by name AND built on a null prototype — the null prototype alone
- * would keep `__proto__` as a silent own key nobody declared.
- */
-const PROTOTYPE_KEYS: ReadonlySet<string> = new Set(['__proto__', 'constructor', 'prototype']);
-
 export function recordSchema<S extends AnySchema>(
   values: S,
 ): Schema<Readonly<Record<string, InferInput<S>>>, Record<string, InferOutput<S>>> {
@@ -311,11 +303,11 @@ export function recordSchema<S extends AnySchema>(
         // new spelling to learn. It is `Object.entries` order — integer-like keys sort ahead of
         // string ones — so it names an entry that exists rather than a byte offset in the body.
         const at = [...path, index];
-        if (PROTOTYPE_KEYS.has(key)) {
+        if (isPrototypeKey(key)) {
           issues.push({
             // The refused NAMES are a closed set declared right here, so the message may state
             // them: that is the one part of this line the caller did not choose.
-            message: expected(`a record key that is not ${[...PROTOTYPE_KEYS].join(' | ')}`, key),
+            message: expected(`a record key that is not ${PROTOTYPE_KEYS.join(' | ')}`, key),
             path: at,
           });
           continue;