fix(spec,cli): todos stays whole and absentTodos names a subset; four code-door entries lose their question; tiers is a carrier

Contract-review patch round: applyMetaMigrations().todos and each hop's
todos keep every semantic entry again; absentTodos names the proven-absent
entries as a subset of them (same objects). os migrate meta lists todos minus
absentTodos. The four CEL/RLS predicate entries whose surface also names a
direct evaluator or compiler caller lose relevantWhen (batch 25). A declared
tiers preset answers unknown like plugins. Docs: --all in the flags table.

Co-authored-by: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RPo7FUd6bSnAfkWMAKi848

Author: claude

.changeset/22072-migrate-meta-relevance-predicate.md

@@ -8,11 +8,18 @@
 Clause-②: yes
 
 - **`SemanticMigration.relevantWhen`** (`@objectstack/spec/migrations`) is a new optional field. It holds a structured question over the loaded stack, `{ kind: 'stack-declares', keys: [...] }`: does the stack declare anything under one of these top-level keys? A key's value in a `packages[].manifest` body counts the same as a top-level value. The question is closed and named. It is never free text, and it never matches against the prose of `surface`. The new types `SemanticRelevance`, `StackDeclaresRelevance` and `SemanticRelevanceKey` are exported beside `SemanticMigration`.
-- **`applyMetaMigrations`** asks each entry's question of the stack it is given and of every hop checkpoint. It returns the new `absentTodos`, on the chain result and on each hop, with the entries whose question answered `absent` in all of them. `todos` keeps every other entry. Together the two arrays hold every semantic entry of every hop crossed, each once and in chain order. Entries move only on a positive proof. These cases answer `unknown` and keep the entry listed:
-  - a value the question cannot read (a function, a promise, a scalar, a getter that throws);
-  - a stack that is not a plain object;
-  - any `plugins` / `devPlugins` entry, since a plugin can register metadata the stack does not show.
+- **`applyMetaMigrations`** asks each entry's question of the stack it is given and of every hop checkpoint.
+  - **`todos` is unchanged.** `MigrationChainResult.todos` and `MigrationHopResult.todos` still hold every semantic entry of every hop crossed, whatever the stack holds, as before.
+  - **`absentTodos` is a new required member** of `MigrationChainResult` and `MigrationHopResult`. It names the subset of `todos` whose question answered `absent` in all of them: the same objects, in chain order. Code that only reads a chain result needs no change. Code that builds one of these two interfaces itself must now supply `absentTodos` (an empty array when nothing is proven absent).
+  - **Only a positive proof names an entry.** These cases answer `unknown` and leave it off `absentTodos`:
+    - a value the question cannot read (a function, a promise, a scalar, a getter that throws);
+    - a stack that is not a plain object;
+    - any `plugins`, `devPlugins` or `tiers` entry, since a plugin, or the platform plugins a tier preset loads, can register metadata the stack does not show.
 
-  An entry that judges a conversion which applied an edit in the same run also stays listed. A consumer that reads only `todos` gets the entries this stack may owe. The rest are in `absentTodos`.
-- **The first batch is 29 entries** (5 from protocol 17, 24 from protocol 18). Each one's surface lives only under named top-level stack keys: `analyticsCubes`, `apis`, `jobs`, `mappings`, `hooks`, `agents`, `tools`, `dashboards` (with `reports` and `pages` for the chart-config entry), `datasets`, `permissions` and `sharingRules`. Each entry was also checked to confirm that its acceptance criteria send the author to no stored row and no runtime door. Every other entry is listed exactly as before.
-- **`os migrate meta`** prints one line after the listed notices. It counts the entries proven absent and names `--all`. A second line says that the proof covers the stack this run loaded, and not metadata a deployment stores. `--all` prints each of those entries in full, with the keys it was proven absent under. `--json` always carries them under `absentTodos`, and under `hops[].absentTodos` with `--step`. `--step` adds a `not listed` count to each hop line. A run whose only notices are proven absent still writes `--out`.
+    An entry that judges a conversion which applied an edit in the same run is never named either.
+- **The first batch is 25 entries** (5 from protocol 17, 20 from protocol 18). Each one's surface lives only under named top-level stack keys: `analyticsCubes`, `apis`, `jobs`, `mappings`, `hooks`, `agents`, `tools`, `dashboards` (with `reports` and `pages` for the chart-config entry), `datasets`, `permissions` and `sharingRules`. None of them names a code door. Each entry was also checked to confirm that its acceptance criteria send the author to no stored row and no runtime door. Every other entry is never named absent, so it is listed exactly as before.
+- **`os migrate meta`** lists `todos` minus `absentTodos`. After the listed notices it prints one line that counts the entries proven absent and names `--all`. A second line says that the proof covers the stack this run loaded, and not metadata a deployment stores.
+  - `--all` prints each of those entries in full, with the keys it was proven absent under.
+  - `--json` keeps `todos` whole and adds `absentTodos`, plus `hops[].absentTodos` with `--step`.
+  - `--step` reports each hop's listed count and adds a `not listed` count to the hop line.
+  - A run whose only notices are proven absent still writes `--out`.

content/docs/upgrading.mdx

@@ -215,6 +215,7 @@ Useful flags:
 | Flag | What it does |
 | :--- | :--- |
 | `--step` | Report each major's hop separately, so a failure bisects to the exact major |
+| `--all` | Also list, in full, the manual changes whose surface the command proved absent from your stack — by default they are only counted. `--json` always reports them in `todos` and names them in `absentTodos` |
 | `--out migrated.stack.json` | Also write the migrated stack as a JSON snapshot — the only file the command writes |
 | `--to 17` | Stop at an intermediate major instead of this runtime's |
 | `--json` | Machine-readable output, for CI or an agent |

packages/cli/src/commands/migrate/meta.report-order.test.ts

@@ -11,9 +11,10 @@
  *
  *  ① the verdict, and every schema refusal left after the chain;
  *  ② the applied mechanical edits;
- *  ③ the semantic notices the stack may owe (`todos`);
- *  ④ the notices proven absent from the stack (`absentTodos`) — counted on one
- *    line by default, listed in full under `--all` (the ABSENT pins below).
+ *  ③ the semantic notices the stack may owe (`todos` minus `absentTodos`);
+ *  ④ the notices proven absent from the stack (`absentTodos`, a subset of
+ *    `todos`) — counted on one line by default, listed in full under `--all`
+ *    (the ABSENT pins below).
  *
  * ## Two kinds of pin, kept apart on purpose
  *
@@ -176,9 +177,19 @@ function blockLines(t: MigrationTodo): string[] {
   ].join('\n').split('\n');
 }
 
+/**
+ * The notices ③ lists: every entry of `todos` the chain did not name in
+ * `absentTodos` — written from the chain's data by key, not by the printer's
+ * own filter.
+ */
+function listedOf(result: MigrationChainResult): MigrationTodo[] {
+  const absent = new Set(result.absentTodos.map((t) => `${t.toMajor}:${t.id}`));
+  return result.todos.filter((t) => !absent.has(`${t.toMajor}:${t.id}`));
+}
+
 /** The lines ③ prints — every listed notice, in chain order. */
 function noticeLines(result: MigrationChainResult): string[] {
-  return result.todos.flatMap(blockLines);
+  return listedOf(result).flatMap(blockLines);
 }
 
 /** ④ without `--all`: the line counting the proven-absent notices, and the line scoping the proof. */
@@ -258,7 +269,7 @@ describe('each group opens with one header line that counts it', () => {
       `  Applied ${result.applied.length} mechanical change(s):`,
     ]);
     expect(lines.filter((l) => SEMANTIC_HEADER_RE.test(l))).toEqual([
-      `  ${result.todos.length} manual change(s) require your judgment:`,
+      `  ${listedOf(result).length} manual change(s) require your judgment:`,
     ]);
   });
 });
@@ -275,8 +286,8 @@ describe('no notice, edit or refusal is dropped, merged or reworded (SET)', () =
     const expected = noticeLines(result);
     // Anti-vacuity: more than one hop's catalogue, and at least one notice
     // whose prose spans several terminal lines.
-    expect(new Set(result.todos.map((t) => t.toMajor)).size).toBeGreaterThan(1);
-    expect(expected.length).toBeGreaterThan(result.todos.length * 3);
+    expect(new Set(listedOf(result).map((t) => t.toMajor)).size).toBeGreaterThan(1);
+    expect(expected.length).toBeGreaterThan(listedOf(result).length * 3);
     const header = indexOf(lines, SEMANTIC_HEADER_RE);
     const printedNotices = lines.slice(header + 1, header + 1 + expected.length);
     expect(printedNotices).toEqual(expected);
@@ -440,11 +451,11 @@ describe('an applied edit a semantic entry judges prints that entry beside it, m
   it('keeps every semantic entry in ③ — the judge included — with the chain\'s count and bytes', () => {
     const { result, lines } = run(DECISION_STACK, MIGRATION_SUPPORT_FLOOR, TERMINUS);
     const header = indexOf(lines, SEMANTIC_HEADER_RE);
-    expect(lines[header]).toBe(`  ${result.todos.length} manual change(s) require your judgment:`);
+    expect(lines[header]).toBe(`  ${listedOf(result).length} manual change(s) require your judgment:`);
     const expected = noticeLines(result);
     expect(lines.slice(header + 1, header + 1 + expected.length)).toEqual(expected);
     const entries = lines.slice(header + 1).filter((l) => /^ {4}⚠ \[protocol \d+\] /.test(l));
-    expect(entries).toHaveLength(result.todos.length);
+    expect(entries).toHaveLength(listedOf(result).length);
     const judge = todoOf(result, DECISION_JUDGE);
     expect(entries).toContain(`    ⚠ [protocol ${judge.toMajor}] ${judge.surface} → ${judge.replacement}`);
   });
@@ -461,7 +472,7 @@ describe('an applied edit a semantic entry judges prints that entry beside it, m
       }
       runs.set(a.conversionId, (runs.get(a.conversionId) ?? 0) + 1);
     }
-    const reviews = result.todos.flatMap((t) =>
+    const reviews = listedOf(result).flatMap((t) =>
       (t.conversionIds ?? []).filter((id) => runs.has(id)).map((id) => reviewLine(t, runs.get(id)!)),
     );
     expect(reviews.length, 'anti-vacuity: the stack exercises a link').toBeGreaterThan(0);
@@ -543,7 +554,7 @@ describe('the notices proven absent leave ③ for one counting line, and --all l
     expect(lines.filter((l) => ABSENT_SCOPE_RE.test(l))).toHaveLength(1);
     expect(indexOf(lines, ABSENT_COUNT_RE)).toBeGreaterThan(indexOf(lines, SEMANTIC_HEADER_RE));
 
-    const headlines = new Set(result.todos.map((t) => blockLines(t)[0]));
+    const headlines = new Set(listedOf(result).map((t) => blockLines(t)[0]));
     for (const t of result.absentTodos) {
       const headline = blockLines(t)[0]!;
       if (headlines.has(headline)) continue; // a listed entry sharing the headline prints it legitimately
@@ -562,26 +573,31 @@ describe('the notices proven absent leave ③ for one counting line, and --all l
     expect(lines.filter((l) => ABSENT_COUNT_RE.test(l) || ABSENT_SCOPE_RE.test(l))).toEqual([]);
     // ③ is unchanged by --all: the same header and the same notices.
     const semantic = indexOf(lines, SEMANTIC_HEADER_RE);
-    expect(lines[semantic]).toBe(`  ${result.todos.length} manual change(s) require your judgment:`);
+    expect(lines[semantic]).toBe(`  ${listedOf(result).length} manual change(s) require your judgment:`);
     expect(lines.slice(semantic + 1, semantic + 1 + noticeLines(result).length)).toEqual(noticeLines(result));
   });
 
-  it('③ and ④ together hold every semantic entry of every hop crossed, each exactly once', () => {
-    const { result } = run(FINDINGS_STACK, MIGRATION_SUPPORT_FLOOR, TERMINUS, undefined, { all: true });
+  it('③ and ④ together print every semantic entry of every hop crossed, each exactly once', () => {
+    const { result, lines } = run(FINDINGS_STACK, MIGRATION_SUPPORT_FLOOR, TERMINUS, undefined, { all: true });
     const crossed = result.hops.flatMap((h) => MIGRATIONS_BY_MAJOR[h.toMajor]!.semantic.map((s) => `${h.toMajor}:${s.id}`));
-    const reported = [...result.todos, ...result.absentTodos].map((t) => `${t.toMajor}:${t.id}`);
-    expect(reported.slice().sort()).toEqual(crossed.slice().sort());
-    expect(new Set(reported).size).toBe(reported.length);
+    // The chain's `todos` is still the whole catalogue; ④ is a subset of it.
+    expect(result.todos.map((t) => `${t.toMajor}:${t.id}`)).toEqual(crossed);
+    for (const t of result.absentTodos) expect(result.todos).toContain(t);
+    const printed = [...listedOf(result), ...result.absentTodos].map((t) => `${t.toMajor}:${t.id}`);
+    expect(printed.slice().sort()).toEqual(crossed.slice().sort());
+    expect(new Set(printed).size).toBe(printed.length);
+    // …and the terminal shows each headline as often as the chain has entries carrying it.
+    const headlineCount = (h: string) => lines.filter((l) => l === h).length;
+    for (const t of result.todos) {
+      const h = blockLines(t)[0]!;
+      expect(headlineCount(h), t.id).toBe(result.todos.filter((u) => blockLines(u)[0] === h).length);
+    }
     // Only an entry carrying a structured question can be in ④.
     for (const t of result.absentTodos) expect(t.relevantWhen, `${t.id} carries relevantWhen`).toBeDefined();
   });
 
   it('prints no ④ at all when the chain proved nothing absent', () => {
-    const { lines } = run(FINDINGS_STACK, MIGRATION_SUPPORT_FLOOR, TERMINUS, (r) => ({
-      ...r,
-      todos: [...r.todos, ...r.absentTodos],
-      absentTodos: [],
-    }));
+    const { lines } = run(FINDINGS_STACK, MIGRATION_SUPPORT_FLOOR, TERMINUS, (r) => ({ ...r, absentTodos: [] }));
     expect(lines.filter((l) => ABSENT_COUNT_RE.test(l) || ABSENT_SCOPE_RE.test(l) || ABSENT_HEADER_RE.test(l))).toEqual([]);
   });
 
@@ -592,7 +608,10 @@ describe('the notices proven absent leave ③ for one counting line, and --all l
         CANONICAL_STACK,
         MIGRATION_SUPPORT_FLOOR,
         TERMINUS,
-        (r) => ({ ...r, todos: [], absentTodos: [...r.todos, ...r.absentTodos].filter((t) => t.relevantWhen) }),
+        (r) => {
+          const questioned = r.todos.filter((t) => t.relevantWhen);
+          return { ...r, todos: questioned, absentTodos: questioned };
+        },
         { out },
       );
       expect(result.applied).toEqual([]);

packages/cli/src/commands/migrate/meta.ts

@@ -210,7 +210,8 @@ function printEmptyRangeAnswer(
   }
 
   const wider = applyMetaMigrations(stack, fromMajor, CHAIN_TERMINUS_MAJOR);
-  if (wider.applied.length === 0 && wider.todos.length === 0) {
+  const widerListed = listedTodos(wider.todos, wider.absentTodos);
+  if (wider.applied.length === 0 && widerListed.length === 0) {
     printInfo(
       `The widest range this build carries (protocol ${fromMajor} → ${CHAIN_TERMINUS_MAJOR}) has `
       + 'nothing for this stack either.',
@@ -220,11 +221,23 @@ function printEmptyRangeAnswer(
 
   printWarning(
     `Protocol ${fromMajor} → ${CHAIN_TERMINUS_MAJOR} has ${wider.applied.length} mechanical and `
-    + `${wider.todos.length} manual change(s) for this stack — re-run with `
+    + `${widerListed.length} manual change(s) for this stack — re-run with `
     + `\`--to ${CHAIN_TERMINUS_MAJOR}\` to list them.`,
   );
 }
 
+/**
+ * The semantic TODOs the default list prints: every entry of `todos` except
+ * the ones `absentTodos` names (ADR-0087 D3 — an entry leaves the default list
+ * only on the chain's structured, stack-derived proof). Matched by hop and id,
+ * so a copy of a TODO is recognised as well as the chain's own object.
+ */
+function listedTodos(todos: readonly MigrationTodo[], absentTodos: readonly MigrationTodo[]): MigrationTodo[] {
+  if (absentTodos.length === 0) return [...todos];
+  const absent = new Set(absentTodos.map((t) => `${t.toMajor}:${t.id}`));
+  return todos.filter((t) => !absent.has(`${t.toMajor}:${t.id}`));
+}
+
 /** Print the data-migration advice — the last thing a crossing upgrade sees. */
 function printPendingDataMigrations(pending: readonly PendingDataMigration[]): void {
   if (pending.length === 0) return;
@@ -348,7 +361,7 @@ function judgesByConversion(todos: readonly MigrationTodo[]): ReadonlyMap<string
  * and lines do not change (ADR-0087 D3, "never silence").
  */
 function printAppliedEdits(result: MigrationChainResult): void {
-  const judges = judgesByConversion(result.todos);
+  const judges = judgesByConversion(listedTodos(result.todos, result.absentTodos));
   console.log(chalk.bold(`  Applied ${result.applied.length} mechanical change(s):`));
   let run = 0;
   for (const [i, a] of result.applied.entries()) {
@@ -429,7 +442,8 @@ function printAbsentNotices(result: MigrationChainResult, all: boolean): void {
  *    the semantic entry that judges an edit printed beside it, marked review
  *    (see {@link printAppliedEdits});
  *  ③ the SEMANTIC notices — every semantic entry of every hop crossed that the
- *    chain could not prove irrelevant to this stack (`todos`);
+ *    chain could not prove irrelevant to this stack (`todos` minus
+ *    `absentTodos`, see {@link listedTodos});
  *  ④ the ABSENT notices — the entries whose structured relevance question
  *    (`SemanticMigration.relevantWhen`) the chain answered `absent` over this
  *    stack (`absentTodos`): one line counting them, or with `--all` each one
@@ -461,9 +475,7 @@ export function printMigrationReport(report: MigrationReport): void {
   // ① The verdict and the refusals — first, whatever else the run found.
   printSchemaVerdict(report);
 
-  // A run whose only notices are proven absent is NOT this branch: it falls
-  // through, so ④ counts them and `--out` is still written.
-  if (result.applied.length === 0 && result.todos.length === 0 && result.absentTodos.length === 0) {
+  if (result.applied.length === 0 && result.todos.length === 0) {
     // ⚠️ Two different facts wear the same empty result, and only one of them
     // is good news (#17134). A range that CONTAINS steps and rewrote nothing
     // is a finding about the metadata. A range that contains no step at all
@@ -494,16 +506,18 @@ export function printMigrationReport(report: MigrationReport): void {
     for (const hop of result.hops) {
       console.log(chalk.bold(`  ── protocol ${hop.toMajor} ──`));
       console.log(chalk.dim(`     ${hop.rationale}`));
+      const listed = listedTodos(hop.todos, hop.absentTodos).length;
       const absent = hop.absentTodos.length > 0 ? `, ${hop.absentTodos.length} not listed (surface absent)` : '';
-      console.log(chalk.dim(`     ${hop.applied.length} mechanical, ${hop.todos.length} manual${absent}`));
+      console.log(chalk.dim(`     ${hop.applied.length} mechanical, ${listed} manual${absent}`));
     }
     console.log('');
   }
 
   // ③ The semantic TODOs (delegated to the agent — never auto-applied).
-  if (result.todos.length > 0) {
-    console.log(chalk.bold(chalk.yellow(`  ${result.todos.length} manual change(s) require your judgment:`)));
-    for (const t of result.todos) printNotice(t);
+  const listed = listedTodos(result.todos, result.absentTodos);
+  if (listed.length > 0) {
+    console.log(chalk.bold(chalk.yellow(`  ${listed.length} manual change(s) require your judgment:`)));
+    for (const t of listed) printNotice(t);
     console.log('');
   }
 
@@ -598,7 +612,7 @@ export default class MigrateMeta extends Command {
     all: Flags.boolean({
       description:
         'Also list, in full, the manual changes whose surfaces this stack provably does not declare '
-        + '(by default they are only counted). --json always carries them, under absentTodos.',
+        + '(by default they are only counted). --json always reports them in todos and names them in absentTodos.',
       default: false,
       exclusive: ['stored'],
     }),
@@ -732,9 +746,9 @@ export default class MigrateMeta extends Command {
               protocolVersion: PROTOCOL_VERSION,
               applied: result.applied,
               todos: result.todos,
-              // The semantic entries the chain proved irrelevant to this stack
-              // (ADR-0087 D3): reported beside `todos`, never dropped, so a
-              // machine consumer reaches them without `--all`.
+              // `todos` keeps every semantic entry; `absentTodos` NAMES the
+              // subset the chain proved irrelevant to this stack (ADR-0087 D3),
+              // so a machine consumer reads the default list as the difference.
               absentTodos: result.absentTodos,
               hops: flags.step
                 ? result.hops.map((h) => ({