docs(cli): correct the reason the driver constants are transcribed

CORRECTING THE RECORD. Three commit messages on this branch, and three sites in
the code, give as their FIRST reason for transcribing the driver's constants
that those members reach no exported surface. That is false, and this queue
composes the squash body from the branch's commit messages, so the sentences
below would land in `main` as written:

  * 9cc1a76 -- "The transcription is still necessary, for two other
    reasons: the constant is `protected static`, and #5726 forbids a CLI
    production module any static value import of a driver package."
  * 11d0e8d -- "`MAX_VARCHAR_CHARS`, `MAX_KEYABLE_VARCHAR_CHARS`,
    `keyableTextLength`, `declaredVarcharLength` and `computeTenantField` are
    `protected` and reach no exported surface".
  * 722880a -- "Replaced with the real reasons: `MAX_VARCHAR_CHARS` is
    `protected static` and reaches no exported surface, and #5726 leaves a CLI
    production module only `await import()`".

`protected` is a COMPILE-TIME visibility modifier. It removes a member from
neither the exported class nor the published types. Measured on this worktree's
built `packages/drivers/driver-sql/dist`:

  index.d.ts:5593  protected static readonly MAX_VARCHAR_CHARS = 16383;
  index.d.ts:5536  protected static readonly MAX_KEYABLE_VARCHAR_CHARS = 768;
  index.d.ts:5625  protected declaredVarcharLength(field: any): number | null;
  index.d.ts:5626  protected keyableTextLength(field: any): number | null;
  index.d.ts:3501  protected computeTenantField(schema: ...);

  require('.../driver-sql/dist/index.js').SqlDriver.MAX_VARCHAR_CHARS  -> 16383
  hasOwnProperty.call(SqlDriver, 'MAX_VARCHAR_CHARS')                  -> true

All five are on the exported `SqlDriver`. The pin test already depends on this:
it reaches the driver's own `protected` judgments by subclassing, which it could
not do if they were absent from the published types.

THE REAL CONSTRAINT, AND IT IS A CHOICE

#5726 forbids a CLI production module any static value import of an
`@objectstack/driver-*` package -- `schema-migrate.lazy-driver-import.test.ts`
scans every non-test `.ts` under `packages/cli/src` -- and what it leaves open
is `await import()` at the point of use. These generators are SYNCHRONOUS, so
they cannot take it. That is the whole reason, and it is a property of how this
package is written rather than of the constants: make the generators async and
the transcription can go.

This is the THIRD round on the same claim. Round 3's review flagged it, round 4
retracted it in the PR body and left it standing at three sites in the code,
which is what produced this round. The PR body is not what the next author
reads; the comment beside the constant is.

WHAT MOVES -- comments and docblocks only. No behaviour, no test, no pin, no
count, no changeset:

  * `generate.ts`, `MAX_VARCHAR_CHARS`'s docblock: the "protected static, so
    not on the driver package's exported surface at all" bullet is gone. The
    reason is now #5726 plus the synchronous generators, and the retracted
    claim is kept as a banned one beside the "does not depend on the driver at
    runtime" ban that preceded it, so nobody restates it a fourth time.
  * `generate.ts`, `isOrganizationScopedUnique`'s docblock: it drew a contrast
    -- "Unlike {@link MAX_VARCHAR_CHARS}, this one IS on `driver-sql`'s
    exported surface" -- that the measurement above dissolves. Both reach the
    exported surface, and both are spelled here for the one reason. Its tail
    also named the LEAF differential as what makes the spelling safe; the
    authority since 722880a is `SqlDriver.initObjects` read back with
    `PRAGMA table_info`, with the leaf differential kept beneath it and
    explicitly not the authority.
  * `generate.ts`, `indexKeyColumns`: the same stale attribution -- "the
    differential ... which now recomputes this whole set from the driver's own
    exported builders" -- now names the real chain and marks the leaf as not
    the authority.
  * `generate-string-family-width.pin.test.ts`: the restatement 722880a
    put there is retracted in place, beside the earlier false reason that
    comment already bans.

`MAX_KEYABLE_VARCHAR_CHARS`'s docblock inherits by reference -- "Transcribed and
pinned for exactly the reasons {@link MAX_VARCHAR_CHARS} gives" -- so it is
corrected by the block it cites and needed no edit.

Verified: `pnpm --filter @objectstack/cli typecheck` exit 0; the four pin files
`Test Files 4 passed (4)` / `Tests 81 passed (81)`.

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

Author: claude

packages/cli/src/commands/generate-string-family-width.pin.test.ts

@@ -730,13 +730,18 @@ describe('#16091 — the character column both generators emit is the driver\'s'
     // ⛔ NOT "because `packages/cli` does not depend on the driver at runtime"
     // — it does, and this file imports it 500 lines up. That sentence was this
     // pin's own first answer, it is false, and `generate.ts` now carries it
-    // with a ⛔ so nobody restates it. The ceiling is transcribed because
-    // `MAX_VARCHAR_CHARS` is `protected static` on `SqlDriver` and reaches no
-    // exported surface, and because #5726 leaves a CLI production module only
-    // `await import()` for a driver package — which these SYNCHRONOUS
-    // generators cannot use. This is the assertion that makes the transcription
-    // safe: the two must be the same number, and a driver that moves fails here
-    // rather than leaving the generators quietly wrong.
+    // with a ⛔ so nobody restates it. ⛔ NOR "because `MAX_VARCHAR_CHARS` is
+    // `protected static` on `SqlDriver` and reaches no exported surface" —
+    // the second false answer, and this file refutes it by construction:
+    // `protected` is compile-time visibility only, the member is on the
+    // exported `SqlDriver` and in the package's `dist/index.d.ts`, and the
+    // subclass below reaches the driver's `protected` judgments precisely
+    // because they are still there. The ceiling is transcribed for ONE reason:
+    // #5726 leaves a CLI production module only `await import()` for a driver
+    // package, and these generators are SYNCHRONOUS, so they cannot use it — a
+    // choice this package makes, not a law. This is the assertion that makes
+    // the transcription safe: the two must be the same number, and a driver
+    // that moves fails here rather than leaving the generators quietly wrong.
     const m = GENERATE_SOURCE.match(/^const MAX_VARCHAR_CHARS = (\d+);$/m);
     expect(m, 'generate.ts no longer declares MAX_VARCHAR_CHARS at top level').not.toBeNull();
     expect(Number(m![1])).toBe(MAX_CHARS);

packages/cli/src/commands/generate.ts

@@ -1201,22 +1201,34 @@ const STRING_FAMILY_TYPES: ReadonlySet<string> = new Set(['email', 'url', 'phone
  * (MySQL 8.0.46 refuses `varchar(16384)` with `ERROR 1074`; it is the LOWEST of
  * the three dialects' ceilings and is applied to all of them deliberately).
  *
- * Transcribed rather than imported, for two independent reasons — the second
- * one holds even if the first is ever lifted:
+ * Transcribed rather than imported for ONE reason, and that reason is a CHOICE
+ * this package makes rather than anything about the constant:
  *
- *   - it is `protected static` on `SqlDriver`, so it is not on the driver
- *     package's exported surface at all;
  *   - #5726 forbids a CLI production module any static value import of an
  *     `@objectstack/driver-*` package, and `schema-migrate.lazy-driver-import.test.ts`
- *     enforces it. oclif `import()`s every command module on every invocation,
- *     so one such edge here charges an unbuilt driver to whatever command the
- *     operator actually ran.
+ *     enforces it over every non-test `.ts` under `packages/cli/src`. oclif
+ *     `import()`s every command module on every invocation, so one such edge
+ *     here charges an unbuilt driver to whatever command the operator actually
+ *     ran. What #5726 leaves open is `await import()` at the point of use —
+ *     and these generators are SYNCHRONOUS, so they cannot take it. Make them
+ *     async and the transcription can go.
  *
  * ⛔ NOT "because `packages/cli` does not depend on the driver at runtime" —
  * it does: `@objectstack/driver-sql` is in this package's `dependencies` at
  * `workspace:^`. A missing dependency was never the reason, and stating it as
  * one invites the next reader to "simplify" the transcription away.
  *
+ * ⛔ NOR "because it is `protected static`, so it reaches no exported surface"
+ * — this block gave that as its FIRST reason and it is false. `protected` is
+ * compile-time visibility only; it removes the member from neither the exported
+ * class nor the published types. `SqlDriver` is exported from
+ * `@objectstack/driver-sql`, `SqlDriver.MAX_VARCHAR_CHARS` is an own static
+ * property that reads `16383` at runtime, and the built `dist/index.d.ts`
+ * declares it as `protected static readonly MAX_VARCHAR_CHARS`. The pin test
+ * reaches this and the driver's other `protected` judgments by subclassing,
+ * which is the same point. The constant IS reachable; what is unavailable
+ * here is a SYNCHRONOUS import of it.
+ *
  * Pinned rather than trusted: `generate-string-family-width.pin.test.ts` reads
  * the constant out of `sql-driver.ts` and fails here if the two part.
  */
@@ -1343,16 +1355,21 @@ function isUniqueScopeDeclared(unique: unknown): boolean {
  * ruling (2026-08-13), not an oversight, so the two readings stay apart here
  * too.
  *
- * ⚠️ Unlike {@link MAX_VARCHAR_CHARS}, this one IS on `driver-sql`'s exported
- * surface, so "not exported" is not the reason it is spelled here — say the
- * real one instead of borrowing that block's: these generators are SYNCHRONOUS,
+ * ⚠️ "Not exported" is not the reason this is spelled here — and it is not the
+ * reason {@link MAX_VARCHAR_CHARS} is either: both reach `driver-sql`'s
+ * exported surface, that block says why, and neither is spelled here for it.
+ * The reason is one and the same for both: these generators are SYNCHRONOUS,
  * and #5726 leaves a CLI production module only `await import()` for a driver
  * package, which a synchronous function cannot use. Spec's own
  * `isOrganizationUnique` is not a substitute either: it detects the WORD and
  * not the scope, so it omits the bare `true` this predicate exists to include.
- * What makes the spelling safe is the oracle in
- * `generate-string-family-width.pin.test.ts`, which recomputes this whole key
- * set from the driver's own exported builders and fails when the two disagree.
+ * What makes the spelling safe is the AUTHORITY in
+ * `generate-string-family-width.pin.test.ts` — `SqlDriver.initObjects` on an
+ * in-memory database, read back with `PRAGMA table_info` — which fails when
+ * the column the platform creates and the one these generators emit disagree.
+ * The leaf differential over the driver's exported builders is kept beneath it
+ * and is explicitly NOT the authority: recomposing the leaves' answers here is
+ * exactly what once left every layer between them and the real chain unread.
  */
 function isOrganizationScopedUnique(unique: unknown): boolean {
   return unique === true || unique === 'organization';
@@ -1443,8 +1460,11 @@ function indexKeyColumns(obj: Record<string, any>): ReadonlySet<string> {
     // nullSafeColumns: ['zzz'] }` the driver keys `{f}` and this keyed
     // `{organization_id, f}` — a column bounded here that the platform leaves
     // unbounded, this card's defect pointed the other way. Found by the
-    // differential in `generate-string-family-width.pin.test.ts`, which now
-    // recomputes this whole set from the driver's own exported builders.
+    // differential in `generate-string-family-width.pin.test.ts`, whose
+    // authority is now the real chain — `SqlDriver.initObjects` on an
+    // in-memory database, read back with `PRAGMA table_info`. The leaf
+    // differential that recomputes this set from the driver's own exported
+    // builders is kept beneath that chain and is NOT the authority.
     const preNormalized = Array.isArray(idx?.nullSafeColumns) && idx.nullSafeColumns.length > 0;
     if (!preNormalized && idx?.unique === 'organization' && tenantField && !listed.includes(tenantField)) {
       out.add(tenantField);