@metaobjectsdev/sdk 0.24.4 → 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.