metaobjects 1.0.3__tar.gz → 1.0.4__tar.gz

{metaobjects-1.0.3 → metaobjects-1.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: metaobjects
-Version: 1.0.3
+Version: 1.0.4
 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-1.0.3 → metaobjects-1.0.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "metaobjects"
-version = "1.0.3"
+version = "1.0.4"
 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"

{metaobjects-1.0.3 → metaobjects-1.0.4}/scripts/generate_embedded_library.py

@@ -52,10 +52,43 @@ def main() -> int:
     if not entries:
         raise SystemExit(f"no *.yaml found under {library_dir} — refusing to emit an empty library")
 
-    body = "".join(f"    {ref!r}: {text!r},\n" for ref, text in entries)
-    out_path.write_text(HEADER + body + "}\n", encoding="utf-8")
+    # The MANIFESTS ride the same embed, in their own map keyed by library NAME.
+    #
+    # Their own map rather than another entry in the ref map, because a ref is
+    # "path under library/ minus .yaml" and every reader appends ``.yaml`` back. Folding
+    # a ``.json`` into that would mean a special case at every call site in four ports.
+    manifests = []
+    missing = []
+    for d in sorted(p for p in library_dir.iterdir() if p.is_dir()):
+        manifest = d / "library.json"
+        if manifest.is_file():
+            manifests.append((d.name, manifest.read_text(encoding="utf-8")))
+        else:
+            missing.append(d.name)
+
+    # A library directory with no manifest is a build error, not a silently-skipped one:
+    # the manifest declares the library's LAYERS, and without it ``libraries: ["iam/db"]``
+    # resolves to nothing and the adopter gets an empty tree with no explanation.
+    if missing:
+        raise SystemExit(f"library director{'y' if len(missing) == 1 else 'ies'} with no library.json: {', '.join(missing)}")
 
-    print(f"wrote {out_path.relative_to(root)} ({len(entries)} ref(s): {', '.join(r for r, _ in entries)})")
+    body = "".join(f"    {ref!r}: {text!r},\n" for ref, text in entries)
+    manifest_body = "".join(f"    {name!r}: {text!r},\n" for name, text in manifests)
+    out_path.write_text(
+        HEADER
+        + body
+        + "}\n\n"
+        + "#: Library NAME -> the exact text of its ``library.json`` manifest.\n"
+        + "EMBEDDED_LIBRARY_MANIFESTS: dict[str, str] = {\n"
+        + manifest_body
+        + "}\n",
+        encoding="utf-8",
+    )
+
+    print(
+        f"wrote {out_path.relative_to(root)} ({len(entries)} ref(s): "
+        f"{', '.join(r for r, _ in entries)}; {len(manifests)} manifest(s))"
+    )
     return 0
 
 

{metaobjects-1.0.3 → metaobjects-1.0.4}/src/metaobjects/cli.py

@@ -53,7 +53,12 @@ from typing import Callable
 
 from metaobjects import MetaDataLoader
 from metaobjects.errors import ParseError
-from metaobjects.config.dependencies import Collection, imported_from, refuse_unowned_packages
+from metaobjects.config.dependencies import (
+    Collection,
+    imported_from,
+    refuse_library_package_misuse,
+    refuse_unowned_packages,
+)
 from metaobjects.loader.meta_data_loader import LoadResult
 from metaobjects.loader.sources import FileSource
 from metaobjects.meta.core.object.meta_object import MetaObject
@@ -119,22 +124,29 @@ def _pkg_of(node: MetaData) -> str:
     return "" if i == -1 else key[:i]
 
 
-def _default_generators() -> list[Generator]:
-    """The default codegen suite — the no-config generators every project gets.
+#: The error a run with no generator selection reports.
+#:
+#: There is no default suite. This port used to run EIGHT generators for a caller who
+#: named none — entity, router, filter-allowlist, names, payload, output-parser,
+#: output-prompt, extractor — which is a shape nobody chose. Java has never had a
+#: default set and has been right all along; TypeScript and C# dropped theirs in the
+#: same change.
+#:
+#: Deciding WHICH code an application needs belongs to whoever is building it —
+#: increasingly an LLM working in the repo, which is well able to make that call given a
+#: truthful catalog and is badly served by a default that pre-empts it. ``--list`` is
+#: that catalog.
+NO_GENERATORS_SELECTED = (
+    "gen: no generators selected. Nothing is generated until you choose it — "
+    "pass --generators <a,b,c>. See the catalog: metaobjects gen --list"
+)
 
-    ``template_generator`` is excluded: it requires a caller-supplied text
-    provider + Mustache template and is not a zero-config per-entity emitter.
-    """
-    return [
-        entity_model(),
-        router_generator(),
-        filter_allowlist_generator(),
-        names_generator(),
-        payload_vo_generator(),
-        output_parser_generator(),
-        output_prompt_generator(),
-        extractor_generator(),
-    ]
+
+class NoGeneratorsSelectedError(ValueError):
+    """Raised when a codegen run names no generator. Carries the usage message."""
+
+    def __init__(self) -> None:
+        super().__init__(NO_GENERATORS_SELECTED)
 
 
 def _resolve_providers(specs: list[str] | None) -> tuple[list[object], list[str]]:
@@ -338,6 +350,11 @@ def _load_collection_result(
     result = loader.load([*lib_sources, *sources])
     if not result.errors:
         refuse_unowned_packages(result.root, collection.imported_packages, collection.imported_nodes)
+        # FR-043 §3.4 / §3.5 — the same rule for a shipped LIBRARY's package, where the
+        # two ways to get it wrong are opposite: a node the library also declares (an
+        # ejected copy, still opted in) and one it does not (a new node in someone
+        # else's package).
+        refuse_library_package_misuse(result.root, libraries)
     return result
 
 
@@ -507,7 +524,11 @@ def _run_suite(
         # verify path (those pass gen_state_dir=None and record nothing at all).
         baseline=baseline,
     )
-    suite = generators if generators is not None else _default_generators()
+    # No default suite — see NO_GENERATORS_SELECTED. A caller that names none gets a
+    # usage error and an empty out dir, never a shape this CLI picked.
+    if not generators:
+        raise NoGeneratorsSelectedError
+    suite = generators
     result = run_gen(config, root, generators=suite, entity_filter=entity_filter, select=select)
     for warning in result.warnings:
         print(f"warning: {warning}")
@@ -885,6 +906,11 @@ def _cmd_gen(args: argparse.Namespace) -> int:
             for msg in gen_errors:
                 print(f"  {msg}", file=sys.stderr)
             return 1
+    else:
+        # Codegen is opt-in: refuse here, at the door, rather than letting the run reach
+        # the generator loop and fail with an empty out dir half-created.
+        print(f"error: {NO_GENERATORS_SELECTED}", file=sys.stderr)
+        return 2
 
     # SP-1: declarative Mustache generators from a JSON template-spec. Their output
     # is format-agnostic (text/markdown/csv/json/xml/html), so they run as a SECOND,
@@ -1380,12 +1406,35 @@ def _verify_codegen(args: argparse.Namespace) -> int:
         print(spec_err, file=sys.stderr)
         return 1
 
+    # `verify --codegen` re-runs the SELECTION and compares. Codegen is opt-in, so the
+    # selection has to be named — with none, there is no generated output to check, and
+    # saying so beats silently regenerating a suite this project never asked for and
+    # convicting every file of being missing.
+    selection: list[Generator] | None = None
+    if getattr(args, "generators", None):
+        selection, gen_errors = _resolve_generators(args.generators)
+        if gen_errors:
+            print("error: invalid --generators selection:", file=sys.stderr)
+            for msg in gen_errors:
+                print(f"  {msg}", file=sys.stderr)
+            return 1
+    elif not spec_gens:
+        print(
+            "verify --codegen: no generators selected, so there is no generated output "
+            "to check. Pass --generators <a,b,c> naming the same suite `gen` ran "
+            "(metaobjects gen --list is the catalog).",
+        )
+        return 0
+
     with tempfile.TemporaryDirectory() as tmp:
         entities = _parse_entities(getattr(args, "entities", None))
-        written, errors = _generate(
-            args.metadata_dir, tmp, None, entities, strict=strict, providers=providers,
-            column_naming=column_naming,
-        )
+        written: list[str] = []
+        errors: list[str] = []
+        if selection is not None:
+            written, errors = _generate(
+                args.metadata_dir, tmp, selection, entities, strict=strict,
+                providers=providers, column_naming=column_naming,
+            )
         if errors:
             print("error: failed to load metadata:", file=sys.stderr)
             for msg in errors:
@@ -1458,6 +1507,22 @@ def _verify_codegen_neutral_fallback(args: argparse.Namespace) -> int:
     if not providers_ok:
         return 1
 
+    # Same rule as _verify_codegen: the selection must be named, because there is no
+    # default suite to regenerate and diff against.
+    if not getattr(args, "generators", None):
+        print(
+            "verify --codegen: no generators selected, so there is no generated output "
+            "to check. Pass --generators <a,b,c> naming the same suite `gen` ran "
+            "(metaobjects gen --list is the catalog).",
+        )
+        return 0
+    selection, gen_errors = _resolve_generators(args.generators)
+    if gen_errors:
+        print("error: invalid --generators selection:", file=sys.stderr)
+        for msg in gen_errors:
+            print(f"  {msg}", file=sys.stderr)
+        return 1
+
     with tempfile.TemporaryDirectory() as tmp:
         entities = _parse_entities(getattr(args, "entities", None))
         root, load_errors = _load_root_from_collection(collection, strict=strict, providers=providers)
@@ -1475,7 +1540,7 @@ def _verify_codegen_neutral_fallback(args: argparse.Namespace) -> int:
             return 2
 
         _run_suite(
-            root, tmp, None, entities, gen_state_dir=None, column_naming=column_naming,
+            root, tmp, selection, entities, gen_state_dir=None, column_naming=column_naming,
             select=collection.in_scope,
         )
         expected = _relative_set(Path(tmp))
@@ -1903,9 +1968,9 @@ def _build_parser() -> argparse.ArgumentParser:
         "--generators",
         default=None,
         help=(
-            "comma-separated STABLE generator names to run (e.g. entity,routes). "
-            "Resolved via the registry; omit to run the default suite. "
-            "See `gen --list`."
+            "REQUIRED — comma-separated STABLE generator names to run "
+            "(e.g. entity,routes). Codegen is opt-in: there is no default suite, so a "
+            "run that names none is a usage error. See `gen --list` for the catalog."
         ),
     )
     gen.add_argument(
@@ -2134,6 +2199,15 @@ def _build_parser() -> argparse.ArgumentParser:
         default=None,
         help="verify only this named target from the config (default: every target)",
     )
+    verify.add_argument(
+        "--generators",
+        default=None,
+        help=(
+            "comma-separated STABLE generator names — must MATCH the `gen` that "
+            "produced --out. `verify --codegen` re-runs the selection and diffs; with "
+            "none named there is nothing to check and it says so."
+        ),
+    )
     verify.set_defaults(func=_cmd_verify)
 
     agent_docs = sub.add_parser(

{metaobjects-1.0.3 → metaobjects-1.0.4}/src/metaobjects/codegen/constants.py

@@ -5,11 +5,20 @@ GENERATED_MARKER = "@generated by metaobjects"
 
 
 def generated_header(entity_name: str, fqn: str) -> str:
-    """Line-1 header for every emitted module. Detected by the overwrite policy."""
+    """Line-1 header for every emitted module. Detected by the overwrite policy.
+
+    Line 3 used to read ``Customize via <name>_extra.py in this directory``, the exact
+    wording the TypeScript emitters carried. It asserted a plugin point no port has: a
+    sibling module is safe because codegen only writes the paths it records, never
+    because of its name, and nothing imports it for you. See #367 for what the TS
+    spelling cost in a real build, and ``docs/features/own-your-codegen.md`` for the
+    convention as it actually works. Keep this line and
+    ``codegen-ts/src/constants.ts``'s ``sidecarLine`` saying the same thing.
+    """
     return (
         f"# {GENERATED_MARKER} — DO NOT EDIT.\n"
         f"# Source metadata: {entity_name} ({fqn})\n"
-        f"# Customize via {entity_name}_extra.py in this directory.\n"
+        f"# Extend in your own module (e.g. {entity_name}_extra.py) — nothing imports it for you.\n"
     )
 
 

{metaobjects-1.0.3 → metaobjects-1.0.4}/src/metaobjects/codegen/generator_registry.py

@@ -6,9 +6,11 @@ the cross-port contract: the same logical generator carries the same stable name
 in every port. This module is the discoverability + identity surface behind
 ``metaobjects gen --list`` and the ``--generators a,b`` selection path.
 
-It is ADDITIVE. The default suite in ``cli.py`` (``_default_generators``) and the
-``run_gen(..., generators=[...])`` factory-array path keep working unchanged — the
-registry powers ``--list`` and stable identity; it does not replace those paths.
+It is the ONLY name-based door. ADR-0034 Amendment 2 made codegen opt-in and DELETED
+the default suite this note used to name (``cli._default_generators``): a run that
+selects no generator generates nothing and raises ``NoGeneratorsSelectedError``. The
+``run_gen(..., generators=[...])`` factory-array path remains for in-process callers,
+where ``generators`` is likewise required.
 
 The registry's name set is conformance-tested for SET EQUALITY against the Python
 slice of the canonical manifest
@@ -45,10 +47,27 @@ from metaobjects.render.verify import InMemoryProvider
 
 GeneratorTier = str  # "native" | "neutral"
 
+#: The six layers a generator can belong to — the axis an adopter SELECTS BY, gated
+#: cross-port against the manifest exactly as ``tier`` is. Six, not ten: an earlier
+#: draft split ``capability`` four ways, each with ONE member, and a layer with one
+#: member does no grouping work. ``capability`` holds the generators the MODEL has
+#: already chosen (you declared a ``template.prompt``), which is why they are found
+#: by probing a real model rather than by browsing a taxonomy.
+GENERATOR_LAYERS: tuple[str, ...] = (
+    "model",
+    "persistence",
+    "api",
+    "client",
+    "docs",
+    "capability",
+)
+
+GeneratorLayer = str  # one of GENERATOR_LAYERS
+
 
 @dataclass(frozen=True)
 class GeneratorEntry:
-    """A registry entry: stable name + one-line description + tier + factory."""
+    """A registry entry: stable name + one-line description + tier + layer + factory."""
 
     #: Stable, cross-port-consistent id. Equals the registry map key.
     name: str
@@ -56,6 +75,8 @@ class GeneratorEntry:
     description: str
     #: "native" = recommended ``metaobjects gen`` suite; "neutral" = ``meta docs``-owned.
     tier: GeneratorTier
+    #: The selection axis — one of :data:`GENERATOR_LAYERS`. Gated cross-port.
+    layer: GeneratorLayer
     #: Constructs the generator with sensible defaults. Calling it must not throw.
     factory: Callable[[], Generator]
 
@@ -89,72 +110,84 @@ def _render_helper_default() -> Generator:
 
 
 #: Stable name -> GeneratorEntry. The 11 native generators whose manifest `ports`
-#: include `python` (ADR-0021 D3). Set-equality conformance-tested vs the manifest.
+#: include `python` (ADR-0021 D3). Set equality, tier AND layer are conformance-tested
+#: against the manifest.
 GENERATOR_REGISTRY: dict[str, GeneratorEntry] = {
     "entity": GeneratorEntry(
         name="entity",
         description="Per-entity model/class — the entity module (table-backed or value object).",
         tier="native",
+        layer="model",
         factory=entity_model,
     ),
     "routes": GeneratorEntry(
         name="routes",
         description="Per-entity REST endpoint surface (controllers / routes / router).",
         tier="native",
+        layer="api",
         factory=router_generator,
     ),
     "output-parser": GeneratorEntry(
         name="output-parser",
         description="Per-template tolerant output parser (recover-on-receipt).",
         tier="native",
+        layer="capability",
         factory=output_parser_generator,
     ),
     "output-prompt": GeneratorEntry(
         name="output-prompt",
         description="Per-template output-format prompt fragment generator.",
         tier="native",
+        layer="capability",
         factory=output_prompt_generator,
     ),
     "render-helper": GeneratorEntry(
         name="render-helper",
         description="Per-template.output render helper (document/email typed wrappers).",
         tier="native",
+        layer="capability",
         factory=_render_helper_default,
     ),
     "extractor": GeneratorEntry(
         name="extractor",
         description="Per-template strict typed extract<Name> helper (strict payload extraction).",
         tier="native",
+        layer="capability",
         factory=extractor_generator,
     ),
     "template": GeneratorEntry(
         name="template",
         description="Generic Mustache template primitive (walk + template -> files).",
         tier="native",
+        layer="capability",
         factory=_template_primitive,
     ),
     "filter-allowlist": GeneratorEntry(
         name="filter-allowlist",
         description="Per-entity REST filter allowlist (queryable-field guard).",
         tier="native",
+        layer="api",
         factory=filter_allowlist_generator,
     ),
     "names": GeneratorEntry(
         name="names",
         description="Per-entity physical database name constants (table/view name, schema, column names).",
         tier="native",
+        layer="model",
         factory=names_generator,
     ),
     "payload": GeneratorEntry(
         name="payload",
         description="Per-template payload value object (the strict payload type).",
         tier="native",
+        layer="capability",
         factory=payload_vo_generator,
     ),
     "trace-helper": GeneratorEntry(
         name="trace-helper",
         description="Per-entity typed record<Entity> LLM-trace helper (extract + buildLlmCallRow + persist).",
         tier="native",
+        layer="capability",
         factory=trace_helper_generator,
     ),
 }

{metaobjects-1.0.3 → metaobjects-1.0.4}/src/metaobjects/codegen/generators/router_generator.py

@@ -60,10 +60,12 @@ from metaobjects.meta.core.field.meta_field import MetaField
 from metaobjects.meta.persistence.db import db_constants as dbc
 from metaobjects.meta.core.identity.identity_constants import (
     IDENTITY_ATTR_FIELDS,
-    IDENTITY_REFERENCE_ATTR_REFERENCES,
     IDENTITY_SUBTYPE_REFERENCE,
 )
 from metaobjects.meta.core.object.meta_object import MetaObject
+from metaobjects.meta.core.relationship.relationship_references import (
+    reference_target_entity,
+)
 from metaobjects.meta.persistence.source.source_constants import SOURCE_KIND_TABLE
 from metaobjects.naming import DEFAULT_COLUMN_NAMING
 from metaobjects.shared.base_types import TYPE_IDENTITY
@@ -269,13 +271,15 @@ def reverse_fks_for(entity: MetaObject) -> list[ReverseFk]:
             fk_field = fields[0]
         elif isinstance(fields, str) and fields:
             fk_field = fields.split(",")[0].strip() or None
-        references = c.get_meta_attr(IDENTITY_REFERENCE_ATTR_REFERENCES)  # ADR-0039: resolving (identity attr)
-        target = (
-            references[references.rfind(PACKAGE_SEP) + len(PACKAGE_SEP):]
-            if isinstance(references, str) and PACKAGE_SEP in references
-            else references
-        )
-        if not fk_field or not isinstance(target, str) or not target:
+        # #368 fallout: @references may be the dotted `Entity.field` /
+        # `Entity.fieldA,fieldB` explicit-fields form (e.g. "acme::sport::Team.id"),
+        # not just a bare/qualified entity name. reference_target_entity() already
+        # drops that dotted tail (ADR-0039: resolving); strip_package here then bares
+        # the remaining qualified entity name, same as the pre-existing package strip.
+        target = reference_target_entity(c)
+        if isinstance(target, str) and PACKAGE_SEP in target:
+            target = target[target.rfind(PACKAGE_SEP) + len(PACKAGE_SEP):]
+        if not fk_field or not target:
             continue
         out.append(ReverseFk(fk_field=fk_field, target_entity=target))
     return out

{metaobjects-1.0.3 → metaobjects-1.0.4}/src/metaobjects/codegen/generators/trace_helper_generator.py

@@ -54,13 +54,31 @@ from metaobjects.meta.meta_data import MetaData
 from metaobjects.meta.template import template_constants as tc
 from metaobjects.meta.template.meta_template import MetaTemplate
 from metaobjects.shared.base_types import TYPE_TEMPLATE
+from metaobjects.library.library_sources import LIBRARY_MANIFESTS
 from metaobjects.shared.separators import PACKAGE_SEP
 
 _GENERATOR_NAME = "trace-helper"
 
-#: The abstract base entity a trace entity must (transitively) ``extends``.
-#: Cross-port constant — mirrors TS ``LLM_CALL_BASE`` / Java ``LLM_CALL_BASE``.
-LLM_CALL_BASE = "LlmCallBase"
+def _anchor_fqns() -> frozenset[str]:
+    """FQNs of the library nodes this generator keys on, read from the shipped
+    ``library.json`` manifests (FR-043 §6) rather than hard-coded here.
+
+    What it replaces: ``LLM_CALL_BASE = "LlmCallBase"``, compared against
+    ``MetaData.name`` (the SHORT name) anywhere in the super chain — so any adopter
+    entity of that name, in any package, triggered a helper that writes the shipped
+    base's columns. An anchor is fully qualified and is resolved to a node below.
+    """
+    out: set[str] = set()
+    for manifest in LIBRARY_MANIFESTS.values():
+        for gen in manifest.get("generators", []):
+            if gen.get("name") == _GENERATOR_NAME and gen.get("anchor"):
+                out.add(gen["anchor"])
+    return frozenset(out)
+
+
+#: The anchor FQNs, resolved once per process from the embedded manifests.
+#: Mirrors TS ``anchorFqns()`` / Java ``LlmTraceHelperGenerator.ANCHOR_FQNS``.
+ANCHOR_FQNS = _anchor_fqns()
 
 
 def _pkg_of(node: MetaData) -> str:
@@ -88,15 +106,18 @@ def _snake_case(name: str) -> str:
 
 
 def _extends_base(entity: MetaObject) -> bool:
-    """Walk the resolved super chain looking for a node SHORT-named
-    :data:`LLM_CALL_BASE`. ``MetaData.name`` holds the short name only (the package
-    lives on ``MetaData.package``), so a plain ``name`` compare is the short-name
-    test — mirrors the Java ``getShortName()`` walk and the TS ``superResolved``
-    walk."""
+    """Walk the resolved super chain looking for one of :data:`ANCHOR_FQNS`.
+
+    The FULLY-QUALIFIED name, via ``resolution_key()``: within one loaded root an FQN
+    identifies exactly one node (a same-name redeclaration merges), so this is the
+    node-identity compare the TypeScript port makes against the resolved anchor node,
+    and the Java port makes against ``getName()``."""
+    if not ANCHOR_FQNS:
+        return False
     cur = entity.super_data
     visited: set[int] = set()
     while cur is not None and id(cur) not in visited:
-        if cur.name == LLM_CALL_BASE:
+        if cur.resolution_key() in ANCHOR_FQNS:
             return True
         visited.add(id(cur))
         cur = cur.super_data
@@ -125,7 +146,7 @@ def render_trace_helper(entity: MetaObject, root: MetaData) -> str | None:
     """Render one ``record_<entity>.py`` for a concrete trace ``object.entity``.
 
     Returns ``None`` when the entity is not a trace-helper target (abstract, not
-    ``LlmCallBase``-derived, no nested ``template.prompt``, or that prompt carries
+    derived from a library anchor, no nested ``template.prompt``, or that prompt carries
     neither ``@responseRef`` nor ``@payloadRef``).
 
     Raises ``ValueError`` when the prompt's ``@responseRef`` does not resolve to an

{metaobjects-1.0.3 → metaobjects-1.0.4}/src/metaobjects/config/dependencies.py

@@ -515,6 +515,88 @@ def refuse_unowned_packages(
         )
 
 
+def refuse_library_package_misuse(
+    root: MetaData,
+    selection: Sequence[str] | None,
+) -> None:
+    """FR-043 §3.4 / §3.5 — refuse the two ways an adopter's own file lands in a
+    shipped library's package while that library is opted in.
+
+    Both are SILENT otherwise, and they fail in opposite directions:
+
+    the EJECTED COPY
+        ``meta eject <lib>`` hands you the library's YAML to own, and the next step it
+        prints is to remove the library from ``libraries``. Skip that and both trees
+        load: the copy merges into the shipped node, so ADDITIONS take and DELETIONS do
+        not, because the library still declares what you removed
+        (``ERR_LIBRARY_PACKAGE_COLLISION``).
+
+    the NEW NODE
+        something of your own declared into ``metaobjects::<lib>``, where a later
+        release of the library may ship a node of that name and merge into it
+        (``ERR_LIBRARY_PACKAGE_NOT_OWNED``).
+
+    An ``overlay: true`` redeclaration is the documented adaptation door (§3.4) and is
+    deliberately untouched — ``is_merge`` is the loader's own record that the flag was
+    honoured, so this cannot mistake the two. Mirrors the TS
+    ``refuseLibraryPackageMisuse`` (``sdk/src/memory.ts``); called AFTER the loader's
+    own errors for the same reason its sibling above is.
+
+    No-op for a project that opts into no library.
+    """
+    if not selection:
+        return
+    from metaobjects.library.library_sources import (
+        LIBRARY_MANIFESTS,
+        is_library_file_id,
+        split_layer_token,
+    )
+
+    owner: dict[str, str] = {}
+    for token in selection:
+        library = split_layer_token(token)[0]
+        for pkg in LIBRARY_MANIFESTS.get(library, {}).get("packages", []):
+            owner[pkg] = library
+    if not owner:
+        return
+
+    # ADR-0039 SANCTIONED own-accessor case: a root-level scan, exactly as the
+    # dependency refusal above — `MetaRoot` has no super, and the question is "what did
+    # this tree declare at the top level".
+    for node in root.own_children():
+        key = node.resolution_key()
+        library = owner.get(package_of_resolution_key(key))
+        if library is None:
+            continue
+        files = getattr(node.source, "files", None) or []
+        if not any(not is_library_file_id(f) for f in files):
+            continue  # the library's own node, untouched
+        if getattr(node, "is_merge", False):
+            continue  # a marked overlay — the documented door
+        if any(is_library_file_id(f) for f in files):
+            raise ParseError(
+                f'"{key}" is declared by your own metadata AND by the shipped library '
+                f'"{library}", which this project opts into. The two merge silently and '
+                "asymmetrically: additions in your copy take effect and DELETIONS do not, "
+                "because the library still declares what you removed. Remove "
+                f'"{library}" from \'libraries\' in .metaobjects/config.json — you own the '
+                "metadata now — or delete your copy and amend the library with "
+                "'overlay: true' on the nodes you want to change.",
+                code=ErrorCode.ERR_LIBRARY_PACKAGE_COLLISION,
+            )
+        raise ParseError(
+            f'"{key}" is declared here, but the package '
+            f'"{package_of_resolution_key(key)}" belongs to the shipped library '
+            f'"{library}", which this project opts into. A later release of that library '
+            "may ship a node of this name and merge into yours. Declare it in a package "
+            "this project owns and 'extends' the library's node if it needs its shape; if "
+            "it was meant to AMEND a library node, give it that node's name and "
+            f"'overlay: true'; if you want this design outright, run 'meta eject {library}' "
+            f'and remove "{library}" from \'libraries\'.',
+            code=ErrorCode.ERR_LIBRARY_PACKAGE_NOT_OWNED,
+        )
+
+
 @dataclass(frozen=True)
 class Collection:
     """Everything the FR-023-aware source ladder resolved for one project:

{metaobjects-1.0.3 → metaobjects-1.0.4}/src/metaobjects/errors.py

@@ -127,6 +127,15 @@ class ErrorCode(str, Enum):
     ERR_COLLECTION_NOT_FOUND = "ERR_COLLECTION_NOT_FOUND"
     # FR-023 — a declared dependency's transport could not locate a directory holding
     # metaobjects.pkg.json.
+    # FR-043: .metaobjects/config.json's `libraries` names a shipped library or layer
+    # this build does not have. Refused with the available tokens rather than skipped —
+    # skipped, it resurfaces as ERR_UNRESOLVED_SUPER against the adopter's own metadata.
+    ERR_UNKNOWN_LIBRARY = "ERR_UNKNOWN_LIBRARY"
+    # FR-043: a node is declared by BOTH an adopter's own metadata and a shipped library the project opts into — the `meta eject <lib>` copy with the library still in `libraries`. The two merge silently and ASYMMETRICALLY: additions take, deletions do not, because the library still declares what was removed.
+    # Raised by the TypeScript SDK's load path; registered in every port so the shared corpus list stays one set.
+    ERR_LIBRARY_PACKAGE_COLLISION = "ERR_LIBRARY_PACKAGE_COLLISION"
+    # FR-043: a NEW top-level node is declared into a package a shipped library owns while that library is opted in — a later release of the library may ship a node of that name and merge into it. `overlay: true` on one of the library's OWN nodes is the documented amendment door and is untouched.
+    ERR_LIBRARY_PACKAGE_NOT_OWNED = "ERR_LIBRARY_PACKAGE_NOT_OWNED"
     ERR_DEPENDENCY_UNRESOLVED = "ERR_DEPENDENCY_UNRESOLVED"
     # FR-023 — a dependency's metaobjects.pkg.json fails its schema, names a different
     # dependency, points at a missing/hash-mismatched artifact, or the artifact does not