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

[dmealing]

What & why

FR-023 Phase 1a — metadata dependencies. One project publishes its typed metadata as a flattened, hash-pinned artifact; another declares it, syncs a committed snapshot, and builds on it — extending, overlaying and referencing its nodes — while being protected from silent upstream drift.

TypeScript and Python only. Java, Kotlin and C# do not read dependencies yet; that is Phase 2.

What ships:

• Declare + sync. dependencies in .metaobjects/config.json (path transport; npm/python refused as deferred). meta deps sync validates the publisher's manifest, re-hashes its artifact, copies it to a committed snapshot under .metaobjects/deps/<name>/, and pins it in a sha256 deps.lock.json. meta deps list reports the lock.
• Load + scope. Dependency artifacts load first, under dep:<name>/<artifact> source ids, so bases precede the declarations that amend them. Imported packages are excluded from every action surface — codegen, migrate, and the requirements ledger — unless a scope.include names their package. One predicate, composed once and threaded through all three.
• Refuse what would fail silently. ERR_DEPENDENCY_PACKAGE_NOT_OWNED catches a local node declared into a dependency's package, which the package-keyed exclusion would otherwise drop from its own project's output with no error.
• Publish. sharedModelFile() emits the artifact plus its manifest. Registered and discoverable, deliberately not ejectable — it produces a contract whose bytes consumers verify.
• Detect drift. meta deps check and verify --deps re-hash the installed artifact and fail on divergence. An advisory overlay lint reports an unflagged cross-file redeclaration.
• Python port with the shared cross-port corpus runner, and a meta init cleanup that stops scaffolding the dead v0.3 package.meta.json and tracks the new dependency files.

No metamodel change: metamodelVersion stays 1.0 and expected-registry.json is untouched.

Checklist

• Tests added/updated and passing locally (TDD — test first)
• For metamodel changes: a conformance fixture was added/updated so all five ports verify it — N/A: no metamodel change. metamodelVersion unchanged at 1.0; expected-registry.json untouched; the gates lane's metamodel-version bump check reports no diff.
• No new metamodel attribute invented — none added (ADR-0023)
• Cross-language wire format & vocabulary preserved — the dependency corpus (fixtures/dependency-conformance/) runs on both consuming ports, 24 assertions each
• Named constants used for metamodel strings; no any (TS)
• Public-repo hygiene — verified by grep over the full diff and by the gates lane's leak-scan
• Docs updated — new docs/features/metadata-dependencies.md plus seven existing pages, three agent-context skills (corpus regenerated), CHANGELOG and roadmap

Notes for reviewers

Gate status. All three lanes green on this exact tree: --only ts (build+typecheck, conformance, unit, mutation gate, two real-PG suites, integration), --only python (2098 + 110), --only gates (30/30).

Process. Each of the 20 tasks (one CUT) was individually reviewed for spec compliance and quality; 19 fix rounds ran. A whole-branch review then found 1 Critical and 2 Important that per-task review structurally could not see, all fixed in one wave and re-verified.

One known residual, deliberately not fixed here. meta docs --site can still fail for a project that both mixes a fresh declaration and an imported-node overlay in the same file — violating the documented "overlay in its own file" convention — and names a dependency that sorts after its own source directory alphabetically. docs-site's loader re-sorts source dirs alphabetically and only rescues overlay-only files. This is strictly narrower than before (that path was wholly broken for any dependency); gen and verify are unaffected, since Collection.files unconditionally leads with artifacts. Two remedies, and the choice is a design call: harden the convention into a requirement, or make docs-site share Collection.files' dependency-leads ordering.

Four findings surfaced that are not this branch's to fix:

1. scripts/ci-local.sh prints LOCAL CI FAILED — N gate(s) red and exits 0. A genuinely red gate on this branch nearly passed as green; it was caught only by reading the summary text. Any automation trusting that exit status gets a false pass.
2. Five --print-only assertions in the CLI tests use toContain, which can detect a missing forecast entry but never a spurious one — the blind spot is directional. One such stale entry shipped and was found by review, not by the suite.
3. bin/meta.ts has no .catch(), so any throw from a command surfaces as an unhandled rejection rather than a diagnostic and an exit code.
4. Nothing gates a source file that git classifies as binary. A stray NUL byte in a TypeScript source made git treat it as binary, blanking the file out of its own review diff and out of the pre-commit hygiene scanner's reach.

Worth a reviewer's attention: the two-pass migrate-ts schema partition (declaredSchemas derived from the remainder) and the docs --site snapshot-dir resolution are the subtlest pieces. The view.text corpus exemption that earlier deferred two Python cases has been discharged — both ports now assert the same 24.

🤖 Generated with Claude Code

https://claude.ai/code/session_01ApQWqotP1jaKs85XhKVXG4