@metaobjectsdev/metadata 0.8.1 → 0.9.0

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

@@ -3,7 +3,7 @@
 import { SUBTYPE_BASE } from "../../shared/base-types.js";
 
 // ---------------------------------------------------------------------------
-// Field subtypes (16)
+// Field subtypes (17)
 // ---------------------------------------------------------------------------
 
 export const FIELD_SUBTYPE_STRING = "string";
@@ -22,6 +22,10 @@ export const FIELD_SUBTYPE_OBJECT = "object";
 export const FIELD_SUBTYPE_CLASS = "class";
 export const FIELD_SUBTYPE_CURRENCY = "currency";
 export const FIELD_SUBTYPE_ENUM = "enum";
+/** R6 Plan 2a: logical UUID identity scalar. Bare scalar (no required attrs, no
+ *  loader value-validation) — like field.long; native binding is forced to TS
+ *  `string` (TS has no native UUID type). DB column is Postgres-native `uuid`. */
+export const FIELD_SUBTYPE_UUID = "uuid";
 
 export const FIELD_SUBTYPES = [
   SUBTYPE_BASE,
@@ -41,6 +45,7 @@ export const FIELD_SUBTYPES = [
   FIELD_SUBTYPE_CLASS,
   FIELD_SUBTYPE_CURRENCY,
   FIELD_SUBTYPE_ENUM,
+  FIELD_SUBTYPE_UUID,
 ] as const;
 export type FieldSubType = (typeof FIELD_SUBTYPES)[number];
 
@@ -50,6 +55,12 @@ export type FieldSubType = (typeof FIELD_SUBTYPES)[number];
 
 export const FIELD_ATTR_REQUIRED = "required";
 export const FIELD_ATTR_UNIQUE = "unique";
+
+/** FR-013: when true, the field is read-only from the application's perspective.
+ *  Codegen emits no setter; persistence skips the column on INSERT/UPDATE; Zod
+ *  create/update variants omit the field. Default false (writable). See ADR-0013
+ *  layer split — this is logical (no DB-introspection round-trip). */
+export const FIELD_ATTR_READ_ONLY = "readOnly";
 export const FIELD_ATTR_DEFAULT = "default";
 export const FIELD_ATTR_MAX_LENGTH = "maxLength";
 export const FIELD_ATTR_PRECISION = "precision";
@@ -119,7 +130,7 @@ export const FIELD_ATTR_VALUES = "values";
 export const ENUM_MEMBER_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 
 /** FR-010: map of off-vocabulary token → canonical enum member, feeding the
- *  tolerant recover alias-fold. `properties`-shaped; only on field.enum. */
+ *  tolerant extract alias-fold. `properties`-shaped; only on field.enum. */
 export const FIELD_ATTR_ENUM_ALIAS = "enumAlias";
 
 /** FR-010: map of enum member → human-readable description, shown per-member in
@@ -135,3 +146,27 @@ export const FIELD_ATTR_EXAMPLE = "example";
 
 /** FR-010: a short instruction for this field, shown in the generated prompt fragment. */
 export const FIELD_ATTR_INSTRUCTION = "instruction";
+
+// ---------------------------------------------------------------------------
+// FR-011 extract-hardening attrs (enum tolerant extract)
+// ---------------------------------------------------------------------------
+
+/** FR-011: fallback enum member used when an LLM sends a present-but-uncoercible
+ *  value. Must be one of the field's @values (loader-validated). On field.enum only. */
+export const FIELD_ATTR_COERCE_DEFAULT = "coerceDefault";
+
+/** FR-011: ASCII normalization mode for tolerant enum extract. Closed enum
+ *  (none|collapse|strip). On field.enum (per-field) and object.value (default
+ *  for its enum fields). Resolved field → object → global NORMALIZE_DEFAULT. */
+export const FIELD_ATTR_NORMALIZE = "normalize";
+
+/** FR-011: the three ASCII normalization modes (closed set).
+ *  - none     : exact match only.
+ *  - collapse : ASCII case-fold + trim + collapse runs of [\s_-]+ to one _.
+ *  - strip    : ASCII case-fold + strip everything except [A-Z0-9] (most forgiving). */
+export const NORMALIZE_MODES = ["none", "collapse", "strip"] as const;
+export type NormalizeMode = (typeof NORMALIZE_MODES)[number];
+
+/** FR-011: global normalization default when neither the field nor its owning
+ *  object.value declares @normalize. */
+export const NORMALIZE_DEFAULT: NormalizeMode = "strip";

package/src/core/field/field-schema.ts

@@ -15,6 +15,7 @@ import {
   FIELD_ATTR_STORAGE,
   STORAGE_VALUES,
   FIELD_ATTR_REQUIRED,
+  FIELD_ATTR_READ_ONLY,
   FIELD_ATTR_UNIQUE,
   FIELD_ATTR_DEFAULT,
   FIELD_ATTR_MAX_LENGTH,
@@ -32,6 +33,10 @@ import {
   FIELD_ATTR_ENUM_DOC,
   FIELD_ATTR_EXAMPLE,
   FIELD_ATTR_INSTRUCTION,
+  FIELD_ATTR_COERCE_DEFAULT,
+  FIELD_ATTR_NORMALIZE,
+  NORMALIZE_MODES,
+  NORMALIZE_DEFAULT,
 } from "./field-constants.js";
 
 /** Attrs common to every field subtype (codegen-ts column mapper + Project D filter/sort). */
@@ -62,6 +67,17 @@ export const commonFieldAttrs: AttrSchema[] = [
     description:
       "When true, the field is NOT NULL. Equivalent to attaching a validator.required child.",
   },
+  {
+    name: FIELD_ATTR_READ_ONLY,
+    valueType: ATTR_SUBTYPE_BOOLEAN,
+    required: false,
+    description:
+      "FR-013: when true, the field is read-only — codegen emits no setter / " +
+      "writable property, the persistence layer skips the column on INSERT/UPDATE, " +
+      "and Zod/Pydantic/class-validator schemas mark it read-only on input variants. " +
+      "The value is populated by the database (computed column, default expression, " +
+      "trigger), by replication, or by another external owner.",
+  },
   {
     name: FIELD_ATTR_UNIQUE,
     valueType: ATTR_SUBTYPE_BOOLEAN,
@@ -167,13 +183,13 @@ export const enumFieldAttr: AttrSchema = {
 };
 
 /** The @enumAlias attr — only on field.enum. Map of off-vocabulary token → canonical
- *  member, feeding the FR-010 tolerant recover alias-fold (runtime aliases win on conflict). */
+ *  member, feeding the FR-010 tolerant extract alias-fold (runtime aliases win on conflict). */
 export const enumAliasAttr: AttrSchema = {
   name: FIELD_ATTR_ENUM_ALIAS,
   valueType: ATTR_SUBTYPE_PROPERTIES,
   required: false,
   description:
-    "Map of alternate/off-vocabulary tokens to canonical enum members; feeds the FR-010 tolerant recover alias-fold.",
+    "Map of alternate/off-vocabulary tokens to canonical enum members; feeds the FR-010 tolerant extract alias-fold.",
 };
 
 /** The @enumDoc attr — only on field.enum. Map of member → human-readable description,
@@ -185,3 +201,28 @@ export const enumDocAttr: AttrSchema = {
   description:
     "Map of enum member to a human-readable description; shown per-member in the FR-010 'guide'-style prompt fragment.",
 };
+
+/** FR-011: the @coerceDefault attr — only on field.enum. String member symbol used as
+ *  the extract fallback when an LLM sends a present-but-uncoercible value. Loader-validated
+ *  to be one of the field's @values (ERR_BAD_ATTR_VALUE otherwise). */
+export const coerceDefaultAttr: AttrSchema = {
+  name: FIELD_ATTR_COERCE_DEFAULT,
+  valueType: ATTR_SUBTYPE_STRING,
+  required: false,
+  description:
+    "Fallback enum member used by tolerant extract when a present value cannot be coerced; must be one of the field's @values.",
+};
+
+/** FR-011: the @normalize attr — on field.enum (per-field) and object.value (object default).
+ *  Closed enum (none|collapse|strip); controls the ASCII normalization applied during tolerant
+ *  enum extract. Resolved field → owning object.value → global default (strip). */
+export const normalizeAttr: AttrSchema = {
+  name: FIELD_ATTR_NORMALIZE,
+  valueType: ATTR_SUBTYPE_STRING,
+  required: false,
+  default: NORMALIZE_DEFAULT,
+  allowedValues: [...NORMALIZE_MODES],
+  description:
+    "ASCII normalization mode for tolerant enum extract (none|collapse|strip, default strip). " +
+    "On field.enum it is per-field; on object.value it is the default for the object's enum fields.",
+};

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

@@ -34,6 +34,7 @@ import {
   FIELD_SUBTYPE_TIMESTAMP,
   FIELD_SUBTYPE_OBJECT,
   FIELD_SUBTYPE_ENUM,
+  FIELD_SUBTYPE_UUID,
   FIELD_ATTR_REQUIRED,
   FIELD_ATTR_UNIQUE,
   FIELD_ATTR_DEFAULT,
@@ -46,6 +47,7 @@ import { FIELD_ATTR_COLUMN } from "../../persistence/db/db-constants.js";
 import { VALIDATOR_SUBTYPE_REQUIRED } from "../validator/validator-constants.js";
 import type { MetaValidator } from "../validator/meta-validator.js";
 import type { MetaView } from "../../presentation/view/meta-view.js";
+import { ValueObject } from "../object/value-object.js";
 
 /** Field subtype → DataType. Co-located with the class — a provider adding a
  *  field subtype supplies its own dataType the same way. */
@@ -53,6 +55,8 @@ const FIELD_DATA_TYPE: Readonly<Record<string, DataType>> = {
   [SUBTYPE_BASE]: DATA_TYPE_STRING,
   [FIELD_SUBTYPE_STRING]: DATA_TYPE_STRING,
   [FIELD_SUBTYPE_CLASS]: DATA_TYPE_STRING,
+  // field.uuid binds to TS `string` (no native UUID type) — DATA_TYPE_STRING.
+  [FIELD_SUBTYPE_UUID]: DATA_TYPE_STRING,
   [FIELD_SUBTYPE_INT]: DATA_TYPE_INT,
   [FIELD_SUBTYPE_SHORT]: DATA_TYPE_INT,
   [FIELD_SUBTYPE_BYTE]: DATA_TYPE_INT,
@@ -179,4 +183,39 @@ export class MetaField extends MetaData implements DataTypeAware {
   resolveSuper(): MetaField | undefined {
     return this.superData as MetaField | undefined;
   }
+
+  // ---------------------------------------------------------------------------
+  // Runtime value access (Java parity: MetaField.getObject / setObject by name).
+  //
+  // Minimal backing-object SPI: dispatch on the backing object's shape — a
+  // ValueObject uses its map, any other object uses typed property access.
+  // Nested OBJECT fields and arrays are driven by the CONSUMER (resolve the
+  // child MetaObject via objectRef, newInstance, recurse); these methods read
+  // and write whatever value (scalar, nested object, or array) the caller
+  // supplies. No coercion here — coerce() is available separately.
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Read this field's value from a backing object. `name` defaults to the
+   * field's own `name`; pass an override only to read a differently-keyed slot.
+   */
+  getValue(obj: object, name: string = this.name): unknown {
+    if (obj instanceof ValueObject) {
+      return obj.get(name);
+    }
+    // Typed property access — the unavoidable dynamic-property bridge.
+    return (obj as Record<string, unknown>)[name];
+  }
+
+  /**
+   * Write `value` into a backing object under `name` (defaults to this field's
+   * own `name`). ValueObject → map set; any other object → typed property set.
+   */
+  setValue(obj: object, value: unknown, name: string = this.name): void {
+    if (obj instanceof ValueObject) {
+      obj.set(name, value);
+      return;
+    }
+    (obj as Record<string, unknown>)[name] = value;
+  }
 }

package/src/core/field/validate-field-readonly.ts

@@ -0,0 +1,142 @@
+// Validation pass: field-level @readOnly cross-attribute rules (FR-013).
+//
+// Codes:
+//   ERR_READONLY_ASSIGNED_PRIMARY — @readOnly: true on a field that is the
+//     target of an identity.primary with @generation: "assigned". The application
+//     has no path to populate the identity value (no setter; not generated; not
+//     defaulted).
+//   ERR_READONLY_DOWNGRADE — a concrete subtype declares @readOnly: false on a
+//     field whose extends-chain parent declares @readOnly: true. Read-only-ness
+//     can only be upgraded, never downgraded.
+//   WARN_READONLY_VALUE_OBJECT — @readOnly: true on a field child of object.value.
+//     The persistence implication does not apply; the attr is retained for
+//     language-specific record/struct treatment.
+
+import type { MetaData } from "../../shared/meta-data.js";
+import { ParseError } from "../../errors.js";
+import type { LoaderWarning } from "../../source.js";
+import {
+  TYPE_OBJECT,
+  TYPE_FIELD,
+  TYPE_IDENTITY,
+} from "../../shared/base-types.js";
+import { OBJECT_SUBTYPE_VALUE } from "../object/object-constants.js";
+import {
+  IDENTITY_SUBTYPE_PRIMARY,
+  IDENTITY_ATTR_GENERATION,
+  IDENTITY_ATTR_FIELDS,
+  GENERATION_ASSIGNED,
+} from "../identity/identity-constants.js";
+import { FIELD_ATTR_READ_ONLY } from "./field-constants.js";
+
+export interface FieldReadOnlyValidationResult {
+  errors: ParseError[];
+  warnings: LoaderWarning[];
+}
+
+export function validateFieldReadOnly(root: MetaData): FieldReadOnlyValidationResult {
+  const errors: ParseError[] = [];
+  const warnings: LoaderWarning[] = [];
+
+  for (const obj of root.ownChildren().filter((c) => c.type === TYPE_OBJECT)) {
+    const isValueObject = obj.subType === OBJECT_SUBTYPE_VALUE;
+
+    // 1) WARN_READONLY_VALUE_OBJECT — any @readOnly field child of an object.value.
+    if (isValueObject) {
+      for (const child of obj.ownChildren()) {
+        if (child.type === TYPE_FIELD && readOnlyFlag(child) === true) {
+          warnings.push({
+            code: "WARN_READONLY_VALUE_OBJECT",
+            message:
+              `field "${child.name}" on object.value "${obj.name}" declares ` +
+              `@readOnly: true; value-objects have no persistence semantics so ` +
+              `the read-only contract is advisory (codegen may use it for record/` +
+              `struct treatment).`,
+            source: child.source,
+          });
+        }
+      }
+    }
+
+    // 2) ERR_READONLY_DOWNGRADE — read-only-ness can only be upgraded across
+    //    extends. Compare own field vs. inherited field's effective @readOnly.
+    for (const ownField of obj.ownChildren().filter((c) => c.type === TYPE_FIELD)) {
+      const ownVal = readOnlyFlag(ownField);
+      if (ownVal !== false) continue; // only the explicit downgrade case matters
+      const inherited = inheritedField(obj, ownField.name);
+      if (inherited !== undefined && readOnlyFlag(inherited) === true) {
+        errors.push(
+          new ParseError(
+            `field "${ownField.name}" on "${obj.name}" sets @readOnly: false, but the ` +
+              `extends-chain parent declares @readOnly: true. Read-only-ness can only be ` +
+              `upgraded, not downgraded (FR-013).`,
+            { code: "ERR_READONLY_DOWNGRADE", source: ownField.source },
+          ),
+        );
+      }
+    }
+
+    // 3) ERR_READONLY_ASSIGNED_PRIMARY — @readOnly: true on a field used in an
+    //    identity.primary whose @generation is "assigned" (effective tree).
+    if (!isValueObject) {
+      const primaryAssignedFields = primaryAssignedFieldNames(obj);
+      if (primaryAssignedFields.size > 0) {
+        for (const field of obj.children().filter((c) => c.type === TYPE_FIELD)) {
+          if (!primaryAssignedFields.has(field.name)) continue;
+          if (readOnlyFlag(field) !== true) continue;
+          errors.push(
+            new ParseError(
+              `field "${field.name}" on "${obj.name}" is @readOnly: true AND the target ` +
+                `of identity.primary with @generation: "assigned"; the application has no ` +
+                `path to populate the identity value (FR-013).`,
+              { code: "ERR_READONLY_ASSIGNED_PRIMARY", source: field.source },
+            ),
+          );
+        }
+      }
+    }
+  }
+
+  return { errors, warnings };
+}
+
+/** Read the explicit @readOnly value from a field's own attrs. Returns
+ *  true / false when explicitly set, undefined when absent. */
+function readOnlyFlag(field: MetaData): boolean | undefined {
+  const v = field.ownAttr(FIELD_ATTR_READ_ONLY);
+  if (typeof v === "boolean") return v;
+  return undefined;
+}
+
+/** Walk the extends chain looking for a field with the same name; return its
+ *  declaring node (own attrs preserved) if found. */
+function inheritedField(obj: MetaData, name: string): MetaData | undefined {
+  let cursor = obj.superResolved;
+  while (cursor !== undefined) {
+    const f = cursor.ownChildren().find((c) => c.type === TYPE_FIELD && c.name === name);
+    if (f !== undefined) return f;
+    cursor = cursor.superResolved;
+  }
+  return undefined;
+}
+
+/** Names of fields participating in any identity.primary with @generation:
+ *  "assigned" on `obj` or its extends chain. */
+function primaryAssignedFieldNames(obj: MetaData): Set<string> {
+  const out = new Set<string>();
+  for (const id of obj.children()) {
+    if (id.type !== TYPE_IDENTITY) continue;
+    if (id.subType !== IDENTITY_SUBTYPE_PRIMARY) continue;
+    const gen = id.ownAttr(IDENTITY_ATTR_GENERATION);
+    if (gen !== GENERATION_ASSIGNED) continue;
+    const fields = id.ownAttr(IDENTITY_ATTR_FIELDS);
+    if (Array.isArray(fields)) {
+      for (const fName of fields) {
+        if (typeof fName === "string") out.add(fName);
+      }
+    } else if (typeof fields === "string") {
+      out.add(fields);
+    }
+  }
+  return out;
+}

package/src/core/object/meta-object-aware.ts

@@ -0,0 +1,27 @@
+// MetaObjectAware — the runtime back-reference contract.
+//
+// Idiomatic TS port of Java's MetaObjectAware: a backing object that knows the
+// MetaObject describing it. The default backing type (ValueObject) implements
+// this; generated/registered native types may implement it too so they carry a
+// back-reference after newInstance(). Reflection-free — no reflect-metadata,
+// no runtime type resolution.
+
+import type { MetaObject } from "./meta-object.js";
+
+/** A backing object that carries a reference to the MetaObject describing it. */
+export interface MetaObjectAware {
+  /** The MetaObject describing this instance, or undefined if not yet attached. */
+  getMetaData(): MetaObject | undefined;
+  /** Attach the MetaObject describing this instance (back-reference). */
+  setMetaData(mo: MetaObject): void;
+}
+
+/** Structural type guard — true when `o` satisfies the MetaObjectAware contract. */
+export function isMetaObjectAware(o: unknown): o is MetaObjectAware {
+  return (
+    typeof o === "object" &&
+    o !== null &&
+    typeof (o as MetaObjectAware).getMetaData === "function" &&
+    typeof (o as MetaObjectAware).setMetaData === "function"
+  );
+}

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

@@ -19,6 +19,12 @@ import {
   OBJECT_SUBTYPE_ENTITY,
   OBJECT_SUBTYPE_VALUE,
 } from "./object-constants.js";
+import { ValueObject } from "./value-object.js";
+import { isMetaObjectAware } from "./meta-object-aware.js";
+import {
+  ObjectClassRegistry,
+  defaultObjectClassRegistry,
+} from "./object-class-registry.js";
 import {
   IDENTITY_SUBTYPE_PRIMARY,
   IDENTITY_SUBTYPE_SECONDARY,
@@ -33,12 +39,17 @@ import type { MetaValidator } from "../validator/meta-validator.js";
 export class MetaObject extends MetaData {
   get dbTable(): string | undefined {
     return this.cached("dbTable", () => {
-      // The primary writable source carries the physical table name (@table).
+      // The primary writable source carries the physical table name. FR-016:
+      // physicalName respects per-kind aliases + the four-step resolution rule.
+      // We still scope to writable + primary because dbTable is the WRITE target
+      // (CQRS read-side via dbView/dbProc is a different accessor).
       const source = this.children().find(
         (c): c is MetaSource =>
           c instanceof MetaSource && c.isWritable() && c.role === SOURCE_ROLE_PRIMARY,
       );
-      return source?.tableName;
+      if (source === undefined) return undefined;
+      const name = source.physicalName;
+      return name !== "" ? name : undefined;
     });
   }
 
@@ -148,4 +159,38 @@ export class MetaObject extends MetaData {
       this.fields().find((f) => f.name === name),
     );
   }
+
+  /** Java parity alias for findField() — locate an effective field by name. */
+  getMetaField(name: string): MetaField | undefined {
+    return this.findField(name);
+  }
+
+  /**
+   * Instantiate a backing object for this MetaObject (Java parity:
+   * MetaObject.newInstance()). Resolution order:
+   *
+   *   1. If `registry.resolve(this.fqn())` yields a factory, call it; if the
+   *      result is MetaObjectAware, attach this MetaObject as its back-reference.
+   *   2. Otherwise create a map-backed ValueObject (the unbound default for
+   *      `object.value`), which sets its own back-reference via the constructor.
+   *
+   * The registry key is the object's fully-qualified name as produced by
+   * `resolutionKey()` (`<package>::<name>`, folding the file-default package).
+   * This is the SAME FQN form used by a nested field's `@objectRef`, so a
+   * factory registered for an object's FQN is found whether instantiation is
+   * driven top-down or via an object-ref. (An object's bare `fqn()` is reserved
+   * for the FR5d cross-port referrer-envelope contract and is NOT the binding
+   * key.) Reflection-free: only registered factories are consulted.
+   */
+  newInstance(registry: ObjectClassRegistry = defaultObjectClassRegistry): object {
+    const factory = registry.resolve(this.resolutionKey());
+    if (factory !== undefined) {
+      const instance = factory(this);
+      if (isMetaObjectAware(instance)) {
+        instance.setMetaData(this);
+      }
+      return instance;
+    }
+    return new ValueObject(this);
+  }
 }

package/src/core/object/object-class-registry.ts

@@ -0,0 +1,48 @@
+// ObjectClassRegistry — FQN → factory binding for runtime instantiation.
+//
+// Idiomatic TS port of Java's ObjectClassRegistry: maps an object's FQN
+// (`package::name`) to a factory that produces a native backing instance.
+// Generated code self-registers at import time (`registry.register(fqn, ...)`)
+// — NO reflection (no Class.forName / Type.GetType / importlib equivalent),
+// AOT/tree-shake-safe per ADR-0001.
+//
+// DISTINCT from the metadata TypeRegistry, which maps metamodel type/subType
+// names to MetaData node classes. This registry maps a DATA object's FQN to a
+// runtime BACKING instance factory.
+
+import type { MetaObject } from "./meta-object.js";
+
+/** Produces a native backing instance for the given MetaObject. */
+export type ObjectFactory = (mo: MetaObject) => object;
+
+export class ObjectClassRegistry {
+  private readonly _factories = new Map<string, ObjectFactory>();
+
+  /** Bind an FQN (`package::name`) to a backing-instance factory. */
+  register(fqn: string, factory: ObjectFactory): void {
+    this._factories.set(fqn, factory);
+  }
+
+  /** Resolve the factory bound to an FQN, or undefined if none is registered. */
+  resolve(fqn: string): ObjectFactory | undefined {
+    return this._factories.get(fqn);
+  }
+
+  /** True if a factory is bound to the FQN. */
+  has(fqn: string): boolean {
+    return this._factories.has(fqn);
+  }
+
+  /** Remove a binding (test/scoping convenience). */
+  unregister(fqn: string): boolean {
+    return this._factories.delete(fqn);
+  }
+}
+
+/**
+ * The module-level default registry. Generated code self-registers here at
+ * import time; `MetaObject.newInstance()` consults it when no explicit registry
+ * is passed. Tests should construct their own `new ObjectClassRegistry()` to
+ * avoid leaking bindings across cases (scenario 6).
+ */
+export const defaultObjectClassRegistry = new ObjectClassRegistry();

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

@@ -19,3 +19,20 @@ export const OBJECT_SUBTYPES = [
   OBJECT_SUBTYPE_VALUE,
 ] as const;
 export type ObjectSubType = (typeof OBJECT_SUBTYPES)[number];
+
+// ---------------------------------------------------------------------------
+// FR-014 — TPH discriminator (Table-per-Hierarchy single-table inheritance)
+// ---------------------------------------------------------------------------
+// Both attrs live on object.entity. Logical layer (ADR-0013): metadata
+// describes the polymorphism; codegen / ORM emit the per-stack idiom
+// (EF HasDiscriminator / JPA @DiscriminatorColumn / SQLAlchemy polymorphic_on
+// / Kotlin sealed class / TS discriminated union).
+
+/** FR-014: names the field on this entity (resolvable via extends) that holds
+ *  the subtype-discriminator value. Subtypes declare @discriminatorValue to
+ *  bind their rows to a value of that field. */
+export const OBJECT_ATTR_DISCRIMINATOR = "discriminator";
+
+/** FR-014: on a subtype of an entity with @discriminator: the value that
+ *  identifies rows of this subtype in the shared discriminator field. */
+export const OBJECT_ATTR_DISCRIMINATOR_VALUE = "discriminatorValue";

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

@@ -2,6 +2,34 @@
 // Consumed by registerCoreTypes().
 
 import type { AttrSchema } from "../../registry.js";
+import { ATTR_SUBTYPE_STRING } from "../attr/attr-constants.js";
+import {
+  OBJECT_ATTR_DISCRIMINATOR,
+  OBJECT_ATTR_DISCRIMINATOR_VALUE,
+} from "./object-constants.js";
 
 /** Attrs common to every object subtype. */
-export const objectAttrs: AttrSchema[] = [];
+export const objectAttrs: AttrSchema[] = [
+  {
+    name: OBJECT_ATTR_DISCRIMINATOR,
+    valueType: ATTR_SUBTYPE_STRING,
+    required: false,
+    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).",
+  },
+  {
+    name: OBJECT_ATTR_DISCRIMINATOR_VALUE,
+    valueType: ATTR_SUBTYPE_STRING,
+    required: false,
+    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.",
+  },
+];