spec: FR-021/022/023 design sketches — api metadata, contract emitters, metadata packages

FR-021: declared api surfaces (operations + protocol bindings) over the
derived-CRUD default; payloads are object.value projections (origin.*); wire-
stable wireId numbering on the contract projection, never the entity.
FR-022: Tier-2 contract emitters — JSON Schema 2020-12 (canonical + strict
structured-output profile) -> OpenAPI 3.1 -> proto3 (AIP CRUD services,
locked type mappings, buf breaking as the wire-compat CI gate).
FR-023: metadata packages — code-free versioned artifacts via npm/Maven/PyPI/
NuGet, metadataDependencies config, cross-package overlay/extends with
provenance attribution. All three added to roadmap Planned.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: dmealing

docs/superpowers/specs/2026-06-11-fr-021-api-metadata-and-contract-projections-design.md

@@ -0,0 +1,107 @@
+# FR-021 — `api` metadata type + contract projections (design)
+
+_Status: PROPOSED (design sketch — needs brainstorming + plan before implementation)._
+_Date: 2026-06-11._
+
+## Problem
+
+The generated REST surface is **convention-derived**: FR-008/FR-009 define a cross-port
+CRUD contract (routes, filter grammar, pagination) computed from each entity. That covers
+CRUD well, but three needs have no declared home:
+
+1. **Non-CRUD operations** (RPC-shaped actions, batch ops, domain verbs) — today they are
+   hand-written outside the metadata, invisible to `verify` and to doc/contract emitters.
+2. **Versioned wire contracts** — an API surface that must stay stable while the domain
+   entities evolve (v1 and v2 served simultaneously over the same entities).
+3. **Contract emission** (FR-022: JSON Schema / OpenAPI / protobuf) — emitters need a
+   declared operation surface and, for protobuf, **wire-stable field numbering**, which
+   must not live on domain entities (it would couple domain evolution to wire compat).
+
+## Design direction
+
+### 1. API payloads are projections (reuse, don't invent)
+
+An operation's input/output references an `object.value` VO whose fields carry the
+existing `origin.*` provenance (`passthrough` / `aggregate` / `collection`) from entities
+— the **same projection machinery** that already drives prompt payloads (FR-004) and DB
+views (FR-003). The entity stays domain truth; the API projection is the contract surface.
+Renaming an entity field re-points (or breaks) the projection's `origin.*`, which `meta
+verify` catches at build time — the wire shape never silently changes.
+
+### 2. New metamodel vocabulary (provider-registered, ADR-0023)
+
+Slim sketch (names to be settled in brainstorming):
+
+```yaml
+api:                       # new top-level type; protocol-neutral surface
+  name: ProgramApi
+  version: v1              # bare attr; versioned surfaces = sibling api nodes
+  children:
+    - operation:           # subtypes: query | command (read vs write semantics)
+        name: getProgram
+        inputRef: ProgramIdParam     # object.value projection (or none)
+        outputRef: ProgramSummary    # object.value projection
+        children:
+          - binding.rest: { method: GET, path: "/programs/{id}" }
+          # future: binding.grpc, binding.messaging — per-protocol bindings
+```
+
+- **Derived CRUD stays the zero-config default.** With no `api` declared, FR-008/009
+  behavior is unchanged. A declared `api` *extends* (or, per entity opt-in, replaces)
+  the derived surface. Emitters consume the union.
+- `binding.*` keeps the surface protocol-neutral with per-protocol attrs where they
+  belong (REST method/path now; gRPC service/method naming later).
+
+### 3. Wire-stable numbering lives on the contract projection
+
+protobuf field numbers identify fields **on the wire**; renumbering silently misdecodes
+(it is equivalent to delete+add). Numbers therefore must be **authored, append-only
+metadata** — they genuinely cannot be computed from the model across schema evolution,
+which is the ADR-0023 "cannot be computed" justification recorded here.
+
+- `wireId: <n>` on fields of an `object.value` used as a contract projection (and
+  `wireId` on `field.enum` members where the enum crosses the wire). Protocol-neutral
+  name on purpose: protobuf consumes it now; Avro/Thrift-style emitters could later.
+- `reservedWireIds: [..]` + `reservedWireNames: [..]` on the VO — emitted as proto
+  `reserved` so deleted fields can never be reused.
+- Validation (loader, own-only): duplicate `wireId` in one VO → `ERR_BAD_ATTR_VALUE`;
+  `wireId` outside 1..536870911 or in 19000..19999 → `ERR_BAD_ATTR_VALUE`; a VO
+  referenced by a proto-bound operation with any field missing `wireId` → emit-time
+  error in FR-022 (not a load error — VOs without proto bindings don't need numbers).
+- Precedent: TypeSpec's protobuf emitter requires `@field(n)`; entproto requires
+  `entproto.Field(n)`. Auto-numbering from declaration order is explicitly rejected
+  (insert/rename/delete renumbers the tail = wire break).
+
+### 4. Relationship to the enterprise tier
+
+Application/ecosystem/dependency-level modeling (which org unit owns which API, what
+consumes what) is intentionally **out of scope** for this library — `api` here is the
+slim contract vocabulary only. An organization-level metadata tier can layer on top via
+the provider SPI without changes here.
+
+## Conformance + verify
+
+- New `fixtures/conformance/` fixtures: api/operation/binding loading, wireId validation
+  errors, projection-ref resolution errors (`format: "resolved"` envelopes).
+- `meta verify --templates`-style gate extended: operation input/output refs must
+  resolve; projections' `origin.*` must resolve against entities (existing machinery).
+- Registry-conformance manifest gains the new vocabulary in all 5 ports (atomic, like
+  the `@responseRef` carve-out close).
+
+## Open questions (settle in brainstorming)
+
+1. Operation vocabulary: AIP-style five standard methods + custom, or free-form
+   query/command only?
+2. Pagination style per surface: the FR-008 `limit/offset` contract vs AIP
+   `page_size/page_token` when emitting proto services — per-binding attr?
+3. Does `endpoint` (a node per HTTP route) deserve first-class existence, or is
+   `operation` + `binding.rest` sufficient? (Lean: the latter — fewer types.)
+4. Versioning semantics: sibling `api` nodes (v1, v2) vs `@version` on operations.
+5. Can a contract projection ALSO be a DB view projection (one VO, two consumers), or
+   should that be discouraged by validation?
+
+## Dependencies / consumers
+
+- Consumes: `object.value` + `origin.*` (shipped), provider SPI (shipped).
+- Consumed by: FR-022 contract emitters; generated API docs (`meta docs` api surface);
+  future MCP exposure (declared operations become discoverable tools).

docs/superpowers/specs/2026-06-11-fr-022-contract-emitters-design.md

@@ -0,0 +1,95 @@
+# FR-022 — Contract emitters: JSON Schema → OpenAPI 3.1 → protobuf (design)
+
+_Status: PROPOSED (design sketch — needs brainstorming + plan before implementation)._
+_Date: 2026-06-11._
+
+## Problem
+
+Adopters keep their existing contract ecosystems: validation tooling wants JSON Schema,
+REST consumers want OpenAPI, gRPC shops want `.proto`. Today MetaObjects generates the
+*implementation* (routes, models) but not the *neutral contract artifacts*, so adopters
+hand-write them — a drift surface the metadata fully describes (raison-d'être violation).
+
+## Design direction
+
+All three emitters are **Tier-2** per ADR-0020 (output bytes don't depend on the
+implementing language → ONE shared TS engine + golden-file conformance fixtures), wired
+as ordinary generators (stable names in the generator registry, `gen --list`). They are
+**one layered investment**, built in this order:
+
+### Phase 1 — JSON Schema 2020-12, two profiles
+
+- `jsonSchemaFile()` — per-entity / per-projection `<Name>.schema.json`:
+  - **Canonical profile**: full fidelity. `$defs` for shared abstracts, `format:
+    uuid/date-time/...`, `field.enum @values` → `enum`, currency → integer minor units
+    (description carries the ISO code), wire-contract-faithful types (decimal as string,
+    int64 as string — must match `normalization.md` exactly or the emitter itself becomes
+    a drift source; conformance-gated).
+  - **Strict profile** (`profile: "strict"`): the cross-provider structured-output
+    intersection — root `type: object`; every property `required` with `["T","null"]`
+    unions for optionals; `additionalProperties: false` everywhere; **no recursion**; no
+    numeric/length constraint keywords (`@maxChars` etc. become `description` prose).
+    This one artifact serves OpenAI strict mode, Anthropic structured outputs, and MCP
+    hosts with restricted schema subsets.
+- Consumers unlocked: validators in every language, MCP `inputSchema`, LLM
+  structured-output schemas, OpenAPI components (Phase 2), schema-registry JSON mode,
+  quicktype-class codegen for languages without a MetaObjects port.
+
+### Phase 2 — OpenAPI 3.1
+
+- `openapiFile()` — one document describing the generated REST surface
+  (accurate-by-construction: derived-CRUD routes + FR-021 declared operations), with
+  `components.schemas` = Phase 1 canonical output (OpenAPI 3.1 schemas ARE JSON Schema
+  2020-12). Covers: CRUD paths, the bracketed filter grammar + operator-per-subtype
+  gating, sort/limit/offset (+`withCount`), M:N traversal routes, error envelopes.
+- `meta verify` gains a spec↔routes drift check (regen-to-temp diff, like `--codegen`).
+- Emit 3.1 canonical; optional 3.0-downlevel flag (consumer tooling lag is real —
+  evaluate per demand).
+- Multiplier: openapi-generator / Kiota / orval turn the document into client SDKs in
+  languages MetaObjects doesn't port.
+
+### Phase 3 — protobuf (proto3)
+
+- `protoFile()` — `.proto` per package + AIP-style CRUD services (Get/List/Create/
+  Update/Delete + FR-021 custom operations) with `google.api.http` annotations (REST
+  transcoding / gRPC-Gateway / Connect-compatible).
+- **Field numbers come from FR-021 `wireId`** (required on proto-bound projections;
+  emit-time error if missing). `reservedWireIds/Names` → `reserved` statements.
+- Type mapping (locked by research; conformance-gated):
+  long→`int64` (ProtoJSON already strings 64-bit — matches our wire contract) ·
+  decimal→`google.type.Decimal` (string-valued) · currency→`int64` minor units (NOT
+  `google.type.Money` — Money is units+nanos, a different contract; offer Money only as
+  an opt-in with explicit conversion) · uuid→`string` (never `bytes`: endianness
+  hazards) · timestamp→`google.protobuf.Timestamp` (UTC) · date/time→`google.type.Date`
+  / `TimeOfDay` · nullable→proto3 `optional` (never wrapper types) · enum→synthesized
+  `<ENUM>_UNSPECIFIED = 0` zero value + prefixed member names + member `wireId`s ·
+  `field.object @storage: jsonb`→`google.protobuf.Struct`, flattened/subdocument→nested
+  message · arrays→`repeated`.
+- **CI gate**: document (and scaffold in `meta init` recipes) `buf breaking
+  --against` on the emitted, committed protos (WIRE_JSON category) — wire-compat
+  regression detection is inherited from buf rather than re-implemented.
+- Explicit non-goals: no runtime descriptor construction in this FR (per-language
+  descriptor APIs are uneven — notably no dynamic message support in one major port
+  ecosystem) and no gRPC *server* codegen — adopters run protoc/buf on the emitted
+  contract with their existing toolchains.
+
+## Conformance
+
+New `fixtures/contract-conformance/` (or per-emitter fixture trees): golden emitted
+artifacts byte-gated from shared input metadata; strict-profile outputs validated
+against provider schema-subset rules; proto outputs additionally `buf lint`/`buf
+breaking`-clean in CI.
+
+## Open questions
+
+1. Package/file layout for emitted artifacts (per-entity vs per-package files; where in
+   `targets` they land).
+2. OpenAPI security schemes: out of metadata scope (config passthrough?) or modeled?
+3. Whether Phase-1 strict profile needs per-provider sub-variants or one intersection
+   profile suffices (start: one).
+4. proto package naming + `option java_package` etc. mapping from `::` packages.
+
+## Dependencies
+
+- FR-021 (declared operations + `wireId`) for Phase 3 and for non-CRUD coverage in
+  Phase 2; Phases 1–2 are useful with derived CRUD alone and can ship first.

docs/superpowers/specs/2026-06-11-fr-023-metadata-packages-design.md

@@ -0,0 +1,109 @@
+# FR-023 — Metadata packages: cross-repo distribution + reuse (design)
+
+_Status: PROPOSED (design sketch — needs brainstorming + plan before implementation)._
+_Date: 2026-06-11._
+
+## Problem
+
+The core polyglot workflow is: a **shared base model** (common entities, abstracts,
+enums, validation) maintained once, consumed by many downstream apps **in different
+languages and different repos**, each augmenting it locally via `extends` and overlays.
+
+The loader mechanics for this already ship — `MetaDataSource` composition
+(directory/file/URI/in-memory) and overlay merge by `package`+`name` with per-node
+source attribution work across arbitrarily many sources. What's missing is the
+**convention**: how a shared model is packaged, versioned, published, resolved, and
+declared by a consumer in each language ecosystem. Today it's hand-wired glue (point a
+source at a checked-out path); it should be a one-liner.
+
+## Design direction
+
+### 1. The metadata package artifact
+
+A metadata package is a **code-free artifact** containing:
+
+```
+metaobjects/                  # the standard tree (canonical JSON and/or YAML)
+  meta.common.json
+  meta.commerce.json
+metaobjects.pkg.json          # manifest: name, version, exported metamodel packages,
+                              # provider requirements (custom types it depends on)
+```
+
+Published through each ecosystem's normal registry — npm / Maven Central / PyPI / NuGet
+— as an ordinary versioned dependency. No runtime code inside; it is data. (One
+artifact CAN be published to multiple registries from one source repo — recipe, not
+mechanism.)
+
+### 2. Consumer declaration (per-port resolution, one shared semantic)
+
+`.metaobjects/config.json` (the JSON config, parseable by all tooling) gains:
+
+```jsonc
+{ "metadataDependencies": [
+    { "package": "@acme/common-model", "version": "^2.1.0" }   // resolved per ecosystem
+]}
+```
+
+- **TS/Node**: resolve via `node_modules/<pkg>/metaobjects/`.
+- **Java/Kotlin**: a Maven/Gradle dependency whose jar carries `metaobjects/` as a
+  classpath resource; the Maven plugin resolves and feeds it to the loader (classpath
+  resource loading is the JVM-native path).
+- **Python**: package-data path via `importlib.resources`.
+- **C#**: NuGet `contentFiles` path.
+- The loader composes: dependency sources first (in declared order), local
+  `metaobjects/**` last — so local overlays win last-writer-wins attr conflicts,
+  matching existing overlay semantics. Provenance attribution records the contributing
+  package+version on every node (extends FR-5c attribution).
+
+### 3. Semantics + guardrails
+
+- `extends` and overlays work across package boundaries exactly as across files
+  (existing behavior — conformance-gated with new cross-package fixtures).
+- **Same-package-name collision** between two dependencies → load error
+  (`ERR_DUPLICATE_DECLARATION` escalated from warn when sources are different
+  dependencies and the merge is not a declared overlay) — settle exact rule in
+  brainstorming.
+- Custom-type requirements: the manifest names required providers; loading a package
+  without its providers registered fails with the existing provider error codes
+  (ADR-0023 strictness preserved — a metadata package cannot smuggle vocabulary in).
+- Version conflicts (two apps want different shared-model versions) are the consuming
+  ecosystem's resolver problem (npm/Maven semantics), not re-solved here; the manifest
+  version is recorded in attribution for drift forensics.
+- `meta verify` reports per-dependency provenance (which package contributed what) so
+  a shared-model upgrade that changes downstream codegen is attributable.
+
+### 4. What this is NOT
+
+- Not a hosted registry or remote-fetch protocol — resolution rides each language's
+  package manager; the loader still only reads local files/resources at build time.
+- Not runtime schema distribution — this FR is about build-time model reuse. (Runtime
+  loading from other sources already exists via `MetaDataSource`; conventions for that
+  are out of scope here.)
+
+## Conformance
+
+- New cross-package fixtures in `fixtures/conformance/`: dependency-then-local overlay
+  merge order, cross-package `extends`, collision errors, provider-requirement errors,
+  attribution shape. All 5 ports load the same fixture "packages" (as plain dirs in the
+  corpus) — the per-ecosystem resolution is port-specific glue tested per port.
+
+## Open questions
+
+1. Manifest shape + name (`metaobjects.pkg.json`?) and whether the manifest is required
+   (lean: required for dependencies, absent for apps).
+2. Exact collision/override rules between two dependencies (vs dependency→local, which
+   is settled: local wins).
+3. Lockfile story: rely on ecosystem lockfiles only, or record resolved versions in
+   `.metaobjects/` state for cross-tool reproducibility?
+4. YAML vs canonical JSON inside published packages (lean: canonical JSON only —
+   interchange form, no desugar variance).
+5. `meta init` scaffold for *authoring* a metadata package (publish workflows per
+   registry).
+
+## Dependencies / consumers
+
+- Consumes: `MetaDataSource` composition + overlay/extends + FR-5c attribution (all
+  shipped).
+- Consumed by: every multi-repo adopter; future organization-level tooling can build on
+  the same manifest.

spec/roadmap.md

@@ -74,6 +74,9 @@ _Last refreshed 2026-05-30._
 
 - **FR-019 — Shared + externally-provided enums.** Stop redeclaring a `field.enum` inline in every consuming entity: a package-level abstract `field.enum` materializes ONE standalone enum type per port (the existing D6 `extends` reuse vocabulary), and **`@provided: true`** — a provenance flag on the named-type *declaration* (not the field), shared cross-type with value objects — references an existing hand-written type instead of emitting one (per-port namespace via codegen config, never a metadata FQN — retires the C#-only `@csEnumType`). Decision in [ADR-0026](decisions/ADR-0026-shared-and-provided-named-types.md); implementation spec `docs/superpowers/specs/2026-06-06-fr-019-shared-and-provided-enums-design.md`. (Generators are now subclass-extensible across all 5 ports, so this lands on open seams.)
 - **MCP exposure of declared prompts/tools** — the remaining library-side piece of the prompt-construction pillar. Surface a `template.output` / tool declaration over the Model Context Protocol (model-agnostic) so an LLM host can discover + register it, built on the shipped render / payload / verify / FR-006 / FR-010 primitives. Designed in `docs/superpowers/specs/2026-05-22-fr-004-cross-language-prompt-construction-design.md`.
+- **FR-021 — `api` metadata type + contract projections.** Declared API surfaces (operations + per-protocol bindings) over the derived-CRUD default; operation payloads are `object.value` projections (the same `origin.*` machinery as prompts and views); wire-stable `wireId` numbering lives on the contract projection (never the entity) so domain evolution can't break wire compat. Design sketch: `docs/superpowers/specs/2026-06-11-fr-021-api-metadata-and-contract-projections-design.md`.
+- **FR-022 — Contract emitters (Tier-2): JSON Schema 2020-12 (canonical + strict structured-output profile) → OpenAPI 3.1 → protobuf.** One shared neutral engine per ADR-0020; strict profile targets the cross-provider structured-output intersection (also MCP input schemas); proto emission consumes FR-021 `wireId`s, maps types per the locked table (Decimal/minor-units/uuid-string/optional/UNSPECIFIED-enum-zero), and inherits wire-compat regression detection via `buf breaking` on the emitted artifacts. Design sketch: `docs/superpowers/specs/2026-06-11-fr-022-contract-emitters-design.md`.
+- **FR-023 — Metadata packages: cross-repo distribution + reuse.** A code-free, versioned artifact (the `metaobjects/` tree + manifest) published through each ecosystem's registry (npm/Maven/PyPI/NuGet) and declared via `metadataDependencies` in config; loader source composition + overlay/extends across package boundaries (mechanics already shipped) with dependency-then-local merge order, collision rules, and per-package provenance attribution. Design sketch: `docs/superpowers/specs/2026-06-11-fr-023-metadata-packages-design.md`.
 
 ### Tracked outside this library repo (not roadmap work here)