@metaobjectsdev/metadata 0.9.0 → 0.11.0-rc.1

package/src/registry-manifest.ts

@@ -0,0 +1,334 @@
+// SP-G Registry Conformance — the TS reference emitter.
+//
+// Walks an assembled core TypeRegistry and serializes the LOGICAL metamodel
+// vocabulary as a canonical, fully-sorted, byte-stable JSON manifest. This is
+// the single-source contract the other four ports (C#, Java, Kotlin, Python)
+// must byte-match — a structural gate against the SP-C class of silent
+// vocabulary drift (a port's registry diverging — wrong attr names, missing
+// subtypes, different required-ness — with every behavioral corpus still green).
+//
+// The IN/OUT boundary is documented in fixtures/registry-conformance/README.md.
+// In short, the manifest emits: type.subType + per-type/per-attr `description`
+// (FR-033) + attrs[{name, valueType, isArray, required, description, rules?,
+// example?, whenToUse?}] + the structural constraint graph (children / parents /
+// cardinality, FR-033) + commonAttrs + defaultSubTypes. EXCLUDED (per-port-
+// physical or not-universally-tracked-on-the-registry): factories/native
+// bindings; AttrSchema.default and allowedValues (Java's attr model —
+// ChildRequirement — carries neither).
+//
+// FR-033 Task 5 GREW the manifest: it now also emits the documentation surface
+// (every type/attr carries a required, non-empty `description`; optional `rules`/
+// `example`/`whenToUse`) AND the full structural constraint graph (each type's
+// `children` from childRules — childType/childSubType/childName + optional
+// cardinality min/max/named — and optional `parents`). Growing the canonical
+// RED-flags the other four ports' registry-conformance until they reconcile
+// (the intended intermediate state, same as the FR-032 sweep).
+
+import type { AttrSchema, ChildRule, TypeDefinition, TypeRegistry } from "./registry.js";
+import { ATTR_SUBTYPE_STRING, ATTR_SUBTYPE_STRINGARRAY } from "./core/attr/attr-constants.js";
+import {
+  EXCLUDED_PER_TYPE_ATTRS,
+  ExclusionReason,
+  isExcludedTypeSubType,
+  manifestRequiredOverride,
+} from "./registry-manifest-exclusions.js";
+
+/** One attribute in the manifest — the logical, cross-port-identical facet. */
+interface ManifestAttr {
+  name: string;
+  /** The attr's SCALAR value-type subtype, or null for a polymorphic/untyped attr (e.g. @default). */
+  valueType: string | null;
+  /** True for an array-valued attr (a list of the scalar `valueType`); the orthogonal array axis. */
+  isArray: boolean;
+  required: boolean;
+  /** FR-033 — human/AI-facing description of the attribute (required, non-empty). */
+  description: string;
+  /** FR-033 — prose documenting the complex rules enforced in code. Emitted only when present. */
+  rules?: string;
+  /** FR-033 — an example value. Emitted only when present. */
+  example?: string;
+  /** FR-033 — guidance on when to reach for this attribute. Emitted only when present. */
+  whenToUse?: string;
+}
+
+/** One structural child rule of a type (FR-033 constraint graph). */
+interface ManifestChild {
+  /** The admitted child `type` (`"*"` = any). */
+  childType: string;
+  /** The admitted child subType — a single subtype, `"*"` (any), or a list of admitted subtypes. */
+  childSubType: string | readonly string[];
+  /** The admitted child name (`"*"` = any). */
+  childName: string;
+  /** Cardinality lower bound — emitted only when defined on the rule. */
+  min?: number;
+  /** Cardinality upper bound (`null` = unbounded) — emitted only when defined on the rule. */
+  max?: number | null;
+  /** Whether the child must carry an explicit name — emitted only when defined on the rule. */
+  named?: boolean;
+}
+
+/** One registered (type, subType) in the manifest, with its docs + attrs + constraint graph. */
+interface ManifestType {
+  type: string;
+  subType: string;
+  /** FR-033 — human/AI-facing description of the type/subType (required, non-empty). */
+  description: string;
+  /** FR-033 — prose documenting the complex rules enforced in code. Emitted only when present. */
+  rules?: string;
+  /** FR-033 — an example. Emitted only when present. */
+  example?: string;
+  /** FR-033 — guidance on when to reach for this type/subType. Emitted only when present. */
+  whenToUse?: string;
+  attrs: ManifestAttr[];
+  /** FR-033 — the type's structural child rules (sorted), the constraint graph. */
+  children: ManifestChild[];
+  /** FR-033 — the child-side placement claim (sorted). Emitted only when present + non-empty. */
+  parents?: string[];
+}
+
+/** The full canonical manifest. All collections are sorted for byte-stability. */
+interface RegistryManifest {
+  types: ManifestType[];
+  commonAttrs: ManifestAttr[];
+  defaultSubTypes: Record<string, string>;
+}
+
+/** ASCII-string compare so the sort is locale-independent and byte-stable across ports. */
+function compareStrings(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/**
+ * Normalize one AttrSchema to the manifest's logical attr shape — decomposing
+ * array-ness into a scalar `valueType` + an orthogonal `isArray` flag.
+ *
+ * An attr is array-valued when its schema sets `isArray: true` (the cross-port
+ * model). For resilience, a legacy `valueType: "stringarray"` token is also
+ * decomposed to `{ valueType: "string", isArray: true }` — so no `stringarray`
+ * token ever reaches the manifest. A polymorphic attr (no valueType) is `null` +
+ * non-array.
+ */
+function toManifestAttr(attr: AttrSchema): ManifestAttr {
+  const isLegacyStringArray = attr.valueType === ATTR_SUBTYPE_STRINGARRAY;
+  const isArray = attr.isArray === true || isLegacyStringArray;
+  // The scalar value-type: a legacy stringarray token collapses to "string";
+  // otherwise the declared valueType (omitted → null for polymorphic attrs).
+  const valueType = isLegacyStringArray
+    ? ATTR_SUBTYPE_STRING
+    : (attr.valueType ?? null);
+  // FR-033: the documentation surface (`description` required + non-empty;
+  // `rules`/`example`/`whenToUse` emitted ONLY when present) follows the
+  // existing facets, preserving key order for byte-stability.
+  const out: ManifestAttr = {
+    name: attr.name,
+    valueType,
+    isArray,
+    required: attr.required,
+    description: attr.description,
+  };
+  if (attr.rules !== undefined) out.rules = attr.rules;
+  if (attr.example !== undefined) out.example = attr.example;
+  if (attr.whenToUse !== undefined) out.whenToUse = attr.whenToUse;
+  return out;
+}
+
+/** The canonical sort key for a child rule: childType, then the childSubType
+ *  string (or comma-joined list), then childName — ASCII codepoint compare. */
+function childSubTypeKey(childSubType: string | readonly string[]): string {
+  return Array.isArray(childSubType) ? childSubType.join(",") : (childSubType as string);
+}
+
+/**
+ * Normalize one structural ChildRule to the manifest's child shape (FR-033).
+ * Cardinality (`min`/`max`/`named`) is emitted ONLY when defined on the rule —
+ * legacy wildcard rules leave them undefined and must NOT fabricate cardinality.
+ * `max` may legitimately be `null` (unbounded); `null` is emitted, `undefined`
+ * is omitted.
+ */
+function toManifestChild(rule: ChildRule): ManifestChild {
+  const out: ManifestChild = {
+    childType: rule.childType,
+    childSubType: rule.childSubType,
+    childName: rule.childName,
+  };
+  if (rule.min !== undefined) out.min = rule.min;
+  if (rule.max !== undefined) out.max = rule.max;
+  if (rule.named !== undefined) out.named = rule.named;
+  return out;
+}
+
+/** Sort the constraint graph by (childType, childSubTypeKey, childName) — ASCII. */
+function sortedChildren(rules: readonly ChildRule[]): ManifestChild[] {
+  return rules
+    .map(toManifestChild)
+    .sort(
+      (a, b) =>
+        compareStrings(a.childType, b.childType) ||
+        compareStrings(childSubTypeKey(a.childSubType), childSubTypeKey(b.childSubType)) ||
+        compareStrings(a.childName, b.childName),
+    );
+}
+
+/** Sort attrs by name (ascending, ASCII). */
+function sortedAttrs(attrs: readonly AttrSchema[]): ManifestAttr[] {
+  return attrs
+    .map(toManifestAttr)
+    .sort((a, b) => compareStrings(a.name, b.name));
+}
+
+/**
+ * Sort PER-TYPE attrs, keeping only those the explicit classification marks
+ * INCLUDED (logical cross-port vocabulary). A per-type attr classified with any
+ * `ExclusionReason` (structural keyword, native binding, per-type `description`
+ * commonAttr dup) is carved out — for a documented reason, never a silent
+ * name-match. The filter is a no-op for TS (which never registers the carved-out
+ * names as per-type attrs); it is applied uniformly so the cross-port contract
+ * is explicit. NOTE: `description` is filtered ONLY here — it remains in the
+ * `commonAttrs` block (built via `sortedAttrs`, unfiltered).
+ */
+function sortedPerTypeAttrs(
+  attrs: readonly AttrSchema[],
+  type: string,
+  subType: string,
+): ManifestAttr[] {
+  return sortedAttrs(attrs.filter((a) => classifyPerTypeAttr(a.name) === INCLUDED)).map(
+    (attr) => {
+      // FR-024-pending requiredness override (the attr-level analogue of the
+      // Fr024Pending row carve-out): the TS registry already registers the
+      // FR-024 requiredness, but the manifest keeps emitting the pre-FR-024
+      // agreed value until the Phase-E atomic all-ports flip.
+      const required = manifestRequiredOverride(type, subType, attr.name);
+      return required === undefined ? attr : { ...attr, required };
+    },
+  );
+}
+
+/**
+ * The boundary classifier (Wave 3b). For every per-type attr the emitter
+ * encounters, the in/out decision is an EXPLICIT classification — never a silent
+ * default. Returns either an `ExclusionReason` (carved out, with a documented
+ * category) or `INCLUDED` (logical cross-port vocabulary). It is TOTAL: there is
+ * no "unclassified" third state, so a port can never silently let an unreasoned
+ * facet through — the self-documenting property the conformance test asserts.
+ *
+ * This replaces the prior tautology — a bare `EXCLUDED.has(name)` whose negative
+ * branch silently meant "logical". The decision is now centralized and reasoned;
+ * the cross-port byte-canonical + ADR-0023 (sealed agreed-vocabulary registry)
+ * together guarantee that an `INCLUDED` attr really is agreed vocabulary rather
+ * than an accidental registration, so inclusion-by-classification is sound.
+ *
+ * NOTE on liveness: a per-type attr exclusion (e.g. `extends`, `object`) is a
+ * CROSS-PORT carve-out that only the OO ports (Java/Kotlin) physically register;
+ * TS/C#/Python never register those names, so a single port's emitter cannot
+ * judge a carve-out "dead" — that is a cross-port property, asserted by the
+ * shared byte-canonical, not here.
+ */
+const INCLUDED = "included" as const;
+export type AttrClassification = ExclusionReason | typeof INCLUDED;
+
+export function classifyPerTypeAttr(name: string): AttrClassification {
+  return EXCLUDED_PER_TYPE_ATTRS.get(name) ?? INCLUDED;
+}
+
+/**
+ * Build one manifest type entry from its full TypeDefinition (FR-033). Key order
+ * is fixed for byte-stability: `type`, `subType`, `description`, then optional
+ * `rules`/`example`/`whenToUse` (emitted only when present), then `attrs`,
+ * `children` (the sorted constraint graph), and optional `parents` (emitted only
+ * when present + non-empty, sorted ASCII).
+ */
+function toManifestType(def: TypeDefinition): ManifestType {
+  // Build in fixed key order. Optional docs facets (rules/example/whenToUse) sit
+  // between `description` and `attrs`, so they are spread into the literal (when
+  // present) to preserve insertion order — `attrs`/`children`/`parents` follow.
+  const out: ManifestType = {
+    type: def.typeId.type,
+    subType: def.typeId.subType,
+    description: def.description,
+    ...(def.rules !== undefined ? { rules: def.rules } : {}),
+    ...(def.example !== undefined ? { example: def.example } : {}),
+    ...(def.whenToUse !== undefined ? { whenToUse: def.whenToUse } : {}),
+    attrs: sortedPerTypeAttrs(def.attributes, def.typeId.type, def.typeId.subType),
+    children: sortedChildren(def.childRules),
+  };
+  if (def.parents !== undefined && def.parents.length > 0) {
+    out.parents = [...def.parents].sort(compareStrings);
+  }
+  return out;
+}
+
+/**
+ * Build the canonical registry manifest object from an assembled registry.
+ *
+ * The registry must already be composed (e.g. `composeRegistry(coreProviders)`)
+ * so all providers — core types, db-domain attrs, common doc attrs — have run.
+ */
+export function buildRegistryManifest(registry: TypeRegistry): RegistryManifest {
+  // Walk every registered (type, subType). `allTypes()` returns the TypeIds;
+  // `find` gives each one's full TypeDefinition (description / attributes /
+  // childRules / parents / rules / example / whenToUse) in a single lookup.
+  const types: ManifestType[] = registry
+    .allTypes()
+    // Skip excluded (type, subType) rows: the `metadata.base` inheritance
+    // anchor (C-5) + the generic TS-presentation `view.*` controls (B-2).
+    .filter((typeId) => !isExcludedTypeSubType(typeId.type, typeId.subType))
+    .map((typeId) =>
+      toManifestType(
+        // The type IS registered (it came from allTypes()), so find() is defined.
+        registry.find(typeId.type, typeId.subType) as TypeDefinition,
+      ),
+    )
+    // Sort by the full "type.subType" key for a stable, port-independent order.
+    .sort((a, b) =>
+      compareStrings(`${a.type}.${a.subType}`, `${b.type}.${b.subType}`),
+    );
+
+  const commonAttrs = sortedAttrs(registry.getCommonAttrs());
+
+  // defaultSubTypes: rebuild with sorted keys so JSON.stringify emits a stable
+  // key order. There is no public "all default subTypes" accessor, so derive
+  // the candidate type names from the registered types and probe each.
+  const typeNames = Array.from(new Set(types.map((t) => t.type))).sort(
+    compareStrings,
+  );
+  const defaultSubTypes: Record<string, string> = {};
+  for (const typeName of typeNames) {
+    const defaultSub = registry.defaultSubTypeOf(typeName);
+    if (defaultSub !== undefined) {
+      defaultSubTypes[typeName] = defaultSub;
+    }
+  }
+
+  return { types, commonAttrs, defaultSubTypes };
+}
+
+/**
+ * Emit the canonical registry manifest as a byte-stable JSON string.
+ *
+ * Serialization contract — every port MUST match this exactly:
+ *  - 2-space indentation (JSON.stringify(_, _, 2)).
+ *  - Object keys in a fixed order (JSON.stringify preserves insertion order):
+ *    the manifest is built with `types`, `commonAttrs`, `defaultSubTypes`.
+ *    - Each attr: `name`, `valueType`, `isArray`, `required`, `description`,
+ *      then optional `rules`, `example`, `whenToUse` (each omitted when absent).
+ *    - Each type: `type`, `subType`, `description`, then optional `rules`,
+ *      `example`, `whenToUse` (omitted when absent), then `attrs`, `children`,
+ *      then optional `parents` (omitted when absent/empty).
+ *    - Each child (FR-033 constraint graph): `childType`, `childSubType`,
+ *      `childName`, then optional `min`, `max`, `named` (each emitted ONLY when
+ *      defined on the rule — legacy wildcard rules omit all three; `max: null`
+ *      is emitted when the rule sets it null, omitted when undefined).
+ *  - All arrays sorted: `types` by "type.subType"; each `attrs` by name;
+ *    each type's `children` by the tuple (childType, childSubTypeKey, childName)
+ *    where childSubTypeKey is the string or the comma-joined list; `parents`
+ *    ascending; `commonAttrs` by name; `defaultSubTypes` keys sorted.
+ *  - `valueType: null` literal for polymorphic/untyped attrs.
+ *  - `childSubType` is a string OR a string[] (a list of admitted subtypes).
+ *  - `description` is required + non-empty on every type and attr (gated by the
+ *    coverage assertion in registry-conformance.test.ts — mirrors ADR-0023).
+ *  - A single trailing newline (matches the repo's committed-canonical style).
+ */
+export function emitRegistryManifest(registry: TypeRegistry): string {
+  const manifest = buildRegistryManifest(registry);
+  return `${JSON.stringify(manifest, null, 2)}\n`;
+}

package/src/registry.ts

@@ -3,6 +3,7 @@ import { SUBTYPE_BASE, TYPE_ATTR } from "./shared/base-types.js";
 import { CHILD_RULE_WILDCARD } from "./shared/structural.js";
 import { type AttrSubType } from "./core/attr/attr-constants.js";
 import type { DataType } from "./data-type.js";
+import type { ReferenceDescriptor, NodeValidator } from "./validation-types.js";
 import { MetaModelError } from "./errors.js";
 
 export class TypeId {
@@ -23,10 +24,25 @@ export class TypeId {
 export interface ChildRule {
   /** `"*"` matches any type. */
   childType: string;
-  /** `"*"` matches any subtype. */
-  childSubType: string;
+  /**
+   * `"*"` matches any subtype. A list (FR-033) admits any one of several
+   * subtypes (e.g. a `source` child may be `["rdb", "view"]`).
+   */
+  childSubType: string | readonly string[];
   /** `"*"` matches any name. */
   childName: string;
+  /**
+   * FR-033 — cardinality lower bound. A required child has `min >= 1`. Optional
+   * on the interface for back-compat with rules authored before FR-033.
+   */
+  min?: number;
+  /**
+   * FR-033 — cardinality upper bound; `null` means unbounded (0..∞). Optional
+   * for back-compat.
+   */
+  max?: number | null;
+  /** FR-033 — whether the child must carry an explicit name. */
+  named?: boolean;
 }
 
 export interface AttrSchema {
@@ -45,6 +61,16 @@ export interface AttrSchema {
    * attrs. Attempting to register an AttrSchema with `valueType: "base"` throws.
    */
   valueType?: AttrSubType;
+  /**
+   * Whether this attribute is array-valued (a list of the scalar `valueType`).
+   *
+   * Array-ness is a single orthogonal axis — a `string` attr with `isArray: true`
+   * is what was formerly the `stringarray` subtype. The loader coerces an
+   * array-flagged attr through the array string-attr coercion (bare-string →
+   * one-element array). Mirrors Java's `StringAttribute + @isArray` model.
+   * Absent/false = scalar.
+   */
+  isArray?: boolean;
   /** Whether this attribute must be present on the node. */
   required: boolean;
   /** Default value applied when the attribute is absent. Optional. */
@@ -53,6 +79,12 @@ export interface AttrSchema {
   allowedValues?: readonly AttrValue[];
   /** Human/AI-facing description of what the attribute means. */
   description: string;
+  /** FR-033 — prose documenting the complex rules enforced in code. Optional. */
+  rules?: string;
+  /** FR-033 — an example value, shown only in the provider detail page. Optional. */
+  example?: string;
+  /** FR-033 — guidance on when to reach for this attribute. Optional. */
+  whenToUse?: string;
 }
 
 export interface TypeDefinition {
@@ -64,6 +96,33 @@ export interface TypeDefinition {
   /** The coarse value-type classification, for (type, subType)s whose nodes
    *  carry a typed value (field, attr). Absent for non-value-bearing types. */
   dataType?: DataType;
+  /**
+   * FR-033 — the child-side placement claim: the `type.subType`s under which a
+   * node of this type is allowed. Additive (an extension provider names a parent
+   * without editing the parent's definition). Optional.
+   */
+  parents?: readonly string[];
+  /** FR-033 — prose documenting the complex rules enforced in code. Optional. */
+  rules?: string;
+  /** FR-033 — an example, shown only in the provider detail page. Optional. */
+  example?: string;
+  /** FR-033 — guidance on when to reach for this type/subType. Optional. */
+  whenToUse?: string;
+  /** Max children of this type.subType per parent (`1` = singleton). Loader-enforced. */
+  maxOccurs?: number;
+  /** Default name for a singleton (`maxOccurs===1`) child declared with no name. */
+  defaultName?: string;
+  /**
+   * Cross-references this node's attrs declare — resolved generically against the symbol
+   * table (a dangling/kind-mismatched target fails the load). Carried by the type's
+   * registration, so a downstream provider's references validate with no core changes.
+   */
+  references?: ReferenceDescriptor[];
+  /**
+   * The type's imperative validator (logic config can't express). Invoked by the recursive
+   * validation walk. Owned by the provider that owns the type.
+   */
+  validate?: NodeValidator;
 }
 
 export class TypeRegistry {
@@ -79,7 +138,41 @@ export class TypeRegistry {
   /** Attrs accepted on every metatype (declared by providers). */
   private readonly _commonAttrs: AttrSchema[] = [];
 
+  /**
+   * ADR-0023 Decision 2 — sealed state. Once sealed, every mutating registration
+   * method (`register`/`setDefaultSubType`/`registerCommonAttrs`/`extend`) throws
+   * `ERR_REGISTRY_SEALED`. The library seals its composed registry after the agreed
+   * metamodel providers bootstrap, so nothing can register made-up metamodel
+   * attributes post-bootstrap. A downstream app composes its own (unsealed) registry.
+   */
+  private _sealed = false;
+
+  /** Seal the registry: every subsequent mutating registration throws
+   *  `ERR_REGISTRY_SEALED`. Idempotent. Reads are unaffected. */
+  seal(): void {
+    this._sealed = true;
+  }
+
+  /** Whether this registry has been sealed (ADR-0023). */
+  isSealed(): boolean {
+    return this._sealed;
+  }
+
+  /** Guard at the top of every mutating registration method. */
+  private checkNotSealed(operation: string): void {
+    if (this._sealed) {
+      throw new MetaModelError(
+        `TypeRegistry is sealed (ADR-0023): ${operation} is not permitted after metamodel ` +
+        `bootstrap. Made-up metamodel attributes/types are structurally disallowed — a new ` +
+        `metamodel attribute requires a registered provider + human agreement. Downstream apps ` +
+        `that need extra vocabulary must compose their own (unsealed) registry.`,
+        { code: "ERR_REGISTRY_SEALED" },
+      );
+    }
+  }
+
   register(def: TypeDefinition): void {
+    this.checkNotSealed(`register("${def.typeId.toString()}")`);
     const key = def.typeId.toString();
     if (this._defs.has(key)) {
       throw new Error(
@@ -129,6 +222,7 @@ export class TypeRegistry {
 
   /** Designate the default subType for a bare `type` key (used by YAML authoring sugar). */
   setDefaultSubType(type: string, subType: string): void {
+    this.checkNotSealed(`setDefaultSubType("${type}")`);
     this._defaultSubTypes.set(type, subType);
   }
 
@@ -150,6 +244,7 @@ export class TypeRegistry {
    * per-type attrs are resolved at validation time (Task 1.3).
    */
   registerCommonAttrs(attrs: AttrSchema[]): void {
+    this.checkNotSealed("registerCommonAttrs");
     for (const attr of attrs) {
       if (attr.valueType === SUBTYPE_BASE) {
         throw new Error(
@@ -182,6 +277,7 @@ export class TypeRegistry {
     subType: string,
     ext: { attributes?: AttrSchema[]; childRules?: ChildRule[] },
   ): void {
+    this.checkNotSealed(`extend("${type}.${subType}")`);
     const def = this.find(type, subType);
     if (def === undefined) {
       throw new Error(
@@ -213,9 +309,16 @@ export function childRuleMatches(
   rule: ChildRule,
   child: { type: string; subType: string; name: string },
 ): boolean {
+  // FR-033 — childSubType may be a wildcard, a single subtype, or a list of
+  // admitted subtypes.
+  const subTypeMatches =
+    rule.childSubType === CHILD_RULE_WILDCARD ||
+    (Array.isArray(rule.childSubType)
+      ? rule.childSubType.includes(child.subType)
+      : rule.childSubType === child.subType);
   return (
     (rule.childType === CHILD_RULE_WILDCARD || rule.childType === child.type) &&
-    (rule.childSubType === CHILD_RULE_WILDCARD || rule.childSubType === child.subType) &&
+    subTypeMatches &&
     (rule.childName === CHILD_RULE_WILDCARD || rule.childName === child.name)
   );
 }

package/src/shared/structural.ts

@@ -52,6 +52,14 @@ export const TYPE_SUBTYPE_SEPARATOR = ".";
 /** Separator between package segments and between package and name. */
 export const PACKAGE_SEPARATOR = "::";
 
+/**
+ * FR-024 (ADR-0029): separator between an owner object and a nested child in a
+ * dotted `extends` reference (`Customer.id`, `acme::sales::Customer.id`).
+ * Names cannot contain `.`, so a `.` in the final `::`-segment of a ref
+ * unambiguously marks a child-targeting reference.
+ */
+export const CHILD_REF_SEPARATOR = ".";
+
 /** Relative-reference "go up one level" marker. */
 export const PACKAGE_PARENT = "..";