feat(fr-023): metadata dependencies — declare, sync, and build on a shared model (Phase 1a)

AGENTS.md

@@ -66,7 +66,7 @@ PyPI has had no product change since `0.25.0` — nothing is broken.
 - **Kotlin** — `codegen-kotlin` (KotlinPoet on JVM): entity + Exposed table + Spring controller + payload + relations + filter allowlist + validator + stored-proc + output-parser generators. `integration-tests-kotlin` runs the persistence-conformance corpus through Exposed against Testcontainers Postgres.
 
 **Cross-port conformance corpora** (every port runs the shared corpus):
-- Metamodel: `fixtures/conformance/` (313 fixtures; 21 shared corpora in total — per-corpus counts + the corpus x port matrix live in `docs/CONFORMANCE.md`). TS / C# / Java / Python all green.
+- Metamodel: `fixtures/conformance/` (314 fixtures; 22 shared corpora in total — per-corpus counts + the corpus x port matrix live in `docs/CONFORMANCE.md`). TS / C# / Java / Python all green.
 - Render: `fixtures/render-conformance/`. TS / C# / Java / Kotlin / Python byte-identical.
 - Persistence: `fixtures/persistence-conformance/`. **Query** scenarios run on every port (TS / C# / Java / Kotlin / Python), each provisioning its test DB by executing the committed, TS-produced `canonical/schema.postgres.sql` (Postgres only — Derby dropped for the cross-port query corpus, ADR-0015). The **migration** scenarios are exercised by **TS only** (TS owns schema migrations). **The corpus now gates WRITES, not just reads (SP-H):** an `op: roundtrip` scenario type INSERTs through each port's runtime/ORM write codec (NOT raw SQL), reads the row back, and asserts the wire-normalized value. The `AllTypes` entity (`roundtrip-all-types.yaml`) carries one field of **every** persistable `field.*` subtype — string/int/long/double/float/decimal/boolean/date/time/timestamp(+tz)/currency/enum/uuid/object — plus an **array-of-VO** `field.object @isArray @storage:jsonb` column (`labels`, written as 2-element / empty-`[]` / single-element arrays across the three rows) — so every subtype write+read (incl. the array-of-value-object jsonb codec) round-trips through every port against Testcontainers PG. (`field.byte`/`field.short`/`field.class` were cut as non-functional registration-only stubs — the matrix tracks only genuinely-supported subtypes; see `fixtures/registry-conformance/README.md` → "Per-subtype write-round-trip matrix".)
 - API-contract: `fixtures/api-contract-conformance/`. TS / C# / Java / Kotlin / Python all green — each port runs **two lanes**: a hand-rolled reference server AND its **generated** API artifact booted over HTTP (the deployed controller/routes; TS+C# full-stack vs Testcontainers PG, Java/Kotlin/Python generated controller + in-memory repo behind the consumer seam). The generated fan-out found 10 real deployment bugs golden snapshots missed.
@@ -288,11 +288,17 @@ File-naming: `meta.<concept>.json`. Each file declares its `package`:
 ```
 metaobjects/
 ├── meta.user.json                     # STRUCTURAL (always present)
-├── meta.user.ui.json                  # UI overlay (views, layouts)
-└── meta.user.db.json                  # DB overlay (sources, dbColumns)
+├── meta.user.ui.json                  # UI overlay (views, layouts) — overlay: true
+└── meta.user.db.json                  # DB overlay (sources, dbColumns) — overlay: true
 ```
 
-All three share the same `package` and object `name`. The Loader merges them. Use only when team-level concerns justify the file proliferation. Default to single-file-per-domain.
+All three share the same `package` and object `name`. The Loader merges them. `meta.user.ui.json`
+and `meta.user.db.json`'s top-level object declaration must carry `overlay: true`: the loader's
+merge doesn't require it (a same-`(type, name)` redeclaration merges either way), but leaving it
+off is exactly what `meta verify`'s overlay authoring lint (`docs/features/metadata-dependencies.md`)
+flags as advisory — and it's what would turn a renamed/removed `User` into a silent second object
+instead of a loud `ERR_OVERLAY_NO_TARGET`. Use only when team-level concerns justify the file
+proliferation. Default to single-file-per-domain.
 
 **`BaseEntity` pattern**: shared abstract bases live in `meta.common.json`. Concrete entities use `extends: "BaseEntity"` to inherit `id` + `createdAt` without redeclaring.
 

CHANGELOG.md

@@ -10,6 +10,106 @@ here.**
 
 ## [Unreleased]
 
+### Added
+
+- **Metadata dependencies (FR-023, Phase 1a — TypeScript + Python).** A project can
+  now build on a metadata model published by another repository or package instead
+  of copy-pasting it:
+  - **`dependencies`** in `.metaobjects/config.json` — `[{ name, path }]` today (the
+    `npm`/`python` transport keys are reserved in the schema and refused by `sync`
+    with `ERR_DEPENDENCY_UNRESOLVED`, "not supported by this toolchain yet").
+  - **`meta deps sync [<name>…] [--dry-run]` / `meta deps check` / `meta deps
+    list`** — `sync` resolves each dependency's `path`, validates its manifest and
+    artifact hash, re-loads the artifact standalone with core providers, and writes
+    the committed snapshot (`.metaobjects/deps/<name>/`) + lock
+    (`.metaobjects/deps.lock.json`); `check` compares the currently-installed
+    artifact's hash against the lock, read-only; `list` prints the lock.
+  - **`verify --deps`** — the same drift comparison as `meta deps check`, as a
+    gated `verify` subverb (needs the publisher's `path` reachable, so it is never
+    part of the bare-`verify` default). `drifted` or `unresolved` fails with the new
+    `ERR_DEPENDENCY_UPSTREAM_DRIFT`.
+  - **`sharedModelFile()`** (`@metaobjectsdev/codegen-ts`) — the publisher-side
+    generator: selects a subset of a project's own metadata by the `scope`
+    pattern grammar, closure-checks it, and emits one canonical-JSON artifact +
+    `metaobjects.pkg.json` manifest. Registered and discoverable (`meta gen
+    --list`), but deliberately **not** offered by `meta eject --list` — the
+    artifact is a contract whose bytes a cross-port corpus pins and whose hash
+    consumers verify, so a user-owned editable copy would invite a silent break.
+  - **An overlay authoring lint** in `meta verify` — advisory, runs on every
+    invocation (no subverb): a top-level `(type, resolutionKey)` declared in two or
+    more collection files (dependency artifacts included) where more than one
+    declaration lacks `overlay: true`. Never fails the build; mute with
+    `--no-overlay-lint` / `META_NO_OVERLAY_LINT=1`.
+  - **`ERR_DEPENDENCY_PACKAGE_NOT_OWNED`** — a project may `extends` or `overlay:
+    true` a dependency's node freely, but declaring a *brand-new* top-level node
+    into a package a dependency owns is refused by name, naming the fix.
+  - New error codes altogether: `ERR_DEPENDENCY_UNRESOLVED`,
+    `ERR_DEPENDENCY_MANIFEST_INVALID`, `ERR_DEPENDENCY_SNAPSHOT_STALE`,
+    `ERR_DEPENDENCY_NODE_COLLISION`, `ERR_DEPENDENCY_METAMODEL_INCOMPATIBLE`,
+    `ERR_DEPENDENCY_UPSTREAM_DRIFT`, `ERR_DEPENDENCY_PACKAGE_NOT_OWNED`.
+  - New exports: `declaredTopLevelKeys` (`@metaobjectsdev/metadata` — the raw,
+    pre-parse walk the overlay lint and the loader's own overlay-only partition
+    share) and `serializeSharedDocument` (the canonical shared-artifact
+    serializer `sharedModelFile()` targets; Python's `serialize_shared_document`
+    is byte-identical, though Python has no publisher CLI wired to it yet —
+    `sharedModelFile()` itself is TypeScript-only in Phase 1a). `FileSource`'s
+    constructor takes an optional `{ id }`, so a dependency's synced snapshot
+    loads with `dep:<name>/<artifact>` provenance instead of reading like a
+    local file.
+  - Deliberately **not** built in Phase 1a — see `docs/features/metadata-dependencies.md`
+    ("Deferred"): the `npm`/`python`/`maven`/`nuget` transports, a local
+    co-development override, a usage-aware breaking-change classifier, cross-boundary
+    codegen imports (`packageBindings`), a runtime `ObjectManager` scope predicate,
+    and Java/Kotlin/C# as dependency consumers or publishers (Phase 2).
+  - No registered vocabulary changed — `metamodelVersion` stays `1.0`.
+    Docs: `docs/features/metadata-dependencies.md`. Corpus:
+    `fixtures/dependency-conformance/` (23 cases, TS + Python).
+
+### Changed
+
+- **A project that declares `scope.include` now sees its requirements-ledger
+  denominator narrow to that scope — even with zero dependencies.** The ledger's
+  ["coverable" object count](docs/features/requirements.md) is computed by
+  `Collection.inScope`, which is `matchesScope(fqn, scope) && …` regardless of
+  whether the project has any `dependencies` at all. Previously the ledger counted
+  every non-abstract entity in the loaded model; a project that scopes its own
+  codegen with `scope.include` now has its ledger coverage counted only over that
+  declared scope too. This is a real behavior change for an existing project that
+  already declares `scope.include` and reads its `meta verify` coverage numbers —
+  they may drop even though nothing was deleted.
+- **`meta verify` now runs the overlay authoring lint for EVERY project, not just
+  one with `dependencies` declared.** `runOverlayLintAdvisory()` is unconditional —
+  it lints `collection.files`, which for a zero-dependency project is simply its
+  own files — so a project with no dependencies at all, but with a top-level
+  `(type, resolutionKey)` redeclared across two or more of its own files (e.g. the
+  ["Optional layered overlay pattern"](AGENTS.md) — a `meta.user.json` +
+  `meta.user.ui.json` + `meta.user.db.json` split), now gets new advisory
+  `WARN_OVERLAY_IMPLICIT` output on `meta verify` it did not get before this
+  release. Advisory only — never fails the build, mute with `--no-overlay-lint` /
+  `META_NO_OVERLAY_LINT=1` — but this is a second, real carve-out from "a project
+  with no dependencies behaves identically," alongside the ledger-denominator one
+  above.
+- **`Collection`** (`@metaobjectsdev/sdk`) gains `dependencies`, `ownFiles`,
+  `fileIds`, `importedPackages`, `importedNodes`, `imported(fqn)`,
+  `declaredMigrateScope`; `inScope` and `inMigrateScope` are now the COMPOSED
+  predicates described above (default-exclusion of imported metadata) — byte-for-byte
+  identical to their prior behavior for a project with no `dependencies` and no
+  declared `scope`/`migrate.scope`.
+- **The scope-pattern grammar (`compileScope`/`matchesScope`/`compilePattern`)
+  moved from `@metaobjectsdev/sdk` to `@metaobjectsdev/metadata`** — pure,
+  browser-safe string code, so `@metaobjectsdev/codegen-ts` (the `sharedModelFile()`
+  publisher side) can use it without a `sdk` dependency. `sdk` re-exports it
+  unchanged; existing importers of `compileScope`/`matchesScope` from `sdk` are
+  unaffected.
+- **`scopeExpectedSchema`** (`@metaobjectsdev/migrate-ts`) takes a third, optional
+  `{ imported }` argument: an imported object the scope does not admit is removed
+  from the *expected* schema before `declaredSchemas` is computed — so importing a
+  table-backed entity can never turn the publisher's other tables into `DROP`
+  candidates, and never proposes creating the imported table.
+- **`scanRequirements`** (`@metaobjectsdev/cli`) takes an optional second argument,
+  `{ coverable }` — the predicate the ledger denominator change above threads
+  through.
+
 ### Deprecated
 
 - **`@metaobjectsdev/sdk`: the v0.3 `package.meta.json` prototype and workspace discovery** —

README.md

@@ -176,8 +176,8 @@ metaobjects/
 ├── README.md                       # you are here
 ├── CLAUDE.md                       # project instructions for Claude
 ├── spec/                           # canonical metamodel docs, ADRs, roadmap
-├── fixtures/                       # 21 cross-language conformance corpora — the oracle
-│   ├── conformance/                # metamodel (loader + serializer + navigation), 313 fixtures
+├── fixtures/                       # 22 cross-language conformance corpora — the oracle
+│   ├── conformance/                # metamodel (loader + serializer + navigation), 314 fixtures
 │   ├── yaml-conformance/           # YAML authoring desugar
 │   ├── render-conformance/         # FR-004 byte-identical render oracle
 │   ├── verify-conformance/         # FR-004 template-drift gate

agent-context/skills/metaobjects-authoring/SKILL.md

@@ -1111,6 +1111,32 @@ 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.
 
+**Extending and overlaying a metadata dependency's nodes is the expected way to
+build on a shared model.** A project may declare `dependencies` in
+`.metaobjects/config.json` and `meta deps sync` a publisher's metadata into a
+committed snapshot — that snapshot loads BEFORE your own files, so a foreign
+abstract resolves via `extends` and a foreign node re-opens via `overlay: true`
+exactly like a local one. Two rules are specific to that boundary:
+
+- **Say `overlay: true` on every amendment to a node you don't own.** Within one
+  project the parser merges a same-`(type, package::name)` redeclaration whether
+  or not it carries the flag; only the flagged form fails loudly
+  (`ERR_OVERLAY_NO_TARGET`) when the target is gone. Skip the flag on a
+  dependency's node and its removal upstream silently becomes a new, disconnected
+  local object instead of a build failure — always flag a contribution to a node
+  you did not declare.
+- **A brand-new top-level node declared into a dependency's package is refused**,
+  not silently excluded: `ERR_DEPENDENCY_PACKAGE_NOT_OWNED`, naming the object,
+  the package, and the fix (declare it in your own package and `extends` the
+  dependency's node, or give it that node's exact name with `overlay: true` if you
+  meant to amend it). A *local node in your own package* is unaffected — this
+  refusal fires only for a package a dependency owns.
+
+What fails when upstream changes (a node removed/renamed, a member's shape
+changed) is the loader's existing errors, unchanged — see
+`docs/features/metadata-dependencies.md` for the full table and what `meta deps
+sync`/`verify --deps` check that the loader cannot.
+
 ## Discriminator inheritance (TPH)
 
 When several concrete entities are variants of one thing and should share a

agent-context/skills/metaobjects-codegen/SKILL.md

@@ -138,6 +138,46 @@ 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.
 
+## A dependency's metadata is load-only by default — codegen excludes it
+
+A project may declare `dependencies` in `.metaobjects/config.json` and `meta deps
+sync` a publisher's metadata into a committed snapshot (TypeScript + Python,
+Phase 1a). That snapshot's nodes load so your own model can resolve against them
+(`extends`, `overlay: true`, plain FQN references) — but codegen (and `verify
+--codegen`, and the requirements ledger's denominator) **excludes them by
+default**. A node is "imported" when its metadata *package* is one a dependency
+owns; an imported node is generated only when your own `scope.include` names that
+package **literally** (`acme::common::**` or `acme::common::Address` name
+`acme::common`; a bare `acme::**` or `**` do not — they match the package's nodes,
+which is weaker than naming it). Naming the package in `scope.include` (and, if
+you own its tables, `migrate.scope`) is how a consumer takes over a shared model —
+the "I instantiate this metadata myself" case, no separate mode needed.
+
+Running `meta gen <Name>` (or a Python `entities: [...]`) on a name that resolves
+to nothing but excluded imports is refused by name (exit 2) rather than silently
+generating nothing — the message names the dependency and the `scope.include` fix.
+
+## Publishing a shared model: `sharedModelFile()`
+
+The other side of the same feature: `@metaobjectsdev/codegen-ts` ships
+`sharedModelFile({ name, include, exclude?, files?, version?, target? })`, a
+generator a publisher wires to select a subset of its own metadata (by the same
+scope-pattern grammar as `scope`) and emit it as one canonical-JSON artifact +
+manifest — the thing a consumer's `meta deps sync` copies. It closure-checks the
+selection (every reference from a selected node must resolve to another selected
+node, or the build fails naming the pair) and re-loads the emitted artifact with
+core providers only, so a Phase 1a export needing non-core vocabulary fails at
+publish time. It is registered and shows up in `meta gen --list` like any other
+generator — but **it is deliberately not offered by `meta eject --list`** (unlike
+the four ADR-0034 scaffold-and-own generators). The artifact is a contract whose
+bytes a cross-port corpus pins and whose hash consumers verify; a user-owned,
+editable copy would invite an artifact that silently stops matching what
+consumers expect. Only TypeScript can run it in Phase 1a. **Phase 1a is TypeScript and Python
+only, full stop** — TypeScript and Python are the only two ports that can
+*consume* a dependency at all today, and only the TypeScript toolchain can
+*publish* one; Java, Kotlin, and C# do not read `dependencies` yet (Phase 2).
+Full detail: `docs/features/metadata-dependencies.md`.
+
 ## You don't have to generate everything — pick your layers
 
 Codegen is **granular and à la carte, not all-or-nothing.** The most powerful