fix(spec): minLength is a positive integer, authorable only on bounded-string field types; register the deferred #11566 maxLength ADR-0087 entry (#12191)

* fix(spec): minLength is a positive integer, authorable only on bounded-string field types

Issue #11949 context (maintainer ruling 2026-08-25, option B): the #11566
template applies in full. Shape tightens to z.number().int().min(1) — the
lower bound is 1, so minLength: 0 is refused loudly ("no minimum" is
expressed by omitting the key, not by declaring a vacuous truth).
Applicability converges on BOUNDED_STRING_FIELD_TYPES via a superRefine twin
of maxLength's; both authoring-form rows align to the same set
(field.form.ts previously showed the key for 3 types, object.form.ts for 9).
Card relationship is declared in the PR body, not here.

Ruled pre-step: corpus + generator grep for minLength: 0 / negative /
fractional output — zero hits repo-wide, so no cleanup rides the PR and no
customer-facing generator fork exists.

- field.zod.ts: shape + applicability superRefine + set doc comment
- field.form.ts / object.form.ts: minLength rows aligned to the ten
- field.test.ts: refusal envelopes (path + code + message) for 0 / -5 / 12.5
  and for nine wrong-type representatives; byte-identical round-trip on all
  ten bounded-string types; minLength: 1 lower-bound pin; absence stays
  absent
- lint RHS-rule census re-derived 44 -> 41 (3 fewer == literal comparisons
  after the in-list respell of the field-form row — the #11989 precedent)
- D3 semantic entry field-min-length-malformed-or-misplaced-refused
  (major-18 one-file shard + gen:migration-registry)
- changeset: @objectstack/spec minor (launch-window convention), adr-0087:
  registered

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NDGG54XF5gbTLdQzCtnaVV

* feat(spec): register the deferred #11566 maxLength narrowing in the ADR-0087 ledger

Issue #11950 context: the #11566 enforcement (PR #11989) shipped without its
ADR-0087 ledger entry — the migrations registry was serialized behind an
in-flight change in that wave — and this commit lands the missing half as a
major-18 D3 semantic entry, following the #8321 scale/precision template.
Semantics are authoritative to PR #11989's actual diff: refused shapes
(0 / negative / non-integer on any type), refused placement (any value
outside the ten-member BOUNDED_STRING_FIELD_TYPES set as of that landing),
forms convergence, byte-identical round-trip for well-formed declarations.
The entry separates the mechanical half (misplaced keys were inert by
construction — the validator's bounded-string branch never read them) from
the judgment half (malformed values on bounded-string types WERE consumed by
the raw comparison — maxLength: 0 accepted only empty strings, a negative
value refused every write — so the author must re-declare the bound they
meant). No accept/reject behaviour moves in this commit. Card relationship
is declared in the PR body, not here.

- D3 semantic entry field-max-length-malformed-or-misplaced-refused
  (major-18 one-file shard + gen:migration-registry)
- changeset: @objectstack/spec minor, adr-0087: registered

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NDGG54XF5gbTLdQzCtnaVV

* regen: migration registry + docs references from the merged tree

Discharges the os-regen deferral the merge commit recorded: registry
regenerated from the (merge-updated) semantic shards; field.mdx rendered
from the merged schema (minLength row at the twelve-member set).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NDGG54XF5gbTLdQzCtnaVV

---------

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

Author: os-litant

.changeset/maxlength-adr0087-ledger-entry.md

@@ -0,0 +1,7 @@
+---
+'@objectstack/spec': minor
+---
+
+The #11566 `maxLength` narrowing (shipped in 17.x: `z.number().int().min(1)`, refused outside `BOUNDED_STRING_FIELD_TYPES`) is now registered in the ADR-0087 migration ledger (#11950) — the enforcement PR deliberately deferred the entry because the registry file was serialized behind an in-flight change. Following the #8321 `scale`/`precision` template, the major-18 semantic entry carries both halves: the mechanical one (delete the key where it was misplaced — inert by construction outside the write-time validator's bounded-string branch) and the judgment one (a malformed value on a bounded-string type WAS consumed by the validator's raw comparison — `maxLength: 0` accepted only empty strings, a negative value refused every write — so only the author knows the bound they meant; the entry tells them to re-declare it). `objectstack migrate meta`, `spec-changes.json` and the upgrade guide surface the entry at the major boundary; no accept/reject behaviour changes in this release.
+
+<!-- adr-0087: registered field-max-length-malformed-or-misplaced-refused -->

.changeset/minlength-bounded-string-only.md

@@ -0,0 +1,9 @@
+---
+'@objectstack/spec': minor
+---
+
+`FieldSchema.minLength` tightens on both axes (#11949, maintainer ruling 2026-08-25) — `maxLength`'s twin defect pair (#11566), closed with the same template. Shape: the key is now `z.number().int().min(1)`, so `minLength: 0`, negative and non-integer declarations are refused at parse. The lower bound is 1 by ruling: "no minimum" is expressed by omitting the key, not by declaring a vacuous truth — `minLength: 0` can never fail, and a permanently-true declaration is exactly the noise an AI metadata author mass-produces, so it is refused loudly at authoring time. Applicability: the key sat on the base schema and was authorable on every field type; it is now refused on any type that does not store a bounded string, and accepted on exactly the `BOUNDED_STRING_FIELD_TYPES` set — `text`, `textarea`, `email`, `url`, `phone`, `password`, `markdown`, `html`, `richtext`, `code`, `signature`, `qrcode` (twelve members since #11875) — the same set `maxLength` converged on.
+
+What newly gets rejected: `minLength: 0` / negative / non-integer on any type, and `minLength` with any value on every non-bounded-string type (`boolean`, `number`, `date`, `select`, `lookup`, `autonumber`, `formula`, `json`, `secret`, …). Both rejections are prescriptive — the message names the legal shape, the legal type set, and the fix. The two authoring forms converge on the same set (`field.form.ts` previously showed the key for three types; `object.form.ts` for nine). Already-legal declarations (a positive-integer `minLength` on a bounded-string type) round-trip byte-identically, and absence stays absence — no default materializes.
+
+<!-- adr-0087: registered field-min-length-malformed-or-misplaced-refused -->

content/docs/references/data/field.mdx

@@ -66,7 +66,7 @@ const result = CurrencyConfigSchema.parse(data);
 | **unique** | `boolean \| 'global' \| 'organization'` | optional (default: `false`) | Unique constraint and its scope (ADR-0120). 'organization' = one holder per organization (NULL-safe composite with the organization key part on organization-scoped objects) — prefer this explicit spelling in new code; true = same per-organization scope (positional synonym, stays valid); 'global' = one holder across the whole installation. 'tenant'/'org' are rejected — the word is 'organization' |
 | **defaultValue** | `any` | optional | Default applied on INSERT when the field is omitted or null (`''` is a real value, not absence). Three legal shapes (#7127), discriminated in the engine's own order: a CEL Expression envelope `{ dialect: 'cel', source: 'today()' }` (accepted structurally; result type is a runtime concern); a runtime TOKEN — `NOW()` on `datetime`/`date`/`time` only, `current_user` on `user` or `lookup` with `reference: 'sys_user'` only, neither on a multi-value field; or a LITERAL, which must satisfy this field's own stored value contract (ADR-0104 D1 `valueSchemaFor`). Anything else is refused at parse time with a prescriptive message. |
 | **maxLength** | `integer` | optional | Max character length (positive integer). Only authorable on types that store a bounded string: text, textarea, email, url, phone, password, markdown, html, richtext, code, signature, qrcode. |
-| **minLength** | `number` | optional | Min character length |
+| **minLength** | `integer` | optional | Min character length (positive integer; `minLength: 0` is refused — express "no minimum" by omitting the key). Only authorable on types that store a bounded string: text, textarea, email, url, phone, password, markdown, html, richtext, code, signature, qrcode. |
 | **precision** | `integer` | optional | Total digits (non-negative integer) |
 | **scale** | `integer` | optional | Decimal places (non-negative integer) |
 | **min** | `number` | optional | Minimum value |

packages/lint/src/validate-predicate-path-refs.test.ts

@@ -598,14 +598,15 @@ describe('#7010 corpus — shipped METADATA_FORM_REGISTRY', () => {
       for (const value of Object.values(rec)) rewrite(value);
     };
     rewrite(corrupted.views);
-    // The count tracks the CORPUS, not an issue: 44 today because #11566
-    // (PR #11989) respelled the field form's `maxLength` row from a 3-way
+    // The count tracks the CORPUS, not an issue: 41 today because #11949
+    // respelled the field form's `minLength` row from a 3-way
     // `data.type == '…'` chain to one `data.type in […]` list while aligning
     // it to the ten bounded-string types — 3 fewer `==` literal comparisons,
     // and `in`-list literals are deliberately not this rule's (see the anchor
-    // note above). The pre-#11566 measurement was 47 and stays 47 — history,
-    // not the census.
-    expect(comparisons, 'no shipped predicate carries an `==`/`!=` literal comparison').toBe(44);
+    // note above) — exactly the #11566 (PR #11989) respell of the sibling
+    // `maxLength` row, which took the measurement from 47 to 44. Earlier
+    // measurements stay what they were — history, not the census.
+    expect(comparisons, 'no shipped predicate carries an `==`/`!=` literal comparison').toBe(41);
 
     const rhsFindings = validatePredicatePathRefs(corrupted)
       .filter((f) => f.rule === PREDICATE_RHS_PATH_SHAPED);

packages/spec/src/data/field.form.ts

@@ -35,7 +35,12 @@ export const fieldForm = defineForm({
         { field: 'defaultValue', helpText: 'Default value for new records' },
         { field: 'placeholder', helpText: 'Hint text shown inside the empty input (disappears once a value is entered); use inlineHelpText for always-visible help' },
         // Text field options
-        { field: 'minLength', visibleWhen: "data.type == 'text' || data.type == 'textarea' || data.type == 'email'", helpText: 'Minimum character length' },
+        // #11949 — `minLength` converges on the same bounded-string types as
+        // `maxLength` below (BOUNDED_STRING_FIELD_TYPES; maintainer ruling
+        // 2026-08-25: the #11566 template applies in full). This row used to
+        // show the key for 3 types while the schema accepted it on every
+        // type; it moves with the set, exactly like the row below.
+        { field: 'minLength', visibleWhen: "data.type in ['text','textarea','email','url','phone','password','markdown','html','richtext','code','signature','qrcode']", helpText: 'Minimum character length' },
         // #11566 — `maxLength` is shown for exactly the bounded-string types
         // the schema accepts it on and the write-time validator enforces it
         // for (BOUNDED_STRING_FIELD_TYPES; maintainer ruling 2026-08-24).

packages/spec/src/data/field.test.ts

@@ -444,6 +444,99 @@ describe('FieldSchema', () => {
         }
       });
     });
+
+    /**
+     * #11949 (maintainer ruling 2026-08-25) — `minLength` converges on the
+     * #11566 template above: `maxLength`'s twin defect pair (no shape
+     * validation + authorable on every type), the same convergence. The lower
+     * bound is deliberately 1: `minLength: 0` is a permanently-true
+     * declaration ("no minimum" is expressed by omitting the key), exactly
+     * the vacuous noise an AI metadata author mass-produces, so it is
+     * refused loudly at authoring rather than parsing cleanly and asserting
+     * nothing.
+     */
+    describe('malformed or misplaced minLength declarations are refused at authoring (#11949)', () => {
+      const shapeCases: Array<[value: number, code: string]> = [
+        [0, 'too_small'],     // the ruled fork: a vacuous "no minimum" declaration
+        [-5, 'too_small'],
+        [12.5, 'invalid_type'], // non-integer count
+      ];
+      for (const [value, code] of shapeCases) {
+        it(`refuses minLength: ${value} on a text field with a ${code} issue at [minLength]`, () => {
+          const result = FieldSchema.safeParse({
+            name: 'title', label: 'Title', type: 'text', minLength: value,
+          });
+          expect(result.success).toBe(false);
+          if (!result.success) {
+            const issue = result.error.issues.find((i) => i.path[0] === 'minLength');
+            expect(issue?.code).toBe(code);
+            // Message substance, not just a throw: the refusal names what a
+            // legal value looks like (int / >=1), so an AI author can fix it.
+            expect(issue?.message).toMatch(code === 'invalid_type' ? /expected int/ : />=1/);
+          }
+        });
+      }
+
+      // Same representative families as the maxLength block above — the
+      // base-schema placement this key is converging away from — including
+      // `secret` and `color`, the near-misses the #11875 ruling explicitly
+      // left OUT of the set.
+      const wrongTypes = [
+        'boolean', 'number', 'date', 'select', 'lookup', 'autonumber',
+        'formula', 'json', 'secret', 'color',
+      ] as const;
+      for (const type of wrongTypes) {
+        it(`refuses minLength on type: '${type}' with a custom issue at [minLength]`, () => {
+          const result = FieldSchema.safeParse({
+            name: 'f', label: 'F', type, minLength: 3,
+          });
+          expect(result.success).toBe(false);
+          if (!result.success) {
+            const issue = result.error.issues.find((i) => i.path[0] === 'minLength');
+            expect(issue?.code).toBe('custom');
+            // The refusal names the legal set and the offending type, so an
+            // AI author can fix the declaration without leaving the message.
+            expect(issue?.message).toMatch(/bounded string/);
+            expect(issue?.message).toContain(`\`${type}\``);
+          }
+        });
+      }
+
+      it('accepts a positive-integer minLength on every bounded-string type, round-tripping byte-identically', () => {
+        // Hardcoded on purpose (not iterated off the export) so this test is
+        // an independent measurement of the set, not a tautology. Ten at
+        // #11566; `signature` / `qrcode` joined in #11875.
+        const twelve = [
+          'text', 'textarea', 'email', 'url', 'phone', 'password',
+          'markdown', 'html', 'richtext', 'code', 'signature', 'qrcode',
+        ] as const;
+        for (const type of twelve) {
+          const result = FieldSchema.safeParse({
+            name: 'f', label: 'F', type, minLength: 2,
+          });
+          expect(result.success).toBe(true);
+          if (result.success) expect(result.data.minLength).toBe(2);
+        }
+      });
+
+      it('accepts minLength: 1 (the lower bound is 1, not 2) and both bounds together', () => {
+        const result = FieldSchema.safeParse({
+          name: 'f', label: 'F', type: 'text', minLength: 1, maxLength: 255,
+        });
+        expect(result.success).toBe(true);
+        if (result.success) {
+          expect(result.data.minLength).toBe(1);
+          expect(result.data.maxLength).toBe(255);
+        }
+      });
+
+      it('absent minLength stays absent — no default materializes, on any type', () => {
+        for (const type of ['text', 'boolean', 'lookup'] as const) {
+          const result = FieldSchema.parse({ name: 'f', label: 'F', type }) as Record<string, unknown>;
+          expect('minLength' in result).toBe(false);
+        }
+      });
+    });
   });
 
   describe('useGrouping — number-field digit-grouping presentation hint (#7768)', () => {

packages/spec/src/data/field.zod.ts

@@ -111,9 +111,10 @@ export type FieldType = z.input<typeof FieldType>;
  * three lists used to disagree (field.form showed the key for 3 types,
  * object.form for 9, the validator enforced 10), and the validator's ten is
  * the only one with a measured reader. `FieldSchema` refuses `maxLength`
- * outside this set (see the superRefine below), and the two authoring forms
- * show the key for exactly this set — declared converges to enforced
- * (ADR-0078).
+ * outside this set (see the superRefine below) — and, per the #11949 ruling
+ * (2026-08-25), `minLength` too: the twin defect pair converges on the same
+ * template — and the two authoring forms show both keys for exactly this
+ * set — declared converges to enforced (ADR-0078).
  *
  * `signature` / `qrcode` joined in #11875 (maintainer ruling 2026-08-25,
  * option 1): their stored value IS the author's own string and routinely far
@@ -897,7 +898,14 @@ export const FieldSchema = lazySchema(() => {
   // consumer to defend itself). Which TYPES may author the key is the
   // superRefine below (BOUNDED_STRING_FIELD_TYPES).
   maxLength: z.number().int().min(1).optional().describe('Max character length (positive integer). Only authorable on types that store a bounded string: text, textarea, email, url, phone, password, markdown, html, richtext, code, signature, qrcode.'),
-  minLength: z.number().optional().describe('Min character length'),
+  // #11949 (maintainer ruling 2026-08-25) — `minLength` converges on the
+  // #11566 template above, `maxLength`'s twin defect pair: same shape, same
+  // applicability set, same forms convergence. The lower bound is deliberately
+  // 1, not 0: "no minimum" is expressed by OMITTING the key, so `minLength: 0`
+  // is a permanently-true declaration — exactly the vacuous noise an AI
+  // metadata author mass-produces — and is refused loudly at authoring instead
+  // of parsing cleanly and asserting nothing.
+  minLength: z.number().int().min(1).optional().describe('Min character length (positive integer; `minLength: 0` is refused — express "no minimum" by omitting the key). Only authorable on types that store a bounded string: text, textarea, email, url, phone, password, markdown, html, richtext, code, signature, qrcode.'),
 
   /** Number Constraints */
   // #8321 — `precision`/`scale` are digit COUNTS, so a non-integer or negative
@@ -1677,6 +1685,31 @@ export const FieldSchema = lazySchema(() => {
     });
   }
 
+  // [#11949] (maintainer ruling 2026-08-25 — the #11566 template applies in
+  // full): `minLength` is only authorable on types that store a bounded
+  // string — the same defect pair, the same convergence. The key sat on the
+  // BASE schema, so it was legal on `boolean` / `lookup` / `autonumber` —
+  // types where nothing bounded is stored — while the write-time validator
+  // has only ever applied `min_length` on the BOUNDED_STRING_FIELD_TYPES
+  // set. Declared converges to enforced (ADR-0078). `minLength` has no
+  // schema default, so `undefined` here always means "not authored" — a
+  // field without the key can never fire this. The message enumerates the
+  // set ITSELF rather than a prose copy of it — the #11875 lesson the
+  // `maxLength` twin above records (#12017 two-copies failure shape).
+  if (field.minLength !== undefined && !BOUNDED_STRING_FIELD_TYPES.has(field.type)) {
+    ctx.addIssue({
+      code: 'custom',
+      path: ['minLength'],
+      message:
+        `\`minLength\` is only valid on field types that store a bounded string — ` +
+        `${[...BOUNDED_STRING_FIELD_TYPES].map((t) => `'${t}'`).join(', ')} — ` +
+        `and this field is \`${field.type}\`: its stored value has no ` +
+        'character length for the bound to constrain, so the declaration would parse and ' +
+        'enforce nothing (the write-time validator applies `minLength` to exactly those ' +
+        'types). Drop the key, or use a bounded string type.',
+    });
+  }
+
   // #7918 (maintainer ruling 2026-08-12, Option A): the FIELD-level
   // `precision` key doubles as the currency display width — objectui's
   // CurrencyField reads it, and objectui#4361 pinned authored-precision-wins

packages/spec/src/data/object.form.ts

@@ -129,7 +129,11 @@ export const objectForm = defineForm({
             // (the write seam now enforces their declared bound); this
             // visibleWhen moves with the set.
             { field: 'maxLength', type: 'number', helpText: 'Max characters', visibleWhen: "data.type in ['text','textarea','email','url','phone','password','markdown','html','richtext','code','signature','qrcode']" },
-            { field: 'minLength', type: 'number', helpText: 'Min characters', visibleWhen: "data.type in ['text','textarea','email','url','phone','password','markdown','html','richtext']" },
+            // #11949 — `minLength` aligned to the same set (maintainer ruling
+            // 2026-08-25: the #11566 template applies in full). This row used
+            // to stop at 9 types (`code` was the one it was missing); it moves
+            // with the set, exactly like the row above.
+            { field: 'minLength', type: 'number', helpText: 'Min characters', visibleWhen: "data.type in ['text','textarea','email','url','phone','password','markdown','html','richtext','code','signature','qrcode']" },
 
             // Numeric constraints
             { field: 'min', type: 'number', helpText: 'Minimum value', visibleWhen: "data.type in ['number','currency','percent','rating','slider','progress']" },