@metaobjectsdev/sdk 0.13.1 → 0.14.0

package/README.md

@@ -26,7 +26,7 @@ import { AGENT_DOCS_BODY, withContentHash } from "@metaobjectsdev/sdk/agent-docs
 ## agent-context
 
 `@metaobjectsdev/sdk/agent-context` assembles the downstream AI-assistant context
-(the slim `.metaobjects/AGENTS.md`/`CLAUDE.md` + the five `metaobjects-*` Claude
+(the slim `.metaobjects/AGENTS.md`/`CLAUDE.md` + the six `metaobjects-*` Claude
 skills with only the project's language reference fragments) from the repo-root
 `agent-context/` source tree. `makeStack`/`detectStack` resolve the project's
 server+client axes; `assemble({ contentRoot, stack })` emits the files. Design:

package/agent-context/README.md

@@ -2,7 +2,7 @@
 
 This tree is the single source the assembler (`@metaobjectsdev/sdk`,
 `src/agent-context/`) turns into the files scaffolded into a consumer project:
-the slim always-on Markdown (`.metaobjects/AGENTS.md` + `CLAUDE.md`) and the five
+the slim always-on Markdown (`.metaobjects/AGENTS.md` + `CLAUDE.md`) and the six
 `metaobjects-*` Claude skills (each a universal `SKILL.md` plus the
 `references/<token>.md` fragments matching the project's resolved stack).
 

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

@@ -0,0 +1,262 @@
+---
+name: metaobjects-audit
+description: Use when assessing how well a project has adopted MetaObjects — greenfield first-pass or deep double-check; produces a scored, prioritized adoption-audit report covering codegen, runtime, drift-gates, and prompts.
+---
+
+# MetaObjects adoption audit
+
+**Thesis.** Typed metadata is the durable spine; generated code is the disposable
+artifact. Hand-writing a layer the metadata could own creates a second source of
+truth for one fact — it will drift. This audit hunts those second sources of truth
+and proposes folding them into the spine.
+
+**Boundary — read-only.** Deliverables: `.metaobjects/adoption-audit.json` (machine-readable
+findings) + a rendered Markdown report. The audit **never edits code, never authors
+metadata** — `metadata_sketch` per finding is a read-only proposal for human review.
+Actual cutovers run through the existing skills mapped per finding tier (§ Bridge).
+
+---
+
+## Phase 0 — Triage (fast, mechanical)
+
+- [ ] MetaObjects present? (`metaobjects/` dir, metadata sources, `@metaobjectsdev/*` /
+  `com.metaobjects:*` / `metaobjects` / `MetaObjects.*` deps).
+- [ ] Count metadata source lines + all `@generated` / `DO NOT EDIT` files repo-wide.
+- [ ] **Owned-generators check:** does the project own generators at `codegen/generators/*`
+  (scaffold-and-own via `meta init`), or still import the **deprecated** package export
+  (`@metaobjectsdev/codegen-ts/generators`)? Not owning is itself a finding.
+- [ ] Classify: **Greenfield** (none/minimal) · **Partial** · **Deep** → choose path below.
+
+---
+
+## Phase 1a — Greenfield path
+
+- [ ] **Shape inventory.** Catalog modelable shapes: entities/tables, DTOs, validation
+  schemas, routes, UI lists/forms, prompt sites.
+- [ ] **Pick wedge:** one real entity (single-column PK, standard CRUD) to model first.
+- [ ] **From-zero roadmap:** `meta init` → model the wedge → `meta gen` the data layer →
+  author a projection view → expand to routes/UI → add prompt pillar where LLM calls exist.
+  Owning the generators from day 1 is part of the roadmap.
+
+## Phase 1b — Partial / Deep path
+
+**Census:** generated output line/file counts + metadata/owned-generator lines.
+Compute **leverage ratio** = `generated_lines / (metadata_lines + generator_lines)`;
+healthy = multi-× (example: ~4.7k spine → ~15.7k generated ≈ 3.3×).
+
+**Coverage matrix:** per entity/projection/value — query helpers? view? routes? UI?
+The gap between "modeled + query helpers" and "has view + route + UI" is the headline
+lopsidedness.
+
+**Surface review — 8 axes (independently runnable).**
+Work the full `references/capability-checklist.md` on every axis. Check calibration
+guards (§ Calibration) before raising a finding. **Verify, don't assume** — read the
+code behind a grep hit; a "duplicate" validator's *divergence* is the finding.
+
+- [ ] **A. Codegen candidates — API / server routes.** Catalog + classify every handler.
+- [ ] **B. Codegen candidates — web / client.** Pages, data layer (hooks, central fetch),
+  grids/forms/filters vs `layout.dataGrid` / form generators / filter-allowlist.
+- [ ] **C. Drift hotspot — validators, mappers, runtime models.** Hand validators / DTO-mappers /
+  dataclasses shadowing a generated shape. Diff field-by-field; the divergence is the bug.
+- [ ] **D. Prompt pillar.** Every LLM prompt-construction site (see § Prompt anti-patterns).
+- [ ] **E. Owned generators & scaffold-and-own** (see § Owned-codegen assessment).
+- [ ] **F. Drift-gate adoption.** Is `meta verify` wired into CI / pre-commit? Which
+  subverbs (`--codegen` / `--templates` / `--db`)? Committed-codegen freshness gate?
+  Advisories heeded? Routine `--no-verify` bypass? Loader `ERR_*` / warnings addressed?
+  Parse the stable `code` field, not message text (ADR-0009).
+- [ ] **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 /
+  FQN registry (ADR-0001 / 0017); process-global registry vs per-loader (ADR-0014); code
+  that **mutates the loaded metadata tree** (read-only after load); JVM/Kotlin missing
+  startup validator; writes not routed to the `@role: primary` source.
+- [ ] **H. Authoring-correctness / ADR-conformance (deep).** Invented/unregistered
+  `@`-attrs or post-bootstrap registration (ADR-0023 — custom attrs belong in a registered
+  provider or `attr.properties`); retired source-v2 forms (`source.dbTable` / `@name` /
+  `@dbColumn` → use `source.rdb` + `@kind` + `@table` / `@column` + `@role`, ADR-0007/0018);
+  taxonomy impurity (entity over read-only primary source; read model that should be
+  `object.projection`; `value` carrying identity/source, ADR-0028); copy-pasted base-field
+  blocks instead of abstract + `extends`; `@`-prefixed YAML keys (ADR-0006); relative refs
+  in committed canonical JSON (ADR-0032); DB-type-as-logical-subtype (ADR-0013); per-port
+  migration engine where schema is Node-`meta`-owned (ADR-0015).
+
+**Phase 4 — Synthesize** into the tiered roadmap and populate both artifacts.
+
+---
+
+## Classification scheme (every surface; classify on codegen AND runtime)
+
+| Class | Meaning | Action |
+|---|---|---|
+| **GENERATED** | Driven by metadata (regenerable). | Confirm it regenerates clean. |
+| **OWNED-GENERATOR** | `codegen/generators/*` file the project owns. | Confirm clean regen; flag drift from reference template. |
+| **CODEGEN CANDIDATE (high)** | Standard CRUD/list/form over a modeled or modelable entity. | Author the view + generate; parity-gate. |
+| **CODEGEN CANDIDATE (partial)** | Generatable data layer, bespoke presentation. | Generate data layer; keep viz hand-written. |
+| **DYNAMIC-RUNTIME CANDIDATE** | Behavior that could be metadata-driven at runtime. | Assess runtime-metadata feasibility. |
+| **BESPOKE (keep)** | Genuine custom: aggregations, graph, SSE, auth, search, viz. | Leave hand-written — still import generated types. |
+
+**Gold-standard exception.** A hand-written component that *derives* from generated metadata
+cannot drift — flag as good. A "bespoke" component hardcoding a shape metadata knows is a
+hidden candidate. **Stub trap:** demo-data routes have nothing to replace — classify
+"candidate (future) — not DB-backed".
+
+---
+
+## Drift signatures (highest-value; grep-then-verify)
+
+Per finding: `file:line` → what → generated-equivalent exists? → recommendation.
+
+1. **Hand validators shadowing a generated schema** — diff field-by-field; divergence is the bug.
+2. **Field-by-field serialize / deserialize / DTO↔model / row mappers** — silently drops a field when metadata grows one.
+3. **camelCase↔snake_case / body↔column maps** maintained beside a generated view that already renames.
+4. **Drift-admitting comments** — grep: `"keep in sync with"` / `"mirrors the"` / `"matching the"`.
+5. **Runtime schema patching** (`ALTER TABLE … ADD COLUMN IF NOT EXISTS`, `_ensure_schema()`) — N schema owners.
+6. **N declarations of one shape** — same entity as Drizzle table + Zod schema + Pydantic model + hand dataclass; target is 1 + N generated.
+
+---
+
+## Owned-codegen & scaffold-and-own assessment
+
+- If config imports deprecated `@metaobjectsdev/codegen-ts/generators` instead of
+  owned `codegen/generators/*`, recommend the scaffold-and-own migration (`meta init`).
+- Audit owned generators: (a) regenerate clean? (b) drifted from reference templates —
+  intentional (good) vs stale/accidental (missed upstream fix)? (c) hand-rolling a walk
+  that a declarative `scope` + `outputPattern` could replace? (d) bespoke shape better as
+  a `templateGenerator` than a forked generator?
+- **Authoring ladder:** built-in fits → use it · close → **own + customize** (the default)
+  · new shape → **author a declarative template-spec / custom generator from the metadata**
+  · genuinely un-modelable → hand-write (still import the generated types).
+- **Generator-gap check:** missing generators that block the biggest wins? Recommend per gap:
+  own + customize / author a template-spec / fix upstream / stopgap.
+- **Verify the DB artifact, not just the types** — computed view columns may appear in the
+  contract but be dropped from the view DDL; the contract may lie.
+- **Version skew:** check *actually-resolved* package versions, not declared; consuming a fix
+  requires a coordinated lockstep bump, not a source-file copy.
+
+---
+
+## Prompt anti-patterns (hunt per site; classify: fully-modeled / partial / fully-inline)
+
+- Inline prompt strings (triple-quoted / template-literal constants in service code).
+- Untyped payloads (`str.format(**dict)` / f-strings / ad-hoc dicts) — payload should be an
+  `object.value` with `origin.*` (`passthrough` / `aggregate` / `collection`) fields.
+- Silent-degradation hack (`try/except KeyError` or `?? ''` around formatting) — flag every instance.
+- Hand-rolled output parsing (regex / XML / ad-hoc JSON) vs declared `template.output` +
+  generated `parse*` / `safeParse*` / `extract*` parser. **Java hand-writes the Jackson
+  one-liner — do NOT flag it** (§ Calibration).
+- Engine-side formatting breaking byte-identical render (prompt-cache exact-prefix hits
+  depend on byte-stability).
+- `template.toolcall` candidates: LLM tool schemas hand-defined per call vs modeled
+  `toolcall @toolName/@payloadRef`.
+- `@responseRef` + AI-trace: hand-parsed responses with no typed response shape; note that
+  `voRequest` / `voResponse` jsonb columns must be authored `field.object` — the loader
+  must not mutate the tree; vendor SDK client + pricing are BYO (ADR-0024).
+- No `meta verify --templates` gate; no declared `@maxChars` / `@maxTokens` budget.
+
+---
+
+## Semantic-constraint ratification (prevents over-modeling)
+
+When folding hand validators into metadata, apply human judgment per constraint.
+A constraint enters **shared metadata** only if it is a **true cross-language domain
+invariant**; a one-consumer preference stays in a thin local refinement layer.
+
+Cross-field rules **are** modelable (`comparison` / `atLeastOne` / `requiredWhen` /
+`presentIff`); ratification decides *which* belong in shared metadata. Output a
+**ratification table**: KEEP-IN-METADATA / LOCAL-REFINEMENT / DROP + rationale —
+human-approved, never applied silently. Distinguish `required` from has-a-safe-default
+(`@default` often fixes the over-requiring bug). A core attr ripples cross-port; for a
+one-consumer need, read it codegen-locally.
+
+---
+
+## Scoring & maturity model — three surfaces (no single global score; bands not decimals)
+
+1. **Headline MATURITY TIER** — Greenfield → Partial → Deep → Exemplary; worst-of with
+   prerequisite gating (a missing pillar can't be averaged away); rendered with **the single
+   next unmet check** ("you're Partial; the next rung needs `verify` in CI").
+2. **Per-pillar breakdown (never rolled into one number)** — `pillar | tier | top gap` over
+   codegen / runtime / drift-gate / prompts. This is the core deliverable.
+3. **Binary CI drift gate** — prominent and separate: **"Is `meta verify` drift detection
+   wired into CI?"** It is binary because the risk is binary.
+
+Coarse bands only (none / some / most / all). Worst-of within a pillar. On re-run, grade
+the delta. Lead with gaps, not the grade.
+
+---
+
+## Report
+
+**Two artifacts:** `.metaobjects/adoption-audit.json` + rendered Markdown.
+
+**Markdown sections (lead with Scorecard):** 0. Scorecard (tier + pillar table + CI gate) ·
+1. Triage + census · 2. Coverage matrix · 3. Per-surface classification tables · 4. Drift
+findings (active bugs first) · 5. Owned-codegen + generator gaps · 6. Drift-gate adoption ·
+7. Runtime-contract + authoring-correctness (axes G+H) · 8. Semantic-constraint ratification ·
+9. Prompt-pillar assessment · 10. Prioritized roadmap: Tier 1 drift kill → Tier 2 existing
+generators → Tier 3 new generators/projections → Tier 4 dynamic-runtime/prompts/cross-port.
+Each roadmap item: LOC retired, prerequisite, **parity-gate before deleting hand-written code**.
+
+**Each finding in `.metaobjects/adoption-audit.json`:**
+
+| Field | Content |
+|---|---|
+| `id` | stable kebab id (e.g. `handwritten-crud-route`, `manual-zod-validator`) |
+| `title` | "you hand-wrote X that metadata can generate / model" |
+| `pillar` | `codegen` / `runtime` / `drift` / `prompt` |
+| `surface` | `entity` / `route` / `validator` / `repository` / `dto` / `hooks` / `prompt` / `migration` |
+| `capability` | the capability-checklist capability this maps to (e.g. `field.currency`, `relationship.@through`) |
+| `locations[]` | exact `file:line` spans |
+| `impact` | LOC eliminated + N call-sites + drift-risk (high/med/low) |
+| `effort` | `trivial` / `small` / `medium` / `large` |
+| `confidence` | bias to under-flagging (false-positive rate >15% is a kill criterion) |
+| `metadata_sketch` | metadata you'd author to replace it — **read-only proposal only; never applied** |
+| `next_command` | the exact command / skill that performs the cutover (see bridge below) |
+| `parity_gate` | the specific check proving behavior-equivalence |
+| `tier` | 1–4 |
+
+Within each tier, sort by impact ÷ effort (quick wins first). Tier 1 leads.
+
+### Audit → action bridge
+
+The audit never edits code. Pattern: **dry-run → review the diff → apply**.
+
+- Propose metadata → `metaobjects-authoring` + brainstorming flow (human reviews).
+- Generate → `meta gen`; **`meta gen --dry-run`** is the review-the-diff step → skill:
+  `metaobjects-codegen`.
+- Prove parity → **`meta verify --codegen`** is the drift gate → skill: `metaobjects-verify`.
+- Routes / runtime / web → skill: `metaobjects-runtime-ui`.
+- Prompts → skill: `metaobjects-prompts`.
+- Cut over **one surface at a time, one commit each**.
+- A separate guided-cutover skill (not this one) reads `adoption-audit.json` and walks
+  findings one tier/surface at a time with human approval at each step.
+
+---
+
+## Guardrails
+
+- **Parity-gate every cutover** — prove behavior-equivalent before deleting hand-written code; generated schemas are often looser.
+- **Verify, don't assume** — read the code behind a grep hit.
+- **Verify the DB artifact, not just the types** — the contract may claim a column the view DDL dropped.
+- **Don't let one bespoke action block generating the entity** — generate CRUD; mount the custom action alongside.
+- **Consumption ≠ a dist copy across versions** — bump + rebuild lockstep and install.
+
+---
+
+## Calibration — port gaps & non-defects (do NOT flag these as adopter fault)
+
+- **Filter-operator route codegen** is full only in **TS**; Java/Kotlin/C#/Python generate
+  pagination/sort/`withCount` but defer filter ops — do not flag hand-added filter handling.
+- **Output-parser codegen** ships TS/C#/Python/Kotlin; **Java hand-writes the Jackson parse** — not a defect.
+- **Python** still hand-wires the FastAPI router + repository impl around a generated
+  `APIRouter`; relationship / non-`table` source-kind / `field.object flattened` codegen is partial.
+- **C#** has no ObjectManager runtime tier (EF Core is the runtime) — hand services over the generated `DbContext` are expected.
+- **Cut subtypes** — `field.byte` / `field.short` / `field.class` are removed; never recommend them.
+- **TS/web-only** — `view.*` widget subtypes exist only for TS/web consumers; only `view.base` / `view.currency` are cross-port-gated.
+- **Planned, not shipped** — `api.*` / `operation.*` / `binding.*` (FR-024) and MCP exposure of declared prompts/tools are not yet in the registry; their absence is not an adopter defect.
+- **Cross-port version skew is by design** — TS/C#/Python `0.x` vs Java/Kotlin `7.x` Maven is correct; never flag it. Flag only *intra-port* drift (mixed versions within one port, or a runtime package in `devDependencies`).
+- **Stale upstream prose** — "hand-write the Spring controller" (Java/Kotlin) is out of date; trust `meta gen --list`, not stale prose.
+
+---
+
+For this project's port specifics and the exhaustive capability checklist, read every `references/*.md` in this skill's directory.

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

@@ -0,0 +1,189 @@
+# MetaObjects capability checklist (registry-grounded)
+
+The **exhaustive** list of every modelable MetaObjects capability, each with its one-line
+audit hunt: *"find a hand-written shape the metadata already describes."* Every
+`type.subtype` and every `@`-prefixed attribute named here is verbatim from the cross-port vocabulary in
+`fixtures/registry-conformance/expected-registry.json` (the
+`agent-context-capability-grounding.test.ts` guard fails the build if a line claims a token
+the registry lacks). Work this checklist on every axis so coverage is exhaustive; respect
+the **inline calibration flags** so a per-port gap is never scored as the adopter's fault.
+
+How to use a line: the capability is what the metamodel can express; the hunt is the
+hand-written second-source-of-truth that should have been derived from it. Found one →
+classify it (using the classification scheme in `SKILL.md`) and route the cutover to the right sibling skill.
+
+---
+
+## Object — `object.*`
+
+- **`object.entity`** (`@discriminator` / `@discriminatorValue` for STI/TPH) — hunt
+  hand-written entity classes, DTOs, and repositories whose field list duplicates a modeled
+  entity; hand-rolled single-table-inheritance / type-discriminator switches that
+  `@discriminator`+`@discriminatorValue` already model.
+- **`object.value`** — hunt hand-authored request / command / payload value objects (no
+  identity, no source) that restate a modeled `value` shape.
+- **`object.projection`** — hunt hand-written read-model DTOs and the SQL views behind them
+  that a derived read-only projection (extends + origin-derived fields) already describes.
+- **`object.base`** — abstract base; hunt copy-pasted shared field blocks that should be an
+  abstract base + `extends` (see cross-cutting).
+
+## Field — `field.*`
+
+- **`field.string`** (`@maxLength`) — hunt hand-validated string-length checks the field
+  models.
+- **`field.int` / `field.long` / `field.double` / `field.float`** — hunt ad-hoc numeric
+  columns / parsing the subtype already types.
+- **`field.decimal`** (`@precision` / `@scale`) — hunt money or quantity stored as `float`/
+  `double` (lossy); the decimal subtype carries exact precision/scale.
+- **`field.boolean`** — hunt int-or-string flags standing in for a boolean.
+- **`field.currency`** (`@currency`, + `view.currency` `@locale`) — hunt money as float,
+  hand `*100` / `/100` minor-unit math, or server-side `Intl.NumberFormat`; storage is
+  integer minor units, formatting is client-side.
+- **`field.date` / `field.time` / `field.timestamp`** (`@autoSet`) — hunt hand-stamped
+  `createdAt` / `updatedAt` assignments and ad-hoc temporal parsing; `@autoSet` stamps them.
+- **`field.enum`** (`@values`) — hunt hand-written TS unions, language `enum`s, or DB
+  `CHECK ... IN (...)` lists that restate a modeled enum's members.
+- **`field.uuid`** — hunt UUIDs typed as bare strings / hand-validated.
+- **`field.object`** (`@objectRef`, `@storage`) — hunt hand-flattened owned columns or
+  hand-rolled jsonb (de)serialization the `@storage` mode (`flattened`/`jsonb`/`subdocument`)
+  already drives.
+- **`field.map`** (`@valueType`) — hunt ad-hoc open-keyed key/value bags stuffed into a jsonb
+  column by hand.
+- **Common field attrs** — `@column` (hand column-name mapping), `@default` (hand default
+  assignment), `@required` (hand presence checks), `@unique` (hand uniqueness), `@readOnly`
+  (hand write-guards), `@filterable` / `@sortable` (hand filter/sort allowlists),
+  `@dbColumnType` (hand native-type override), `@example` / `@instruction` (hand prompt
+  hints), `@xmlText` (hand XML-text mapping). Indexed-without-filter suppression is the
+  `db.indexed` attr (cite without the `@` sigil — it is a dotted attr name).
+- **CALIBRATION — cut subtypes:** `field.byte`, `field.short`, `field.class` are
+  non-functional removed stubs. **Do NOT audit for them and never recommend them.**
+
+## Source — `source.rdb`
+
+- **`source.rdb`** (`@table`, `@schema`) — hunt hard-coded physical table/schema names that
+  diverge from the default naming the source models.
+- **`@kind` = `view` / `materializedView`** — hunt hand-written SQL views where an authored
+  projection source (read-only `@kind`) belongs.
+- **`@kind` = `storedProc` / `tableFunction`** (`@parameterRef`) — hunt hand-called procs /
+  table functions that a modeled callable source with `@parameterRef` already describes.
+- **`@role` = `primary`** (multi-source write-through) — hunt manual CQRS / write-through
+  wiring; exactly one `primary` source per object models it.
+- **`source.base`** — abstract source base (no audit target of its own).
+
+## Relationship — `relationship.*`
+
+- **1:N / N:1** (`@cardinality`, `@objectRef`) — hunt hand-written FK joins and type-unsafe
+  finders the cardinality + target reference already model.
+- **M:N** (`@through`) — hunt hand junction-table queries where `@through` + the junction's
+  two `identity.reference` children generate the traversal.
+- **Self-join** (`@symmetric`, `@sourceRefField`) — hunt hand-coded self-join / graph queries
+  that an undirected (`@symmetric`) or directed (`@sourceRefField`) self-relationship models.
+- **Referential actions** (`@onDelete`, `@onUpdate`) — hunt app-code cascade/null-out logic
+  the relationship's referential actions express.
+- **`relationship.association` / `relationship.aggregation` / `relationship.composition`** —
+  hunt ownership/lifecycle semantics (delete-with-parent, shared vs owned) coded by hand
+  instead of by the relationship subtype.
+- **`relationship.base`** — abstract base.
+
+## Identity — `identity.*`
+
+- **`identity.primary`** (`@generation`) — hunt hand-assigned primary keys / ID generation
+  the primary identity's `@generation` strategy models.
+- **`identity.secondary`** (`@unique`, `@where`, `@expr`) — hunt raw-SQL partial or functional
+  unique indexes a secondary identity with `@where` / `@expr` describes.
+- **`identity.reference`** (`@references`, `@enforce`) — hunt hand-written FK constraints /
+  reference enforcement the reference identity already declares.
+
+## Origin — `origin.*` (projection-field derivation)
+
+- **`origin.aggregate`** (`@agg`, `@of`, `@via`) — hunt hand `COUNT` / `SUM` / `AVG`
+  subqueries or in-app rollups a derived aggregate field models.
+- **`origin.passthrough`** (`@from`, `@via`) — hunt denormalized-by-hand copied fields that a
+  passthrough origin pulls across a relationship.
+- **`origin.collection`** (`@via`) — hunt hand-assembled child-collection loading a collection
+  origin derives.
+- **`origin.base`** — abstract base.
+
+## Validator — `validator.*`
+
+- **`validator.required` / `validator.length` / `validator.numeric` / `validator.array` /
+  `validator.regex`** — hunt hand field-level validation (presence, length, numeric range,
+  array bounds, `@pattern` regex) the validator subtypes model.
+- **Cross-field validators** — `validator.comparison` (`@left`/`@op`/`@right`, e.g.
+  "end ≥ start"), `validator.atLeastOne` (one-of-N present), `validator.requiredWhen`
+  (conditional-required), `validator.presentIff` (mutual presence). Hunt these as hand-coded
+  multi-field rules — they ARE modelable (see the Semantic-constraint ratification section in
+  `SKILL.md` to decide what belongs in shared metadata vs port-local).
+- **`validator.base`** — abstract base.
+
+## View / Layout — `view.*`, `layout.*`
+
+- **`view.currency`** (`@locale`) — hunt hand-passed currency locale / `Intl.NumberFormat`
+  options the currency view models. **Cross-port-gated** (with `view.base`).
+- **`layout.dataGrid`** (`@columns`, `@defaultSortField`, `@defaultSortOrder`, `@pageSize`) —
+  hunt hand-written grid column definitions + data hooks a data-grid layout generates.
+- **CALIBRATION — TS/web-only:** the `view.*` widget subtypes exist only for TS/web consumers
+  and are NOT in the cross-port registry — `view.text`, `view.textarea`, `view.date`,
+  `view.month`, `view.hotlink`, `view.dropdown`, `view.radio`, `view.checkbox`, `view.number`,
+  `view.password`, `view.hidden`, `view.web`. **Audit these only for TS adopters.** Only
+  `view.base` / `view.currency` are cross-port-gated.
+
+## Template — `template.*` (prompt pillar)
+
+- **`template.prompt`** (`@payloadRef`, `@textRef`, `@responseRef`, `@requiredSlots`,
+  `@maxTokens`, `@maxChars`, `@format`, `@model`, `@promptStyle`) — hunt prompt strings
+  assembled inline in services, payloads built ad-hoc, output parsing without a typed
+  `@responseRef`, or token/char budgets enforced by hand.
+- **`template.output`** (`@kind` = `document` | `email`; `@subjectRef`, `@htmlBodyRef`,
+  `@textBodyRef`) — hunt hand-built document/email rendering + hand-written
+  parse-on-receipt the output template + generated render helper/parser cover.
+- **`template.toolcall`** (`@toolName`, `@payloadRef`) — hunt hand-declared LLM tool schemas
+  a modeled tool call describes.
+- **`template.base`** — abstract base.
+
+## Attr — `attr.*`
+
+- **`attr.properties`** — the sanctioned author key/value escape hatch; hunt ad-hoc metadata
+  stuffed into code comments / side-maps that could instead ride the properties bag.
+- **`attr.filter`** — hunt hand-maintained preset filter definitions a modeled filter attr
+  holds.
+- **`attr.class`** — binding facet (`field.class` binding); hunt hand-wired type-binding
+  facets. (`attr.base`, `attr.string`, `attr.int`, `attr.long`, `attr.double`, `attr.boolean`
+  are the value-type primitives behind typed attrs — not direct audit targets.)
+
+## Common documentation attrs (any node)
+
+- `@description`, `@title`, `@summary`, `@notes`, `@deprecated`, `@replacedBy`, `@seeAlso`,
+  `@aliases` — hunt weak/absent generated docs and deprecation tracked only in code comments;
+  these doc attrs flow into JSDoc / XML-doc / Postgres `COMMENT` / Mermaid doc-gen, and
+  `@deprecated` / `@replacedBy` model lifecycle the codebase tracks by hand. (`@notes` is the
+  internal-only rationale slot — never emitted to user-facing doc-gen.)
+
+## Cross-cutting
+
+- **`extends`** (any depth, cross-package `::`) — hunt copy-pasted base-entity field blocks
+  that should be an abstract base inherited via `extends` (the inheritance mechanism;
+  `origin.*` never inherits).
+- **Filter + sort + pagination REST layer** — hunt hand-written query parsing, `LIMIT`/
+  `OFFSET` pagination, total-count queries, and filter/sort handling the generated CRUD layer
+  (8 filter operators + sort + `?limit=N&offset=N` + count) already provides.
+  - **CALIBRATION — per-port codegen gaps:** filter-operator route codegen is full only in
+    **TS**; Java / Kotlin / C# / Python generate pagination/sort/count but **defer filter
+    ops** — do NOT flag hand-added filter handling there. Output-parser codegen ships
+    TS/C#/Python/Kotlin; **Java hand-writes** the Jackson parse (acceptable). **Python**
+    still hand-wires the FastAPI router around a generated `APIRouter` (relationship /
+    non-`table` source-kind / flattened-object codegen is partial). **C#** has no
+    ObjectManager runtime tier (EF Core *is* the runtime) — hand services over the generated
+    `DbContext` are expected.
+- **Single-source config** — `apiPrefix` (URL prefix wired into routes + hooks) and
+  `columnNamingStrategy` (snake_case / literal / kebab-case) and per-target output dirs:
+  hunt these values hard-coded in multiple places instead of resolved from config.
+- **CALIBRATION — planned, not yet shipped:** the declared-API surface (`api.base`,
+  `api.operational`, `operation.query`, `operation.command`, `binding.rest`) and MCP exposure
+  of declared prompts/tools are **not yet in the registry** — their absence is not an adopter
+  defect; do NOT audit for them.
+- **CALIBRATION — cross-port version skew is by design:** TS/C#/Python on the `0.x` line vs
+  Java/Kotlin on the `7.x` Maven line is correct — **never flag it.** Flag only *intra-port*
+  version drift (mixed package versions within one port, or a runtime package in
+  `devDependencies`). Trust the port docs + `meta gen --list`, not stale upstream prose
+  (e.g. the out-of-date "hand-write the Spring controller" note — controllers ARE generated).

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

@@ -0,0 +1,104 @@
+# C# port — audit reference
+
+The C# port targets .NET consumers (EF Core + ASP.NET Minimal API). Codegen runs
+through the `dotnet meta` .NET tool (`MetaObjects.Cli`). Schema migration and
+live-DB drift are **Node-`meta`-only** (ADR-0015) — `dotnet meta` has no `migrate`
+subcommand and `dotnet meta verify --db` is rejected with exit 2.
+
+---
+
+## Finding generated files
+
+Generated files are named `<Entity>.g.cs` and carry an `@generated` guard comment:
+
+```csharp
+// @generated by MetaObjects.Codegen
+```
+
+The metadata source directory is the first positional arg (`<metadataDir>`); `--out`
+is required (errors if absent, no default). The runner overwrites only files bearing
+this header; it refuses to touch files without it. Locate the output directory from
+how the team invokes `dotnet meta gen` (or a CI script) — the arg is explicit, there
+is no config file equivalent on the C# side.
+
+---
+
+## Run codegen + verify
+
+```bash
+dotnet meta gen metaobjects --out Generated --namespace Acme.Generated
+
+dotnet meta gen --list                                     # list all registered generators
+dotnet meta gen --generators entity,db-context,routes      # select a subset
+
+dotnet meta verify --codegen    # regenerate to temp, diff vs committed output
+dotnet meta verify --templates  # check {{field}} refs vs payload VO (bare default)
+```
+
+Schema migration + live-DB drift run through the **Node `meta` CLI** regardless of
+server language — see the migration reference. `dotnet meta verify --db` is
+rejected (exit 2).
+
+---
+
+## Drift signatures (what to grep for)
+
+| Signature | What it means |
+|---|---|
+| `[Column(...)]` / `[Table(...)]` in hand-written `.cs` (not `.g.cs`) | hand-authored EF Core entity — candidate to generate |
+| `DbSet<T>` in a hand-written `DbContext` subclass | generated `AppDbContext` (`db-context` generator) should own this |
+| `HasConversion<string>()` by hand | the `entity` generator emits this for `field.enum`; duplicate if entity is modeled |
+| `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 |
+
+---
+
+## Owned generators
+
+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>`.
+
+To re-scaffold the agent-context into a C# project, use the Node `meta` CLI (the
+single agent-docs assembler per ADR-0033):
+
+```bash
+npx meta agent-docs --server csharp [--out <dir>]
+```
+
+(`dotnet meta agent-docs` is a non-executing stub — it prints this redirect and exits 1.)
+
+---
+
+## Version-skew check
+
+The resolved NuGet package version is what actually ran codegen — check the lock file
+or the restore log, not the `.csproj` range:
+
+```bash
+dotnet list package --include-transitive | grep -i MetaObjects
+```
+
+`MetaObjects` (loader), `MetaObjects.Codegen`, `MetaObjects.Render`, and
+`MetaObjects.Cli` all publish in lockstep on the C# `0.x` line. A mixed resolved
+version across these packages is an intra-port skew finding.
+
+---
+
+## Calibration gaps (do NOT flag these)
+
+- **No ObjectManager runtime tier.** C# has no `ObjectManager` equivalent — EF Core
+  (the generated `AppDbContext` + generated entity classes) **is** the runtime persistence
+  layer. Hand-written service classes over the generated `AppDbContext` are the expected
+  pattern, not a defect.
+- **No C# migrate command.** Schema migration is Node-`meta`-owned for every port
+  (ADR-0015). `dotnet meta` has no migrate subcommand; `meta migrate` is correct.
+- **Filter-operator route codegen deferred.** The generated `<Entity>Routes.cs` (Minimal
+  API) supports `?sort`, `?limit`/`?offset`, and `?withCount=1` envelope, but filter
+  operators (`?filter[field][op]=value`) are not yet generated. Do NOT flag hand-added
+  C# filter handling as an adopter defect.
+- **Output-parser codegen ships in C#.** `output-parser` / `extractor` / `render-helper`
+  generators are available (`dotnet meta gen --generators output-parser`). Absence of
+  wired output parsers where `template.output` nodes exist IS a finding.