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

Author: claude

.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 -->

packages/spec/src/migrations/entries/semantic/18.field-max-length-malformed-or-misplaced-refused.ts

@@ -0,0 +1,53 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { SemanticMigration } from '../../types.js';
+
+export const entry: SemanticMigration = {
+  id: 'field-max-length-malformed-or-misplaced-refused',
+  surface: 'object field `maxLength` declarations — `maxLength: 0`, negative or non-integer '
+    + 'values on any type, and the key with any value on field types outside '
+    + '`BOUNDED_STRING_FIELD_TYPES` (`boolean`, `lookup`, `autonumber`, `formula`, `select`, '
+    + '`json`, `secret`, …)',
+  replacement: 'a positive-integer `maxLength` (>= 1) on a bounded-string field type — `text`, '
+    + '`textarea`, `email`, `url`, `phone`, `password`, `markdown`, `html`, `richtext`, `code` '
+    + '— or no declaration at all. Deleting the key is mechanical and behaviour-preserving '
+    + 'for a MISPLACED declaration: the write-time validator only ever applied `max_length` '
+    + 'inside its bounded-string branch, so the key was inert by construction on every other '
+    + 'type. A MALFORMED value on a bounded-string type is the judgment case — the '
+    + 'validator\'s raw `>` comparison did consume it (`maxLength: 0` accepted only the '
+    + 'empty string, a negative value refused every write, `maxLength: 12.5` behaved as '
+    + '"at most 12"), and the SQL schema-drift planner consumed `maxLength: 0` as '
+    + '`varchar(0)` DDL until #11431 taught it to defend itself — so only the author knows '
+    + 'the bound they MEANT: re-declare it as a positive integer, or delete it deliberately '
+    + 'accepting the unbounding',
+  reason:
+    '#11566 (maintainer ruling 2026-08-24; enforcement shipped on the 17.x line in PR '
+    + '#11989 — accept-set narrowings ride minors, and this entry tells `migrate meta` users '
+    + 'at the major boundary; registration was deferred to #11950 because the registry file '
+    + 'was serialized behind an in-flight change when the enforcement landed). Shape: a '
+    + 'character length is a positive integer, so the key tightened from `z.number()` to '
+    + '`z.number().int().min(1)` — `maxLength: 0` measurably sent schema-drift planning '
+    + '`varchar(0)` DDL no server accepts, at severity error/destructive, before #11431 '
+    + 'taught that consumer to defend itself (the #8321 `precision`/`scale` house pattern). '
+    + 'Applicability: the key sat on the BASE field schema — authorable on `boolean` / '
+    + '`lookup` / `autonumber`, types where nothing bounded is stored — while the write-time '
+    + 'validator (objectql `record-validator.ts`) only ever enforced it on its ten '
+    + 'bounded-string types, the one list of the three that had a measured reader; that list '
+    + 'is promoted to the protocol as `BOUNDED_STRING_FIELD_TYPES`, the schema refuses the '
+    + 'key outside it (ADR-0078 declared=enforced), and both authoring forms '
+    + '(`field.form.ts`, previously 3 types; `object.form.ts`, previously 9) show the key '
+    + 'for exactly that set.',
+  acceptanceCriteria:
+    'Every field declaring `maxLength` carries a positive integer and is a bounded-string '
+    + 'type. Well-formed declarations (a positive-integer `maxLength` on a bounded-string '
+    + 'type) parse byte-identically to before; fields declaring no `maxLength` are '
+    + 'untouched, and absence stays absence — no default materializes. Deleting a misplaced '
+    + 'key changes no runtime behaviour (it sat outside the validator\'s bounded-string '
+    + 'branch and enforced nothing). For a malformed value on a bounded-string type the '
+    + 'author decides: re-declare the intended positive-integer bound (enforced by the '
+    + 'write-time validator from the next write on, and honoured by schema drift as '
+    + '`varchar(n)`), or delete the key and accept the type\'s unbounded/default column '
+    + 'shape — either way the accidental old behaviour (empty-only writes under '
+    + '`maxLength: 0`, unwritable fields under a negative value) is gone by decision, not '
+    + 'by silence.',
+};

packages/spec/src/migrations/registry.ts

@@ -5853,6 +5853,55 @@ const step18: MigrationStep = {
         + '`metadata_spec_invalid` and are refused on their next authoring-path save — re-declare '
         + 'the field deliberately when that happens.',
     },
+    {
+      id: 'field-max-length-malformed-or-misplaced-refused',
+      surface: 'object field `maxLength` declarations — `maxLength: 0`, negative or non-integer '
+        + 'values on any type, and the key with any value on field types outside '
+        + '`BOUNDED_STRING_FIELD_TYPES` (`boolean`, `lookup`, `autonumber`, `formula`, `select`, '
+        + '`json`, `secret`, …)',
+      replacement: 'a positive-integer `maxLength` (>= 1) on a bounded-string field type — `text`, '
+        + '`textarea`, `email`, `url`, `phone`, `password`, `markdown`, `html`, `richtext`, `code` '
+        + '— or no declaration at all. Deleting the key is mechanical and behaviour-preserving '
+        + 'for a MISPLACED declaration: the write-time validator only ever applied `max_length` '
+        + 'inside its bounded-string branch, so the key was inert by construction on every other '
+        + 'type. A MALFORMED value on a bounded-string type is the judgment case — the '
+        + 'validator\'s raw `>` comparison did consume it (`maxLength: 0` accepted only the '
+        + 'empty string, a negative value refused every write, `maxLength: 12.5` behaved as '
+        + '"at most 12"), and the SQL schema-drift planner consumed `maxLength: 0` as '
+        + '`varchar(0)` DDL until #11431 taught it to defend itself — so only the author knows '
+        + 'the bound they MEANT: re-declare it as a positive integer, or delete it deliberately '
+        + 'accepting the unbounding',
+      reason:
+        '#11566 (maintainer ruling 2026-08-24; enforcement shipped on the 17.x line in PR '
+        + '#11989 — accept-set narrowings ride minors, and this entry tells `migrate meta` users '
+        + 'at the major boundary; registration was deferred to #11950 because the registry file '
+        + 'was serialized behind an in-flight change when the enforcement landed). Shape: a '
+        + 'character length is a positive integer, so the key tightened from `z.number()` to '
+        + '`z.number().int().min(1)` — `maxLength: 0` measurably sent schema-drift planning '
+        + '`varchar(0)` DDL no server accepts, at severity error/destructive, before #11431 '
+        + 'taught that consumer to defend itself (the #8321 `precision`/`scale` house pattern). '
+        + 'Applicability: the key sat on the BASE field schema — authorable on `boolean` / '
+        + '`lookup` / `autonumber`, types where nothing bounded is stored — while the write-time '
+        + 'validator (objectql `record-validator.ts`) only ever enforced it on its ten '
+        + 'bounded-string types, the one list of the three that had a measured reader; that list '
+        + 'is promoted to the protocol as `BOUNDED_STRING_FIELD_TYPES`, the schema refuses the '
+        + 'key outside it (ADR-0078 declared=enforced), and both authoring forms '
+        + '(`field.form.ts`, previously 3 types; `object.form.ts`, previously 9) show the key '
+        + 'for exactly that set.',
+      acceptanceCriteria:
+        'Every field declaring `maxLength` carries a positive integer and is a bounded-string '
+        + 'type. Well-formed declarations (a positive-integer `maxLength` on a bounded-string '
+        + 'type) parse byte-identically to before; fields declaring no `maxLength` are '
+        + 'untouched, and absence stays absence — no default materializes. Deleting a misplaced '
+        + 'key changes no runtime behaviour (it sat outside the validator\'s bounded-string '
+        + 'branch and enforced nothing). For a malformed value on a bounded-string type the '
+        + 'author decides: re-declare the intended positive-integer bound (enforced by the '
+        + 'write-time validator from the next write on, and honoured by schema drift as '
+        + '`varchar(n)`), or delete the key and accept the type\'s unbounded/default column '
+        + 'shape — either way the accidental old behaviour (empty-only writes under '
+        + '`maxLength: 0`, unwritable fields under a negative value) is gone by decision, not '
+        + 'by silence.',
+    },
     {
       id: 'field-min-length-malformed-or-misplaced-refused',
       surface: 'object field `minLength` declarations — `minLength: 0`, negative or non-integer '