metaobjects 0.9.0__py3-none-any.whl

metaobjects/__init__.py

@@ -0,0 +1,75 @@
+"""metaobjects — Python implementation of the MetaObjects standard.
+
+Top-level exports cover the cross-language loader API (MetaDataLoader +
+LoadResult, the four MetaDataSource impls, and Pythonic module-level
+shortcuts ``load_directory`` / ``load_uris`` / ``load_string`` that
+alias the class factories ala ``requests.get`` over ``Session().get``).
+"""
+from __future__ import annotations
+
+from .errors import ErrorCode, MetaError
+from .loader.meta_data_loader import LoadResult, MetaDataLoader
+from .loader.sources import (
+    DirectorySource,
+    FileSource,
+    InMemoryStringSource,
+    MetaDataFormat,
+    MetaDataSource,
+    UriSource,
+)
+from .meta.core.object.meta_object_aware import (
+    MetaObjectAware,
+    is_meta_object_aware,
+)
+from .meta.core.object.object_class_registry import (
+    ObjectClassRegistry,
+    ObjectFactory,
+    default_object_class_registry,
+)
+from .meta.core.object.object_extract import (
+    MAX_NEST_DEPTH,
+    ExtractError,
+    assemble,
+    or_throw,
+    extract_object,
+    extract_schema_for,
+)
+from .meta.core.object.value_object import ValueObject
+
+# Module-level shortcuts: the 99% case for callers who don't need a
+# long-lived loader. Signatures + docstrings come straight from the
+# classmethods — no wrapping layer to drift.
+load_directory = MetaDataLoader.from_directory
+load_uris = MetaDataLoader.from_uris
+load_string = MetaDataLoader.from_string
+
+
+__all__ = [
+    "MetaDataLoader",
+    "LoadResult",
+    "MetaDataSource",
+    "MetaDataFormat",
+    "FileSource",
+    "DirectorySource",
+    "UriSource",
+    "InMemoryStringSource",
+    "ErrorCode",
+    "MetaError",
+    "load_directory",
+    "load_uris",
+    "load_string",
+    # Runtime object model (Phase A)
+    "ValueObject",
+    "MetaObjectAware",
+    "is_meta_object_aware",
+    "ObjectClassRegistry",
+    "ObjectFactory",
+    "default_object_class_registry",
+    # Phase B metadata-driven extract bridge
+    "extract_object",
+    "extract_schema_for",
+    "assemble",
+    "or_throw",
+    "ExtractError",
+    "MAX_NEST_DEPTH",
+]

metaobjects/agent_context/__init__.py

@@ -0,0 +1,55 @@
+"""Agent-context assembler — scaffold the slim MetaObjects Claude Code context.
+
+Reproduces the TypeScript reference assembler (``server/typescript/packages/sdk/
+src/agent-context/``) BYTE-FOR-BYTE: given the repo-root ``agent-context/``
+content tree and a resolved :class:`Stack`, emit the consumer files
+(``.metaobjects/AGENTS.md`` + ``CLAUDE.md`` and the five ``metaobjects-*`` Claude
+Code skills, carrying only the reference fragments for the project's stack).
+
+The assembly is pure given the content tree — the only computed content is the
+two always-on template substitutions; every other file is a verbatim UTF-8 copy.
+"""
+
+from __future__ import annotations
+
+from .assemble import (
+    AssembledFile,
+    assemble,
+    make_stack,
+)
+from .content_root import resolve_agent_context_root
+from .scaffold import (
+    AGENT_CONTEXT_MANIFEST_PATH,
+    Manifest,
+    ScaffoldDecision,
+    agent_context_staleness,
+    hash_contents,
+    installed_metaobjects_version,
+    plan_scaffold,
+)
+from .types import (
+    CLIENT_FRAMEWORKS,
+    MIGRATION_TOKEN,
+    SERVER_LANGS,
+    SKILL_NAMES,
+    Stack,
+)
+
+__all__ = [
+    "AGENT_CONTEXT_MANIFEST_PATH",
+    "AssembledFile",
+    "CLIENT_FRAMEWORKS",
+    "MIGRATION_TOKEN",
+    "Manifest",
+    "SERVER_LANGS",
+    "SKILL_NAMES",
+    "ScaffoldDecision",
+    "Stack",
+    "agent_context_staleness",
+    "assemble",
+    "hash_contents",
+    "installed_metaobjects_version",
+    "make_stack",
+    "plan_scaffold",
+    "resolve_agent_context_root",
+]

metaobjects/agent_context/_content/README.md

@@ -0,0 +1,14 @@
+# agent-context — source of truth for downstream AI-assistant context
+
+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
+`metaobjects-*` Claude skills (each a universal `SKILL.md` plus the
+`references/<token>.md` fragments matching the project's resolved stack).
+
+- `servers/<lang>.meta.json` — per-server install + codegen command (drives the always-on).
+- `templates/always-on.md.mustache` — the slim always-on body (`{{stackLine}}`, `{{codegenCommand}}`).
+- `skills/<skill>/SKILL.md` — universal skill body.
+- `skills/<skill>/references/<token>.md` — language fragment; installed iff `<token>` is in the stack.
+
+Design: `docs/superpowers/specs/2026-06-02-downstream-agent-context-design.md`.

metaobjects/agent_context/_content/servers/csharp.meta.json

@@ -0,0 +1,5 @@
+{
+  "displayName": "C#",
+  "install": "install the MetaObjects .NET tool (dotnet tool install) + add the MetaObjects.Codegen package",
+  "codegenCommand": "dotnet meta gen"
+}

metaobjects/agent_context/_content/servers/java.meta.json

@@ -0,0 +1,5 @@
+{
+  "displayName": "Java",
+  "install": "add com.metaobjects:metaobjects-metadata + metaobjects-codegen-spring + metaobjects-maven-plugin to your pom.xml",
+  "codegenCommand": "mvn metaobjects:generate"
+}

metaobjects/agent_context/_content/servers/kotlin.meta.json

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

metaobjects/agent_context/_content/servers/python.meta.json

@@ -0,0 +1,5 @@
+{
+  "displayName": "Python",
+  "install": "pip install metaobjects",
+  "codegenCommand": "metaobjects gen"
+}

metaobjects/agent_context/_content/servers/typescript.meta.json

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

metaobjects/agent_context/_content/skills/metaobjects-authoring/SKILL.md

@@ -0,0 +1,301 @@
+---
+name: metaobjects-authoring
+description: Use when authoring or modifying MetaObjects metadata — fields, entities, relationships, sources, enums, abstracts/inheritance — in YAML or canonical JSON.
+---
+
+# Authoring MetaObjects metadata
+
+MetaObjects metadata is the durable spine of your app: typed entity declarations
+that drive code generation, runtime behavior, and drift detection. You author it,
+the loader reads it, the codegen emits idiomatic per-language code from it. This
+skill is the procedure for writing it correctly.
+
+Metadata lives in files under `metaobjects/` at project root, one file per domain
+concept (`meta.commerce.json`, `meta.users.yaml`, …). Each file declares a
+`package` on its root node. Files in the same `package` with the same object
+`name` are merged by the loader.
+
+Two on-disk formats, one shape:
+
+- **Canonical JSON** — the on-disk interchange. Every node is a single-key map
+  whose key fuses the type and subtype.
+- **YAML** — the sigil-free authoring front-end. Lowered to canonical JSON at load
+  time, so it shares the entire downstream pipeline.
+
+Author in whichever fits the project. Prefer YAML for new hand-authored metadata
+(it's less noisy); JSON is the format conformance fixtures and tooling pin.
+
+## The fused-key encoding (non-negotiable)
+
+Every node is `{ "<type>.<subType>": { <body> } }`. The wrapper key fuses type and
+subtype — there is **no** separate `subType` body key.
+
+```json
+{ "object.entity": { "name": "User" } }
+{ "field.string": { "name": "email", "@required": true } }
+{ "field.enum":   { "name": "status", "@values": ["OPEN", "CLOSED"] } }
+{ "identity.primary": { "@fields": ["id"] } }
+```
+
+A complete entity in canonical JSON:
+
+```json
+{
+  "metadata.root": {
+    "package": "acme::blog",
+    "children": [
+      {
+        "object.entity": {
+          "name": "Author",
+          "children": [
+            { "source.rdb":   { "@table": "authors" } },
+            { "field.long":   { "name": "id" } },
+            { "field.string": { "name": "name", "@required": true, "@maxLength": 200 } },
+            { "field.string": { "name": "bio",  "@maxLength": 2000 } },
+            { "identity.primary": { "@fields": ["id"], "@generation": "increment" } }
+          ]
+        }
+      }
+    ]
+  }
+}
+```
+
+The same entity in sigil-free YAML:
+
+```yaml
+metadata:
+  package: acme::blog
+  children:
+    - object.entity:
+        name: Author
+        children:
+          - source.rdb: { table: authors }
+          - field.long:   { name: id }
+          - field.string: { name: name, required: true, maxLength: 200 }
+          - field.string: { name: bio, maxLength: 2000 }
+          - identity.primary: { fields: id, generation: increment }
+```
+
+## Reserved structural keys vs. attributes
+
+There is one closed set of **reserved structural keys**. Everything else is an
+attribute.
+
+```
+name   package   extends   abstract   overlay   isArray   children   value
+```
+
+- In **canonical JSON**: reserved keys are bare (`"name"`, `"extends"`); every
+  other key is `@`-prefixed (`"@required"`, `"@maxLength"`, `"@table"`).
+- In **YAML**: reserved keys are bare AND attributes are bare too — the desugar
+  re-adds the `@` when lowering.
+- `@`-prefixing a reserved word (e.g. `"@isArray": true`) is invalid and fails the
+  load with `ERR_RESERVED_ATTR`. Use the bare `isArray: true` (YAML) or the `[]`
+  key-suffix sugar (`field.long[]: weekIds`).
+
+## Two violation rules — internalize these
+
+1. **Attribute-name uniqueness within a node.** A node body must not declare the
+   same attribute name twice. `{ "field.string": { "name": "x", "@maxLength": 10,
+   "@maxLength": 20 } }` is malformed.
+
+2. **An inline `@attr` IS an `attr` child — never both.** An inline attribute and
+   a child `attr.*` node with the same name are the same slot expressed two ways.
+   Declare a given attribute once, in one form. Don't set `@required` inline AND
+   also add an `attr.boolean` child named `required` — that's a double-declaration.
+
+## Field subtypes (closed vocabulary)
+
+| Subtype | Stores | Notes |
+|---|---|---|
+| `field.string` | text | `@maxLength` drives `varchar(N)` |
+| `field.int` | 32-bit integer | |
+| `field.long` | 64-bit integer | |
+| `field.double` | float | |
+| `field.boolean` | true/false | |
+| `field.date` | calendar date | ISO 8601 `YYYY-MM-DD` on the wire |
+| `field.timestamp` | instant | ISO 8601 with timezone on the wire |
+| `field.decimal` | exact decimal | `@precision` / `@scale`; lossless money/quantity |
+| `field.currency` | integer minor units | see Currency below |
+| `field.enum` | string member | `@values` required; see Enum below |
+| `field.uuid` | UUID | canonical lowercase hex on the wire |
+| `field.object` | embedded value object | `@objectRef` + `@storage`; see below |
+
+Common field attributes: `@required`, `@maxLength`, `@column` (physical column
+name), `@default`, `@filterable`, `@sortable`.
+
+### Currency
+
+`field.currency` stores money as **integer minor units** (cents for USD, yen for
+JPY) — never a float. `@currency` is ISO 4217; `@locale` (on a `view.currency`
+child) is BCP 47. The server never formats currency; formatting is client-side.
+
+```json
+{ "field.currency": {
+    "name": "priceCents", "@currency": "USD", "@required": true,
+    "children": [ { "view.currency": { "@locale": "en-US" } } ]
+}}
+```
+
+### Enum
+
+`field.enum` is string-backed. `@values` is **required**: a non-empty set of
+unique members, each matching `^[A-Za-z_][A-Za-z0-9_]*$`. Missing `@values` →
+`ERR_MISSING_REQUIRED_ATTR`; a bad member → `ERR_BAD_ATTR_VALUE`.
+
+```json
+{ "field.enum": { "name": "status", "@required": true,
+    "@values": ["DRAFT", "PUBLISHED", "ARCHIVED"] } }
+```
+
+Reuse a constraint set across entities with an abstract `field.enum` + `extends`.
+
+### Embedded value objects — `field.object` + `@storage`
+
+`field.object` embeds another `object` declaration. `@objectRef` names it;
+`@storage` controls persistence:
+
+- `flattened` — one DB column per sub-field (`address_street`, `address_city`, …).
+  Illegal on array fields.
+- `jsonb` — one `jsonb` column.
+- `subdocument` (default, back-compat) — single jsonb column.
+
+```json
+{ "field.object": { "name": "address", "@objectRef": "Address", "@storage": "flattened" } }
+```
+
+## YAML sigil-free authoring + the coercion footgun
+
+In YAML, write the fused `type.subType` key with a **map body**, bare reserved
+keys, bare attributes. Two house-style rules:
+
+1. **Always write the explicit `type.subType`** (`field.string`, not `field`).
+   Defaults change; the explicit form survives registry edits.
+
+2. **Quote any scalar that looks like a boolean, number, date, or null.** YAML
+   silently coerces unquoted `yes` / `no` / `on` / `off` to booleans and bare
+   `2026-05-25` to a date. The loader's coercion guard rejects a coerced value in
+   a slot that declares a different type (`ERR_YAML_COERCION`) — but quoting is how
+   you *prevent* the surprise. Enum members are the classic trap:
+
+   ```yaml
+   # Rejected — Y and N coerce to booleans
+   field.enum: { name: flag, values: [Y, N] }
+   # Correct — quote domain-data members
+   field.enum: { name: flag, values: ["Y", "N"] }
+   ```
+
+The `[]` key-suffix declares an array field: `field.long[]: weekIds` lowers to
+`{ "field.long": { "name": "weekIds", "isArray": true } }`.
+
+## Identities
+
+| Subtype | Purpose | Key attrs |
+|---|---|---|
+| `identity.primary` | the PK field(s) | `@fields`, `@generation` |
+| `identity.secondary` | a unique secondary index | `@fields` |
+| `identity.reference` | an inbound FK from this entity to another | `@fields`, `@references`, `@enforce` |
+
+`@generation` on a primary controls value generation (e.g. `increment`).
+`@fields` accepts a single string in authoring; it normalizes to an array in
+canonical JSON. `@enforce` on a reference (default `true`) controls whether the
+backend physically enforces it (a SQL FK constraint); set `false` for a logical
+reference for navigation/typing/codegen only. Referential actions
+(`@onDelete`/`@onUpdate`) are NOT on `identity.reference` — they live on the
+`relationship.*` node (see Relationships below).
+
+```json
+{ "identity.primary":   { "@fields": ["id"], "@generation": "increment" } }
+{ "identity.secondary": { "@fields": ["email"] } }
+{ "identity.reference": { "name": "fkAuthor", "@fields": ["authorId"], "@references": "Author", "@enforce": true } }
+```
+
+## Relationships
+
+`relationship.composition` is the "this entity owns / aggregates instances of
+that entity" side; `identity.reference` (above) is the FK-column side. They are
+the two halves of one FK.
+
+| Attr | On | Values |
+|---|---|---|
+| `@objectRef` | composition | target entity name |
+| `@cardinality` | composition | `one` / `many` |
+| `@onDelete` / `@onUpdate` | `relationship.*` only | `cascade` / `set-null` / `restrict` / `no-action` |
+
+```json
+{ "relationship.composition": {
+    "name": "posts", "@objectRef": "Post",
+    "@cardinality": "many", "@onDelete": "cascade" } }
+```
+
+## Sources — `source.rdb` + `@kind`
+
+`source.rdb` declares where an entity's data lives. Read-only-ness derives from
+`@kind` (it is NOT a separate subtype):
+
+| `@kind` | Read-only | Default? |
+|---|---|---|
+| `table` | no | yes (when `@kind` omitted) |
+| `view` | yes | – |
+| `materializedView` | yes | – |
+| `storedProc` | yes | – |
+| `tableFunction` | yes | – |
+
+The physical name is `@table` (NOT `@name`). The physical column name on a field
+is `@column`. `@schema` namespaces the DB schema (Postgres default `public`;
+SQLite rejects non-default values). Multi-source: multiple `source.rdb` children,
+each with a `@role`, exactly one `primary`.
+
+```json
+{ "source.rdb": { "@kind": "view", "@table": "v_author", "@schema": "blog" } }
+```
+
+A `view`-kind entity's fields carry `origin.*` children (`passthrough` /
+`aggregate` / `collection`) declaring where each value comes from.
+
+## Abstracts + `extends` (deferred resolution) + `overlay`
+
+An **abstract** node (`abstract: true`) describes a shape but is never emitted as
+a concrete entity. A concrete node references it via `extends:` to inherit its
+children + attrs. This is the lightest reuse mechanism — pure data, no codegen
+change.
+
+```yaml
+- object.entity:
+    name: BaseEntity
+    abstract: true
+    children:
+      - field.long: { name: id }
+      - field.timestamp: { name: createdAt, required: true }
+
+- object.entity:
+    name: Author
+    extends: BaseEntity
+    children:
+      - source.rdb: { table: authors }
+      - field.string: { name: name, required: true }
+      - identity.primary: { fields: id }
+```
+
+Resolution facts:
+
+- **Deferred.** `extends:` resolves *after all files load* — abstracts can live in
+  any file, forward references are fine.
+- **Multi-level chains flatten** (`Author extends BaseEntity extends Auditable`).
+- **Cross-package** refs use the fully-qualified name (`extends: "shared::auditable"`);
+  same-package refs use the bare name.
+- An unresolved reference fails with `ERR_UNKNOWN_EXTENDS`.
+
+`abstract` and `extends` are **structural keys** (bare, no `@`).
+
+**`overlay` is a different concept.** `extends:` is an IS-A relationship between
+two distinct nodes. `overlay: true` re-opens the *same* named node to amend it
+across files (same `package` + same `name` → merged; last-writer-wins on attr
+conflicts, structural children accumulate). Use `extends` to share shape between
+distinct entities; use `overlay` to split one entity's declaration across files.
+
+---
+
+For non-trivial schema design, use `/superpowers:brainstorming` if installed;
+otherwise proceed.

metaobjects/agent_context/_content/skills/metaobjects-codegen/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: metaobjects-codegen
+description: Use when configuring or running MetaObjects code generation: generators/targets/dialect config, the gen command, and hand-edit-preserving regeneration.
+---
+
+# MetaObjects code generation
+
+Codegen is the first pillar: MetaObjects reads your typed metadata and emits
+**idiomatic per-language code** — entity types, DB tables/schemas, query helpers,
+REST routes, validators, payload value-objects, output parsers. The metadata is the
+durable spine; the generated code is a disposable artifact. It runs at runtime
+**without any MetaObjects dependency** — if the libraries disappeared tomorrow, you
+keep working code.
+
+This skill is the port-agnostic procedure. The exact config file, generator names,
+and command for *this* project's server language live in a reference fragment
+(pointed to at the bottom).
+
+## What codegen does
+
+You run a `gen` step. The runner:
+
+1. Loads all metadata under `metaobjects/` (the same loader the runtime uses).
+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.
+
+The output is normal idiomatic code in your language — you import it and use it
+like any hand-written module.
+
+## The `@generated` header + hand-edit-preserving regen
+
+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.
+- **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
+  the backstop: a diff on a `@generated` file that wasn't produced by `gen` is a
+  smell.
+
+Practical rule: **pattern-derivable-from-metadata = regenerate; business logic =
+hand-write in a non-generated file.** FK columns, CRUD, validator chains,
+type-safe finders, `relations()` blocks — all derived, never hand-coded. Custom
+SQL views, regex from outside metadata, and domain logic are what you hand-write.
+
+## Selecting generators by stable name
+
+Codegen is a set of named generators you opt into. Each generator has a **stable
+name** (kebab-case) that surfaces in diagnostics — reference generators by that
+name, never by inlining what they emit. Typical generators cover: the entity
+type/model, the DB table/schema, query/finder helpers, REST routes, client
+form/grid/hook artifacts, filter + sort allowlists, payload value-objects, and
+`template.output` parsers. You enable the subset your project needs; an abstract
+entity never emits instance/write artifacts regardless.
+
+Per-entity opt-outs exist (e.g. skipping client-side artifacts for a given
+entity) and are set as attributes on the entity in metadata, not in code.
+
+## Dialects
+
+Generated DB schema/DDL targets a SQL **dialect**:
+
+- `postgres` — the default, fullest-featured.
+- `sqlite` — supported; rejects non-default DB schemas.
+- `d1` (Cloudflare D1) — **TypeScript-only**. It is SQLite at the SQL level; the
+  non-TS server ports have no analogue, so it never appears in their config.
+
+Set the dialect once in the project's codegen config. Field subtypes map to the
+dialect's column types deterministically (`field.string` + `@maxLength` →
+`varchar(N)`, `field.currency` → integer, `field.uuid` → native `uuid` on
+Postgres, `field.enum` → `varchar` + `CHECK`, etc.).
+
+## Per-target output
+
+Generated code can be routed to **multiple output directories/packages** so each
+artifact lands with its runtime concern: the entity model in a database package,
+routes in the API app, client hooks/forms/grids in the web app. Each generator can
+declare which named target it writes to; same-target references stay relative,
+cross-target references go through the target's configured import base. With no
+targets configured, everything lands in a single output directory — output is
+byte-identical to the single-directory case. Use multiple targets only when the
+project's package boundaries justify it.
+
+## Running gen
+
+The shape is always the same — a `gen` verb that loads metadata, renders, merges,
+and writes — but the binary differs per server language (the Node `meta`, a
+language-native console tool, or a build-plugin goal). A dry-run mode previews
+without writing; a watch mode re-runs on metadata changes where supported. Pass
+specific entity names to scope a run to those entities.
+
+---
+
+For this project's server-language codegen specifics, read every `references/*.md` file in this skill's directory (one per server language in this project's stack).

metaobjects/agent_context/_content/skills/metaobjects-codegen/references/csharp.md

@@ -0,0 +1,87 @@
+# C# codegen specifics
+
+The C# port targets .NET consumers (EF Core + ASP.NET). Codegen runs through the
+**`dotnet meta` .NET tool** — there is no Maven plugin and the Node `meta` binary
+is **schema-migrations only** on the C# side (ADR-0015): `meta migrate` /
+`meta verify --db` are Node-`meta`-owned; everything below is `dotnet meta`.
+
+## Install
+
+Per the always-on descriptor:
+
+```bash
+dotnet tool install --global MetaObjects.Cli   # provides `dotnet meta`
+dotnet add package MetaObjects.Codegen          # the codegen generators
+```
+
+`dotnet meta` is a .NET tool invoked as `dotnet meta <command>` (the underlying
+command is `dotnet-meta`).
+
+## Run
+
+```bash
+dotnet meta gen \
+  --metadata-dir metaobjects \
+  --output-dir Generated \
+  --namespace Acme.Generated
+dotnet meta gen --list                      # list registered generators
+dotnet meta gen --generators entity,db-context,routes   # select a subset
+dotnet meta verify --codegen                # codegen-drift gate (regenerate + diff vs committed)
+```
+
+`dotnet meta verify` defaults to `--templates` (the FR-004 prompt/template drift
+gate, see the prompts reference); `--codegen` is the codegen-output drift gate.
+**Schema migration + live-DB drift are NOT `dotnet meta`** — they run through the
+Node `meta` tool (see the migration reference).
+
+## `MetaObjects.Codegen` generators
+
+Wire generators by their stable name (`dotnet meta gen --generators <names>`),
+or run the default set. Output lands under `--namespace` in `--output-dir`.
+
+| Stable name | Output |
+|---|---|
+| `entity` | `<Entity>.g.cs` — an EF Core entity class per `object.entity` / projection: PascalCase props mapped via `[Column]`, `[Table]`, `[Key]` (or class-level `[PrimaryKey]` for composites), `[MaxLength]`/validators, nullability from `@required`. Enum fields → a nested (or shared) C# `enum`; object fields → owned-type navigations; value objects → POCOs. A TPH `@discriminator` base is emitted `abstract` with `: Base` subtypes (single-table). |
+| `db-context` | one `AppDbContext` — a `DbSet<T>` per entity + `OnModelCreating`: `.HasConversion<string>()` (enums), `.OwnsOne(...)`/`.ToJson(...)` (owned/jsonb object fields), `.HasPrecision(p,s)` (decimals), `.UsingEntity<>(...)` (M:N), `.HasDiscriminator(e => e.Type).HasValue<Sub>(...)` (TPH). |
+| `routes` | `<Entity>Routes.cs` — ASP.NET **Minimal API** CRUD per writable entity (`source.rdb @kind="table"`) on the cross-port REST contract (`?filter[field][op]=`, `?sort=field:asc`, `?limit`/`?offset`, `?withCount=1` envelope, 400/404 envelopes). A TPH base emits polymorphic `GET /<base>(+/{id})` + a per-subtype CRUD set at `/<base>/<discriminatorValue lowercased>` (create injects the discriminator, cross-subtype get/update/delete → 404). |
+| `filter-allowlist` | per-entity `<Entity>FilterAllowlist` (FR-009 — the server-side field+operator allowlist the routes validate against). |
+| `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). |
+| `output-parser` / `extractor` / `output-prompt` / `render-helper` | the `template.output` prompt-pillar artifacts (strict parser, tolerant `extract`, output-format prompt fragment, typed render helper) — see the **prompts** reference. |
+| `template` | the generic Mustache `templateGenerator()` primitive. |
+
+Metadata lives under `metaobjects/` (or wherever you point `--metadata-dir`) in the
+same canonical JSON every port reads — fused-key form, `source.rdb` + `@table`,
+`@column` for a renamed physical column.
+
+## Persistence + routes are the deployed artifact
+
+C# generates a *complete* server stack: the entity classes + `AppDbContext` ARE the
+persistence layer (EF Core), and the minimal-API routes mount on your `WebApplication`.
+There is no runtime "ObjectManager" layer to wire — the generated EF Core code is
+what runs. (The other ports leave a repository seam; C# does not.)
+
+## Extending the generators (open-for-extension, ADR-0002)
+
+The generators are subclassable: the per-class emit methods are `protected virtual`,
+plus finer hooks — `EmitClassHeader` / `EmitClassDeclarationLine` (class declaration:
+`partial`, marker interfaces), `EmitPropertyAttributes` (per-property C# attributes),
+`EmitFileUsings` (extra usings), `EmitClassBodyTrailer` (extra members). Subclass a
+generator and override only the seam you need rather than forking. `@default` on a
+scalar emits a literal initializer; an `object.value`'s default storage is jsonb.
+
+**Shared + externally-provided enums (FR-019).** A package-level abstract
+`field.enum` (`abstract: true`, `@values`) extended by concrete entity fields is
+materialized **once** (`Enums.g.cs`) and referenced — no per-entity nested enum.
+Adding `@provided: true` to that declaration suppresses materialization entirely:
+consuming fields reference a hand-written/third-party enum, and the C# namespace
+**binds to the enum's declaring metadata package** via
+`GenConfig.PackageNamespaces["<pkg>"] = "Your.Namespace"` (one entry per namespace;
+`ProvidedEnumNamespace` is the single fallback). The `@values` still drive the DB
+`CHECK` + validation. This replaces the retired C#-only `@csEnumType` FQN attr
+(ADR-0026) — no language FQN ever lives in metadata (ADR-0001).
+
+## Re-scaffold this context
+
+`dotnet meta agent-docs --server csharp [--out <dir>]` (re)scaffolds the slim
+always-on Markdown + these `metaobjects-*` skills into the project — the C# tool
+bundles the agent-context tree, so a C# consumer needs no Node `meta`.