@metaobjectsdev/codegen-ts 0.23.1 → 0.24.0

package/src/projection/extract-view-spec.ts

@@ -32,6 +32,8 @@ import {
   FILTER_OP_LT,
   FILTER_OP_LTE,
   FILTER_OP_IS_NULL,
+  FILTER_OP_LIKE,
+  FIELD_SUBTYPE_ENUM,
   FILTER_COMPOSE_AND,
   FILTER_COMPOSE_OR,
   SORT_ORDER_DESC,
@@ -47,6 +49,7 @@ import {
   type AggregateFunction,
 } from "@metaobjectsdev/metadata";
 import { type MetaData, type MetaField, type MetaRoot, MetaObject } from "@metaobjectsdev/metadata";
+import { intValueMapOf } from "../enum-meta.js";
 import {
   columnNameFromField,
   viewNameFromProjection,
@@ -126,13 +129,84 @@ function resolveAggregateFilter(
       kind: "cmp",
       ref: `${alias}.${sourceColumnNameFor(field, ctx)}`,
       op,
-      value: opObj[op],
+      // Same int-backed-enum encoding as the row-scope @filter below: this scoping
+      // filter renders as a SQL literal too (FILTER (WHERE …) / CASE WHEN), so a
+      // member symbol would land unencoded in an integer comparison.
+      value: encodeIntEnumFilterValue(
+        opObj[op],
+        op,
+        field.subType === FIELD_SUBTYPE_ENUM ? intValueMapOf(field) : undefined,
+        key,
+        entity.name,
+      ),
     });
   }
   if (clauses.length === 0) return undefined;
   return clauses.length === 1 ? clauses[0]! : { kind: "and", clauses };
 }
 
+/**
+ * The `@intValueMap` of every int-backed `field.enum` the projection declares, keyed
+ * by field name. Only int-backed enums appear, so a lookup miss means "no encoding".
+ *
+ * `fields()` (effective) and `intValueMapOf` (which reads `attr`, RESOLVING) — a
+ * projection's fields are bound through `extends` to the base entity's, and post-#246
+ * the map itself commonly lives one hop further up on a shared abstract declaration.
+ * Own-only at either hop would silently emit the member symbol into an integer column
+ * (ADR-0039).
+ */
+function intEnumMapsOf(projection: MetaObject): ReadonlyMap<string, Record<string, number>> {
+  const out = new Map<string, Record<string, number>>();
+  for (const f of projection.fields()) {
+    if (f.subType !== FIELD_SUBTYPE_ENUM) continue;
+    const map = intValueMapOf(f);
+    if (map !== undefined) out.set(f.name, map);
+  }
+  return out;
+}
+
+/**
+ * Lower a filter value for an int-backed `field.enum` from its member SYMBOL to the
+ * INTEGER it persists as. A no-op for every other field (`intMap` undefined), so a
+ * string-backed enum's SQL is byte-identical.
+ *
+ * `isNull` is skipped — its value is a boolean, not a member. `like` is unreachable:
+ * `opsForField` removes it from an int-backed enum's band, so the loader rejects it
+ * before codegen; the explicit throw makes that a loud failure rather than a
+ * `LIKE NaN`. An unmapped member is likewise loader-unreachable (the key set is
+ * pinned equal to `@values`) and throws for the same reason — silently emitting the
+ * symbol would produce DDL that fails only at apply time, against a live database.
+ */
+function encodeIntEnumFilterValue(
+  value: unknown,
+  op: string,
+  intMap: Record<string, number> | undefined,
+  fieldName: string,
+  projectionName: string,
+): unknown {
+  if (intMap === undefined) return value;
+  if (op === FILTER_OP_IS_NULL) return value;
+  if (op === FILTER_OP_LIKE) {
+    throw new Error(
+      `Projection ${projectionName}: view @filter uses "like" on "${fieldName}", an ` +
+        `int-backed field.enum (@intValueMap) — it stores as an integer column, so a ` +
+        `substring match is not expressible. Use eq/ne/in.`,
+    );
+  }
+  const encode = (v: unknown): unknown => {
+    if (typeof v !== "string") return v;
+    const n = intMap[v];
+    if (typeof n !== "number") {
+      throw new Error(
+        `Projection ${projectionName}: view @filter value "${v}" for "${fieldName}" has no ` +
+          `entry in @intValueMap.`,
+      );
+    }
+    return n;
+  };
+  return Array.isArray(value) ? value.map(encode) : encode(value);
+}
+
 /**
  * #207 — resolve a projection's row-scope `@filter` (the desugared canonical
  * `{ field: { op: value }, and?, or? }`) into a {@link ViewFilterClause} whose
@@ -152,13 +226,14 @@ function resolveViewFilter(
   filter: unknown,
   columnsByField: ReadonlyMap<string, SelectColumn>,
   projectionName: string,
+  intMapsByField: ReadonlyMap<string, Record<string, number>>,
 ): ViewFilterClause | undefined {
   if (typeof filter !== "object" || filter === null || Array.isArray(filter)) return undefined;
   const clauses: ViewFilterClause[] = [];
   for (const [key, val] of Object.entries(filter as Record<string, unknown>)) {
     if (key === FILTER_AND || key === FILTER_OR) {
       const subs = (Array.isArray(val) ? val : [])
-        .map((s) => resolveViewFilter(s, columnsByField, projectionName))
+        .map((s) => resolveViewFilter(s, columnsByField, projectionName, intMapsByField))
         .filter((c): c is ViewFilterClause => c !== undefined);
       if (subs.length > 0) clauses.push({ kind: key === FILTER_AND ? "and" : "or", clauses: subs });
       continue;
@@ -177,7 +252,14 @@ function resolveViewFilter(
     // becomes its own comparison, AND-composed (dropping all-but-the-first would silently
     // widen the exposed row set). The loader has already validated every op for this
     // field's subtype.
-    for (const [op, value] of Object.entries(desugarClause(val))) {
+    for (const [op, rawValue] of Object.entries(desugarClause(val))) {
+      // An INT-BACKED field.enum (@intValueMap, design D5) stores as an INTEGER
+      // column, so the authored member SYMBOL must become its integer before it is
+      // rendered as a SQL literal. The Drizzle customType handles the runtime query
+      // path, but view DDL is emitted as literal SQL text and never touches Drizzle.
+      const value = encodeIntEnumFilterValue(
+        rawValue, op, intMapsByField.get(key), key, projectionName,
+      );
       if (col.kind === "passthrough") {
         clauses.push({ kind: "cmp", ref: `${col.sourceAlias}.${col.sourceColumn}`, op, value });
       } else if (col.kind === "computed") {
@@ -990,7 +1072,9 @@ export function extractViewSpec(
       const columnsByField = new Map<string, SelectColumn>(
         selectSpec.columns.map((c) => [c.fieldName, c] as const),
       );
-      where = resolveViewFilter(rawFilter, columnsByField, projection.name);
+      where = resolveViewFilter(
+        rawFilter, columnsByField, projection.name, intEnumMapsOf(projection),
+      );
     }
   }
 

package/src/reconcile-orphans.ts

@@ -0,0 +1,136 @@
+// FR-038 §8 — deletion integrity: what happens to a generated file that is no
+// longer generated.
+//
+// A requirement's stubs become orphans when the requirement is deleted. The
+// obvious move — remove them, as the FR-038 draft said for `abandoned` entries —
+// is safe only for an UNTOUCHED stub. On a filled one it eats assertions somebody
+// wrote, and the whole point of the inversion is that the body is hand-written and
+// survives regeneration.
+//
+// So: remove what the generator wrote, REFUSE what a human changed, and name it.
+// That mirrors the migrate engine refusing a primary-key move rather than emitting
+// something un-appliable (#258) — a refusal is recoverable, a deletion is not.
+//
+// Deliberately PURE: the caller supplies the readers. The decision is the part
+// worth testing, and threading a filesystem through it would make the rule harder
+// to exercise than the plumbing around it.
+
+/**
+ * A generator's opt-in to orphan reconciliation, and the namespace it applies to.
+ *
+ * Declaring this is the ONLY way in: `.gen-state/.hashes.json` records paths, not
+ * which generator produced each one, so the runner genuinely cannot work out who
+ * owns what. Deriving ownership from the output directory instead would be worse
+ * than useless — every generator in a single-target project writes to the same
+ * `outDir`, so one generator narrowing its output would delete its siblings'
+ * files. The generator has to say.
+ */
+export interface OrphanPolicy {
+  /**
+   * True when `relPathInTarget` — a path relative to this generator's own output
+   * directory, always `/`-separated — is inside the namespace this generator is
+   * the sole producer of.
+   *
+   * Be narrow. This predicate is the blast radius: every previously-generated
+   * path it accepts and this run did not re-emit is a deletion candidate.
+   */
+  readonly owns: (relPathInTarget: string) => boolean;
+  /**
+   * Delete a hand-edited orphan instead of refusing it. Default false.
+   *
+   * The seam exists because §6 requires every default to have one, not because
+   * it is advisable: the refusal already names the file and deleting it by hand
+   * is a one-line answer, whereas this flag makes the destructive outcome the
+   * automatic one.
+   */
+  readonly force?: boolean;
+}
+
+export interface OrphanDecision {
+  /** No longer emitted, on disk, and byte-identical to the snapshot we wrote.
+   *  Safe to delete — the generator is removing only its own untouched output. */
+  readonly remove: readonly string[];
+  /** No longer emitted and CHANGED since we wrote it (or with no snapshot to
+   *  compare against). Left alone and reported, never deleted. */
+  readonly refused: readonly string[];
+  /** No longer emitted and already absent from disk. Nothing to delete; the
+   *  caller should just drop the stale snapshot. */
+  readonly vanished: readonly string[];
+}
+
+export interface ReconcileOrphansArgs {
+  /** Relative paths this generator emitted on some previous run — in practice the
+   *  keys of `.gen-state/.hashes.json`. */
+  readonly previouslyGenerated: readonly string[];
+  /** Relative paths emitted on THIS run. */
+  readonly emitted: readonly string[];
+  /** Namespace guard. Orphan reconciliation is opt-in and scoped: a generator must
+   *  never delete another generator's output just because it stopped emitting its
+   *  own. */
+  readonly owns: (relPath: string) => boolean;
+  /** Whether the file is still on disk at all. */
+  readonly exists: (relPath: string) => boolean;
+  /**
+   * Whether the file is byte-for-byte what we recorded writing.
+   *
+   * MUST fail closed — false when it cannot be proven. This is deliberately the
+   * same question the write path asks (`isPristineGenerated`), of the same
+   * evidence: the committed hash manifest. Before they were unified, one feature
+   * refused to DELETE a hand-edited file while silently OVERWRITING one, which is
+   * the same uncertainty answered two opposite ways.
+   */
+  readonly isUntouched: (relPath: string) => boolean;
+}
+
+export function reconcileOrphans(args: ReconcileOrphansArgs): OrphanDecision {
+  const emitted = new Set(args.emitted);
+  const remove: string[] = [];
+  const refused: string[] = [];
+  const vanished: string[] = [];
+
+  for (const relPath of args.previouslyGenerated) {
+    if (emitted.has(relPath)) continue;
+    if (!args.owns(relPath)) continue;
+
+    if (!args.exists(relPath)) {
+      vanished.push(relPath);
+      continue;
+    }
+
+    // Fail closed: unless we can prove the file is untouched, guessing wrong
+    // deletes someone's work.
+    if (!args.isUntouched(relPath)) {
+      refused.push(relPath);
+      continue;
+    }
+
+    remove.push(relPath);
+  }
+
+  return { remove, refused, vanished };
+}
+
+/**
+ * The message shown when a hand-edited orphan is refused.
+ *
+ * It has to say what happened, why nothing was deleted, and what the two ways out
+ * are — otherwise the reasonable reaction to an unexplained refusal is to delete
+ * the file, which is the outcome the refusal exists to prevent.
+ */
+export function refusedOrphanMessage(
+  paths: readonly string[],
+  /** Which generator's namespace these came from. `orphanPolicy` is a generic
+   *  `Generator` field and `sweepOrphans`/`OrphanPolicy` are exported precisely so an
+   *  app can compose its own — so this message must not hardcode `requirement-tests`,
+   *  naming a generator the project may not even use and a cause ("the requirement was
+   *  removed") that may not apply. */
+  generatorName = "orphan cleanup",
+): string {
+  return (
+    `${generatorName}: ${paths.length} generated file(s) are no longer produced by ` +
+    `this generator but have been edited by hand, so they were NOT deleted: ` +
+    `${paths.join(", ")}. Either what produced them was removed (delete these files ` +
+    `yourself if the edits are no longer wanted) or it was renamed (move the edits ` +
+    `into the newly generated file first — regeneration cannot follow a rename).`
+  );
+}

package/src/reference/barrel.ts

@@ -2,6 +2,10 @@
 // Then import it LOCALLY in metaobjects.config.ts instead of from the package:
 //   import { barrel } from "./codegen/generators/barrel.js";
 //
+// RUNTIME: this file executes under whatever runs `meta gen`, and the published CLI's
+// shebang is `#!/usr/bin/env node` — so it runs under NODE even in a Bun project. Do not
+// reach for `Bun.*` globals here; they are undefined and take the whole run down with
+// `Bun is not defined`. Use `node:` builtins instead.
 // use-when:      you want a single `index.ts` re-exporting every generated entity module.
 // emits:         <target>/index.ts with one `export * from "./<Entity>"` per entity, alphabetical.
 // customize:     the export form (star vs named), ordering, grouping by package, what to include/exclude.

package/src/reference/entity.ts

@@ -2,6 +2,10 @@
 // Then import it LOCALLY in metaobjects.config.ts:
 //   import { entityFile } from "./codegen/generators/entity.js";
 //
+// RUNTIME: this file executes under whatever runs `meta gen`, and the published CLI's
+// shebang is `#!/usr/bin/env node` — so it runs under NODE even in a Bun project. Do not
+// reach for `Bun.*` globals here; they are undefined and take the whole run down with
+// `Bun is not defined`. Use `node:` builtins instead.
 // use-when:      ALWAYS — this is the entity-module generator. It owns the shape of each
 //                generated <Entity>.ts (the Drizzle table, Zod schemas, inferred types,
 //                constants, filter allowlists). Start here and adapt the assembly.

package/src/reference/queries.ts

@@ -2,6 +2,10 @@
 // Then import it LOCALLY in metaobjects.config.ts:
 //   import { queriesFile } from "./codegen/generators/queries.js";
 //
+// RUNTIME: this file executes under whatever runs `meta gen`, and the published CLI's
+// shebang is `#!/usr/bin/env node` — so it runs under NODE even in a Bun project. Do not
+// reach for `Bun.*` globals here; they are undefined and take the whole run down with
+// `Bun is not defined`. Use `node:` builtins instead.
 // use-when:      you want generated typed CRUD finders (find<E>ById, list<E>s, create/update/delete)
 //                over Drizzle. Drop it if you hand-write your data access.
 // emits:         <target>/<Entity>.queries.ts per source-backed object (any source.rdb kind,

package/src/reference/routes.ts

@@ -2,6 +2,10 @@
 // Then import it LOCALLY in metaobjects.config.ts:
 //   import { routesFile } from "./codegen/generators/routes.js";
 //
+// RUNTIME: this file executes under whatever runs `meta gen`, and the published CLI's
+// shebang is `#!/usr/bin/env node` — so it runs under NODE even in a Bun project. Do not
+// reach for `Bun.*` globals here; they are undefined and take the whole run down with
+// `Bun is not defined`. Use `node:` builtins instead.
 // use-when:      you want generated Fastify REST routes per entity. Drop it and hand-write routes
 //                if you need bespoke endpoints — or keep it and add handlers via <Entity>.extra.ts.
 // emits:         <target>/<Entity>.routes.ts — full CRUD for write-through entities, read-only

package/src/render-engine/embedded-templates.generated.ts

@@ -9,6 +9,6 @@ export const EMBEDDED_FRAMEWORK_TEMPLATES: Record<string, string> = {
   "api/agent-api.md": "{{{generatedMarker}}}\n\n# {{title}}\n\nGenerated API reference for {{project}}; call these exactly as written. {{importNote}}\n{{#hasSetup}}\n\n## Setup\n{{#setup}}\n- `{{handle}}` — {{{note}}} `{{{snippetInline}}}`\n{{/setup}}\n{{/hasSetup}}\n{{#units}}\n\n## {{node}}\n{{#groups}}\n\n`{{importHeader}}`\n{{#symbols}}\n- `{{signature}}` — {{usage}}{{#throwsMarker}} {{throwsMarker}}{{/throwsMarker}}\n{{/symbols}}\n{{/groups}}\n{{#example}}\n\nExample:\n```ts\n{{{example}}}\n```\n{{/example}}\n{{/units}}\n",
   "api/entity-api.md": "{{{generatedMarker}}}\n\n# {{node}} API\n{{#modelPageHref}}\n\n**Model / metadata:** [{{node}}]({{modelPageHref}})\n{{/modelPageHref}}\n\n> Import paths are relative to your generated-output directory.\n{{#hasSetup}}\n\n## Setup\n\nObtain the runtime handles the calls below need:\n{{#setup}}\n\n- `{{handle}}` — {{{note}}}\n\n```ts\n{{{snippet}}}\n```\n{{/setup}}\n{{/hasSetup}}\n{{#unitExample}}\n\n## Example\n\n```ts\n{{{unitExample}}}\n```\n{{/unitExample}}\n{{#sections}}\n\n## {{heading}}\n{{#symbols}}\n\n### `{{signature}}`\n\n{{usage}}\n\n```ts\n{{importLine}}\n```\n{{#hasFields}}\n\n{{fieldsCaption}}:\n\n| Field | Type | Required | Notes |\n|---|---|---|---|\n{{#fieldRows}}\n| `{{field}}` | `{{{type}}}` | {{required}} | {{notes}} |\n{{/fieldRows}}\n{{/hasFields}}\n{{#mountNote}}\n\nMount: {{{mountNote}}}\n{{/mountNote}}\n{{#throws}}\n\nThrows: {{throws}}\n{{/throws}}\n{{#example}}\n\n```ts\n{{{example}}}\n```\n{{/example}}\n{{/symbols}}\n{{/sections}}\n",
   "api/index.md": "{{{generatedMarker}}}\n\n# {{title}}\n\n{{intro}}\n{{#hasEntities}}\n\n## Entities\n\n{{#entities}}\n- [{{node}}]({{href}}) — {{summary}} ({{symbolCount}} symbol{{^one}}s{{/one}})\n{{/entities}}\n{{/hasEntities}}\n{{#hasTemplates}}\n\n## Templates\n\n{{#templates}}\n- [{{node}}]({{href}}) — {{summary}} ({{symbolCount}} symbol{{^one}}s{{/one}})\n{{/templates}}\n{{/hasTemplates}}\n",
-  "docs/entity-page.md": "{{{generatedMarker}}}\n\n# {{entity.name}}\n{{#summaryLead}}\n\n{{{.}}}\n{{/summaryLead}}\n{{#descriptionQuote}}\n\n{{{.}}}\n{{/descriptionQuote}}\n{{#apiRefs.0}}\n\n**API reference:** {{/apiRefs.0}}{{#apiRefs}}[{{label}}]({{href}}){{^last}} · {{/last}}{{/apiRefs}}{{#apiRefs.0}}\n{{/apiRefs.0}}\n\n{{{preambleHeader}}}\n{{#hasIdentities}}\n\n## Identity\n\n{{#identities}}\n- {{{bullet}}}\n{{/identities}}\n{{/hasIdentities}}\n{{#hasNeighborhoodEr}}\n\n## In context\n\n{{{neighborhoodErBlock}}}\n{{/hasNeighborhoodEr}}\n{{#fields.hasFields}}\n\n## Fields\n\n| Field | Type | Required | Column | Rules |\n|---|---|---|---|---|\n{{#fields.rows}}\n| {{{fieldCell}}} | {{{typeCell}}} | {{requiredCell}} | {{{storageCell}}} | {{{rulesCell}}} |\n{{/fields.rows}}\n{{/fields.hasFields}}\n{{#fieldDetails.hasDetails}}\n\n## Field details\n\n{{#fieldDetails.rows}}\n{{{block}}}\n\n{{/fieldDetails.rows}}\n{{/fieldDetails.hasDetails}}\n{{#hasRelationships}}\n\n## Relationships\n\n{{#relationships}}\n- {{{bullet}}}\n{{/relationships}}\n{{/hasRelationships}}\n{{#hasUsedBy}}\n\n## Used by\n\n{{#usedBy}}\n- {{{bullet}}}\n{{/usedBy}}\n{{/hasUsedBy}}\n",
+  "docs/entity-page.md": "{{{generatedMarker}}}\n\n# {{entity.name}}\n{{#summaryLead}}\n\n{{{.}}}\n{{/summaryLead}}\n{{#descriptionQuote}}\n\n{{{.}}}\n{{/descriptionQuote}}\n{{#apiRefs.0}}\n\n**API reference:** {{/apiRefs.0}}{{#apiRefs}}[{{label}}]({{href}}){{^last}} · {{/last}}{{/apiRefs}}{{#apiRefs.0}}\n{{/apiRefs.0}}\n\n{{{preambleHeader}}}\n{{#hasIdentities}}\n\n## Identity\n\n{{#identities}}\n- {{{bullet}}}\n{{/identities}}\n{{/hasIdentities}}\n{{#hasNeighborhoodEr}}\n\n## In context\n\n{{{neighborhoodErBlock}}}\n{{/hasNeighborhoodEr}}\n{{#fields.hasFields}}\n\n## Fields\n\n| Field | Type | Required | Column | Rules |\n|---|---|---|---|---|\n{{#fields.rows}}\n| {{{fieldCell}}} | {{{typeCell}}} | {{requiredCell}} | {{{storageCell}}} | {{{rulesCell}}} |\n{{/fields.rows}}\n{{/fields.hasFields}}\n{{#fieldDetails.hasDetails}}\n\n## Field details\n\n{{#fieldDetails.rows}}\n{{{block}}}\n\n{{/fieldDetails.rows}}\n{{/fieldDetails.hasDetails}}\n{{#hasRelationships}}\n\n## Relationships\n\n{{#relationships}}\n- {{{bullet}}}\n{{/relationships}}\n{{/hasRelationships}}\n{{#hasUsedBy}}\n\n## Used by\n\n{{#usedBy}}\n- {{{bullet}}}\n{{/usedBy}}\n{{/hasUsedBy}}\n{{#hasClaimedBy}}\n\n## Required by\n\n{{#claimedBy}}\n- {{{bullet}}}\n{{/claimedBy}}\n{{/hasClaimedBy}}\n",
   "docs/template-page.md": "{{{generatedMarker}}}\n\n# {{name}}\n{{#descriptionQuote}}\n\n{{{.}}}\n{{/descriptionQuote}}\n\n**Kind:** {{kind}}\n\n## Output\n{{^isEmail}}\n\n- Format: `{{format}}`\n{{/isEmail}}\n{{#isEmail}}\n\nMultipart email — rendered as the following parts:\n\n| Part | Source | Format | Escaping |\n|---|---|---|---|\n{{#parts}}\n| {{label}} | `{{ref}}` | `{{format}}` | {{#escaped}}escaped{{/escaped}}{{^escaped}}raw{{/escaped}} |\n{{/parts}}\n{{/isEmail}}\n\n## Input\n\n- Payload: [`{{payload.name}}`]({{payload.link}})\n{{#hasRequiredTags}}\n- Required fields:{{#requiredTags}} `{{.}}`{{/requiredTags}}\n{{/hasRequiredTags}}\n\n## Render contract\n\n- Every field referenced by the template is validated against the payload at generation time; an unknown field fails generation.\n{{#maxChars}}\n- Maximum length: {{.}} characters (rendering longer output fails).\n{{/maxChars}}\n{{#hasRequiredTags}}\n- Required tags must be present:{{#requiredTags}} `{{.}}`{{/requiredTags}}\n{{/hasRequiredTags}}\n\n## Source\n\n{{#sourceRefs}}\n- `{{.}}`\n{{/sourceRefs}}\n{{#templateSourceSection}}\n\n{{{.}}}\n{{/templateSourceSection}}\n\n## Capability\n\n{{capability}}\n",
 };

package/src/requirement-walk.ts

@@ -0,0 +1,124 @@
+// FR-038 — walking `requirement.*` nodes and projecting them for downstream filters.
+//
+// WHY A WALK RATHER THAN ctx.matches: the `Generator` contract is entity-shaped —
+// `GenContext.entities` is `MetaObject[]` and `filter` is
+// `(entity: MetaObject) => boolean` — so a requirement-driven generator cannot use
+// it and must walk `loadedRoot` itself. Generalising `Generator` over any node kind
+// is the principled fix and is deliberately out of scope: it is a core contract
+// change touching every existing generator in five ports.
+//
+// WHY A PROJECTION rather than the raw node: an application's filter is app-owned
+// policy (FR-038 §5), and handing it a `MetaData` would bind adopter code to
+// metamodel internals and export the ADR-0039 own-vs-resolving accessor trap. The
+// projection is additive — it can grow, but it never hands out the node.
+
+import { TYPE_REQUIREMENT, resolveClaim } from "@metaobjectsdev/metadata";
+import type { MetaData, MetaRequirement } from "@metaobjectsdev/metadata";
+
+/** The shape an app's `filter` receives. Never the node itself. */
+export interface RequirementView {
+  /** "functional" | "architectural" — the check-polarity axis. */
+  readonly subType: string;
+  /** 1 solution · 2 segment · 3 service · 4 object · 5 member. Undefined on an
+   *  unlevelled architectural requirement (the original flat policy form). */
+  readonly level: number | undefined;
+  readonly status: string | undefined;
+  /** Dotted path from the root through nesting ancestors — hierarchy is nesting. */
+  readonly path: string;
+  /** DISTINCT `type.subType` concerns among the resolved targets. */
+  readonly implementedByTypes: readonly string[];
+}
+
+export interface ResolvedClaim {
+  /** The reference exactly as authored, for the doc comment. */
+  readonly ref: string;
+  readonly node: MetaData;
+  readonly concern: string;
+}
+
+export interface WalkedRequirement {
+  readonly node: MetaRequirement;
+  readonly view: RequirementView;
+  readonly targets: readonly ResolvedClaim[];
+}
+
+/** `<type>.<subType>` — the key a renderer map is looked up by. */
+export function concernOf(node: MetaData): string {
+  return `${node.type}.${node.subType}`;
+}
+
+/**
+ * The concern key for a requirement that resolves NO targets.
+ *
+ * Doubles as the catch-all renderer key, deliberately: a requirement with nothing
+ * to fan out over falls through to whatever the app registered as its default.
+ */
+export const NO_CONCERN = "*";
+
+/**
+ * Depth-first walk of every `requirement.*` node, nested ones included.
+ *
+ * Unresolvable `@implementedBy` references are skipped rather than thrown on —
+ * resolution severity is `meta verify`'s job (it depends on `@status`, which is why
+ * it cannot live in the loader), and codegen must not fail a build over a
+ * diagnostic another command owns.
+ */
+export function walkRequirements(root: MetaData): WalkedRequirement[] {
+  const out: WalkedRequirement[] = [];
+
+  const visit = (node: MetaData, prefix: string): void => {
+    if (node.type !== TYPE_REQUIREMENT) return;
+    const path = prefix === "" ? node.name : `${prefix}.${node.name}`;
+    const req = node as MetaRequirement;
+    // Same referrer-package basis the CLI's checks use, so a bare reference binds
+    // package-locally under the ADR-0042 contract.
+    const referrerPkg = node.package ?? node.fileDefaultPackage ?? "";
+
+    const targets: ResolvedClaim[] = [];
+    for (const ref of req.implementedBy()) {
+      const target = resolveClaim(root, ref, referrerPkg);
+      if (target === undefined) continue;
+      targets.push({ ref, node: target, concern: concernOf(target) });
+    }
+
+    out.push({
+      node: req,
+      view: {
+        subType: node.subType,
+        level: req.level(),
+        status: req.status(),
+        path,
+        implementedByTypes: [...new Set(targets.map((t) => t.concern))],
+      },
+      targets,
+    });
+
+    for (const child of node.children()) visit(child, path);
+  };
+
+  for (const child of root.children()) visit(child, "");
+  return out;
+}
+
+/**
+ * Group a requirement's targets by distinct concern — the fan-out unit.
+ *
+ * One entry per distinct `type.subType`, NOT one per target: a single architectural
+ * requirement claimed by 123 entities must emit one stub, not 123, which is the
+ * hostile-first-contact outcome FR-038 §10 exists to avoid.
+ *
+ * A requirement resolving NO targets still yields exactly ONE group. That is not a
+ * degenerate case: `REQUIREMENT_LINK_FLOOR_LEVEL` forbids `@implementedBy` below L4,
+ * so every L1–L3 requirement resolves nothing — and an application that chooses to
+ * cover L3 would otherwise get silence instead of a stub.
+ */
+export function groupByConcern(w: WalkedRequirement): Map<string, ResolvedClaim[]> {
+  const groups = new Map<string, ResolvedClaim[]>();
+  for (const t of w.targets) {
+    const existing = groups.get(t.concern);
+    if (existing === undefined) groups.set(t.concern, [t]);
+    else existing.push(t);
+  }
+  if (groups.size === 0) groups.set(NO_CONCERN, []);
+  return groups;
+}