fix(docs): neutralize Storage section — physical column mapping, drop TypeScript-type column + Drizzle DDL

The entity-page Storage section rendered a 'TypeScript type' column and
Drizzle ORM DDL cells (integer("id"), text(..., { enum: [...] as const })) —
TS-codegen output, not neutral metadata (ADR-0020 violation).

Replace with declared physical facts only:
  | Column | Type | Nullable | Key |
- Column   = @column override else field name (the field→column mapping)
- Type     = @dbColumnType override (uppercased) else the same neutral logical
             type the Constraints table uses — no ANSI/ORM SQL re-derivation
- Nullable = yes unless required or PK
- Key      = primary key / foreign key → <Target> (reuses pkFieldNames/fkMap)

Distinct from (not duplicative of) the Constraints table: Storage's value is
the physical mapping + type override + key role; Constraints carries the
validation rules. Removed dead tsTypeForStorage/sqlColumnExpr/constraintsCell
and the SCALAR_TS_BY_SUBTYPE map. Root Mustache template unchanged (header/rows
stay pre-rendered), so the byte-identity gate is unaffected. Strengthened
docs-neutrality with Storage-section asserts + a folded-in entity+template
combined neutrality guard. Regenerated the golden; spec note updated.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: dmealing

docs/superpowers/specs/2026-06-02-neutral-metadata-docs-design.md

@@ -50,7 +50,7 @@ language?) to the current entity page:
 
 | Section | Neutral? | Decision |
 |---|---|---|
-| Storage (table, columns, SQL types, DDL) | **Yes** — the persistence mapping is declared in metadata and is identical across ports | Keep |
+| Storage (column name, **TypeScript type**, **Drizzle ORM DDL**) | **No** — the "TypeScript type" column and the `integer("id")` / `text(..., { enum: [...] as const })` cells are TS-codegen output, not metadata facts | **Neutralized** → keep the section (physical persistence mapping IS neutral) but render declared facts only: **Column / Type / Nullable / Key** (`@column` name, `@dbColumnType` override else logical type, nullability, PK/FK role). No TS type, no DDL, no ANSI re-derivation. |
 | Identity (primary/secondary/reference keys) | **Yes** | Keep |
 | Relationships (cardinality, composition) | **Yes** | Keep |
 | Validation (`OrderInsertSchema` / `OrderUpdateSchema` — **Zod**) | **No** — names a TS artifact | **Neutralize** → document the constraint metadata (required, maxLength, ranges, enum membership, validators) |
@@ -96,7 +96,16 @@ language-agnostic location and add a conformance gate.
   **Rendering: a table** (matches the Storage section style; scannable for
   many-field entities) with columns: field | required | type |
   limits (maxLength/min/max/pattern) | enum/validators.
-- Keep Storage / Identity / Relationships / Used by unchanged (already neutral).
+- **Neutralize Storage**: keep the section (the physical persistence MAPPING is
+  neutral, useful metadata) but drop the language-specific **TypeScript type**
+  column and the **Drizzle ORM DDL** cell. Render declared physical facts only —
+  columns: **Column** (`@column` override else field name) | **Type**
+  (`@dbColumnType` override uppercased, else the same neutral logical type the
+  Constraints table uses — no ANSI/ORM SQL re-derivation) | **Nullable** | **Key**
+  (PK / `foreign key → <Target>`). This is distinct from (not duplicative of) the
+  Constraints table, whose value is validation rules; Storage's value is the
+  physical field→column mapping + physical-type override + key role.
+- Keep Identity / Relationships / Used by unchanged (already neutral).
 - Make **Used by** bullets link to the new template page (`./<Template>.md`).
 - The TS golden (`test/golden/docs-file-conformance.test.ts`) updates to the
   neutralized output — this is an intentional improvement, not a regression.

fixtures/conformance/docs-file-basic/expected/Author.md

@@ -10,12 +10,12 @@
 
 ## Storage
 
-| Field | TypeScript type | SQL column | Constraints |
+| Column | Type | Nullable | Key |
 |---|---|---|---|
-| `id` | `number` | `integer("id")` | primary key, generation: `increment` |
-| `name` | `string` | `text("name")` | required, maxLength: 200 |
-| `status` | `"active" \| "suspended" \| "archived"` | `text("status", { enum: ["active","suspended","archived"] as const })` | required, CHECK `status IN ('active', 'suspended', 'archived')` |
-| `tags` | `string[] \| null` | `text("tags", { mode: "json" })` | optional, JSON column |
+| `id` | `long` | no | primary key |
+| `name` | `string` | no |  |
+| `status` | `enum` | no |  |
+| `tags` | `string[]` | yes |  |
 
 ## Identity
 

server/typescript/packages/codegen-ts/src/generators/docs-data-builder.ts

@@ -23,21 +23,6 @@ import {
   RELATIONSHIP_SUBTYPE_ASSOCIATION,
   FIELD_SUBTYPE_ENUM,
   FIELD_SUBTYPE_OBJECT,
-  FIELD_SUBTYPE_STRING,
-  FIELD_SUBTYPE_CLASS,
-  FIELD_SUBTYPE_UUID,
-  FIELD_SUBTYPE_INT,
-  FIELD_SUBTYPE_SHORT,
-  FIELD_SUBTYPE_BYTE,
-  FIELD_SUBTYPE_LONG,
-  FIELD_SUBTYPE_DOUBLE,
-  FIELD_SUBTYPE_FLOAT,
-  FIELD_SUBTYPE_DECIMAL,
-  FIELD_SUBTYPE_CURRENCY,
-  FIELD_SUBTYPE_BOOLEAN,
-  FIELD_SUBTYPE_DATE,
-  FIELD_SUBTYPE_TIME,
-  FIELD_SUBTYPE_TIMESTAMP,
   FIELD_ATTR_REQUIRED,
   FIELD_ATTR_UNIQUE,
   FIELD_ATTR_OBJECT_REF,
@@ -51,11 +36,11 @@ import {
   VALIDATOR_ATTR_MIN,
   VALIDATOR_ATTR_MAX,
   DOC_ATTR_DESCRIPTION,
+  FIELD_ATTR_DB_COLUMN_TYPE,
   stripPackage,
 } from "@metaobjectsdev/metadata";
-import { mapColumnType, type Dialect } from "../column-mapper.js";
+import type { Dialect } from "../column-mapper.js";
 import type { ColumnNamingStrategy } from "../metaobjects-config.js";
-import { toPascalCase } from "../naming.js";
 import { enumValues } from "../enum-meta.js";
 import { hasWritableRdbSource } from "../source-detect.js";
 import { GENERATED_HEADER } from "../constants.js";
@@ -74,93 +59,15 @@ export interface BuildDocDataOpts {
   loadedRoot: MetaRoot;
 }
 
-const SCALAR_TS_BY_SUBTYPE: Record<string, string> = {
-  [FIELD_SUBTYPE_STRING]: "string",
-  [FIELD_SUBTYPE_CLASS]: "string",
-  [FIELD_SUBTYPE_UUID]: "string",
-  [FIELD_SUBTYPE_INT]: "number",
-  [FIELD_SUBTYPE_SHORT]: "number",
-  [FIELD_SUBTYPE_BYTE]: "number",
-  [FIELD_SUBTYPE_LONG]: "number",
-  [FIELD_SUBTYPE_DOUBLE]: "number",
-  [FIELD_SUBTYPE_FLOAT]: "number",
-  // field.decimal is precision-exact: surfaced as a TS `string` (Drizzle pg
-  // `numeric` infers `string`). Keep the docs scalar mapping in lockstep.
-  [FIELD_SUBTYPE_DECIMAL]: "string",
-  [FIELD_SUBTYPE_CURRENCY]: "number",
-  [FIELD_SUBTYPE_BOOLEAN]: "boolean",
-  [FIELD_SUBTYPE_DATE]: "string",
-  [FIELD_SUBTYPE_TIME]: "string",
-  [FIELD_SUBTYPE_TIMESTAMP]: "string",
-};
-
-function enumTypeAliasName(entity: MetaObject, field: MetaField): string {
-  const superField = field.resolveSuper();
-  return superField !== undefined
-    ? toPascalCase(superField.name)
-    : `${entity.name}${toPascalCase(field.name)}`;
-}
-
 function isFieldRequired(field: MetaField): boolean {
   if (field.ownAttr(FIELD_ATTR_REQUIRED) === true) return true;
   return field.validators().some((v) => v.subType === VALIDATOR_SUBTYPE_REQUIRED);
 }
 
-function tsTypeForStorage(
-  entity: MetaObject,
-  field: MetaField,
-  pkFieldNames: ReadonlySet<string>,
-): string {
-  let base: string;
-
-  if (field.subType === FIELD_SUBTYPE_ENUM) {
-    const values = enumValues(field);
-    if (values !== undefined && values.length > 0) {
-      if (field.isArray) {
-        base = `${enumTypeAliasName(entity, field)}[]`;
-      } else {
-        base = values.map((v) => JSON.stringify(v)).join(" | ");
-      }
-    } else {
-      base = field.isArray ? "string[]" : "string";
-    }
-  } else if (field.subType === FIELD_SUBTYPE_OBJECT) {
-    const ref = field.ownAttr(FIELD_ATTR_OBJECT_REF);
-    const refName = typeof ref === "string" && ref.length > 0 ? ref : "unknown";
-    base = field.isArray ? `${refName}[]` : refName;
-  } else {
-    const scalar = SCALAR_TS_BY_SUBTYPE[field.subType] ?? "unknown";
-    base = field.isArray ? `${scalar}[]` : scalar;
-  }
-
-  const required = pkFieldNames.has(field.name) || isFieldRequired(field);
-  return required ? base : `${base} | null`;
-}
-
-function sqlColumnExpr(spec: ReturnType<typeof mapColumnType>): string {
-  const dbName = JSON.stringify(spec.dbName);
-  if (spec.fnOptions !== undefined && Object.keys(spec.fnOptions).length > 0) {
-    const parts: string[] = [];
-    for (const [k, v] of Object.entries(spec.fnOptions)) {
-      const lit = JSON.stringify(v);
-      if (Array.isArray(v)) {
-        parts.push(`${k}: ${lit} as const`);
-      } else {
-        parts.push(`${k}: ${lit}`);
-      }
-    }
-    return `${spec.fnName}(${dbName}, { ${parts.join(", ")} })`;
-  }
-  return `${spec.fnName}(${dbName})`;
-}
-
-/** The raw validator/limit facts shared by both constraint walks. Walks the
- *  field's validators ONCE, bucketed by subtype, plus the `@maxLength` attr.
- *  Both `constraintsCell()` (Storage cell) and `buildConstraintRow()`
- *  (Constraints row) consume these — the SINGLE source of truth for the
- *  validator emission, so the two presentations can't DRIFT. Each caller
- *  arranges the parts into its own layout (one cell vs. limits/rules columns)
- *  but the emission ORDER and exact strings come from here:
+/** The raw validator/limit facts for the Constraints table. Walks the field's
+ *  validators ONCE, bucketed by subtype, plus the `@maxLength` attr.
+ *  `buildConstraintRow()` consumes these — the SINGLE source of truth for the
+ *  validator emission. The emission ORDER and exact strings come from here:
  *    regex pattern → maxLength-from-@maxLength → length-validator (min/max) →
  *    numeric-validator (min/max). */
 interface ValidatorParts {
@@ -205,73 +112,13 @@ function collectValidatorParts(field: MetaField): ValidatorParts {
   };
 }
 
-function constraintsCell(
-  entity: MetaObject,
-  field: MetaField,
-  pkFieldNames: Set<string>,
-  fkMap: Map<string, { targetEntity: string; targetField: string }>,
-): string {
-  const parts: string[] = [];
-
-  if (pkFieldNames.has(field.name)) {
-    parts.push("primary key");
-    const primary = entity.primaryIdentity();
-    const gen = primary?.ownAttr(IDENTITY_ATTR_GENERATION);
-    if (typeof gen === "string") {
-      parts.push(`generation: \`${gen}\``);
-    }
-  } else if (isFieldRequired(field)) {
-    parts.push("required");
-  } else {
-    parts.push("optional");
-  }
-
-  if (field.ownAttr(FIELD_ATTR_UNIQUE) === true) {
-    parts.push("unique");
-  }
-
-  if (field.isArray) {
-    parts.push("JSON column");
-  }
-
-  if (field.subType === FIELD_SUBTYPE_ENUM && !field.isArray) {
-    const values = enumValues(field);
-    if (values !== undefined && values.length > 0) {
-      const list = values.map((v) => `'${v.replace(/'/g, "''")}'`).join(", ");
-      parts.push(`CHECK \`${field.column ?? field.name} IN (${list})\``);
-    }
-  }
-
-  const { maxLenAttr, regexParts, lengthParts, numericParts } = collectValidatorParts(field);
-  parts.push(...regexParts);
-  if (maxLenAttr !== undefined) {
-    parts.push(`maxLength: ${maxLenAttr}`);
-  }
-  parts.push(...lengthParts, ...numericParts);
-
-  const fk = fkMap.get(field.name);
-  if (fk !== undefined) {
-    parts.push(`references \`${fk.targetEntity}.${fk.targetField}\``);
-  }
-
-  const def = field.ownAttr(FIELD_ATTR_DEFAULT);
-  if (def !== undefined) {
-    parts.push(`default: \`${String(def)}\``);
-  }
-
-  const sup = field.resolveSuper();
-  if (sup !== undefined) {
-    parts.push(`extends \`${sup.name}\``);
-  }
-
-  return parts.join(", ");
-}
-
-/** Neutral logical type cell for the Constraints table. Unlike the Storage
- *  table's TypeScript type, this is language-agnostic: the field's logical
+/** The NEUTRAL logical type string (no backticks): the field's logical
  *  subtype (e.g. `string`, `enum`, `decimal`), suffixed `[]` for arrays, and
- *  the referenced object name for `field.object`. Wrapped in backticks. */
-function neutralTypeCell(field: MetaField): string {
+ *  the referenced object name for `field.object`. Language-agnostic — built
+ *  from declared metadata, never re-derived into ANSI/ORM SQL. Shared by the
+ *  Constraints table (`neutralTypeCell`) and the Storage table's physical-type
+ *  fallback (`storageTypeCell`). */
+function neutralTypeStr(field: MetaField): string {
   let base: string;
   if (field.subType === FIELD_SUBTYPE_OBJECT) {
     const ref = field.ownAttr(FIELD_ATTR_OBJECT_REF);
@@ -280,7 +127,27 @@ function neutralTypeCell(field: MetaField): string {
     base = field.subType;
   }
   if (field.isArray) base = `${base}[]`;
-  return `\`${base}\``;
+  return base;
+}
+
+/** Neutral logical type cell for the Constraints table — `neutralTypeStr`
+ *  wrapped in backticks. */
+function neutralTypeCell(field: MetaField): string {
+  return `\`${neutralTypeStr(field)}\``;
+}
+
+/** Neutral PHYSICAL type cell for the Storage table. Metadata-driven, no DDL
+ *  re-derivation (ADR-0020): if the field declares a `@dbColumnType` physical
+ *  override (e.g. `uuid`, `jsonb`, `timestamp_with_tz`) show it UPPERCASED;
+ *  otherwise fall back to the same neutral LOGICAL type the Constraints table
+ *  uses. Deliberately does NOT derive ANSI/ORM SQL so it can't drift vs the
+ *  migrate engine or re-introduce language-specific DDL. Wrapped in backticks. */
+function storageTypeCell(field: MetaField): string {
+  const dbColumnType = field.ownAttr(FIELD_ATTR_DB_COLUMN_TYPE);
+  if (typeof dbColumnType === "string" && dbColumnType.length > 0) {
+    return `\`${dbColumnType.toUpperCase()}\``;
+  }
+  return `\`${neutralTypeStr(field)}\``;
 }
 
 /** Build one neutral Constraints-table row for a field. Reuses the same
@@ -420,28 +287,46 @@ export function buildEntityDocData(
   entity: MetaObject,
   opts: BuildDocDataOpts,
 ): EntityDocData {
-  const strategy = opts.columnNamingStrategy ?? "snake_case";
   const root = opts.loadedRoot;
   const primary = entity.primaryIdentity();
   const pkFields = primary?.fields ?? [];
   const pkFieldNames = new Set<string>(pkFields);
   const fkMap = buildFkMap(entity, root);
 
-  // ---- Storage rows
+  // ---- Storage rows — NEUTRAL physical persistence MAPPING (ADR-0020): the
+  // physical column name, a neutral physical type (declared `@dbColumnType`
+  // override else the logical type), nullability, and the key role. NO
+  // TypeScript type, NO ORM DDL, NO ANSI re-derivation — declared metadata
+  // facts only. The value-add over the Constraints table is the field→column
+  // mapping + physical-type override + key role.
   const storageRows: StorageFieldDoc[] = entity.fields().map((field) => {
-    const spec = mapColumnType(field, opts.dialect, strategy);
-    const tsType = tsTypeForStorage(entity, field, pkFieldNames);
-    const tsTypeCell = tsType.split("|").map((s) => s.trim()).join(" \\| ");
-    const sqlExpr = sqlColumnExpr(spec);
-    const cons = constraintsCell(entity, field, pkFieldNames, fkMap);
-    const tsTypeCellStr = `\`${tsTypeCell}\``;
-    const sqlExprCellStr = `\`${sqlExpr}\``;
+    const isPk = pkFieldNames.has(field.name);
+    // Physical column name: the field's `@column` override if set, else the
+    // field name. (The Storage section shows the RAW declared mapping; column
+    // naming-strategy folding stays a codegen concern, not a docs fact.)
+    const columnName = field.column ?? field.name;
+    const columnCell = `\`${columnName}\``;
+    const typeCell = storageTypeCell(field);
+    // Nullable iff not required and not the PK (matches the Constraints table's
+    // required-ness rule).
+    const nullable = !(isPk || isFieldRequired(field));
+    const nullableCell = nullable ? "yes" : "no";
+
+    let keyCell = "";
+    if (isPk) {
+      keyCell = "primary key";
+    } else {
+      const fk = fkMap.get(field.name);
+      if (fk !== undefined) keyCell = `foreign key → \`${fk.targetEntity}\``;
+    }
+
     return {
       name: field.name,
-      tsTypeCell: tsTypeCellStr,
-      sqlExprCell: sqlExprCellStr,
-      constraintsCell: cons,
-      rowLine: `| \`${field.name}\` | ${tsTypeCellStr} | ${sqlExprCellStr} | ${cons} |`,
+      columnCell,
+      typeCell,
+      nullableCell,
+      keyCell,
+      rowLine: `| ${columnCell} | ${typeCell} | ${nullableCell} | ${keyCell} |`,
     };
   });
 
@@ -523,7 +408,7 @@ export function buildEntityDocData(
 
   if (hasStorage) {
     data.storage = {
-      tableHeader: "| Field | TypeScript type | SQL column | Constraints |\n|---|---|---|---|",
+      tableHeader: "| Column | Type | Nullable | Key |\n|---|---|---|---|",
       rows: storageRows,
     };
     data.hasStorage = true;