@metaobjectsdev/sdk 0.24.4 → 0.25.0

package/agent-context/skills/metaobjects-codegen/SKILL.md

@@ -24,8 +24,28 @@ You run a `gen` step. The runner:
 2. Resolves output targets and precomputes shared render state.
 3. Runs each configured **generator** — most emit one file per entity; some emit a
    single shared file (a barrel, a DB-context, an app-config).
-4. Refuses to overwrite any file that does NOT carry the `@generated` header;
-   overwrites the ones that do.
+4. Decides whether it may overwrite a file — and **the rule differs by port**:
+   - **TypeScript, C#, Python** — by a committed **hash manifest**
+     (`.metaobjects/.gen-state/.hashes.json`). If a file still hashes to what the
+     generator recorded writing, it is safe to overwrite; if it was edited, or there is
+     no record of it, the write is **refused by name**. TypeScript additionally
+     three-way-merges against a snapshot when one is present locally.
+   - **Java, Kotlin** — by a bare **`GENERATED`** token in the file's header comment
+     (`GeneratedFileWriter.GENERATED_MARKER`). The token is `GENERATED`, **not**
+     `@generated`: the matcher allows only whitespace between the comment punctuation
+     and the token, so an `@`-prefixed tag does not match it. Remove that token and
+     regeneration never touches the file again.
+
+   **The two rules protect a hand edit in opposite ways, so do not carry a habit across
+   ports.** On TypeScript, C# and Python, *editing the content* is what takes ownership —
+   that is what breaks the hash — and deleting the header changes nothing except your
+   ability to tell what generated the file. On Java and Kotlin the reverse holds: editing
+   a file protects it not at all, because the `GENERATED` token is still there and the
+   next run overwrites the edit; only removing that token does.
+
+   (The header text differs per port and none of it is the write decision on the
+   hash-manifest ports: TypeScript and Python emit `@generated by …`, C# emits
+   `<auto-generated/>`, Java and Kotlin emit the `GENERATED` token above.)
 
 The output is normal idiomatic code in your language — you import it and use it
 like any hand-written module.
@@ -35,8 +55,11 @@ like any hand-written module.
 Every emitted file carries a `@generated` header. This is load-bearing:
 
 - **Never hand-edit a file with a `@generated` header for a change you want to
-  keep.** The next `gen` run overwrites it. If you need different output, change
-  the metadata (or the template), not the generated file.
+  keep.** The next `gen` run overwrites it. If you need different output, change the
+  metadata, or change the generator that emits it.
+- **This rule is about emitted output — it is not a rule about your generators.** A
+  generator you own carries no `@generated` header and is edited like any other source
+  file in your repo. See the next section before you conclude a shape is unreachable.
 - **Hand-written regions are preserved by three-way merge.** Where the codegen
   supports designated hand-editable regions, regeneration runs a three-way merge
   (base → yours → newly-generated) so your edits survive a regen. Code review is
@@ -54,6 +77,43 @@ for a shape origins can express is drift the drift gate can't even see. A genuin
 loose either — it goes in the `source.rdb` **`@sql`** escape (#208, ADR-0043) so the
 tool still registers, fingerprints, and drift-checks it (see the projection bullet).
 
+## Your generators are yours — editing one needs no permission
+
+A generator in your repo is your code, not a vendor artifact. ADR-0034 is
+**scaffold-and-own**: the generators the scaffolded config wires are copied into your
+repo at init, and every reference template's header says so in its own first line
+("copy this into your repo … and own it", "now YOURS to change"). None carries a
+`@generated` header. Editing one is ordinary work.
+
+**A standing rule not to change the MetaObjects repo is not a rule about your
+generators.** They are different repositories, and you own yours outright. That
+generalisation is the observed failure mode, not a hypothetical: an agent told not to
+touch upstream quietly drops "edit the generator" from the moves available to it and
+hand-writes the layer instead — the single outcome the rest of this skill exists to
+prevent. If you are about to hand-write something data-shaped because the generated
+shape is wrong, the generator is the file to open, and you do not need to ask first.
+
+**The order when generated output does not fit:**
+
+1. **The metadata**, if the model is wrong — wrong column type, missing relationship,
+   a join that should be a projection. Fix the spine first; it fixes every port at once.
+2. **Your own generator**, if the model is right and the *emit* is wrong — naming, file
+   layout, imports, framework, signatures.
+3. **Hand-write**, only for what metadata genuinely cannot express — and wire it to the
+   generated types.
+
+Hand-writing something the metadata already describes is step 3 used as step 1.
+
+**The converse, so ownership does not become sprawl:** wire a generator only for output
+you will actually consume. Decide per generator, narrow one with its own `filter`, and
+own the ones you keep — an emitted file nobody imports still reads as an invitation to
+adopt the surface you decided against.
+
+How you get a generator's source differs per port — a copy command on TypeScript,
+implementing the port's generator interface elsewhere. Your language reference has the
+mechanism; see also "The commands and config keys that implement the steps above differ
+per port" below.
+
 ## Selecting generators by stable name
 
 Codegen is a set of named generators you opt into. Each generator has a **stable
@@ -150,12 +210,13 @@ don't silently churn the existing code.
 
 ## Write your own generators — the built-ins rarely fit an app exactly
 
-The built-in generators (entity, queries, routes, form, grid, barrel) cover the
-common shape, but **real apps routinely need output the built-ins don't emit as-is**
-— a bespoke REST contract, custom DTO/response shapes, an app-specific service or
-repository layer, a UI the defaults don't produce. When that happens the model-first
-move is **not** to abandon metadata and hand-write the layer. Write a **custom
-generator** that reads the same metadata and emits *your* app's shape.
+The built-in generators (entity, queries, routes, routes-hono, barrel, form, hooks,
+grid, grid-hook) cover the common shape, but **real apps routinely need output the
+built-ins don't emit as-is** — a bespoke REST contract, custom DTO/response shapes,
+an app-specific service or repository layer, a UI the defaults don't produce. When
+that happens the model-first move is **not** to abandon metadata and hand-write the
+layer. Write a **custom generator** that reads the same metadata and emits *your*
+app's shape.
 
 Treat this as a first-class, expected activity — not an escape hatch. A custom
 generator is still model-first: it derives from the metadata spine, so it
@@ -163,6 +224,12 @@ regenerates on change and stays consistent across every entity — the leverage
 forfeit by hand-writing. Hand-rolling *away from* metadata is the anti-pattern;
 generating *your own shape from* metadata is the point.
 
+This is for when the *shape* itself needs to change. If a built-in's shape is
+already right and only the *target* is wrong — a different framework than the
+shipped reference emits for — take ownership of that generator instead of writing
+one from scratch; see "Your framework isn't the default" below, and your language
+reference for the command that does it.
+
 The plugin interface is small (`@metaobjectsdev/codegen-ts`): a `Generator` is
 `{ name, filter?, generate }`, where `generate(ctx)` returns `EmittedFile[]`
 (`{ path, content }`). `perEntity` / `oncePerRun` wrap the common cases:
@@ -190,6 +257,31 @@ the `generators` array in `metaobjects.config.ts` next to the built-ins — it r
 the same pass, writes under the same target rules, and carries the `@generated`
 header so it round-trips like any other.
 
+## Your framework isn't the default — the retargeting procedure
+
+If the shipped templates do not emit for your stack, retargeting is the **normal first
+move** — not a workaround and not a sign of a bug. Owning a generator is the supported
+path to any framework; MetaObjects does not ship a codegen package per framework and is
+not waiting to.
+
+The doctrine, in order of what to try:
+
+1. **Check config first.** Several apparent codegen failures are one config value
+   (module-specifier style, output directory, dialect, API prefix). Change it and retest
+   before writing any code.
+2. **Own the generator, not the renderer.** Take a copy of the reference template for the
+   artifact that is wrong and edit the one step your framework disagrees about. Each
+   template's header names what its emit is coupled to and which call to swap.
+3. **Compose, do not fork.** Call the exported render function and wrap its result where
+   you can, so you keep receiving upstream fixes. Forking a whole renderer is the thing
+   to avoid — not owning the generator.
+4. **Server-tier output is usually already portable.** The entity module and the query
+   helpers carry no HTTP-framework coupling; retargeting is usually only needed at the
+   routes and UI tiers.
+
+Hand-rolling *away from* metadata is the anti-pattern. Generating *your own shape from*
+metadata is the point.
+
 ### Never read metadata through an `own*()` accessor (ADR-0039) — top bug source
 
 When writing OR reviewing a generator, **read every field/node property and iterate
@@ -239,6 +331,153 @@ output/template · doesn't fit → write a generator that emits your shape *from
 metadata* · only the genuinely un-modelable (business algorithms, external calls) is
 hand-written outside codegen — and it still imports the generated types.
 
+## Two ways to author a generator — pick deliberately
+
+A generator can be **programmatic** (code that builds the output) or **declarative** (a
+Mustache template plus a scope). Both are first-class, both ship in every port, and they
+are good at different things.
+
+| | Programmatic | Declarative template |
+|---|---|---|
+| What you write | a `Generator` in the port's language, using its AST builder (ts-poet, KotlinPoet, …) | a `.mustache` file + `{ template, scope, outputPattern, format? }` |
+| Output shape | expressed in code | **is the file you are editing** |
+| Cross-language | per-port by construction | one template emits for any language — it renders against the neutral, byte-gated data dict |
+| Logic | any | what a template can express: sections, iteration, presence flags |
+
+**The rule:** reach for **programmatic** when the logic is gnarly or the run is hot; reach
+for a **template** when the *shape* is what you are iterating on, or when you want the same
+output across languages. `scope` is `perEntity` / `perPackage` / `perModel` — the walk you
+would otherwise hand-write — and `outputPattern` is the output path per item, with
+`{name}` / `{Name}` / `{package}` placeholders (e.g. `"{package}/{Name}Service.java"`).
+Full tradeoff table and the data dict: `docs/features/codegen-concepts.md` §3 and §10.
+**Asking whether a base/extension split or a write-if-absent file exists? That's §5-§7, not
+here.** §5 (*Preserving hand edits*) states MetaObjects ships exactly one hand-edit strategy —
+no shipped generator on any port emits a generated-base + hand-owned-concrete pair, or a
+write-if-absent file; §6 names the `skip-existing` merge strategy `runGen` accepts for
+building that pair yourself, reachable only from a programmatic caller (no CLI flag selects
+it); §7 (*Safety*) is the per-port write-decision mechanism behind "What codegen does" step 4
+above.
+
+**A template is not limited to documents.** It emits source as readily as docs — that is
+what the neutral data dict is for.
+
+### Which is available to you depends on the port — check before you plan
+
+**TypeScript** has both, and the whole programmatic procedure is documented: `meta eject`,
+the `metaobjects.config.ts` keys, the exported `render*` functions — see this skill's
+`references/typescript.md`. The declarative path is declared in the SAME config: call
+`templateGenerator()` in `generators`, or spread a parsed JSON spec with
+`templateSpecToGenerators(parseTemplateSpec(...))` to reuse one written for C#/Python.
+**There is no `--template-spec` flag on `meta gen` and its absence is not a gap** — the
+config takes generator values, and keeping the declaration there is what keeps
+`meta verify --codegen` regenerating with it.
+
+**Java / Kotlin** have both. **No eject command** — a programmatic generator means
+implementing `com.metaobjects.generator.Generator` and naming your class in the Maven
+`<generator>` element, which the plugin loads from the project classpath. The declarative
+path is `TemplateScopeGenerator`, wired the same way with `<template>` / `<scope>` /
+`<outputPattern>` / `<format>` / `<templatesDir>` (plus the standard `<outputDir>`), and
+covers Java and Kotlin alike. No `--template-spec` flag here either, for the same reason:
+`<generator>` already loads a consumer class from the project classpath.
+
+**C# and Python: the declarative path is your only option, and it is a real one.** Their
+generator sets are **closed built-in registries** — `--generators` *selects* from what
+ships, and there is no seam to register a `Generator` of your own. (Python's
+`--provider module:symbol` registers **metamodel vocabulary**, not a generator; do not
+reach for it here.) Use `--template-spec <json>` — plus `--templates <dir>` on Python or
+`--template-root <dir>` on C# — and your entries are appended to the default suite. Worked
+examples with the full JSON: `docs/ports/python.md` and `docs/ports/csharp.md`.
+
+**The spec is auto-discovered, and that is load-bearing.** With no `--template-spec`, both
+ports read `<projectRoot>/template-spec.json` — projectRoot being the metadata dir's parent.
+Keep it there: `verify --codegen` accepts no `--template-spec` flag, so the conventional path
+is how the drift gate learns your template generators exist. Put the spec somewhere else and
+reach it only by flag, and `verify` regenerates without it and reports its output as stale.
+
+So on C#/Python, "I need a shape the built-ins do not emit" is answered by a template, not
+by writing generator code. Do not conclude the port cannot be customized.
+
+Each port's `references/` fragment documents what its built-ins emit, which is what you
+compare your own emit against; they do not carry a step-by-step retargeting procedure.
+
+## Never hand-write a physical name — the generator emits them
+
+A table name, a column name, a schema — these are declared in metadata and derived by the
+same resolver the migration and the runtime use. A string literal for one is a magic string
+that no compiler checks and no gate catches, and it goes wrong silently: `@column` is
+free-form, so a field named `callPurpose` may map to a column named `purpose_code`, which is
+neither the field name nor any transformation of it. A consumer deriving the column as
+`to_snake_case(<the field's name>)` gets that case wrong and never finds out.
+
+Every port emits a per-object names artifact. Reference it:
+
+```ts
+import { ProgramNames } from "./generated/Program.names.js";
+
+ProgramNames.name                          // "Program"        — the OBJECT's name
+ProgramNames.sources.primary.table         // "programs"       — physical table
+ProgramNames.sources.primary.kind          // "table"          — table | view | proc | …
+ProgramNames.fields.createdAt.name         // "createdAt"      — logical / wire name
+ProgramNames.fields.createdAt.column       // "created_at"     — physical column
+ProgramNames.indexes.ix_prog_owner.index   // "ix_prog_owner"  — database index name
+```
+
+The artifact mirrors the metadata tree: every node carries its own `type`, `subType` and
+`name`, and a physical name sits under the key that says **what kind of database object it
+is**. A view is `sources.primary.view`, a stored proc `sources.primary.proc`, and a
+write-through entity's read view `sources.replica.view` — so `sources.replica.table` is a
+compile error rather than a wrong answer. There is no `readOnly`: it was derived from
+`kind`, never declared, so ask `kind`.
+
+The artifact is per-object and the shape is per-language; the guarantee is the same
+everywhere — **each physical name is spelled once, and generated code references it**:
+
+| Port | Artifact | Reads as |
+|---|---|---|
+| TypeScript | `<Entity>.names.ts` | `ProgramNames.fields.createdAt.column` |
+| C# | `<Entity>Names.g.cs` | `ProgramNames.CreatedAtColumn` |
+| Java | `<Entity>Names.java` | `ProgramNames.CREATED_AT_COLUMN` |
+| Kotlin | `<Entity>Names.kt` | `ProgramNames.CREATED_AT_COLUMN` |
+| Python | `<entity_snake>_names.py` | `PROGRAM_CREATED_AT_COLUMN` |
+
+On TypeScript (`meta init`), C# and Python the names generator is in the default suite; on
+the JVM it is opt-in — add `SpringNamesGenerator` / `KotlinNamesGenerator` to the pom's
+`<generators>`, and the Exposed table binding switches to the constants once it is present.
+
+**It follows `extends`.** An object that extends another does not restate what it
+inherits: C# and Java use real class inheritance (`class CopayAuthNames extends
+AuthNames`), TypeScript spreads (`...AuthNames.fields`), and Kotlin and Python re-export
+the parent's constants by reference. An abstract base a persisted object extends gets an
+artifact of its own — columns only, no table name, because it has none. So if you are
+reading a subtype's artifact and its table name is not there, it is on the base, which is
+where it belongs.
+
+**Where generated code consumes it, and where it does not.** TypeScript, C# and Kotlin
+bind an ORM (Drizzle, EF Core, Exposed) and so must spell physical names — their generated
+code references these constants, and a cross-port gate proves no generated file spells one
+literally. **Java and Python generate no SQL at all**: their DTOs and models carry logical
+names, and persistence is the repository interface/`Protocol` you implement. There the
+artifact exists *for your code*, which is the only place a physical name appears.
+
+Two categories stay literal, deliberately, and the gate pins them as such rather than
+exempting them:
+
+- a **flattened value-object column** (`@storage: flattened`) is a composite —
+  `<owner field column>_<member column>` — belonging to no single field of either object,
+  so there is no one constant to reference;
+- a **write-through entity's replica view name**: the artifact holds the object's PRIMARY
+  source's name (its table), and a write-through entity has two physical names.
+
+**But prefer a typed handle where one exists — this rule has a real limit.** If the ORM
+gives you a type-checked object for the same thing, use that. Replacing a Drizzle column
+object (`programs.createdAt`, checked against the schema at compile time) with a string
+constant makes the code **worse**: it trades an error the compiler catches for one the
+database raises at runtime. The constants are for the places with no typed handle — raw
+SQL, migration scripts, log lines, an external system's column mapping, a port whose
+generated model carries no persistence binding at all.
+
+The rule is *don't invent the string*, not *replace every name with a constant*.
+
 ## Dialects
 
 Generated DB schema/DDL targets a SQL **dialect**:

package/agent-context/skills/metaobjects-codegen/references/csharp.md

@@ -47,6 +47,7 @@ or run the default set. Output lands under `--namespace` in `--output-dir`.
 | `callable` | `<Entity>.callable.g.cs` — an FR-015 calling method for a `source.rdb @kind="storedProc"|"tableFunction"`, via EF `FromSqlInterpolated` (args from the `@parameterRef` value object in declaration order). |
 | `payload` | `<Payload>.payload.cs` — the strict typed payload `record` (+ any nested element records) per `template.prompt` `@payloadRef` / `@responseRef` (each an `object.value`): `@payloadRef` types the REQUEST, `@responseRef` the REPLY the parser/extractor bind to. |
 | `output-parser` / `extractor` / `output-prompt` / `render-helper` | the prompt-pillar artifacts for a **responding `template.prompt`** — one carrying `@responseRef` (ADR-0052: these tiers are INBOUND; `template.output` is outbound only and emits no parser). The strict parser, the tolerant `extract`, the **output-format prompt fragment** (`output-prompt`; presentation via `@promptStyle: guide`/`inline`/`exampleOnly`), and the typed render helper. See the **prompts** reference. |
+| `names` | `<Entity>Names.g.cs` — `public abstract class <Entity>Names` of `const` physical database names, MIRRORING THE METADATA TREE: the object's own `Type`/`SubType`/`Name` (`Name` is the OBJECT's name, never a physical one), then per `source.rdb` keyed by `@role` — `SourcePrimaryType`/`SubType`/`Kind`, `SourcePrimarySchema` when declared, and the physical name under the alias for its `@kind` (`SourcePrimaryTable` / `SourceReplicaView` / `SourcePrimaryProc` / `…Function` / `…MaterializedView`) — then a `<Field>Field`/`<Field>Column` pair per field, then each identity and index (`IdentityPkName`, and `IdentityUqCustEmailIndex` / `IndexIxCustStatusIndex` — the DATABASE name, carried for `identity.secondary` and `index.lookup` only), then a complete `ColumnsByField`. There is no `ReadOnly`: it is a derivation over `@kind`, so ask `SourcePrimaryKind`. Emitted for every object with a declared or inherited primary source, PLUS a fragment for any abstract base such an object extends (its own identity + columns, and NO source members — it has no table). A class whose object extends another one **inherits** it (`class CopayAuthNames : AuthNames`) rather than restating its constants — a C# `const` is inherited, so `CopayAuthNames.IdColumn` and `CopayAuthNames.SourcePrimaryTable` resolve through the base (`Type`/`SubType`/`Name` are redeclared with `new`, since every artifact carries its own). `abstract`, not `static`, precisely so it can be inherited; it still cannot be instantiated. In the run, `entity` and `db-context` reference the constants (`[Table(OrderNames.SourcePrimaryTable)]`, `[Column(OrderNames.StatusColumn)]`, `.ToView(OrderNames.SourceReplicaView)`); a `--generators` selection omitting `names` falls back to literals. |
 | `template` | the generic Mustache `templateGenerator()` primitive. |
 
 Metadata lives under `metaobjects/` (or wherever you point `--metadata-dir`) in the

package/agent-context/skills/metaobjects-codegen/references/java.md

@@ -106,6 +106,7 @@ separate `metaobjects-codegen-base` module instead.)
 | `SpringRenderHelperGenerator` | the typed render helper for a `template.prompt` payload |
 | `LlmTraceHelperGenerator` | `<Entity>TraceHelper.java` per concrete entity — the LLM-trace helper |
 | `SpringFilterAllowlistGenerator` | per-entity filter allowlist |
+| `SpringNamesGenerator` | `<Entity>Names.java` — `public abstract class` of `static final String` names that MIRRORS THE METADATA TREE. Every node carries its own `TYPE`/`SUB_TYPE`/`NAME`, so `AuthorNames.NAME` is the OBJECT's name (`"Author"`), **not** a table name, and a physical name sits under the member that says what it is: `SOURCE_<ROLE>_TABLE` / `_VIEW` / `_MATERIALIZED_VIEW` / `_PROC` / `_FUNCTION`, from the metamodel's own `@kind`-to-alias map, with `<ROLE>` being `PRIMARY` or `REPLICA` (a write-through entity has a member for each). Plus a `<FIELD>_FIELD`/`<FIELD>_COLUMN` pair per field and a complete `COLUMNS_BY_FIELD`; an `identity.secondary` or `index.lookup` also carries `IDENTITY_<NAME>_INDEX` / `INDEX_<NAME>_INDEX`, while `identity.primary` deliberately carries no index member (migrate names a PK by a dialect-conditional formula this artifact must not restate). **There is no `READ_ONLY`** — it was a derivation over `@kind`, never metadata, so ask `SOURCE_<ROLE>_KIND`. Emitted for every object with a declared or inherited primary source, PLUS a fragment for any abstract base such an object extends (columns only, no source). A class whose object extends another one **extends** it (`class CopayAuthNames extends AuthNames`) rather than restating its constants — Java inherits static members, so `CopayAuthNames.SOURCE_PRIMARY_TABLE` and `CopayAuthNames.ID_COLUMN` both resolve through the base. **This port generates no SQL** (the repository is an interface you implement), so nothing generated consumes these — they exist for your implementation. |
 | `JavaObjectCodeGenerator` | module `metaobjects-codegen-base` (`com.metaobjects.generator.direct.object.javacode`), a separate module from the Spring generators above. Flavor-selected via the `flavor` generator arg. `flavor=pojoAware` → `class <Name> extends PojoObject` (a concrete `MetaObjectAware` class with a `(MetaObject)` constructor) — its inherited `getMetaData()` back-reference is what breaks a default Jackson/Gson mapper, see "Serializing generated objects" below. `flavor=valueObject` → `class <Name> extends ValueObject` (map-backed; less hostile to a default mapper, but still not the sanctioned serialization path). Either concrete flavor also emits a `<Name>Extractor` plus a self-registering `ObjectClassBindingProvider`. For a plain default-Jackson-friendly type, use the `codegen-spring` record surface instead — never `pojoAware`. |
 
 **Projections (read-only views).** An `object.projection` (read-only `source.rdb`

package/agent-context/skills/metaobjects-codegen/references/kotlin.md

@@ -120,6 +120,7 @@ All live in `metaobjects-codegen-kotlin` under
 | `KotlinRenderHelperGenerator` | the typed render helper for a `template.prompt` payload |
 | `KotlinValidatorGenerator` | `MetadataStartupValidator.kt` + `ExposedTableValidator.kt` (once per project) |
 | `KotlinSpringConfigGenerator` | `MetadataExposedConfig.kt` — `@Configuration` wiring `Database.connect()` + the startup validator (once per project) |
+| `KotlinNamesGenerator` | `<Entity>Names.kt` — an `object` of `const val` names that MIRRORS THE METADATA TREE. Every node carries its own `TYPE`/`SUB_TYPE`/`NAME`, so `AuthorNames.NAME` is the OBJECT's name (`"Author"`), **not** a table name, and a physical name sits under the member that says what it is: `SOURCE_<ROLE>_TABLE` / `_VIEW` / `_MATERIALIZED_VIEW` / `_PROC` / `_FUNCTION`, from the metamodel's own `@kind`-to-alias map, with `<ROLE>` being `PRIMARY` or `REPLICA` (a write-through entity has a member for each). Plus a `<FIELD>_FIELD`/`<FIELD>_COLUMN` pair per field and a complete `COLUMNS_BY_FIELD`; an `identity.secondary` or `index.lookup` also carries `IDENTITY_<NAME>_INDEX` / `INDEX_<NAME>_INDEX`, while `identity.primary` deliberately carries no index member (migrate names a PK by a dialect-conditional formula this artifact must not restate). **There is no `READ_ONLY`** — it was a derivation over `@kind`, never metadata, so ask `SOURCE_<ROLE>_KIND`. Emitted for every object with a declared or inherited primary source, PLUS a fragment for any abstract base such an object extends (columns only, no source). Kotlin has no static inheritance — an `object` cannot extend another — so an artifact whose object extends another **re-exports** the parent's constants by reference (`const val SOURCE_PRIMARY_TABLE: String = AuthNames.SOURCE_PRIMARY_TABLE`) instead of restating the literal. Wire it alongside `KotlinExposedTableGenerator`: the Maven plugin then turns the table binding's constant substitution ON automatically (`AuthorTable : Table(AuthorNames.SOURCE_PRIMARY_TABLE)`); a run without it keeps the literals, so the output still compiles. |
 | `KotlinStoredProcGenerator` | stored-procedure call wrappers for `source.rdb` `@kind="storedProc"` |
 | `KotlinFilterAllowlistGenerator` | per-entity filter allowlist |
 

package/agent-context/skills/metaobjects-codegen/references/python.md

@@ -61,6 +61,7 @@ a renamed physical column).
 | `routes` | a **FastAPI `APIRouter`** per writable entity (`source.rdb @kind="table"`) on the cross-port REST contract (`?filter[field][op]=`, `?sort=field:asc`, `?limit`/`?offset`, `?withCount=1` envelope, 400/404 envelopes). The router declares a repository **`Protocol`** you implement and inject. A TPH `@discriminator` base emits ONE polymorphic router: `GET /<base>(+/{id})` plus a per-subtype CRUD set at `/<base>/<discriminatorValue lowercased>` — create injects the discriminator from the URL (never the body); get/update/delete scoped to the subtype (cross-subtype → 404); discriminator immutable. Its repository `Protocol` is subtype-keyed (`subtype=None` for the polymorphic base) so your implementation applies the single-table discriminator scope. |
 | `filter-allowlist` | per-entity filter allowlist (FR-009 — the server-side field+operator allowlist the routes validate against). |
 | `payload` / `output-parser` / `output-prompt` / `extractor` / `render-helper` / `trace-helper` | the prompt-pillar artifacts for a **responding `template.prompt`** — one carrying `@responseRef` (ADR-0052: these tiers are INBOUND; `template.output` is outbound only and emits no parser). The payload VO, the strict parser (`<template>_response_parser`), the **output-format prompt fragment** (`<template>_response_format`; presentation via `@promptStyle: guide`/`inline`/`exampleOnly`), the tolerant `extract`, the typed render helper, and the LLM-trace helper. See the **prompts** reference. |
+| `names` | `<entity_snake>_names.py` — module-level `Final` constants mirroring the object's metadata tree. Every node carries its own `_TYPE`/`_SUB_TYPE`/`_NAME`; `<ENTITY>_NAME` is the OBJECT's name, and a physical name sits under the member naming what it is: `<ENTITY>_SOURCE_<ROLE>_{TABLE,VIEW,MATERIALIZED_VIEW,PROC,FUNCTION}` (`<ROLE>` is `PRIMARY` or `REPLICA`, so a write-through entity's read view has a slot), plus `<ENTITY>_SOURCE_<ROLE>_{KIND,SCHEMA}`, a `<ENTITY>_<FIELD>_FIELD`/`_COLUMN` pair each, `<ENTITY>_IDENTITY_<NAME>_*` / `<ENTITY>_INDEX_<NAME>_*` carrying `_INDEX` (the database index name) for `identity.secondary` and `index.lookup`, and a complete `<ENTITY>_COLUMNS_BY_FIELD`. No `_READ_ONLY` — it was derived from `@kind`, never declared; ask `_SOURCE_<ROLE>_KIND`. Emitted for every object with a declared or inherited primary source, PLUS a fragment for any abstract base such an object extends (columns and keys only, no `_SOURCE_*` — it has no table and must never acquire one). Python has no static inheritance, so a module whose object extends another **imports and re-exports** the parent's constants (`AUTHOR_CREATED_AT_COLUMN: Final[str] = BASEENTITY_CREATED_AT_COLUMN`) instead of restating the literal; a TPH subtype re-exports `_SOURCE_PRIMARY_*` too, since it shares its base's table. **This port generates no SQL**, so nothing generated consumes these — they exist for the repository `Protocol` implementation you write. |
 | `template` | the generic Mustache `template` primitive. |
 
 **Projections + entity read-views.** An `object.projection` (read-only `source.rdb`

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

@@ -8,9 +8,11 @@ packages. Codegen runs through the Node `meta` CLI (`@metaobjectsdev/cli`, binar
 - Install
 - `metaobjects.config.ts`
 - The generators
+- Declarative template-codegen (Mustache)
 - Run
 - Multiple output targets
 - Field subtype → column mapping
+- Retargeting to another framework — the TypeScript procedure
 
 ## Install
 
@@ -43,6 +45,7 @@ import { tanstackQuery, tanstackGrid } from "@metaobjectsdev/codegen-ts-tanstack
 export default defineConfig({
   outDir: "src/generated",
   dialect: "postgres",                 // "postgres" | "sqlite" | "d1" (D1 is TS-only)
+  extStyle: "js",                      // "js" (default) for Node ESM / plain tsc; "none" for a bundler-resolution toolchain — see SKILL.md "Your framework isn't the default"
   apiPrefix: "/api",                   // flows to routes AND client fetch URLs
   columnNamingStrategy: "snake_case",  // "snake_case" (default) | "literal" | "kebab-case"
   timestampMode: "string",             // "string" (default, ISO-8601 wire contract) | "date" (Drizzle native Date)
@@ -80,7 +83,10 @@ PROJECT ROOT that CONTAINS the metadata — never the metadata directory itself.
 
 ## The generators
 
-From `@metaobjectsdev/codegen-ts/generators` (server-side, framework-neutral):
+Server-side, framework-neutral. The first four are **scaffolded into your repo** by
+`meta init` and imported from `./codegen/generators/*` (ADR-0034); the rest come from the
+package main entry, `@metaobjectsdev/codegen-ts`. Do **not** import any of them from
+`@metaobjectsdev/codegen-ts/generators` — that subpath is deprecated and removed at 1.0.
 
 | Generator | Emits per entity |
 |---|---|
@@ -91,6 +97,7 @@ From `@metaobjectsdev/codegen-ts/generators` (server-side, framework-neutral):
 | `promptRender()` | `render<Name>()` per `template.prompt` |
 | `outputParser()` | `<Name>.response.ts` (`parse*` / `safeParse*`) per **responding `template.prompt`** — one carrying `@responseRef` (ADR-0052: this tier is INBOUND; `template.output` is outbound only and emits nothing here). Siblings: `outputPrompt()` → `<Name>.responseFormat.ts` (the FR-010 output-format fragment, presentation via `@promptStyle`), `extractor()` → `<Name>.extractor.ts` (the tolerant `extract` mapper). |
 | `callableFile()` | `<Entity>.callable.ts` — an FR-015 `call<Entity>` wrapper for a `source.rdb` `@kind: storedProc`/`tableFunction` (args from the `@parameterRef` value object, in declaration order) |
+| `namesFile()` | `<Entity>.names.ts` — `export const <Entity>Names`, mirroring the object's metadata tree. Every node carries its own `type`/`subType`/`name`; `name` is the OBJECT's name, and a physical name sits under the key naming what it is: `sources.<role>.{table,view,materializedView,proc,function}` (`<role>` is `primary` or `replica`, so a write-through entity's read view has a slot), plus `sources.<role>.{kind,schema}`, `fields.<field>.{name,column}`, and `identities.<name>` / `indexes.<name>` carrying `.index` (the database index name) for `identity.secondary` and `index.lookup`. No `readOnly` — it was derived from `kind`, never declared. Emitted for every object with a declared or inherited primary source, PLUS a fragment for any abstract base such an object extends (columns only, `sources: {}` — it has no table and must never acquire one). An artifact whose object extends another spreads the parent's collections rather than restating them, and a TPH subtype spreads `...AuthNames.sources` too, since it shares its base's table. With this generator in the run, **no generated TypeScript spells a physical name at all** — table, view, proc, column, schema and index name all travel as references; drop it from the suite and they fall back to literals. |
 
 **Projections (read-only views).** For an `object.projection` (a read-only `source.rdb`
 `@kind: view` child), `entityFile()` emits a `pgView(...)` + read-only Zod + a read-only
@@ -178,8 +185,73 @@ From `@metaobjectsdev/codegen-ts-tanstack`: `tanstackQuery()` → `<Entity>.hook
 `tanstackGridHook()` → `<Entity>.grid.tsx`.
 
 `entityFile({ allowlists: false })` drops the `runtime-ts/drizzle-fastify` import
-for edge/worker consumers that don't mount server routes. Per-entity opt-out:
-`@emitTanstack: false` on the entity skips its hook + column files.
+for edge/worker consumers that don't mount server routes.
+
+**Wire a generator only for output you consume, and narrow it with its `filter`.**
+Every generator factory takes `{ filter?: (entity) => boolean }`, ANDed with the
+generator's built-in gates — so it can only NARROW what emits, never widen it:
+`tanstackQuery({ filter: (e) => e.name !== "InternalAudit" })` emits no hooks for
+that entity. There is no `@emit*` metadata attribute to do this — `@emitTanstack`,
+`@emitRoutes`, `@emitForm`, `@emitGrid` and `@emitAngular` were never registered
+vocabulary, so they passed `meta gen` and failed `meta verify`. If a project carries
+one, `meta upgrade --apply` removes it.
+
+The one thing a `filter` can't express is opting a TPH subtype IN to its own
+per-subtype grid (that WIDENS): `tanstackGrid({ tphSubtypeGrids: (e) => … })`,
+default `() => false`. Pass the same predicate to `tanstackGridHook()` or you get
+a `<Sub>.grid.ts` whose `<Sub>.columns.tsx` is never emitted.
+
+## Declarative template-codegen (Mustache)
+
+Everything above is the **programmatic** path. A generator can also be **declarative** —
+a Mustache template plus a scope, no generator code — and on TypeScript you have both.
+Pick a template when the output SHAPE is what you are iterating on, or when you want the
+same output across languages; pick programmatic when the logic is gnarly or the run is
+hot.
+
+**There is no `--template-spec` flag on `meta gen`.** Do not look for one and do not
+report its absence as a gap. `metaobjects.config.ts` takes generator VALUES, so a
+template generator is declared there like any other — which is also what keeps it
+visible to `meta verify --codegen`, a gate that re-runs the config's generator list.
+
+```ts
+import { templateGenerator } from "@metaobjectsdev/codegen-ts";
+
+export default defineConfig({
+  generators: [
+    entityFile(),
+    templateGenerator({
+      name: "entity-service",
+      template: "service/entity-service",   // → templates/service/entity-service.mustache
+      scope: "perEntity",                   // "perEntity" | "perPackage" | "perModel"
+      outputPattern: "{package}/{Name}Service.ts",
+    }),
+  ],
+});
+```
+
+- `template` resolves under the project's `templates/` dir first, then framework defaults.
+- `outputPattern` placeholders: `{name}`, `{Name}`, `{package}` (its `::` segments become
+  nested directories). An unknown placeholder throws.
+- `scope` and `walk` are mutually exclusive — supply exactly one. `walk` is the escape
+  hatch for a walk none of the three scopes expresses.
+- Abstract objects are excluded from every scope.
+
+**Reusing a C#/Python spec.** Those ports declare the same generators as a JSON
+template-spec because their registries are closed and the flag is their only seam. Parse
+it and spread it:
+
+```ts
+import { parseTemplateSpec, templateSpecToGenerators } from "@metaobjectsdev/codegen-ts";
+
+const spec = parseTemplateSpec(JSON.parse(readFileSync("./template-spec.json", "utf8")));
+// generators: [entityFile(), ...templateSpecToGenerators(spec)]
+```
+
+Portability runs ONE way: TS also accepts a `target` field that the CLI ports reject, so
+a spec written there always runs here, but not the reverse. Keep `target` out of a shared
+spec. The data dict a template renders against is the cross-port byte-gated contract —
+`docs/features/codegen-data-shapes.md`.
 
 ## Run
 
@@ -189,9 +261,18 @@ npx meta gen --dry-run       # preview without writing
 npx meta gen Author Post     # scope to named entities
 ```
 
-Generated files carry an `@generated by @metaobjectsdev/codegen-ts` header; the
-runner overwrites those and refuses to touch files without it. Hand-customizations
-that metadata can't express live in sibling `<Entity>.extra.ts` files.
+Generated files carry an `@generated by @metaobjectsdev/codegen-ts` header. It is
+**informational** — the write decision never reads it. `.metaobjects/.gen-state/`
+decides: the snapshot body if this machine has one (three-way merge), otherwise the
+committed `.hashes.json` (byte-for-byte what it wrote ⇒ overwrite; anything else ⇒
+refused, path named, exit 1). So the merge is machine-local: a file you edited and
+pushed is REFUSED on a fresh clone or in CI, not merged. Recovery is in
+`docs/features/own-your-codegen.md`.
+
+Hand-customizations that metadata can't express go in a sibling module you create and
+import yourself — `<Entity>.extra.ts` by convention. The name carries no tool behaviour:
+the file is safe because codegen writes only the paths it records, and the generated
+barrel (built from the model, not a directory listing) does **not** re-export it.
 
 **Output format:** `meta gen` (and the CLI generally) is TTY-aware — human-readable
 text on a terminal, TOON on a pipe or agent. Override with `--format toon|json|text`.
@@ -231,3 +312,106 @@ The VO type, its Zod `InsertSchema`, and this `.$type<>()` all import the VO fro
 the same module (layout/package/`extStyle`-aware resolution). An opaque jsonb column
 (`field.string @dbColumnType: jsonb`) gets no `.$type<>()` — it stays `unknown`,
 which is the correct shape for freeform payloads with no fixed VO.
+
+## Retargeting to another framework — the TypeScript procedure
+
+This is the TypeScript implementation of the retargeting doctrine in SKILL.md
+("Your framework isn't the default"). Read that first for the order of moves;
+everything below — `meta eject`, `metaobjects.config.ts` keys, the exported
+`render*` functions — is Node-CLI-specific and exists only on this port.
+
+The shipped reference templates emit for **Fastify on Node** (plus a Hono variant) with
+Drizzle and Zod. If that is not your stack, retargeting is the **normal first move** — not
+a workaround and not a sign of a bug. Each template's header carries a `targets:` line
+naming exactly what its emit is coupled to and which call to swap.
+
+Work the list in order; the first two cost nothing.
+
+**1. Check the target-shaped config first.** Several apparent codegen failures are one
+config value in `metaobjects.config.ts`:
+
+- **`extStyle`** — `"js"` emits `./Entity.js` specifiers, correct for Node ESM and a plain
+  `tsc` with `nodenext`. Bundlers disagree on whether they perform the TypeScript
+  `.js`→`.ts` rewrite: it fails outright under **Turbopack** — including between two
+  generated files, which makes the whole generated tree unresolvable — while Vite and
+  esbuild are documented to accept it and webpack needs `resolve.extensionAlias` to do the
+  same. **If a generated import fails to resolve, set `extStyle: "none"` and retest** for
+  your toolchain rather than assuming either setting from this list.
+- **`clientDirective`** — `true` prepends `"use client";` to the generated form, hooks,
+  columns and grid-hook modules. Defaults to `false`. **Set it if your framework compiles
+  server and client from one tree** (React Server Components — Next.js App Router and
+  friends); leave it off otherwise, where the directive is inert and some bundlers warn
+  about it.
+- **`outDir`** / **`targets`** — where output lands, per generator.
+- **`apiPrefix`**, **`dialect`** — route mounting and column mapping.
+
+**2. Ask whether your framework splits the module graph.** Some frameworks compile server
+and client from one source tree and resolve each half under *different export conditions*
+(React Server Components, Angular universal, Qwik). Where they do:
+
+- a generated artifact using client-only APIs may need a **marker directive** or a distinct
+  import path, and
+- the resulting error frequently **names a package that is installed and present** — because
+  resolution failed under the server condition, not because the dependency is missing.
+
+Read that error as a *boundary* problem, not a dependency problem. The fix belongs in the
+generator that emits the artifact, which you own.
+
+**3. If the emit is wrong for your framework, own the generator.**
+
+    meta eject --list          # every template you can take ownership of
+    meta eject form            # copies it to codegen/generators/form.ts
+
+Then compose the engine and replace only the step that differs. Every generator's renderer
+is exported, so wrapping is available — but **how much that buys you differs by tier, and
+it is worth knowing which one you are in before you start**:
+
+- **Entity module (`entity`)** — genuinely composable. `renderDrizzleSchema`,
+  `renderZodValidators`, `renderInferredTypes`, `renderFilterAllowlist` and friends are
+  separate exported sections the template assembles into a `Code[]`. Swap or drop one and
+  keep the rest.
+- **Routes and UI (`routes`, `routes-hono`, `form`, `hooks`, `grid`, `grid-hook`)** — one
+  whole-file renderer each, so "replace a step" really means wrap the whole output. That
+  is enough for a marker directive, a header, or a post-process, and it is what the RSC
+  case below needs. It is **not** enough to retarget the emitted framework: if you need
+  Svelte or Angular instead of React, you are writing a renderer, and the honest move is
+  to keep the generator's metadata walk and replace the render call entirely.
+
+**`"use client"` needs no ejecting at all — it is a config knob.** The generated form,
+hooks, columns and grid-hook modules are client components; React Server Components
+frameworks (Next.js App Router and friends) require the directive saying so. Set it once:
+
+```ts
+export default defineConfig({
+  clientDirective: true,   // prepend `"use client";` to generated client artifacts
+  // ...
+});
+```
+
+Defaults to `false`, because the directive is only *required* under RSC and is inert
+(and warned about by some bundlers) everywhere else. It is applied ahead of the
+`@generated` header, exactly once, and only to the four client artifacts — the entity
+module, the query helpers and `<Entity>.meta.ts` are untouched, since `.meta.ts` is plain
+data and in RSC the boundary is the importing component, not everything it reaches.
+
+For the general wrap-the-output case — a directive or header MetaObjects does not model:
+
+```ts
+// codegen/generators/form.ts — OWNED
+import { renderFormFile } from "@metaobjectsdev/codegen-ts-react";
+
+// ...inside generate():
+if (!ctx.renderContext) throw new Error("renderContext is required (provided by runGen)");
+const body = renderFormFile(entity, ctx.renderContext);
+return { path, content: `// @my-framework:client\n` + body };
+```
+
+You keep receiving upstream fixes to `renderFormFile` while owning the one line your
+framework cares about. **Forking the whole renderer is the thing to avoid**, not owning the
+generator.
+
+**4. Server-tier output is usually already portable.** The entity module (a table plus
+validation schemas) and the query helpers (which take `db` as a parameter rather than
+importing a singleton) carry no HTTP-framework coupling — a server-rendered component can
+call a generated query directly. Retargeting is usually only needed at the routes and UI
+tiers.

package/agent-context/skills/metaobjects-prompts/references/typescript.md

@@ -22,7 +22,16 @@ provider/LLM-call layer — you compose the call yourself.
 ```ts
 // metaobjects.config.ts
 import { defineConfig } from "@metaobjectsdev/cli";
-import { entityFile, queriesFile, barrel, promptRender, outputParser } from "@metaobjectsdev/codegen-ts/generators";
+// The entity trio + barrel come from the OWNED copies `meta init` scaffolded into
+// ./codegen/generators/ (ADR-0034). Importing them from the package instead is the
+// deprecated path, and quietly hands their shape back to the package — so keep these
+// lines as `meta init` wrote them and add only the prompt pair below.
+import { entityFile } from "./codegen/generators/entity.js";
+import { queriesFile } from "./codegen/generators/queries.js";
+import { barrel } from "./codegen/generators/barrel.js";
+// promptRender / outputParser are NOT in the ownable set — the render and parse engines
+// are upstream-owned, so importing them from the package is the supported pattern.
+import { promptRender, outputParser } from "@metaobjectsdev/codegen-ts/generators";
 
 export default defineConfig({
   outDir: "src/generated",