feat: enforce eject contract across generators and gate final releases on it (#435)

* test(eject): hold every generator in every port to the eject contract

Every stock generator is meant to be ejectable, with the owned copy holding
its emit. Three pieces of work each made a named list ejectable and no test
stated the rule, so the newest generators shipped as thin copies with every
lane green. This adds the test, in all five ports, driven by one shared file.

The shared file is fixtures/generator-registry-conformance/registry.json.
Each generator now carries "eject": "full" or an exemption with its reason
and ruling. A top-level "eject" block holds, per port, the packaged modules
an owned copy may still import (the engine surface), the exempt
non-generator emitters, and a "pending" list of every place the contract
does not hold yet.

Each port's eject-contract test makes three assertions:

- Census: every generator implementation the port ships is in its registry.
- Completeness: every registered generator ships eject source unless exempt,
  and the other lists of ejectable generators are derived from the registry
  or held equal to it.
- Depth: each generator, ejected alone, compiles or loads, references
  nothing in the codegen packages outside the engine surface, and emits
  what the packaged generator emits.

A pending entry that passes fails the test, and so does a gap that is not
listed. PENDING_LIST_MAY_BE_NON_EMPTY in the shared file skips each port's
"the pending list is empty" test until the release branch sets it false:
1.1.0 does not ship with entries left.

The census registered seven generators that no registry listed: TypeScript
requirements and agent-docs, and Java plantuml, html-docs, ai-docs,
json-schema and the deprecated mustache. Registering PlantUML put it in two
registry-driven suites for the first time; both failed on a
StringIndexOutOfBoundsException for any single-segment package, which is
fixed here.

The tests that asserted a gap are gone, with the hand-typed lists they
pinned. ADR-0034 Amendment 8 records the six rulings, the engine surface,
the exemptions, the gap list and the release gate, and supersedes FR-040
section 4.2 and the eject-in-every-port design's thin-copy rule.

This closes none of the pending gaps. It also found one the audit did not
list: an owned Java entity constructs the packaged extractor generator when
no extractor is in the run (gap 13).

* feat(release): refuse a final release while the eject pending list has entries

The eject contract's release rule was a switch a person had to remember to
flip. It is now enforced by the release scripts, and the guard's scans are
tighter.

- scripts/eject-release-gate.mjs refuses a version with no prerelease suffix
  while fixtures/generator-registry-conformance/registry.json has an entry in
  eject.pending, or while PENDING_LIST_MAY_BE_NON_EMPTY is anything but false.
  scripts/release.mjs calls it first in its preflight and
  scripts/finish-release.mjs calls it as gate 0, before the tag. A release
  candidate is allowed. An unreadable manifest is refused.
- The "pending list is empty" test now reports as skipped in TypeScript and
  C# while the switch is on, as it already did in Java, Kotlin and Python. It
  used to return early and count as a pass.
- The TypeScript reference scan also counts type-only imports, inline
  import("...") types and dynamic import() of a package module. The Python
  scan also counts importlib.import_module and __import__ on a string literal.
  Each scan has a test over a file whose answer is known.
- The tighter TypeScript scan found the owned requirement-tests generator
  importing two types from the packaged generator and its template. The
  renderer's argument record and signature are now declared beside the
  requirement walk. The package's exports are unchanged. relation-resolver.ts
  and render-context.ts join the TypeScript engine surface: an owned copy
  imports their types.
- ADR-0034 Amendment 8 states the limits of the guard with the reason for
  each, lists the engine-surface names that were a judgment call, and records
  that gap 13 closes with the Java work on gaps 4, 5 and 7.

* test(eject): read the pending census names once per manifest pass

The Java registry-conformance test rebuilt the set of pending census names for
every manifest entry. It now builds it once. Also splits a comment in the
TypeScript generators barrel back into its two subjects.

* no-mistakes(review): remove eject release switch; execute release.mjs wiring test

* no-mistakes(review): gate publish workflows; dedupe shape checks; widen Python scope

* no-mistakes(review): accept PEP 440 prereleases; gate hand-typed publish routes

* test(eject): drop the nine C# pending entries the emitter hand-over closed

Rebased onto the change that hands the C# emitters over on eject and makes
api-docs ejectable there. All nine C# pending entries now pass the guard, so
they leave the list: the api-docs census entry and eight depth entries (gaps
4 and 5). 49 entries are left: typescript 22, java 10, python 9, kotlin 8.

- C# eject now writes the emitters beside the generator, so the contract test
  compiles and scans every file eject writes under codegen/generators. It
  used to require exactly one file.
- DocsRunFacts, GeneratorApplicability and IDocsGenerator join the C# engine
  surface: the owned api-docs copy reads the docs run's facts and asks the
  packaged generators whether they apply, and writes no output through them.
- ADR-0034 Amendment 8: gaps 4, 5 and 6 are closed in C#.

* no-mistakes(review): compare real paths in eject gate entry guard

Author: dmealing

.github/workflows/publish-csharp.yml

@@ -41,6 +41,16 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      # A final version is not published while the eject pending list has entries
+      # (ADR-0034 Amendment 8). A release candidate passes, which is why the `version`
+      # input is read first.
+      - name: Eject release gate
+        env:
+          VERSION_INPUT: ${{ github.event.inputs.version }}
+        run: |
+          COMMITTED="$(sed -n 's:.*<Version>\(.*\)</Version>.*:\1:p' server/csharp/Directory.Build.props | head -n 1)"
+          node scripts/eject-release-gate.mjs "${VERSION_INPUT:-$COMMITTED}"
+
       - name: Set up .NET
         uses: actions/setup-dotnet@v4
         with:

.github/workflows/publish-java.yml

@@ -33,6 +33,11 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      # A final version is not published while the eject pending list has entries
+      # (ADR-0034 Amendment 8). A release candidate passes.
+      - name: Eject release gate
+        run: node scripts/eject-release-gate.mjs "$(sed -n 's:.*<version>\(.*\)</version>.*:\1:p' server/java/pom.xml | head -n 1)"
+
       - name: Set up JDK 21 + Maven settings (Central server + GPG import)
         uses: actions/setup-java@v4
         with:

.github/workflows/publish-npm.yml

@@ -39,6 +39,11 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      # A final version is not published while the eject pending list has entries
+      # (ADR-0034 Amendment 8). A release candidate passes.
+      - name: Eject release gate
+        run: node scripts/eject-release-gate.mjs "$(node -p "require('./server/typescript/packages/cli/package.json').version")"
+
       - name: Set up Bun
         uses: oven-sh/setup-bun@v2
 

.github/workflows/publish-python.yml

@@ -28,6 +28,11 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      # A final version is not published while the eject pending list has entries
+      # (ADR-0034 Amendment 8). A release candidate passes.
+      - name: Eject release gate
+        run: node scripts/eject-release-gate.mjs "$(sed -n 's/^version *= *"\(.*\)".*/\1/p' server/python/pyproject.toml | head -n 1)"
+
       - name: Set up uv
         uses: astral-sh/setup-uv@v5
 

AGENTS.md

@@ -6,7 +6,7 @@ MetaObjects is a **cross-language metadata standard** for declaring typed entity
 
 The metamodel is the **durable spine**; generated code is the **disposable artifact**. Substrate is local-first: typed metadata lives in your repo, generated code is idiomatic per-language output with **no proprietary runtime**: the generated entity and model code imports nothing from MetaObjects at runtime, and the REST, prompt, client and runtime tiers import ordinary Apache-2.0 packages you can vendor, fork or replace. If `@metaobjectsdev/*` disappears tomorrow, you keep working code.
 
-**Core vs helpers (ADR-0034 Amendment 3, 2026-09-22).** Only the core is a product promise: the metamodel, loader, canonical format and registry; runtime metadata access (the `ObjectManager` and its drivers; the HTTP adapters that mount it on a web framework are helpers, 2026-09-24 ruling); schema migrations (`meta migrate`); the drift gates (`meta verify`); prompt render and the reply parser. Every generator that writes application code into an adopter's repo — routes, controllers, ORM wiring, DTOs, forms, grids, hooks, filter allowlists — is a **reference helper**: it must compile and pass its reference fixtures, and the adopter copies it with `meta eject` and owns the copy. Mechanical test: what the tool guarantees is core; what it writes into your repo is a helper. Every port can eject: `meta eject` (TypeScript), `metaobjects eject` (Python), `mvn metaobjects:eject` (Java/Kotlin), `dotnet meta eject` (C#). Not every generator ships a reference copy: `meta gen --list` marks the ones that do not `package-only` (in TypeScript: `template` alone; ADR-0034 Amendment 3 correction, 2026-09-26, narrowed by Amendments 5 and 7). When you find a generator defect, fix the reference; do not describe it as a broken core guarantee.
+**Core vs helpers (ADR-0034 Amendment 3, 2026-09-22).** Only the core is a product promise: the metamodel, loader, canonical format and registry; runtime metadata access (the `ObjectManager` and its drivers; the HTTP adapters that mount it on a web framework are helpers, 2026-09-24 ruling); schema migrations (`meta migrate`); the drift gates (`meta verify`); prompt render and the reply parser. Every generator that writes application code into an adopter's repo — routes, controllers, ORM wiring, DTOs, forms, grids, hooks, filter allowlists — is a **reference helper**: it must compile and pass its reference fixtures, and the adopter copies it with `meta eject` and owns the copy. Mechanical test: what the tool guarantees is core; what it writes into your repo is a helper. Every port can eject: `meta eject` (TypeScript), `metaobjects eject` (Python), `mvn metaobjects:eject` (Java/Kotlin), `dotnet meta eject` (C#). Not every generator ships a reference copy: `meta gen --list` marks the ones that do not `package-only` (in TypeScript: `template`, which is exempt for good, and `requirements` and `agent-docs`, which are pending; ADR-0034 Amendment 3 correction, 2026-09-26, narrowed by Amendments 5 and 7, and held to the shared manifest by Amendment 8). When you find a generator defect, fix the reference; do not describe it as a broken core guarantee.
 
 ## Six pillars
 

CHANGELOG.md

@@ -105,6 +105,29 @@ generator catalog and the Atlas evaluation are 1.2 work.
 
 ### Added
 
+- **The eject contract: every generator hands over its emit, and a test in every port holds
+  it to that** (ADR-0034 Amendment 8). `fixtures/generator-registry-conformance/registry.json`
+  now says, for each generator, `"eject": "full"` or an exemption with its reason, and lists
+  per port the packaged modules an owned copy may still import (the engine surface). Each
+  port's eject-contract test asserts three things from it: every generator the port ships is
+  in its registry; every registered generator ships eject source unless exempt; and each
+  generator, ejected alone, compiles or loads, references no emit code left in the package,
+  and emits what the packaged generator emits. `template` is exempt in every port that ships
+  it, with the deprecated Java Mustache generator and the docs-site builders. Where the
+  contract does not hold yet, the file's `eject.pending` list names the generator, the port
+  and the packaged modules its owned copy still calls. A port's test fails on an unlisted gap
+  and on a listed one that has closed. The release does not ship while the list has entries:
+  `scripts/release.mjs`, `scripts/finish-release.mjs` and the four publish workflows refuse a
+  version with no prerelease suffix until the list is empty (`scripts/eject-release-gate.mjs`); a
+  release candidate is allowed. No generator emits different bytes because of this change.
+- **Seven generators that no registry listed are registered**, so `--list`, the eject
+  commands and the registry-driven tests see them. TypeScript: `requirements` (the ledger
+  pages `meta docs` writes) and `agent-docs` (the pages `meta docs --agent` writes), both
+  neutral and both still run by `meta docs`; a `generators` entry naming either string is
+  refused the way `"docs"` is. Java: `plantuml`, `html-docs`, `ai-docs`, `json-schema` and the
+  deprecated `mustache`, each by the class name a pom already uses. None of the seven ships
+  eject source yet; `mustache` will not.
+
 - **The Java `entity` and `extractor` generators can be ejected.**
   `mvn metaobjects:eject -Dnames=entity,extractor -Dport=java` copies each generator, with
   the rest of its emit, into your `codegen/` module. They were the two Java generators that
@@ -872,6 +895,13 @@ until you regenerate.
 
 ### Fixed
 
+- **The Java PlantUML generator no longer throws on a single-segment package.**
+  `PlantUMLGenerator` failed with `StringIndexOutOfBoundsException` for any model whose
+  package has one segment (`acme`, not `acme::shop`), which is most small models. It was in
+  no registry, so no registry-driven test ran it; registering it (above) put it in two such
+  suites and both failed. A package with no parent now draws no parent namespace. Output
+  for a multi-segment package is unchanged.
+
 - **A doc generator skipped by `meta gen` is now reported in every output form.** `meta docs`
   is the door for documentation (ADR-0025), so `meta gen` warns about and skips a `docsFile()`
   or `apiDocsFile()` listed under `generators`. That has not changed. What changed is who hears

agent-context/skills/metaobjects-codegen/references/typescript.md

@@ -126,8 +126,10 @@ name. Import by default and eject to customize: an owned copy you never change o
 behind the reference. (`entityFile` / `queriesFile` / `routesFile` / `barrel` were removed
 from that subpath at 1.0 and restored in 1.1, so on a 1.0.x install an owned copy is the
 only path for those four.) The engine primitives come from the package main entry,
-`@metaobjectsdev/codegen-ts`. One entry cannot be ejected and is `package-only` in
-`meta gen --list`: the `template` primitive, which has no emit logic of its own.
+`@metaobjectsdev/codegen-ts`. Three entries cannot be ejected and are `package-only` in
+`meta gen --list`: the `template` primitive, which has no emit logic of its own, and
+`requirements` and `agent-docs`, the pages `meta docs` writes, which do not ship a
+reference template yet.
 
 Three ejectable entries behave differently from the rest:
 

docs/CONFORMANCE.md

@@ -87,8 +87,8 @@ the corpora above do two different jobs. Only the first is a promise to adopters
   exporter's output, a TypeScript reference helper),
   `requirement-test-identity-conformance/` (which tests the `requirement-tests` reference
   generator yields from a ledger and what each is called; the text it writes is not
-  pinned) and the codegen-compile gate. They check that the reference generators are correct
-  starting points; an adopter's ejected copy is theirs and is not gated. The hand-rolled
+  pinned), the codegen-compile gate and the eject contract (below). They check that the
+  reference generators are correct starting points; an adopter's ejected copy is theirs and is not gated. The hand-rolled
   reference-server lane of `api-contract-conformance/` still pins the wire contract that
   the runtimes and the client speak, which is core.
 
@@ -99,6 +99,23 @@ corpora, or between its *vocabulary* and its *behaviour* — never gets a row of
 own, and its boundary ends up discoverable only from the feature doc. The split ones
 are recorded here instead.
 
+**The eject contract** ([ADR-0034](../spec/decisions/ADR-0034-codegen-scaffold-and-own.md)
+Amendment 8). A gate, not a corpus: it has no fixtures of its own, and reads
+`generator-registry-conformance/registry.json`.
+
+- *Gated in all five ports.* Each port's eject-contract test asserts that every generator it
+  ships is in the registry (census), that every registered generator ships eject source
+  unless the shared file exempts it (completeness), and that each generator ejected alone
+  compiles or loads, references nothing in the codegen packages outside the engine surface
+  and emits what the packaged generator emits (depth). TypeScript:
+  `cli/test/eject-contract.test.ts`. C#: `EjectContractTests`. Java: `EjectContractTest` in
+  `maven-plugin`. Kotlin: `EjectContractTest` in `codegen-kotlin`. Python:
+  `tests/conformance/test_eject_contract.py`.
+- *Not yet true everywhere, and the shared file says where.* `eject.pending` lists every
+  generator that still fails an assertion. A port's test fails when an unlisted gap appears
+  and when a listed one closes without its entry being removed.
+- *Not gated: an adopter's owned copy.* The contract is about what the reference hands over.
+
 **Capability requirements** ([features/requirements.md](features/requirements.md)):
 
 - *Vocabulary — gated in all five ports.* The types, their attributes and their closed

docs/RELEASING.md

@@ -10,7 +10,8 @@
 > - **Maven Central** → push a `java-v<maven-version>` tag (`publish-java.yml` signs and deploys
 >   from repo secrets), or locally `~/.m2/settings.xml` (server ids `central` +
 >   `gpg-credentials`) + the local GPG signing key and `mvn -Prelease deploy` from
->   `server/java` (autoPublish — no manual staging promotion). One route per version, never both.
+>   `server/java` (autoPublish, so no manual staging promotion; run the eject release gate
+>   first, see the Java procedure). One route per version, never both.
 > - **NuGet** → keyless OIDC via the `publish-csharp.yml` workflow: `gh workflow run
 >   publish-csharp.yml` (or push a `csharp-v<version>` tag).
 >
@@ -48,6 +49,26 @@ Decide explicitly for every branch the scan returns: merge it into this cut, or
 Note that `no-mistakes/*` branches are usually gate replays of work already on `main` — confirm
 rather than assume. Do not skip past the list.
 
+**The eject pending list (1.1.0).** 1.1.0 does not ship while
+`fixtures/generator-registry-conformance/registry.json` has an entry in `eject.pending`
+(ADR-0034 Amendment 8). The scripted paths enforce it: `scripts/release.mjs` (first check of
+its preflight), `scripts/finish-release.mjs` (gate 0, before the tag) and the four publish
+workflows (the step after checkout) refuse a version with no prerelease suffix while the list
+holds an entry. A release candidate (`1.1.0-rc.3`, or `1.1.0rc3` on PyPI) is allowed.
+
+A publish you type by hand passes through none of those, so run the gate yourself as the
+command before it. This document has it before each of the four: the npm promote in step 3,
+the isolated one-package `bun publish`, the PyPI fallback `uv publish`, and the local
+`mvn -Prelease deploy`. It exits non-zero on a refusal:
+
+```
+node scripts/eject-release-gate.mjs <version>    # the version that registry is about to receive
+```
+
+To clear it for a final release: close the gaps and delete their entries. There is no other
+step. Each port's eject-contract test fails on a gap that is not listed, so an entry cannot be
+deleted before its gap is closed.
+
 **Why this is step 0 and not a nicety:** `0.21.1` shipped *without* a `timestampMode` fix that was
 already written and sitting on an unmerged branch. Because versions are immutable on all four
 registries, the only correction was a full coordinated `0.21.2` within the hour — four publishes, an
@@ -549,6 +570,7 @@ scripts/ci-local.sh --strict-toolchains        # must end "LOCAL CI PASSED"
 # bump the candidate set to the final <version>
 rm bun.lock && bun install
 # verify packed deps (rule 2); commit "chore(release): <version>"
+node scripts/eject-release-gate.mjs <version>    # must exit 0; refuses while eject.pending has entries
 ( cd <pkg-dir> && bun publish )                  # default tag = latest, tier order
 git push origin main                             # NO tag here — see golden rule 7
 ```
@@ -587,8 +609,8 @@ CDN-cached and lags right after publish.
 ## Isolated patch (one package)
 
 If only one package changed (e.g. a `cli` bugfix), bump just that package, `rm bun.lock && bun
-install`, verify, and `bun publish` it — the others stay at their current version. Tag scoped
-(e.g. `cli-v0.5.1`).
+install`, verify, run `node scripts/eject-release-gate.mjs <version>` (it must exit 0), and
+`bun publish` it. The others stay at their current version. Tag scoped (e.g. `cli-v0.5.1`).
 
 # Releasing the C# packages to NuGet
 
@@ -750,9 +772,10 @@ Project `metaobjects` → **Settings → Publishing → Add a new GitHub publish
    python-v<version>`. **Do not ALSO publish by hand.** The `1.0.3` cut ran a local
    `uv publish` and then pushed the tag, so the workflow went red with `400 File already
    exists` on a release that had shipped — a red run that reads exactly like a failed publish.
-   The local route is the fallback only when the workflow cannot run: `UV_PUBLISH_TOKEN=<a PyPI
-   API token> uv publish dist/*` from `server/python`, and then do not push a `python-v*` tag
-   for that version.
+   The local route is the fallback only when the workflow cannot run. Run
+   `node scripts/eject-release-gate.mjs <version>` from the repository root first (it must exit
+   0; the workflow runs the same gate), then `UV_PUBLISH_TOKEN=<a PyPI API token> uv publish
+   dist/*` from `server/python`, and then do not push a `python-v*` tag for that version.
 4. **Verify:** `curl -s https://pypi.org/pypi/metaobjects/json | python3 -c "import sys,json;print(json.load(sys.stdin)['info']['version'])"`.
 
 # Releasing the Java/Kotlin modules to Maven Central
@@ -789,7 +812,9 @@ versioned on its own major line — npm major + 7, so `7.x` while npm was `0.x`
    with `Component … already exists`): push a `java-v<maven-version>` tag, and
    `publish-java.yml` runs the deploy below in CI with the signing secrets (how `8.0.4`
    shipped; it takes no version override, so it deploys the COMMITTED version — do not fire
-   it for an uncommitted pre-release); or run `mvn -Prelease deploy` from `server/java`.
+   it for an uncommitted pre-release); or run
+   `node scripts/eject-release-gate.mjs <maven-version>` from the repository root (it must exit
+   0; the workflow runs the same gate) and then `mvn -Prelease deploy` from `server/java`.
    The `central-publishing-maven-plugin`
    (`<publishingServerId>central</publishingServerId>`, `<autoPublish>true</autoPublish>`) uploads
    the signed bundle and auto-releases — **no manual staging → release promotion**. Auth + the GPG

docs/features/own-your-codegen.md

@@ -159,10 +159,13 @@ you how far it is from the reference.
 
 ## The docs generators and `shared-model` (TypeScript)
 
-Every stock TypeScript generator can be ejected except one. `template` is the Mustache
+Every stock TypeScript generator can be ejected except three. `template` is the Mustache
 primitive: you already supply its template, its walk and its name, and it has no emit
-logic of its own, so a copy would own nothing. `meta gen --list` marks it `package-only`.
-The C#, Java and Python ports rule the same way for theirs (ADR-0034 Amendment 7).
+logic of its own, so a copy would own nothing. That exemption is permanent, and the C#,
+Java and Python ports rule the same way for theirs (ADR-0034 Amendment 7). `requirements`
+and `agent-docs`, the pages `meta docs` and `meta docs --agent` write, were registered by
+the eject census and do not ship a reference template yet (ADR-0034 Amendment 8).
+`meta gen --list` marks all three `package-only`.
 
 Three of the ejectable ones differ from the rest in what runs them or in what the copy may
 change.
@@ -274,7 +277,11 @@ directory that holds `metaobjects.config.ts`.
 ## What `meta eject` hands over, and what stays core (TypeScript)
 
 Owning a generator means owning the code it writes **and the code that code calls**,
-when that code is a helper. On TypeScript the generated routes call an HTTP adapter —
+when that code is a helper. That is the rule for every generator in every port
+(ADR-0034 Amendment 8). It is not yet true of all of them: several owned copies still call
+emit code in the package, and `fixtures/generator-registry-conformance/registry.json` lists
+each one under `eject.pending` until it is closed. What follows is the part that is
+already handed over. On TypeScript the generated routes call an HTTP adapter —
 the mount helpers, the filter/sort parser, the error envelopes, pagination — and that
 adapter is where most route defects have lived. So ejecting a generator whose output
 calls it copies the adapter's source too:
@@ -997,10 +1004,11 @@ against your copy, ignoring the package line and `^// metaobjects:owned-support`
 have no edits of your own (`-Dlist` says `identical`), re-eject with `-Dforce`.
 
 `-Dport` is needed only when a name exists in both ports and your project's dependencies
-do not say which. Every Kotlin generator is ejectable, and every Java generator except
-`template`. `template` is the Mustache primitive: the template you supply is its emit
-logic, so the generator has none of its own to hand over. That holds in every port that
-ships it.
+do not say which. Every Kotlin generator is ejectable. Every Java generator is too, except
+`template`, the deprecated `mustache`, and four that are registered and do not ship eject
+source yet (`plantuml`, `html-docs`, `ai-docs`, `json-schema`). `template` is the Mustache
+primitive: the template you supply is its emit logic, so the generator has none of its own
+to hand over. That holds in every port that ships it.
 
 ## C#: `dotnet meta eject`