Skip to content

Commit 6b220ef

Browse files
committed
fix(objectql,cli): recompute-home-amounts review round 1 — since check owned by the recompute, aborted runs audited, truncated runs exit 1
- The --since check is the recompute's own exported pure function (assertHomeAmountRecomputeSince); the CLI calls it before its probe and keeps no copy, so the VALIDATION_FAILED stamp has one owner. - An unclassified error that stops an applied walk still writes the run-level sys_audit_log entry, marked aborted, then is thrown on. - A walk --max-records cut short exits 1. - refuseUndeclaredObjects sets httpStatus 404, so the --json envelope carries it beside OBJECT_NOT_FOUND. - Pinned with the real audit writers: per-row update rows plus the run entry. Docs: the duplicated heading removed; per-row audit rows, updated_at kept, and record-currency-codes' every-organization code stated. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Utp6CXZRTkUQ6UjyMWfN2U
1 parent 90fabf3 commit 6b220ef

11 files changed

Lines changed: 389 additions & 164 deletions

File tree

‎.changeset/27193-recompute-home-amounts.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ feat(objectql,cli): `os migrate recompute-home-amounts` — recompute stored hom
88
Clause-②: yes (widening)
99
Metadata-protocol: none
1010

11-
- **`@objectstack/objectql`: `recomputeHomeAmounts(engine, logger, { object, field?, since?, apply?, maxRecords?, maxListed?, source? })`**, with `formatHomeAmountRecomputeReport`, `homeAmountRecomputeComplete` and `HOME_AMOUNT_SKIP_REASONS`. It walks every stored row of an object whose `record`-mode amounts declare `currencyConfig.homeAmount` and projects each through the write-time projection itself (the same rate row, division, single rounding, same-currency rule and organization-timezone day), in the row's own organization, so each organization converts into its own home currency at its own rates and is counted apart. A dry run (the default) reports what would change and writes nothing; `apply` writes only the rows that differ, through `engine.update` with the home field in the payload, so the value stored is the one the write itself computes, and only the home and rate fields move (`updated_at` is kept). Rows that cannot be converted are listed by reason and never written: `rate_missing` (with the currency and date), `code_blank` (an amount with no currency code; the remedy is `os migrate record-currency-codes`), `document_date_blank`, `home_currency_unset` and `unconvertible`. `since` filters on the document date (`homeAmount.rateDate`). One `sys_audit_log` entry records each applied run (counts per organization and reason, and the skipped rows). Refused before any row is read: an unknown object (`OBJECT_NOT_FOUND`), an object or `field` declaring no home amount (`INVALID_FIELD`), a `since` that is not `YYYY-MM-DD` (`VALIDATION_FAILED`).
11+
- **`@objectstack/objectql`: `recomputeHomeAmounts(engine, logger, { object, field?, since?, apply?, maxRecords?, maxListed?, source? })`**, with `assertHomeAmountRecomputeSince` (the pure `since` check a door can run before it opens a database), `formatHomeAmountRecomputeReport`, `homeAmountRecomputeComplete` and `HOME_AMOUNT_SKIP_REASONS`. It walks every stored row of an object whose `record`-mode amounts declare `currencyConfig.homeAmount` and projects each through the write-time projection itself (the same rate row, division, single rounding, same-currency rule and organization-timezone day), in the row's own organization, so each organization converts into its own home currency at its own rates and is counted apart. A dry run (the default) reports what would change and writes nothing; `apply` writes only the rows that differ, through `engine.update` with the home field in the payload, so the value stored is the one the write itself computes, and only the home and rate fields move (`updated_at` is kept, so a consumer syncing by `updated_at` does not see the recompute). Being a write, it moves what reads the home field as a fresh write would: stored formulas, parent summaries, and the per-row audit rows where audit capture is installed. Rows that cannot be converted are listed by reason and never written: `rate_missing` (with the currency and date), `code_blank` (an amount with no currency code; the remedy is `os migrate record-currency-codes`), `document_date_blank`, `home_currency_unset` and `unconvertible`. `since` filters on the document date (`homeAmount.rateDate`). One run-level `sys_audit_log` entry records each applied run (counts per organization and reason, and the skipped rows), also when an unclassified error stops the run partway (marked `aborted`, then the error is thrown on). A walk cut short by `maxRecords` is `truncated` and not complete. Refused before any row is read: an unknown object (`OBJECT_NOT_FOUND`), an object or `field` declaring no home amount (`INVALID_FIELD`), a `since` that is not `YYYY-MM-DD` (`VALIDATION_FAILED`).
1212
- **`@objectstack/objectql`: `ObjectQL.homeAmountReadsFor(context?)`**, the reads the write-time projection makes (its serving, and the organization a write converts a row under), for a caller that projects a stored row as a write would.
13-
- **`@objectstack/cli`: `os migrate recompute-home-amounts --object <o> [--field <amount>] [--since YYYY-MM-DD] [--apply] [--yes] [--json] [--force] [--max-records] [--database-url]`**, the shell of `os migrate record-currency-codes`, booting the settings service (each organization's `localization.currency` and `.timezone`) and the audit ledger. It exits 1 while any row is listed and skipped, on a dry run as on an apply, because a total over the home field silently leaves such a row out.
13+
- **`@objectstack/cli`: `os migrate recompute-home-amounts --object <o> [--field <amount>] [--since YYYY-MM-DD] [--apply] [--yes] [--json] [--force] [--max-records] [--database-url]`**, the shell of `os migrate record-currency-codes`, booting the settings service (each organization's `localization.currency` and `.timezone`) and the audit ledger. It exits 1 while any row is listed and skipped, on a dry run as on an apply, because a total over the home field silently leaves such a row out, and when `--max-records` cut the walk short.
14+
- **`@objectstack/cli`: an unknown `--object` on any `os migrate` command now carries `httpStatus: 404` in its `--json` envelope** beside `code: OBJECT_NOT_FOUND` (`refuseUndeclaredObjects` sets ADR-0112 D5's spelling of the status it already carried as `status`).

‎content/docs/data-modeling/currency.mdx‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -351,15 +351,18 @@ os migrate recompute-home-amounts --object invoice --apply # Wr
351351

352352
Each row is converted exactly as a write converts it, in its own organization's home
353353
currency at that organization's rates, and an applied row holds what a fresh write of it
354-
would store. `--since` compares the **document date** (the field `homeAmount.rateDate`
354+
would store, so what reads the home field (formulas, roll-ups, the audit trail) follows as
355+
it does for a fresh write. The row's `updated_at` is kept: an integration that syncs by
356+
`updated_at` does not see the recomputed value until it resyncs the object. `--since` compares the **document date** (the field `homeAmount.rateDate`
355357
names), read as the day the write reads it. The report counts each organization apart and
356358
lists every row that changes, with its stored and new values.
357359

358360
**A row that cannot be converted is listed and left as stored**, never filled with a rate
359361
of 1, a later rate or a zero. The report names each one and why: no rate in force on its
360362
document date (add the rate), an amount with no currency code (run
361363
[`os migrate record-currency-codes`](#switching-a-field-that-already-holds-rows) first: no
362-
rate can help a row that names no currency), no document date, or no home currency. Until
364+
rate can help a row that names no currency; it writes its one code into every
365+
organization's codeless rows, so check the per-organization count first), no document date, or no home currency. Until
363366
a re-run converts them, a total over the home field leaves those rows out, so the command
364367
keeps exiting 1 while any is listed, and the applied run's audit entry records them. The
365368
full reference is [`os migrate recompute-home-amounts`](/docs/deployment/cli#os-migrate-recompute-home-amounts).

‎content/docs/deployment/cli.mdx‎

Lines changed: 14 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1647,7 +1647,13 @@ row would store. Each organization converts into its own home currency at its ow
16471647
and the report counts each organization apart.
16481648
16491649
**What is written.** Only rows whose stored home amount or rate differs, and in them only
1650-
the home and rate fields: `updated_at` keeps its stored value. `--field` limits the run to
1650+
the home and rate fields: `updated_at` keeps its stored value. Because each one is an
1651+
ordinary write of the home field, whatever reads that field moves with it, as it would for
1652+
a fresh write: stored formulas, parent summaries, and, where audit capture is installed
1653+
(it is in the command's own boot), one per-row `sys_audit_log` `update` row for each row
1654+
rewritten. ⚠️ Since `updated_at` does not move, a consumer that syncs incrementally by
1655+
`updated_at` does not see a recomputed row; resync the object, or the rows the report
1656+
lists. (`os migrate record-currency-codes` does move `updated_at`.) `--field` limits the run to
16511657
one amount; without it, every amount of the object that declares a home amount is
16521658
recomputed. `--since YYYY-MM-DD` keeps the rows whose **document date** (the field
16531659
`homeAmount.rateDate` names, the date that picks the rate) is on or after that day, a
@@ -1662,20 +1668,22 @@ is refused after the boot and before any row is read.
16621668
| Reason | The row | Fix, then re-run |
16631669
|:---|:---|:---|
16641670
| `rate_missing` | No rate for its currency is in force on its document date (the report names both). | Add the rate. |
1665-
| `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). |
1671+
| `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. |
16661672
| `document_date_blank` | A foreign-currency amount with no document date. | Fill the document date. |
16671673
| `home_currency_unset` | Its organization has no `localization.currency`. | Set **Localization → Default currency**. |
16681674
| `unconvertible` | A code, amount or document date the write itself refuses. | Correct the value. |
16691675
16701676
A skipped row keeps whatever it stored, so a total over the home field leaves it out (a
16711677
`sum` skips an empty home amount silently). That gap stays visible: the command exits 1,
16721678
on a dry run and on an apply, for as long as any row is listed, and an applied run's
1673-
`sys_audit_log` entry (one per run, `action: update`, `metadata.event:
1674-
home_amount.recompute`) records the counts per organization and reason and every skipped
1675-
row. Idempotent: re-running until it lists nothing and changes nothing *is* the
1679+
run-level `sys_audit_log` entry (one per run beside the per-row rows, no record,
1680+
`action: update`, `metadata.event: home_amount.recompute`) records the counts per
1681+
organization and reason and every skipped row. A run that an unexpected error stops
1682+
partway still writes that entry, marked `aborted` with the counts it reached, before the
1683+
command fails. A walk cut short by `--max-records` also exits 1: rows past the bound were
1684+
not looked at. Idempotent: re-running until it lists nothing and changes nothing *is* the
16761685
verification, which is why it records no flag.
16771686
1678-
#### `os migrate comment-reactions`
16791687
#### `os migrate comment-reactions`
16801688
16811689
v18 retired `sys_comment.reactions`, the JSON column that held every emoji

‎packages/cli/src/commands/migrate/recompute-home-amounts.test.ts‎

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
*
77
* The recompute itself is proven in `@objectstack/objectql`'s
88
* `engine-home-amount-projection.test.ts` (in memory) and in
9-
* `packages/qa/dogfood/test/home-amount-recompute.test.ts` (SQLite and
9+
* `packages/qa/dogfood/test/home-amount-projection.test.ts` (SQLite and
1010
* PostgreSQL). What is pinned here is what those cannot see: the command is a
1111
* dry run by default, its flags reach `recomputeHomeAmounts` as given, a
1212
* malformed `--since` is refused before the probe, the prompt and the boot,
@@ -38,6 +38,8 @@ vi.mock('@objectstack/objectql', async (importOriginal) => {
3838
const real = await importOriginal<typeof import('@objectstack/objectql')>();
3939
return {
4040
recomputeHomeAmounts: vi.fn(),
41+
// The `--since` check is the recompute's own, called by the command before its probe.
42+
assertHomeAmountRecomputeSince: real.assertHomeAmountRecomputeSince,
4143
formatHomeAmountRecomputeReport: real.formatHomeAmountRecomputeReport,
4244
};
4345
});
@@ -154,7 +156,7 @@ describe('os migrate recompute-home-amounts', () => {
154156
const err = await MigrateRecomputeHomeAmounts.run(['--json', '--object', 'nope'], { root: CLI_ROOT }).catch((e: unknown) => e);
155157
expect(exitOf(err)).toBe(1);
156158
expect(vi.mocked(recomputeHomeAmounts)).not.toHaveBeenCalled();
157-
expect(json()).toMatchObject({ code: 'OBJECT_NOT_FOUND' });
159+
expect(json()).toMatchObject({ code: 'OBJECT_NOT_FOUND', httpStatus: 404 });
158160
}, RUN_TIMEOUT);
159161

160162
it('a listed and skipped row keeps the exit code at 1, on a dry run and on an apply run (Open item 8)', async () => {
@@ -170,6 +172,20 @@ describe('os migrate recompute-home-amounts', () => {
170172
expect(json()).toMatchObject({ report: { skippedTotal: 1 } });
171173
}, RUN_TIMEOUT);
172174

175+
it('a walk --max-records cut short exits 1: rows past the bound were not looked at', async () => {
176+
vi.mocked(recomputeHomeAmounts).mockResolvedValue(report({ truncated: true }) as any);
177+
const dry = await MigrateRecomputeHomeAmounts.run(['--object', 'invoice', '--max-records', '2'], { root: CLI_ROOT })
178+
.catch((e: unknown) => e);
179+
expect(exitOf(dry)).toBe(1);
180+
expect(printed()).toContain('--max-records');
181+
expect(vi.mocked(recomputeHomeAmounts).mock.calls[0]![2]).toMatchObject({ maxRecords: 2 });
182+
vi.mocked(recomputeHomeAmounts).mockResolvedValue(report({ truncated: true, applied: true, written: 1 }) as any);
183+
const applied = await MigrateRecomputeHomeAmounts.run(['--json', '--apply', '--yes', '--object', 'invoice'], { root: CLI_ROOT })
184+
.catch((e: unknown) => e);
185+
expect(exitOf(applied)).toBe(1);
186+
expect(json()).toMatchObject({ report: { truncated: true } });
187+
}, RUN_TIMEOUT);
188+
173189
it('a run with nothing skipped exits 0', async () => {
174190
await expect(MigrateRecomputeHomeAmounts.run(['--object', 'invoice'], { root: CLI_ROOT })).resolves.toBeUndefined();
175191
expect(printed()).toContain('i1 amount: 71994.24 @ 0.1389 → 80000 @ 0.125');

‎packages/cli/src/commands/migrate/recompute-home-amounts.ts‎

Lines changed: 13 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -24,28 +24,6 @@ import { refuseUndeclaredObjects } from '../../utils/migrate-object-scope.js';
2424
// Type-only, so the heavy engine package is still loaded lazily below.
2525
import type { HomeAmountRecomputeEngine } from '@objectstack/objectql';
2626

27-
const CALENDAR_DATE = /^\d{4}-\d{2}-\d{2}$/;
28-
29-
/**
30-
* The `--since` refusal, judged before the occupancy probe, the `--apply`
31-
* prompt and the boot: a date that is not one is not one on every database.
32-
* The envelope and the leading wording are `recomputeHomeAmounts`'s own
33-
* (`VALIDATION_FAILED` / 400), which keeps the check for every other caller.
34-
*/
35-
function refuseMalformedSince(since: string | undefined): void {
36-
if (since === undefined) return;
37-
const ms = Date.parse(`${since}T00:00:00Z`);
38-
if (CALENDAR_DATE.test(since) && !Number.isNaN(ms) && new Date(ms).toISOString().slice(0, 10) === since) return;
39-
const err = new Error(
40-
`[home-amount-recompute] since '${since}' is not a calendar date: give it as YYYY-MM-DD (for example 2026-01-01). `
41-
+ 'It is compared with each row\'s document date. Refused before the database was opened or any row was read.',
42-
) as Error & { code: string; status: number; httpStatus: number };
43-
err.code = 'VALIDATION_FAILED';
44-
err.status = 400;
45-
err.httpStatus = 400;
46-
throw err;
47-
}
48-
4927
async function confirm(question: string): Promise<boolean> {
5028
if (!process.stdin.isTTY) return false; // non-interactive → require --yes
5129
const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -71,7 +49,7 @@ async function confirm(question: string): Promise<boolean> {
7149
* The numbers are the write's: the run projects each stored row through the
7250
* write's own projection, and an applied row is written through the engine,
7351
* which projects it again. The boot carries the settings service (each
74-
* organization's home currency and timezone) and the audit ledger (one entry
52+
* organization's home currency and timezone) and the audit ledger (one run-level entry
7553
* per applied run).
7654
*
7755
* Dry run by default (writes no row), `--apply` to write. Rows that cannot be
@@ -131,9 +109,11 @@ export default class MigrateRecomputeHomeAmounts extends Command {
131109

132110
if (!flags.json) printHeader('Migrate · recompute-home-amounts');
133111

134-
// `--since` first: before the occupancy probe, the `--apply` prompt and the boot.
112+
// `--since` first: before the occupancy probe, the `--apply` prompt and the boot. The check
113+
// and its envelope are the recompute's own, so the command keeps no copy of either.
135114
try {
136-
refuseMalformedSince(flags.since);
115+
const { assertHomeAmountRecomputeSince } = await import('@objectstack/objectql');
116+
assertHomeAmountRecomputeSince(flags.since);
137117
} catch (error: any) {
138118
if (flags.json) {
139119
await emitJson({ error: error.message, ...errorCodeFields(error) }, 0, { compact: true });
@@ -252,8 +232,9 @@ export default class MigrateRecomputeHomeAmounts extends Command {
252232
});
253233
// [ADR-0144 Open item 8] A listed-and-skipped row is a gap a total over
254234
// the home field silently leaves out, so the run is not done while one
255-
// remains: exit 1, on a dry run as on an apply run.
256-
const gap = report.failures.length > 0 || report.skippedTotal > 0;
235+
// remains: exit 1, on a dry run as on an apply run. A walk `--max-records`
236+
// cut short has not looked at every row, so it is not done either.
237+
const gap = report.failures.length > 0 || report.skippedTotal > 0 || report.truncated;
257238

258239
if (flags.json) {
259240
await emitJson({ database: stack.dbLabel, apply, report, duration: timer.elapsed() });
@@ -280,6 +261,11 @@ export default class MigrateRecomputeHomeAmounts extends Command {
280261
`${report.skippedTotal} amount(s) could not be converted and were left as stored — totals over the home ` +
281262
'field leave them out. Fix each reason listed above, then re-run.',
282263
);
264+
} else if (report.truncated) {
265+
printError(
266+
`The walk stopped at --max-records (${report.scannedRecords} row(s) read): rows past it were not looked at. ` +
267+
'Re-run with a higher --max-records to cover every row.',
268+
);
283269
} else if (apply && report.written > 0) {
284270
printSuccess(`Recomputed ${report.written} row(s). Re-run any time — it only rewrites rows that still differ.`);
285271
} else if (!apply && report.changed > 0) {

‎packages/cli/src/utils/migrate-object-scope.test.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,8 @@ describe('[#21644] refuseUndeclaredObjects: an unknown --object is refused, neve
2020
expect(error).not.toBeNull();
2121
expect(error?.code).toBe('OBJECT_NOT_FOUND');
2222
expect(error?.status).toBe(404);
23+
// …and under ADR-0112 D5's spelling, the field a `--json` envelope carries.
24+
expect((error as { httpStatus?: number } | null)?.httpStatus).toBe(404);
2325
expect(error?.object).toBe('os_sitee');
2426
expect(error?.message).toContain("'os_sitee'");
2527
// Every declared object, sorted, so the operator can correct the spelling.

‎packages/cli/src/utils/migrate-object-scope.ts‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@ export function narrowedFlagNote(command: string, objects: readonly string[], ap
6767
* Refuse every `--object` name the booted registry does not declare, before
6868
* anything is scanned or written.
6969
*
70-
* Throws the `OBJECT_NOT_FOUND` envelope (`code`, `status: 404`, `object`
70+
* Throws the `OBJECT_NOT_FOUND` envelope (`code`, `status` and `httpStatus` 404, `object`
7171
* naming the first unknown name). Its message names every unknown name and the
7272
* declared objects, sorted.
7373
*/
@@ -80,7 +80,10 @@ export function refuseUndeclaredObjects(
8080
const unknown = [...new Set(requested.filter((name) => !known.has(name)))];
8181
if (unknown.length === 0) return;
8282

83-
const error = objectNotFoundError(unknown[0]);
83+
const error = objectNotFoundError(unknown[0]) as Error & { httpStatus?: number };
84+
// ADR-0112 D5's spelling of the same 404, the one a command's `--json` envelope reads
85+
// (`errorCodeFields`): without it the envelope carried the code and dropped the status.
86+
error.httpStatus = 404;
8487
const names = unknown.map((name) => `'${name}'`).join(', ');
8588
const declaredList = [...known].sort();
8689
error.message =

0 commit comments

Comments
 (0)