metaobjects 0.9.0__tar.gz → 0.11.0__tar.gz

{metaobjects-0.9.0 → metaobjects-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metaobjects
-Version: 0.9.0
+Version: 0.11.0
 Summary: Cross-language metadata standard: declare typed entities once, generate idiomatic drift-checked code across languages — Python port.
 Project-URL: Homepage, https://metaobjects.dev
 Project-URL: Repository, https://github.com/metaobjectsdev/metaobjects

{metaobjects-0.9.0 → metaobjects-0.11.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "metaobjects"
-version = "0.9.0"
+version = "0.11.0"
 description = "Cross-language metadata standard: declare typed entities once, generate idiomatic drift-checked code across languages — Python port."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -75,6 +75,12 @@ exclude = ["**/KNOWN_GAPS.md"]
 # falls back to walking up to the monorepo agent-context/.
 [tool.hatch.build.hooks.custom]
 
+# FR-033 — the 15 shared spec/metamodel/*.json files are COMMITTED copies under
+# src/metaobjects/spec_metamodel/ (not build-time-generated), so hatchling's default
+# package inclusion ships them in both the sdist and the wheel (read via
+# importlib.resources, AOT-safe). A byte-identity gate
+# (tests/conformance/test_spec_metamodel_embed.py) keeps the copies from drifting
+# from the repo-root spec/metamodel/ source.
 [tool.hatch.build]
 artifacts = ["src/metaobjects/agent_context/_content/**"]
 
@@ -93,4 +99,13 @@ exclude = ["tests/codegen/golden/"]
 [dependency-groups]
 dev = [
     "pytest>=9.0.3",
+    # `uv run` installs THIS group (PEP 735), not [project.optional-dependencies].
+    # The validator-parity corpus (tests/codegen/test_validation_conformance.py)
+    # imports pydantic to exercise the generated Pydantic models, so it must be here
+    # or the CI `uv run pytest` collection fails with ModuleNotFoundError.
+    "pydantic>=2",
+    # ruff is the Python codegen format pass (src/metaobjects/codegen/format.py); the
+    # cli-registry corpus runs codegen, so without ruff in the group `uv run pytest`
+    # fails at format time with "No module named ruff".
+    "ruff>=0.6",
 ]

{metaobjects-0.9.0 → metaobjects-0.11.0}/src/metaobjects/agent_context/_content/skills/metaobjects-authoring/SKILL.md

@@ -34,7 +34,7 @@ subtype — there is **no** separate `subType` body key.
 { "object.entity": { "name": "User" } }
 { "field.string": { "name": "email", "@required": true } }
 { "field.enum":   { "name": "status", "@values": ["OPEN", "CLOSED"] } }
-{ "identity.primary": { "@fields": ["id"] } }
+{ "identity.primary": { "name": "id", "@fields": ["id"] } }
 ```
 
 A complete entity in canonical JSON:
@@ -52,7 +52,7 @@ A complete entity in canonical JSON:
             { "field.long":   { "name": "id" } },
             { "field.string": { "name": "name", "@required": true, "@maxLength": 200 } },
             { "field.string": { "name": "bio",  "@maxLength": 2000 } },
-            { "identity.primary": { "@fields": ["id"], "@generation": "increment" } }
+            { "identity.primary": { "name": "id", "@fields": ["id"], "@generation": "increment" } }
           ]
         }
       }
@@ -74,7 +74,7 @@ metadata:
           - field.long:   { name: id }
           - field.string: { name: name, required: true, maxLength: 200 }
           - field.string: { name: bio, maxLength: 2000 }
-          - identity.primary: { fields: id, generation: increment }
+          - identity.primary: { name: id, fields: id, generation: increment }
 ```
 
 ## Reserved structural keys vs. attributes
@@ -165,6 +165,26 @@ Reuse a constraint set across entities with an abstract `field.enum` + `extends`
 { "field.object": { "name": "address", "@objectRef": "Address", "@storage": "flattened" } }
 ```
 
+**Arrays of value objects** — set `isArray: true` with `@storage: jsonb`. The whole
+array lives in **one** jsonb column (a JSON array), never a native `jsonb[]`. The
+generated Postgres column is typed `.$type<VO[]>()` and the Zod schema is
+`z.array(<VO>InsertSchema)`:
+
+```json
+{ "field.object": { "name": "triples", "@objectRef": "Triple",
+    "@storage": "jsonb", "isArray": true } }
+```
+
+**Opaque jsonb (no value object)** — when the payload has no fixed shape (freeform
+config, passthrough metadata, an open-keyed map), do NOT use `field.object` (it
+requires `@objectRef`, and a partial VO would let the generated Zod strip unknown
+keys → data loss). Model it as a `field.string` with the physical-type override
+`@dbColumnType: jsonb` — the logical type stays string-bound, the column is jsonb:
+
+```json
+{ "field.string": { "name": "metadata", "@dbColumnType": "jsonb" } }
+```
+
 ## YAML sigil-free authoring + the coercion footgun
 
 In YAML, write the fused `type.subType` key with a **map body**, bare reserved
@@ -194,7 +214,7 @@ The `[]` key-suffix declares an array field: `field.long[]: weekIds` lowers to
 | Subtype | Purpose | Key attrs |
 |---|---|---|
 | `identity.primary` | the PK field(s) | `@fields`, `@generation` |
-| `identity.secondary` | a unique secondary index | `@fields` |
+| `identity.secondary` | a unique secondary index | `@fields` (or `@expr` for a functional index) |
 | `identity.reference` | an inbound FK from this entity to another | `@fields`, `@references`, `@enforce` |
 
 `@generation` on a primary controls value generation (e.g. `increment`).
@@ -205,9 +225,27 @@ reference for navigation/typing/codegen only. Referential actions
 (`@onDelete`/`@onUpdate`) are NOT on `identity.reference` — they live on the
 `relationship.*` node (see Relationships below).
 
+`@references` resolves cross-package by **fully-qualified name**
+(`@references: "shared::billing::Account"`), the same rule as `extends`; a bare
+name resolves within the current package. The FK target must be an entity with a
+single-column primary key (the FK points at that PK); a target with a composite
+PK needs the explicit dotted form `@references: "pkg::Target.fieldA,fieldB"`.
+
+**A dangling reference fails the load (0.11.0+).** An unresolved
+`identity.reference.@references` raises `ERR_INVALID_REFERENCE` and an unresolved
+`relationship.@objectRef` raises `ERR_INVALID_RELATIONSHIP` — the target entity must
+exist (previously such references loaded silently). So every `@references` /
+`@objectRef` you author must name a real entity.
+
+A `identity.secondary` can index an **expression** instead of plain columns: use
+`@expr` (e.g. `"lower(email)"`) in place of `@fields`, optionally with `@using` (the
+index method — `gin` / `gist` / `hash`; default `btree`) and `@where` (a partial-index
+predicate).
+
 ```json
-{ "identity.primary":   { "@fields": ["id"], "@generation": "increment" } }
-{ "identity.secondary": { "@fields": ["email"] } }
+{ "identity.primary":   { "name": "id", "@fields": ["id"], "@generation": "increment" } }
+{ "identity.secondary": { "name": "byEmail", "@fields": ["email"] } }
+{ "identity.secondary": { "name": "byEmailCI", "@expr": "lower(email)" } }
 { "identity.reference": { "name": "fkAuthor", "@fields": ["authorId"], "@references": "Author", "@enforce": true } }
 ```
 
@@ -229,6 +267,39 @@ the two halves of one FK.
     "@cardinality": "many", "@onDelete": "cascade" } }
 ```
 
+**Adoption footgun — pin BOTH actions.** `@onDelete` and `@onUpdate` each default to
+`cascade` when omitted, but a plain SQL foreign key is `NO ACTION` on both. If you're
+adopting an existing database (matching metadata to a live schema), omitting these
+makes the metadata declare `CASCADE` where the DB has `NO ACTION` — a perpetual
+`verify --db` drift. Pin **both** explicitly to the DB's real behavior:
+
+```json
+{ "relationship.composition": { "name": "author", "@objectRef": "User",
+    "@cardinality": "one", "@onDelete": "no-action", "@onUpdate": "no-action" } }
+```
+
+## Validators — cross-field rules
+
+Entity-scoped `validator.*` children declare invariants that reference sibling fields
+**by name** (the same name-reference pattern as `identity.*`). The backend derives the
+enforcement (a CHECK constraint / cross-field assertion) — no raw expression is stored.
+
+| Subtype | Rule | Key attrs |
+|---|---|---|
+| `validator.comparison` | two fields stand in a relational order (`@left @op @right`) | `@left`, `@op` (`gt`/`gte`/`lt`/`lte`/`ne`/`eq`), `@right` |
+| `validator.requiredWhen` | `@field` is required when `@when` equals `@equals` | `@field`, `@when`, `@equals` |
+| `validator.presentIff` | `@field` is present **iff** `@when` equals `@equals` (biconditional) | `@field`, `@when`, `@equals` |
+| `validator.atLeastOne` | at least one of `@fields` (2+) is present | `@fields` |
+
+```json
+{ "validator.comparison":   { "name": "hpInRange", "@left": "currentHp", "@op": "lte", "@right": "maxHp" } }
+{ "validator.requiredWhen": { "name": "reasonIfRejected", "@field": "rejectReason", "@when": "status", "@equals": "rejected" } }
+{ "validator.presentIff":   { "name": "usedAtWhenUsed", "@field": "usedAt", "@when": "isUsed", "@equals": "true" } }
+{ "validator.atLeastOne":   { "name": "emailOrPhone", "@fields": ["email", "phone"] } }
+```
+
+These are children of `object.entity`, alongside its fields and identities.
+
 ## Sources — `source.rdb` + `@kind`
 
 `source.rdb` declares where an entity's data lives. Read-only-ness derives from
@@ -251,8 +322,15 @@ each with a `@role`, exactly one `primary`.
 { "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.
+**An entity's PRIMARY source must be writable** (`table`) — read-only kinds are
+legal only in non-primary roles (e.g. table `primary` + view `replica` for
+read-through). A derived read model over a view/proc is an **`object.projection`**
+(FR-024): its fields `extends` entity fields (`extends: "Author.id"` — dotted
+child traversal, package only on the root segment) and/or carry `origin.*`
+children (`passthrough` / `aggregate` / `collection`) declaring assembly; its
+identity passes through via `extends` (`identity.primary: { name: id, extends:
+"Author.id" }`); it is read-only by construction and the declared field set IS
+the exposure (fail-closed).
 
 ## Abstracts + `extends` (deferred resolution) + `overlay`
 
@@ -275,7 +353,7 @@ change.
     children:
       - source.rdb: { table: authors }
       - field.string: { name: name, required: true }
-      - identity.primary: { fields: id }
+      - identity.primary: { name: id, fields: id }
 ```
 
 Resolution facts:

{metaobjects-0.9.0 → metaobjects-0.11.0}/src/metaobjects/agent_context/_content/skills/metaobjects-codegen/references/typescript.md

@@ -41,6 +41,11 @@ export default defineConfig({
   dialect: "postgres",                 // "postgres" | "sqlite" | "d1" (D1 is TS-only)
   apiPrefix: "/api",                   // flows to routes AND client fetch URLs
   columnNamingStrategy: "snake_case",  // "snake_case" (default) | "literal" | "kebab-case"
+  timestampMode: "string",             // "string" (default, ISO-8601 wire contract) | "date" (Drizzle native Date)
+  pluralizeCollections: true,          // default; table VARS auto-pluralize (AgentConfig → agentConfigs)
+  collectionNameOverrides: {           // per-entity escape hatch for names the rule gets wrong
+    AuditLog: "auditLog", LlmTierConfig: "llmTierConfig",
+  },
   generators: [
     entityFile(), queriesFile(), routesFile(), barrel(),
     formFile(), tanstackQuery(), tanstackGrid(),
@@ -48,6 +53,13 @@ export default defineConfig({
 });
 ```
 
+Naming + timestamp knobs are **codegen config**, not metadata attributes — a
+collection variable name and a Drizzle column mode are per-port rendering choices
+with no meaning to the other language ports, so they carry no cross-port
+conformance cost. `collectionNameOverrides` wins over `pluralizeCollections` and is
+applied consistently to the table declaration, every FK reference, the `relations()`
+block, and the inferred types.
+
 A second file, `.metaobjects/config.json`, holds static project state parseable by
 non-TS tooling; `meta init` scaffolds both plus the `metaobjects/` source dir.
 
@@ -133,3 +145,21 @@ Deterministic per dialect: `field.string` + `@maxLength` → `varchar(N)`,
 (Postgres) + `gen_random_uuid()`, `field.enum` → `varchar` + `CHECK`. Override a
 field's physical column name with `@column` on the field; the DB schema name lives
 on `source.rdb` via `@schema`.
+
+### Value-object jsonb columns
+
+A `field.object` with `@storage: jsonb` (or the default `subdocument`) becomes a
+single typed jsonb column — the referenced value-object's TS type is carried onto
+the Drizzle column via `.$type<>()`, and its Zod schema is the VO's `InsertSchema`:
+
+```ts
+// field.object @objectRef=LlmConfig @storage=jsonb
+llmConfigJson: jsonb("llm_config_json").$type<LlmConfig>(),
+// field.object @objectRef=Triple @storage=jsonb isArray=true
+triples: jsonb("triples").$type<Triple[]>(),   // one jsonb column, NOT a native jsonb[]
+```
+
+The VO type, its Zod `InsertSchema`, and this `.$type<>()` all import the VO from
+the same module (layout/package/`extStyle`-aware resolution). An opaque jsonb column
+(`field.string @dbColumnType: jsonb`) gets no `.$type<>()` — it stays `unknown`,
+which is the correct shape for freeform payloads with no fixed VO.

{metaobjects-0.9.0 → metaobjects-0.11.0}/src/metaobjects/agent_context/_content/skills/metaobjects-prompts/SKILL.md

@@ -123,6 +123,47 @@ For the `xml`-format example above with payload `{ displayName: "Ada", postCount
 bytes. You render the prompt, call your LLM client (provider-agnostic — codegen
 emits no provider-side schema), then parse the response.
 
+## Conditional content: data and flags, never branched prose
+
+When a prompt's wording varies along some dimension — audience, tier, mode,
+locale, entitlement, a domain variant — do NOT branch the prose in code and
+concatenate strings. Branching prompt text in a service is the anti-pattern this
+pillar exists to remove: it scatters the same distinction across call sites, each
+re-encoded and free to drift, and none of it snapshot-tested. The variation
+belongs in exactly two places, with a third for the rare genuine divergence:
+
+- **Vocabulary as payload data.** The words and values that differ become typed
+  payload fields, pre-computed once from the varying dimension — a noun, a label,
+  a set of verbs (a list), an example. The template stays single and references
+  `{{term}}` / `{{#items}}…{{/items}}`. The prose *structure* is identical across
+  variants; only the data differs, so there is nothing to branch.
+- **Presence as boolean flags.** When a whole block exists-or-not for a variant,
+  gate it with a section flag the payload sets: `{{#showBlock}}…{{/showBlock}}`.
+  Reserve flags for entire blocks — never mid-sentence word swaps, which are
+  vocabulary.
+- **Variant text only when prose truly diverges.** If a section's wording — not
+  just its vocabulary — genuinely differs, select a per-variant text through the
+  provider seam (a `@textRef` variant, or an included partial) so the shared
+  prose still lives in one place. Expect to need this rarely.
+
+A single resolver maps the varying dimension to that payload (the flags + the
+vocabulary), so the distinction is defined ONCE and every template that depends
+on it stays consistent.
+
+```
+// WRONG — prose branched and concatenated in a service:
+if (tier.isPremium()) sb.append("Your plan includes priority support.");
+else                  sb.append("Upgrade any time for priority support.");
+```
+```mustache
+{{! RIGHT — text in the template; the variant is data + a flag }}
+{{supportLine}}
+{{#isPremium}}(Priority queue enabled.){{/isPremium}}
+```
+
+This stays deterministic and golden-testable per variant: render the template
+against each value of the dimension and snapshot every variant.
+
 ## `verify` fails the build on prompt-drift
 
 For every template, the verify step resolves the text, parses each `{{...}}`

{metaobjects-0.9.0 → metaobjects-0.11.0}/src/metaobjects/agent_context/_content/skills/metaobjects-verify/references/migration.md

@@ -66,7 +66,40 @@ A clean run is silent; a failure names the drifted table/column. Bias toward
 trusting the tool — a drift failure almost always means the metadata changed and the
 DB didn't follow.
 
+## Index modeling (Postgres)
+
+Secondary indexes carry physical-shape attributes contributed by the db provider
+(they live on `identity.secondary`, not core):
+
+- `@orders` — per-key sort direction, positional to `@fields` (`["asc", "desc"]`).
+  Omit for all-ascending; drives `DESC`-ordered index keys (e.g. a recency index).
+- `@where` — a partial-index predicate (raw SQL, e.g. `"delivered_at IS NULL"`),
+  emitted as `WHERE (<pred>)`. The index then covers only matching rows.
+
+```json
+{ "identity.secondary": { "@fields": ["userId", "createdAt"],
+    "@orders": ["asc", "desc"], "@where": "archived_at IS NULL" } }
+```
+
+## Adopting an existing database (non-destructive)
+
+`meta verify --db` / `meta migrate` can reach **zero drift** against a hand-built
+schema without a rewrite:
+
+- **`meta migrate --from-db`** reverse-engineers a baseline from the live DB so the
+  first diff is empty.
+- **Auto schema-scope** — the diff manages only the schemas the metadata *declares*
+  (via `source.rdb @schema`); tables in undeclared schemas belong to another owner
+  and are left untouched. This is what lets several apps share one database, each
+  owning its own schema, with a clean per-owner `verify --db` and no manual ignore
+  lists. A downstream app that extends the toolkit's DB declares its own `@schema`,
+  models only its tables, and runs its own migrate/verify against that scope.
+- **`identity.reference @constraintName`** pins a foreign-key constraint name so the
+  metadata can match an existing DB's naming convention without a destructive
+  rename.
+
 ## Not yet shipped
 
-Triggers, generated columns, partial/exclusion/check constraints, MySQL, and data
+Triggers, generated columns, exclusion + CHECK constraints, MySQL, and data
 migrations (column-type changes needing data transformation error out with a hint).
+(Partial + descending **indexes** *are* supported — see Index modeling above.)

metaobjects-0.11.0/src/metaobjects/apidocs/__init__.py

@@ -0,0 +1,91 @@
+"""Python native SDK / API-reference docs (the ``api/python`` surface).
+
+Tier-1, idiomatic per-language reference for the generated Python SDK (Pydantic
+model / FastAPI routes / repository ``Protocol`` data-access / validation /
+extractor / render helper / payload / output-format prompt / output parser /
+filter allowlist). Accurate-by-construction: every documented symbol name comes
+from the :mod:`metaobjects.apidocs.naming` seam — the SAME seam the real
+generators delegate to — so docs can never claim a name the generators do not
+emit. Distinct from the model docs (Tier-2, neutral, TS-owned). See
+``docs/superpowers/specs/2026-06-13-cross-port-sdk-docs-conformance-design.md``.
+
+The builder / renderer symbols are exposed lazily (via :pep:`562` module
+``__getattr__``) so that a generator importing the lightweight
+:mod:`metaobjects.apidocs.naming` seam does NOT pull in the builder (which imports
+those same generators) — that would be a circular import at module-init time.
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+# Path math is leaf-level (no generator imports) — safe to expose eagerly.
+from metaobjects.apidocs.paths import (
+    Layout,
+    doc_page_output_path,
+    model_cross_href,
+    package_to_path,
+    surface_cross_href,
+)
+
+if TYPE_CHECKING:  # pragma: no cover - import-time only for type checkers
+    from metaobjects.apidocs.api_model import (
+        ApiModel,
+        ApiSymbol,
+        ApiSymbolKind,
+        ApiUnit,
+        FieldShape,
+        UnitExample,
+    )
+    from metaobjects.apidocs.builder import PythonApiModelBuilder, build_api_model
+    from metaobjects.apidocs.renderer import (
+        PythonApiDocsRenderer,
+        render_agent_api,
+        render_index,
+        render_unit_page,
+    )
+
+# Lazily-resolved exports → their defining submodule.
+_LAZY: dict[str, str] = {
+    "ApiModel": "api_model",
+    "ApiSymbol": "api_model",
+    "ApiSymbolKind": "api_model",
+    "ApiUnit": "api_model",
+    "FieldShape": "api_model",
+    "UnitExample": "api_model",
+    "PythonApiModelBuilder": "builder",
+    "build_api_model": "builder",
+    "PythonApiDocsRenderer": "renderer",
+    "render_unit_page": "renderer",
+    "render_index": "renderer",
+    "render_agent_api": "renderer",
+}
+
+__all__ = [
+    "ApiModel",
+    "ApiSymbol",
+    "ApiSymbolKind",
+    "ApiUnit",
+    "FieldShape",
+    "UnitExample",
+    "PythonApiModelBuilder",
+    "build_api_model",
+    "PythonApiDocsRenderer",
+    "render_unit_page",
+    "render_index",
+    "render_agent_api",
+    "Layout",
+    "doc_page_output_path",
+    "model_cross_href",
+    "package_to_path",
+    "surface_cross_href",
+]
+
+
+def __getattr__(name: str) -> Any:
+    submodule = _LAZY.get(name)
+    if submodule is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    import importlib
+
+    mod = importlib.import_module(f"{__name__}.{submodule}")
+    return getattr(mod, name)

metaobjects-0.11.0/src/metaobjects/apidocs/api_model.py

@@ -0,0 +1,111 @@
+"""The Python native SDK api-surface IR (intermediate representation).
+
+Mirrors the Java ``JavaApiModel`` IR (server/java/.../apidocs), the C#
+``CSharpApiModel``, and the TS ``api-model.ts``, idiomatic to the Python
+(Pydantic / FastAPI / ObjectManager) generated surface: Pydantic model /
+``ObjectManager`` data-access / FastAPI routes / validation / extractor /
+render helper / payload model / output-format prompt / output parser / filter
+allowlist.
+
+NAMES on every symbol come from the :mod:`metaobjects.apidocs.naming` seam (never
+re-concatenated in the builder), so what this model documents == what the real
+generators emit.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class ApiSymbolKind(str, Enum):
+    """The generated-category axis a documented symbol belongs to (Python /
+    Pydantic + FastAPI flavored)."""
+
+    #: The Pydantic v2 model class (entity) or value-object model.
+    MODEL = "model"
+    #: Data access — the consumer-implemented repository ``Protocol`` seam.
+    DATA_ACCESS = "data_access"
+    #: A FastAPI route (named ``"VERB path"``).
+    REST = "rest"
+    #: Pydantic field validation on the create/update shape.
+    VALIDATION = "validation"
+    #: The tolerant + strict extractor for a template payload.
+    EXTRACTOR = "extractor"
+    #: The typed render helper wrapping the render engine.
+    RENDER = "render"
+    #: The typed payload model bound to a template.
+    PAYLOAD = "payload"
+    #: The output-format prompt fragment.
+    PROMPT = "prompt"
+    #: The output parser (``parse_*``) back into the typed payload.
+    OUTPUT_PARSER = "output_parser"
+    #: The per-entity sort/filter allowlist.
+    FILTER = "filter"
+
+
+@dataclass(frozen=True)
+class FieldShape:
+    """A documented field: name + Python type + optionality + an optional note
+    (e.g. enum values)."""
+
+    name: str
+    type: str
+    optional: bool
+    note: str | None = None
+
+
+@dataclass(frozen=True)
+class UnitExample:
+    """A worked example for a unit (reserved for later phases; carried for
+    cross-port IR parity)."""
+
+    title: str
+    code: str
+
+
+@dataclass(frozen=True)
+class ApiSymbol:
+    """One documented symbol of the generated Python SDK surface.
+
+    :param name: the emitted Python identifier (or ``"VERB path"`` for a REST route).
+    :param kind: which generated category this symbol belongs to.
+    :param module: the import line / module path the symbol lives in.
+    :param signature: a human-readable Python signature line.
+    :param usage: a one-line "what you use this for".
+    :param returns: the symbol's return surface, or ``None``.
+    :param fields: per-field shapes for model/validation/payload symbols (may be empty).
+    """
+
+    name: str
+    kind: ApiSymbolKind
+    module: str
+    signature: str
+    usage: str
+    returns: str | None = None
+    fields: list[FieldShape] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class ApiUnit:
+    """One documented unit (an entity / value object, or a template) + its symbols.
+
+    :param node: the unit's short name (the doc-page basename).
+    :param package: the unit's metadata package (e.g. ``acme::shop``).
+    :param kind: ``"entity"`` | ``"value"`` | ``"template"``.
+    :param symbols: the documented symbols, in canonical IR order.
+    :param example: an optional unit-level worked example (reserved).
+    """
+
+    node: str
+    package: str
+    kind: str
+    symbols: list[ApiSymbol]
+    example: UnitExample | None = None
+
+
+@dataclass(frozen=True)
+class ApiModel:
+    """The full per-project Python SDK api surface IR."""
+
+    project: str
+    units: list[ApiUnit]