@metaobjectsdev/metadata 0.24.0-rc.1 → 0.24.0

package/src/errors.ts

@@ -138,8 +138,9 @@ export const ERROR_CODES = [
   "ERR_PHYSICAL_NAME_KIND_MISMATCH",
   "ERR_PHYSICAL_NAME_MULTIPLE",
   // FR-013 — field-level @readOnly cross-attribute validation.
+  "ERR_MUTABILITY_AUTOSET_CONFLICT",
+  "ERR_MUTABILITY_DOWNGRADE",
   "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",
@@ -208,6 +209,18 @@ export const ERROR_CODES = [
   // an integer array. An array-of-enum stays string-backed: drop @intValueMap,
   // or make the field scalar.
   "ERR_ENUM_INT_VALUE_MAP_ARRAY",
+  // Phase-1 metadata-source-resolution — a path source declared in
+  // .metaobjects/config.json does not exist on disk.
+  "ERR_SOURCE_UNRESOLVED",
+  // Phase-1 metadata-source-resolution — a declared source kind (resource or
+  // package) is not supported by this toolchain.
+  "ERR_SOURCE_KIND_UNSUPPORTED",
+  // Phase-1 metadata-source-resolution — a scope include/exclude package
+  // pattern is malformed (empty pattern or empty :: segment).
+  "ERR_SCOPE_PATTERN_INVALID",
+  // Phase-1 metadata-source-resolution — no metadata collection was discovered:
+  // no config declaring sources, and no default metaobjects/ directory.
+  "ERR_COLLECTION_NOT_FOUND",
   "ERR_UNKNOWN",
 ] as const;
 
@@ -226,7 +239,8 @@ export const WARNING_CODES = [
   // 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",
+  "WARN_MUTABILITY_VALUE_OBJECT",
+  "WARN_MUTABILITY_READONLY_HOST",
   // #208 — a host object whose source carries @unmanaged also declares an
   // origin.*-bearing (derived) field. Deliberate asymmetry with
   // ERR_ORIGIN_UNDER_SQL_BODY: @unmanaged acts on nothing (the tool never

package/src/index.ts

@@ -27,6 +27,14 @@ export * from "./shared/base-types.js";
 export * from "./shared/structural.js";
 export * from "./core/object/object-constants.js";
 export * from "./core/field/field-constants.js";
+// FR-037 R1 — THE mutability accessors. Every consumer deciding "may this be
+// written, and when?" must go through these rather than reading the attr, so the
+// absent-means-readWrite default lives in exactly one place per port.
+export {
+  fieldMutability,
+  isReadOnlyMutability,
+  isWriteOnceMutability,
+} from "./core/field/validate-field-mutability.js";
 export * from "./core/attr/attr-constants.js";
 export * from "./core/documentation/doc-constants.js";
 export * from "./core/validator/validator-constants.js";
@@ -34,6 +42,13 @@ export * from "./core/identity/identity-constants.js";
 export * from "./core/index/index-constants.js";
 export * from "./core/requirement/requirement-constants.js";
 export { MetaRequirement } from "./core/requirement/meta-requirement.js";
+// Shared `@implementedBy` resolution — one resolver for the CLI's requirement
+// checks and codegen's requirement-test fan-out (FR-038).
+export {
+  resolveClaim,
+  resolveClaimTarget,
+  resolveMember,
+} from "./core/requirement/resolve-claim.js";
 export * from "./core/relationship/relationship-constants.js";
 export * from "./core/query/query-constants.js";
 export * from "./persistence/source/source-constants.js";
@@ -121,7 +136,6 @@ export {
   MetaOrigin,
   MetaPassthroughOrigin,
   MetaAggregateOrigin,
-  MetaCollectionOrigin,
   MetaComputedOrigin,
   MetaFirstOrigin,
 } from "./persistence/origin/meta-origin.js";
@@ -273,3 +287,17 @@ export {
   stripPackage,
 } from "./naming.js";
 export type { EntityNameMap, ColumnNamingStrategy } from "./naming.js";
+
+// Retired vocabulary: the map the loader reads to explain a retirement, and the raw-document
+// rewriter `meta upgrade` drives from the SAME entries — so the error message and the fix
+// cannot drift apart.
+export {
+  RETIRED_VOCABULARY,
+  retiredAttr,
+  retiredAttrValue,
+  retiredSubType,
+  retirementHint,
+} from "./retired-vocabulary.js";
+export type { RetirementNote, RetiredEntry, VocabularyRewrite } from "./retired-vocabulary.js";
+export { rewriteDocument } from "./vocabulary-rewrite.js";
+export type { RewriteResult, RewriteChange, RewriteRefusal, RewriteOpts } from "./vocabulary-rewrite.js";

package/src/library/library-sources.ts

@@ -51,6 +51,20 @@ function getLibraryDir(): string | undefined {
   return (_cache ??= { dir: libraryDirOnDisk() }).dir;
 }
 
+/**
+ * The library package names this build ships, sorted.
+ *
+ * `librarySources` skips an unrecognised package silently — the right behaviour for a
+ * programmatic caller asking for something a given version may not ship. A name a human
+ * typed into a config file is a different case: skipping it silently resurfaces later as
+ * `ERR_UNRESOLVED_SUPER` pointing at the adopter's own metadata, which is the wrong place
+ * to go looking. Config readers use this to refuse an unknown name and say what IS
+ * available (Python's `project_config` draws the same line, in the same place).
+ */
+export function knownLibraryPackages(): string[] {
+  return Object.keys(REFS_BY_PACKAGE).sort();
+}
+
 /**
  * Returns a list of `MetaDataSource` instances for the requested library packages.
  *

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

@@ -24,10 +24,10 @@ import { validateSourceRoles } from "../persistence/source/validate-source-roles
 import { validateSourceEscapes } from "../persistence/source/validate-source-escapes.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 { validateFieldMutability } from "../core/field/validate-field-mutability.js";
 import { validateEnumNormalizeAmbiguity } from "../core/field/validate-enum-normalize-ambiguity.js";
 import { validateDiscriminator } from "../core/object/validate-discriminator.js";
-import { resolveDeferredSupers } from "../super-resolve.js";
+import { resolveDeferredSupers, EXTENDS_TARGET_MISMATCH_RULE } from "../super-resolve.js";
 import { validateSubtypeRules } from "../subtype-rules.js";
 import { validateMaxOccurs } from "../validate-max-occurs.js";
 import { validateIdentityPassthrough } from "../core/identity/validate-identity-passthrough.js";
@@ -534,7 +534,7 @@ export class MetaDataLoader {
           const t = failure.target;
           errors.push(
             new ParseError(
-              `the extends target '${failure.ref}' is ${t?.type}.${t?.subType} but the extending node '${failure.nodeFqn}' is ${r?.type}.${r?.subType} — a dotted extends must target a node of the same type and subtype`,
+              `the extends target '${failure.ref}' is ${t?.type}.${t?.subType} but the extending node '${failure.nodeFqn}' is ${r?.type}.${r?.subType} — ${EXTENDS_TARGET_MISMATCH_RULE}`,
               {
                 code: "ERR_EXTENDS_TARGET_MISMATCH",
                 source: resolvedSource(failure.source, failure.nodeFqn, failure.ref),
@@ -650,12 +650,13 @@ export class MetaDataLoader {
       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-037 R1 — field-level @mutability cross-attribute rules
+      // (ERR_MUTABILITY_AUTOSET_CONFLICT / ERR_MUTABILITY_DOWNGRADE /
+      // ERR_READONLY_ASSIGNED_PRIMARY / WARN_MUTABILITY_VALUE_OBJECT /
+      // WARN_MUTABILITY_READONLY_HOST).
+      const mutabilityResult = validateFieldMutability(root);
+      errors.push(...mutabilityResult.errors);
+      envelopeWarnings.push(...mutabilityResult.warnings);
 
       // Authoring guard — a field.enum vocabulary that is ambiguous under the
       // default `@normalize: strip` (a member equal to the concatenation of

package/src/loader/validation-passes.ts

@@ -1109,8 +1109,8 @@ export function validateOriginPaths(root: MetaData): ParseError[] {
     for (const field of obj.ownChildren().filter((c) => c.type === TYPE_FIELD)) {
       for (const origin of field.ownChildren().filter((c) => c.type === TYPE_ORIGIN)) {
         // #210 — assembly origins live on projections. A value-hosted field may
-        // not carry origin.aggregate / origin.computed / origin.collection /
-        // origin.first: a value is constructed — by a caller or by embedding —
+        // not carry origin.aggregate / origin.computed / origin.first:
+        // a value is constructed — by a caller or by embedding —
         // never assembled from a backing store. origin.passthrough STAYS legal
         // on a value (FR-015 parameter lineage; the B5 exemption below).
         if (
@@ -1997,7 +1997,7 @@ function checkFilterClauses(
 //   - a plain (extends-bound / no-origin) or origin.passthrough or origin.computed
 //     field → addressable (a base/joined column, or an inlined row-level expression).
 //   - an aggregate-derived field (origin.aggregate — count/sum/…/any/all/collect —
-//     or origin.first / origin.collection) → NOT addressable: a WHERE runs before
+//     or origin.first) → NOT addressable: a WHERE runs before
 //     aggregation, so it cannot see an aggregate (post-aggregate filtering is HAVING,
 //     a separate later extension). Fail-closed → ERR_BAD_ATTR_FILTER.
 //   - a ref naming no declared field → dangling → ERR_BAD_ATTR_FILTER.

package/src/naming-refs.ts

@@ -37,7 +37,6 @@ import {
   ORIGIN_PASSTHROUGH_ATTR_VIA,
   ORIGIN_AGGREGATE_ATTR_OF,
   ORIGIN_AGGREGATE_ATTR_VIA,
-  ORIGIN_COLLECTION_ATTR_VIA,
 } from "./persistence/origin/origin-constants.js";
 import { SOURCE_ATTR_PARAMETER_REF } from "./persistence/source/source-constants.js";
 import { TEMPLATE_ATTR_PAYLOAD_REF, TEMPLATE_ATTR_RESPONSE_REF } from "./template/template-constants.js";
@@ -63,10 +62,9 @@ export const REF_BEARING_ATTR_NAMES: ReadonlySet<string> = new Set<string>([
   RELATIONSHIP_ATTR_THROUGH, // ADR-0042: the M:N junction ref joins the desugar+resolution set.
   IDENTITY_REFERENCE_ATTR_REFERENCES,
   ORIGIN_PASSTHROUGH_ATTR_FROM,
-  ORIGIN_PASSTHROUGH_ATTR_VIA, // = ORIGIN_AGGREGATE_ATTR_VIA = ORIGIN_COLLECTION_ATTR_VIA ("via")
+  ORIGIN_PASSTHROUGH_ATTR_VIA, // = ORIGIN_AGGREGATE_ATTR_VIA ("via")
   ORIGIN_AGGREGATE_ATTR_OF,
   ORIGIN_AGGREGATE_ATTR_VIA,
-  ORIGIN_COLLECTION_ATTR_VIA,
   SOURCE_ATTR_PARAMETER_REF,
   TEMPLATE_ATTR_PAYLOAD_REF,
   TEMPLATE_ATTR_RESPONSE_REF,

package/src/parser-core.ts

@@ -29,9 +29,16 @@ import { MetaRoot } from "./shared/meta-root.js";
 import { MetaAttr } from "./core/attr/meta-attr.js";
 import { canonicalSerialize, inferAttrSubType } from "./serializer-json.js";
 import { ParseError, type ErrorCode } from "./errors.js";
+// #337 — see retired-vocabulary.ts. Diagnostic only; no load outcome changes.
+import { retiredSubType, retirementHint } from "./retired-vocabulary.js";
 import { resolvedSource, type ErrorSource, type LoaderWarning, type Contributor } from "./source.js";
 import { semanticDiff } from "./semantic-diff.js";
-import { resolveSuperRef, isChildTargetingRef } from "./super-resolve.js";
+import {
+  resolveSuperRef,
+  isChildTargetingRef,
+  extendsTargetCompatible,
+  EXTENDS_TARGET_MISMATCH_RULE,
+} from "./super-resolve.js";
 import { JsonPathBuilder } from "./json-path.js";
 import { getYamlPosition, type YamlPosition } from "./core/yaml-positions.js";
 import {
@@ -422,8 +429,13 @@ export function buildTree(parsed: unknown, opts: ParseOptions): ParseResult {
       _currentPath!.pushKey(rootKey);
       const src = errSource();
       _currentPath!.pop();
+      // Same hint at the ROOT door. No retired subtype is root-legal today, so this arm
+      // is currently unreachable — wired anyway, because "fixed one door, left the
+      // other" is how a rule ends up half-true and passing every probe.
+      const retiredRoot = retiredSubType(rootType, rootSubType);
       throw new ParseError(
-        `Unknown root type "${rootType}.${rootSubType}" — not registered`,
+        `Unknown root type "${rootType}.${rootSubType}" — ` +
+          (retiredRoot !== undefined ? retirementHint(retiredRoot) : "not registered"),
         { code: rootTypeCode, source: src },
       );
     }
@@ -607,12 +619,18 @@ function parseNodeFresh(
       // FR-024 — a dotted child-targeting ref must resolve to a node of the
       // SAME type and subtype as the extending node. Dotted-only check; the
       // shipped top-level extends behavior is unchanged.
+      //
+      // The predicate is IMPORTED, not restated: this eager path and
+      // super-resolve's deferred path are two doors onto one rule, and they
+      // previously held independent copies of the boolean — so #310's relaxation
+      // applied to one would have left the other refusing, on whichever path a
+      // given loader configuration happens to take.
       if (
         isChildTargetingRef(model.superRef) &&
-        (superModel.type !== model.type || superModel.subType !== model.subType)
+        !extendsTargetCompatible(model, superModel)
       ) {
         throw new ParseError(
-          `the extends target '${model.superRef}' is ${superModel.type}.${superModel.subType} but the extending node '${model.fqn()}' is ${model.type}.${model.subType} — a dotted extends must target a node of the same type and subtype`,
+          `the extends target '${model.superRef}' is ${superModel.type}.${superModel.subType} but the extending node '${model.fqn()}' is ${model.type}.${model.subType} — ${EXTENDS_TARGET_MISMATCH_RULE}`,
           {
             code: "ERR_EXTENDS_TARGET_MISMATCH",
             source: resolvedSource(errSource(), model.fqn(), model.superRef),
@@ -1253,9 +1271,13 @@ function processChildren(
         const childTypeCode = explicit && registry.allSubTypesOf(childType).length > 0
           ? "ERR_UNKNOWN_SUBTYPE" as const
           : "ERR_UNKNOWN_TYPE" as const;
+        // #337: a subtype we RETIRED (origin.collection) gets its retirement and its
+        // migration, not a bare "not registered" that reads like a broken install.
+        const retiredChild = retiredSubType(childType, childSubType);
         errors.push(
           new ParseError(
-            `Unknown type "${childType}.${childSubType}" — not registered`,
+            `Unknown type "${childType}.${childSubType}" — ` +
+              (retiredChild !== undefined ? retirementHint(retiredChild) : "not registered"),
             { code: childTypeCode, source: errSource() },
           ),
         );

package/src/persistence/origin/meta-origin.ts

@@ -14,7 +14,6 @@ import {
   ORIGIN_AGGREGATE_ATTR_AGG,
   ORIGIN_AGGREGATE_ATTR_OF,
   ORIGIN_AGGREGATE_ATTR_VIA,
-  ORIGIN_COLLECTION_ATTR_VIA,
   ORIGIN_COMPUTED_ATTR_EXPR,
   ORIGIN_FIRST_ATTR_OF,
   ORIGIN_FIRST_ATTR_VIA,
@@ -77,21 +76,6 @@ export class MetaAggregateOrigin extends MetaOrigin {
   }
 }
 
-/**
- * Collection origin — the (array) field's value is a relationship-derived
- * array of nested view-objects (FR-004 R4). Carries `@via` (required): the
- * dotted relationship path the collection walks (e.g. "Author.posts"), or a
- * wildcard-prefixed selector for a package-spanning collection (e.g. "*.User").
- */
-export class MetaCollectionOrigin extends MetaOrigin {
-  /** The dotted relationship path (or wildcard selector) this collection is sourced from. */
-  get via(): string | undefined {
-    // ADR-0039: own — origin.* never inherits (ADR-0029), so own is correct.
-    const v = this.ownAttr(ORIGIN_COLLECTION_ATTR_VIA);
-    return typeof v === "string" ? v : undefined;
-  }
-}
-
 /**
  * Computed origin (#195) — a row-level value computed from the base entity's own
  * fields via a structured expression tree (`@expr`). No related rows, no `@via`.

package/src/persistence/origin/origin-constants.ts

@@ -13,7 +13,15 @@ import { SUBTYPE_BASE } from "../../shared/base-types.js";
 
 export const ORIGIN_SUBTYPE_PASSTHROUGH = "passthrough";
 export const ORIGIN_SUBTYPE_AGGREGATE   = "aggregate";
-export const ORIGIN_SUBTYPE_COLLECTION  = "collection";
+// FR-037 R2 — `collection` is RESERVED, NOT REGISTERED. It duplicated
+// `origin.aggregate @agg: collect` on a strictly smaller attr set (@via only —
+// no @filter, no @orderBy, no @distinct), and nothing dispatched on it: its last
+// real consumer, the payload-VO typing edge, was deleted in 0.20.16 (#270) for
+// being actively wrong. Re-entry bar (ADR-0007 Amendment 2): a member enters the
+// registry only when a shipping consumer dispatches on it. The designated
+// re-entry shape is `@agg: collect` with `@of` made OPTIONAL (absent = whole-
+// object rollup, typed by the field's declared @objectRef + isArray), NOT a
+// restored subtype.
 // #195 — computed: a row-level value from the base entity's own fields via a
 // structured @expr tree (no related rows). first: the single related row picked
 // by @orderBy along @via, projecting @of (argmax-then-project).
@@ -24,7 +32,6 @@ export const ORIGIN_SUBTYPES = [
   SUBTYPE_BASE,
   ORIGIN_SUBTYPE_PASSTHROUGH,
   ORIGIN_SUBTYPE_AGGREGATE,
-  ORIGIN_SUBTYPE_COLLECTION,
   ORIGIN_SUBTYPE_COMPUTED,
   ORIGIN_SUBTYPE_FIRST,
 ] as const;
@@ -38,7 +45,6 @@ export type OriginSubType = (typeof ORIGIN_SUBTYPES)[number];
 export const ASSEMBLY_ORIGIN_SUBTYPES = [
   ORIGIN_SUBTYPE_AGGREGATE,
   ORIGIN_SUBTYPE_COMPUTED,
-  ORIGIN_SUBTYPE_COLLECTION,
   ORIGIN_SUBTYPE_FIRST,
 ] as const;
 
@@ -50,11 +56,6 @@ export const ORIGIN_PASSTHROUGH_ATTR_VIA  = "via";
 // does NOT generate a cast; real type-converting projections are origin.computed (#195/#159).
 export const ORIGIN_PASSTHROUGH_ATTR_CONVERT = "convert";
 
-// collection attrs — a relationship-derived array of nested view-objects
-// (FR-004 R4). @via is the dotted relationship path (optionally wildcard-
-// prefixed, e.g. "*.User", for a package-spanning collection).
-export const ORIGIN_COLLECTION_ATTR_VIA = "via";
-
 // aggregate attrs
 export const ORIGIN_AGGREGATE_ATTR_AGG = "agg";
 export const ORIGIN_AGGREGATE_ATTR_OF  = "of";

package/src/persistence/origin/origin-definition.embedded.ts

@@ -114,22 +114,6 @@ export const ORIGIN_DEFINITION: ProviderDefinition = {
         }
       ]
     },
-    {
-      "type": "origin",
-      "subType": "collection",
-      "description": "A relationship-derived array of nested view-objects: walks @via to produce the collection (e.g. 'Author.posts'), or a wildcard selector for a package-spanning collection.",
-      "whenToUse": "A projection needs an array of nested child view-objects (a parent with its children inline). Declare it instead of hand-assembling the nested query + mapping.",
-      "children": [
-        {
-          "type": "attr",
-          "subType": "string",
-          "name": "via",
-          "min": 1,
-          "max": 1,
-          "description": "Dotted relationship path the collection walks to produce an array of nested view-objects (e.g. 'Author.posts'), or a wildcard selector for a package-spanning collection (e.g. '*.User')."
-        }
-      ]
-    },
     {
       "type": "origin",
       "subType": "computed",

package/src/registry-manifest.ts

@@ -103,11 +103,16 @@ interface ManifestType {
  * manifest (the byte-exact bill of materials), NOT a per-provider or per-file marker:
  * every port emits the same string, asserted by registry-conformance. Pre-1.0 the
  * vocabulary is still `0.x` (semver = unstable, may change) but largely settled going
- * into the quiet period, so this is `"0.9"` (near-final); the 1.0 cut (readiness G1)
- * freezes it to `"1.0"`. Decoupled from every package line — it is the spec version,
- * not a package version.
+ * into the quiet period; the 1.0 cut (readiness G1) freezes it to `"1.0"`. Decoupled
+ * from every package line — it is the spec version, not a package version.
+ *
+ * The current value is the declaration below and nothing else. Do not restate it in
+ * prose: `scripts/check-metamodel-version.mjs --set` rewrites the declaration, so any
+ * copy in a comment goes stale on the very next bump (it said `"0.9"` here while the
+ * constant read `"0.10"`). Bump with that script — never by hand — so the manifest and
+ * all four port constants move together.
  */
-export const METAMODEL_VERSION = "0.9";
+export const METAMODEL_VERSION = "0.10";
 
 /** The full canonical manifest. All collections are sorted for byte-stability. */
 interface RegistryManifest {