@metaobjectsdev/metadata 0.21.6 → 0.22.0-rc.2

package/src/core/requirement/meta-requirement.ts

@@ -0,0 +1,69 @@
+// MetaRequirement — concrete node class for type=requirement nodes.
+//
+// Extends MetaData directly: no model wrapper, no metaOf() indirection.
+// Accessors are RESOLVING (ADR-0039) so a requirement that `extends` an
+// abstract parent inherits its properties.
+
+import { MetaData } from "../../shared/meta-data.js";
+import {
+  REQUIREMENT_SUBTYPE_FUNCTIONAL,
+  REQUIREMENT_SUBTYPE_ARCHITECTURAL,
+  REQUIREMENT_ATTR_LEVEL,
+  REQUIREMENT_ATTR_STATUS,
+  REQUIREMENT_ATTR_IMPLEMENTED_BY,
+  REQUIREMENT_ATTR_VERIFIED_BY,
+  REQUIREMENT_LINK_FLOOR_LEVEL,
+  REQUIREMENT_STATUSES_REQUIRING_LIVE_NODES,
+  type RequirementStatus,
+} from "./requirement-constants.js";
+
+export class MetaRequirement extends MetaData {
+  /** What the product does for a user — checked by EXISTENCE. */
+  isFunctional(): boolean {
+    return this.subType === REQUIREMENT_SUBTYPE_FUNCTIONAL;
+  }
+
+  /** How the system is built — checked by UNIVERSALITY (the opposite polarity). */
+  isArchitectural(): boolean {
+    return this.subType === REQUIREMENT_SUBTYPE_ARCHITECTURAL;
+  }
+
+  /** 1 solution · 2 segment · 3 service · 4 object · 5 member. Architectural
+   *  requirements carry none — they are object-independent by definition. */
+  level(): number | undefined {
+    const v = this.attr(REQUIREMENT_ATTR_LEVEL);
+    return typeof v === "number" ? v : undefined;
+  }
+
+  status(): RequirementStatus | undefined {
+    const v = this.attr(REQUIREMENT_ATTR_STATUS);
+    return typeof v === "string" ? (v as RequirementStatus) : undefined;
+  }
+
+  implementedBy(): string[] {
+    const v = this.attr(REQUIREMENT_ATTR_IMPLEMENTED_BY);
+    return Array.isArray(v) ? (v as string[]) : [];
+  }
+
+  verifiedBy(): string[] {
+    const v = this.attr(REQUIREMENT_ATTR_VERIFIED_BY);
+    return Array.isArray(v) ? (v as string[]) : [];
+  }
+
+  /** True when this requirement is permitted to reference the model at all.
+   *  Architectural requirements always may (their claim set is the point);
+   *  functional ones only at or below the link floor, so the organisational
+   *  tiers stay organisational. */
+  mayReferenceModel(): boolean {
+    if (this.isArchitectural()) return true;
+    const lvl = this.level();
+    return lvl !== undefined && lvl >= REQUIREMENT_LINK_FLOOR_LEVEL;
+  }
+
+  /** True when a dangling `@implementedBy` is an ERROR rather than expected.
+   *  An abandoned or superseded requirement's nodes are supposed to be gone. */
+  requiresLiveNodes(): boolean {
+    const s = this.status();
+    return s !== undefined && REQUIREMENT_STATUSES_REQUIRING_LIVE_NODES.includes(s);
+  }
+}

package/src/core/requirement/requirement-constants.ts

@@ -0,0 +1,82 @@
+// Requirement concern constants — type name, subtypes, and attr keys.
+//
+// `requirement.*` is REGISTERED metamodel vocabulary (ruling amendment 3): the
+// capability ledger is a metadata model, so it is declared in `metaobjects/`
+// beside the entities it describes and validated by the loader like everything
+// else — not hand-parsed from a side file.
+
+export const REQUIREMENT = "requirement";
+
+// ---------------------------------------------------------------------------
+// Subtypes — the axis is the CHECK POLARITY, which is a genuine behaviour
+// difference and therefore a subtype under ADR-0037 §2:
+//   functional    -> EXISTENCE:    fails when nothing implements it
+//   architectural -> UNIVERSALITY: fails when something violates it
+// ---------------------------------------------------------------------------
+
+export const REQUIREMENT_SUBTYPE_FUNCTIONAL = "functional";
+export const REQUIREMENT_SUBTYPE_ARCHITECTURAL = "architectural";
+
+export const REQUIREMENT_SUBTYPES = [
+  REQUIREMENT_SUBTYPE_FUNCTIONAL,
+  REQUIREMENT_SUBTYPE_ARCHITECTURAL,
+] as const;
+export type RequirementSubType = (typeof REQUIREMENT_SUBTYPES)[number];
+
+// ---------------------------------------------------------------------------
+// Attrs
+// ---------------------------------------------------------------------------
+
+/** 1 solution · 2 segment (app/library) · 3 service · 4 object · 5 member. */
+export const REQUIREMENT_ATTR_LEVEL = "level";
+export const REQUIREMENT_ATTR_STATUS = "status";
+export const REQUIREMENT_ATTR_STATEMENT = "statement";
+export const REQUIREMENT_ATTR_VIOLATION = "violation";
+export const REQUIREMENT_ATTR_IMPLEMENTED_BY = "implementedBy";
+export const REQUIREMENT_ATTR_VERIFIED_BY = "verifiedBy";
+export const REQUIREMENT_ATTR_SUPERSEDED_BY = "supersededBy";
+
+// ---------------------------------------------------------------------------
+// Status — a closed enum, enforced by the registry via `allowedValues`. This is
+// the one payload with controlled evidence behind it: model-only agents flagged
+// a deliberately-retired capability 0 times out of 24, so a typo that silently
+// disabled it would disable the whole mechanism.
+// ---------------------------------------------------------------------------
+
+export const REQUIREMENT_STATUS_LIVE = "live";
+export const REQUIREMENT_STATUS_PARTIAL = "partial";
+export const REQUIREMENT_STATUS_ABANDONED = "abandoned";
+export const REQUIREMENT_STATUS_SUPERSEDED = "superseded";
+
+export const REQUIREMENT_STATUSES = [
+  REQUIREMENT_STATUS_LIVE,
+  REQUIREMENT_STATUS_PARTIAL,
+  REQUIREMENT_STATUS_ABANDONED,
+  REQUIREMENT_STATUS_SUPERSEDED,
+] as const;
+export type RequirementStatus = (typeof REQUIREMENT_STATUSES)[number];
+
+/** Statuses whose implementing nodes are supposed to still exist. A dangling
+ *  `@implementedBy` on one of these means the model moved and the requirement is
+ *  stale; on the other two the nodes are supposed to be GONE, which is the whole
+ *  point of the entry. The asymmetry inverts as a pair. */
+export const REQUIREMENT_STATUSES_REQUIRING_LIVE_NODES: readonly RequirementStatus[] = [
+  REQUIREMENT_STATUS_LIVE,
+  REQUIREMENT_STATUS_PARTIAL,
+];
+
+// ---------------------------------------------------------------------------
+// Levels — organisational above the link floor, model-referencing at or below.
+// ---------------------------------------------------------------------------
+
+export const REQUIREMENT_LEVEL_SOLUTION = 1;
+export const REQUIREMENT_LEVEL_SEGMENT = 2;
+export const REQUIREMENT_LEVEL_SERVICE = 3;
+export const REQUIREMENT_LEVEL_OBJECT = 4;
+export const REQUIREMENT_LEVEL_MEMBER = 5;
+
+/** The lowest level that may reference the model. L1-L3 are organisational and
+ *  carrying `@implementedBy` there is an error. */
+export const REQUIREMENT_LINK_FLOOR_LEVEL = REQUIREMENT_LEVEL_OBJECT;
+export const REQUIREMENT_MIN_LEVEL = REQUIREMENT_LEVEL_SOLUTION;
+export const REQUIREMENT_MAX_LEVEL = REQUIREMENT_LEVEL_MEMBER;

package/src/core/requirement/requirement-definition.embedded.ts

@@ -0,0 +1,148 @@
+// AUTO-GENERATED by scripts/generate-embedded-metamodel.ts — DO NOT EDIT.
+// Canonical source: repo-root spec/metamodel/requirement.json
+// Regenerate: bun run scripts/generate-embedded-metamodel.ts
+//
+// Embeds the canonical FR-033 ProviderDefinition so the provider can register
+// itself wherever the on-disk spec/ tree is unavailable (bundled builds).
+import type { ProviderDefinition } from "../../provider-data.js";
+
+export const REQUIREMENT_DEFINITION: ProviderDefinition = {
+  "provider": "metaobjects-core-types",
+  "types": [
+    {
+      "type": "requirement",
+      "subType": "functional",
+      "description": "What the product does for a user, stated as one violable claim. Its check is EXISTENCE: it fails when nothing implements it. Hierarchy is nesting — an L1 solution contains its L2 segments, which contain L3 services, and so on down to the levels that reference the model.",
+      "whenToUse": "Something exists because someone asked for it. Levels: 1 solution, 2 segment (an application or library), 3 service, 4 object, 5 member. Only L4 and L5 carry @implementedBy — L1-L3 are organisational and never reference the model.",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "int",
+          "name": "level",
+          "min": 1,
+          "max": 1,
+          "description": "1 solution, 2 segment (application/library), 3 service, 4 object, 5 member. Nesting depth must agree with it."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "status",
+          "min": 1,
+          "max": 1,
+          "allowedValues": [
+            "live",
+            "partial",
+            "abandoned",
+            "superseded"
+          ],
+          "description": "live implemented and in use; partial implemented with known gaps; abandoned built then deliberately retired; superseded replaced by a different mechanism. A dangling @implementedBy is an ERROR on live/partial (the model moved, the requirement is stale) and ALLOWED on abandoned/superseded (those nodes are meant to be gone — that is the entry doing its job)."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "statement",
+          "min": 1,
+          "max": 1,
+          "description": "What the capability is, in one sentence."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "violation",
+          "min": 1,
+          "max": 1,
+          "description": "What breaking it looks like, in one sentence. A requirement MUST be violable: 'every entity has a uuid primary key' is (point at one with a composite string key); 'things are persisted' is not, and is a description rather than a requirement."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "implementedBy",
+          "isArray": true,
+          "min": 0,
+          "max": 1,
+          "description": "FQN references to the model nodes realising this requirement. Legal on level 4 (an object) and level 5 (a field, view or identity) only; an organisational level carrying it is ERR_REQUIREMENT_LINK_ABOVE_FLOOR. Many-to-many by construction — several requirements may name the same node."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "verifiedBy",
+          "isArray": true,
+          "min": 0,
+          "max": 1,
+          "description": "Names of the tests proving the behaviour. verify checks each exists and is not skipped; it never runs them."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "supersededBy",
+          "min": 0,
+          "max": 1,
+          "description": "The requirement that replaced this one. Expected on status=superseded."
+        },
+        {
+          "type": "requirement",
+          "subType": "*",
+          "name": "*",
+          "min": 0,
+          "max": null,
+          "description": "Nested child requirements. Hierarchy IS nesting — an L1 solution contains its L2 segments, which contain L3 services — so regrouping moves a node rather than editing a parent string, and a requirement is addressable by the same dotted child-name path as every other node."
+        }
+      ]
+    },
+    {
+      "type": "requirement",
+      "subType": "architectural",
+      "description": "How the system is built, applied uniformly across the model. Its check is UNIVERSALITY: it fails when something VIOLATES it, which is the opposite polarity to a functional requirement. Carries no level and no parent — levels come from object-in-focus decomposition and an architectural requirement is object-independent by definition.",
+      "whenToUse": "Something exists because every entity here looks like this — a uuid primary key, an @autoSet createdAt, a change-attribution column, tenant scoping. The discriminator is mechanical: did this exist because someone asked for something, or because it is the architecture?",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "status",
+          "min": 1,
+          "max": 1,
+          "allowedValues": [
+            "live",
+            "partial",
+            "abandoned",
+            "superseded"
+          ],
+          "description": "As on requirement.functional. A live or partial architectural requirement claimed by NOTHING is an error: a policy declared and applied to nothing."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "statement",
+          "min": 1,
+          "max": 1,
+          "description": "The policy, in one sentence."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "violation",
+          "min": 1,
+          "max": 1,
+          "description": "What breaking it looks like — the node that would contradict it. This is what makes universality checkable."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "implementedBy",
+          "isArray": true,
+          "min": 0,
+          "max": 1,
+          "description": "FQN references to the nodes applying this policy. High fan-out is normal and expected: one uuid-primary-key requirement is claimed by every entity."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "supersededBy",
+          "min": 0,
+          "max": 1,
+          "description": "The requirement that replaced this one. Expected on status=superseded."
+        }
+      ]
+    }
+  ]
+};

package/src/core-types.ts

@@ -56,6 +56,9 @@ import { TEMPLATE_SUBTYPES } from "./template/template-constants.js";
 import { MetaIndex } from "./core/index/meta-index.js";
 import { INDEX_DEFINITION } from "./core/index/index-definition.embedded.js";
 import { INDEX_SUBTYPES } from "./core/index/index-constants.js";
+import { MetaRequirement } from "./core/requirement/meta-requirement.js";
+import { REQUIREMENT_DEFINITION } from "./core/requirement/requirement-definition.embedded.js";
+import { REQUIREMENT_SUBTYPES } from "./core/requirement/requirement-constants.js";
 import {
   TYPE_METADATA,
   TYPE_OBJECT,
@@ -70,6 +73,7 @@ import {
   TYPE_ORIGIN,
   TYPE_TEMPLATE,
   TYPE_INDEX,
+  TYPE_REQUIREMENT,
   SUBTYPE_ROOT,
 } from "./shared/base-types.js";
 import { CHILD_RULE_WILDCARD } from "./shared/structural.js";
@@ -186,6 +190,8 @@ function registerCoreTypeDefs(registry: TypeRegistry): void {
       wildcard(TYPE_FIELD),
       wildcard(TYPE_VALIDATOR),
       wildcard(TYPE_TEMPLATE),
+      // Capability requirements are declared beside the entities they describe.
+      wildcard(TYPE_REQUIREMENT),
     ], MetaRoot),
   );
 
@@ -487,6 +493,23 @@ function registerCoreTypeDefs(registry: TypeRegistry): void {
     registry.register(indexDef);
   }
 
+  // requirement — 2 subtypes. The axis is CHECK POLARITY, a genuine behaviour
+  // difference (ADR-0037 §2): `functional` is checked by EXISTENCE (nothing
+  // implements it -> fail), `architectural` by UNIVERSALITY (something violates
+  // it -> fail). Registered rather than hand-parsed because the capability
+  // ledger IS a metadata model: a closed status enum and a list of FQN
+  // references to model nodes are exactly `allowedValues` plus reference
+  // resolution, both of which this registry already owns (ruling amendment 3).
+  const REQUIREMENT_FACTORIES: FactoryMap = Object.fromEntries(
+    REQUIREMENT_SUBTYPES.map((subType) => [
+      `${TYPE_REQUIREMENT}.${subType}`,
+      (typeId: TypeId, name: string) => new MetaRequirement(typeId, name),
+    ]),
+  );
+  for (const reqDef of defineProviderFromData(REQUIREMENT_DEFINITION, REQUIREMENT_FACTORIES)) {
+    registry.register(reqDef);
+  }
+
   // Declare the core cross-references ON their TypeDefinitions, so the loader's
   // registry-derived validation resolves them generically (a dangling target fails the
   // load). Set on the concrete subtypes the parser produces. (Production moves these into
@@ -499,6 +522,13 @@ function registerCoreTypeDefs(registry: TypeRegistry): void {
       ];
     }
   }
+  // NOTE: @implementedBy is deliberately NOT declared as a loader `references`
+  // descriptor. That pass always ERRORS on an unresolved target, and a
+  // requirement with status `abandoned`/`superseded` exists precisely to name
+  // nodes that are GONE — declaring it here would make the entries that carry
+  // the mechanism's only controlled evidence fail to load. The loader owns what
+  // is unconditional (the status enum, shape, levels); `meta verify` owns the
+  // status-conditional resolution, where the severity actually depends on data.
   const idRefDef = registry.find(TYPE_IDENTITY, IDENTITY_SUBTYPE_REFERENCE);
   if (idRefDef) {
     idRefDef.references = [

package/src/errors.ts

@@ -60,6 +60,7 @@ export const ERROR_CODES = [
   "ERR_PROVIDER_DUPLICATE_ID",
   "ERR_PROVIDER_MISSING_DEPENDENCY",
   "ERR_PROVIDER_ATTR_CONFLICT",
+  "ERR_EXTEND_REQUIRED_ATTR",
   "ERR_MALFORMED_JSON",
   "ERR_MISSING_REQUIRED_ATTR",
   "ERR_SUBTYPE_RULE_VIOLATION",

package/src/index.ts

@@ -32,6 +32,8 @@ export * from "./core/documentation/doc-constants.js";
 export * from "./core/validator/validator-constants.js";
 export * from "./core/identity/identity-constants.js";
 export * from "./core/index/index-constants.js";
+export * from "./core/requirement/requirement-constants.js";
+export { MetaRequirement } from "./core/requirement/meta-requirement.js";
 export * from "./core/relationship/relationship-constants.js";
 export * from "./core/query/query-constants.js";
 export * from "./persistence/source/source-constants.js";
@@ -48,6 +50,19 @@ export type { AttrValue } from "./shared/meta-data.js";
 // Shared node classes
 export { MetaRoot } from "./shared/meta-root.js";
 
+// Cross-realm node guards — identify a node by metamodel `type`, not `instanceof`.
+// Cross-package callers (codegen-ts / migrate-ts / runtime-ts) MUST use these:
+// `instanceof` silently fails when two physical copies of this package are
+// loaded. See shared/node-guards.ts for the mechanism.
+export {
+  isMetaRoot,
+  isMetaObject,
+  isMetaField,
+  isMetaSource,
+  isWritableSource,
+  isReadOnlySource,
+} from "./shared/node-guards.js";
+
 // Core node classes
 export { MetaObject } from "./core/object/meta-object.js";
 export { MetaField } from "./core/field/meta-field.js";

package/src/naming.ts

@@ -6,7 +6,14 @@ import {
   SOURCE_ATTR_SCHEMA,
   SOURCE_ROLE_PRIMARY,
 } from "./persistence/source/source-constants.js";
-import { MetaSource } from "./persistence/source/meta-source.js";
+import type { MetaSource } from "./persistence/source/meta-source.js";
+// isMetaSource, not `instanceof`: unlike the loader-internal validators, these two
+// are EXPORTED helpers that run on a caller-supplied node — migrate-ts calls both
+// on nodes the CLI's loader built. Under a split @metaobjectsdev/metadata tree the
+// class check would be false for a real primary source, and resolveTableName would
+// silently fall through to the entity-name fallback: a DIFFERENT table name, which
+// migrate then emits as a rename against a live database.
+import { isMetaSource } from "./shared/node-guards.js";
 
 /**
  * Strip the package prefix from a metadata-qualified name
@@ -72,7 +79,7 @@ export function resolveTableName(entity: MetaData): string {
   // entity-name fallback. For an entity declaring its own source, own shadows
   // inherited, so the result is unchanged.
   const source = entity.children().find(
-    (c): c is MetaSource => c instanceof MetaSource && c.role === SOURCE_ROLE_PRIMARY,
+    (c): c is MetaSource => isMetaSource(c) && c.role === SOURCE_ROLE_PRIMARY,
   );
   if (source !== undefined) return source.physicalName;
   return pluralize(toSnakeCase(entity.name));
@@ -98,8 +105,7 @@ export function resolveColumnName(
 export function resolveTableSchema(entity: MetaData): string | undefined {
   // ADR-0039: resolving — a concrete entity may inherit its source.rdb via extends.
   const source = entity.children().find(
-    (c): c is MetaSource =>
-      c instanceof MetaSource && c.role === SOURCE_ROLE_PRIMARY,
+    (c): c is MetaSource => isMetaSource(c) && c.role === SOURCE_ROLE_PRIMARY,
   );
   if (!source) return undefined;
   // ADR-0039: resolving — an inherited source's @schema lives on the super node.

package/src/registry.ts

@@ -252,6 +252,20 @@ export class TypeRegistry {
           `which is not valid for attrs. Use no valueType (omit the field) for a polymorphic/untyped attr.`,
         );
       }
+      // ADR-0050, the second door. A common attr is a projection onto EVERY type, so a
+      // required one is the same defect as a required `extend` — with the widest possible
+      // blast radius: drop the provider and every type in the registry silently loses a
+      // required-attr rule. Java makes this unrepresentable (its registerCommonAttribute
+      // takes no `required` parameter); TS's AttrSchema carries `required`, so it needs the
+      // explicit guard.
+      if (attr.required === true) {
+        throw new MetaModelError(
+          `TypeRegistry.registerCommonAttrs: attribute "${attr.name}" is REQUIRED. A common attr ` +
+            `is projected onto every registered type, so a required one would vanish from all of ` +
+            `them whenever its provider is composed out. Common attrs must be optional (ADR-0050).`,
+          { code: "ERR_EXTEND_REQUIRED_ATTR" },
+        );
+      }
       if (this._commonAttrs.some((existing) => existing.name === attr.name)) {
         continue; // dedupe same-name re-registration; conflict-with-per-type-attr is checked at validation time
       }
@@ -297,6 +311,26 @@ export class TypeRegistry {
           { code: "ERR_PROVIDER_ATTR_CONFLICT" },
         );
       }
+      // ADR-0050: a REQUIRED attr may never be PROJECTED onto someone else's type.
+      // `extend` is how a concern provider decorates a type another provider owns, and
+      // a concern can be composed out. A required attr arriving this way makes the
+      // target type's validity depend on an optional provider — and the failure is
+      // silent: drop the provider and the type stays registered while its required-attr
+      // rule simply stops firing, so invalid metadata begins loading clean.
+      //
+      // If the attr is genuinely required, it is OWN, not projected: declare it with the
+      // type, in the type's own provider. This is exactly how FR-033 broke template.*'s
+      // @payloadRef / @toolName, and this guard makes that class unrepresentable rather
+      // than merely fixed.
+      if (attr.required === true) {
+        throw new MetaModelError(
+          `TypeRegistry.extend: attribute "${attr.name}" being added to "${type}.${subType}" is REQUIRED. ` +
+            `A provider may only project OPTIONAL attributes onto a type it does not own — a required ` +
+            `attr registered this way disappears, silently, whenever that provider is composed out. ` +
+            `Declare it with the type instead (ADR-0050).`,
+          { code: "ERR_EXTEND_REQUIRED_ATTR" },
+        );
+      }
       def.attributes.push(attr);
     }
     for (const rule of ext.childRules ?? []) {

package/src/shared/base-types.ts

@@ -19,6 +19,9 @@ export const TYPE_ORIGIN = "origin";
 export const TYPE_TEMPLATE = "template";
 /** Non-unique lookup indexes — `index.lookup` is the only registered subtype. */
 export const TYPE_INDEX = "index";
+/** Capability / requirement records — `requirement.functional` (existence check)
+ *  and `requirement.architectural` (universality check). Ruling amendment 3. */
+export const TYPE_REQUIREMENT = "requirement";
 
 export const BASE_TYPES = [
   TYPE_METADATA,
@@ -34,6 +37,7 @@ export const BASE_TYPES = [
   TYPE_ORIGIN,
   TYPE_TEMPLATE,
   TYPE_INDEX,
+  TYPE_REQUIREMENT,
 ] as const;
 export type BaseType = (typeof BASE_TYPES)[number];
 

package/src/shared/node-guards.ts

@@ -0,0 +1,96 @@
+// Cross-realm node guards — identify a node by its metamodel `type`, never by
+// `instanceof`.
+//
+// WHY THESE EXIST
+//
+// `x instanceof MetaSource` is only sound when the class object and the instance
+// come from the SAME physical copy of this package. Two copies in one process —
+// a globally-installed or linked `meta` CLI alongside a project-local
+// dependency — give them different class objects, so `instanceof` returns false
+// for a node that is a source in every observable respect. This is the same
+// class-identity defect that split ts-poet's `Code` objects in 0.21.6; there it
+// was loud (duplicate imports → TS2300), but across the metadata boundary it is
+// SILENT: a consumer package reads the node as "not a source" and simply emits
+// nothing for it, with no error.
+//
+// WHO IS EXPOSED
+//
+// Sites INSIDE this package are immune by construction — a package's own module
+// graph resolves its own files, so the class and the instance always match.
+// The exposed callers are the OTHER packages that import a class from here
+// (`codegen-ts`, `migrate-ts`, `runtime-ts`). `meta gen` / `meta migrate` alias
+// `@metaobjectsdev/metadata` to the CLI's own copy (the CLI's
+// `load-metaobjects-config.ts` CLI_PKG_PATHS), which closes the split for the
+// CLI path — but that alias map does not run when a consumer embeds `runGen()`
+// or the migrate engine programmatically, so cross-package code must not depend
+// on it. A flat single-tree install also dedupes and hides the split, which is
+// why in-process gates do not reproduce it.
+//
+// WHY TYPE-BASED IDENTIFICATION IS EQUIVALENT
+//
+// The registry binds one concrete class per metamodel type (TYPE_SOURCE →
+// MetaSource, TYPE_OBJECT → MetaObject, TYPE_METADATA → MetaRoot), so on a
+// single-copy tree `node.type === TYPE_SOURCE` and `node instanceof MetaSource`
+// answer identically — these guards change nothing there. On a split tree the
+// type still answers correctly, because `type` is data on the node rather than
+// an identity shared with a class object.
+//
+// The returned predicate narrows to this copy's class type. That is a
+// structural assertion, not a claim of instance identity: a foreign-realm node
+// carries the same properties and prototype methods, so every member the caller
+// then touches resolves. Callers needing behaviour from a node that may be
+// foreign should still fail closed if a method is absent.
+
+import { TYPE_FIELD, TYPE_METADATA, TYPE_OBJECT, TYPE_SOURCE } from "./base-types.js";
+import type { MetaData } from "./meta-data.js";
+import type { MetaRoot } from "./meta-root.js";
+import type { MetaObject } from "../core/object/meta-object.js";
+import type { MetaField } from "../core/field/meta-field.js";
+import type { MetaSource } from "../persistence/source/meta-source.js";
+
+/** The node's metamodel `type`, or undefined when the value is not a node at all. */
+function nodeType(node: unknown): string | undefined {
+  if (typeof node !== "object" || node === null) return undefined;
+  const t = (node as { type?: unknown }).type;
+  return typeof t === "string" ? t : undefined;
+}
+
+/** True when the node is a metadata root (type=metadata), across package copies. */
+export function isMetaRoot(node: unknown): node is MetaRoot {
+  return nodeType(node) === TYPE_METADATA;
+}
+
+/** True when the node is an object node (type=object), across package copies. */
+export function isMetaObject(node: unknown): node is MetaObject {
+  return nodeType(node) === TYPE_OBJECT;
+}
+
+/** True when the node is a field node (type=field), across package copies. */
+export function isMetaField(node: unknown): node is MetaField {
+  return nodeType(node) === TYPE_FIELD;
+}
+
+/** True when the node is a source node (type=source), across package copies. */
+export function isMetaSource(node: unknown): node is MetaSource {
+  return nodeType(node) === TYPE_SOURCE;
+}
+
+/**
+ * True when the node is a source that reports itself writable.
+ *
+ * Reads the writability surface through the node rather than through the class,
+ * and fails closed when a foreign node cannot answer — the same outcome the old
+ * `instanceof` guard produced for a node it did not recognise.
+ */
+export function isWritableSource(node: MetaData | undefined): node is MetaSource {
+  if (!isMetaSource(node)) return false;
+  const probe = node as unknown as { isWritable?: () => boolean };
+  return typeof probe.isWritable === "function" && probe.isWritable();
+}
+
+/** True when the node is a source that reports itself read-only. See isWritableSource. */
+export function isReadOnlySource(node: MetaData | undefined): node is MetaSource {
+  if (!isMetaSource(node)) return false;
+  const probe = node as unknown as { isReadOnly?: () => boolean };
+  return typeof probe.isReadOnly === "function" && probe.isReadOnly();
+}