@metaobjectsdev/metadata 0.5.0-rc.1

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

@@ -0,0 +1,89 @@
+// FileMetaDataLoader — discovers file-backed MetaDataSources and runs the
+// MetaDataLoader pipeline over them. A UrlMetaDataLoader will slot in the
+// same way later.
+
+import type { Stats } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { MetaDataLoader, type LoadResult } from "../loader/meta-data-loader.js";
+import { FileSource } from "./file-source.js";
+import { parseYaml } from "./parser-yaml.js";
+import type { ParseOptions, ParseResult } from "../parser-core.js";
+import type { MetaDataSource } from "../loader/meta-data-source.js";
+
+/** Minimal glob matcher supporting `*` (any chars except `/`) and `**` (any chars). */
+function matchSimpleGlob(pattern: string, value: string): boolean {
+  const regexStr = pattern
+    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+    .replace(/\*\*/g, "::DOUBLESTAR::")
+    .replace(/\*/g, "[^/]*")
+    .replace(/::DOUBLESTAR::/g, ".*");
+  return new RegExp(`^${regexStr}$`).test(value);
+}
+
+export class FileMetaDataLoader extends MetaDataLoader {
+  /** Adds YAML parsing on top of the base loader's JSON-only `parseSource`. */
+  protected override parseSource(
+    content: string,
+    source: MetaDataSource,
+    parseOpts: ParseOptions,
+  ): ParseResult {
+    if (source.format === "yaml") {
+      return parseYaml(content, parseOpts);
+    }
+    return super.parseSource(content, source, parseOpts);
+  }
+
+  /**
+   * Load every `.json` / `.yaml` / `.yml` file in a directory (non-recursive),
+   * in deterministic ordinal filename order.
+   * @param opts.exclude glob patterns (relative to dir) to skip — `*` / `**`.
+   */
+  async loadDirectory(dir: string, opts?: { exclude?: string[] }): Promise<LoadResult> {
+    let entries: string[];
+    try {
+      // Sorted for deterministic multi-file load order: the overlay merge is
+      // order-sensitive (last-writer-wins on attr conflicts), so the scan must
+      // not depend on filesystem readdir order. Ordinal filename sort is
+      // reproducible across the Java/Python/C# ports.
+      entries = (await readdir(dir)).sort();
+    } catch (err) {
+      // Surface the I/O failure as a collected error via the empty-source path.
+      const emptyResult = await this.load([]);
+      return {
+        ...emptyResult,
+        errors: [
+          new Error(`loadDirectory: cannot read ${dir}: ${(err as Error).message}`),
+          ...emptyResult.errors,
+        ],
+      };
+    }
+
+    const excludes = opts?.exclude ?? [];
+    const paths: string[] = [];
+    for (const entry of entries) {
+      const lower = entry.toLowerCase();
+      if (!lower.endsWith(".json") && !lower.endsWith(".yaml") && !lower.endsWith(".yml")) {
+        continue;
+      }
+      const filePath = join(dir, entry);
+      let statResult: Stats;
+      try {
+        statResult = await stat(filePath);
+      } catch {
+        // Entry vanished between readdir and stat (TOCTOU) or is not accessible.
+        // Skip it rather than breaking the no-throw contract of loadDirectory.
+        continue;
+      }
+      if (!statResult.isFile()) continue;
+      if (excludes.some((p) => matchSimpleGlob(p, entry))) continue;
+      paths.push(filePath);
+    }
+    return this.loadFiles(paths);
+  }
+
+  /** Load an explicit list of file paths, in order. */
+  async loadFiles(paths: string[]): Promise<LoadResult> {
+    return this.load(paths.map((p) => new FileSource(p)));
+  }
+}

package/src/core/file-source.ts

@@ -0,0 +1,52 @@
+// FileSource — a MetaDataSource backed by a file on disk. Server-side only
+// (touches node:fs); lives under src/core/ so the browser-safe root never
+// imports it.
+
+import { basename, extname } from "node:path";
+import type { MetaDataFormat, MetaDataSource } from "../loader/meta-data-source.js";
+
+/** Infer a source format from a file extension. `.yaml`/`.yml` → "yaml";
+ *  everything else (including `.json`) → "json", the canonical default. */
+function inferFormat(path: string): MetaDataFormat {
+  const ext = extname(path).toLowerCase();
+  return ext === ".yaml" || ext === ".yml" ? "yaml" : "json";
+}
+
+// File reader — Bun-first (Bun.file().text()) with a Node fallback
+// (node:fs/promises.readFile). Matches CLAUDE.md's Bun-first / Node-compatible policy.
+let _readText: ((path: string) => Promise<string>) | undefined;
+
+async function getReadText(): Promise<(path: string) => Promise<string>> {
+  if (_readText !== undefined) return _readText;
+  if (typeof Bun !== "undefined") {
+    _readText = (p) => Bun.file(p).text();
+  } else {
+    const { readFile } = await import("node:fs/promises");
+    _readText = (p) => readFile(p, "utf-8");
+  }
+  return _readText;
+}
+
+/** A metadata source backed by a file on disk. */
+export class FileSource implements MetaDataSource {
+  readonly id: string;
+  readonly format: MetaDataFormat;
+  private readonly _path: string;
+
+  constructor(path: string) {
+    this._path = path;
+    // basename() for readable error messages; cross-platform (handles both / and \). Full path retained for read().
+    this.id = basename(path);
+    this.format = inferFormat(path);
+  }
+
+  /** The absolute/relative path this source reads from. */
+  get path(): string {
+    return this._path;
+  }
+
+  async read(): Promise<string> {
+    const readText = await getReadText();
+    return readText(this._path);
+  }
+}

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

@@ -0,0 +1,44 @@
+// Identity concern constants — subtypes, attr keys, and generation strategy values.
+
+// ---------------------------------------------------------------------------
+// Identity subtypes (3: primary, secondary, reference — NO base; Java doesn't register one)
+// ---------------------------------------------------------------------------
+
+export const IDENTITY_SUBTYPE_PRIMARY = "primary";
+export const IDENTITY_SUBTYPE_SECONDARY = "secondary";
+export const IDENTITY_SUBTYPE_REFERENCE = "reference";
+
+export const IDENTITY_SUBTYPES = [
+  IDENTITY_SUBTYPE_PRIMARY,
+  IDENTITY_SUBTYPE_SECONDARY,
+  IDENTITY_SUBTYPE_REFERENCE,
+] as const;
+export type IdentitySubType = (typeof IDENTITY_SUBTYPES)[number];
+
+// ---------------------------------------------------------------------------
+// Identity attrs
+// ---------------------------------------------------------------------------
+
+export const IDENTITY_ATTR_FIELDS = "fields";
+export const IDENTITY_ATTR_GENERATION = "generation";
+/** On secondary identities: true → uniqueIndex; false/absent → index. Defaults to true for back-compat. */
+export const IDENTITY_ATTR_UNIQUE = "unique";
+/** Identity-reference attr: target entity (bare or dotted `Entity.field` / `Entity.fA,fB`). */
+export const IDENTITY_REFERENCE_ATTR_REFERENCES = "references";
+/** Identity-reference attr: physical-enforcement flag. Default true → hard FK constraint; false → logical-only reference. */
+export const IDENTITY_REFERENCE_ATTR_ENFORCE = "enforce";
+
+// ---------------------------------------------------------------------------
+// Identity generation strategies (values for IDENTITY_ATTR_GENERATION)
+// ---------------------------------------------------------------------------
+
+export const GENERATION_INCREMENT = "increment";
+export const GENERATION_UUID = "uuid";
+export const GENERATION_ASSIGNED = "assigned";
+
+export const GENERATION_VALUES = [
+  GENERATION_INCREMENT,
+  GENERATION_UUID,
+  GENERATION_ASSIGNED,
+] as const;
+export type GenerationValue = (typeof GENERATION_VALUES)[number];

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

@@ -0,0 +1,80 @@
+// Identity attribute schemas — per-subtype attr inventories for identity types.
+// Consumed by registerCoreTypes().
+
+import type { AttrSchema } from "../../registry.js";
+import {
+  ATTR_SUBTYPE_STRING,
+  ATTR_SUBTYPE_BOOLEAN,
+  ATTR_SUBTYPE_STRINGARRAY,
+} from "../attr/attr-constants.js";
+import {
+  IDENTITY_SUBTYPE_PRIMARY,
+  IDENTITY_SUBTYPE_SECONDARY,
+  IDENTITY_SUBTYPE_REFERENCE,
+  IDENTITY_ATTR_FIELDS,
+  IDENTITY_ATTR_GENERATION,
+  IDENTITY_ATTR_UNIQUE,
+  IDENTITY_REFERENCE_ATTR_REFERENCES,
+  IDENTITY_REFERENCE_ATTR_ENFORCE,
+  GENERATION_VALUES,
+} from "./identity-constants.js";
+
+/** Attrs on identity.primary / identity.secondary — @fields is required. */
+export const identityFieldsAttr: AttrSchema = {
+  name: IDENTITY_ATTR_FIELDS,
+  valueType: ATTR_SUBTYPE_STRINGARRAY,
+  required: true,
+  description:
+    "The field name(s) composing this identity. Single-element for a simple PK/index, multiple for a composite.",
+};
+
+const primaryIdentityAttrs: AttrSchema[] = [
+  { ...identityFieldsAttr },
+  {
+    name: IDENTITY_ATTR_GENERATION,
+    valueType: ATTR_SUBTYPE_STRING,
+    required: false,
+    allowedValues: [...GENERATION_VALUES],
+    description:
+      "Primary-key value generation strategy: 'increment' (auto-increment), 'uuid', or 'assigned' (caller-supplied).",
+  },
+];
+
+const secondaryIdentityAttrs: AttrSchema[] = [
+  { ...identityFieldsAttr },
+  {
+    name: IDENTITY_ATTR_UNIQUE,
+    valueType: ATTR_SUBTYPE_BOOLEAN,
+    required: false,
+    description:
+      "When true (default), the secondary identity is a UNIQUE index; false makes it a plain (non-unique) index.",
+  },
+];
+
+const referenceIdentityAttrs: AttrSchema[] = [
+  { ...identityFieldsAttr },
+  {
+    name: IDENTITY_REFERENCE_ATTR_REFERENCES,
+    valueType: ATTR_SUBTYPE_STRING,
+    required: true,
+    description:
+      "Target of the reference. Bare entity name (e.g. 'Program') resolves to that entity's primary identity. " +
+      "Dotted forms ('Program.id' or 'Program.fieldA,fieldB') target an explicit field set on the entity.",
+  },
+  {
+    name: IDENTITY_REFERENCE_ATTR_ENFORCE,
+    valueType: ATTR_SUBTYPE_BOOLEAN,
+    required: false,
+    description:
+      "When true (default), the backend physically enforces the reference (SQL FK constraint, " +
+      "document validation rule, graph edge guarantee). Set false to declare a logical reference " +
+      "for navigation/typing/codegen only — the value may dangle at the backend level.",
+  },
+];
+
+/** Attrs per identity subtype. primary adds @generation; secondary adds @unique. */
+export const IDENTITY_ATTRS_MAP = new Map<string, AttrSchema[]>([
+  [IDENTITY_SUBTYPE_PRIMARY, [...primaryIdentityAttrs]],
+  [IDENTITY_SUBTYPE_SECONDARY, [...secondaryIdentityAttrs]],
+  [IDENTITY_SUBTYPE_REFERENCE, [...referenceIdentityAttrs]],
+]);

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

@@ -0,0 +1,148 @@
+// MetaIdentity — concrete node class for type=identity nodes.
+// MetaPrimaryIdentity and MetaSecondaryIdentity are co-located subtype classes.
+//
+// Extends MetaData directly: no model wrapper, no metaOf() indirection.
+
+import { MetaData } from "../../shared/meta-data.js";
+import {
+  IDENTITY_SUBTYPE_PRIMARY,
+  IDENTITY_SUBTYPE_SECONDARY,
+  IDENTITY_SUBTYPE_REFERENCE,
+  IDENTITY_ATTR_FIELDS,
+  IDENTITY_ATTR_GENERATION,
+  IDENTITY_ATTR_UNIQUE,
+  IDENTITY_REFERENCE_ATTR_REFERENCES,
+  IDENTITY_REFERENCE_ATTR_ENFORCE,
+} from "./identity-constants.js";
+import type { MetaRoot } from "../../shared/meta-root.js";
+
+/** Strongly-typed identity generation strategies. */
+export type IdentityGeneration = "increment" | "uuid" | "assigned";
+
+export class MetaIdentity extends MetaData {
+  get fields(): string[] {
+    const f = this.ownAttr(IDENTITY_ATTR_FIELDS);
+    return Array.isArray(f) ? (f as string[]) : [];
+  }
+
+  /**
+   * Whether the identity enforces uniqueness.
+   * Defaults to true; explicit `@unique: false` makes it a non-unique index.
+   */
+  get unique(): boolean {
+    return this.ownAttr(IDENTITY_ATTR_UNIQUE) !== false;
+  }
+
+  isPrimary(): boolean {
+    return this.subType === IDENTITY_SUBTYPE_PRIMARY;
+  }
+
+  isSecondary(): boolean {
+    return this.subType === IDENTITY_SUBTYPE_SECONDARY;
+  }
+
+  isReference(): boolean {
+    return this.subType === IDENTITY_SUBTYPE_REFERENCE;
+  }
+
+  isComposite(): boolean {
+    return this.fields.length > 1;
+  }
+}
+
+/**
+ * Primary identity (the entity's PK). Always unique by definition.
+ * Carries `@generation` (increment / uuid / assigned).
+ */
+export class MetaPrimaryIdentity extends MetaIdentity {
+  get generation(): IdentityGeneration | undefined {
+    const v = this.ownAttr(IDENTITY_ATTR_GENERATION);
+    return typeof v === "string" ? (v as IdentityGeneration) : undefined;
+  }
+}
+
+/**
+ * Secondary identity — a unique or non-unique index on one or more fields.
+ * `@generation` does not apply here.
+ */
+export class MetaSecondaryIdentity extends MetaIdentity {}
+
+/**
+ * Reference identity — a field (or compound field set) on this entity whose
+ * value(s) identify an instance of another entity.
+ *
+ * Maps to: SQL foreign key, document linked reference, graph edge target,
+ * OO pointer/reference. Backend-agnostic at the metamodel level.
+ *
+ * Carries `@references` — either a bare entity name (defaults to that
+ * entity's primary identity) or a dotted `Entity.field` or
+ * `Entity.fieldA,fieldB` form for explicit field/compound targets.
+ */
+export class MetaReferenceIdentity extends MetaIdentity {
+  /** Raw `@references` attr value, unparsed. */
+  get referencesRaw(): string | undefined {
+    const v = this.ownAttr(IDENTITY_REFERENCE_ATTR_REFERENCES);
+    return typeof v === "string" ? v : undefined;
+  }
+
+  /** Target entity name (the bit before the dot, or the whole bare value). */
+  get targetEntity(): string | undefined {
+    const raw = this.referencesRaw;
+    if (raw === undefined) return undefined;
+    const dotIdx = raw.indexOf(".");
+    return dotIdx === -1 ? raw : raw.slice(0, dotIdx);
+  }
+
+  /**
+   * Whether the reference is physically enforced by the backend.
+   * Default true (hard FK constraint emitted). Explicit `@enforce: false`
+   * marks the reference as logical-only — drizzle-schema skips `.references()`
+   * and migrate-ts's expected schema omits the FK descriptor. relations()
+   * block and projection JOIN inference are unaffected.
+   */
+  get enforce(): boolean {
+    return this.ownAttr(IDENTITY_REFERENCE_ATTR_ENFORCE) !== false;
+  }
+
+  /**
+   * Target field names. Empty array means "use the target's primary identity"
+   * (the bare-entity form). For dotted forms, returns the field(s) after the
+   * dot (comma-split, trimmed).
+   */
+  get targetFields(): string[] {
+    const raw = this.referencesRaw;
+    if (raw === undefined) return [];
+    const dotIdx = raw.indexOf(".");
+    if (dotIdx === -1) return [];
+    return raw
+      .slice(dotIdx + 1)
+      .split(",")
+      .map((s) => s.trim())
+      .filter((s) => s.length > 0);
+  }
+
+  /**
+   * Resolve the target field on the referenced entity that this reference
+   * points at. Priority: explicit dotted-form `@references: "Entity.field"`
+   * override → target entity's primary identity field → "id" fallback.
+   *
+   * Returns undefined only if the target entity cannot be found in `root`.
+   * Centralizes the FK-target resolution rule used by projection view DDL,
+   * Drizzle schema emit, and migration schema comparison.
+   */
+  resolvedTargetPkField(root: MetaRoot): string | undefined {
+    const explicit = this.targetFields[0];
+    if (explicit !== undefined) return explicit;
+
+    const targetName = this.targetEntity;
+    if (targetName === undefined) return undefined;
+    const targetObj = root.findObject(targetName);
+    if (!targetObj) return undefined;
+
+    const primary = targetObj.primaryIdentity();
+    const fields = primary?.ownAttr(IDENTITY_ATTR_FIELDS) as string | string[] | undefined;
+    if (typeof fields === "string") return fields.split(",")[0]!.trim();
+    if (Array.isArray(fields) && fields.length > 0) return String(fields[0]).trim();
+    return "id";
+  }
+}

package/src/core/index.ts

@@ -0,0 +1,12 @@
+// @metaobjectsdev/metadata/core — server-side capabilities.
+//
+// This entry point holds everything that touches node:fs or the `yaml`
+// dependency: the file loaders, the YAML authoring parser, and the
+// load-and-export convenience. The root `@metaobjectsdev/metadata` entry is
+// browser-safe and imports none of this. See the package README.
+
+export { FileSource } from "./file-source.js";
+export { FileMetaDataLoader } from "./file-meta-data-loader.js";
+export { parseYaml } from "./parser-yaml.js";
+export { loadAndExportJson } from "./export-json.js";
+export type { ExportResult } from "./export-json.js";

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

@@ -0,0 +1,151 @@
+// MetaObject — concrete node class for type=object nodes.
+//
+// Extends MetaData directly: no model wrapper, no metaOf() indirection.
+// Children are already concrete typed nodes; accessors filter by type constant.
+
+import { MetaData } from "../../shared/meta-data.js";
+import {
+  TYPE_FIELD,
+  TYPE_IDENTITY,
+  TYPE_RELATIONSHIP,
+  TYPE_VALIDATOR,
+  TYPE_SOURCE,
+  TYPE_LAYOUT,
+} from "../../shared/base-types.js";
+import {
+  SOURCE_SUBTYPE_DB_TABLE,
+  SOURCE_DB_TABLE_ATTR_NAME,
+} from "../../persistence/source/source-constants.js";
+import {
+  OBJECT_SUBTYPE_ENTITY,
+  OBJECT_SUBTYPE_VALUE,
+} from "./object-constants.js";
+import {
+  IDENTITY_SUBTYPE_PRIMARY,
+  IDENTITY_SUBTYPE_SECONDARY,
+  IDENTITY_SUBTYPE_REFERENCE,
+} from "../identity/identity-constants.js";
+import type { MetaField } from "../field/meta-field.js";
+import type { MetaIdentity, MetaReferenceIdentity } from "../identity/meta-identity.js";
+import type { MetaLayout } from "../../presentation/layout/meta-layout.js";
+import type { MetaRelationship } from "../relationship/meta-relationship.js";
+import type { MetaValidator } from "../validator/meta-validator.js";
+
+export class MetaObject extends MetaData {
+  get dbTable(): string | undefined {
+    return this.cached("dbTable", () => {
+      const source = this.children().find(
+        (c) => c.type === TYPE_SOURCE && c.subType === SOURCE_SUBTYPE_DB_TABLE,
+      );
+      const name = source?.ownAttr(SOURCE_DB_TABLE_ATTR_NAME);
+      return typeof name === "string" && name !== "" ? name : undefined;
+    });
+  }
+
+  isEntity(): boolean {
+    return this.subType === OBJECT_SUBTYPE_ENTITY;
+  }
+
+  isValue(): boolean {
+    return this.subType === OBJECT_SUBTYPE_VALUE;
+  }
+
+  /** All effective fields (own + inherited via extends). */
+  fields(): MetaField[] {
+    return this.cached("fields", () =>
+      this.children().filter((c): c is MetaField => c.type === TYPE_FIELD),
+    );
+  }
+
+  /** Own fields only — excludes fields inherited via extends. Java parity: getMetaFields(false). */
+  ownFields(): MetaField[] {
+    return this.cached("ownFields", () =>
+      this.ownChildren().filter((c): c is MetaField => c.type === TYPE_FIELD),
+    );
+  }
+
+  /** All effective identities (own + inherited via extends). */
+  identities(): MetaIdentity[] {
+    return this.cached("identities", () =>
+      this.children().filter((c): c is MetaIdentity => c.type === TYPE_IDENTITY),
+    );
+  }
+
+  /** Own identities only — excludes inherited. */
+  ownIdentities(): MetaIdentity[] {
+    return this.cached("ownIdentities", () =>
+      this.ownChildren().filter((c): c is MetaIdentity => c.type === TYPE_IDENTITY),
+    );
+  }
+
+  /** Returns the single primary identity, if any. */
+  primaryIdentity(): MetaIdentity | undefined {
+    return this.cached("primaryIdentity", () =>
+      this.identities().find((i) => i.subType === IDENTITY_SUBTYPE_PRIMARY),
+    );
+  }
+
+  /** Secondary identities. */
+  secondaryIdentities(): MetaIdentity[] {
+    return this.cached("secondaryIdentities", () =>
+      this.identities().filter((i) => i.subType === IDENTITY_SUBTYPE_SECONDARY),
+    );
+  }
+
+  /** Reference identities — fields on this entity that identify another entity. */
+  referenceIdentities(): MetaReferenceIdentity[] {
+    return this.cached("referenceIdentities", () =>
+      this.identities().filter((i): i is MetaReferenceIdentity =>
+        i.subType === IDENTITY_SUBTYPE_REFERENCE,
+      ),
+    );
+  }
+
+  /** All effective relationships (own + inherited via extends). */
+  relationships(): MetaRelationship[] {
+    return this.cached("relationships", () =>
+      this.children().filter((c): c is MetaRelationship => c.type === TYPE_RELATIONSHIP),
+    );
+  }
+
+  /** Own relationships only — excludes inherited. */
+  ownRelationships(): MetaRelationship[] {
+    return this.cached("ownRelationships", () =>
+      this.ownChildren().filter((c): c is MetaRelationship => c.type === TYPE_RELATIONSHIP),
+    );
+  }
+
+  /** All effective validators (own + inherited via extends). */
+  validators(): MetaValidator[] {
+    return this.cached("validators", () =>
+      this.children().filter((c): c is MetaValidator => c.type === TYPE_VALIDATOR),
+    );
+  }
+
+  /** Own validators only — excludes validators inherited via extends. Java parity: getChildren(Class, false). */
+  ownValidators(): MetaValidator[] {
+    return this.cached("ownValidators", () =>
+      this.ownChildren().filter((c): c is MetaValidator => c.type === TYPE_VALIDATOR),
+    );
+  }
+
+  /** All effective layouts (own + inherited via extends). */
+  layouts(): MetaLayout[] {
+    return this.cached("layouts", () =>
+      this.children().filter((c): c is MetaLayout => c.type === TYPE_LAYOUT),
+    );
+  }
+
+  /** Own layouts only — excludes inherited. */
+  ownLayouts(): MetaLayout[] {
+    return this.cached("ownLayouts", () =>
+      this.ownChildren().filter((c): c is MetaLayout => c.type === TYPE_LAYOUT),
+    );
+  }
+
+  findField(name: string): MetaField | undefined {
+    return this.cached(`findField:${name}`, () =>
+      this.fields().find((f) => f.name === name),
+    );
+  }
+}

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

@@ -0,0 +1,21 @@
+// Object concern constants — subtypes for the object.* type family.
+
+import { SUBTYPE_BASE } from "../../shared/base-types.js";
+
+// ---------------------------------------------------------------------------
+// Object subtypes (cross-language, conceptual)
+// ---------------------------------------------------------------------------
+//
+//   - base   : abstract template (no runtime semantics)
+//   - entity : persistent record (typically has @primary identity)
+//   - value  : value-object (no identity; equality by content)
+//
+export const OBJECT_SUBTYPE_ENTITY = "entity";
+export const OBJECT_SUBTYPE_VALUE = "value";
+
+export const OBJECT_SUBTYPES = [
+  SUBTYPE_BASE,
+  OBJECT_SUBTYPE_ENTITY,
+  OBJECT_SUBTYPE_VALUE,
+] as const;
+export type ObjectSubType = (typeof OBJECT_SUBTYPES)[number];

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

@@ -0,0 +1,7 @@
+// Object attribute schemas — attrs common to every object subtype.
+// Consumed by registerCoreTypes().
+
+import type { AttrSchema } from "../../registry.js";
+
+/** Attrs common to every object subtype. */
+export const objectAttrs: AttrSchema[] = [];

package/src/core/parser-yaml.ts

@@ -0,0 +1,54 @@
+// Authoring YAML parser.
+//
+// parseYaml is a front-end: yaml.parse → desugar → the shared buildTree
+// (parser-core.ts). The desugar applies the four authoring-sugar rules so the
+// resulting typed tree is identical to the one the equivalent canonical JSON
+// produces.
+
+import { parse as parseYamlText } from "yaml";
+import { ParseError } from "../errors.js";
+import { buildTree, errOpts } from "../parser-core.js";
+import type { ParseOptions, ParseResult } from "../parser-core.js";
+import { desugar } from "./yaml-desugar.js";
+
+export function parseYaml(content: string, opts: ParseOptions): ParseResult {
+  // Strip UTF-8 BOM if present (consistent with parseJson).
+  const normalizedContent =
+    content.charCodeAt(0) === 0xfeff ? content.slice(1) : content;
+
+  // YAML syntax errors throw — consistent with parseJson on invalid JSON.
+  // The loader's per-source try/catch collects the throw into LoadResult.errors.
+  let parsed: unknown;
+  try {
+    parsed = parseYamlText(normalizedContent);
+  } catch (err) {
+    throw new ParseError(
+      `Invalid YAML: ${(err as Error).message}`,
+      { ...errOpts(opts.sourceName), code: "ERR_MALFORMED_YAML" },
+    );
+  }
+
+  // Desugar the sugared authoring object into the canonical structure.
+  const { canonical, errors: desugarErrors } = desugar(parsed, opts.registry);
+
+  // If the desugar could not produce a usable document at all, surface the
+  // first desugar error as a throw — parallels parseJson's top-level throws.
+  if (Object.keys(canonical).length === 0) {
+    throw new ParseError(
+      desugarErrors[0]!,
+      { ...errOpts(opts.sourceName), code: "ERR_MALFORMED_YAML" },
+    );
+  }
+
+  const result = buildTree(canonical, opts);
+
+  // Merge collected desugar errors ahead of buildTree's own collected errors.
+  const desugarParseErrors = desugarErrors.map(
+    (msg) => new ParseError(msg, { ...errOpts(opts.sourceName), code: "ERR_MALFORMED_YAML" }),
+  );
+  return {
+    root: result.root,
+    warnings: result.warnings,
+    errors: [...desugarParseErrors, ...result.errors],
+  };
+}