fix(cli): meta types under-reported the registry it is the search for (#357)

`meta types` is the vocabulary search the generated AGENTS.md and the
metaobjects-authoring skill both make step 1 of the authoring procedure, on the
reasoning that you must search the vocabulary before concluding something cannot
be expressed. It gave confidently wrong answers, for two independent reasons.

It read the cross-port manifest. buildRegistryManifest answers "what must all five
ports byte-match?" and deliberately carves out the 13 TS-web-presentation view.*
controls (B-2), which stay REGISTERED in TypeScript. Asked "what can I author
here?", it reported 2 of the 15 registered view.* subtypes, and the other 13 came
back exactly as a genuine typo does.

And it composed a partial registry -- registerCoreTypes alone, which core-types.ts
itself documents as a legacy wrapper to be preferred against. Every attr the db,
ui-web and documentation providers register was invisible: field.string reported 6
attrs instead of 16 (no @column, @filterable, @Sortable, @dbColumnType),
view.textarea none at all (no @rows), and the eight documentation common attrs were
absent entirely -- so `meta types title` found nothing, for the very attr an author
is meant to find INSTEAD of asking for a new one. That omission is how #353 became
a request to register @Label when @title already existed: the tool that would have
prevented it under-reported the attribute involved.

The command now composes the same provider set the loader does, and reads a new
buildVocabularyCatalog -- the authoring-facing twin of the manifest, built from the
same row rules -- which enumerates every registered (type, subType) and MARKS the
cross-port carve-outs [ts-only] rather than dropping them. That is the honest way
to surface what the carve-out means: not "missing", but "TypeScript-only". A type's
shared root is marked [base] so a listing cannot be mistaken for the concrete
vocabulary; it is deliberately not called "abstract", since nothing in the registry
records abstractness and some base rows (attr.base) are the authorable polymorphic
form. Common attrs are searchable and no --type scope hides them, since they are
accepted on every node.

Reserved structural keys (isArray, extends) stay unlisted: @-prefixing one is
ERR_RESERVED_ATTR, so offering them would teach metadata the loader rejects. An
unregistered subtype still reports as missing -- the fix must not make the tool
answer "yes" to everything.

TypeScript-only, and deliberately so. The B-2 exclusion is correct and documented;
adding those rows to expected-registry.json would break the C#/Python
deregistration and force a cross-port change for a bug whose cause was a CLI
command asking the wrong source. expected-registry.json and metamodelVersion are
untouched, and registry-conformance is unchanged. Both halves of the fix were
proven by reverting each in turn: the carve-out reinstated fails 6 of the 10 new
tests, the partial composition fails 4.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HSCgs7z19w8aGXGiceCohC

Author: dmealing

CHANGELOG.md

@@ -48,6 +48,45 @@ same `[0]` and, though source-only (ADR-0048), builds in-repo and would have dri
 grid tier it is modelled on. No generated output in this repo changes: not one model here
 declares two views on a field, which is also why nothing caught this.
 
+### Fixed — `meta types` under-reported the registry it is the search for (#357)
+
+`meta types` is the vocabulary search the generated `.metaobjects/AGENTS.md` and the
+`metaobjects-authoring` skill both make **step 1** of the authoring procedure, on the reasoning
+that you must search the vocabulary before concluding something cannot be expressed. It gave
+confidently wrong answers, for two independent reasons:
+
+1. **It read the cross-port manifest.** `buildRegistryManifest` answers *"what must all five
+   ports byte-match?"* and deliberately carves out the 13 TS-web-presentation `view.*` controls
+   (B-2), which stay REGISTERED in TypeScript. Asked *"what can I author here?"*, it therefore
+   reported **2 of the 15** registered `view.*` subtypes, and the other 13 came back exactly as
+   a genuine typo does: `meta types view.text` → *"No vocabulary matches"*.
+2. **It composed a partial registry** — `registerCoreTypes` alone, which `core-types.ts` itself
+   documents as a legacy wrapper to be preferred against. Every attr the db, ui-web and
+   documentation providers register was invisible: `field.string` reported **6** attrs instead
+   of 16 (no `@column`, `@filterable`, `@sortable`, `@dbColumnType`), `view.textarea` none at
+   all (no `@rows`), and the eight documentation common attrs were absent entirely — so
+   **`meta types title` found nothing**, for the very attr an author is meant to find instead
+   of asking for a new one. That omission is exactly how #353 became a request to register
+   `@label` when `@title` already existed: the tool that would have prevented it under-reported
+   the attribute involved.
+
+The command now composes the same provider set the loader does, and reads a new
+`buildVocabularyCatalog` — the authoring-facing twin of the manifest, built from the same row
+rules — which enumerates every registered `(type, subType)` and **marks** the cross-port
+carve-outs `[ts-only]` rather than dropping them, which is the honest way to surface what the
+carve-out means: not "missing", but "TypeScript-only". A type's shared root (`<type>.base`) is
+marked `[base]`, so a listing cannot be mistaken for the concrete vocabulary. Common attrs are
+searchable and no `--type` scope hides them, since they are accepted on every node.
+
+Reserved structural keys (`isArray`, `extends`) stay unlisted: `@`-prefixing one is
+`ERR_RESERVED_ATTR`, so offering them would teach metadata the loader rejects. An unregistered
+subtype still reports as missing — the fix must not make the tool answer "yes" to everything.
+
+**TypeScript-only, and deliberately so.** The B-2 exclusion is correct and documented; adding
+those rows to `expected-registry.json` would break the C#/Python deregistration and force a
+cross-port change for a bug whose cause was a CLI command asking the wrong source.
+`expected-registry.json` and `metamodelVersion` are untouched.
+
 ### Fixed — `verify --codegen` convicted the output `gen` had just written (C#, Python)
 
 The declarative Mustache template-spec was wired into `gen` and nowhere else, so the drift

server/typescript/packages/cli/src/commands/types.ts

@@ -2,12 +2,8 @@
 // without loading it all into context. apropos + `kubectl explain` over the live
 // registry, tuned for an agent's token budget: terse names-first default, opt-in
 // description search, drill-in `--detail`, machine-readable `--json`.
-import {
-  TypeRegistry,
-  registerCoreTypes,
-  buildRegistryManifest,
-} from "@metaobjectsdev/metadata";
-import { registerForgeTypes } from "@metaobjectsdev/sdk";
+import { composeRegistry, coreProviders, buildVocabularyCatalog } from "@metaobjectsdev/metadata";
+import { forgeTypesProvider } from "@metaobjectsdev/sdk";
 import { log } from "../lib/log.js";
 
 interface TypesFlags {
@@ -78,7 +74,24 @@ interface Entry {
   description: string;
   whenToUse: string | undefined;
   attrNames: string[]; // attr-name hints (for subtype terse lines)
-  raw: unknown; // the manifest node, for --json
+  /** Accepted on EVERY node, so no `--type` scope excludes it (#357). */
+  common: boolean;
+  /** Registered here but carved out of the cross-port manifest — TS-only vocabulary. */
+  tsOnly: boolean;
+  /** A type's shared root (`<type>.base`): its attrs apply to every subtype. */
+  sharedRoot: boolean;
+  raw: unknown; // the catalog node, for --json
+}
+
+/** Compact markers appended to a terse line, and the legend that explains them. */
+const MARK_TS_ONLY = "[ts-only]";
+const MARK_BASE = "[base]";
+const LEGEND = `  ${MARK_BASE}     the type's shared root — its @attrs apply to every subtype of that type\n` +
+  `  ${MARK_TS_ONLY}  registered in TypeScript only; the cross-port metamodel contract does not carry it`;
+
+function marks(e: Entry): string {
+  const m = [e.sharedRoot ? MARK_BASE : "", e.tsOnly ? MARK_TS_ONLY : ""].filter(Boolean);
+  return m.length > 0 ? `  ${m.join(" ")}` : "";
 }
 
 export async function typesCommand(args: string[]): Promise<number> {
@@ -94,35 +107,55 @@ export async function typesCommand(args: string[]): Promise<number> {
     return 0;
   }
 
-  const registry = new TypeRegistry();
-  registerCoreTypes(registry);
-  registerForgeTypes(registry);
-  const manifest = buildRegistryManifest(registry);
-
-  // Flatten the manifest into searchable entries.
+  // #357 — COMPOSE the registry, never `registerCoreTypes` alone. The db, ui-web and
+  // documentation providers 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` came back with 6 attrs instead of 16 (no @column, @filterable,
+  // @sortable, @dbColumnType), `view.textarea` with none (no @rows), and the eight
+  // documentation commonAttrs — @title among them — were absent entirely. This is the same
+  // provider set the loader composes, so what this prints is what the loader accepts.
+  const registry = composeRegistry([...coreProviders, forgeTypesProvider], { validate: true });
+  const catalog = buildVocabularyCatalog(registry);
+
+  // Flatten the catalog into searchable entries.
   const entries: Entry[] = [];
-  for (const mt of manifest.types) {
+  for (const mt of catalog.types) {
     const tsName = `${mt.type}.${mt.subType}`;
     entries.push({
       kind: "subtype", name: tsName, owner: tsName, type: mt.type,
       description: mt.description, whenToUse: mt.whenToUse,
-      attrNames: mt.attrs.map((a) => `@${a.name}`), raw: mt,
+      attrNames: mt.attrs.map((a) => `@${a.name}`),
+      common: false, tsOnly: !mt.crossPort, sharedRoot: mt.sharedRoot, raw: mt,
     });
     for (const at of mt.attrs) {
       entries.push({
         kind: "attr", name: `${tsName} @${at.name}`, owner: tsName, type: mt.type,
-        description: at.description, whenToUse: at.whenToUse, attrNames: [], raw: at,
+        description: at.description, whenToUse: at.whenToUse, attrNames: [],
+        common: false, tsOnly: !mt.crossPort, sharedRoot: false, raw: at,
       });
     }
   }
+  // #357 — the attrs every node accepts. These were absent from the search entirely, so
+  // `meta types title` reported nothing for `@title` — the registered attr an author is
+  // supposed to find INSTEAD of asking for a new one (that omission is exactly how #353
+  // became a request to register `@label`). They belong to no single type, so no `--type`
+  // scope excludes them.
+  for (const at of catalog.commonAttrs) {
+    entries.push({
+      kind: "attr", name: `@${at.name}`, owner: "(any node)", type: "",
+      description: at.description, whenToUse: at.whenToUse, attrNames: [],
+      common: true, tsOnly: false, sharedRoot: false, raw: at,
+    });
+  }
 
   const q = (f.query ?? "").toLowerCase();
   const wantKind = (e: Entry) => f.kind.size === 0
     ? true
     : (f.kind.has("attr") && e.kind === "attr") ||
       ((f.kind.has("subtype") || f.kind.has("type")) && e.kind === "subtype");
   const matches = entries.filter((e) => {
-    if (f.type && e.type !== f.type) return false;
+    // A common attr is accepted on every type, so `--type field` must not hide it.
+    if (f.type && e.type !== f.type && !e.common) return false;
     if (!wantKind(e)) return false;
     if (!q) return true;
     if (e.name.toLowerCase().includes(q)) return true;
@@ -149,9 +182,12 @@ export async function typesCommand(args: string[]): Promise<number> {
 
   if (f.detail) {
     for (const e of shown) {
-      const head = e.kind === "subtype" ? e.name : e.name;
-      log.info(`\n${head}  (${e.kind})`);
+      log.info(`\n${e.name}  (${e.kind})`);
       if (e.description) log.info(`  ${e.description}`);
+      if (e.sharedRoot)
+        log.info(`  shared root: @attrs registered here apply to every ${e.type}.* subtype.`);
+      if (e.tsOnly)
+        log.info("  TypeScript-only: registered here, but not part of the cross-port metamodel contract.");
       if (e.whenToUse) log.info(`  → reach for it when: ${e.whenToUse}`);
       if (e.kind === "subtype") {
         const mt = e.raw as { attrs: { name: string; valueType: string | null; required: boolean; description: string }[] };
@@ -167,12 +203,13 @@ export async function typesCommand(args: string[]): Promise<number> {
     for (const e of shown) {
       if (e.kind === "subtype") {
         const hint = e.attrNames.length ? `  (${e.attrNames.slice(0, 6).join(", ")}${e.attrNames.length > 6 ? ", …" : ""})` : "";
-        log.info(`${e.name.padEnd(28)} ${oneLine(e.description)}${hint}`);
+        log.info(`${e.name.padEnd(28)} ${oneLine(e.description)}${hint}${marks(e)}`);
       } else {
-        log.info(`${e.name.padEnd(28)} ${oneLine(e.description)}`);
+        log.info(`${e.name.padEnd(28)} ${oneLine(e.description)}${marks(e)}`);
       }
     }
   }
+  if (!f.noHeaders && !f.detail && shown.some((e) => marks(e) !== "")) log.info(`\n${LEGEND}`);
   if (!f.noHeaders && shown.length < total)
     log.info(`\n${shown.length} of ${total} shown — narrow with QUERY/--type/--kind or raise --limit.`);
   else if (!f.noHeaders)

server/typescript/packages/cli/test/types-command.test.ts

@@ -0,0 +1,106 @@
+// #357 — `meta types` is the vocabulary search the generated `.metaobjects/AGENTS.md` and
+// the `metaobjects-authoring` skill both make STEP 1 of the authoring procedure, on the
+// reasoning that you must search the vocabulary before concluding something cannot be
+// expressed. It under-reported the registry two ways at once, so following the documented
+// procedure produced a confidently wrong answer:
+//
+//   1. It read `buildRegistryManifest`, whose job is the byte-gated FIVE-PORT contract.
+//      That deliberately carves out the 13 TS-web-presentation `view.*` controls (B-2),
+//      which stay REGISTERED in TypeScript. So 9 of 10 authorable view subtypes reported
+//      exactly as a genuine typo does: `meta types view.text` → "No vocabulary matches".
+//   2. It composed the registry with `registerCoreTypes` alone rather than
+//      `composeRegistry(coreProviders)`, so every attr the db / ui-web / documentation
+//      providers register was invisible — `field.string` with 6 attrs instead of 16, and
+//      NO commonAttrs at all, which is why `meta types title` found nothing for the very
+//      attr #353 should have been answered with.
+//
+// These assert the tool's ANSWER, not its internals: each is a question an author asks.
+
+import { describe, test, expect, spyOn } from "bun:test";
+import { typesCommand } from "../src/commands/types.js";
+
+/** Run `meta types ...` and return everything it printed to stdout. */
+async function run(args: string[]): Promise<string> {
+  const lines: string[] = [];
+  const spy = spyOn(console, "log").mockImplementation((...a: unknown[]) => {
+    lines.push(a.map(String).join(" "));
+  });
+  try {
+    expect(await typesCommand(args)).toBe(0);
+  } finally {
+    spy.mockRestore();
+  }
+  return lines.join("\n");
+}
+
+describe("#357 every registered view subtype is findable", () => {
+  test("a named lookup of a TS-only control resolves", async () => {
+    // The issue's headline repro: this printed "No vocabulary matches \"view.text\"".
+    const out = await run(["view.text"]);
+    expect(out).toContain("view.text");
+    expect(out).not.toContain("No vocabulary matches");
+  });
+
+  test("listing the type reports all 15 registered subtypes, not 2", async () => {
+    const out = await run(["--type", "view", "--kind", "subtype", "--limit", "0"]);
+    for (const sub of [
+      "base", "text", "textarea", "date", "month", "hotlink", "dropdown", "radio",
+      "checkbox", "number", "password", "hidden", "web", "currency", "image",
+    ]) {
+      expect(out).toContain(`view.${sub}`);
+    }
+    expect(out).toContain("15 matches.");
+  });
+
+  test("a control the loader rejects is still reported missing", async () => {
+    // The fix must not make the tool answer "yes" to everything: an unregistered
+    // subtype has to stay indistinguishable from a typo, because it IS one.
+    expect(await run(["view.bogusxyz"])).toContain("No vocabulary matches");
+  });
+
+  test("TS-only vocabulary is marked rather than hidden", async () => {
+    const out = await run(["--type", "view", "--kind", "subtype", "--limit", "0"]);
+    // `view.currency` is in the cross-port contract; `view.text` is not.
+    expect(out).toMatch(/view\.text .*\[ts-only\]/);
+    expect(out).not.toMatch(/view\.currency .*\[ts-only\]/);
+    expect(out).toContain("cross-port metamodel contract does not carry it");
+  });
+
+  test("a type's shared root is marked, so the concrete list is not mistaken for it", async () => {
+    expect(await run(["--type", "view", "--kind", "subtype", "--limit", "0"]))
+      .toMatch(/view\.base .*\[base\]/);
+  });
+});
+
+describe("#357 the registry is COMPOSED, so attrs are not missing", () => {
+  test("a db-provider attr on a core type is findable", async () => {
+    // @filterable/@column are registered by the db provider onto field.*; with only
+    // registerCoreTypes they did not exist as far as this command was concerned.
+    const out = await run(["field.string", "--limit", "0"]);
+    expect(out).toContain("@filterable");
+    expect(out).toContain("@column");
+    expect(out).toContain("@dbColumnType");
+  });
+
+  test("a ui-web-provider attr is findable", async () => {
+    expect(await run(["view.textarea", "--limit", "0"])).toContain("@rows");
+  });
+
+  test("@title — the attr #353 should have found — is findable by name", async () => {
+    const out = await run(["title"]);
+    expect(out).toContain("@title");
+    expect(out).not.toContain("No vocabulary matches");
+  });
+
+  test("a common attr is not hidden by a --type scope", async () => {
+    // @title is accepted on every node, so scoping to one type must not exclude it.
+    expect(await run(["--type", "view", "title"])).toContain("@title");
+  });
+
+  test("reserved structural keys are NOT offered as attrs", async () => {
+    // `isArray`/`extends` are bare structural keys; `@`-prefixing one is ERR_RESERVED_ATTR,
+    // so listing them would teach metadata the loader rejects.
+    const out = await run(["--kind", "attr", "--limit", "0", "isArray"]);
+    expect(out).toContain("No vocabulary matches");
+  });
+});

server/typescript/packages/metadata/src/index.ts

@@ -178,6 +178,11 @@ export { validateConstraints } from "./constraint-validate.js";
 
 // Registry conformance manifest (SP-G) — the canonical logical-vocabulary serializer.
 export { buildRegistryManifest, emitRegistryManifest, classifyPerTypeAttr, METAMODEL_VERSION } from "./registry-manifest.js";
+// #357 — the AUTHORING-facing twin of buildRegistryManifest: every registered
+// (type, subType) this port accepts, with the cross-port carve-outs MARKED rather
+// than dropped. `meta types` reads this; the five-port byte gate reads the manifest.
+export { buildVocabularyCatalog } from "./vocabulary-catalog.js";
+export type { VocabularyCatalog, VocabularyType } from "./vocabulary-catalog.js";
 export type { AttrClassification } from "./registry-manifest.js";
 export { ExclusionReason } from "./registry-manifest-exclusions.js";
 

server/typescript/packages/metadata/src/registry-manifest.ts

@@ -37,7 +37,7 @@ import {
 } from "./registry-manifest-exclusions.js";
 
 /** One attribute in the manifest — the logical, cross-port-identical facet. */
-interface ManifestAttr {
+export interface ManifestAttr {
   name: string;
   /** The attr's SCALAR value-type subtype, or null for a polymorphic/untyped attr (e.g. @default). */
   valueType: string | null;
@@ -63,7 +63,7 @@ interface ManifestAttr {
 }
 
 /** One structural child rule of a type (FR-033 constraint graph). */
-interface ManifestChild {
+export interface ManifestChild {
   /** The admitted child `type` (`"*"` = any). */
   childType: string;
   /** The admitted child subType — a single subtype, `"*"` (any), or a list of admitted subtypes. */
@@ -79,7 +79,7 @@ interface ManifestChild {
 }
 
 /** One registered (type, subType) in the manifest, with its docs + attrs + constraint graph. */
-interface ManifestType {
+export interface ManifestType {
   type: string;
   subType: string;
   /** FR-033 — human/AI-facing description of the type/subType (required, non-empty). */
@@ -124,7 +124,7 @@ interface RegistryManifest {
 }
 
 /** ASCII-string compare so the sort is locale-independent and byte-stable across ports. */
-function compareStrings(a: string, b: string): number {
+export function compareStrings(a: string, b: string): number {
   return a < b ? -1 : a > b ? 1 : 0;
 }
 
@@ -195,7 +195,7 @@ function toManifestChild(rule: ChildRule): ManifestChild {
 }
 
 /** Sort the constraint graph by (childType, childSubTypeKey, childName) — ASCII. */
-function sortedChildren(rules: readonly ChildRule[]): ManifestChild[] {
+export function sortedChildren(rules: readonly ChildRule[]): ManifestChild[] {
   return rules
     .map(toManifestChild)
     .sort(
@@ -207,7 +207,7 @@ function sortedChildren(rules: readonly ChildRule[]): ManifestChild[] {
 }
 
 /** Sort attrs by name (ascending, ASCII). */
-function sortedAttrs(attrs: readonly AttrSchema[]): ManifestAttr[] {
+export function sortedAttrs(attrs: readonly AttrSchema[]): ManifestAttr[] {
   return attrs
     .map(toManifestAttr)
     .sort((a, b) => compareStrings(a.name, b.name));
@@ -260,7 +260,8 @@ function sortedPerTypeAttrs(
  * judge a carve-out "dead" — that is a cross-port property, asserted by the
  * shared byte-canonical, not here.
  */
-const INCLUDED = "included" as const;
+/** The classifier's "this is logical cross-port vocabulary" verdict. */
+export const INCLUDED = "included" as const;
 export type AttrClassification = ExclusionReason | typeof INCLUDED;
 
 export function classifyPerTypeAttr(name: string): AttrClassification {