@metaobjectsdev/sdk 0.24.5 → 0.25.0

package/README.md

@@ -1,6 +1,6 @@
 # @metaobjectsdev/sdk
 
-Programmatic SDK for MetaObjects: workspace memory records, path resolution, project config loading, and the agent-docs reference content. Consumed by the `meta` CLI and by AI-collaboration tooling (MCP exposers, codegen prompts).
+Programmatic SDK for MetaObjects: workspace memory records, path resolution, and project config loading. Consumed by the `meta` CLI and by AI-collaboration tooling (MCP exposers, codegen prompts).
 
 ## Install
 
@@ -17,12 +17,6 @@ const metaRoot = await resolveMetaRoot(process.cwd());
 const config = await loadConfig(metaRoot);
 ```
 
-The canonical agent reference docs (scaffolded by `meta init`) are available via a sub-path:
-
-```ts
-import { AGENT_DOCS_BODY, withContentHash } from "@metaobjectsdev/sdk/agent-docs";
-```
-
 ## agent-context
 
 `@metaobjectsdev/sdk/agent-context` assembles the downstream AI-assistant context

package/agent-context/servers/csharp.meta.json

@@ -1,5 +1,7 @@
 {
   "displayName": "C#",
   "install": "install the MetaObjects .NET tool (dotnet tool install) + add the MetaObjects.Codegen package",
-  "codegenCommand": "dotnet meta gen"
+  "codegenCommand": "dotnet meta gen",
+  "docsCommand": "dotnet meta docs",
+  "apiSubDir": "api/csharp"
 }

package/agent-context/servers/java.meta.json

@@ -1,5 +1,7 @@
 {
   "displayName": "Java",
   "install": "add com.metaobjects:metaobjects-metadata + metaobjects-codegen-spring + metaobjects-maven-plugin to your pom.xml",
-  "codegenCommand": "mvn metaobjects:generate"
+  "codegenCommand": "mvn metaobjects:generate",
+  "docsCommand": "mvn metaobjects:docs",
+  "apiSubDir": "api/java"
 }

package/agent-context/servers/kotlin.meta.json

@@ -1,5 +1,7 @@
 {
   "displayName": "Kotlin",
   "install": "add com.metaobjects:metaobjects-codegen-kotlin + metaobjects-metadata-ktx + metaobjects-maven-plugin to your pom.xml",
-  "codegenCommand": "mvn metaobjects:generate"
+  "codegenCommand": "mvn metaobjects:generate",
+  "docsCommand": "mvn metaobjects:docs",
+  "apiSubDir": "api/kotlin"
 }

package/agent-context/servers/python.meta.json

@@ -1,5 +1,7 @@
 {
   "displayName": "Python",
   "install": "pip install metaobjects",
-  "codegenCommand": "metaobjects gen"
+  "codegenCommand": "metaobjects gen",
+  "docsCommand": "metaobjects docs",
+  "apiSubDir": "api/python"
 }

package/agent-context/servers/typescript.meta.json

@@ -1,5 +1,7 @@
 {
   "displayName": "TypeScript",
   "install": "npm install -D @metaobjectsdev/cli @metaobjectsdev/codegen-ts",
-  "codegenCommand": "npx meta gen"
+  "codegenCommand": "npx meta gen",
+  "docsCommand": "npx meta docs",
+  "apiSubDir": "api"
 }

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

@@ -118,19 +118,25 @@ code behind a grep hit; a "duplicate" validator's *divergence* is the finding.
     references repo-wide (grep the emitted symbol / module path for importers):
     delete it and stop generating it.
   - **Artifacts an entity doesn't need** — REST routes / TanStack grids / forms /
-    hooks emitted for an entity that has no such surface. The per-entity opt-outs
-    exist for exactly this (`@emitRoutes: false`, `@emitTanstack: false`, a
-    `layout.dataGrid`-gated grid): flag the opt-out NOT used where the artifact is
-    unused.
+    hooks emitted for an entity that has no such surface. The remedy is the
+    generator's own `filter` option (`routesFile({ filter: (e) => e.name !== "Audit" })`,
+    `tanstackQuery({ filter })`), which is ANDed with the generator's built-in gates
+    and so can only NARROW what emits; a grid additionally needs a `layout.dataGrid`
+    on the entity at all. Flag the unused artifact and name the filter that would
+    suppress it. **Never recommend an `@emit*` attribute** — `@emitRoutes`,
+    `@emitTanstack`, `@emitForm`, `@emitGrid` and `@emitAngular` were never
+    registered vocabulary, so they passed `meta gen` (open load) and FAILED
+    `meta verify` (strict). A project carrying one is a **finding**, not an opt-out:
+    report it and route to `meta upgrade --apply` plus the generator config above.
   - **Generators wired but unconsumed** — a generator in `metaobjects.config.ts`
     `generators: [...]` (or the per-port equivalent) whose whole output class no
     code imports: drop the generator rather than generate into the void.
   - **Wrong target / duplicate output** — the same logical artifact emitted to two
     places (a mis-set per-target `outDir`), one of which is orphaned.
-  Recommend generating ONLY what is consumed — narrow the generator set + use the
-  per-entity opt-outs. A smaller, fully-consumed generated surface beats a large one
-  with dead files (which also make the leverage ratio lie; discount them from the
-  census).
+  Recommend generating ONLY what is consumed — decide per generator: drop the ones
+  whose whole output class nothing imports, and narrow the ones that over-emit with
+  their `filter`. A smaller, fully-consumed generated surface beats a large one with
+  dead files (which also make the leverage ratio lie; discount them from the census).
 - [ ] **G. Runtime-contract anti-patterns.** Module-global `db` vs context-as-parameter
   (ADR-0008); wire-canonicalization in the query path vs native in-process return types
   (ADR-0019); runtime reflection to resolve a type from FQN vs generated static imports /
@@ -331,6 +337,7 @@ Per finding: `file:line` → what → generated-equivalent exists? → recommend
    - **Not expressible → carry it in `@sql` or `@unmanaged`, never a hand-edited migration (#208, ADR-0043).** When a NAMED irreducible construct blocks origin authoring — recursive CTE, window function / `OVER`, `UNION` / `INTERSECT` / `EXCEPT`, lateral join — the body still belongs in the metadata: carry the hand-written SQL in the `source.rdb` **`@sql`** escape — a read-only-`@kind` body the tool REGISTERS, fingerprints, and drift-checks (adopt a pre-existing view with `meta migrate --allow adopt-view`); `@sql` forbids `origin.*` children (two sources of truth). A DB object whose DDL is owned **entirely elsewhere** (Flyway / a hand-migration) → mark its source **`@unmanaged: true`** (legal on any `@kind` incl. `table`); `meta migrate` never creates/drops/drift-checks it and `verify --db` reports it as external. `@sql` and `@unmanaged` are mutually exclusive. **Only a view left *undeclared*** — neither modeled, nor `@sql`, nor `@unmanaged` — is truly *unmanaged*, invisible to `meta verify --db`, so this audit is the only gate that sees it. "It's an aggregation" is NOT an irreducibility justification (plain count/sum/avg/min/max rollups are `origin.aggregate`); nor is a `DISTINCT ON` pick-one-row (`origin.first`) or a non-aggregate expression column (`origin.computed`).
 9. **A closed variant-set hand-modeled per instance** — N sibling modules / classes / config blocks, one per channel / provider / target, sharing a payload + config shape and diverging only by transport. Grep for sibling-file families and switch-on-a-string dispatch; verify the set is closed and recurring (never a one-off). → axis I "New-vocabulary OPPORTUNITY" (VOCAB CANDIDATE, advisory).
 10. **N declarations of one FIELD across objects (same-name-field census)** — the field-level sibling of signature 6. Census field names across `object.*` nodes (`grep -rn 'name: <field>'` the metadata dir); a name recurring in ≥2 objects where a canonical owner exists — one whose name the field embeds (`<owner><Field>`: `wizardId` → `Wizard.id`, `orderTotal` → `Order.total`) or whose type+constraints it matches — is provenance loss → `extends: Owner.field` (dotted child targets, ADR-0029). **VERIFY by diffing the copies' attrs: a `@maxLength` / `@required` / validator divergence across them is drift already shipping — cite it.** Evidence multiplier: `extends` already used elsewhere in the repo raises confidence. Do NOT flag: generic names on unrelated concepts (`id` / `name` / `status` with no owner-embedding name and no matching constraints); required per-node attrs a loader forces (e.g. `payloadRef` / `format` on sibling `template.prompt` nodes — a product constraint, not a copy).
+11. **A physical table / column / schema name spelled as a literal outside its metadata declaration** — in a hand-written repository, raw SQL, a migration script, a log line, or a hand-maintained body-to-column map. Every port emits a per-object names artifact (`<Entity>Names` / `<entity_snake>_names.py`) from the declaration, so a literal is a second spelling of the same fact; and because the physical column is free-form, deriving it from the field name is a guess that fails silently. **No verify subverb sees this** — `--codegen` diffs generated files, `--db` compares schema to metadata — so this audit is the only gate. Remedy: reference the constant; on the JVM the names generator is opt-in, so an un-wired pom is the first finding and wiring `SpringNamesGenerator` / `KotlinNamesGenerator` the first remedy. **Do NOT flag:** a typed ORM handle in its place (a Drizzle column object, an Exposed `Column`, an EF property — replacing one with a string is a regression); a physical name inside a `source.rdb` hand-written SQL body (a metadata document cannot import a constant, which is why that body is fingerprinted); a flattened value-object composite column (it belongs to no single field of either object); a write-through entity's replica view name (the artifact holds the PRIMARY source's); a relationship-synthesized foreign-key column (derived, never declared). A hand-written repository that imports `<Entity>Names` is the gold standard — call it out as good.
 
 ---
 

package/agent-context/skills/metaobjects-audit/references/capability-checklist.md

@@ -66,7 +66,12 @@ classify it (using the classification scheme in `SKILL.md`) and route the cutove
 ## Source — `source.rdb`
 
 - **`source.rdb`** (`@table`, `@schema`) — hunt hard-coded physical table/schema names that
-  diverge from the default naming the source models.
+  diverge from the default naming the source models, AND any physical table/column/schema
+  name spelled as a literal outside its declaration — raw SQL, a hand-written repository, a
+  migration script, a body-to-column map (drift signature 11). Every port emits a per-object
+  names artifact from the declaration, so a literal is a second source of truth even when it
+  agrees with the naming strategy today. A typed ORM handle in its place is correct; on the
+  JVM an un-wired names generator is the finding first.
 - **`@kind` = `view` / `materializedView`** — hunt hand-written SQL views where an authored
   read-only source belongs. Apply the **view-necessity test** (SKILL.md, drift signature 8): a
   hand-written `CREATE VIEW` (or read-only SQL mirroring a read model) is a CODEGEN CANDIDATE when

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

@@ -51,6 +51,7 @@ rejected (exit 2).
 | `FromSqlInterpolated(` outside `.g.cs` | stored-proc call — candidate for the `callable` generator |
 | `// keep in sync with` / `// mirrors the` | second-source-of-truth comment — always a finding |
 | `HasPrecision(` hand-coded | `field.decimal` with `@precision`/`@scale` drives this from the `entity` generator |
+| a table/column string in raw-SQL EF calls, or `nameof(Entity.Prop)` standing in for a column | second spelling of a declared physical name — reference `<Entity>Names.g.cs` (`AuthorNames.SourcePrimaryTable` / `<Field>Column`, default suite — `Names.Name` is the OBJECT's name, not the table); an EF property inside LINQ is the typed handle — correct |
 
 ---
 
@@ -59,7 +60,15 @@ rejected (exit 2).
 C# does not scaffold-and-own generators — the generators are provided by
 `MetaObjects.Codegen` and are not meant to be copied into the consumer project.
 There is no analog to the TS `codegen/generators/*.ts` pattern here. Generator
-selection uses stable names via `dotnet meta gen --generators <names>`.
+selection uses stable names via `dotnet meta gen --generators <names>`, over a
+**closed built-in registry** — there is no seam to register a generator of your own.
+
+**So do not score a C# project down for "not owning its generators", and do not
+recommend writing one.** The customization path here is the **declarative template**:
+`dotnet meta gen --template-spec <json> --template-root <dir>`, whose entries append to
+the default suite. A finding of the form "the built-ins do not emit the shape this
+project needs" resolves to a template-spec, not to generator code. Worked example with
+the full JSON: `docs/ports/csharp.md`.
 
 To re-scaffold the agent-context into a C# project, use the Node `meta` CLI (the
 single agent-docs assembler per ADR-0033):

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

@@ -51,6 +51,7 @@ plugin `<configuration>` — that is the source of truth for which generators ru
 | `// keep in sync with` / `// mirrors the` | second-source-of-truth comment — always a finding |
 | `ObjectMapper.readValue(` outside a `*Parser.java` file | check if a responding `template.prompt` (`@responseRef`) exists — output-parser codegen ships in Java |
 | `LIMIT ?` / `OFFSET ?` assembled by hand | generated CRUD routes handle pagination; OMDB `getObjects` accepts `QueryOptions` |
+| a table/column string in a repository implementation — JDBC SQL, jOOQ `table("authors")`, a Spring Data query | second spelling of a declared physical name — reference `<Entity>Names` (`AuthorNames.SOURCE_PRIMARY_TABLE` / `_COLUMN`; opt-in `SpringNamesGenerator`): an un-wired generator is the finding first |
 
 ---
 
@@ -60,6 +61,15 @@ Java does not scaffold-and-own generators — they are provided by
 `metaobjects-codegen-spring` and wired by FQ class name in `pom.xml`. There is no
 analog to the TS `codegen/generators/*.ts` pattern here.
 
+Java does, however, have **both** authoring paths, so a project needing a shape the
+built-ins do not emit has two legitimate answers and neither is a finding on its own:
+a **programmatic** generator (implement `com.metaobjects.generator.Generator`, name the
+class in a `<generator>` element — the plugin loads it from the project classpath), or a
+**declarative template** (`TemplateScopeGenerator`, wired with `<template>` / `<scope>` /
+`<outputPattern>` / `<format>` / `<templatesDir>`). Prefer the template when the output
+SHAPE is the thing being iterated on or the same output is wanted in another language;
+prefer code when the logic is gnarly. See `docs/features/codegen-concepts.md` §3.
+
 To re-scaffold the agent-context into a Java project, use the Node `meta` CLI (the
 single agent-docs assembler per ADR-0033):
 

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

@@ -56,6 +56,7 @@ The active generator list is declared in `pom.xml` under the plugin `<configurat
 | `@Serializable` on a payload class not in generated sources | `KotlinPayloadGenerator` should own this; check `pom.xml` generator list |
 | `// keep in sync with` / `// mirrors the` | second-source-of-truth comment — always a finding |
 | `transaction(db) {` bodies that duplicate every CRUD operation | hand-written Exposed transactions are expected (see Calibration), but if they duplicate generated-CRUD logic exactly, audit further |
+| a table/column string in `exec("…")` raw SQL or a Flyway script | reference `<Entity>Names` (`KotlinNamesGenerator`, opt-in); `AuthorTable.name` inside the Exposed DSL is the typed handle — correct, not a finding |
 
 ---
 
@@ -65,6 +66,16 @@ Kotlin does not scaffold-and-own generators — they are provided by
 `metaobjects-codegen-kotlin` and wired by FQ class name in `pom.xml`. There is no
 analog to the TS `codegen/generators/*.ts` pattern here.
 
+Kotlin does, however, have **both** authoring paths — it shares the JVM engine — so a
+project needing a shape the built-ins do not emit has two legitimate answers and neither
+is a finding on its own: a **programmatic** generator (implement
+`com.metaobjects.generator.Generator`, name the class in a `<generator>` element), or a
+**declarative template** (`TemplateScopeGenerator`, wired with `<template>` / `<scope>` /
+`<outputPattern>` / `<format>` / `<templatesDir>` — no KotlinPoet involved). Prefer the
+template when the output SHAPE is the thing being iterated on or the same output is
+wanted in another language; prefer code when the logic is gnarly. See
+`docs/features/codegen-concepts.md` §3.
+
 To re-scaffold the agent-context into a Kotlin project, use the Node `meta` CLI (the
 single agent-docs assembler per ADR-0033):
 

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

@@ -52,14 +52,24 @@ regardless of server language — see the migration reference.
 | `def get_all_` / `def create_` / `def update_` / `def delete_` in non-generated files | hand-rolled CRUD — compare to the generated router |
 | `# keep in sync with` / `# mirrors the` | second-source-of-truth comment — always a finding |
 | `try: ... except KeyError` / `?? ''` around format strings in prompt code | silent-degradation hack around a prompt payload — flag it |
+| a table/column string in the repository implementation (SQLAlchemy Core, asyncpg/psycopg SQL) | second spelling of a declared physical name — reference `<entity>_names.py` (`AUTHOR_SOURCE_PRIMARY_TABLE` / `AUTHOR_<FIELD>_COLUMN`, default suite); no typed handle exists on this port, so that is never the reason to waive it |
 
 ---
 
 ## Owned generators
 
 Python does not scaffold-and-own generators — they are provided by the `metaobjects`
-package and selected by stable name via `--generators`. There is no analog to the
-TS `codegen/generators/*.ts` pattern here.
+package and selected by stable name via `--generators`, over a **closed built-in
+registry**. There is no analog to the TS `codegen/generators/*.ts` pattern here, and no
+seam to register a generator of your own. (`--provider module:symbol` registers
+**metamodel vocabulary**, not a generator — do not read it as one.)
+
+**So do not score a Python project down for "not owning its generators", and do not
+recommend writing one.** The customization path here is the **declarative template**:
+`metaobjects gen --template-spec <json> --templates <dir>`, whose entries append to the
+default suite. A finding of the form "the built-ins do not emit the shape this project
+needs" resolves to a template-spec, not to generator code. Worked example with the full
+JSON: `docs/ports/python.md`.
 
 To re-scaffold the agent-context into a Python project, use the Node `meta` CLI (the
 single agent-docs assembler per ADR-0033):

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

@@ -14,8 +14,12 @@ Generated files carry the header:
 // @generated by @metaobjectsdev/codegen-ts
 ```
 
-The runner **only overwrites files bearing this header** — hand-edited sibling
-files (`<Entity>.extra.ts`) are never touched. Locate generated output at the
+The header is **informational on this port** — the write decision never reads it. What
+the runner overwrites is decided by `.metaobjects/.gen-state/`: the snapshot body if the
+machine has one (three-way merge), otherwise the committed `.hashes.json` (byte-for-byte
+what it wrote ⇒ overwrite; anything else ⇒ refused, exit 1). A sibling file you created
+(`<Entity>.extra.ts` by convention) is never touched because it is not a path the runner
+records — not because of its name, and not because of the header. Locate generated output at the
 `outDir` (and per-target `outDir` values) declared in `metaobjects.config.ts`. With
 the default single-target config, generated files land at the one configured
 `outDir` (e.g. `src/generated/`).
@@ -50,6 +54,7 @@ value-sets against the constructs that replace them.
 | `// keep in sync with` / `// mirrors the` | second-source-of-truth comment — always a finding |
 | camelCase↔snake_case mapping tables | generated views handle this; diff field by field |
 | `@generated` file with hand edits | three-way merge preserves them; review at codegen; never delete |
+| a table/column string in a `sql` fragment, a Kysely identifier, or a migration/seed script outside the generated dir | second spelling of a declared physical name — reference `<Entity>.names.ts` (`ProgramNames.fields.<f>.column`); a Drizzle column object in its place is correct, not a finding |
 
 ---
 

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

@@ -49,10 +49,19 @@ aggregate — that is almost always **metadata you have not declared yet.** In o
 1. **Search the vocabulary** — `meta types <term>`, or `meta types --all
    <what-it-does>` to search by behavior. There are field subtypes, relationships,
    projections, origins, identities, sources, and attributes you may not know exist.
-   Find the construct that models it.
+   Find the construct that models it. Add `--detail` for one construct's valid
+   `@attrs`, or `--format json` for the same answer as one machine-readable document
+   — that form carries every match (`--limit` never truncates it) with each attr's
+   `allowedValues`, so you read the accepted values rather than guessing them.
 2. **Declare it and generate** — then *consume* the generated query/type/route;
    never reimplement it alongside.
-3. **Only if no construct can express it** — and you have actually looked —
+3. **If the model is right but the generated OUTPUT is wrong, change your generator.**
+   Naming, file layout, imports, framework, signatures are generator concerns, not
+   reasons to hand-write. The generators are in *your* repo and are yours to edit — a
+   standing rule not to change the MetaObjects repo does not reach them; they are a
+   different repository. Editing one is ordinary work, not an escalation. (See
+   `metaobjects-codegen` → "Your generators are yours".)
+4. **Only if no construct can express it** — and you have actually looked —
    hand-write it, wired to generated types. Business algorithms, external
    integrations, and bespoke interactions are legitimately hand-written; CRUD,
    validation, finders, relationships, and derived/aggregate data are not.
@@ -86,10 +95,20 @@ Read the existing code and schema *first*, then model to reproduce them:
 
 **Customize the CODEGEN to match the existing code before you change the existing code.**
 If generated output doesn't match the code's shape (naming, file layout, imports,
-signatures), **tune the generator/template/config to reproduce it** — that is the
-intended adoption path (owned generators, `outputPattern`, naming strategy — see the
-`metaobjects-codegen` skill), **not a hack**. Reshaping working call sites to satisfy
-the generator's defaults is the *last* resort, not the first.
+signatures), **tune the generator/template/config to reproduce it** — naming strategy
+first, then the generator or the template. **Which lever you have depends on the port,
+so establish that before planning:** on TypeScript and the JVM you can own a generator
+outright (TS scaffolds copies into your repo; the JVM loads your class from the project
+classpath), while on C# and Python the generator registry is closed and a **Mustache
+template** is the customization path — a real one, with `scope` and `outputPattern`
+doing the walk and the file naming. The `metaobjects-codegen` skill has the per-port
+matrix and defines `outputPattern`; read it before concluding a shape is unreachable.
+**Whichever lever you get, it is yours to edit.** A standing instruction not to
+change the MetaObjects repo says nothing about your own generators or templates —
+reading it as though it did is how an adoption ends up hand-written, and it is the most
+common way this step is skipped. Editing a generator or a template here is ordinary
+adoption work: not an escalation, not a hack, and nothing to ask permission for. Reshaping working call sites to satisfy the
+generator's defaults is the *last* resort, not the first.
 
 **Minimize churn to code the generator is not replacing.** The ONLY existing code that
 should change is the hand-written layer codegen now **owns** (the hand-rolled
@@ -743,6 +762,16 @@ Multi-source: multiple `source.rdb` children, each with a `@role`, exactly one
 { "source.rdb": { "@kind": "view", "@view": "v_author", "@schema": "blog" } }
 ```
 
+**This declaration is the only place a physical name is ever spelled.** Codegen emits a
+per-object names artifact from it (`<Entity>Names` — `ProgramNames.fields.createdAt.column`,
+`ProgramNames.CreatedAtColumn`, `PROGRAM_CREATED_AT_COLUMN`, per port), the generated table
+binding reads that artifact, and hand-written SQL, repositories and migration scripts
+reference it — so a consumer never restates `v_author` or `created_at`, and a rename here
+propagates. Declare `@column` explicitly whenever the physical name is not the naming
+strategy's answer (`callPurpose` → `purpose_code`): nothing downstream can recover that
+mapping by derivation, and the constant is what carries it. (See `metaobjects-codegen` →
+"Never hand-write a physical name".)
+
 **An entity's PRIMARY source must be writable** (`table`) — read-only kinds are
 legal only in non-primary roles.
 

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
@@ -271,17 +331,152 @@ 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.
 
-**The commands and config keys that implement the steps above differ per port, and the
-ports differ in how much is written down.** TypeScript has the whole procedure as a
-documented one — `meta eject`, the `metaobjects.config.ts` keys, the exported `render*`
-functions — in this skill's `references/typescript.md`. **The other ports have no eject
-command.** There, owning a generator means implementing that port's generator interface
-— `com.metaobjects.generator.Generator` (Java / Kotlin),
-`metaobjects.codegen.generator.Generator` (Python), `MetaObjects.Codegen.IGenerator`
-(C#) — and registering it with the build tool that runs codegen for your port. Their
-`references/` fragments document what each built-in emits, which is what you compare
-your own emit against; they do not carry a step-by-step retargeting procedure, so do
-not go looking for one.
+## 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
 

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`