feat(library): ship FR-043 Phase 1 — reusable declared design as opt-in libraries with opt-in codegen - #369
Merged
Merged
Conversation
## Catalog spec — §8a and §8b ruled, and one correction `framework` exclusivity is an ADVISORY on the `api` layer only. Verified first that it is a real silent hazard: `routes` emits `<Entity>.routes.ts` and `routes-hono` emits `<Entity>.routes.hono.ts`, so wiring both trips no duplicate-path error, compiles clean, and quietly serves two complete HTTP surfaces over the same entities. But it is not invalid — migrating Fastify→Hono, or serving Node and edge from one model, are real — so it warns rather than fails, like every other gate here. And the draft's general per-layer rule was WRONG. `@metaobjectsdev/tanstack` declares `react` as a peer, so `form` + `hooks` + `grid` is the documented normal composition, not a conflict; "at most one framework per `api` and per `client` layer" would have forbidden the most common client selection there is. Corrected in D4. Six layers, not ten. The draft had four single-member layers, which do no grouping work, and it conflated two different kinds of choice: app-shape decisions a builder makes, and model-driven ones the model already made. Nobody picks `prompt-render` from a taxonomy — they declared a `template.prompt`, and `--probe` reports that exactly. So `model`/`persistence`/`api`/`client`/`docs` are chosen by app shape and `capability` is chosen by the probe. Six gated cross-port values instead of ten, all 34 generator names covered. Compatibility declarations become resolved-not-trusted, the doctrine `@implementedBy` already runs on. `runtimePeers` is checked against the generators' emitted third-party imports; `requires` is now checked the same way, by resolving emitted RELATIVE imports back to whichever generator emits those paths — so a new framework generator cannot ship claiming it depends on nothing. That is what keeps the catalog accurate as frameworks are added, rather than discipline. Applicability comes from running the generators and cannot drift; compatibility is declared and therefore has to be gated. Conflating the two is how a catalog goes quietly wrong. ## FR-043 — feature and non-functional packages Shippable *declared design*: the requirements a capability must satisfy plus the model metadata it needs, pulled into a project by an agent and adapted. It moves an LLM from "invent a design for this" to "here is a considered one, and `meta verify` will hold you to it". It is not greenfield, which is the main thing the design records. `library/ai/llm-call.yaml` already ships one package — an eighteen-field `LlmCallBase` modelling one LLM call, plus a concrete `LlmCall` with its table and identity — opted into by name via the loader's `libraries` option with a default of none, embedded into TS, Java and Python under an `embedded-library drift` gate, with `trace-helper` codegen and OMDB runtime beside it. That instance also falsifies the clean split we started from: `ai` is a FEATURE package that nonetheless carries a generator and runtime. So the model is components — metadata, requirements, generator selection, runtime helpers — any subset of which may be present, and feature-vs-non-functional describes what a package is ABOUT, not whether it ships code. The catalog spec's §9 is corrected to match rather than left contradicting it. Five gaps make up the FR: only MetaObjects can author one; no requirements component; no discovery; no copy-and-own; and the package→generator coupling is hard-coded (`trace-helper` carries `const LLM_CALL_BASE = "LlmCallBase"` and matches on the name). Mechanism proposal is embed by default, eject to own — `library` composed with ADR-0034 — explicitly NOT FR-023, whose sync-and-pin semantics and deliberate ledger exclusion are the opposite of what a package pulled in to be implemented against wants. Deferred by ruling: market-facing and wanted, but in a later version or an adjacent project. FR-041 is the instrument that can say whether declared design actually accelerates an agent, and it needs a baseline first. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011cQxyVuTkdPmAduLiedNEg
…ng example Reverses this file's own deferral. The argument for waiting was that the mechanism was unproven; it is not. `library/ai/llm-call.yaml` ships today: opt-in by name through the loader's `libraries` option with a default of none, `library/` as the source of truth embedded into every port, an `embedded-library drift` gate keeping the copies byte-identical, and the TS resolver already deriving its package set from the embedded keys so a second library needs no port edit. What was missing was never transport. ## The pillar, argued rather than assumed A library is not a sixth verb — it is the reuse unit that COMPOSES the other five: the first pillar's inputs, the fifth's, the first's generator selection, the second's runtime helpers, as one named opt-in artifact. What makes it a pillar rather than a folder of YAML is requirements: without them a library is a schema snippet; with them it is design an adopter's build is held to. The test applied is the one the requirements pillar itself passes — does it change what an agent can be checked against? ## The fact that shapes the design Library sources are PREPENDED and never marked `imported` — the opposite of FR-023 — so an opted-in library's entities are in codegen, migrate AND ledger scope by default. That is correct and is what makes a library a library, but `checkRequirements` early-returns only when the tree has ZERO requirements, so a library shipping requirements would have switched the unclaimed-entity gate on for every one of an adopter's own entities. Day-one ambush, one rule to prevent: object coverage activates on adopter-authored requirements only. A library can count, claim and be gate-checked; it cannot volunteer you for coverage. ## Rulings recorded - `iam`, not `user` or `rbac` — it names both halves. - Permission is an ENTITY with two grant junctions, not one nullable-scope assignment table: a nullable column in a unique key means NULLs are distinct, so global grants could silently duplicate, and fixing that needs a partial-index escape carrying a physical column name. Two composite-keyed tables need no escape and survive three dialects and five ports unchanged. - Coverage-activation as above. - `iam` ships `stability: preview` with a promotion bar to `stable` (one external estate running it with the drift gate enforced, on the G3d precedent) — and the standing escape is that an adopter may eject the metadata into their own project and repackage it however they like, which is what makes a shape freeze survivable. ## Verified, not asserted The complete nine-entity model was extracted from this spec and loaded against the real registry under `strict: true`: clean. `identity.reference` with `references`/`onDelete`, `identity.primary` with `generation`, `autoSet`, `stringFormat: email`, `field.enum` values/default, `relationship.association` `through` and `index.lookup` are all registered vocabulary today. No type, subtype or attribute is added; `expected-registry.json` and `metamodelVersion` do not move. The sharpest single entry is `noCredentialsOnUser`, a NEGATIVE architectural requirement. An adopter's legacy model of this shape stored a plaintext password and a knowledge-based secret pair on the user row — what an agent extending "the user model" re-derives on sight. Stating the prohibition in the ledger, where `meta docs --agent` renders it, is a thing no schema snippet can do, and it is the clearest demonstration of why requirements are what make this a pillar. One question gates "shippable" and is recorded as such: whether `overlay: true` merges on a NESTED requirement node. If it does not, an adopter cannot disagree with a library requirement without ejecting the whole ledger. It wants a conformance fixture, not a spot check. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011cQxyVuTkdPmAduLiedNEg
… adapt The ladder had overlay as the primary adaptation door and eject as the escape hatch for structural changes. That is backwards, and it contradicted the project's own doctrine: ADR-0034 copies the codegen reference templates into the adopter's repo BECAUSE the adopter owns their code. Metadata is no different. Telling adopters to use library metadata in place and adapt it through a merge would have made libraries the one thing MetaObjects ships that you are expected to rent rather than own. So copy-and-own leads — rename the package, delete what you do not need, change a PK strategy, keep the requirements and edit them — and using a library in place is the deliberate minority choice of someone who wants to track upstream. Two consequences, both good. The shape freeze mostly evaporates: a later change to `iam` reaches only adopters who chose to track it, which is the real answer to the stability question and demotes `stability: preview` to the belt rather than the braces. And Phase 1's weight shifts — the provenance header, a clean package rename and the staleness report are what must be excellent, while `libraries: [...]` polish matters less than it looked. Also records a delete directive for overlays as a CANDIDATE, with the analysis rather than the wish. Overlay can add and can override an attribute; it cannot remove, and the eight reserved structural keys carry no removal semantic, so an adopter tracking a library upstream cannot drop a field or a requirement they do not want. `delete` and `remove` are both free names in every port. The constraint that decides it: overlay merge is deliberately order-independent — ADR-0055 made it a deferred pass, #188 established the same for super-resolution, and the result is a pure function of the source SET. A naive delete breaks that; making delete ABSORBING preserves it, at the stated price that a library reintroducing a member can never reach an adopter who deleted it. The ledger interaction is the part worth having: deleting `User.email` dangles `uniqueLogin`'s `implementedBy`, which is an error on a live requirement, so removing a capability forces you to amend the design that promised it. That is what the requirements pillar is for. Not Phase 1. A new reserved structural key changes the canonical interchange format in all five ports and moves `metamodelVersion`; and once copy-and-own is the expected mode, you delete by editing your copy. The directive serves only the track-upstream minority, so their turning out to be real is the evidence that would justify it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011cQxyVuTkdPmAduLiedNEg
… is inert The maintainer ruled that a library ships its core model, its DB persistence and its UI rendering as separate layers, the second and third applied as `overlay: true` files over the first — the layered overlay pattern the project already documents, and the shape used habitually on the predecessor JVM implementation. It is not a packaging preference. A core layer that declares no `source.rdb` is inert by a contract that already ships: migrate-ts skips an object with no writable source, and codegen-ts emits no route, queries, hooks, grid or form for one, both citing #248 — persistability derives from source presence, never from the object subtype. So opting into a library adds zero tables and zero generated code, and what the adopter gains is the design being present and resolvable. Verified against the real loader under `strict: true`: a sourceless core entity loads with zero writable sources, and an overlay carrying `source.rdb` + `index.lookup` merges to exactly one. Four consequences, all recorded in the amendment table: - §12 Q2 (`migrate.scope.exclude`) DISSOLVES. There is nothing to subtract, so `migrate.scope` stays include-only and its committed rationale stands. - The `ai` concrete-`LlmCall` wart CLOSES instead of persisting. It was carried on the grounds that splitting changes what existing adopters get; a sweep of ~70 estate configs found zero uses of `libraries`, so there are none. - §12 Q4 is ruled: `libraries` moves to `.metaobjects/config.json` outright, with no dual-read, for the same reason. - §12 Q3 is dropped — `iam` uses no composite FK, so that was a metamodel question wearing a library costume. Two things become worth gating, neither of which gates the library itself: "an overlay can add a source.rdb" is documented in CLAUDE.md and gated nowhere in any port, and the core layer's sourcelessness is a promise that would otherwise break silently. §11's `delete` overlay directive stays a candidate, unchanged — not Phase 1. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011cQxyVuTkdPmAduLiedNEg
Two conformance fixtures, ahead of both feature plans, because both specs rest on overlay behaviour neither verified. FR-043 section 12 Q1 — does `overlay: true` merge on a NESTED requirement node — is named by that spec as the question gating "Phase 1 shippable". If the answer is no, an adopter cannot disagree with a library requirement without ejecting the whole ledger, section 5.5 collapses to eject-only, and Phase 1 is a different shape than planned. Existing coverage stops at a field one level inside an object; requirements nest arbitrarily deep. Amendment 1's layering rests on an overlay being able to add a `source.rdb`. That is documented in the project context and gated nowhere in any port. It has been verified in TypeScript only, by a throwaway probe. The plan carries the corpus's non-obvious cost: the fixture count is a derived value with three committed copies plus the site payload, asserted only in the `gates` lane, so a fixture-adding commit that moves one of them reds a gate no port lane can see. Task 2 has a real chance of answering Q1 no. That is the plan working, and it is why it runs first. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011cQxyVuTkdPmAduLiedNEg
… rests on Both were documented and gated nowhere. Landed together rather than as two commits, because the corpus count is a derived value asserted against four committed copies and splitting them buys nothing. overlay-adds-source — a core model declares no source and a db layer overlays `source.rdb` + `index.lookup` onto it. This is the mechanism the layered-library design in FR-043 Amendment 1 rests on. It merges clean: one entity, one writable source, zero errors, zero warnings. overlay-nested-requirement — an adopter disagrees with a library requirement nested three deep, per FR-043 section 5.5. Existing nested-overlay coverage stopped at a field one level inside an object. Two findings worth the fixture, both recorded in what it asserts: Addressing a nested node means re-declaring its ancestor chain, and every ancestor must ALSO carry `overlay: true`. Left plain — the shape the existing nested fixture uses — each one emits WARN_DUPLICATE_DECLARATION, so a depth-4 tree costs three warnings to change one leaf. Marked, it is silent. Overriding an attribute that already has a value emits ERR_MERGE_CONFLICT even under an explicit `overlay: true`. The new value does win, so the adopter's intent is honoured, but the build carries an error — the loader treats an override as a defect to fix rather than as an adaptation. That is FR5c behaviour, shared by every overlay and not specific to requirements. Adding a NEW attribute is clean. The fixture pins the error rather than hiding it. Corpus 322 -> 324. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011cQxyVuTkdPmAduLiedNEg
… an override Both gating fixtures landed and are green in all five ports with no expected-failure ledger entries, so the layering is verified cross-port rather than in TypeScript alone. Q1 is answered YES structurally: an adopter's overlay of a library requirement nested three deep merges to the right tree with the adopter's values applied. Section 5.5 is not withdrawn and Phase 1 keeps its shape. Running it surfaced two things the spec had assumed away. Every ancestor in the chain must also carry `overlay: true`. Left plain, each emits WARN_DUPLICATE_DECLARATION, so a depth-4 tree costs three warnings to change one leaf. That is a documentation obligation, measured rather than inferred. And section 0's fact row was wrong: an attribute override emits ERR_MERGE_CONFLICT even under an explicit `overlay: true`. The adopter's value wins, but the build carries an error, because the loader treats an override as a defect to fix. The row is corrected in place. Ruled: `overlay: true` licenses the override. The conflict error exists to catch two files that collided without knowing about each other, and the flag is the author saying they know. The loader already treats it specially, so this makes it mean one thing rather than two. No vocabulary moves. The cost carries a coverage trap, recorded rather than discovered later: `overlay-attr-last-writer-wins` marks its overlay and expects the error, so flipping it alone would silently delete the only coverage of the accident case. A new fixture has to take over that branch. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011cQxyVuTkdPmAduLiedNEg
Q1 answered yes structurally; the plan's stop-and-re-scope branch did not fire. Two findings it surfaced are recorded in FR-043 Amendment 2. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011cQxyVuTkdPmAduLiedNEg
Twelve tasks over the settled spec. Order is forced by one fact: the compatibility declarations (`requires`, `runtimePeers`) must be DERIVED from what the generators actually emit, not guessed and gated afterwards — so Task 9 writes the gates first and reads the truth off their failure messages, and Tasks 2/3 deliberately leave those fields empty. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011cQxyVuTkdPmAduLiedNEg
… composed across packages `meta gen --list` and `meta eject --list` read two different tables and gave an agent two different answers to "what can I turn on". Four TypeScript generators (form, hooks, grid, grid-hook) were in neither, and requirement-tests in the registry but not the manifest. This makes it one table. - `layer` — model / persistence / api / client / docs / capability — joins the cross-port manifest beside `tier`, and the five missing names join it too, so 34 generators are described where 29 were. Six values, not the ten an earlier draft carried: four of those had ONE member each, and a layer with one member does no grouping work. `capability` is deliberately the big undifferentiated bucket — you are not meant to choose inside it by reading labels, you are meant to run `--probe` against your own model. - The entry type gains the facts a selection needs: `kind` (today always "generator"; FR-043 adds library rows to this same table), `framework`, `requires`, `runtimePackage`, `runtimePeers`, `configKeys` and `ejectable`. `requires`/`runtimePeers` are deliberately left EMPTY — they are declarations, and a declaration nobody resolves goes stale, so the gate that derives them from what the generators actually emit lands before the values do. `ejectable` and `configKeys` need no such gate: the first is derived from REFERENCE_GENERATOR_NAMES, the second is typed `keyof MetaobjectsGenConfig`. - codegen-ts cannot import its own dependents, so the react and tanstack packages export their own registry slices and the CLI unions them in `lib/catalog.ts`. Composition refuses a duplicate stable name outright rather than letting the last slice win — otherwise `--list` would describe one generator and `gen` run another. The conformance split follows from that: codegen-ts is one slice of three, so its own gate can only assert "no rogue names", and set equality — the half that catches a MISSING registration — moves to the CLI, the only package that sees all three. Both directions are still gated; they are just gated where the facts are. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011cQxyVuTkdPmAduLiedNEg
C#, Java, Kotlin and Python registries gain a `layer` beside `tier`, and each port's conformance test asserts two things: that its own entries agree with the manifest, and that EVERY manifest entry — including the other ports' — declares one of the six. The second half is not redundant. A port only reads its own slice, so a bad layer on a name that port does not expose would sit unnoticed in four of the five gates; making each port check the whole manifest's well-formedness means the first lane to run catches it. The allowed set is spelled out as a literal in every gate rather than enumerated off the port's own enum. Deriving it would make the gate agree with whatever the code says, which is the one thing a conformance gate must not do. Kotlin and Java expose `manifestValue()` on the enum rather than lower-casing at each call site, so the enum owns its own wire spelling. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011cQxyVuTkdPmAduLiedNEg
…inst YOUR model Two questions, deliberately kept apart, because they fail for different reasons and drift for different reasons (design §D5): - APPLICABILITY — "would this emit anything for my model?" — is `--probe`. It constructs every catalog generator and dry-runs it, one isolated run each, and reports a real file count. It cannot go stale, because it does not describe the generators, it runs them. That is the whole answer to the `capability` layer looking like an undifferentiated bucket: you are not meant to pick inside it by reading labels. - COMPATIBILITY — "what does this need to work?" — is declared (`requires`, `runtimePeers`, `configKeys`) and therefore gated separately, in a later commit. Three consequences worth naming: - One `runGen` per generator, not one run over the suite. Two shipped generators genuinely cannot be probed — `render-helper` needs an on-disk template root for its drift gate, `shared-model` needs a `files` selection `meta gen` supplies at run time — and a suite-wide run would take the entire listing down with them. Each reports its own reason and every other row still answers. - `useWhen` / `emits` are READ from each reference template's own header, never restated in the registry, so a catalog row cannot describe a generator differently from the file an adopter opens. - Install ranges: the package range is the CLI's own version (engine and CLI ship in lockstep), and third-party peer ranges are read from the runtime package's own `peerDependencies`. `install-set.ts` generalizes the reader `init` had for one package. A second copy of a peer range is a second thing to keep in step, and the failure mode of drift is an adopter installing a major nothing was tested against. `--probe` without a project is a usage error rather than a listing of zeros, which would read like "none of these apply to you". `--probe` without `--list` is refused rather than silently ignored. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011cQxyVuTkdPmAduLiedNEg
…he generators emit The `@implementedBy` doctrine applied to the catalog: a declaration is a promise someone has to remember to keep, and "someone remembers" scales badly across five ports and a growing framework set. So the gate RUNS every generator over a fixture model, reads the emitted files back, and asserts `requires`, `runtimePackages` and `runtimePeers` are supersets of what actually got imported. The declarations in this commit were then read off its failure messages — none was guessed and gated afterwards. Three things the derivation corrected: - **`runtimePackage` had to become `runtimePackages`.** The emitted code imports more than one MetaObjects runtime: an `output-parser` module imports `metadata`, `render` AND `runtime-ts`; a `hooks` module imports `runtime-web` and `tanstack`. A singular field would have forced two of three to go undeclared — exactly the under-declaration the gate exists to catch, written into the type. - **`grid-hook` requires `grid`, and the fixture had to be fixed to see it.** The hook imports the columns module only when a `layout.dataGrid` declares a filter PRESET. Without one the edge is invisible, the derivation reports nothing, and the gate cheerfully certifies `requires: []` — a green gate over a hole. The fixture now declares a preset for that reason and says so. - **Six generators contribute no evidence and are PINNED as such.** render-helper needs a template root, shared-model a `files` selection, trace-helper an LlmCallBase subtype, docs/api-docs a docs config, template is a no-op primitive. Their subset checks are vacuous, so the list is asserted exactly rather than left implicit — a corpus that quietly loses coverage fails nothing. Subset checks, not equality: over-declaring is a documentation defect an adopter shrugs off; under-declaring hands them a file that does not compile. `configKeys` is deliberately NOT gated this way (nor does the design ask it to be) — it is typed `keyof MetaobjectsGenConfig`, which buys the rename protection that is the real drift mode, and the values here come from reading each generator's own `ctx.*` reads rather than from guessing. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011cQxyVuTkdPmAduLiedNEg
…ameworks Codegen is opt-in, so the selection is the adopter's — which makes `meta gen` the place it gets AUDITED, by naming the two ways a legal selection still surprises you. Both warn; neither fails a build. A hand-written half is legitimate, and so is serving Node and edge from one model. The load-bearing detail is a name collision that would have made both gates silent no-ops: the catalog key is `routes` / `grid-hook`, but the object a factory returns calls itself `routes-file` / `tanstack-grid-hook`. Keying on `g.name` matches nothing — and matches nothing QUIETLY, because a name the catalog does not know is legitimately skipped as somebody's own generator. So `stableNameIndex()` derives the mapping by constructing every catalog factory and reading the name back, and a conformance test asserts that index is TOTAL. A hand-kept table would have been a third spelling of every generator's name, whose staleness looks exactly like success. `runGen` takes the catalog as an option, defaulting to codegen-ts's own slice: the composition lives in the CLI, since codegen-ts cannot import its own dependents. An embedder that never composes stays correct — it simply has nothing to say about client-tier generators. Three tests in sourceless-objects.test.ts wire BOTH route generators on purpose (the question is whether a sourceless object gets DB-bound artifacts, asked of both HTTP surfaces at once) and asserted zero warnings. They now filter that one advisory by substring rather than relaxing to "some warnings", so every OTHER unexpected warning still fails them. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011cQxyVuTkdPmAduLiedNEg
…nstall set Under opt-in codegen `eject` is THE copy door — `meta init` wires nothing, so every generator an adopter runs arrives through here — and a real selection is several names, not one. Three separate invocations produce three separate install lines for the same package; taking them together is what makes the install set usable. - `--format json` emits one document: per file the two edits to make (`wire.import` and `wire.entry`) and its `requires`, then ONE install set and the config keys the ejected generators read. The entry is read from the template's own header rather than derived from the file name, because the exported symbol does not follow it — `hooks.ts` exports `tanstackQuery`. - An unknown name refuses the WHOLE call before any file is written. A partial eject is the worst outcome available: a non-zero exit over a half-changed repo, where re-running the fixed command reports the already-copied half as "preserved" and the adopter cannot tell what happened. - Text mode additionally names the `requires` edges the selection does not satisfy. `meta gen` warns about this too, but saying it here is what stops a broken pair being wired in the first place. One bug caught by its own test: the duplicate-name check was written as `positionals.filter((n) => !seen.add(n))`, and `Set.add` returns the SET — always truthy — so it reported nothing. It is a loop now, with the trap named in a comment. Every existing single-name message is unchanged; each was written against a real incident (a stale owned copy reading as DIFFERS, a --force silently discarding customization, "paste" producing a duplicate binding that runs the packaged generator). Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011cQxyVuTkdPmAduLiedNEg
…ection
A new project got code it never asked for: five generators copied and wired, five
dependencies declared for them, and a throwing `src/db.ts` stub to make one of those
generators' emitted import resolve. None of it was chosen. `generators: []` now, and
the config's job is to point at the catalog.
The scaffold is a NET SHRINK, and each removal follows from the same fact rather than
being separate tidying:
- The five-name copy list and its copier. The list existed as an explicit literal
because looping over REFERENCE_GENERATOR_NAMES had once made init silently start
writing an unwired `routes-hono.ts` into every fresh project. Opt-in removes the
class: there is no eager set to drift.
- `dbImport` and the `src/db.ts` throwing stub — including its three-branch
"was it written this run?" warning and the `dbStubWritten` parameter threaded into
the next-steps message. All of it existed because the scaffold wired `routesFile()`,
whose output emits `import { db } from …`. Nothing is wired, so nothing emits it.
`dbImport` is a declared `configKey` on the `routes` catalog entry now, reported by
`meta eject routes` to the adopter who actually chose routes.
- The five dependency declarations and the peer-range reader behind them. Declaring
them now would be declaring a dependency on code this project may never generate.
What STAYS is the layout and the interfaces — `codegen/generators/` (empty),
`tsconfig.codegen.json`, `.metaobjects/`, the config shape, and the ESM `"type":
"module"` handling, which is unrelated to what is wired.
The tests were translated, not deleted. `scaffold-output-imports-declared.test.ts`
asserted "everything `meta gen` writes must be resolvable from what `meta init`
declared" — an invariant that would now pass vacuously. It ejects a selection, applies
the install set `eject` reported, generates, and checks the manifest: same invariant,
asked of the command that now owns the obligation. Its three-starting-manifest
dimension is kept, because the lesson there was about testing one shape, not about the
function that happened to hold the bug.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011cQxyVuTkdPmAduLiedNEg
…uired C# ran nine generators for a caller who named none; Python ran eight. Both were a shape nobody chose, and both now report a usage error and write nothing. Java has never had a default set and has been right all along; TypeScript dropped its five in the same release. Two consequences beyond the removal itself: - **`verify --codegen` re-runs the SELECTION**, so with no default suite there is nothing to diff against. Both ports now say "no generators selected, nothing to check" rather than silently regenerating a suite the project never ran and convicting every file of being missing. Python had no `--generators` flag on `verify` at all — it does now, mirroring the C# option, and both of its verify rungs (explicit-dir and neutral-fallback) honour it. - **Two C# gates were ANCHORED on the default list**, deliberately: `CodegenDriftTests` and `NoMagicPhysicalNamesTests` derived from it rather than hardcoding, because a generator added to the real list and forgotten in a copy is silently never tested. That anchor could not become a literal again, so it moves UP to the whole REGISTRY — strictly more coverage than the nine that happened to be default, minus `render-helper` and `template`, each excluded for a stated reason (a template root, and a no-default-walk primitive) rather than for being uninteresting. The mechanics tests — write path, hash manifest, baselines, column naming, template-spec resolution, staleness nudges, drift detection — are about how gen behaves, not about what an app should run, so they name a suite in ONE place per port (`GenSuite.Names`, `tests/codegen/gen_suite.py`). Both say in their own docs that they are test-local conveniences and that nothing in the product reads them; the value is deliberately the old default, because those fixtures and assertions were written against exactly that output. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011cQxyVuTkdPmAduLiedNEg
…tion procedure
ADR-0034 Decision 2 already ruled that choosing generators "cannot be captured in CLI
flags" because it is judgment over infinite per-project variation. It then made one
selection anyway, for the first-run case. Amendment 2 retracts that half and leaves the
rest standing; Amendment 1 (FR-040's `meta eject`) is written down at the same time,
since it had been an unlabelled amendment referred to by number in two other documents.
`docs/compatibility-policy.md` is narrowed in the same commit, which is what makes this
a PATCH: the scaffold-and-own promise is the LAYOUT and the INTERFACES —
`codegen/generators/`, the local-import config shape, `.metaobjects/`, the `Generator`
interface — not which generators a fresh scaffold happens to wire.
The `metaobjects-codegen` skill gets the PROCEDURE, not a list: read the app, `--list
--probe`, choose by layer and satisfy `requires`, `eject`, `gen`. Recipes are stated at
intent level ("a headless data service is model + persistence") because naming members
in prose is a list that goes stale the day a generator is added, while `--probe` cannot,
since it runs the generators rather than describing them. The TypeScript reference's
generator table says outright that it is a per-emission reference and NOT the selection
surface.
A new gate keeps that honest, and is deliberately narrow. It checks two things: every
generator name the skill hands to a COMMAND (`meta eject a b c`, `--generators a,b,c`)
is a real stable name, and every layer it names is one of the six. Both are checked
where the reader will literally type them. A looser "every backticked token must be
real" sweep was tried first and flagged the English word `interface` and the field names
`framework` and `requires` — a gate that cries wolf gets ignored, and then it gates
nothing. The authority is the cross-port MANIFEST, not the TypeScript catalog, because
the C# reference legitimately names `db-context`.
Agent-context corpus regenerated in this commit, as it must be.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011cQxyVuTkdPmAduLiedNEg
…Amendment 2) `ERR_MERGE_CONFLICT` fired even under an explicit `overlay: true`, which made the one move FR-043 §5.5 asks an adopter to make — retune a library requirement's `@status` — look like a defect. It now fires only on an UNMARKED conflicting redeclaration, in all four loaders (Kotlin inherits the JVM's). The reasoning is that the flag already means something specific and this makes it mean one thing rather than two: the conflict error exists to catch two files that collided WITHOUT knowing about each other, and `overlay: true` is the author saying "I know about the other declaration and I mean to change it". The loader already treats it specially — find-or-throw versus create-or-find. Checked per NODE, not per file, because a nested overlay marks its own ancestors and each is judged on its own flag. **The coverage MOVED rather than being deleted.** `overlay-attr-last-writer-wins` marks its overlay and expected the error; flipping it alone would have left nothing covering the case FR5c was written for. `merge-conflict-unmarked-attr-redeclaration` is the identical collision with neither file marked, and the two carry READMEs pointing at each other so the pair cannot be half-read. `overlay-nested-requirement` flips to zero errors in the same change and gains a README stating both things it pins. **One consequence beyond what the amendment weighed, recorded rather than left to be discovered.** The ruling is unconditional, so it reaches a DEPENDENCY node an adopter overlays: `fixtures/dependency-conformance`'s `an-overlay-attr-the-base-now-sets-differently-conflicts` expected the error there and now loads clean. It is renamed `…-is-licensed`, an unmarked sibling is added so the accident case stays covered on that axis, and the spec says why: what guards a dependency is the hash lock plus `meta deps check` and `refuseUnownedPackages`, not the merge-conflict error. Corpus is 325. Four-file bump done (fixture, AGENTS.md, both CONFORMANCE.md sites plus its prefix map, site-payload). Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011cQxyVuTkdPmAduLiedNEg
… layer-granular FR-043 Phase 1 items 1, 1a, 1b, 2 and 2b. A library now ships its core model, its DB persistence and its requirements as separate layers, and an adopter takes as much of it as they want. **The core layer declares no `source.rdb`, and that is the whole design.** A sourceless object is inert by a contract that already ships — migrate skips an object with no writable source, codegen emits no route/queries/hooks/grid/form for one, both citing #248 — so `libraries: ["iam"]` adds ZERO tables and ZERO generated code. What an adopter gains is the design being present and resolvable: an agent in the repo knows the capability exists, and nothing else happens until they add `"iam/db"`. A new test asserts that inertness per library rather than trusting it, because a single `source.rdb` slipped into a core layer would break it SILENTLY — the adopter's next migrate simply proposes a table. **`iam`** is nine entities: User, GroupType, Group, Role, Permission, and four grant junctions. The two shape decisions worth naming: Permission is an ENTITY (its own identity, its own lifecycle, a junction with real FKs — ADR-0037's own test), and grants are TWO junctions rather than one with a nullable scope, because a NULL in a unique key is distinct from every other NULL in SQL, so a nullable-scope design lets the same global grant be inserted twice and fixing it needs a partial index carrying a physical column name. Twenty-one requirements ship with it; `noCredentialsOnUser` is the one that earns the library its keep with an agent, stating as a prohibition IN FORCE the one thing every reader of a user table proposes adding. **`ai` splits the same way**, closing the concrete-`LlmCall` wart rather than documenting it. It was accepted on the grounds that splitting changes what existing `ai` adopters get; the estate sweep found there are none. **Layer selection is real work, done in all four ports.** `librarySources` was package-granular — every ref under a library came back for a bare name — which under this design would hand an adopter the db layer they did not ask for. It now resolves a token through the manifest's declared layers. `"iam/db"` IMPLIES `"iam"`, and the implication is not a convenience: a db layer is nothing but `overlay: true` redeclarations, and an overlay whose target was never declared is ERR_OVERLAY_NO_TARGET. A token whose LAYER is unknown is dropped WHOLE rather than reduced to its core — implying the core from an invalid layer would answer a mistyped `iam/database` with an inert core and no tables. **`libraries` moved to `.metaobjects/config.json`**, beside `dependencies`, outright and with no dual-read (zero estate uses). Which designs a project adopts is a fact about the PROJECT, not about how one port generates code from it, and that file is the port-neutral one every port already reads. A config still carrying the old key gets a pointed error rather than silence. It also rides `collectionLoadOptions` now instead of a second helper — #333 is on record as the bug where one of those two reached every command and the other reached none. `ERR_UNKNOWN_LIBRARY` is registered in all four ports and the shared corpus list. It prints TOKENS, not library names, so an adopter who typed `iam/database` is shown `iam/db` rather than only the half they got right. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011cQxyVuTkdPmAduLiedNEg
Seven of the twelve. Stated at the top of §8 rather than left to be reconstructed from git log, because the remaining five (coverage activation, the catalog library row, implied-generator warnings, `meta eject <lib>`, docs) each depend on knowing which of the foundations is already load-bearing. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011cQxyVuTkdPmAduLiedNEg
…and must pass its own gate FR-043 Phase 1 item 3, plus the half of item 2 that was declared shipped and was not: the standalone verify gate. Writing the gate is what found the rest of this commit. **Both shipped libraries failed the requirement gate.** Eleven errors and two warnings, in metadata an adopter cannot fix: every L4 in `ai` claimed FIELDS (`LlmCallBase.traceId`), which is ERR_REQUIREMENT_L4_NOT_OBJECT, and both libraries wrote their concerns as SIBLINGS of the L2 segment the file comments said they were children of — leaving that L2 claiming nothing in its whole subtree. `library-load` proved the libraries LOAD clean, which is a different claim, and nothing checked the other one. Every adopter who opted in would have run `meta verify` over it. Both are fixed as the model intends rather than by relaxing anything: the concerns are nested under their L2, and each L4 names the OBJECT with the fields hanging off it as an L5 child. The grain split earns its keep twice — `ai`'s `typedIo` and `iam`'s `roleScopedToGroupType` are both `partial` + `accepted` parents over a `live` L5, which says exactly what is shipped and what is the adopter's move, and a member-grain claim RESOLVES, so dropping one of the four addressing columns now fails a build that naming the object alone would not have. **The gate itself is derived, not listed.** It iterates `knownLibraryTokens()`, so a new library — or a new layer — is gated the day it is embedded, and it asserts the whole surface an adopter inherits: zero loader errors, zero loader WARNINGS (one `filterable-without-index` on a library field would print in every adopter's run forever), zero gate findings, zero authoring-lint findings, no unruled gaps (§5.4), and every entity claimed by the library's own ledger. **Item 3: object coverage activates on ADOPTER-authored requirements only.** `checkRequirements` activated it on the presence of ANY requirement, so opting into `iam` would have switched the unclaimed-entity gate on across a project that has never written one, and reported every entity in it — measuring the library's decision to ship a ledger rather than anything the adopter did. Library requirements are still counted, still gate-checked, still claim what they claim. Write one of your own and coverage turns on, over the library's entities too, which by then its own ledger claims. Provenance is the library's declared PACKAGE, read from the embedded manifests: that is a manifest fact the standalone gate resolves against the library loaded alone, whereas a node's source id differs between the on-disk dev layout (an absolute path) and the embedded one, so a rule keyed on source would hold here and stop holding in an installed build. An adopter OVERLAYING a library requirement is deliberately not authoring one — disagreeing with a shipped verdict is a statement about the library's design, and treating it as activation would mean correcting one entry silently acquired a coverage gate over the whole estate. The summary line says `coverage: not measured (no project-authored requirements)` rather than a ratio, and the JSON omits the pair rather than zeroing it: a reader cannot tell `0/0 claimed` from "not measured", and the two mean opposite things. `measureCoverage` can be forced by the one caller that legitimately knows better — the standalone gate, where the library IS the project under test. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011cQxyVuTkdPmAduLiedNEg
… --probe FR-043 Phase 1 item 4. `meta gen --list` gains `kind: "library"` rows beside the generators rather than a second command: an agent about to model "users who log in and things some of them may not do" should meet `iam` in the list it was already reading. **The row describes the box; the project block describes your shelf.** `provides` counts what a library ships across ALL its layers — nine entities, one abstract, twelve requirements for `iam` — while `project.tablesAdded` counts what YOUR selection put into the model. Under Amendment 1 those are different numbers in the common case: `libraries: ["iam"]` provides nine entities and adds zero tables, which is the inertness promise expressed as a number an adopter can read before committing. The project block also names which layers you selected, which of your entities `extends` into the library (the adoption that opting out would break), how many requirements it put in your ledger, and any generator it implies that you have not wired — a fact, not a warning: a library is metadata, and wiring is the adopter's call. `layers` is the field an adopter acts on, because you do not opt into a library, you opt into its layers. **Every manifest fact is resolved against the thing it claims** (§4), in a new test per library: `name` against the key AND the last segment of every package; `packages` against the library loaded standalone, BOTH ways (a package claimed but empty is a promise unkept; one declared but unclaimed escapes the ownership refusal that reads the list); `generators[].name` against the composed catalog; `generators[].anchor` against the nodes the library actually ships — which is what lets item 5 retire a hard-coded entity name. The `ports` claim is resolved too: every ref, in every port's embedded module, with Kotlin mapped onto the JVM's because it has no embed of its own. **One namespace.** A library name may not equal a generator stable name — they are rows in one table and `meta eject <name>` takes either, so a collision would make the catalog ambiguous exactly where an agent acts on it. The two skills get the step and its mirror: `metaobjects-codegen` checks the libraries before choosing generators, `metaobjects-authoring` before declaring an entity. The grounding gate is extended to cover them, keyed on STRUCTURE as the existing checks are — a token inside a `libraries` array, which is a config value a reader copies, never a backticked word in prose. Proven by breaking it: `iam/database` fails by name. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011cQxyVuTkdPmAduLiedNEg
…copy is refused while still opted in FR-043 Phase 1 items 5 and 6. **Item 5 — the hard-coded entity name is retired, and it was hiding a real bug.** `trace-helper` compared `"LlmCallBase"` against the SHORT name anywhere in an entity's super chain, so ANY adopter entity of that name, in ANY package, emitted a helper that writes the shipped base's columns — columns that entity does not declare. It now reads the `anchor` its library's manifest declares, resolves it to a node in the run's own loaded root, and compares by node IDENTITY (Java and Python compare the full name, which within one loader is the same claim). All three ports that ship the generator. That the old predicate never actually keyed on the shipped base is visible in what this commit had to change: every trace fixture in three ports declared its OWN `LlmCallBase` and passed. That is the bypass ADR-0024 named — "the green tests pass only because they bypass the shipped base with bespoke entities" — and the fixtures now extend the real one through the `libraries` opt-in. A new test pins the impostor arm in each port. `runGen` gains `ctx.libraries`. Undefined means the caller never said (a programmatic run) and every shipped anchor is a candidate; `[]` is the opposite and is honoured — the caller looked, and nothing is opted in. **Two self-extinguishing warnings** cover the halves of one choice: a library opted into whose implied generator is not wired (the design is in your model, its code is not being generated) and a generator wired whose library is not opted into (its anchor is a node only that library declares, so it emits nothing — indistinguishable from "no trace entities yet" without the line). **Item 6 — `meta eject <library>`, and the guard that makes it finishable.** Eject copies every layer into the project's first DECLARED source root, resolved through `resolveCollection()` — never `metaobjects/`, which is the default value of `sources` and nothing else. Files land as `meta.<library>.<file>.yaml` (three libraries ejected into one root would otherwise collide on `model.yaml`) carrying a provenance header that states the one step left: remove the library from `libraries`. Skip that step and both trees load and merge, and the merge is ASYMMETRIC — additions in your copy take effect and deletions do not, because the library still declares what you removed. `ERR_LIBRARY_PACKAGE_COLLISION` refuses it outright, in TS and Python. `ERR_LIBRARY_PACKAGE_NOT_OWNED` is its opposite: a NEW node declared into a package the library owns, where a later release may ship that name and merge into yours. An `overlay: true` amendment is the documented door and stays open — the loader's own `isMerge` separates the two, which no comparison of the merged trees could do (Python gained the flag to match; its merge recorded nothing). **`meta eject --list` reports per-node staleness** for what this project already owns, through the canonical serializer in own mode, matched by NAME with the package neutralized — because §3.4 says an ejector may rename the package freely, and keying on the FQN would report a renamed copy as wholly changed. And `meta verify` gains an advisory for `metaobjects::` nodes with no ejection provenance. **A library file now carries a stable `library:<ref>.yaml` source id in every build.** It was the file's BASENAME on disk and `library:…` when embedded, so one node's error envelope read `model.yaml` in a checkout and something else in an installed package — and collided outright with an adopter file of that name, which is exactly what the collision guard has to tell apart. Java and C# gained an id-carrying `FileSource` constructor for it; all four ports now report identically. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011cQxyVuTkdPmAduLiedNEg
FR-043 Phase 1 item 7. `docs/features/libraries.md` leads with the thing the rest of the design rests on: a library is LAYERED and its core layer is INERT, so `["iam"]` adds zero tables and zero generated code while making the design present and resolvable. Then the door an adopter actually uses — copy is the expected mode — and the one step that finishes an eject, with the loader error that fires when it is skipped. `cli.md`'s `libraries` section was stale on two counts: it showed the key in `metaobjects.config.ts`, which it left in this cycle, and it predates layers entirely. It gains the layer tokens, the implication rule, and `meta eject <library>` with its staleness report. The compatibility policy gains the clause a shipped library needs: `stable` is additive-only within a MINOR, `preview` is exempt with a stated promotion bar, and the two things that bound what either costs — copy-and-own, and a core layer that generates nothing. `CLAUDE.md` (via `AGENTS.md`, its symlink target) says SIX pillars. The sixth is not a sixth verb: a library is the reuse unit that composes the other five, and what makes it a pillar rather than a folder of YAML is the fifth — without requirements it is a schema snippet; with them it is design an adopter's build is held to. The CHANGELOG carries the `ai` split as the breaking-ish note it is (opting into `"ai"` alone no longer proposes `CREATE TABLE llm_call` — add `"ai/db"`), the coverage denominator growing for a project that already has a ledger, and the library gate finding that both shipped libraries failed `meta verify` before it existed. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011cQxyVuTkdPmAduLiedNEg
…adicted The spec's §8 now records the whole of Phase 1 as done, plus the three findings that disagreed with what it assumed: item 2's standalone-verify gate was declared shipped and did not exist (and both libraries failed it), §6's "latent bug" in trace-helper was the whole behaviour rather than a corner of it, and a library file's source id was ambiguous in exactly the way the collision guard has to resolve. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011cQxyVuTkdPmAduLiedNEg
…l documentation properly updated for FR-043 Phase 1 libraries and opt-in codegen changes.
…three notes stop promising a default suite Two review findings from the FR-043 Phase 1 gate, both in this change's own surface. `ownNodesByName` keyed the staleness comparison on the BARE node name. The reasoning behind not using the FQN still holds — §3.4 invites an ejector to rename the package, and an FQN key reports every node of a renamed copy as both upstream-only and local-only. But a bare name is not a key: a library free to use two packages is free to declare `User` in both, and one map entry for two declarations means the one serialized last silently wins. The other one's divergence is then reported as `identical` — a staleness check answering the single question it exists for with the wrong answer, and the wrong answer in the quiet direction. The key is now the node's package path RELATIVE to the library's own root package, computed segment-wise so `acme::identity` and `acme::identityhub` are not confused for one another. That is exactly what survives the invited edit: moving the root leaves every suffix below it where it was. The root package (rather than each node's own) is what gets neutralized in the serialized text too, so a deeper node's reference back up to the root is neutralized in it as well. A single-package library yields the bare names it always did, so the two shipped libraries compare exactly as before. No shipped library uses two packages yet, which is why nothing caught this. The new fixture does, so the first library that adds one cannot land the misreport with it. Second: three notes still described a default generator suite that ADR-0034 Amendment 2 deleted. `GenCommand`'s XML doc promised "when generatorNames is null/empty the default suite runs (back-compat)" four lines below its own `NoGeneratorsSelected` constant and a hundred above the body that refuses; the two registry headers pointed at `GenCommand.DefaultGenerators` and `cli._default_generators`, neither of which exists. Comments that contradict the code are read as the contract by whoever arrives next, so they now say what was removed and what replaced it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011cQxyVuTkdPmAduLiedNEg
…odegen, no default suite
The stale-reference sweep replaced two "ships in the default generator suite" claims with "use `dotnet meta eject names`" and "use `meta eject names`". Both name a command that does not exist: `eject` is the Node `meta` CLI's, and per ADR-0015 the C# CLI is `gen`/`verify` only while the Python console-script is the same pair. A reader following either line gets an unknown-command error. They also conflated two different things. Ejecting is about OWNING a generator's source (ADR-0034); it is not how a run selects one. Both ports select with `--generators <csv>`, which is what these sections now say — and each names its own `--list` as the catalog, so the next question has an answer in the same sentence. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011cQxyVuTkdPmAduLiedNEg
…e this branch deleted `29f84b461` removed `cli._default_generators()` and `GenCommand.DefaultGeneratorNames`, which made ADR-0034 Amendment 2 true on every port. Ten places in the shipped skills went on describing the world before it — and these are not repo docs, they assemble into every adopter's stack, so the wrong answer arrives wherever an agent is doing the work. The sharpest was a table in `metaobjects-codegen/SKILL.md` naming both removed symbols as "a real default" and answering "does an existing project upgrading get it?" with **Yes, with no edit** for C# and Python. The same claim drove a COUNT in two other skills — "on three of five ports an existing project emits none" — which is now five of five, so the fix is arithmetic, not a word swap. Alongside it, `meta init` no longer scaffolds `namesFile()`; it writes `generators: []` and an empty `codegen/generators/`, so the paragraph that offered the scaffold as the port's exception had no exception left to offer. The rest were `--template-spec` entries "appended to the default suite" (C# and Python) and three "`names` is in the default suite" asides. Every surviving mention of the phrase in `agent-context/` is now a negation. The conformance corpus is regenerated in this commit rather than a later one: the expected trees are byte-compared against `assemble()`, so prose and corpus moving apart by even one commit is a red lane on a docs-only push. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011cQxyVuTkdPmAduLiedNEg
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Intent
GOAL: Ship FR-043 Phase 1 — reusable declared design as named, opt-in "libraries" (the sixth MetaObjects pillar), plus opt-in codegen via a generator catalog (ADR-0034 Amendment 2). Landing as PR 369 against main, NOT a direct push to main, at the user explicit instruction. PR 369 is open on this branch and has been green on three prior rounds.
WHAT CHANGED SINCE THE LAST GATE ROUND: exactly one commit, 6f11da4, DOCS + FIXTURES only.
The previous round's document step flagged one line in agent-context/skills/metaobjects-audit/SKILL.md as a pre-existing stale claim and called it out of scope. It was NOT pre-existing and the user ruled to fix it here: origin/main still carries cli._default_generators() and GenCommand.DefaultGeneratorNames, and commit 29f84b4 ON THIS BRANCH deleted both. So this branch is what made those claims false. A sweep of agent-context/ found TEN such places, not one.
The sharpest was a table in metaobjects-codegen/SKILL.md naming both removed symbols as "a real default" and answering "does an existing project upgrading get it?" with "Yes, with no edit" for C# and Python. That same claim drove a COUNT repeated in two other skills — "on three of five ports an existing project emits none" — which is now five of five, so the correction is arithmetic rather than a word swap. Separately, meta init no longer scaffolds namesFile(); commit 840a2fc made it write generators: [] plus an empty codegen/generators/, so the paragraph offering the TS scaffold as that port's exception had no exception left. The remainder were --template-spec entries described as "appended to the default suite" on C# and Python, and three "names is in the default suite" asides in audit and runtime-ui references.
Every surviving occurrence of the phrase "default suite" in agent-context/ is now a NEGATION ("no port ships a default suite", "there is no default suite", "dropped their default suites"). Those are correct and must not be flagged as stale.
Files: 7 under agent-context/skills/, plus 17 regenerated expected trees under fixtures/agent-context-conformance/. The regen is deliberately in the SAME commit: sdk/test/agent-context-conformance.test.ts byte-compares each expected tree against assemble(), so prose and corpus moving apart by even one commit turns the lane red on a docs-only push. The corpus test has no --update switch, so the regen was done with a throwaway script placed INSIDE the sdk package (a scratchpad script under /tmp resolves a stale /tmp/node_modules instead of the workspace) and deleted immediately after; it is not in the commit.
Verified before commit: sdk/test/agent-context-conformance.test.ts 5 pass 0 fail, and the full sdk package suite 322 pass 0 fail across 32 files. No code, no behaviour change.
THE REST OF THE BRANCH, unchanged and validated over three gate rounds (rounds 2 and 3: review 0 findings, test 0 findings): 26 FR-043 Phase 1 commits, bfe3b5b (round 1 review findings: eject staleness keying + three stale code comments), 306136d (a docs correction of two nonexistent commands the round-2 document step introduced), and two no-mistakes document commits. scripts/ci-local.sh passed green on the 26-commit tree — all 41 gates, the 5-port conformance matrix, the Java reactor, the docker integration suite.
Deliberate decisions a reviewer reading only the diff would not know:
A library is LAYERED and its core layer is INERT: the core declares no source.rdb, so selecting "iam" adds zero tables and zero generated code, while "iam/db" is the separate opt-in that proposes schema. The ai library split is therefore breaking-ish for a tracking adopter — "ai" alone no longer proposes CREATE TABLE llm_call — which is intended and recorded in the CHANGELOG.
Copy is the expected mode (meta eject , the NODE CLI only); an ejected copy still named in libraries is REFUSED at load with ERR_LIBRARY_PACKAGE_COLLISION. COLLISION vs NOT_OWNED are told apart by isMerge, the loader own record that overlay: true was honoured; no comparison of the merged trees could make that distinction.
Library source ids are library:.yaml in EVERY build, not the on-disk basename. Two tests assert the source KIND rather than the id label ON PURPOSE (TS library-load.test.ts, Python test_shipped_library_ai.py) — do not "fix" them back.
Object coverage activates on ADOPTER-authored requirements only, keyed on the library declared PACKAGE. A library must not volunteer a project for a gate it did not ask for, and an adopter OVERLAYING a library requirement is deliberately not "authoring one".
ownNodesByName keys eject staleness on the node package path RELATIVE to the library root package, segment-wise. Not the FQN, because spec section 3.4 invites a package rename; not the bare name, because a two-package library may declare User in both and one entry for two declarations silently loses a divergence. A single-package library yields the bare names it always did. ownNodesByName is exported so the new test can execute it; no shipped library uses two packages, so there is no end-to-end path through libraryStaleness yet.
cli/test/skill-catalog-grounding.test.ts is a text-over-markdown gate ON PURPOSE — it catches prose drift against the live catalog and keys on STRUCTURE. An earlier version flagging any backticked word near a keyword cried wolf and was rejected. Do not delete it as a grep test.
The GeneratorRegistry headers and GenCommand XML doc deliberately still NAME the removed symbols to tell the reader what went away, so a grep for those identifiers still hits those files on purpose.
SCOPE: Phase 1 ONLY. Phase 2 is in the spec section 8 and deliberately NOT here — third-party libraries over FR-023 transports, requires edges library-to-library, loader-level collision errors in all five ports, "live only if wired" in verify, Python and C# catalog rows and probe, migrate.scope.exclude, a runtime can() per port, an authentication library. Do not flag their absence.
REPO CONSTRAINTS: PUBLIC repo — no private or sibling project names, no absolute home paths, anywhere including commit subjects and branch names. CLAUDE.md is a SYMLINK to AGENTS.md; edit AGENTS.md and never rewrite the link. Never run a bare bun test at the repo root.
What Changed
Libraries as the sixth pillar: Users can now declare reusable, requirement-backed models via
"libraries": ["iam"]in.metaobjects/config.json, bringing common designs (users, roles, permissions, LLM traces) into their projects without hand-authoring from scratch.Layered library model with inert core: A library ships its core model, persistence (
/db), and UI rendering (/ui) as separate opt-in layers. The core layer declares no tables, so["iam"]adds zero generated code and zero tables — the design is present and resolvable, with schema persistence a separate second choice via["iam", "iam/db"].Opt-in codegen via a generator catalog: All five language ports moved from a hard-coded default generator suite to an explicit, catalog-driven selection.
meta initnow scaffolds an empty generators list;meta gen --list --probeshows the available generators and simulates what each would emit against your model;meta eject <name>installs the selected generators. C#, Python, and Kotlin's--generatorsflag is now required; TS and Java default to an empty selection.Overlay mechanism with explicit merge marking:
overlay: truelicenses an attribute override across multiple metadata files, permitting adopters to disagree with a library's shipped requirement without ejecting the whole ledger. Unmarked attribute conflicts now produceERR_MERGE_CONFLICTonly when the author did not consent to the override.Library catalog with metadata-driven discovery: Libraries appear as catalog rows in
meta gen --list, carryinguseWhen,layers,providesmetadata, and--probeanswers what a given library selection actually added to your project.Shipped libraries:
iam(preview) — nine entities, eleven requirements, users with typed groups, roles as permission bundles, grants scoped to groups — andai(stable), split intomodel+dblayers.ai/modelalone provides the typed LLM-call trace shape;ai/dbadds thellm_calltable.Cross-port conformance: Generator registry, library source resolution, overlay merge semantics, and requirement ledger validation now conform across all five ports (TS / C# / Java / Kotlin / Python). New conformance fixtures gate overlay behavior, library-declared entity names, and source id stability.
Documentation, agent context, and skill updates: Complete spec and feature docs, updated agent context skills with accurate capability descriptions, and conformance corpus fixes in all five language ports.
Risk Assessment
✅ Low: The reviewed commit (6f11da4) is docs+fixtures only — prose corrections to agent-context skill files that removed stale "default suite" claims, matched exactly by the user intent's description, with corresponding conformance-fixture regeneration in the same commit; no source/behavior code changed, no policy or security surface touched.
Testing
Ran the critical agent-context-conformance test covering 5 stack configurations (typescript-react, typescript-tanstack, csharp-react, java-react, java-kotlin-react-tanstack), which byte-compares assembled skills against expected fixture trees. All 5 cases pass, confirming the prose updates are accurate and complete. Also ran the full SDK package test suite (322 tests). Verified via git diff that 24 files changed, all in agent-context/skills/ and fixtures/agent-context-conformance/, with zero changes outside these documentation directories. Verified via grep that all surviving mentions of 'default suite' are negations ('no port ships a default suite', 'dropped their default suites', 'there is no default suite') and old references to 'three of five ports' have been corrected to 'ALL FIVE ports'. CHANGELOG confirms the codegen opt-in change from ADR-0034 Amendment 2."
Evidence: Test Evidence Summary
Pipeline
Updates from git push no-mistakes
✅ **intent** - passed
✅ No issues found.
AGENTS.md- branch carries 26 commit(s) that exist on your local main branch but were never pushed to origin/main; these may be unintended bundled work (proposed PR changes 236 file(s)):overlay: truelicenses an attribute override (FR-043 Amendment 2)overlay: truelicenses an overrideConfirm these commits belong in this PR before approving, or manually separate the intended work onto origin/main before gating.
✅ **Review** - passed
✅ No issues found.
✅ **Test** - passed
✅ No issues found.
bun test -- agent-context-conformance (5 pass, 0 fail, 93 expect calls)bun test -- packages/sdk (322 pass, 0 fail, 750 expect calls)git diff HEAD~1..HEAD file enumeration (24 files, all in agent-context/ or fixtures/)grep for all mentions of 'default suite' (all 4 remaining are negations or deletions)grep for removed symbols DefaultGeneratorNames and _default_generators (not found in source)✅ **Document** - passed
✅ No issues found.
✅ **Lint** - passed
✅ No issues found.
✅ **Push** - passed
✅ No issues found.