fix(cli): a narrowed os migrate --apply records no deployment flag, and an unknown --object is refused (#21662)

Fixes #21644

Clause-②: no

A deployment-level flag is now written only by a full-scope run. `os
migrate value-shapes` and `os migrate files-to-references` narrowed by
`--object` apply their fixes, record no deployment flag, and say so. A
full-scope `--apply` records the flag exactly as before. Across the
family (`value-shapes`, `files-to-references`, `summary-nulls`,
`duplicates`), an `--object` name the deployment does not declare is
refused with `OBJECT_NOT_FOUND` before anything is read or written. The
refusal names the unknown name and the declared objects. This follows
triage ruling `5974774596`. `--apply --object` is not refused.

## Measured first (base `759dbe9ed3`)

### A1. The reach, at the public door (hypothesis confirmed)

A throwaway SQLite project held three objects, one of them
`os21644_site` with a `location` field. A served-shape boot seeded one
clean row per object. Then one off-shape value was written past the
write path: the site's `geo` stored as `{latitude, longitude}`. The
fresh-datastore attestation had recorded both ADR-0104 flags as verified
at birth, so the flag table was emptied first.

- `os migrate value-shapes --json` exited 1, with `gatePassed: false`
and `blocking: 1`.
- `os migrate value-shapes --object os21644_sitee --apply --yes --json`
(misspelled) exited **0**. It answered `gatePassed: true` with
`scannedObjects: []`, and the `adr-0104-value-shapes` row read
**verified** (`verified_at` set, `blocking: 0`).

### A2. The census, one row per command

| command | `--object` | `--apply` records a deployment flag | where it
is written (base) | unknown `--object` on base (measured) |
| --- | --- | --- | --- | --- |
| `value-shapes` | repeatable | `adr-0104-value-shapes` | the CLI:
`recordDataMigrationRun` at `value-shapes.ts:221` | exit 0,
`scannedObjects: []`; with `--apply`, the flag is recorded **verified**
|
| `files-to-references` | repeatable | `adr-0104-file-references`, then
the column step's `columns_moved_at` | the producer:
`runFilesToReferencesMigration` at
`files-to-references-migration.ts:120`; the column stamp is
`recordFileColumnMove` in the CLI (`files-to-references.ts:472`) | exit
0, both scans' `scannedObjects: []`; with `--apply`, the flag is
recorded **verified**, **and the column step moved
`os21644_product.image` and stamped `columns_moved_at`** |
| `summary-nulls` | repeatable | none (its header: "No deployment flag,
deliberately") | none | exit 0, `fields: []`, on a dry run and on
`--apply` |
| `duplicates` | single | none: no `--apply`, and it writes nothing |
none | exit 0, `scanned: []`, `filter: { object: 'os21644_sitee' }` |

A correctly spelled narrowed `files-to-references --apply` on base also
recorded the flag verified and moved the column. Every scan draws its
default candidates from the same registry: `options.objects ??
Object.keys(engine.getConfigs())` in `scanValueShapes`,
`backfillFileReferences`, `verifyFileReferences` and
`backfillSummaryNulls`, and `stack.allObjects()` for
`collectScanTargets`. Each keeps only the candidates it covers, which is
where an undeclared name was dropped.

### A3. The narrowed run

- **CLI-recorded flag (`value-shapes`).** The flag write is skipped on a
narrowed run, whether the run passes or fails. `--json` carries `flag:
null` and `filter: { objects }` (`null` on a full-scope run, the shape
`duplicates` already keeps). Both faces print one sentence: the run was
narrowed, no deployment flag was recorded, and the command that records
one is the same command without `--object`.
- **Producer-recorded flag (`files-to-references`).**
`runFilesToReferencesMigration` skips the write when it is given
`objects`. This is the declared `service-storage` path only. Its `flag`
result is `null` on a narrowed run. The CLI prints the same sentence and
carries `filter`.
- **The column step (`files-to-references`) does not run on a narrowed
run.** The census row above is why. The step retypes every single-value
media column in the database on the authority of the gate, and a
narrowed gate vouches only for the named objects. Its stamp also
requires a verified flag, which a narrowed run no longer records. Left
running, a narrowed `--apply` would move columns and then fail to record
the move. It now returns a stated skip, `narrowed_run`, and the human
face says why.
- **What "narrowed" means.** Any `--object` narrows, even a list that
names every declared object. The flag is earned by the one spelling that
means "every object", which is a run without `--object`. Treating a full
list as full scope would need a second definition of "the whole
deployment", checked against the registry of the moment, and that
registry changes with the composition between two runs. The operator
also gets one unambiguous prescription.
- **Deviation from the dispatch wording ("skips it when `objects` is
non-empty").** The producer treats **any** `objects` as narrowed, `[]`
included. A scan handed `[]` walks nothing (`[] ?? …` is `[]`). A
non-empty test would therefore record a verified flag over an empty
scan, the card's own defect at the producer's API. A unit pin holds
this.
- The prompts and closing lines that promised a flag on a narrowed run
now say it records none. ⛔ `--apply --object` is not refused, and the
full-scope write is unchanged.

### A4. Unknown `--object`

- **Checked against the registry the command's own boot resolved, before
the scan.** For `value-shapes`, `files-to-references` and
`summary-nulls` that registry is `Object.keys(engine.getConfigs())`. For
`duplicates` it is the names of `stack.allObjects()`. These are the same
sets the scans draw from, so the refusal and the scan judge one
population. There is no `packages/objectql` edit and no scanner edit.
- **The refusal is #21643's.** It is `objectNotFoundError` from
`@objectstack/core`: `code: 'OBJECT_NOT_FOUND'`, `status: 404`, and
`object` naming the first unknown name. Its message names every unknown
name and the declared objects, sorted. There is no new error code.
`value-shapes`, `files-to-references` and `summary-nulls` answer `{
error, code }`, as `unmapped-columns` does. `duplicates` keeps its own
error shape, `{ error: 'report_failed', detail, code }`: its catch now
passes `errorCodeFields` through.
- **The list is the declared set, not the covered subset.** Computing
the covered subset for `value-shapes` needs
`isScannableValueShapeField`, which `@objectstack/objectql` does not
export, and that package is fenced. The declared set is also exactly the
accept set. A declared object the command has nothing to check on is
accepted, because an empty answer about a real object is true. On the
fixture boot the list is 12 names, platform objects included.
- **Clause-②: no stands as the claim declared it.** A misspelled name
moves from exit 0 to exit 1, which is the ruled correction of a wrong
answer. Every declared name and `--apply --object` are still accepted.

## Changes

- `packages/cli/src/utils/migrate-object-scope.ts` (new):
`refuseUndeclaredObjects`, `isNarrowedRun` and `narrowedFlagNote`,
shared by the four commands.
- `packages/cli/src/commands/migrate/value-shapes.ts`: refuses an
unknown name, skips the flag on a narrowed run, adds `filter`, and
adjusts the narrowed prompt and closing lines.
- `packages/cli/src/commands/migrate/files-to-references.ts`: refuses an
unknown name, adds the `narrowed_run` column-step skip, adds `filter`,
and adjusts the narrowed prompt and closing lines.
- `packages/cli/src/commands/migrate/summary-nulls.ts` and
`duplicates.ts`: refuse an unknown name. `duplicates`' error document
carries the error's `code`.
-
`packages/services/service-storage/src/files-to-references-migration.ts`:
skips the flag write when given `objects`.
- `content/docs/deployment/cli.mdx`: one paragraph under "Data
migrations" (`--object` narrows, an unknown name is refused, only a
full-scope run records a flag), and the two `--object` example comments.
- `.changeset/21644-narrowed-apply-flag.md`: `@objectstack/cli` patch
and `@objectstack/service-storage` patch, `Clause-②: no`.

`packages/objectql`, `packages/platform-objects`, `packages/spec`, every
other `service-storage` path, and `content/docs/releases/` are
untouched.

## Pins

- **`object-scope.integration.test.ts`** spawns the CLI against SQLite,
one database copy per run, and is one enumeration over the census
(`FAMILY`).
- A narrowed `--apply` (`value-shapes`, `files-to-references`): exit 0,
`flag: null`, `filter: { objects }`, no flag row, and the note on stderr
naming the full-scope command.
- A full-scope `--apply`: the flag recorded verified, in the document
and in the row.
- `summary-nulls` and `duplicates`: no flag row, narrowed or not, as
before.
- A narrowed `--apply` after an earned flag leaves that row byte-equal.
- `files-to-references` narrowed: `columnMove: null` and
`columnsMovedAt: null`. Its full-scope control moves
`os21644_product.image` and stamps it.
- Unknown `--object`, on all four: exit 1 and `OBJECT_NOT_FOUND`, naming
the name and the declared objects. The one document is the refusal and
no report, no flag row is written, and the app rows are unchanged. The
human face exits 1 and names it.
- The measured repro. Control: the full-scope scan sees `blocking: 1`
and exits 1. The misspelled `--object --apply` exits 1 with
`OBJECT_NOT_FOUND`, and the flag stays unrecorded. Spelled right, the
narrowed run finds the value, exits 1, and still records no flag.
- **`migrate-object-scope.test.ts`** (unit): the envelope (`code`,
`status`, `object`), every unknown name named once, the declared list
sorted, the empty-registry message, the accepted cases, and what
`isNarrowedRun` treats as narrowed (an empty list and a full list both
narrow).
- **`files-to-references-migration.test.ts`** (`service-storage`, beside
the producer):
  - a narrowed apply converts and records no flag;
  - a narrowed failing apply records nothing;
  - a narrowed apply leaves an earned flag row equal;
  - `objects: []` records nothing.

## Reverse verification (implementation committed first; all three legs
re-run at the final head `fe988c20f0`)

Each leg ran through `node scripts/ablation-replace.mjs` in wrap mode,
under a script trap that restores from `HEAD`. The spawned CLI loads its
commands from `src/` through `bin/run-dev.js`. In the first round
`packages/cli/dist` did not exist. In the final round it held a build of
the unmutated source, and legs 1a and 2 still went red, which shows the
spawned CLI read the mutated `src/`. The `service-storage` unit pin
imports the producer from `src/`. Neither needed a rebuild.

- **Leg 1a, the narrowed-run skip in the CLI** (`value-shapes.ts`):
- The anchor `if (apply && !narrowed) {` became `if (apply) {`: anchor 1
to 0, replacement 0 to 1, blob `9f241dc2` to `d3a5c236`.
- **3 red, 17 green.** Red: the `value-shapes` narrowed pin, the
earned-flag-unchanged pin, and the spelled-right repro. Green: both
full-scope controls (the column-step control among them), the
`files-to-references` narrowed pin (its skip is the producer's), and
every unknown-name pin.
- Restored: blob `9f241dc2` equals `HEAD`, and `git diff HEAD` is empty.
- **Leg 1b, the narrowed-run skip in the producer**
(`files-to-references-migration.ts`):
- The same anchor and replacement: anchor 1 to 0, blob `1aa9fea2` to
`d4bb5002`.
- **4 red, 6 green.** Red: all four narrowed pins (passing, failing,
earned-flag-unchanged, and `objects: []`). Green: the six original pins,
the full-scope apply among them.
  - Restored: blob `1aa9fea2` equals `HEAD`.
- **A first round is recorded here because one of its readings was
vacuous.** At `80e5eda6ea` this leg read 3 red and 7 green: the
earned-flag-unchanged pin stayed green under the mutation, because the
fake engine's rewrite landed in the same millisecond as the earned row.
The pin now dates the earned row in the past (`fe988c20f0`), and the
re-run is the reading above.
- **Leg 2, the unknown-name refusal** (`migrate-object-scope.ts`):
- The anchor `if (unknown.length === 0) return;` became `if
(unknown.length >= 0) return;`: anchor 1 to 0, replacement 0 to 1, blob
`b78a88b4` to `9286a990`.
- **Unit: 3 red, 3 green.** Red: the three refusal cases. Green: the
accepted cases and the two `isNarrowedRun` cases.
- **Integration: 10 red, 10 green.** Red: all eight unknown-name pins
(two per command, on all four), the human face, and the misspelled
repro. Green: every narrowed and full-scope pin, and the repro's
control.
  - Restored: blob `b78a88b4` equals `HEAD`.
- In the first round, the `duplicates` "refused before anything was
read" pin stayed green under this mutation: it asserted only on a key
that report never carries. It now asserts that the one document is the
refusal, which reds on all four commands.

After all legs, `git diff HEAD` was empty and `git status --porcelain`
was clean.

## Local verification (final head `fe988c20f0`, on base `759dbe9ed3`)

`origin/main` was `759dbe9ed3` for the whole verification. Just before
this PR opened, it gained four commits, `f40bb3217f` to `1a230548cf`
(#21649, #21632, #21648, #21650). None of them touches this diff's paths
(`packages/spec`, `metadata-protocol`, `service-automation`, `lint`,
skills and docs references), so they were not merged in. CI runs on the
merge ref.

- **Builds.** The CLI's dependency closure (`turbo run build
--filter=@objectstack/cli^...`) gave VERDICT 0.
`@objectstack/service-storage` was rebuilt after the producer change
(exit 0), and `@objectstack/cli` was built (exit 0). A repo build for
the gate prerequisites gave VERDICT 0 (turbo: 72 tasks, 71 cached).
- **`@objectstack/cli` typecheck** (`tsc --noEmit` plus
`check:test-typecheck`): exit 0 at `80e5eda6ea`. No CLI file changed
after that commit.
- **`@objectstack/cli` unit project in full** at `80e5eda6ea`:
- 255 of 257 files passed, with 3742 tests passed and 29 skipped (the
two files below).
- The other two files,
`test/published-subpath-{console,hook-body}.pin.test.ts`, refused before
testing because `packages/cli` was not built (their own prerequisite
message). After the CLI build, both passed: 2 files, 29 tests.
- **`@objectstack/service-storage`**: typecheck exit 0, and the full
suite at `fe988c20f0` passed 41 files and 633 tests.
- **`os migrate` integration pins on built packages**, at `80e5eda6ea`:
  - this PR's pin plus the absent-database roster: 2 files, 59 passed;
- the one-shot family plus `duplicates.integration`: 2 files, 79 passed.
- **Gates.** `node scripts/pm/dispatch-gates.mjs --commands --repo
objectstack-ai/objectstack` (no paths) derived 97 commands at
`fe988c20f0`.
  - All 97 ran there, and each exited 0.
- `--ran` with exit codes: 97 derived, 97 run, 0 NOT-MEASURED, 0 UNRUN.
- An earlier round at `80e5eda6ea` had three gates answer `PREREQUISITE
NOT MET` (exit 3): `check:skill-examples`, `check:dual-build-cjs-loads`
and `check:i18n-coverage`. They read packages outside the CLI closure.
The repo build cleared them.
- **Full `pnpm lint`** (`eslint . --no-inline-config` over the whole
repo): exit 0 at `fe988c20f0`, with nothing printed.
- **No exported symbol was renamed or moved,** so the liveness-ledger
anchor check had nothing to read.

## Acceptance notes

- **A narrowed run's counterexample is not recorded.** The ruling says a
narrowed `--apply` records no flag, so it records none even when it
finds a violation. Such a counterexample is deployment-level evidence,
since one off-shape value disproves "every value is on shape". The
operator still gets exit 1 and the findings, and the next full-scope run
closes the gate. This is an observation, not a filing. Carrier: none.
- **The declared list includes platform objects.** It is 12 names on the
fixture's lean boot, and a deployment that composes more plugins prints
more. A long list in an error message is the price of naming the exact
accept set. Carrier: none.
- **A narrowed `value-shapes --apply` still takes the plain
(DDL-performing) boot** even though it now writes nothing. That is
unchanged, and the boot paragraph in the docs still describes it
truthfully. Carrier: none.

---
_Generated by [Claude
Code](https://claude.ai/code/session_016GiHYRmLSNWTfbX9gVQkpz)_

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: objectstack-fleet[bot]

.changeset/21644-narrowed-apply-flag.md

@@ -0,0 +1,13 @@
+---
+'@objectstack/cli': patch
+'@objectstack/service-storage': patch
+---
+
+`os migrate value-shapes` and `os migrate files-to-references` record the deployment-level ADR-0104 flag only from a run over every object, and every command in the `os migrate` data-migration family refuses an `--object` name the deployment does not declare (#21644).
+
+Clause-②: no
+
+- **A narrowed `--apply` records no deployment flag.** The flag attests the stored data of every object and turns strict enforcement on, but a run narrowed by `--object` reads only the named objects. Such a run still applies its fixes: `files-to-references` converts the named objects' values. It records no flag, whether it passes or fails, and leaves a flag that an earlier full-scope run recorded exactly as it was. Its output says why and names the run that records the flag: the same command without `--object`. The `--json` document carries `filter: { objects }`, which is `null` on a full-scope run, so a narrowed run is never mistaken for a full one. Any `--object` narrows, even a list that names every object. A full-scope `--apply` records the flag as before.
+- **`runFilesToReferencesMigration`** (`@objectstack/service-storage`) skips the flag write when it is given `objects`. That includes `[]`, which walks nothing. Its `flag` result is `null` on a narrowed run.
+- **The column step of `files-to-references` does not run on a narrowed run.** It retypes every single-value media column in the database on the authority of the gate, and a narrowed gate vouches only for the named objects. Before this change, a narrowed `--apply` or a misspelled one moved those columns and stamped `columns_moved_at`.
+- **An unknown `--object` is an error.** This applies to `value-shapes`, `files-to-references`, `summary-nulls` and `duplicates`. A name the booted registry does not declare exits 1 with `OBJECT_NOT_FOUND`, and the error names that name and the declared objects. The check runs before anything is read or written. Until now, such a name was filtered out of the scan without a word, so a typo scanned nothing and read as a clean run. `duplicates` reports the refusal as `{ error: 'report_failed', detail, code }`. A declared object that the command has nothing to check on is still accepted.

content/docs/deployment/cli.mdx

@@ -1132,11 +1132,25 @@ report no secret and no file. A read the command cannot avoid and that fails for
 other reason still refuses and exits 1. Point `--database-url` at the deployment's
 database, or boot the deployment once first, to see what it holds.
 
+**`--object` narrows a run, and only a run over every object records a flag.**
+`files-to-references`, `value-shapes`, `summary-nulls` and `duplicates` take
+`--object` to restrict the run to the objects you name. `duplicates` takes one name,
+and the others are repeatable. A name your deployment does not declare is refused
+with `OBJECT_NOT_FOUND` and exit 1 before anything is read or written. The error
+names the unknown name and the declared objects, so a misspelling is never answered
+as a clean run over nothing. A narrowed `--apply` applies its fixes to the named
+objects. `files-to-references` and `value-shapes` then record **no** deployment flag,
+because the flag is a claim about every object's stored data and a narrowed run read
+only some. A narrowed `files-to-references` run does not move the media columns
+either. The output says so, a flag that an earlier full run recorded is left as it
+was, and `--json` carries `filter: { objects }`. Any `--object` narrows, even a list
+that names every object, so run the command without `--object` to record the flag.
+
 ```bash
 os migrate files-to-references            # Dry run: full report, writes nothing
 os migrate files-to-references --apply    # Convert, verify, record the flag (prompts)
 os migrate files-to-references --apply --yes --json   # CI / scripts
-os migrate files-to-references --object product       # Restrict to one object (repeatable)
+os migrate files-to-references --object product       # Restrict to one object (repeatable); records no flag
 ```
 
 A `file` / `image` / `avatar` / `video` / `audio` field value is an opaque
@@ -1189,7 +1203,7 @@ The same gate for the **non-media** value classes — references (`lookup`,
 os migrate value-shapes                    # Scan: full report, writes nothing
 os migrate value-shapes --apply            # Scan, then record the flag if clean (prompts)
 os migrate value-shapes --apply --yes --json   # CI / scripts
-os migrate value-shapes --object contact       # Restrict to one object (repeatable)
+os migrate value-shapes --object contact       # Restrict to one object (repeatable); records no flag
 ```
 
 **This one converts nothing.** Its sibling rewrites legacy file values because

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

@@ -1,8 +1,9 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { Command, Flags } from '@oclif/core';
-import { emitJson, isExitSignal } from '../../utils/format.js';
+import { emitJson, errorCodeFields, isExitSignal } from '../../utils/format.js';
 import { bootSchemaStack } from '../../utils/schema-migrate.js';
+import { refuseUndeclaredObjects } from '../../utils/migrate-object-scope.js';
 // The `objectql` slot's contract (#4251) — read the registry through it rather
 // than erasing the lookup to `any`, so a rename breaks this at compile time
 // instead of silently reporting zero objects.
@@ -874,7 +875,9 @@ export default class MigrateDuplicates extends Command {
       env: 'OS_DATABASE_URL',
     }),
     object: Flags.string({
-      description: 'Restrict the scan to one object (recorded in the report, so a narrowed run cannot be mistaken for a full one)',
+      description:
+        'Restrict the scan to one object (recorded in the report, so a narrowed run cannot be mistaken for a full ' +
+        'one). A name the deployment does not declare is refused',
     }),
   };
 
@@ -906,6 +909,18 @@ export default class MigrateDuplicates extends Command {
     }
 
     try {
+      // [#21644] `collectScanTargets` keeps only the objects it would probe, so
+      // a name this registry does not declare would be dropped without a word
+      // and the report would read "no duplicates" over a scan of nothing.
+      // Refused before any probe, against the set the scan draws from.
+      refuseUndeclaredObjects(
+        flags.object === undefined ? undefined : [flags.object],
+        stack
+          .allObjects()
+          .map((o) => (o as { name?: unknown } | null)?.name)
+          .filter((name): name is string => typeof name === 'string'),
+      );
+
       const {
         resolveSeedTenancyExec,
         normalizeRows,
@@ -973,7 +988,11 @@ export default class MigrateDuplicates extends Command {
       await emitJson(report);
     } catch (error: unknown) {
       if (isExitSignal(error)) throw error;
-      await emitJson({ error: 'report_failed', detail: messageOf(error) }, 1, { compact: true });
+      await emitJson(
+        { error: 'report_failed', detail: messageOf(error), ...errorCodeFields(error) },
+        1,
+        { compact: true },
+      );
     } finally {
       await stack.shutdown();
     }

packages/cli/src/commands/migrate/files-to-references.ts

@@ -21,6 +21,7 @@ import { bootSchemaStack } from '../../utils/schema-migrate.js';
 import { OCCUPANCY_HINT, probeMigrationTarget } from '../../utils/migrate-occupancy-gate.js';
 import { describeOccupancy } from '../../utils/sqlite-occupancy.js';
 import { buildDataMigrationPlugins } from '../../utils/data-migration-plugins.js';
+import { isNarrowedRun, narrowedFlagNote, refuseUndeclaredObjects } from '../../utils/migrate-object-scope.js';
 import {
   describeFileColumnMoveRefusal,
   runFileColumnMove,
@@ -41,6 +42,7 @@ import type { MediaColumnMoveScan, SqlDialectName } from '@objectstack/driver-sq
 interface ColumnStepOutcome {
   skipped:
     | 'gate_not_passed'
+    | 'narrowed_run'
     | 'no_sql_driver'
     | 'no_sql_seam'
     | 'driver_cannot_plan'
@@ -96,11 +98,19 @@ async function confirm(question: string): Promise<boolean> {
  * Dry run by default, and a dry run writes NOTHING — not conversions, not the
  * flag. Not run / not passed → files keep being retained forever: storage
  * cost, zero data loss.
+ *
+ * [#21644] Only a run over every object records the flag or moves the
+ * columns. A run narrowed by `--object` converts the named objects' values and
+ * stops there: the producer records no flag for it, and the column step, which
+ * retypes every media column in the database on the strength of the gate,
+ * does not run. A name the deployment does not declare is refused
+ * (`OBJECT_NOT_FOUND`) rather than scanned as nothing.
  */
 export default class MigrateFilesToReferences extends Command {
   static override description =
     'Migrate legacy file-field values to sys_file references and verify the ownership ledger (ADR-0104). ' +
-    'Dry-run by default; --apply also records the deployment-level migration flag when the self-check passes.';
+    'Dry-run by default; --apply also records the deployment-level migration flag when the self-check of every ' +
+    'object passes.';
 
   static override examples = [
     '$ os migrate files-to-references',
@@ -117,7 +127,8 @@ export default class MigrateFilesToReferences extends Command {
     }),
     apply: Flags.boolean({
       description:
-        'Write the conversions and record the deployment migration flag (default is a read-only dry run)',
+        'Write the conversions and record the deployment migration flag (default is a read-only dry run). ' +
+        'Only a run without --object records the flag',
       default: false,
     }),
     yes: Flags.boolean({ char: 'y', description: 'Skip the --apply confirmation prompt', default: false }),
@@ -126,7 +137,9 @@ export default class MigrateFilesToReferences extends Command {
       default: false,
     }),
     object: Flags.string({
-      description: 'Restrict to this object (repeatable; default: every object with a file field)',
+      description:
+        'Restrict to this object (repeatable; default: every object with a file field). A narrowed run converts ' +
+        'but records no deployment flag and moves no column, and a name the deployment does not declare is refused',
       multiple: true,
     }),
     'max-records': Flags.integer({
@@ -144,6 +157,7 @@ export default class MigrateFilesToReferences extends Command {
     const { flags } = await this.parse(MigrateFilesToReferences);
     const timer = createTimer();
     const apply = flags.apply;
+    const narrowed = isNarrowedRun(flags.object);
 
     if (!flags.json) {
       printHeader('Migrate · files-to-references');
@@ -197,7 +211,12 @@ export default class MigrateFilesToReferences extends Command {
         return;
       }
       const ok = await confirm(
-        chalk.bold('\nConvert legacy file values and record the migration flag on this database? [y/N] '),
+        chalk.bold(
+          narrowed
+            ? '\nConvert legacy file values of the named object(s) on this database? ' +
+                'A run narrowed by --object records no deployment flag. [y/N] '
+            : '\nConvert legacy file values and record the migration flag on this database? [y/N] ',
+        ),
       );
       if (!ok) {
         printInfo('Aborted — no changes made.');
@@ -248,6 +267,13 @@ export default class MigrateFilesToReferences extends Command {
             'Run "os build" in your project root first (the migration reads dist/objectstack.json), then re-run.',
         );
       }
+      // [#21644] Before anything is converted: the scan keeps only the
+      // candidates it covers, so a name this registry does not declare would
+      // be dropped without a word, and the run would read as clean.
+      refuseUndeclaredObjects(flags.object, loadedObjects);
+      const narrowedNote = isNarrowedRun(flags.object)
+        ? narrowedFlagNote('files-to-references', flags.object, apply)
+        : null;
       const getStorage = () => {
         try {
           // Canonical slot since #9683 (service-storage also registers the
@@ -293,13 +319,18 @@ export default class MigrateFilesToReferences extends Command {
         engine,
         apply,
         gatePassed: result.gatePassed,
+        narrowed,
         json: flags.json,
       });
 
       if (flags.json) {
+        if (narrowedNote) logger.info(narrowedNote);
         await emitJson({
           database: stack.dbLabel,
           apply,
+          // [#21644] Recorded in the document, so a narrowed run cannot be
+          // mistaken for a full one (the shape `os migrate duplicates` keeps).
+          filter: narrowed ? { objects: flags.object } : null,
           backfill: {
             scannedObjects: result.backfill.scannedObjects,
             scannedRecords: result.backfill.scannedRecords,
@@ -341,7 +372,23 @@ export default class MigrateFilesToReferences extends Command {
       console.log(formatFileReferenceReport(result.verify));
       console.log('');
 
-      if (result.gatePassed) {
+      if (narrowedNote) {
+        // [#21644] Every sentence below would promise the flag or the
+        // enforcement it turns on, and a narrowed run records neither.
+        if (!result.gatePassed) {
+          for (const failure of result.gateFailures) printError(`Gate not passed: ${failure}`);
+          printWarning('Fix the records listed above, then re-run.');
+        } else if (apply) {
+          printSuccess('Self-check passed over the named object(s); their conversions are written.');
+        } else if (result.backfill.converted > 0) {
+          printInfo(
+            `Dry run only — ${result.backfill.converted} value(s) would be converted. Re-run with --apply to convert.`,
+          );
+        } else {
+          printInfo('Data in the named object(s) is already in reference form.');
+        }
+        printInfo(narrowedNote);
+      } else if (result.gatePassed) {
         if (apply) {
           printSuccess(
             'Self-check passed — deployment flag recorded (adr-0104-file-references). ' +
@@ -398,15 +445,23 @@ export default class MigrateFilesToReferences extends Command {
     engine: unknown;
     apply: boolean;
     gatePassed: boolean;
+    narrowed: boolean;
     json: boolean;
   }): Promise<ColumnStepOutcome> {
-    const { stack, apply, gatePassed, json } = args;
+    const { stack, apply, gatePassed, narrowed, json } = args;
 
     if (!gatePassed) {
       // ⛔ The ruling's "abort unless backfill + verify report zero blocking".
       // Not an error of this step's own — the gate already reported why.
       return { skipped: 'gate_not_passed', failed: false, stampedAt: null, report: null };
     }
+    if (narrowed) {
+      // [#21644] ⛔ The move retypes EVERY single-value media column in the
+      // database, and a narrowed gate vouched for the named objects only. Its
+      // stamp also requires the verified flag a narrowed run does not record,
+      // so running it here would move columns it then could not record.
+      return { skipped: 'narrowed_run', failed: false, stampedAt: null, report: null };
+    }
     if (!stack.driver || typeof stack.driver.planMediaColumnMove !== 'function') {
       return { skipped: 'no_sql_driver', failed: false, stampedAt: null, report: null };
     }
@@ -503,7 +558,12 @@ export default class MigrateFilesToReferences extends Command {
   /** The human-mode half of {@link runColumnStep}. JSON mode reports the same facts. */
   private renderColumnStep(outcome: ColumnStepOutcome): void {
     if (outcome.skipped === 'gate_not_passed' || outcome.report === null) {
-      if (outcome.skipped === 'no_sql_driver') {
+      if (outcome.skipped === 'narrowed_run') {
+        printInfo(
+          'Column step: not run — it moves every media column in the database, so only a run without ' +
+            '--object authorises it.',
+        );
+      } else if (outcome.skipped === 'no_sql_driver') {
         printInfo(
           'Column step: not applicable — the ADR-0104 file-family column move is a SQL-driver step ' +
             'and no SQL driver is active here.',