@metaobjectsdev/metadata 0.9.0 → 0.10.0

package/src/core/identity/validate-identity-passthrough.ts

@@ -0,0 +1,194 @@
+// Validation pass: FR-024 projection identity pass-through + key correspondence.
+//
+// A projection's identity is a PASS-THROUGH of an entity identity:
+//
+//   - every identity child of an object.projection MUST extend an entity
+//     identity (the dotted by-name form, e.g. `extends: "Customer.id"`);
+//     a projection identity without `extends` → ERR_PROJECTION_IDENTITY_NOT_EXTENDED.
+//   - key correspondence: every field named by the extended identity's
+//     @fields must have a local projection field extending it; a missing
+//     pass-through → ERR_IDENTITY_KEY_MISMATCH.
+//   - the identity's local key is COMPUTED from those local fields (in the
+//     extended identity's order) — derived on read, NEVER written back into
+//     the tree (metadata is the authored spine; the loader never mutates it).
+//     An explicit @fields that disagrees with the computed set →
+//     ERR_IDENTITY_KEY_MISMATCH.
+//
+// Unresolved / type-mismatched `extends` refs are NOT re-reported here — the
+// deferred-super pass already emitted ERR_UNRESOLVED_SUPER /
+// ERR_EXTENDS_TARGET_MISMATCH for those.
+
+import type { MetaData } from "../../shared/meta-data.js";
+import { ParseError } from "../../errors.js";
+import { TYPE_OBJECT, TYPE_IDENTITY, TYPE_FIELD } from "../../shared/base-types.js";
+import { OBJECT_SUBTYPE_PROJECTION } from "../object/object-constants.js";
+import { IDENTITY_ATTR_FIELDS } from "./identity-constants.js";
+
+/**
+ * Normalize an identity's OWN @fields attr to a string[]. Accepts both the
+ * array form (["id"]) and the comma-string form ("id" / "a,b"); returns
+ * undefined when the identity declares no own @fields (the pass-through case).
+ */
+export function identityOwnFields(identity: MetaData): string[] | undefined {
+  return normalizeFields(identity.ownAttr(IDENTITY_ATTR_FIELDS));
+}
+
+/** Normalize an identity's EFFECTIVE @fields attr (inherits through extends). */
+export function identityEffectiveFields(identity: MetaData): string[] | undefined {
+  return normalizeFields(identity.attr(IDENTITY_ATTR_FIELDS));
+}
+
+function normalizeFields(raw: unknown): string[] | undefined {
+  if (raw === undefined || raw === null) return undefined;
+  if (Array.isArray(raw)) return raw.map((v) => String(v).trim());
+  if (typeof raw === "string") {
+    return raw
+      .split(",")
+      .map((s) => s.trim())
+      .filter((s) => s.length > 0);
+  }
+  return undefined;
+}
+
+/** The result of deriving a projection identity's pass-through key. */
+export interface IdentityPassthroughResolution {
+  /** The owning entity of the extended identity. */
+  readonly entity: MetaData;
+  /** Local pass-through field names, in the extended identity's @fields order. */
+  readonly computedFields: string[];
+  /** Extended-identity field names with NO local pass-through field. */
+  readonly missing: string[];
+}
+
+/**
+ * Derive a projection identity's pass-through key — a PURE read of the
+ * resolved tree (no mutation): for each field name in the extended identity's
+ * effective @fields, find the local field whose extends-chain reaches the
+ * entity's field of that name; the computed key is those local field names in
+ * the extended identity's order.
+ *
+ * Returns undefined when the identity has no resolved identity super (the
+ * not-extended / unresolved / mismatched cases — reported elsewhere).
+ */
+export function resolveIdentityPassthrough(
+  identity: MetaData,
+): IdentityPassthroughResolution | undefined {
+  const extended = identity.superResolved;
+  if (extended === undefined || extended.type !== TYPE_IDENTITY) return undefined;
+  const entity = extended.parent;
+  if (entity === undefined || entity.type !== TYPE_OBJECT) return undefined;
+  const owner = identity.parent;
+  if (owner === undefined) return undefined;
+
+  const extendedFields = identityEffectiveFields(extended) ?? [];
+  const computedFields: string[] = [];
+  const missing: string[] = [];
+  for (const fieldName of extendedFields) {
+    const entityField = entity
+      .children()
+      .find((c) => c.type === TYPE_FIELD && c.name === fieldName);
+    if (entityField === undefined) {
+      missing.push(fieldName);
+      continue;
+    }
+    const local = owner
+      .ownChildren()
+      .find((c) => c.type === TYPE_FIELD && extendsChainReaches(c, entityField));
+    if (local === undefined) {
+      missing.push(fieldName);
+      continue;
+    }
+    computedFields.push(local.name);
+  }
+  return { entity, computedFields, missing };
+}
+
+/**
+ * The computed pass-through key of a projection identity, or undefined when
+ * the identity is not a fully-corresponding pass-through. Codegen-facing
+ * convenience over resolveIdentityPassthrough.
+ */
+export function computedIdentityFields(identity: MetaData): string[] | undefined {
+  const res = resolveIdentityPassthrough(identity);
+  if (res === undefined || res.missing.length > 0) return undefined;
+  return res.computedFields;
+}
+
+function extendsChainReaches(node: MetaData, target: MetaData): boolean {
+  let cur = node.superResolved;
+  while (cur !== undefined) {
+    if (cur === target) return true;
+    cur = cur.superResolved;
+  }
+  return false;
+}
+
+function arraysEqual(a: readonly string[], b: readonly string[]): boolean {
+  return a.length === b.length && a.every((v, i) => v === b[i]);
+}
+
+/**
+ * Walk every object.projection in the root and enforce the pass-through +
+ * key-correspondence rules. Returns errors; never mutates the tree.
+ */
+export function validateIdentityPassthrough(root: MetaData): ParseError[] {
+  const errors: ParseError[] = [];
+
+  for (const obj of root
+    .ownChildren()
+    .filter(
+      (c) => c.type === TYPE_OBJECT && c.subType === OBJECT_SUBTYPE_PROJECTION,
+    )) {
+    for (const identity of obj
+      .ownChildren()
+      .filter((c) => c.type === TYPE_IDENTITY)) {
+      if (identity.superRef === undefined) {
+        errors.push(
+          new ParseError(
+            `identity '${identity.name}' on projection '${obj.name}' must extend an entity identity ` +
+              `(e.g. extends: "Customer.id") — a projection identity is a pass-through (FR-024)`,
+            {
+              code: "ERR_PROJECTION_IDENTITY_NOT_EXTENDED",
+              source: identity.source,
+            },
+          ),
+        );
+        continue;
+      }
+
+      const res = resolveIdentityPassthrough(identity);
+      // Unresolved or non-identity target: ERR_UNRESOLVED_SUPER /
+      // ERR_EXTENDS_TARGET_MISMATCH already reported by the deferred-super pass.
+      if (res === undefined) continue;
+
+      if (res.missing.length > 0) {
+        const missingRefs = res.missing
+          .map((f) => `'${res.entity.name}.${f}'`)
+          .join(", ");
+        errors.push(
+          new ParseError(
+            `identity '${identity.name}' on projection '${obj.name}' does not correspond to its ` +
+              `extended identity: no local field extends ${missingRefs} — every field of the ` +
+              `extended identity needs a pass-through field on the projection (FR-024)`,
+            { code: "ERR_IDENTITY_KEY_MISMATCH", source: identity.source },
+          ),
+        );
+        continue;
+      }
+
+      const explicit = identityOwnFields(identity);
+      if (explicit !== undefined && !arraysEqual(explicit, res.computedFields)) {
+        errors.push(
+          new ParseError(
+            `identity '${identity.name}' on projection '${obj.name}' declares @fields ` +
+              `[${explicit.join(", ")}] but the computed pass-through key is ` +
+              `[${res.computedFields.join(", ")}] — omit @fields (it is derived) or make them agree (FR-024)`,
+            { code: "ERR_IDENTITY_KEY_MISMATCH", source: identity.source },
+          ),
+        );
+      }
+    }
+  }
+
+  return errors;
+}

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

@@ -9,14 +9,17 @@ import { SUBTYPE_BASE } from "../../shared/base-types.js";
 //   - base   : abstract template (no runtime semantics)
 //   - entity : persistent record (typically has @primary identity)
 //   - value  : value-object (no identity; equality by content)
+//   - projection : derived read-only representation of entities (FR-024, ADR-0028)
 //
 export const OBJECT_SUBTYPE_ENTITY = "entity";
 export const OBJECT_SUBTYPE_VALUE = "value";
+export const OBJECT_SUBTYPE_PROJECTION = "projection";
 
 export const OBJECT_SUBTYPES = [
   SUBTYPE_BASE,
   OBJECT_SUBTYPE_ENTITY,
   OBJECT_SUBTYPE_VALUE,
+  OBJECT_SUBTYPE_PROJECTION,
 ] as const;
 export type ObjectSubType = (typeof OBJECT_SUBTYPES)[number];
 

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

@@ -0,0 +1,117 @@
+// AUTO-GENERATED by scripts/generate-embedded-metamodel.ts — DO NOT EDIT.
+// Canonical source: repo-root spec/metamodel/object.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 OBJECT_DEFINITION: ProviderDefinition = {
+  "provider": "metaobjects-core-types",
+  "types": [
+    {
+      "type": "object",
+      "subType": "base",
+      "description": "Abstract object base — the shared root subtype that concrete object subtypes (entity/value/projection) specialize. Declares the structural children common to EVERY object subtype (the intersection: field/identity/validator/layout/source); subtype-specific children (relationship, template) and attrs (discriminator) ride their own subtypes. Has no runtime semantics of its own; not authored directly.",
+      "children": [
+        {
+          "type": "field",
+          "subType": "*",
+          "name": "*",
+          "min": 0,
+          "max": null
+        },
+        {
+          "type": "identity",
+          "subType": "*",
+          "name": "*",
+          "min": 0,
+          "max": null
+        },
+        {
+          "type": "validator",
+          "subType": "*",
+          "name": "*",
+          "min": 0,
+          "max": null
+        },
+        {
+          "type": "layout",
+          "subType": "*",
+          "name": "*",
+          "min": 0,
+          "max": null
+        },
+        {
+          "type": "source",
+          "subType": "*",
+          "name": "*",
+          "min": 0,
+          "max": null
+        }
+      ]
+    },
+    {
+      "type": "object",
+      "subType": "entity",
+      "extendsBase": true,
+      "description": "An object that owns its data: own identity, writable sources, and lifecycle. The default object subtype — a bare `object:` key resolves to entity. May co-locate templates (template.prompt and friends) with the owning entity.",
+      "rules": "object.entity owns data — it declares its own identity, its primary source must be a writable @kind (read-only kinds may appear only in a read role), and it carries lifecycle. A field carrying origin.* is derived ⇒ read-only wherever it lives, including on an entity. Templates (template.*) may be nested so a prompt can be co-located with its owning entity. See ADR-0028 (object taxonomy).",
+      "children": [
+        {
+          "type": "relationship",
+          "subType": "*",
+          "name": "*",
+          "min": 0,
+          "max": null
+        },
+        {
+          "type": "template",
+          "subType": "*",
+          "name": "*",
+          "min": 0,
+          "max": null
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "discriminator",
+          "min": 0,
+          "max": 1,
+          "description": "FR-014: names the field on this entity (resolvable via extends:) that holds the subtype-discriminator value. Subtypes of this entity declare @discriminatorValue to bind their rows to a discriminator value. The discriminator field itself is an ordinary field declaration (typically field.enum or field.int / field.string)."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "discriminatorValue",
+          "min": 0,
+          "max": 1,
+          "description": "FR-014: on a subtype of an entity with @discriminator — the value that identifies rows of this subtype in the shared discriminator field. Wire form is always a string; the underlying field's subtype (enum / int / string) controls codegen + storage coercion. Required on every concrete subtype of a discriminated entity."
+        }
+      ]
+    },
+    {
+      "type": "object",
+      "subType": "value",
+      "extendsBase": true,
+      "description": "A value object — pure shape with NO identity and NO source, ever. Constructed (by caller / assembly / embedding), never populated from a store. May `extends` an entity's fields to reuse shape. Equality is by content.",
+      "rules": "object.value is pure shape: it NEVER declares an identity and NEVER declares a source, in any role. It is constructed — by a caller, by assembly, or by embedding — and is never populated from a backing store. It may `extends` an entity's fields to reuse their shape. @normalize is the object-level default ASCII normalization mode applied to this value's enum fields' tolerant extract (each field may still override per-field). See ADR-0028 (object taxonomy, value purity).",
+      "children": [
+        {
+          "type": "relationship",
+          "subType": "*",
+          "name": "*",
+          "min": 0,
+          "max": null
+        }
+      ]
+    },
+    {
+      "type": "object",
+      "subType": "projection",
+      "extendsBase": true,
+      "description": "A derived read-only representation of entities. Its fields are extends-bound / origin-derived / self-declared-under-external-assembly, all read-only at the subtype level. Identity is optional and MUST extend an entity identity; sources are restricted to read-only @kinds. The declared field set IS the exposure (inclusive, fail-closed).",
+      "rules": "object.projection is a derived read-only representation: every field is extends-bound, origin-derived, or self-declared-under-external-assembly, and all are read-only at the subtype level. Identity is optional and, when present, MUST extend an entity identity. Sources are restricted to read-only @kinds. The declared field set IS the exposure — an inclusive list, fail-closed. A projection NEVER declares relationships (derivation is expressed via @via, not a relationship child) and NEVER co-locates templates — hence its child set omits both relationship and template. See ADR-0028 (object taxonomy, projection)."
+    }
+  ]
+};

package/src/core/object/validate-discriminator.ts

@@ -28,8 +28,6 @@ import {
   FIELD_SUBTYPE_ENUM,
   FIELD_SUBTYPE_INT,
   FIELD_SUBTYPE_LONG,
-  FIELD_SUBTYPE_SHORT,
-  FIELD_SUBTYPE_BYTE,
   FIELD_SUBTYPE_STRING,
   FIELD_ATTR_VALUES,
 } from "../field/field-constants.js";
@@ -37,8 +35,6 @@ import {
 const NUMERIC_DISCRIMINATOR_SUBTYPES = new Set<string>([
   FIELD_SUBTYPE_INT,
   FIELD_SUBTYPE_LONG,
-  FIELD_SUBTYPE_SHORT,
-  FIELD_SUBTYPE_BYTE,
 ]);
 
 export function validateDiscriminator(root: MetaData): ParseError[] {

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

@@ -1,4 +1,4 @@
-import { FIELD_SUBTYPE_UUID } from "../field/field-constants.js";
+import { FIELD_SUBTYPE_UUID, FIELD_SUBTYPE_CURRENCY, FIELD_SUBTYPE_ENUM } from "../field/field-constants.js";
 
 // Query concern constants — filter operators, sort order values.
 //
@@ -39,13 +39,15 @@ export type FilterOp = (typeof FILTER_OPS)[number];
 
 export const OPS_BY_SUBTYPE: Readonly<Record<string, readonly FilterOp[]>> = {
   string:    [FILTER_OP_EQ, FILTER_OP_NE, FILTER_OP_IN, FILTER_OP_LIKE, FILTER_OP_IS_NULL],
+  // enum: string-backed — same op band as string.
+  [FIELD_SUBTYPE_ENUM]: [FILTER_OP_EQ, FILTER_OP_NE, FILTER_OP_IN, FILTER_OP_LIKE, FILTER_OP_IS_NULL],
   int:       [FILTER_OP_EQ, FILTER_OP_NE, FILTER_OP_GT, FILTER_OP_GTE, FILTER_OP_LT, FILTER_OP_LTE, FILTER_OP_IN, FILTER_OP_IS_NULL],
-  short:     [FILTER_OP_EQ, FILTER_OP_NE, FILTER_OP_GT, FILTER_OP_GTE, FILTER_OP_LT, FILTER_OP_LTE, FILTER_OP_IN, FILTER_OP_IS_NULL],
-  byte:      [FILTER_OP_EQ, FILTER_OP_NE, FILTER_OP_GT, FILTER_OP_GTE, FILTER_OP_LT, FILTER_OP_LTE, FILTER_OP_IN, FILTER_OP_IS_NULL],
   long:      [FILTER_OP_EQ, FILTER_OP_NE, FILTER_OP_GT, FILTER_OP_GTE, FILTER_OP_LT, FILTER_OP_LTE, FILTER_OP_IN, FILTER_OP_IS_NULL],
   double:    [FILTER_OP_EQ, FILTER_OP_NE, FILTER_OP_GT, FILTER_OP_GTE, FILTER_OP_LT, FILTER_OP_LTE, FILTER_OP_IN, FILTER_OP_IS_NULL],
   float:     [FILTER_OP_EQ, FILTER_OP_NE, FILTER_OP_GT, FILTER_OP_GTE, FILTER_OP_LT, FILTER_OP_LTE, FILTER_OP_IN, FILTER_OP_IS_NULL],
   decimal:   [FILTER_OP_EQ, FILTER_OP_NE, FILTER_OP_GT, FILTER_OP_GTE, FILTER_OP_LT, FILTER_OP_LTE, FILTER_OP_IN, FILTER_OP_IS_NULL],
+  // currency: integer minor units — an orderable number. Numeric ops, no `like`.
+  [FIELD_SUBTYPE_CURRENCY]: [FILTER_OP_EQ, FILTER_OP_NE, FILTER_OP_GT, FILTER_OP_GTE, FILTER_OP_LT, FILTER_OP_LTE, FILTER_OP_IN, FILTER_OP_IS_NULL],
   boolean:   [FILTER_OP_EQ, FILTER_OP_IS_NULL],
   date:      [FILTER_OP_EQ, FILTER_OP_NE, FILTER_OP_GT, FILTER_OP_GTE, FILTER_OP_LT, FILTER_OP_LTE, FILTER_OP_IN, FILTER_OP_IS_NULL],
   time:      [FILTER_OP_EQ, FILTER_OP_NE, FILTER_OP_GT, FILTER_OP_GTE, FILTER_OP_LT, FILTER_OP_LTE, FILTER_OP_IN, FILTER_OP_IS_NULL],

package/src/core/relationship/derive-m2m-fields.ts

@@ -0,0 +1,145 @@
+// M:N junction FK derivation — the single source of truth for which junction
+// columns are the SOURCE side and the TARGET side of a many-to-many relationship.
+//
+// A M:N relationship (`@cardinality: "many"`, `@objectRef: <target>`,
+// `@through: <junction>`) does NOT restate its FK columns. They are derived from
+// the junction entity's two `identity.reference` children — one resolving to the
+// source entity, one to the target — exactly as 1:N FK direction is declared
+// (`find-reference.ts` is the analogous SSOT).
+//
+// Three modes (see the FR-018 design):
+//   1. Hetero (source != target): the reference resolving to the source entity
+//      gives sourceField; the one resolving to the target gives targetField.
+//   2. Directed self-join (source == target, @sourceRefField set): both
+//      references resolve to the same entity, so @sourceRefField names the
+//      source-side FK field; the OTHER reference is the target side.
+//   3. Symmetric self-join (source == target, @symmetric: true): undirected; the
+//      two references are taken in declaration order (sourceField = first,
+//      targetField = second). Resolution unions both at read time.
+// Ambiguous (source == target, neither @sourceRefField nor @symmetric) → throw.
+
+import type { MetaObject } from "../object/meta-object.js";
+import type { MetaRoot } from "../../shared/meta-root.js";
+import type { MetaRelationship } from "./meta-relationship.js";
+import type { MetaReferenceIdentity } from "../identity/meta-identity.js";
+import { stripPackage } from "../../naming.js";
+
+/** Thrown when a M:N relationship's junction FK fields cannot be derived. */
+export class M2MDerivationError extends Error {
+  readonly code = "ERR_INVALID_RELATIONSHIP";
+  constructor(message: string) {
+    super(message);
+    this.name = "M2MDerivationError";
+  }
+}
+
+export interface M2MFields {
+  /** The junction FK field holding the source-entity key. */
+  readonly sourceField: string;
+  /** The junction FK field holding the target-entity key. */
+  readonly targetField: string;
+}
+
+/** First @fields entry of a reference (the physical FK column on the junction). */
+function refFkField(ref: MetaReferenceIdentity): string | undefined {
+  return ref.fields[0];
+}
+
+/**
+ * Derive the source/target junction FK fields for a M:N relationship.
+ *
+ * @param rel     the M:N relationship (carries @objectRef + @through + optional
+ *                @sourceRefField / @symmetric)
+ * @param source  the entity declaring `rel`
+ * @param root    the loaded model root (to find the junction entity)
+ * @throws M2MDerivationError when the junction is missing/malformed or the
+ *         self-join is ambiguous.
+ */
+export function deriveM2MFields(
+  rel: MetaRelationship,
+  source: MetaObject,
+  root: MetaRoot,
+): M2MFields {
+  const throughName = rel.through;
+  if (throughName === undefined) {
+    throw new M2MDerivationError(
+      `relationship "${source.name}.${rel.name}" is missing @through (required for M:N derivation)`,
+    );
+  }
+  const junction = root.findObject(throughName);
+  if (junction === undefined) {
+    throw new M2MDerivationError(
+      `relationship "${source.name}.${rel.name}" @through "${throughName}" does not resolve to an entity`,
+    );
+  }
+
+  const targetName = rel.objectRef;
+  if (targetName === undefined) {
+    throw new M2MDerivationError(
+      `relationship "${source.name}.${rel.name}" is missing @objectRef (the M:N target)`,
+    );
+  }
+
+  const refs = junction.referenceIdentities();
+  if (refs.length !== 2) {
+    throw new M2MDerivationError(
+      `junction "${throughName}" for relationship "${source.name}.${rel.name}" must declare exactly two ` +
+        `identity.reference children (found ${refs.length})`,
+    );
+  }
+
+  const isSelfJoin = stripPackage(targetName) === source.name;
+
+  if (!isSelfJoin) {
+    // Hetero: match each reference by the entity it resolves to.
+    const sourceRef = refs.find((r) => r.targetEntity !== undefined && stripPackage(r.targetEntity) === source.name);
+    const targetRef = refs.find((r) => r.targetEntity !== undefined && stripPackage(r.targetEntity) === stripPackage(targetName));
+    const sourceField = sourceRef ? refFkField(sourceRef) : undefined;
+    const targetField = targetRef ? refFkField(targetRef) : undefined;
+    if (sourceField === undefined || targetField === undefined) {
+      throw new M2MDerivationError(
+        `junction "${throughName}" for relationship "${source.name}.${rel.name}" must declare one ` +
+          `identity.reference to "${source.name}" and one to "${stripPackage(targetName)}"`,
+      );
+    }
+    return { sourceField, targetField };
+  }
+
+  // Self-join: both references resolve to the same entity.
+  if (rel.symmetric) {
+    // Undirected: take references in declaration order; union happens at read time.
+    const a = refFkField(refs[0]!);
+    const b = refFkField(refs[1]!);
+    if (a === undefined || b === undefined) {
+      throw new M2MDerivationError(
+        `symmetric junction "${throughName}" for "${source.name}.${rel.name}" has a reference with no @fields`,
+      );
+    }
+    return { sourceField: a, targetField: b };
+  }
+
+  const sourceRefField = rel.sourceRefField;
+  if (sourceRefField === undefined) {
+    throw new M2MDerivationError(
+      `self-join relationship "${source.name}.${rel.name}" through "${throughName}" is ambiguous: ` +
+        `set @sourceRefField (directed) or @symmetric (undirected)`,
+    );
+  }
+
+  // Directed self-join: @sourceRefField names the source-side FK; the other ref is the target.
+  const sourceRef = refs.find((r) => refFkField(r) === sourceRefField);
+  if (sourceRef === undefined) {
+    throw new M2MDerivationError(
+      `@sourceRefField "${sourceRefField}" on "${source.name}.${rel.name}" does not match any ` +
+        `identity.reference FK field on junction "${throughName}"`,
+    );
+  }
+  const targetRef = refs.find((r) => r !== sourceRef);
+  const targetField = targetRef ? refFkField(targetRef) : undefined;
+  if (targetField === undefined) {
+    throw new M2MDerivationError(
+      `junction "${throughName}" for "${source.name}.${rel.name}" has no distinct target-side reference`,
+    );
+  }
+  return { sourceField: sourceRefField, targetField };
+}

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

@@ -6,8 +6,9 @@ import { MetaData } from "../../shared/meta-data.js";
 import {
   RELATIONSHIP_ATTR_CARDINALITY,
   RELATIONSHIP_ATTR_OBJECT_REF,
-  RELATIONSHIP_ATTR_JOIN_ENTITY,
-  RELATIONSHIP_ATTR_JOIN_FIELDS,
+  RELATIONSHIP_ATTR_THROUGH,
+  RELATIONSHIP_ATTR_SOURCE_REF_FIELD,
+  RELATIONSHIP_ATTR_SYMMETRIC,
   RELATIONSHIP_ATTR_ON_DELETE,
   RELATIONSHIP_ATTR_ON_UPDATE,
 } from "./relationship-constants.js";
@@ -24,16 +25,21 @@ export class MetaRelationship extends MetaData {
     return typeof v === "string" ? v : undefined;
   }
 
-  /** Join-table entity name for N:M relationships. */
-  get joinEntity(): string | undefined {
-    const v = this.ownAttr(RELATIONSHIP_ATTR_JOIN_ENTITY);
+  /** Junction (through) entity name for M:N relationships. */
+  get through(): string | undefined {
+    const v = this.ownAttr(RELATIONSHIP_ATTR_THROUGH);
     return typeof v === "string" ? v : undefined;
   }
 
-  /** Join-table column names for N:M relationships. */
-  get joinFields(): string[] {
-    const f = this.ownAttr(RELATIONSHIP_ATTR_JOIN_FIELDS);
-    return Array.isArray(f) ? (f as string[]) : [];
+  /** Source-side FK field on the junction (directed self-join disambiguator). */
+  get sourceRefField(): string | undefined {
+    const v = this.ownAttr(RELATIONSHIP_ATTR_SOURCE_REF_FIELD);
+    return typeof v === "string" ? v : undefined;
+  }
+
+  /** Whether this M:N relationship is an undirected (symmetric) self-join. */
+  get symmetric(): boolean {
+    return this.ownAttr(RELATIONSHIP_ATTR_SYMMETRIC) === true;
   }
 
   /** Referential action on parent delete. Undefined when not explicitly set (default derives from subtype). */

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

@@ -24,8 +24,12 @@ export type RelationshipSubType = (typeof RELATIONSHIP_SUBTYPES)[number];
 
 export const RELATIONSHIP_ATTR_CARDINALITY = "cardinality";
 export const RELATIONSHIP_ATTR_OBJECT_REF = "objectRef";
-export const RELATIONSHIP_ATTR_JOIN_ENTITY = "joinEntity";    // N:M cardinality
-export const RELATIONSHIP_ATTR_JOIN_FIELDS = "joinFields";    // N:M cardinality
+/** M:N junction (through) entity — a third entity declaring two identity.reference children. */
+export const RELATIONSHIP_ATTR_THROUGH = "through";
+/** M:N directed-self-join disambiguator — names the source-side FK field on the junction. */
+export const RELATIONSHIP_ATTR_SOURCE_REF_FIELD = "sourceRefField";
+/** M:N undirected-self-join flag — union-on-read; valid only when objectRef == the declaring entity. */
+export const RELATIONSHIP_ATTR_SYMMETRIC = "symmetric";
 
 // ---------------------------------------------------------------------------
 // Relationship cardinality values (for RELATIONSHIP_ATTR_CARDINALITY)