@metaobjectsdev/metadata 0.8.1 → 0.9.0

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

@@ -0,0 +1,195 @@
+// Validation pass: TPH discriminator cross-attribute rules (FR-014).
+//
+// Codes (all errors):
+//   ERR_DISCRIMINATOR_FIELD_NOT_FOUND      — @discriminator names a field that
+//                                            does not exist on the entity (own
+//                                            or via extends chain).
+//   ERR_DISCRIMINATOR_VALUE_DUPLICATE      — two subtypes of the same
+//                                            @discriminator-bearing root claim
+//                                            the same @discriminatorValue.
+//   ERR_DISCRIMINATOR_VALUE_MISSING        — a concrete (non-abstract) entity
+//                                            extends a chain whose root carries
+//                                            @discriminator but the subtype lacks
+//                                            @discriminatorValue.
+//   ERR_DISCRIMINATOR_VALUE_TYPE_MISMATCH  — @discriminatorValue cannot be
+//                                            coerced to the discriminator field's
+//                                            subtype (enum: not in @values;
+//                                            int: not numeric; string: always OK).
+
+import type { MetaData } from "../../shared/meta-data.js";
+import { ParseError } from "../../errors.js";
+import { TYPE_OBJECT, TYPE_FIELD } from "../../shared/base-types.js";
+import {
+  OBJECT_ATTR_DISCRIMINATOR,
+  OBJECT_ATTR_DISCRIMINATOR_VALUE,
+  OBJECT_SUBTYPE_ENTITY,
+} from "./object-constants.js";
+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";
+
+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[] {
+  const errors: ParseError[] = [];
+
+  const entities = root
+    .ownChildren()
+    .filter((c) => c.type === TYPE_OBJECT && c.subType === OBJECT_SUBTYPE_ENTITY);
+
+  // Pass 1: @discriminator on bases — name resolution (own + inherited fields).
+  for (const obj of entities) {
+    const disc = obj.ownAttr(OBJECT_ATTR_DISCRIMINATOR);
+    if (typeof disc !== "string" || disc === "") continue;
+
+    const field = findFieldOnEntity(obj, disc);
+    if (field === undefined) {
+      errors.push(
+        new ParseError(
+          `object.entity "${obj.name}" @discriminator: "${disc}" does not name a field on this entity ` +
+            `(checked own children and the extends chain)`,
+          { code: "ERR_DISCRIMINATOR_FIELD_NOT_FOUND", source: obj.source },
+        ),
+      );
+    }
+  }
+
+  // Pass 2: @discriminatorValue validation — for every entity that declares it,
+  // walk up to find the @discriminator-bearing root, then check field membership
+  // and uniqueness within that root's subtype set.
+  type SubtypeBinding = {
+    subtype: MetaData;
+    value: string;
+    discField: MetaData;
+  };
+  const bindingsByRoot = new Map<MetaData, SubtypeBinding[]>();
+
+  for (const obj of entities) {
+    const value = obj.ownAttr(OBJECT_ATTR_DISCRIMINATOR_VALUE);
+    if (typeof value !== "string" || value === "") continue;
+
+    const { root: discRoot, fieldName } = findDiscriminatorRoot(obj);
+    if (discRoot === undefined || fieldName === undefined) continue;
+
+    const field = findFieldOnEntity(discRoot, fieldName);
+    if (field === undefined) continue; // root's own ERR_DISCRIMINATOR_FIELD_NOT_FOUND already fires
+
+    // Type-match check.
+    if (field.subType === FIELD_SUBTYPE_ENUM) {
+      const enumValues = field.ownAttr(FIELD_ATTR_VALUES);
+      const list = Array.isArray(enumValues) ? enumValues.map(String) : [];
+      if (!list.includes(value)) {
+        errors.push(
+          new ParseError(
+            `object.entity "${obj.name}" @discriminatorValue: "${value}" is not a member of the ` +
+              `discriminator enum field "${fieldName}" @values [${list.join(", ")}]`,
+            { code: "ERR_DISCRIMINATOR_VALUE_TYPE_MISMATCH", source: obj.source },
+          ),
+        );
+      }
+    } else if (NUMERIC_DISCRIMINATOR_SUBTYPES.has(field.subType)) {
+      if (!/^-?\d+$/.test(value)) {
+        errors.push(
+          new ParseError(
+            `object.entity "${obj.name}" @discriminatorValue: "${value}" does not coerce to ` +
+              `numeric discriminator field "${fieldName}" (field.${field.subType})`,
+            { code: "ERR_DISCRIMINATOR_VALUE_TYPE_MISMATCH", source: obj.source },
+          ),
+        );
+      }
+    } else if (field.subType !== FIELD_SUBTYPE_STRING) {
+      // Discriminator fields outside {enum, integer-family, string} are
+      // unusual; accept silently (a future refinement may add a warning).
+    }
+
+    let list = bindingsByRoot.get(discRoot);
+    if (list === undefined) {
+      list = [];
+      bindingsByRoot.set(discRoot, list);
+    }
+    list.push({ subtype: obj, value, discField: field });
+  }
+
+  // Pass 3: ERR_DISCRIMINATOR_VALUE_DUPLICATE within each root's subtypes.
+  for (const [, bindings] of bindingsByRoot) {
+    const seen = new Map<string, MetaData>();
+    for (const b of bindings) {
+      const prev = seen.get(b.value);
+      if (prev !== undefined) {
+        errors.push(
+          new ParseError(
+            `object.entity "${b.subtype.name}" @discriminatorValue: "${b.value}" ` +
+              `duplicates the value already claimed by "${prev.name}"`,
+            { code: "ERR_DISCRIMINATOR_VALUE_DUPLICATE", source: b.subtype.source },
+          ),
+        );
+      } else {
+        seen.set(b.value, b.subtype);
+      }
+    }
+  }
+
+  // Pass 4: ERR_DISCRIMINATOR_VALUE_MISSING — every concrete (non-abstract)
+  // entity that extends a @discriminator-bearing root must declare a value.
+  for (const obj of entities) {
+    if (obj.isAbstract === true) continue;
+    if (typeof obj.ownAttr(OBJECT_ATTR_DISCRIMINATOR_VALUE) === "string") continue;
+    if (typeof obj.ownAttr(OBJECT_ATTR_DISCRIMINATOR) === "string") continue; // a root, not a subtype
+    const { root: discRoot } = findDiscriminatorRoot(obj);
+    if (discRoot === undefined) continue;
+    if (discRoot === obj) continue; // safety: same node, shouldn't happen
+    errors.push(
+      new ParseError(
+        `object.entity "${obj.name}" extends the @discriminator-bearing root "${discRoot.name}" ` +
+          `but is missing @discriminatorValue (required on every concrete subtype)`,
+        { code: "ERR_DISCRIMINATOR_VALUE_MISSING", source: obj.source },
+      ),
+    );
+  }
+
+  return errors;
+}
+
+/** Find a field with the given name on `entity` — own first, then via the
+ *  resolved extends chain. Returns the declaring field node (own attrs intact). */
+function findFieldOnEntity(entity: MetaData, name: string): MetaData | undefined {
+  for (const child of entity.ownChildren()) {
+    if (child.type === TYPE_FIELD && child.name === name) return child;
+  }
+  let cursor = entity.superResolved;
+  while (cursor !== undefined) {
+    for (const child of cursor.ownChildren()) {
+      if (child.type === TYPE_FIELD && child.name === name) return child;
+    }
+    cursor = cursor.superResolved;
+  }
+  return undefined;
+}
+
+/** Walk the extends chain to find the first ancestor (or self) carrying
+ *  @discriminator. Returns {root, fieldName} when found; both undefined
+ *  otherwise. */
+function findDiscriminatorRoot(
+  entity: MetaData,
+): { root: MetaData | undefined; fieldName: string | undefined } {
+  let cursor: MetaData | undefined = entity;
+  while (cursor !== undefined) {
+    const v = cursor.ownAttr(OBJECT_ATTR_DISCRIMINATOR);
+    if (typeof v === "string" && v !== "") {
+      return { root: cursor, fieldName: v };
+    }
+    cursor = cursor.superResolved;
+  }
+  return { root: undefined, fieldName: undefined };
+}

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

@@ -0,0 +1,65 @@
+// ValueObject — the map-backed default backing object for `object.value`.
+//
+// Idiomatic TS port of Java's ValueObject: a string-keyed map that holds its
+// MetaObject back-reference and supports both declared fields and arbitrary
+// overflow keys. THE unbound default produced by MetaObject.newInstance() when
+// no native type is registered for the object's FQN. Reflection-free.
+
+import type { MetaObject } from "./meta-object.js";
+import type { MetaObjectAware } from "./meta-object-aware.js";
+
+export class ValueObject implements MetaObjectAware {
+  private readonly _values = new Map<string, unknown>();
+  private _metaData: MetaObject | undefined = undefined;
+
+  /** Construct over an optional MetaObject back-reference (set at newInstance). */
+  constructor(mo?: MetaObject) {
+    this._metaData = mo;
+  }
+
+  // ---------------------------------------------------------------------------
+  // MetaObjectAware
+  // ---------------------------------------------------------------------------
+
+  getMetaData(): MetaObject | undefined {
+    return this._metaData;
+  }
+
+  setMetaData(mo: MetaObject): void {
+    this._metaData = mo;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Map-backed value access — declared fields AND arbitrary overflow keys.
+  // ---------------------------------------------------------------------------
+
+  /** Read a value by key. Returns undefined for an unset key. */
+  get(name: string): unknown {
+    return this._values.get(name);
+  }
+
+  /** Write a value by key. Any string key is accepted (overflow-friendly). */
+  set(name: string, value: unknown): void {
+    this._values.set(name, value);
+  }
+
+  /** True if the key has been set (including to undefined). */
+  has(name: string): boolean {
+    return this._values.has(name);
+  }
+
+  /** Remove a key. */
+  delete(name: string): boolean {
+    return this._values.delete(name);
+  }
+
+  /** Insertion-ordered keys currently held. */
+  keys(): string[] {
+    return [...this._values.keys()];
+  }
+
+  /** A plain-object snapshot of the backing map (insertion-ordered). */
+  toObject(): Record<string, unknown> {
+    return Object.fromEntries(this._values);
+  }
+}

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

@@ -1,3 +1,5 @@
+import { FIELD_SUBTYPE_UUID } from "../field/field-constants.js";
+
 // Query concern constants — filter operators, sort order values.
 //
 // NOTE: `query` is NOT a metamodel node type — it has no subtype, schema, or
@@ -48,6 +50,9 @@ export const OPS_BY_SUBTYPE: Readonly<Record<string, readonly FilterOp[]>> = {
   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],
   timestamp: [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],
+  // uuid: identity-comparison ops only — no `like` (not free-text) and no
+  // ordering (`gt`/`lt` are meaningless on a UUID).
+  [FIELD_SUBTYPE_UUID]: [FILTER_OP_EQ, FILTER_OP_NE, FILTER_OP_IN, FILTER_OP_IS_NULL],
 } as const;
 
 export function opsForSubType(subType: string): readonly FilterOp[] {

package/src/core-types.ts

@@ -35,7 +35,7 @@ import { MetaRelationship } from "./core/relationship/meta-relationship.js";
 import { MetaLayout } from "./presentation/layout/meta-layout.js";
 import { MetaSource } from "./persistence/source/meta-source.js";
 import { MetaOrigin, MetaPassthroughOrigin, MetaAggregateOrigin, MetaCollectionOrigin } from "./persistence/origin/meta-origin.js";
-import { commonFieldAttrs, currencyFieldAttr, enumFieldAttr, enumAliasAttr, enumDocAttr } from "./core/field/field-schema.js";
+import { commonFieldAttrs, currencyFieldAttr, enumFieldAttr, enumAliasAttr, enumDocAttr, coerceDefaultAttr, normalizeAttr } from "./core/field/field-schema.js";
 import { objectAttrs } from "./core/object/object-schema.js";
 import { relationshipAttrs } from "./core/relationship/relationship-schema.js";
 import { identityFieldsAttr, IDENTITY_ATTRS_MAP } from "./core/identity/identity-schema.js";
@@ -62,7 +62,7 @@ import {
   SUBTYPE_ROOT,
 } from "./shared/base-types.js";
 import { CHILD_RULE_WILDCARD } from "./shared/structural.js";
-import { OBJECT_SUBTYPES, OBJECT_SUBTYPE_ENTITY } from "./core/object/object-constants.js";
+import { OBJECT_SUBTYPES, OBJECT_SUBTYPE_ENTITY, OBJECT_SUBTYPE_VALUE } from "./core/object/object-constants.js";
 import { FIELD_SUBTYPES, FIELD_SUBTYPE_CURRENCY, FIELD_SUBTYPE_ENUM } from "./core/field/field-constants.js";
 import { ATTR_SUBTYPES } from "./core/attr/attr-constants.js";
 import {
@@ -183,8 +183,14 @@ function registerCoreTypeDefs(registry: TypeRegistry): void {
     wildcard(TYPE_ATTR),
   ];
   for (const subType of OBJECT_SUBTYPES) {
+    // FR-011: object.value additionally carries @normalize — the object-level
+    // default normalization mode for its enum fields' tolerant extract.
+    const subTypeObjectAttrs =
+      subType === OBJECT_SUBTYPE_VALUE
+        ? [...objectAttrs, { ...normalizeAttr }]
+        : [...objectAttrs];
     registry.register(
-      def(TYPE_OBJECT, subType, `Object/entity (${subType})`, objectRules, MetaObject, [...objectAttrs]),
+      def(TYPE_OBJECT, subType, `Object/entity (${subType})`, objectRules, MetaObject, subTypeObjectAttrs),
     );
   }
 
@@ -202,7 +208,14 @@ function registerCoreTypeDefs(registry: TypeRegistry): void {
       subType === FIELD_SUBTYPE_CURRENCY
         ? [...commonFieldAttrs, { ...currencyFieldAttr }]
         : subType === FIELD_SUBTYPE_ENUM
-          ? [...commonFieldAttrs, { ...enumFieldAttr }, { ...enumAliasAttr }, { ...enumDocAttr }]
+          ? [
+              ...commonFieldAttrs,
+              { ...enumFieldAttr },
+              { ...enumAliasAttr },
+              { ...enumDocAttr },
+              { ...coerceDefaultAttr },
+              { ...normalizeAttr },
+            ]
           : [...commonFieldAttrs];
     registry.register(
       def(TYPE_FIELD, subType, `Field of type ${subType}`, fieldRules, MetaField, fieldAttrs,

package/src/errors.ts

@@ -49,6 +49,22 @@ export const ERROR_CODES = [
   "ERR_RESERVED_ATTR",
   "ERR_SOURCE_NO_PRIMARY",
   "ERR_SOURCE_MULTIPLE_PRIMARY",
+  // FR-016 / ADR-0018 — per-kind physical-name alias validation on source.rdb.
+  "ERR_PHYSICAL_NAME_KIND_MISMATCH",
+  "ERR_PHYSICAL_NAME_MULTIPLE",
+  // FR-013 — field-level @readOnly cross-attribute validation.
+  "ERR_READONLY_ASSIGNED_PRIMARY",
+  "ERR_READONLY_DOWNGRADE",
+  // FR-015 — source.rdb @parameterRef typed-input validation.
+  "ERR_PARAMETER_REF_UNRESOLVED",
+  "ERR_PARAMETER_REF_NOT_VALUE_OBJECT",
+  "ERR_PARAMETER_REF_ON_NON_CALLABLE_KIND",
+  "ERR_PARAMETER_REF_PASSTHROUGH_TYPE_MISMATCH",
+  // FR-014 — TPH discriminator cross-attribute validation.
+  "ERR_DISCRIMINATOR_FIELD_NOT_FOUND",
+  "ERR_DISCRIMINATOR_VALUE_DUPLICATE",
+  "ERR_DISCRIMINATOR_VALUE_MISSING",
+  "ERR_DISCRIMINATOR_VALUE_TYPE_MISMATCH",
   // ADR-0006 D2 — YAML type-coercion guard. Emitted by every port's YAML
   // loader when a coerced scalar mismatches the schema-declared type.
   "ERR_YAML_COERCION",
@@ -67,6 +83,13 @@ export const WARNING_CODES = [
   // strings; wrapped at the loader boundary into the envelope shape with
   // this code. Retired as those sites are migrated to envelopes.
   "WARN_LEGACY",
+  // FR-016 / ADR-0018 — pre-1.0 legacy @table spelling on a non-table @kind.
+  // Loader accepts; canonical-serializer rewrites to the kind-matching alias.
+  "WARN_LEGACY_PHYSICAL_NAME_ALIAS",
+  // FR-013 — @readOnly on a field child of object.value. The persistence
+  // implication does not apply to value-objects; the attr is retained for
+  // language-specific record/struct treatment (e.g. Kotlin `val` vs `var`).
+  "WARN_READONLY_VALUE_OBJECT",
 ] as const;
 export type WarningCode = (typeof WARNING_CODES)[number];
 

package/src/index.ts

@@ -50,6 +50,16 @@ export { MetaRoot } from "./shared/meta-root.js";
 export { MetaObject } from "./core/object/meta-object.js";
 export { MetaField } from "./core/field/meta-field.js";
 export { MetaAttr } from "./core/attr/meta-attr.js";
+
+// Runtime object model — backing objects + FQN→factory binding (Phase A).
+export { ValueObject } from "./core/object/value-object.js";
+export { isMetaObjectAware } from "./core/object/meta-object-aware.js";
+export type { MetaObjectAware } from "./core/object/meta-object-aware.js";
+export {
+  ObjectClassRegistry,
+  defaultObjectClassRegistry,
+} from "./core/object/object-class-registry.js";
+export type { ObjectFactory } from "./core/object/object-class-registry.js";
 // Identity: base + subtype-specific
 export {
   MetaIdentity,

package/src/loader/meta-data-loader.ts

@@ -17,8 +17,12 @@ import { ParseError } from "../errors.js";
 import type { LoaderWarning } from "../source.js";
 import { codeSource, resolvedSource } from "../source.js";
 import { parseJson } from "../parser-json.js";
-import { validateDataGridSortFields, validateFilterableHasIndex, validateOriginPaths, validateDataGridFilterValues, validateFieldObjectStorage, validateTemplatePayloadRefs } from "./validation-passes.js";
+import { validateDataGridSortFields, validateFilterableHasIndex, validateOriginPaths, validateDataGridFilterValues, validateFieldObjectStorage, validateTemplatePayloadRefs, validateFieldDefaults } from "./validation-passes.js";
 import { validateSourceRoles } from "../persistence/source/validate-source-roles.js";
+import { validateSourcePhysicalNames } from "../persistence/source/validate-source-physical-names.js";
+import { validateSourceParameterRef } from "../persistence/source/validate-source-parameter-ref.js";
+import { validateFieldReadOnly } from "../core/field/validate-field-readonly.js";
+import { validateDiscriminator } from "../core/object/validate-discriminator.js";
 import { resolveDeferredSupers } from "../super-resolve.js";
 import { validateSubtypeRules } from "../subtype-rules.js";
 import { validateAttrSchema } from "../attr-schema-validate.js";
@@ -441,6 +445,32 @@ export class MetaDataLoader {
       // exactly one must carry role "primary" (ERR_SOURCE_NO_PRIMARY /
       // ERR_SOURCE_MULTIPLE_PRIMARY).
       errors.push(...validateSourceRoles(root));
+
+      // FR-016 / ADR-0018 — per-kind physical-name alias validation on
+      // source.rdb (kind-matching alias, no multiples, legacy @table warning).
+      const physicalNameResult = validateSourcePhysicalNames(root);
+      errors.push(...physicalNameResult.errors);
+      envelopeWarnings.push(...physicalNameResult.warnings);
+
+      // FR-013 — field-level @readOnly cross-attribute rules
+      // (ERR_READONLY_DOWNGRADE / ERR_READONLY_ASSIGNED_PRIMARY /
+      // WARN_READONLY_VALUE_OBJECT).
+      const readOnlyResult = validateFieldReadOnly(root);
+      errors.push(...readOnlyResult.errors);
+      envelopeWarnings.push(...readOnlyResult.warnings);
+
+      // FR-015 — source.rdb @parameterRef typed-input validation.
+      errors.push(...validateSourceParameterRef(root));
+
+      // FR-014 — TPH discriminator (@discriminator / @discriminatorValue)
+      // cross-attribute validation.
+      errors.push(...validateDiscriminator(root));
+
+      // Eleventh pass: per-type @default coercibility — a field's @default value
+      // must coerce to the field's type (int/long → integer, double/float/decimal →
+      // finite number, boolean → true|false). Enum @default membership is validated
+      // by validateAttrSchema (Check 5). Cross-port parity with Java/Python/C#.
+      errors.push(...validateFieldDefaults(root));
     }
 
     // If nothing parsed successfully, synthesize an empty root so callers

package/src/loader/validation-passes.ts

@@ -24,6 +24,13 @@ import {
 import {
   TEMPLATE_ATTR_PAYLOAD_REF,
   TEMPLATE_ATTR_REQUIRED_SLOTS,
+  TEMPLATE_ATTR_TEXT_REF,
+  TEMPLATE_ATTR_KIND,
+  TEMPLATE_KIND_EMAIL,
+  TEMPLATE_ATTR_SUBJECT_REF,
+  TEMPLATE_ATTR_HTML_BODY_REF,
+  TEMPLATE_SUBTYPE_OUTPUT,
+  TEMPLATE_SUBTYPE_PROMPT,
 } from "../template/template-constants.js";
 import { OBJECT_SUBTYPE_VALUE } from "../core/object/object-constants.js";
 import {
@@ -36,6 +43,15 @@ import {
   FIELD_ATTR_OBJECT_REF,
   FIELD_ATTR_STORAGE,
   STORAGE_FLATTENED,
+  FIELD_ATTR_DEFAULT,
+  FIELD_SUBTYPE_INT,
+  FIELD_SUBTYPE_LONG,
+  FIELD_SUBTYPE_CURRENCY,
+  FIELD_SUBTYPE_DOUBLE,
+  FIELD_SUBTYPE_FLOAT,
+  FIELD_SUBTYPE_DECIMAL,
+  FIELD_SUBTYPE_BOOLEAN,
+  FIELD_SUBTYPE_ENUM,
 } from "../core/field/field-constants.js";
 import { FIELD_ATTR_DB_INDEXED } from "../persistence/db/db-constants.js";
 import { IDENTITY_ATTR_FIELDS } from "../core/identity/identity-constants.js";
@@ -97,6 +113,56 @@ export function validateDataGridSortFields(root: MetaData): ParseError[] {
 export function validateTemplatePayloadRefs(root: MetaData): ParseError[] {
   const errors: ParseError[] = [];
   for (const tmpl of root.ownChildren().filter((c) => c.type === TYPE_TEMPLATE)) {
+    // --- @kind / textRef / email part-ref cross-field rules ---
+    // template.output is either a document (@kind absent/"document" → @textRef
+    // required) or an email (@kind="email" → @subjectRef + @htmlBodyRef required,
+    // @textRef unused). template.prompt always requires @textRef (the renderable
+    // body). The closed-enum membership of @kind is handled by validateAttrSchema
+    // (allowedValues) — here we only enforce the conditional ref presence.
+    if (tmpl.subType === TEMPLATE_SUBTYPE_OUTPUT) {
+      const kind = tmpl.ownAttr(TEMPLATE_ATTR_KIND);
+      if (kind === TEMPLATE_KIND_EMAIL) {
+        if (typeof tmpl.ownAttr(TEMPLATE_ATTR_SUBJECT_REF) !== "string") {
+          errors.push(
+            new ParseError(
+              `template "${tmpl.name}" @kind "email" requires @subjectRef`,
+              { code: "ERR_INVALID_TEMPLATE", source: tmpl.source },
+            ),
+          );
+        }
+        if (typeof tmpl.ownAttr(TEMPLATE_ATTR_HTML_BODY_REF) !== "string") {
+          errors.push(
+            new ParseError(
+              `template "${tmpl.name}" @kind "email" requires @htmlBodyRef`,
+              { code: "ERR_INVALID_TEMPLATE", source: tmpl.source },
+            ),
+          );
+        }
+      } else {
+        // @kind absent or "document" → require @textRef. (An out-of-enum @kind is
+        // separately reported by validateAttrSchema; we still require @textRef so a
+        // document is never bodyless.)
+        if (typeof tmpl.ownAttr(TEMPLATE_ATTR_TEXT_REF) !== "string") {
+          errors.push(
+            new ParseError(
+              `template "${tmpl.name}" @kind "document" requires @textRef`,
+              { code: "ERR_INVALID_TEMPLATE", source: tmpl.source },
+            ),
+          );
+        }
+      }
+    } else if (tmpl.subType === TEMPLATE_SUBTYPE_PROMPT) {
+      // template.prompt always carries a renderable body via @textRef.
+      if (typeof tmpl.ownAttr(TEMPLATE_ATTR_TEXT_REF) !== "string") {
+        errors.push(
+          new ParseError(
+            `template "${tmpl.name}" requires @textRef`,
+            { code: "ERR_INVALID_TEMPLATE", source: tmpl.source },
+          ),
+        );
+      }
+    }
+
     const payloadRef = tmpl.ownAttr(TEMPLATE_ATTR_PAYLOAD_REF);
     if (typeof payloadRef !== "string") continue; // absence handled by the required-attr schema check
     const payload = root.ownChildren().find((c) => c.type === TYPE_OBJECT && c.name === payloadRef);
@@ -454,6 +520,101 @@ export function validateFieldObjectStorage(root: MetaData): ParseError[] {
   return errors;
 }
 
+// ---------------------------------------------------------------------------
+// Per-type @default coercibility validation (Phase B — generalized @default)
+//
+// The @default attr is registered on the field base, so any field subtype may
+// declare it. Its value must coerce to the field's type (cross-port parity with
+// Java ValidationPhase.validateFieldDefaults, Python _validate_field_defaults,
+// C# ValidateFieldDefaults):
+//   - int / long / currency        → ASCII integer parse (or finite decimal that
+//                                     truncates — matches the engine's Coerce INT/LONG fallback)
+//   - double / float / decimal      → finite-number parse (ASCII)
+//   - boolean                       → exactly "true" | "false"
+//   - enum                          → member of @values (handled by attr-schema-validate
+//                                     Check 5; SKIPPED here to avoid double-emit)
+//   - string / date / time / object / others → any value allowed
+// A violation emits ERR_BAD_ATTR_VALUE on the field node's source.
+//
+// Own-only: validates @default declared on THIS node (ownAttr), matching the
+// @values / FR-011 own-attr passes. Numeric gates are ASCII-only — they reject
+// "1_000" separators, "0x.."/radix literals, and unicode digits (JS Number()
+// would accept some of these). This mirrors Java's Long.parseLong / Double.parseDouble
+// strictness exactly.
+//
+// The @default value is type-preserved by the parser (a JSON true/false → boolean,
+// a JSON number → number, a JSON string → string), so it is stringified to the
+// canonical form before the per-type gate (lower-case bool, plain number).
+// ---------------------------------------------------------------------------
+
+const _INT_DEFAULT_SUBTYPES = new Set<string>([
+  FIELD_SUBTYPE_INT,
+  FIELD_SUBTYPE_LONG,
+  FIELD_SUBTYPE_CURRENCY,
+]);
+const _NUM_DEFAULT_SUBTYPES = new Set<string>([
+  FIELD_SUBTYPE_DOUBLE,
+  FIELD_SUBTYPE_FLOAT,
+  FIELD_SUBTYPE_DECIMAL,
+]);
+
+// ASCII-only integer: optional sign, then digits. No separators, radix, unicode.
+const _ASCII_INT = /^[+-]?\d+$/;
+// ASCII-only decimal: optional sign, digits with optional fraction/exponent.
+// No separators, no hex, no Infinity/NaN.
+const _ASCII_NUMBER = /^[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/;
+
+/** Canonical string form of a type-preserved @default value (lower-case bool, plain number). */
+function _stringifyDefault(value: string | number | boolean): string {
+  if (typeof value === "boolean") return value ? "true" : "false";
+  return String(value);
+}
+
+/** ASCII integer, or a finite ASCII decimal that truncates to an integer (Java parsesAsLong parity). */
+function _parsesAsLong(s: string): boolean {
+  const t = s.trim();
+  if (_ASCII_INT.test(t)) return true;
+  // accept a finite decimal that truncates to an integer value
+  return _ASCII_NUMBER.test(t) && Number.isFinite(Number(t));
+}
+
+/** Finite ASCII number (Java parsesAsFiniteNumber parity). */
+function _parsesAsFiniteNumber(s: string): boolean {
+  const t = s.trim();
+  return _ASCII_NUMBER.test(t) && Number.isFinite(Number(t));
+}
+
+export function validateFieldDefaults(root: MetaData): ParseError[] {
+  const errors: ParseError[] = [];
+  _walkFieldDefaults(root, errors);
+  return errors;
+}
+
+function _walkFieldDefaults(node: MetaData, errors: ParseError[]): void {
+  if (node.type === TYPE_FIELD && node.subType !== FIELD_SUBTYPE_ENUM) {
+    // Enum @default membership is validated by attr-schema-validate Check 5.
+    const raw = node.ownAttr(FIELD_ATTR_DEFAULT);
+    if (raw !== undefined && raw !== null && !Array.isArray(raw) && typeof raw !== "object") {
+      const def = _stringifyDefault(raw as string | number | boolean);
+      const sub = node.subType;
+      let ok: boolean;
+      if (_INT_DEFAULT_SUBTYPES.has(sub)) ok = _parsesAsLong(def);
+      else if (_NUM_DEFAULT_SUBTYPES.has(sub)) ok = _parsesAsFiniteNumber(def);
+      else if (sub === FIELD_SUBTYPE_BOOLEAN) ok = def === "true" || def === "false";
+      else ok = true; // string / date / time / object / others — any value allowed
+      if (!ok) {
+        errors.push(
+          new ParseError(
+            `field.${sub} "${node.name}" @${FIELD_ATTR_DEFAULT} "${def}" is not coercible to the field's type`,
+            { code: "ERR_BAD_ATTR_VALUE", source: node.source },
+          ),
+        );
+      }
+    }
+  }
+  for (const child of node.ownChildren()) _walkFieldDefaults(child, errors);
+}
+
 // ---------------------------------------------------------------------------
 // Layout dataGrid @filter value validation
 //

package/src/naming.ts

@@ -60,14 +60,15 @@ export function pluralize(s: string): string {
 }
 
 export function resolveTableName(entity: MetaData): string {
-  // Primary source carries the physical table/view name (@table). Writability
-  // (table vs view/storedProc/tableFunction) only affects write-routing — for
-  // SELECT-side name resolution, a read-only primary source is the right answer.
+  // FR-016: primary source's `physicalName` implements the four-step rule
+  // (kind-matching alias → legacy @table → source.name → entity-name fallback),
+  // so this helper now just delegates. Writability (table vs view/storedProc/
+  // tableFunction) only affects write-routing — for SELECT-side name resolution,
+  // a read-only primary source is the right answer.
   const source = entity.ownChildren().find(
     (c): c is MetaSource => c instanceof MetaSource && c.role === SOURCE_ROLE_PRIMARY,
   );
-  const name = source?.tableName;
-  if (typeof name === "string" && name !== "") return name;
+  if (source !== undefined) return source.physicalName;
   return pluralize(toSnakeCase(entity.name));
 }