FR-033: strict per-subtype metamodel + 5-concern provider split + metamodel docs + 5-port fan-out

docs/superpowers/plans/2026-06-14-fr-033-cross-port-fan-out.md

@@ -0,0 +1,92 @@
+# FR-033 Phase 4 — cross-port fan-out (Java → C# → Python; Kotlin via JVM)
+
+_Status: PLANNED 2026-06-14. Follows the TS strict re-architecture (S0–S3, branch
+`fr-033-strict-constraint-model`). Makes the 4 non-TS ports' `registry-conformance`
+go RED→green against the strict, description-carrying, constraint-graph
+`fixtures/registry-conformance/expected-registry.json`._
+
+## The oracle rule (cross-language-porting skill)
+`fixtures/registry-conformance/expected-registry.json` is the (correct, TS-produced)
+golden. Port each language to MATCH it. NEVER edit the golden to match a port. If a
+fixture looks wrong, escalate — don't silently regenerate. Update the
+expected-failures ledger honestly for what isn't done.
+
+## Gap analysis (measured 2026-06-14)
+The golden grew (TS S0–S3) to carry, per `type.subType`: `description`, optional
+`rules`/`example`/`whenToUse`, the `children` constraint graph (childRules with
+cardinality, the `(attr,*,*)` wildcard REMOVED), `parents?`, and **strict
+per-subtype attr scoping** (e.g. `@maxLength` only on `field.string`,
+`@storage` only on `field.object`, `@autoSet` only on temporal fields,
+`@discriminator` only on `object.entity`). Per attr: `description` (+ optional
+rules/example/whenToUse) alongside `name`/`valueType`/`isArray`/`required`.
+
+Each non-TS port currently emits only the **v1 manifest** (`types[{type, subType,
+attrs[{name, valueType, isArray, required}]}]` + `commonAttrs` + `defaultSubTypes`)
+and explicitly EXCLUDES description / children / rules. So all four are RED at the
+first type. (Confirmed for Java: `RegistryManifestConformanceTest` fails at
+`type: "base"`.)
+
+**Two load-bearing facts that shrink the work:**
+1. **The manifest is provider-agnostic.** It emits the COMPOSED per-type view with
+   NO `provider` field (provenance is derived at TS doc-gen time, not in the
+   manifest). So the **5-concern provider split is an internal Tier-3 detail** — a
+   port does NOT need the same provider structure, only the same composed
+   per-`type.subType` `{description, attrs, children, parents, rules}`.
+2. **Descriptions must be byte-identical to TS.** Hand-maintaining identical prose
+   across ports is the exact duplication FR-033 kills. So the correct port reads the
+   **shared `spec/metamodel/*.json`** (embedded) for descriptions + the strict
+   constraint graph — single-sourced, byte-identical by construction. (Java's
+   `TypeDefinition` already has a `description` slot; its `ChildRequirement` likely
+   needs a per-attr `description` added. Verify per port.)
+
+## Per-port recipe
+For each of Java, C#, Python (Kotlin inherits via the shared JVM `metadata` module):
+1. **Embed the shared definitions.** Bundle the repo-root `spec/metamodel/*.json`
+   (the 15 provider definition files) as build-time resources / embedded constants
+   (the port's existing asset-embed pattern). A byte-identity gate per port.
+2. **Read them at registration.** A port-local `defineProviderFromData` equivalent:
+   parse the embedded JSON, register each `type.subType` with its strict
+   constraints + `description` (+ rules/example/whenToUse) + the `children` graph
+   (named attrs → the port's attr-requirement; structural entries → child rules;
+   `extendsBase` → additive inheritance; universal `*.*` → common attrs;
+   `extends` directives → the port's "extend an existing type" path). Keep the
+   port's factories / native bindings / validation passes as code (Tier 2/3).
+   - **Strict scoping reconciliation:** the registered per-subtype attr set must
+     equal TS's (move attrs off subtypes where TS scoped them away). Java already
+     has a per-subtype `ChildRequirement` model (pre-6.0 typesConfig) — reconcile it
+     to the JSON, don't reinvent.
+   - **Drop the any-attr wildcard** from the registered childRules (strict).
+3. **Grow the manifest emitter** to output, in the TS key order: per type
+   `description`, optional `rules`/`example`/`whenToUse`, `attrs` (each now with
+   `description` + optional doc fields), `children` (the constraint graph: childType,
+   childSubType [value|list|`*`], childName, `min?`/`max?` emitted only when defined,
+   `named?`), `parents?` (sorted). Match `server/typescript/packages/metadata/src/
+   registry-manifest.ts` exactly (key order, sorting, `null` for polymorphic
+   valueType, single trailing newline).
+4. **Run `registry-conformance`** → byte-match the golden. Iterate the diff.
+   Per-port: Java `mvn -q -pl metadata test -Dtest=RegistryManifestConformanceTest -o`;
+   C# `dotnet test MetaObjects.Conformance.Tests/...`; Python `uv run pytest tests/conformance/`.
+   Kotlin's `codegen-kotlin` RegistryManifestConformanceTest uses the shared JVM
+   `metadata` registry — it goes green when Java does (re-verify it after Java).
+5. **Enforce placement in validate().** Port the `ERR_CHILD_NOT_ALLOWED`
+   structural-child check (Java already has `ValidationPhase` + `acceptsChild`;
+   wire the strict check). Misplaced attr → `ERR_UNKNOWN_ATTR` (the ports likely
+   already enforce per-type attrs). Fix any port-local fixture that placed an attr
+   on a now-disallowed subtype (fix the fixture, not the model — and confirm it's a
+   genuine misplacement first).
+6. **Expected-failures ledger:** while a port is mid-port (RED), record it honestly.
+   The conformance byte-match is all-or-nothing, so intermediate commits stay RED
+   until that port completes — expected.
+
+## Sequencing
+**Java first** (the pre-6.0 strict typesConfig is the closest existing model; Kotlin
+rides its `metadata` module → mostly free, re-verify `codegen-kotlin`), **then C#,
+then Python** (mirrors the FR-032 fan-out). Each port is its own multi-step effort
+(embed + reader + emitter + scoping reconcile + enforce) — comparable to a slice of
+the TS arc. Budget a focused session per port; the byte-match diff is the guide.
+
+## Scale note
+This is the largest remaining FR-033 phase — effectively porting the strict model +
+description/constraint-graph emission into 3 engines (Java/C#/Python; Kotlin free).
+Do it port-by-port with the subagent-driven review discipline; keep the TS reference
+(`registry-manifest.ts`, `provider-data.ts`, `constraint-merge.ts`) as the spec.

docs/superpowers/plans/2026-06-14-fr-033-strict-constraint-model.md

@@ -0,0 +1,112 @@
+# FR-033 (revised) — Strict per-subtype constraint model + concern-provider split
+
+_Status: DESIGNED (brainstormed + approved 2026-06-14). Revises the FR-033 plan
+(`2026-06-13-fr-033-provider-definitions-as-data.md`) and spec
+(`docs/superpowers/specs/2026-06-13-metamodel-self-description-design.md`)._
+
+## Why this revision
+
+The first Phase-2 pass (commits `a72f8bb2`..`e08218db`) made each provider's
+metamodel definition *data*, but in a **loose** shape:
+
+- every field attr was lumped into the **core** provider (`@maxLength`/`@objectRef`/
+  `@filterable`/`@example`/… all on *every* field subtype);
+- the wildcard **"any attr"** child rule (`{type:"attr", subType:"*", name:"*"}`)
+  was registered on every type — a catch-all that accepts a misplaced/typo'd attr;
+- structural child rules were **post-assigned in provider code**, not in the data;
+- `documentation` got a **bespoke** `commonAttrs` field + `defineCommonAttrsFromData`.
+
+This is the looseness of the post-6.0 Java model. We are moving to the **pre-6.0
+strict** model: each type/subtype declares **exactly** which children it allows
+(by type + subtype + name + cardinality), it is **fail-closed**, and the *checking*
+runs in `validate()`. Goal triad: **strict** (kills drift) + **documentable** (the
+rules ARE the docs) + **extensible** (concerns ride their own providers; additive
+merge only — a provider/app can ADD rules, never loosen).
+
+The committed data files + descriptions are **reusable**; the structure is reworked.
+
+## Decisions
+
+1. **Strict per-subtype rules.** Each `type.subType` declares its allowed children
+   explicitly. The **"any attr" wildcard is removed**. Genuinely-open *structural*
+   sets stay wildcard (an `object.entity` holds arbitrary `field.*`; a field takes
+   any `validator.*`/`view.*`/`origin.*`). Cardinality is pinned where there's
+   structure (`identity.primary` max 1; an object's primary `source` exactly 1).
+2. **Attrs are named `attr` children.** A child rule with a concrete name = a
+   specific allowed attr (→ `AttrSchema`); there is no wildcard-attr rule anymore.
+3. **Common attrs = attr-children of a universal `*.*` entry** in the data, routed
+   to the existing common-attr registration by the **one** apply path. Deletes the
+   bespoke `commonAttrs` field + `defineCommonAttrsFromData`.
+4. **All child rules live in the JSON, none in provider code.** Shared rules declared
+   on `*.base` and inherited via the existing `constraint-merge.ts`; subtype
+   specializations on that subtype. The manifest emits **effective (merged)**
+   constraints so inheritance is DRY and the canonical does not churn for inherited
+   rules.
+5. **Enforce in `validate()` now.** A child (attr or structural) not admitted by the
+   merged rules → load-time error (new code, e.g. `ERR_CHILD_NOT_ALLOWED`). Data stays
+   declarative; the strict checking is code — the pre-6.0 Java split. Complex
+   cross-node rules (M:N junction, `@symmetric` self-join, origin path) stay in the
+   existing loader validation passes.
+6. **Concern-provider split (5).** Only **documentation** is universal (`*.*`); every
+   other concern attaches to the specific nodes it is about (DB/XML/etc. are NOT
+   universal).
+
+## The 5 concern providers + attr ownership
+
+| Provider | Concern | Owns | Scope |
+|---|---|---|---|
+| `metaobjects-core-types` *(exists)* | metamodel spine + intrinsic logical shape | type/subtype vocabulary; fields `@default`/`@readOnly`/`@required`, `@maxLength`→string, `@precision`/`@scale`→decimal, `@currency`→currency, `@objectRef`→object, `@values`/`@provided`→enum; objects `@discriminator`/`@discriminatorValue`; identity/relationship/origin structure; `source.rdb` subtype | per node type/subtype |
+| `metaobjects-db` *(exists, gains)* | physical storage + DB constraints | fields `@column`/`@db.indexed`/`@dbColumnType` (today) **+ `@storage`→object, `@autoSet`→temporal, `@unique`**; sources `@table`/`@kind`/`@role`/`@schema` | fields + sources (NOT universal) |
+| `metaobjects-documentation` *(exists)* | documentation | `@description`/`@title`/`@notes`/`@deprecated`/`@replacedBy`/`@seeAlso`/`@aliases`/`@summary` | **universal `*.*`** |
+| `metaobjects-prompt` *(expand `templateProvider`)* | AI + serialization (FR-004/006/010/011) | `template.prompt`/`output`/`toolcall` **type attrs** (`@payloadRef`/`@textRef`/`@format`/`@kind`/…) **moved out of core**; field teaching/extract attrs `@example`/`@instruction`/`@enumAlias`/`@enumDoc`/`@coerceDefault`/`@normalize`/`@xmlText` | fields + `template.*` (NOT universal) |
+| `metaobjects-ui` *(new)* | presentation + query surface | fields `@filterable`/`@sortable`/`@sortableDefaultOrder`; `view.*` + `layout.dataGrid` **type attrs** (`@locale`/`@pageSize`/`@columns`/…) **moved out of core** | fields + view/layout (NOT universal) |
+
+Open per-attr calls confirmed: `@autoSet` → date/time/timestamp (all temporal);
+`@maxLength` → `field.string` only. `@normalize` lives on `field.enum` (prompt
+provider) AND remains the `object.value` default (prompt provider extends
+`object.value`).
+
+## Mechanics (foundation changes)
+
+- **`provider-data.ts`**: one apply path. Route a `type:"attr"` child to an
+  `AttrSchema` (named) and DROP the wildcard-attr concept; recognize the universal
+  `type:"*", subType:"*"` TypeDef and register its attr children via
+  `registerCommonAttrs`. Remove `commonAttrs` field + `defineCommonAttrsFromData`.
+- **manifest emitter** (`registry-manifest.ts`): emit **effective** (merged via
+  `mergeConstraints`) children/attrs per `type.subType` so base-inherited rules show
+  on subtypes — keeping the canonical byte-stable while the JSON is DRY. Common
+  attrs stay in the `commonAttrs` block (NOT folded into every type's children).
+- **`validate()` enforcement**: a placement check against the merged effective
+  rules; misplaced/unknown child → new error code. Wire into the loader validation
+  phase. Expect to surface + fix existing corpus violations (fail-closed is stricter).
+
+## Implementation sequence (provider-by-provider, reviewed)
+
+- **Phase S0 — foundation.** provider-data routing + universal `*.*` + effective-
+  constraint manifest + the `validate()` placement check (enforcement). Prove on a
+  trivial provider; keep the canonical byte-stable for unchanged placements.
+- **Phase S1 — re-scope core providers strictly.** `field` first (densest; bring the
+  per-subtype placement table back for review), then object/attr/validator/identity/
+  relationship/source/origin — move shared rules to `*.base`, scope subtype attrs,
+  pin cardinalities, drop "any attr". Each its own commit + review; regen canonical.
+- **Phase S2 — re-home attrs to the 5 providers.** Expand `templateProvider` →
+  `metaobjects-prompt` (template type attrs + field teaching/extract attrs +
+  `@xmlText`); create `metaobjects-ui` (view/layout type attrs + filter/sort field
+  attrs); move `@storage`/`@autoSet`/`@unique` to `metaobjects-db`. Update
+  `coreProviders`. registry-conformance ownership reconciled.
+- **Phase S3 — documentation as universal `*.*`.** Replace the bespoke path; canonical
+  `commonAttrs` block unchanged.
+- **Phase S4 — corpus + enforcement green.** Fix any fixture that placed an attr on a
+  now-disallowed subtype; full TS suite + registry-conformance green.
+- **Phase S5 — docs-gen + cross-port (Phase 4).** Tiered metamodel docs from the
+  strict graph; fan out the read-the-file + strict model to Java/C#/Python/Kotlin
+  (Java already has the pre-6.0 model to mirror).
+
+## Invariants throughout
+
+- TS reference goes green at each step; the other four ports stay RED on
+  registry-conformance until Phase S5 (documented intermediate state).
+- The data files own declarative facts + rule prose; factories, the apply mechanism,
+  validation passes, and codegen stay code (ADR-0023 strict provenance preserved;
+  no DSL).
+- Commit to local `main`; per-provider implementer + two-stage review.