@metaobjectsdev/metadata 0.24.5 → 1.0.0-rc.1

package/src/retired-vocabulary.ts

@@ -1,6 +1,7 @@
 // server/typescript/packages/metadata/src/retired-vocabulary.ts
 //
-// Vocabulary this project USED to register, and what to do instead.
+// Vocabulary this project USED to register — or used to READ and document without ever
+// registering — and what to do instead.
 //
 // WHY THIS EXISTS (#337). Under ADR-0023 the registry is strict and sealed, so retired
 // vocabulary fails the load — correctly. But the message it failed with said the attribute
@@ -45,6 +46,15 @@ export interface RetirementNote {
   readonly replacedBy?: string;
   /** Repo-relative migration guide. */
   readonly migration?: string;
+  /**
+   * True when `meta upgrade --apply` can make this edit itself.
+   *
+   * Carried on the NOTE, not just the entry, because the diagnostic is the only place an
+   * adopter meets a retirement — and the difference between "run one command" and "this is
+   * a judgement call" is the single most useful thing to tell them at that moment. Absent
+   * ⇒ the human decides (see `VocabularyRewrite`).
+   */
+  readonly automated?: boolean;
 }
 
 /**
@@ -97,6 +107,7 @@ export interface RetiredEntry extends RetirementNote {
 
 const REQUIREMENT_MIGRATION = "docs/features/migrations/verified-by-retirement.md";
 const RETIRED_STATUS_MIGRATION = "docs/features/migrations/retired-status-restore.md";
+const EMIT_ATTR_MIGRATION = "docs/features/migrations/emit-attrs-to-generator-config.md";
 
 export const RETIRED_VOCABULARY: readonly RetiredEntry[] = [
   // ── 0.24.0: `@violation` is renamed `@counterexample` ──
@@ -244,8 +255,80 @@ export const RETIRED_VOCABULARY: readonly RetiredEntry[] = [
     // caught this exists to prevent.
     rewrite: { kind: "dropAttr" },
   },
+  // ── FR-040: the @emit* family leaves the model (0.25.0) ──
+  //
+  // Five attributes — @emitRoutes, @emitTanstack, @emitForm, @emitGrid, @emitAngular — were
+  // READ by the TypeScript generators as per-entity kill switches, and documented as THE way
+  // to suppress an artifact, but they were never REGISTERED by any provider. So they worked
+  // under `meta gen`, which loads open, and failed `meta verify`, which loads strict: a
+  // mechanism we documented broke the drift gate we documented beside it.
+  //
+  // They are retired rather than registered. codegen-ts's own constants file already called
+  // them "NOT metamodel vocabulary — they tune codegen, not the model" and then read them off
+  // metadata anyway; that contradiction is the defect, and ADR-0023 §2 names the class.
+  // Registering them instead would move `metamodelVersion` and oblige four other ports to
+  // carry a TypeScript-only generator flag none of them will ever read.
+  //
+  // WHAT REPLACED THEM IS CONFIGURATION, NOT VOCABULARY, so `replacedBy` names a mechanism
+  // rather than an attribute — the only entries here that do. The rule is one sentence:
+  // decide per generator what you consume, wire only the generators whose output you import,
+  // and narrow one with its own `filter`.
+  //
+  // `dropAttr` is safe for all five: after this release nothing reads them, so removing one
+  // cannot change what is emitted. What it DOES change is what `meta gen` emitted BEFORE —
+  // an adopter who suppressed an artifact this way now gets that artifact — which is why the
+  // run also warns by name, rather than letting the file appear with no explanation.
+  {
+    type: "object", subType: "*", attr: "emitRoutes",
+    since: "0.25.0",
+    why: "it was never registered vocabulary, so the opt-out we documented passed `meta gen` " +
+         "and failed `meta verify`",
+    replacedBy: "the routes generator's own `filter` — routesFile({ filter: (e) => … })",
+    migration: EMIT_ATTR_MIGRATION,
+    rewrite: { kind: "dropAttr" },
+  },
+  {
+    type: "object", subType: "*", attr: "emitTanstack",
+    since: "0.25.0",
+    why: "it was never registered vocabulary, so the opt-out we documented passed `meta gen` " +
+         "and failed `meta verify`",
+    replacedBy: "the `filter` option on tanstackQuery() / tanstackGrid() / tanstackGridHook()",
+    migration: EMIT_ATTR_MIGRATION,
+    rewrite: { kind: "dropAttr" },
+  },
+  {
+    type: "object", subType: "*", attr: "emitForm",
+    since: "0.25.0",
+    why: "it was never registered vocabulary, and its own doc comment described it backwards " +
+         "— as opt-IN via `true`, while the code implemented opt-OUT via `false`",
+    replacedBy: "formFile({ filter: (e) => … })",
+    migration: EMIT_ATTR_MIGRATION,
+    rewrite: { kind: "dropAttr" },
+  },
+  {
+    type: "object", subType: "*", attr: "emitAngular",
+    since: "0.25.0",
+    why: "it was never registered vocabulary, and unlike its four siblings it was not even a " +
+         "named constant — just a bare string literal in four generators",
+    replacedBy: "the `filter` option on the Angular generators",
+    migration: EMIT_ATTR_MIGRATION,
+    rewrite: { kind: "dropAttr" },
+  },
+  {
+    // The one that is opt-IN rather than opt-out, so `filter` cannot replace it: a filter is
+    // ANDed with the built-in gates and can only ever narrow. It became a generator OPTION,
+    // which must be passed to BOTH grid generators — they emit a matched pair of files.
+    type: "object", subType: "*", attr: "emitGrid",
+    since: "0.25.0",
+    why: "it was never registered vocabulary, and being an opt-IN it could not be expressed " +
+         "by a generator filter, which only ever narrows",
+    replacedBy: "the `tphSubtypeGrids` option on BOTH tanstackGrid() and tanstackGridHook()",
+    migration: EMIT_ATTR_MIGRATION,
+    rewrite: { kind: "dropAttr" },
+  },
 ];
 
+
 /**
  * True when `entry` governs `typeKey` (`"<type>.<subType>"`).
  *
@@ -267,6 +350,7 @@ export function note(entry: RetiredEntry): RetirementNote {
     why: entry.why,
     ...(entry.replacedBy !== undefined ? { replacedBy: entry.replacedBy } : {}),
     ...(entry.migration !== undefined ? { migration: entry.migration } : {}),
+    ...(entry.rewrite !== undefined ? { automated: true } : {}),
   };
 }
 
@@ -321,3 +405,25 @@ export function retirementHint(n: RetirementNote): string {
   if (n.migration !== undefined) parts.push(`Migration: ${n.migration}`);
   return `${parts.join(". ")}.`;
 }
+
+/**
+ * The ADR-0009 `suggestions[]` for a retirement: what to DO, as distinct from
+ * `retirementHint`, which says what happened.
+ *
+ * WHY THIS EXISTS. A caller that knows only "the load failed with ERR_UNKNOWN_ATTR" gives
+ * the generic three exits — register the attr, stash it in an `attr.properties` bag, or
+ * re-run with `--lax`. For a TYPO that is exactly right. For a RETIREMENT the middle one is
+ * actively harmful: the properties bag is exempt from the strict-attr check, so it loads,
+ * and the value then sits there reaching nothing. The adopter gets a green `meta verify`
+ * over metadata that no longer means what they wrote — a loud, correct failure converted
+ * into a quiet, wrong pass. So a retirement supplies its own exits and the caller prints
+ * those instead of guessing.
+ */
+export function retirementSuggestions(n: RetirementNote): string[] {
+  const out: string[] = [];
+  if (n.automated === true) out.push("Run `meta upgrade --apply` to make this edit for you.");
+  if (n.replacedBy !== undefined) out.push(`Use ${n.replacedBy} instead.`);
+  if (n.migration !== undefined) out.push(`Migration guide: ${n.migration}`);
+  // Never the `attr.properties` bag: it would load, and mean nothing. See above.
+  return out;
+}

package/src/shared/meta-data.ts

@@ -497,14 +497,34 @@ export abstract class MetaData {
     // Track which of our own children matched (overrode) a super child position.
     const appendQueue: MetaData[] = [];
 
+    // Indices already taken by an own child in THIS pass. Without it, an own child
+    // written into `result[idx]` stays visible to the next own sibling's scan, so a
+    // second own child sharing the same (type, name) matches its own sibling and
+    // overwrites it. `extends` decides what a child overrides; a sibling is not a super.
+    // The append queue already closed the other branch — a non-shadowing own child is
+    // deferred so it cannot be matched later — and this closes the branch it left open.
+    //
+    // The shape is a write-through entity (two unnamed `source.rdb` children, primary +
+    // replica) whose base ALSO declares a source: the entity's own primary was silently
+    // dropped, and `primaryRdbSource` reads `children()`.
+    // A flag array, not a Set: `result` does not grow until after this loop, so the length
+    // is known, and this is the memoized effective-children path walked for every node.
+    // One small allocation, index access instead of hashing, and no per-child closure.
+    const claimed = new Uint8Array(result.length);
     for (const ownChild of this._children) {
       // Find the index in result that has the same (type, name).
-      const idx = result.findIndex(
-        (sc) => sc.type === ownChild.type && sc.name === ownChild.name,
-      );
+      let idx = -1;
+      for (let i = 0; i < result.length; i++) {
+        const sc = result[i] as MetaData;
+        if (claimed[i] === 0 && sc.type === ownChild.type && sc.name === ownChild.name) {
+          idx = i;
+          break;
+        }
+      }
       if (idx !== -1) {
         // Replace the super child with our own (in-place override).
         result[idx] = ownChild;
+        claimed[idx] = 1;
       } else {
         // No matching super child — will be appended at the end.
         appendQueue.push(ownChild);

package/src/template/template-definition.embedded.ts

@@ -12,7 +12,7 @@ export const TEMPLATE_DEFINITION: ProviderDefinition = {
     {
       "type": "template",
       "subType": "base",
-      "description": "Abstract base template — the shared root subtype for the fourth pillar (FR-004, ADR-0011). A template is a typed payload bound to either a rendered text artifact (prompt/output) or a tool-call envelope. The base carries no attrs of its own; concrete subtypes add their reference + governance attrs.",
+      "description": "Abstract base template — the shared root subtype for the fourth pillar (FR-004, ADR-0011). A template is a typed payload bound to either a rendered text artifact (prompt/output) or a tool-call envelope. The base carries no attrs of its own; concrete subtypes add their reference + governance attrs. Not authored directly: a `template.base` node fails to load (ERR_ABSTRACT_SUBTYPE_AUTHORED) — this subtype is a registry anchor concrete subtypes inherit from, never a node in a document.",
       "rules": "A single MetaTemplate node class backs every template subtype (no subType→class dispatch); the subtype selects which reserved-attr set applies. @format (a closed-enum ATTRIBUTE, never a subtype) drives the render engine's escaper/whitespace behavior, so a new format costs one escaper + one enum value rather than a new subtype + cross-language port."
     },
     {

package/src/vocabulary-catalog.ts

@@ -0,0 +1,133 @@
+// #357 — "what can I author HERE?", which is NOT the question the registry manifest answers.
+//
+// `buildRegistryManifest` answers "what must all five ports byte-match?" and deliberately
+// carves rows OUT of its answer: the `metadata.base` inheritance anchor, and the 13
+// TS-web-presentation `view.*` controls, which stay REGISTERED in TypeScript (the loader
+// must accept an authored `view.dropdown`) but are deregistered in C# and Python and
+// excluded from the shared canonical everywhere. That carve-out is correct and documented
+// (fixtures/registry-conformance/README.md, B-2).
+//
+// `meta types` — the vocabulary search the generated `AGENTS.md` and the
+// `metaobjects-authoring` skill both make STEP 1 of the authoring procedure — was built on
+// that same function, so the answer it gave an author was the cross-port contract with
+// this port's own vocabulary removed: 2 of the 15 registered `view.*` subtypes, with the
+// other 13 reported exactly as a genuine typo is. Following the documented procedure, an
+// author correctly concluded `view.text` does not exist.
+//
+// One function cannot answer both questions, so there are two. This one enumerates every
+// (type, subType) the registry accepts and MARKS the rows the cross-port manifest omits,
+// which is the honest way to surface what the carve-out means: not "missing" but
+// "TypeScript-only".
+
+import type { TypeDefinition, TypeRegistry } from "./registry.js";
+import {
+  type ManifestAttr,
+  type ManifestChild,
+  classifyPerTypeAttr,
+  INCLUDED,
+  compareStrings,
+  sortedAttrs,
+  sortedChildren,
+  METAMODEL_VERSION,
+} from "./registry-manifest.js";
+import { classifyTypeSubType } from "./registry-manifest-exclusions.js";
+import { SUBTYPE_BASE } from "./shared/base-types.js";
+
+/** One registered (type, subType), as an AUTHOR sees it. */
+export interface VocabularyType {
+  type: string;
+  subType: string;
+  description: string;
+  rules?: string;
+  example?: string;
+  whenToUse?: string;
+  attrs: ManifestAttr[];
+  children: ManifestChild[];
+  parents?: string[];
+  /**
+   * False when the cross-port manifest carves this row out — vocabulary THIS port
+   * accepts that the shared five-port contract does not carry. An author can use it
+   * here; a sibling port may not have it.
+   */
+  crossPort: boolean;
+  /** Why it is not cross-port (the carve-out's declared category). Absent when it is. */
+  portPrivateReason?: string;
+  /**
+   * True for a type's shared ROOT subtype (`<type>.base`). Attrs and child rules
+   * registered there apply to every subtype of the type (see constraint-merge.ts), so a
+   * `base` row is a summary of the whole family rather than a control an author picks.
+   * Deliberately NOT called "abstract": nothing in the registry records abstractness, and
+   * some `base` rows (`attr.base`) are the authorable polymorphic form.
+   */
+  sharedRoot: boolean;
+}
+
+/** Every (type, subType) the registry accepts, plus what every node accepts. */
+export interface VocabularyCatalog {
+  metamodelVersion: string;
+  types: VocabularyType[];
+  /** Attrs accepted on EVERY node, whatever its type (`@title`, `@description`, …). */
+  commonAttrs: ManifestAttr[];
+  defaultSubTypes: Record<string, string>;
+}
+
+function toVocabularyType(def: TypeDefinition): VocabularyType {
+  const { type, subType } = def.typeId;
+  const reason = classifyTypeSubType(type, subType);
+  const out: VocabularyType = {
+    type,
+    subType,
+    description: def.description,
+    ...(def.rules !== undefined ? { rules: def.rules } : {}),
+    ...(def.example !== undefined ? { example: def.example } : {}),
+    ...(def.whenToUse !== undefined ? { whenToUse: def.whenToUse } : {}),
+    // Same attr filter the manifest applies — the carved-out per-type attr names are
+    // bare structural keywords (`isArray`, `extends`) that `@`-prefix to ERR_RESERVED_ATTR,
+    // OO-port native bindings, and the `description` commonAttr re-registered per type.
+    // Listing any of them here would teach metadata the loader rejects. The manifest's
+    // FR-024 requiredness override is deliberately NOT applied: that freezes the
+    // CROSS-PORT value during a reference-first rollout, and this answer is about what
+    // THIS registry requires of an author right now.
+    attrs: sortedAttrs(def.attributes.filter((a) => classifyPerTypeAttr(a.name) === INCLUDED)),
+    children: sortedChildren(def.childRules),
+    crossPort: reason === undefined,
+    ...(reason !== undefined ? { portPrivateReason: reason } : {}),
+    sharedRoot: subType === SUBTYPE_BASE,
+  };
+  if (def.parents !== undefined && def.parents.length > 0) {
+    out.parents = [...def.parents].sort(compareStrings);
+  }
+  return out;
+}
+
+/**
+ * Build the authoring-facing vocabulary catalog from an assembled registry.
+ *
+ * The registry must be COMPOSED (`composeRegistry(coreProviders)`), not merely
+ * `registerCoreTypes`'d: the db, ui-web and documentation providers each register attrs
+ * onto types the core provider declares, so a partially-composed registry reports a type
+ * that exists with most of its attributes missing — `field.string` with 6 attrs instead of
+ * 16, and no commonAttrs at all.
+ */
+export function buildVocabularyCatalog(registry: TypeRegistry): VocabularyCatalog {
+  const types = registry
+    .allTypes()
+    .map((typeId) => toVocabularyType(registry.find(typeId.type, typeId.subType) as TypeDefinition))
+    .sort((a, b) =>
+      compareStrings(`${a.type}.${a.subType}`, `${b.type}.${b.subType}`),
+    );
+
+  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 {
+    metamodelVersion: METAMODEL_VERSION,
+    types,
+    commonAttrs: sortedAttrs(registry.getCommonAttrs()),
+    defaultSubTypes,
+  };
+}