chore: integrate 1.1.0 twin machinery with the v2 catalog after rebase

Author: rahlk

schema.neo4j.json

@@ -406,5 +406,20 @@
   "indexes": [
     "CREATE INDEX callable_name IF NOT EXISTS FOR (c:Callable) ON (c.name)",
     "CREATE INDEX cannode_kind IF NOT EXISTS FOR (n:CanNode) ON (n.kind)"
-  ]
+  ],
+  "label_twins": {
+    "Application": "TSApplication",
+    "Module": "TSModule",
+    "Class": "TSClass",
+    "Interface": "TSInterface",
+    "Enum": "TSEnum",
+    "TypeAlias": "TSTypeAlias",
+    "Namespace": "TSNamespace",
+    "Callable": "TSCallable",
+    "Field": "TSField",
+    "BodyNode": "TSBodyNode",
+    "External": "TSExternal",
+    "AnonymousCallable": "TSAnonymousCallable",
+    "Entrypoint": "TSEntrypoint"
+  }
 }

src/build/neo4j/project.ts

@@ -11,7 +11,7 @@
  */
 
 import type { V2Application, V2BodyNode, V2Callable, V2External, V2Field, V2Module, V2Node, V2Root, V2Type } from "../../schema/v2";
-import { SCHEMA_VERSION } from "./schema";
+import { SCHEMA_VERSION, withTwins } from "./schema";
 import { type GraphRows, type NodeRef, type Prop, type Props, RowBuilder, prune } from "./rows";
 
 /** The shared MERGE label + key every can://-id-keyed node is addressed by. */
@@ -42,7 +42,7 @@ const KIND_LABEL: Record<string, string> = {
 };
 
 export function project(app: V2Application, _appName?: string): GraphRows {
-  const b = new RowBuilder();
+  const b = new RowBuilder(withTwins);
   const root: V2Root = app.application;
 
   const appRef = b.node(["Application"], "id", root.id, prune({

src/build/neo4j/rows.ts

@@ -61,11 +61,19 @@ export class RowBuilder {
   private readonly deferred: EdgeRow[] = []; // edges gated against node existence at finish()
   private readonly keys = new Set<string>(); // every node value seen, for resolved-gating
 
+  /**
+   * @param expand optional label-set expander applied to every node's labels (the schema layer
+   * injects its twin-label policy here; rows.ts itself stays schema-agnostic). Must keep the
+   * merge label at index 0.
+   */
+  constructor(private readonly expand: (labels: string[]) => string[] = (l) => l) {}
+
   /**
    * Upsert a node. Re-seeing the same (mergeLabel, value) merges props (last write wins) and
    * unions labels — the in-memory analog of `MERGE (n:Label {key}) SET n += props`.
    */
   node(labels: string[], keyProp: string, value: string, props: Props): NodeRef {
+    labels = this.expand(labels);
     const id = `${labels[0]}\0${value}`;
     const existing = this.nodes.get(id);
     if (existing) {

src/build/neo4j/schema.ts

@@ -38,6 +38,35 @@ export interface RelType {
 /** Labels layered onto a node in addition to its primary/specific label. */
 export const MARKER_LABELS = ["Entrypoint"] as const;
 
+/**
+ * Language-namespace twins (transient dual-labeling, issue #65): every specific and marker label is
+ * also stamped as `TS<Label>` so a shared multi-language database can attribute TS nodes (epic #64).
+ * The shared MERGE labels (`Symbol`, `CanNode`) deliberately have NO twin — MERGE targets, keys and
+ * constraints are unchanged. This dual-label state is transient; the vocabulary is finalized later.
+ */
+export const TS_PREFIX = "TS";
+
+/** The TS-prefixed twin of a specific or marker label. */
+export const twinOf = (label: string): string => `${TS_PREFIX}${label}`;
+
+/** Shared merge labels never get a twin — they carry the constraint; node identity is unchanged. */
+const UNTWINNED = new Set(["Symbol", "CanNode"]);
+
+/**
+ * Expand a projection label set with its twins: order preserved, shared merge labels skipped,
+ * idempotent. Any label already starting with `TS` is treated as a twin and never re-prefixed — so
+ * no bare label may legitimately begin with `TS`.
+ */
+export function withTwins(labels: string[]): string[] {
+  const out = [...labels];
+  for (const l of labels) {
+    if (UNTWINNED.has(l) || l.startsWith(TS_PREFIX)) continue;
+    const t = twinOf(l);
+    if (!out.includes(t)) out.push(t);
+  }
+  return out;
+}
+
 /** The shared MERGE label for every can://-id-keyed node (one constraint; uniform edge endpoints). */
 const CAN = "CanNode";
 const SPAN = { start_line: "integer", end_line: "integer" } as const;
@@ -200,6 +229,16 @@ export interface SchemaDocument {
   relationship_types: RelType[];
   constraints: readonly string[];
   indexes: readonly string[];
+  /** Specific/marker label → its TS-prefixed twin (both are present on every emitted node). */
+  label_twins: Record<string, string>;
+}
+
+/** One twin per specific label + per marker label — derived from the catalogs, never drifts. */
+function labelTwins(): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const n of NODE_LABELS) out[n.label] = twinOf(n.label);
+  for (const m of MARKER_LABELS) out[m] = twinOf(m);
+  return out;
 }
 
 /** Build the full machine-readable schema document emitted by `--emit schema`. */
@@ -212,5 +251,6 @@ export function buildSchemaDocument(): SchemaDocument {
     relationship_types: REL_TYPES,
     constraints: CONSTRAINTS,
     indexes: INDEXES,
+    label_twins: labelTwins(),
   };
 }

test/neo4j-schema.test.ts

@@ -16,6 +16,8 @@ import {
   REL_TYPES,
   buildSchemaDocument,
   project,
+  twinOf,
+  withTwins,
 } from "../src/build/neo4j";
 import { analyze } from "../src/core";
 import type { AnalysisOptions } from "../src/options";
@@ -44,13 +46,17 @@ const byLabel = new Map(NODE_LABELS.map((n) => [n.label, n]));
 const mergeOf = new Map(NODE_LABELS.map((n) => [n.label, n.mergeLabel]));
 const relByType = new Map(REL_TYPES.map((r) => [r.type, r]));
 const markers = new Set<string>(MARKER_LABELS);
+const twins = new Set<string>([
+  ...NODE_LABELS.map((n) => twinOf(n.label)),
+  ...MARKER_LABELS.map((m) => twinOf(m)),
+]);
 const mergeLabelsFor = (specifics: string[]) => new Set(specifics.map((s) => mergeOf.get(s)));
 
-/** The specific (schema) label for a node row: the non-merge, non-marker label (`Application`
- * has only its own label; every `CanNode` carries exactly one specific kind label). */
+/** The specific (schema) label for a node row: the non-merge, non-marker, non-twin label
+ * (`Application` has only its own label; every `CanNode` carries exactly one specific kind label). */
 function specificLabel(labels: string[]): string {
   const merge = labels[0];
-  return labels.find((l) => l !== merge && !markers.has(l)) ?? merge;
+  return labels.find((l) => l !== merge && !markers.has(l) && !twins.has(l)) ?? merge;
 }
 
 const rows = await fixtureRows();
@@ -65,7 +71,7 @@ describe("neo4j schema conformance", () => {
       expect(node.labels[0]).toBe(decl!.mergeLabel);
 
       for (const label of node.labels) {
-        const ok = label === decl!.mergeLabel || label === specific || markers.has(label);
+        const ok = label === decl!.mergeLabel || label === specific || markers.has(label) || twins.has(label);
         expect(ok, `unexpected label '${label}' on ${specific}`).toBe(true);
       }
       for (const key of Object.keys(node.props)) {
@@ -91,6 +97,17 @@ describe("neo4j schema conformance", () => {
     const fresh = JSON.stringify(buildSchemaDocument(), null, 2).trim();
     expect(onDisk).toBe(fresh);
   });
+
+  test("every node carries exactly the TS twins of its base labels (transient dual-labeling)", () => {
+    for (const node of rows.nodes) {
+      const base = node.labels.filter((l) => !twins.has(l));
+      expect(new Set(node.labels), `bad twin set on ${node.labels.join(":")} ${node.value}`).toEqual(
+        new Set(withTwins(base)),
+      );
+      // the shared merge label (`CanNode` / `Application`) stays bare at index 0.
+      expect(twins.has(node.labels[0]), `merge label must stay bare: ${node.labels[0]}`).toBe(false);
+    }
+  });
 });
 
 // ---- :Application analyzer identity (issue #43) ------------------------------------------------

test/neo4j-twins.test.ts

@@ -1,6 +1,8 @@
 /**
- * Twin-label vocabulary (graph schema 1.1.0, issue #65): every specific and marker label has a
- * TS-prefixed twin; the shared merge label `Symbol` deliberately has none (epic #64).
+ * Twin-label vocabulary (transient dual-labeling on graph schema 2.0.0, issue #65): every specific
+ * and marker label has a TS-prefixed twin; the shared merge labels (`Symbol`, `CanNode`)
+ * deliberately have none (epic #64). The v2 catalog merges on `CanNode`, so it is the merge label
+ * that must stay bare here.
  */
 import { describe, expect, test } from "bun:test";
 import {
@@ -20,25 +22,31 @@ describe("TS twin-label vocabulary", () => {
     expect(twinOf("Entrypoint")).toBe("TSEntrypoint");
   });
 
-  test("withTwins appends a twin per label, keeps order, and skips Symbol", () => {
+  test("withTwins appends a twin per label, keeps order, and skips shared merge labels", () => {
     expect(withTwins(["Module"])).toEqual(["Module", "TSModule"]);
+    // both shared merge labels are skipped (v2 merges on CanNode)
+    expect(withTwins(["CanNode", "Callable"])).toEqual(["CanNode", "Callable", "TSCallable"]);
     expect(withTwins(["Symbol", "Class"])).toEqual(["Symbol", "Class", "TSClass"]);
-    expect(withTwins(["Symbol", "Callable", "Entrypoint"])).toEqual([
-      "Symbol", "Callable", "Entrypoint", "TSCallable", "TSEntrypoint",
+    expect(withTwins(["CanNode", "Callable", "Entrypoint"])).toEqual([
+      "CanNode", "Callable", "Entrypoint", "TSCallable", "TSEntrypoint",
     ]);
     // idempotent: an already-expanded set gains nothing
     expect(withTwins(["Module", "TSModule"])).toEqual(["Module", "TSModule"]);
   });
 
-  test("schema version is 1.1.0 (additive MINOR)", () => {
-    expect(SCHEMA_VERSION).toBe("1.1.0");
+  test("schema version is 2.0.0 (v2 catalog)", () => {
+    expect(SCHEMA_VERSION).toBe("2.0.0");
   });
 
   test("schema document maps every specific + marker label to its twin", () => {
     const doc = buildSchemaDocument();
     for (const n of NODE_LABELS) expect(doc.label_twins[n.label]).toBe(twinOf(n.label));
     for (const m of MARKER_LABELS) expect(doc.label_twins[m]).toBe(twinOf(m));
+    // shared merge labels are never specific/marker labels, so they map to nothing
+    expect(doc.label_twins["CanNode"]).toBeUndefined();
     expect(doc.label_twins["Symbol"]).toBeUndefined();
+    // 12 node labels + 1 marker (Entrypoint) = 13 twins
+    expect(Object.keys(doc.label_twins).length).toBe(13);
     expect(Object.keys(doc.label_twins).length).toBe(NODE_LABELS.length + MARKER_LABELS.length);
   });
 });