fix(metadata,codegen-ts,migrate-ts,runtime-ts): identify nodes by type, not instanceof

`x instanceof MetaSource` is only sound when the class object and the instance
come from the same physical copy of @metaobjectsdev/metadata. A globally
installed or linked meta CLI alongside a project-local dependency puts two
copies in one process and the class check goes false for a node that is a
source in every observable respect — the class-identity defect that split
ts-poet's Code objects in 0.21.6, which 400c53f fixed for source-detect only.

Across this boundary the failure is SILENT rather than loud. In codegen-ts an
entity reads as "not backed by any store", so no table, queries or routes are
emitted and meta gen still reports success. In migrate-ts it is worse: the
entity drops out of the EXPECTED schema, so migrate sees a live table with no
counterpart and proposes to DROP it, while verify reports drift against a model
that is correct.

The exposure is not "which package the code lives in" — it is who created the
node the function is looking at. Loader-internal work (the validators, parser,
subtype rules) and methods on a node are immune by construction. Anything
taking a CALLER-SUPPLIED node is exposed, and that includes metadata's own
exported helpers: resolveTableName / resolveTableSchema are called by migrate-ts
on loader nodes, and their fallthrough is not a dropped table but the
entity-name fallback — a DIFFERENT table name, which migrate emits as a rename
against a live database. That one is the sharpest edge in the set.

metadata now exports cross-realm guards (shared/node-guards.ts): isMetaRoot /
isMetaObject / isMetaField / isMetaSource / isWritableSource / isReadOnlySource.
They key on the metamodel `type` — the registry binds one class per type, so on
a single-copy tree they and instanceof answer identically — and read behaviour
through the node, failing closed when it cannot answer. All 13 exposed sites are
converted; the rule is recorded in CLAUDE.md under "Coding discipline (TS)".

Output is unchanged: regenerating the canonical Postgres schema with this change
is byte-identical (sha256) to regenerating without it.

Gated by metadata/test/node-guards.test.ts and
migrate-ts/test/expected-schema-cross-realm.test.ts, which simulate the second
copy by re-prototyping a REAL loaded node onto a clone of its own prototype —
every method still resolves, instanceof is false. Each fix was verified by
reverting it and watching the gate reproduce the original symptom.

The migrate gate needed de-blinding first: entity "Order" with @table "orders"
has a name-derived fallback of "orders", the identical string, so it passed with
the defect present. It now uses a @table that differs from the fallback plus a
non-default @Schema. Same failure shape as the case-aligned `like` corpus 0.21.6
had to de-blind.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KTGT5ksntpcJDZVJ5VyXHS

Author: dmealing

CLAUDE.md

@@ -511,6 +511,7 @@ These are the load-bearing principles that have emerged through implementation.
 - **String literals OK only for**: error message text, instance/entity names that are user data, and test data values that aren't metamodel-level concepts.
 - **No backwards-compat hacks.**
 - **No `any` escape hatches.** Use `unknown` and narrow.
+- **Never `instanceof` a metadata node from another package.** Cross-package code (`codegen-ts`, `migrate-ts`, `runtime-ts`, `cli`) identifies nodes with the guards `@metaobjectsdev/metadata` exports — `isMetaRoot` / `isMetaObject` / `isMetaField` / `isMetaSource` / `isWritableSource` / `isReadOnlySource` — never `x instanceof MetaSource`. Two physical copies of the package in one process (a globally-installed or linked `meta` CLI plus a project-local dependency) give the class object and the instance different identities, so `instanceof` returns **false for a real node**. The failure is **silent**: in `codegen-ts` the entity reads as "not backed by any store" and simply emits no table/queries/routes; in `migrate-ts` it drops the table from the EXPECTED schema, so `meta migrate` proposes `DROP TABLE` against a live database. This is the same class-identity defect that split ts-poet's `Code` objects in 0.21.6. The CLI's alias map (`load-metaobjects-config.ts` `CLI_PKG_PATHS`) closes it for `meta gen`/`migrate` **only** — a consumer embedding `runGen()` or the migrate engine programmatically never runs it. Sites **inside** `metadata` are immune by construction (a package's own module graph resolves its own files) and keep using `instanceof`. Mechanism + blast radius: `metadata/src/shared/node-guards.ts`.
 
 ## Useful commands
 

server/typescript/packages/codegen-ts/src/projection/build-projection-views.ts

@@ -12,8 +12,11 @@ import {
   type AggregateFunction,
   type MetaData,
   MetaObject,
-  MetaRoot,
-  MetaSource,
+  type MetaRoot,
+  type MetaSource,
+  isMetaRoot,
+  isReadOnlySource,
+  isWritableSource,
   SOURCE_KIND_VIEW,
   TYPE_FIELD,
   TYPE_IDENTITY,
@@ -81,7 +84,9 @@ export function buildProjectionViews(
   root: MetaData,
   opts: BuildProjectionViewsOptions,
 ): ExpectedView[] {
-  if (!(root instanceof MetaRoot)) {
+  // isMetaRoot, not `instanceof`: under a split @metaobjectsdev/metadata tree the
+  // class check rejects a perfectly good root, turning a working build into a throw.
+  if (!isMetaRoot(root)) {
     throw new Error("buildProjectionViews: root must be a loaded MetaRoot.");
   }
   // D1 is SQLite at the SQL level.
@@ -164,9 +169,7 @@ type ReadOnlySourceClass =
   | { kind: "derive"; source: MetaSource };
 
 function classifyReadOnlySource(host: MetaObject): ReadOnlySourceClass {
-  const source = host.ownChildren().find(
-    (c): c is MetaSource => c instanceof MetaSource && c.isReadOnly(),
-  );
+  const source = host.ownChildren().find(isReadOnlySource);
   if (source === undefined) return { kind: "skip" };
   if (source.isUnmanaged) return { kind: "skip" }; // external — Flyway/hand-migration owns it
   if (source.sqlBody !== undefined) return { kind: "sql", source }; // author-supplied body
@@ -265,9 +268,7 @@ function collectSqlDependsOn(
 ): string[] {
   const tables = new Set<string>();
   // The write-through host's own writable table (keyed the way the diff keys descriptors).
-  const hasWritableSource = host.ownChildren().some(
-    (c) => c instanceof MetaSource && c.isWritable(),
-  );
+  const hasWritableSource = host.ownChildren().some(isWritableSource);
   if (hasWritableSource) {
     const t = joinTables[host.resolutionKey()];
     if (t !== undefined) tables.add(t);

server/typescript/packages/codegen-ts/src/projection/extract-view-spec.ts

@@ -3,7 +3,8 @@ import {
   TYPE_IDENTITY,
   TYPE_ORIGIN,
   TYPE_RELATIONSHIP,
-  MetaSource,
+  isMetaObject,
+  isReadOnlySource,
   ORIGIN_SUBTYPE_PASSTHROUGH,
   ORIGIN_SUBTYPE_AGGREGATE,
   ORIGIN_SUBTYPE_COMPUTED,
@@ -252,9 +253,7 @@ function viewName(projection: MetaObject, ctx: ExtractContext): string {
   // ADR-0039: own — projection source classification (mirrors C# projection
   // OwnSources / IsReadOnlyProjection): the view name comes from the projection's
   // OWN read-only source, not one inherited via extends.
-  const viewSource = projection.ownChildren().find(
-    (c): c is MetaSource => c instanceof MetaSource && c.isReadOnly(),
-  );
+  const viewSource = projection.ownChildren().find(isReadOnlySource);
   const explicit = viewSource?.physicalName;
   // physicalName always returns a string; empty string means the source had
   // neither alias nor a name and the owning entity name was empty (impossible
@@ -317,7 +316,7 @@ function packageOf(obj: MetaData): string {
  */
 function resolveEntityRef(root: MetaRoot, ref: string, referrerPkg: string): MetaObject | undefined {
   const node = resolveObjectRef(root, ref, referrerPkg).node;
-  return node instanceof MetaObject ? node : undefined;
+  return isMetaObject(node) ? node : undefined;
 }
 
 function baseEntityFor(

server/typescript/packages/codegen-ts/src/projection/projection-detector.ts

@@ -1,20 +1,20 @@
-import { MetaSource } from "@metaobjectsdev/metadata";
+// isReadOnlySource / isWritableSource rather than `instanceof MetaSource`: a
+// second physical copy of @metaobjectsdev/metadata makes the class check false
+// for a real source, which would silently reclassify every projection and
+// write-through entity as a vanilla entity.
+import { isReadOnlySource, isWritableSource } from "@metaobjectsdev/metadata";
 import type { MetaData } from "@metaobjectsdev/metadata";
 
 function hasReadOnlyKindSource(entity: MetaData): boolean {
   // ADR-0039: own — projection source-kind classification. Mirrors C#
   // IsReadOnlyProjection()/projection OwnSources: an entity's projection-ness is
   // determined by its OWN declared source @kind, not one inherited via extends.
-  return entity.ownChildren().some(
-    (c) => c instanceof MetaSource && c.isReadOnly(),
-  );
+  return entity.ownChildren().some(isReadOnlySource);
 }
 
 function hasWritableKindSource(entity: MetaData): boolean {
   // ADR-0039: own — projection source-kind classification (see hasReadOnlyKindSource).
-  return entity.ownChildren().some(
-    (c) => c instanceof MetaSource && c.isWritable(),
-  );
+  return entity.ownChildren().some(isWritableSource);
 }
 
 export function isProjection(entity: MetaData): boolean {

server/typescript/packages/codegen-ts/src/runner.ts

@@ -3,7 +3,7 @@ import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { existsSync, readFileSync } from "node:fs";
 import type { MetaData, MetaObject } from "@metaobjectsdev/metadata";
-import { MetaRoot, OBJECT_SUBTYPE_VALUE, FIELD_SUBTYPE_TIMESTAMP, FIELD_ATTR_FILTERABLE } from "@metaobjectsdev/metadata";
+import { isMetaRoot, OBJECT_SUBTYPE_VALUE, FIELD_SUBTYPE_TIMESTAMP, FIELD_ATTR_FILTERABLE } from "@metaobjectsdev/metadata";
 import { assignEmittedNames } from "./naming/collision-names.js";
 import { isAbstract } from "./instance-artifacts.js";
 import { hasAnyRdbSource } from "./source-detect.js";
@@ -128,7 +128,10 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
 
   // loadMemory now returns MetaRoot; guard here also covers callers that pass a
   // plain MetaData (e.g. test helpers that build trees programmatically).
-  if (!(opts.metadata instanceof MetaRoot)) {
+  // isMetaRoot, not `instanceof`: a consumer embedding runGen() programmatically
+  // never runs the CLI's @metaobjectsdev/metadata alias, so a split tree would
+  // reject the very root the caller just loaded.
+  if (!isMetaRoot(opts.metadata)) {
     throw new Error("runGen: opts.metadata must be a loaded MetaRoot.");
   }
   const root = opts.metadata;

server/typescript/packages/codegen-ts/src/source-detect.ts

@@ -6,40 +6,20 @@
 // metadata-driven, not a typeId discriminator: any object subtype can opt out
 // of Drizzle table emission simply by omitting source.rdb.
 
-import { TYPE_SOURCE, SOURCE_SUBTYPE_RDB } from "@metaobjectsdev/metadata";
+// Cross-realm safety: identify a source by metamodel type/subType and read its
+// writability through the node, never by `instanceof MetaSource`. Two physical
+// copies of @metaobjectsdev/metadata make the class check false for a real
+// source, and here the consequence is SILENT — the entity reads as "not backed
+// by any store", so no Drizzle table, no queries and no routes are emitted for
+// it and nothing errors. Mechanism and blast radius: metadata's
+// shared/node-guards.ts. Gated by test/source-detect.test.ts ("survives a split
+// @metaobjectsdev/metadata tree").
+import { SOURCE_SUBTYPE_RDB, isMetaSource, isWritableSource } from "@metaobjectsdev/metadata";
 import type { MetaData, MetaObject } from "@metaobjectsdev/metadata";
 
-// Cross-realm safety: identify a source structurally (type/subType + the
-// writability surface), never by `instanceof MetaSource`.
-//
-// Two physical copies of @metaobjectsdev/metadata in one process give the
-// loader's nodes a different MetaSource class object than this module closes
-// over, so `instanceof` is false for a node that is a source.rdb in every
-// observable respect — the same class-identity defect that split ts-poet's Code
-// objects in 0.21.6. Here the consequence is silent: the entity reads as "not
-// backed by any store", so no Drizzle table, no queries and no routes are
-// emitted for it, and nothing errors.
-//
-// `meta gen` aliases @metaobjectsdev/metadata to the CLI's own copy
-// (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()
-// programmatically, so these helpers do not depend on it. Gated by
-// test/source-detect.test.ts ("survives a split @metaobjectsdev/metadata tree").
-
-/** True when the child is a source.rdb node, by structure rather than class identity. */
+/** True when the child is a source.rdb node (subType-scoped — the rdb paradigm only). */
 function isRdbSource(child: MetaData): boolean {
-  return child.type === TYPE_SOURCE && child.subType === SOURCE_SUBTYPE_RDB;
-}
-
-/**
- * True when the node reports itself writable. Reads the writability surface
- * structurally so a source built by a second copy of the package still answers.
- * A node that cannot answer is not counted as writable (fail-closed — the same
- * outcome the `instanceof` guard produced for a non-source node).
- */
-function reportsWritable(child: MetaData): boolean {
-  const probe = child as unknown as { isWritable?: () => boolean };
-  return typeof probe.isWritable === "function" && probe.isWritable();
+  return isMetaSource(child) && child.subType === SOURCE_SUBTYPE_RDB;
 }
 
 /**
@@ -55,7 +35,7 @@ export function hasWritableRdbSource(entity: MetaObject): boolean {
   // would suppress the Drizzle table for such an entity.
   for (const child of entity.children()) {
     if (!isRdbSource(child)) continue;
-    if (reportsWritable(child)) return true;
+    if (isWritableSource(child)) return true;
   }
   return false;
 }

server/typescript/packages/codegen-ts/src/templates/callable-file.ts

@@ -21,7 +21,8 @@
 
 import {
   type MetaObject,
-  MetaSource,
+  type MetaSource,
+  isMetaSource,
   SOURCE_ATTR_PARAMETER_REF,
   SOURCE_KIND_STORED_PROC,
   SOURCE_KIND_TABLE_FUNCTION,
@@ -47,7 +48,9 @@ function callableSource(entity: MetaObject): MetaSource | undefined {
   // ADR-0039: resolving — an entity may inherit its callable source.rdb via extends.
   for (const child of entity.children()) {
     if (child.type !== TYPE_SOURCE) continue;
-    if (!(child instanceof MetaSource)) continue;
+    // isMetaSource, not `instanceof`: a split @metaobjectsdev/metadata tree would
+    // make the class check false and silently emit no callable wrapper.
+    if (!isMetaSource(child)) continue;
     if (CALLABLE_KINDS.has(child.effectiveKind)) return child;
   }
   return undefined;

server/typescript/packages/codegen-ts/src/templates/projection-decl.ts

@@ -9,7 +9,7 @@
 
 import { code, imp, joinCode, type Code } from "ts-poet";
 import {
-  MetaField, MetaObject, type MetaRoot,
+  MetaField, MetaObject, type MetaRoot, isMetaObject,
   FIELD_ATTR_OBJECT_REF, stripPackage,
 } from "@metaobjectsdev/metadata";
 import { projectionViewName } from "../projection/extract-view-spec.js";
@@ -126,7 +126,7 @@ export function renderProjectionDecl(
   const superName = superModel?.name ?? projection.superRef;
   if (superName) {
     const baseObj =
-      superModel instanceof MetaObject ? superModel : root.findObject(superName);
+      isMetaObject(superModel) ? superModel : root.findObject(superName);
     if (baseObj) {
       // fields() returns effective fields, so inherited fields (from extends:/super:) are included.
       for (const f of baseObj.fields()) allFields.push(f);

server/typescript/packages/metadata/src/index.ts

@@ -48,6 +48,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";

server/typescript/packages/metadata/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.