merge: Documentation Provider — universal common-attrs substrate across 4 ports

Lands the Documentation Provider: 7 universal doc common attrs (description /
title / notes / deprecated / replacedBy / seeAlso / aliases) registered via a
new `commonAttrs` registry hook on every metatype, across TS / C# / Java /
Python, plus doc-gen consumption:

- TS: JSDoc above entity types, Drizzle columns, Zod schemas; Postgres
  COMMENT ON TABLE/COLUMN in migrate-ts; Mermaid ER diagram (docs/model.md)
  via mermaidErDiagram() generator.
- C#: XML doc + [Obsolete] on entity classes / properties / DbSet properties;
  Postgres COMMENT ON in PostgresSchema DDL.
- Java: substrate-only — constants + SPI-registered provider class with
  deferred wiring (TODO(java-h3b)) pending an open-policy validation pass.
- Python: full substrate — register_common_attrs hook + validation merge +
  ERR_PROVIDER_ATTR_CONFLICT + doc module + conformance adapter integration.

D5 contract: @notes is internal-only and NEVER emitted to user-facing
doc-gen surfaces. Enforced by negative-emission tests in every output-
emitting port.

4 new cross-language conformance fixtures (doc-common-attrs-{basic,
multiline,on-all-types,stringarray-shapes}) pin the contract; TS and
Python pass all 4 green, C# passes 3 + lists on-all-types pending its
source-v2 port.

CLAUDE.md updated with the cross-language vocabularies entry. Spec
status flipped to Implemented.

Per-unit + aggregate code-reviewer + code-simplifier gates passed.

Spec: docs/superpowers/specs/2026-05-24-documentation-provider-design.md
Plan: docs/superpowers/plans/2026-05-24-documentation-provider.md

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

Author: dmealing

CLAUDE.md

@@ -17,11 +17,11 @@ Equal weight. Three ship per-language today; the fourth is committed for 7.0.0:
 
 ## Status
 
-TypeScript reference implementation is **published to npm at `0.5.0`** (11 `@metaobjectsdev/*` packages on the `latest` tag; `cli` at `0.5.1`) — Projects D–G shipped end-to-end with 2124+ tests passing. Java port is in progress: H3a (loader restructure) shipped 2026-05-19; H3b (conformance harness) is active. **C# is a first-class full-stack target.** Loader + conformance shipped (loader, canonical serializer, and a `dotnet test` conformance runner over the full shared corpus; metadata layer fully caught up — empty expected-failures ledger, incl. `template.*` + `origin.collection`). The FR-004 tier ships: the **render engine (`MetaObjects.Render`)** renders the shared `fixtures/render-conformance` corpus byte-identical to TS, plus payload-VO codegen and `verify`. **The EF Core + ASP.NET codegen tier ships** (`MetaObjects.Codegen` + the `meta` CLI: `verify`/`gen`/`migrate`): entities, `AppDbContext` (DbSets, projection `.ToView`, `@storage` owned types via `OwnsOne`), CRUD minimal-API routes, and Postgres DDL (`CREATE TABLE` with PK/NOT NULL/UNIQUE/FK + `@storage` columns; `CREATE VIEW` for projections incl. aggregate/passthrough-`@via`/collection origins). Remaining tiers — introspection-driven incremental migration (`migrate` is full-CREATE today) and the runtime-metadata pillar — are being built out (no part of MetaObjects is out of scope for C#). Python is planned post-H3.
+TypeScript reference implementation is **published to npm at `0.5.0`** (11 `@metaobjectsdev/*` packages on the `latest` tag; `cli` at `0.5.1`) — Projects D–G shipped end-to-end with 2124+ tests passing. Java port is in progress: H3a (loader restructure) shipped 2026-05-19; H3b (conformance harness) is active. **C# is a first-class full-stack target.** Loader + conformance shipped (loader, canonical serializer, and a `dotnet test` conformance runner over the full shared corpus; metadata layer largely caught up — known-gap list now tracks the `source.rdb` source-v2 paradigm cluster + `doc-common-attrs-on-all-types`, all blocked on the source-v2 port). The FR-004 tier ships: the **render engine (`MetaObjects.Render`)** renders the shared `fixtures/render-conformance` corpus byte-identical to TS, plus payload-VO codegen and `verify`. **The EF Core + ASP.NET codegen tier ships** (`MetaObjects.Codegen` + the `meta` CLI: `verify`/`gen`/`migrate`): entities, `AppDbContext` (DbSets, projection `.ToView`, `@storage` owned types via `OwnsOne`), CRUD minimal-API routes, and Postgres DDL (`CREATE TABLE` with PK/NOT NULL/UNIQUE/FK + `@storage` columns; `CREATE VIEW` for projections incl. aggregate/passthrough-`@via`/collection origins). Remaining tiers — introspection-driven incremental migration (`migrate` is full-CREATE today) and the runtime-metadata pillar — are being built out (no part of MetaObjects is out of scope for C#). Python is planned post-H3.
 
 The 7.0.0 line is specced: FR-003 brings the Java OMDB persistence engine, metadata-driven schema migration, and dynamic projections onto current core; FR-004 builds the fourth pillar (cross-language prompt construction) on top of FR-003's projections. Both are design-stage plan-of-record (`docs/superpowers/specs/2026-05-22-fr-003-*` and `*-fr-004-*`), not yet implemented.
 
-Cross-language conformance fixtures live at `fixtures/conformance/` (45 fixtures + a `CAPABILITIES.json` manifest). See `spec/roadmap.md` for current + planned work.
+Cross-language conformance fixtures live at `fixtures/conformance/` (85 fixtures + a `CAPABILITIES.json` manifest). See `spec/roadmap.md` for current + planned work.
 
 ## Public repository hygiene
 
@@ -396,6 +396,7 @@ Preserve the following contracts exactly across all language ports:
 - Schema attrs: `@schema` on `source[dbTable]` and `source[dbView]` (DB schema name; Postgres default `public`, SQLite rejects non-default values)
 - Storage attrs: `@storage` on `field.object` (with `@objectRef`) — values `flattened` / `jsonb` / `subdocument`. Unifies "owned types" (flattened storage) and "structured JSONB" (jsonb storage). Defaults to single-jsonb-column when absent (back-compat).
 - Enum: `field.enum` is a first-class field subtype (peer of `currency`), string-backed. Required `@values` string-array attr (member symbols). Members must be a non-empty set, each matching `^[A-Za-z_][A-Za-z0-9_]*$`, no duplicates — every port's loader enforces this (own-only) emitting `ERR_BAD_ATTR_VALUE` (missing `@values` → `ERR_MISSING_REQUIRED_ATTR`). Reuse via abstract `field.enum` + `extends`. Codegen: TS union + `z.enum`, C# `enum` + EF `HasConversion<string>()`, DB `varchar` + `CHECK`. Int-backed values, display labels, and native PG enum are deferred (see `docs/superpowers/specs/2026-05-23-enum-datatype-design.md`).
+- Documentation common attrs (any node): `description`, `title`, `notes`, `deprecated`, `replacedBy`, `seeAlso`, `aliases`. Registered via the cross-language `commonAttrs` registry hook (`registerCommonAttrs` / `RegisterCommonAttrs` / `register_common_attrs`; Java provider currently substrate-only, wiring deferred to H3b). `notes` is the internal-only rationale slot — never emitted to user-facing doc-gen (JSDoc / XML-doc / Postgres `COMMENT ON` / Mermaid prose). TS doc-gen ships all three tiers; C# ships XML-doc + COMMENT ON. See `docs/superpowers/specs/2026-05-24-documentation-provider-design.md`.
 
 **Wire format:**
 - Currency: integer minor units on the wire always. Float arithmetic for money is forbidden.

docs/superpowers/specs/2026-05-24-documentation-provider-design.md

@@ -1,7 +1,7 @@
 # Design: Documentation provider — universal doc common attrs + cross-language doc-gen
 
 **Date:** 2026-05-24
-**Status:** Approved (design)
+**Status:** Implemented across TS, C#, Java (substrate; wiring deferred to H3b), Python (2026-05-24)
 **Author:** Doug Mealing (with Claude)
 
 ## Problem

fixtures/conformance/doc-common-attrs-basic/expected.json

@@ -0,0 +1,54 @@
+{
+  "metadata.root": {
+    "package": "acme",
+    "children": [
+      {
+        "object.entity": {
+          "name": "User",
+          "@aliases": [
+            "Account",
+            "Member"
+          ],
+          "@description": "A registered account holder.",
+          "@title": "User",
+          "children": [
+            {
+              "field.long": {
+                "name": "id"
+              }
+            },
+            {
+              "field.string": {
+                "name": "email",
+                "@aliases": [
+                  "emailAddress",
+                  "userEmail"
+                ],
+                "@deprecated": "Use contactEmail instead.",
+                "@description": "User's primary email address.",
+                "@replacedBy": "User.contactEmail",
+                "@seeAlso": [
+                  "https://acme.com/docs/email"
+                ],
+                "@title": "Email"
+              }
+            },
+            {
+              "field.string": {
+                "name": "contactEmail",
+                "@description": "Replacement contact email."
+              }
+            },
+            {
+              "identity.primary": {
+                "@fields": [
+                  "id"
+                ]
+              }
+            }
+          ]
+        }
+      }
+    ]
+  }
+}

fixtures/conformance/doc-common-attrs-basic/input/meta.acme.json

@@ -0,0 +1,44 @@
+{
+  "metadata.root": {
+    "package": "acme",
+    "children": [
+      {
+        "object.entity": {
+          "name": "User",
+          "@description": "A registered account holder.",
+          "@title": "User",
+          "@aliases": ["Account", "Member"],
+          "children": [
+            {
+              "field.long": {
+                "name": "id"
+              }
+            },
+            {
+              "field.string": {
+                "name": "email",
+                "@description": "User's primary email address.",
+                "@title": "Email",
+                "@deprecated": "Use contactEmail instead.",
+                "@replacedBy": "User.contactEmail",
+                "@seeAlso": ["https://acme.com/docs/email"],
+                "@aliases": ["emailAddress", "userEmail"]
+              }
+            },
+            {
+              "field.string": {
+                "name": "contactEmail",
+                "@description": "Replacement contact email."
+              }
+            },
+            {
+              "identity.primary": {
+                "@fields": "id"
+              }
+            }
+          ]
+        }
+      }
+    ]
+  }
+}

fixtures/conformance/doc-common-attrs-basic/providers.json

@@ -0,0 +1 @@
+["metaobjects-core-types", "metaobjects-documentation"]

fixtures/conformance/doc-common-attrs-multiline/expected.json

@@ -0,0 +1,28 @@
+{
+  "metadata.root": {
+    "package": "acme",
+    "children": [
+      {
+        "object.entity": {
+          "name": "Order",
+          "@description": "An order placed by a User.\n\nLifecycle: DRAFT → PUBLISHED → ARCHIVED.\nMultiple lines preserved via canonical serialization.",
+          "@notes": "Internal rationale:\n- We chose status as an enum because external integrations require canonical states.\n- Don't surface this in API docs.",
+          "children": [
+            {
+              "field.long": {
+                "name": "id"
+              }
+            },
+            {
+              "identity.primary": {
+                "@fields": [
+                  "id"
+                ]
+              }
+            }
+          ]
+        }
+      }
+    ]
+  }
+}

fixtures/conformance/doc-common-attrs-multiline/input/meta.acme.json

@@ -0,0 +1,26 @@
+{
+  "metadata.root": {
+    "package": "acme",
+    "children": [
+      {
+        "object.entity": {
+          "name": "Order",
+          "@description": "An order placed by a User.\n\nLifecycle: DRAFT → PUBLISHED → ARCHIVED.\nMultiple lines preserved via canonical serialization.",
+          "@notes": "Internal rationale:\n- We chose status as an enum because external integrations require canonical states.\n- Don't surface this in API docs.",
+          "children": [
+            {
+              "field.long": {
+                "name": "id"
+              }
+            },
+            {
+              "identity.primary": {
+                "@fields": "id"
+              }
+            }
+          ]
+        }
+      }
+    ]
+  }
+}

fixtures/conformance/doc-common-attrs-multiline/providers.json

@@ -0,0 +1 @@
+["metaobjects-core-types", "metaobjects-documentation"]

fixtures/conformance/doc-common-attrs-on-all-types/expected.json

@@ -0,0 +1,48 @@
+{
+  "metadata.root": {
+    "package": "acme",
+    "children": [
+      {
+        "object.entity": {
+          "name": "Subscriber",
+          "@description": "Entity-level doc.",
+          "children": [
+            {
+              "source.rdb": {
+                "@description": "Source-level doc.",
+                "@kind": "table",
+                "@table": "subscribers"
+              }
+            },
+            {
+              "field.long": {
+                "name": "id"
+              }
+            },
+            {
+              "field.string": {
+                "name": "email",
+                "@description": "Field-level doc.",
+                "children": [
+                  {
+                    "validator.required": {
+                      "@description": "Validator-level doc."
+                    }
+                  }
+                ]
+              }
+            },
+            {
+              "identity.primary": {
+                "@description": "Identity-level doc.",
+                "@fields": [
+                  "id"
+                ]
+              }
+            }
+          ]
+        }
+      }
+    ]
+  }
+}

fixtures/conformance/doc-common-attrs-on-all-types/input/meta.acme.json

@@ -0,0 +1,46 @@
+{
+  "metadata.root": {
+    "package": "acme",
+    "children": [
+      {
+        "object.entity": {
+          "name": "Subscriber",
+          "@description": "Entity-level doc.",
+          "children": [
+            {
+              "source.rdb": {
+                "@kind": "table",
+                "@table": "subscribers",
+                "@description": "Source-level doc."
+              }
+            },
+            {
+              "field.long": {
+                "name": "id"
+              }
+            },
+            {
+              "field.string": {
+                "name": "email",
+                "@description": "Field-level doc.",
+                "children": [
+                  {
+                    "validator.required": {
+                      "@description": "Validator-level doc."
+                    }
+                  }
+                ]
+              }
+            },
+            {
+              "identity.primary": {
+                "@fields": "id",
+                "@description": "Identity-level doc."
+              }
+            }
+          ]
+        }
+      }
+    ]
+  }
+}