@@ -0,0 +1,21 @@
+---
+'@objectstack/objectql': patch
+'@objectstack/cli': patch
+---
+
+feat(objectql, cli)!: the record-currency code backfill runs one organization at a time, and the home-amount recompute takes the same organization filter
+
+Clause-②: yes (narrowing) — `backfillRecordCurrencyCodes` (and `os migrate record-currency-codes`) given no organization over the rows of more than one organization is refused with `400 VALIDATION_ERROR` (`field: 'organizationId'`) before any write, where it wrote the one code into every organization's codeless rows; widened beside it: the optional `organizationId` and `allOrganizations` options and the `--org` / `--all-organizations` flags, and `recomputeHomeAmounts`'s optional `organizationId` with `os migrate recompute-home-amounts --org`.
+Metadata-protocol: none
+
+<!-- adr-0087: not-required (no-migration-prescription) no key of any schema is added, removed or re-shaped and no stored row is converted: an operator's run of a data command over several organizations is refused until it names its scope, which is a choice of currency per organization made by hand, not a mechanical conversion -->
+
+**BREAKING** for an operator who runs `os migrate record-currency-codes` (or calls `backfillRecordCurrencyCodes`) without naming an organization on a database whose rows of that object belong to more than one organization.
+
+- **Why (ADR-0144 Open item 13).** Each organization has its own home currency (`localization.currency`), so the one code a run writes is right for the rows of at most the organizations that use it. Before this release the run wrote it into every organization's codeless rows, silently wrong for the others.
+- **One organization.** `--org ID` (`organizationId`) fills only that organization's rows: the walk and every write run under `{ isSystem: true, tenantId: ID }`, and the walk also filters on each row's own `organization_id`, because the system context alone narrows the driver only under a walled tenancy posture. The report counts per organization (`organizations`).
+- **Refused, and what it says.** With neither `--org` nor `--all-organizations`, the rows are first counted read-only; when they belong to more than one organization the run (a dry run as well as `--apply`) exits 1 before any write. The refusal lists each organization's codeless row count, and under `--json` carries them in `organizations`. The code is still never derived: no organization's `localization.currency` is read to pick one (ADR-0144 D8 rule 4).
+- **Every organization, explicitly.** `--all-organizations` (`allOrganizations: true`) writes the one code into every organization's codeless rows, as an unscoped run did before. `--org` with `--all-organizations` is a usage error; the engine refuses both options together with `400 VALIDATION_ERROR`.
+- **Unchanged.** A database whose rows of the object belong to one organization, or name none, runs exactly as before, with the same report text.
+- **The recompute.** `os migrate recompute-home-amounts --org ID` (`recomputeHomeAmounts`'s `organizationId`) limits the run to that organization's rows, read and written as it, and records the organization in the run's audit entry. Without it the run still covers every organization, each in its own home currency, and is never refused for that: it writes no value the operator chose. Its `code_blank` remedy now names `--org`.
+- **Who moves, and the fix.** A script that ran the backfill once over a multi-organization database runs it once per organization with `--org ID` and the code that organization's rows are in, or adds `--all-organizations` when one code really is right for all of them.
@@ -141,7 +141,12 @@ a grouped aggregate, and sits outside every filter on the pair until it holds a
 The code is the one you give with `--code`, and it is never derived: not from the
 `defaultCurrency` the field had under `fixed`, not from the organization's currency.
 One run writes one code, so if the stored amounts are in more than one currency, split
-those rows with your own writes first. See
+those rows with your own writes first. Each organization has its own home currency, so
+on a database whose rows belong to more than one organization, run it once per
+organization with `--org <id>` and the code that organization's rows are in: a run
+naming no organization there is refused before any write and lists each organization's
+codeless row count, and `--all-organizations` writes the one code into every
+organization's rows when it really is right for all of them. See
 [`os migrate record-currency-codes`](/docs/deployment/cli#os-migrate-record-currency-codes).
 
 ### Aggregating a record-mode amount
@@ -362,8 +367,8 @@ lists every row that changes, with its stored and new values.
 of 1, a later rate or a zero. The report names each one and why: no rate in force on its
 document date (add the rate), an amount with no currency code (run
 [`os migrate record-currency-codes`](#switching-a-field-that-already-holds-rows) first: no
-rate can help a row that names no currency; it writes its one code into every
-organization's codeless rows, so check the per-organization count first), no document date, or no home currency. Until
+rate can help a row that names no currency; give it `--org` for each organization's
+code), no document date, or no home currency. Until
 a re-run converts them, a total over the home field leaves those rows out, so the command
 keeps exiting 1 while any is listed, and the applied run's audit entry records them. The
 full reference is [`os migrate recompute-home-amounts`](/docs/deployment/cli#os-migrate-recompute-home-amounts).
 
@@ -1623,6 +1623,7 @@ covers the switch). This command writes the code into those rows.
 ```bash
 os migrate record-currency-codes --object opportunity --field amount --code USD          # Dry run: counts the rows, writes none
 os migrate record-currency-codes --object opportunity --field amount --code USD --apply  # Write the code (prompts)
+os migrate record-currency-codes --object opportunity --field amount --code EUR --org org_emea --apply   # One organization
 os migrate record-currency-codes --object opportunity --field amount --code USD --apply --yes --json   # CI / scripts
 ```
 
@@ -1634,6 +1635,21 @@ anything else. A row that holds a code is never touched, whatever the code, and
 with no amount owes none. If the stored amounts are in more than one currency, split
 them with your own writes first: nothing here can tell those rows apart.
 
+**One organization at a time.** Each organization has its own home currency, so one
+code is right for the rows of at most the organizations that use it. `--org <id>` fills
+only that organization's rows: the walk and every write run as that organization, and
+the walk filters on each row's own `organization_id`. When the object's rows belong to
+**more than one organization** and you give neither `--org` nor `--all-organizations`,
+the run (a dry run as well as `--apply`) is refused with `VALIDATION_ERROR` / 400 and
+exit 1 before any row is written, and the refusal lists each organization's codeless
+row count; under `--json` they are in its `organizations` array. Re-run with `--org`
+once per organization, each with the code its rows are in. `--all-organizations` is
+the explicit way to write the one code into every organization's codeless rows, and
+the report then counts each organization apart. `--org` and `--all-organizations`
+together are a usage error. When the rows belong to one organization (or name none),
+the run behaves as it always did. The command never reads an organization's
+`localization.currency` to pick a code for you.
+
 **A bad `--code` is refused before anything is opened.** A code that is not an
 uppercase ISO 4217 code (`usd`, `EURO`) is refused with `INVALID_FIELD` / 400 and
 exit 1 before the database is probed, the `--apply` prompt is shown or the app is
@@ -1658,6 +1674,7 @@ report.
 ```bash
 os migrate recompute-home-amounts --object invoice                               # Dry run: reports, writes none
 os migrate recompute-home-amounts --object invoice --since 2026-01-01            # Documents dated on or after Jan 1 only
+os migrate recompute-home-amounts --object invoice --org org_emea                # One organization's rows only
 os migrate recompute-home-amounts --object invoice --field amount --apply        # Write (prompts)
 os migrate recompute-home-amounts --object invoice --apply --yes --json          # CI / scripts
 ```
@@ -1683,7 +1700,10 @@ one amount; without it, every amount of the object that declares a home amount i
 recomputed. `--since YYYY-MM-DD` keeps the rows whose **document date** (the field
 `homeAmount.rateDate` names, the date that picks the rate) is on or after that day, a
 `datetime` read as its day in the organization's timezone; a row with no document date is
-outside every `--since` window. A malformed `--since` is refused with `VALIDATION_FAILED` /
+outside every `--since` window. `--org <id>` limits the run to one organization's rows,
+read and written as that organization; without it the run covers every organization,
+each in its own home currency, and is never refused for that (it writes no value you
+chose). A malformed `--since` is refused with `VALIDATION_FAILED` /
 400 before the database is opened; an object the deployment does not declare
 (`OBJECT_NOT_FOUND`), or one or a `--field` that declares no home amount (`INVALID_FIELD`),
 is refused after the boot and before any row is read.
@@ -1693,7 +1713,7 @@ is refused after the boot and before any row is read.
 | Reason | The row | Fix, then re-run |
 |:---|:---|:---|
 | `rate_missing` | No rate for its currency is in force on its document date (the report names both). | Add the rate. |
-| `code_blank` | An amount with no currency code: stored before the field switched to record mode. | [`os migrate record-currency-codes`](#os-migrate-record-currency-codes). It writes its one code into the codeless rows of **every** organization, so check the report's `code_blank` count per organization first. |
+| `code_blank` | An amount with no currency code: stored before the field switched to record mode. | [`os migrate record-currency-codes`](#os-migrate-record-currency-codes) with `--org`, once per organization, each with the code its rows are in; the report's `code_blank` count per organization says which ones owe codes. |
 | `document_date_blank` | A foreign-currency amount with no document date. | Fill the document date. |
 | `home_currency_unset` | Its organization has no `localization.currency`. | Set **Localization → Default currency**. |
 | `unconvertible` | A code, amount or document date the write itself refuses. | Correct the value. |
 
@@ -133,6 +133,13 @@ describe('os migrate recompute-home-amounts', () => {
     expect(json()).toMatchObject({ apply: false, report: { changed: 1, written: 0 } });
   }, RUN_TIMEOUT);
 
+  it('--org hands that organization to recomputeHomeAmounts as its filter; without it, none (every organization)', async () => {
+    await MigrateRecomputeHomeAmounts.run(['--json', '--object', 'invoice', '--org', 'org_b'], { root: CLI_ROOT });
+    expect(vi.mocked(recomputeHomeAmounts).mock.calls[0]![2]).toMatchObject({ object: 'invoice', organizationId: 'org_b' });
+    await MigrateRecomputeHomeAmounts.run(['--json', '--object', 'invoice'], { root: CLI_ROOT });
+    expect(vi.mocked(recomputeHomeAmounts).mock.calls[1]![2]).toHaveProperty('organizationId', undefined);
+  }, RUN_TIMEOUT);
+
   it('--apply --yes writes, on the plain boot', async () => {
     await MigrateRecomputeHomeAmounts.run(['--json', '--apply', '--yes', '--object', 'invoice'], { root: CLI_ROOT });
     expect(vi.mocked(recomputeHomeAmounts).mock.calls[0]![2]).toMatchObject({ apply: true });
 
@@ -60,6 +60,12 @@ async function confirm(question: string): Promise<boolean> {
  * and keep the command's exit code at 1 until a re-run converts them
  * (ADR-0144 Open item 8). Idempotent: a re-run with nothing listed is the
  * verification. No `sys_migration` flag is recorded: nothing gates on the run.
+ *
+ * `--org <id>` limits the run to one organization's rows, the same flag
+ * `os migrate record-currency-codes` takes (ruling 6670707546 item 3), handed
+ * to `recomputeHomeAmounts` as its organization filter. Without it the run
+ * covers every organization, each in its own home currency, and is never
+ * refused for it: a recompute writes no value the operator chose.
  */
 export default class MigrateRecomputeHomeAmounts extends Command {
   static override description =
@@ -70,6 +76,7 @@ export default class MigrateRecomputeHomeAmounts extends Command {
   static override examples = [
     '$ os migrate recompute-home-amounts --object invoice',
     '$ os migrate recompute-home-amounts --object invoice --since 2026-01-01',
+    '$ os migrate recompute-home-amounts --object invoice --org org_emea',
     '$ os migrate recompute-home-amounts --object invoice --field amount --apply',
     '$ os migrate recompute-home-amounts --object invoice --apply --yes --json',
   ];
@@ -89,6 +96,10 @@ export default class MigrateRecomputeHomeAmounts extends Command {
         'date, YYYY-MM-DD. A datetime document date is read as its calendar day in the organization\'s timezone; ' +
         'a row with no document date is outside every --since window',
     }),
+    org: Flags.string({
+      description:
+        'Only this organization\'s rows (its id). Default: every organization, each in its own home currency',
+    }),
     apply: Flags.boolean({
       description: 'Write the recomputed home amounts and rates (default is a read-only dry run)',
       default: false,
@@ -168,8 +179,8 @@ export default class MigrateRecomputeHomeAmounts extends Command {
       }
       const ok = await confirm(
         chalk.bold(
-          `\nRewrite the stored home amounts of ${flags.object}${flags.field ? `.${flags.field}` : ''} at the rates ` +
-            'in force now, on this database? [y/N] ',
+          `\nRewrite the stored home amounts of ${flags.object}${flags.field ? `.${flags.field}` : ''}` +
+            `${flags.org !== undefined ? ` in organization ${flags.org}` : ''} at the rates in force now, on this database? [y/N] `,
         ),
       );
       if (!ok) {
@@ -228,6 +239,7 @@ export default class MigrateRecomputeHomeAmounts extends Command {
         object: flags.object,
         field: flags.field,
         since: flags.since,
+        organizationId: flags.org,
         apply,
         maxRecords: flags['max-records'],
         source: 'os migrate recompute-home-amounts',