docs: add the second correction phase and renumber the plan

This commit is contained in:
ai-bot committed 2026-11-15 10:31:19 +00:00
1 parent fdf1631b01
commit 02c4420083
1 file changed
+150 -160
+150 -160
View File
@@ -25,7 +25,7 @@ a later project; the only concession to it is that the DDL lives in `schema.sql`
half-written. Never leave a page without its script or a module without its caller. half-written. Never leave a page without its script or a module without its caller.
- Commit at the end of each step, message in English, one line about what changed. - Commit at the end of each step, message in English, one line about what changed.
- Run the step's verification before moving on. If it fails, fix it in the same step. - Run the step's verification before moving on. If it fails, fix it in the same step.
- Do not reorder. Phase B2 must be finished before Phase C starts. - Do not reorder. Phase B3 must be finished before Phase C starts.
- When the spec is silent, choose the smaller option and record the choice in the commit - When the spec is silent, choose the smaller option and record the choice in the commit
message. Ask the owner only for the four open questions in the spec (§13). message. Ask the owner only for the four open questions in the spec (§13).
@@ -52,7 +52,14 @@ a later project; the only concession to it is that the DDL lives in `schema.sql`
| D17 | `admin_cost` has no account (`market_id` null), takes no fee, and consumes no lots | The owner wants it to stand on its own; it changes no holdings, so nothing else can be derived from it | | D17 | `admin_cost` has no account (`market_id` null), takes no fee, and consumes no lots | The owner wants it to stand on its own; it changes no holdings, so nothing else can be derived from it |
| D18 | The transaction price is derived on the fly and never stored, and is called `btc_price_ore` in the API on both transactions and lots | It is a function of legs the owner already entered, so storing it would let it drift; the owner's word for it is "bitcoin pris", so the API uses one name for one unit | | D18 | The transaction price is derived on the fly and never stored, and is called `btc_price_ore` in the API on both transactions and lots | It is a function of legs the owner already entered, so storing it would let it drift; the owner's word for it is "bitcoin pris", so the API uses one name for one unit |
| D19 | The stored rate column keeps its name `prices.nok_per_btc_ore`, and the settings table keeps the heading `NOK per BTC` | It is Skatteetaten's year-end rate, not a transaction price; renaming a stored column buys a migration and nothing else | | D19 | The stored rate column keeps its name `prices.nok_per_btc_ore`, and the settings table keeps the heading `NOK per BTC` | It is Skatteetaten's year-end rate, not a transaction price; renaming a stored column buys a migration and nothing else |
| D20 | The Avgift section is hidden for `gift_received` and `admin_cost` | The owner's field list gives those two no fee, and the schema now refuses one | | D20 | The Avgift section is hidden for `gift_received` and `admin_cost` | The owner's field list gives those two no fee, and the schema refuses one |
| D21 | A fee is entered in sats only; a kroner cost is folded into the amount the owner types | The owner asked for it, and it keeps every leg to one currency with no conversion the app would have to invent |
| D22 | A transfer's fee is taken on top at the source, so what is sent is exactly what arrives | The owner requires `INN` on the `transfer_in` to equal `Sendt` on the `transfer_out`; subtracting the fee would also make the fee vanish from the destination's holdings instead of the source's |
| D23 | The mirrored lots cover exactly the sent amount, and the cost share of the fee sats leaves the ledger with them | It keeps the destination's price per sat identical to the source's, which is what "inherits the price of the chosen lot" means. Skuld books no gain or loss for a fee |
| D24 | A transfer's price comes from its consumed lots (out) and its mirrored lots (in) | Same unit as the price of a buy, both sides of the pair agree, and nothing extra is stored |
| D25 | `admin_cost` is in kroner | The owner confirmed it. No account, no lots, and no conversion: the report shows the sum and subtracts it only when `deduct_admin_costs` is on |
| D26 | `fee_ore` stays in the schema, always 0 | `CREATE TABLE IF NOT EXISTS` cannot drop a column, and a migration is not worth it for a dead field; no client ever sends it |
| D27 | A field with a single currency shows the unit as plain text instead of a selector | The owner asked for it, and a select with one option claims a choice that does not exist |
## Phase A — application core (steps 1-16) — DONE ## Phase A — application core (steps 1-16) — DONE
@@ -67,165 +74,144 @@ Implemented and committed: `static/style.css`, `static/session.js`, `static/app.
page pairs `login.*`, `index.*`, `transactions.*`, `transaction.*`, `markets.*`, `report.*` and page pairs `login.*`, `index.*`, `transactions.*`, `transaction.*`, `markets.*`, `report.*` and
`settings.*`. `settings.*`.
## Phase B2 — corrections the owner asked for (steps 27-44) ## Phase B2 — first round of corrections (steps 27-44) — DONE
Do these before Phase C. They change the ledger schema, the field set of one transaction type, Sats everywhere, whole kroner in the display, the `Bitcoin pris` figure, `admin_cost` off the
the way amounts are shown, and add one derived figure. Nothing here is optional, and nothing accounts, and no fee for `gift_received`.
here may spill into Phase C.
### 27. `schema.sql` ## Phase B3 — second round of corrections (steps 45-55)
Change `transactions.market_id` from `INTEGER NOT NULL REFERENCES markets(id)` to
`INTEGER REFERENCES markets(id)`, with a comment that it is null only for `admin_cost`. Add the
two CHECK constraints of `docs/spec.md` §4: `(type = 'admin_cost' OR market_id IS NOT NULL)` and
`(type NOT IN ('gift_received', 'admin_cost') OR (fee_sats = 0 AND fee_ore = 0))`. `lots` keeps
its `NOT NULL`.
**Verify:** on a fresh database, an `INSERT` of an `admin_cost` row without a market succeeds,
the same insert for a `trade` fails, and an `admin_cost` with a fee fails.
### 28. `rates.py` Do these before Phase C. The owner has reviewed the app again. These steps change the fee to
Replace `parse_btc_to_sats(text)` with `parse_sats(text)`: whole sats only, space, narrow space sats only, change the transfer pair so that what is sent is what arrives, make
and non-breaking space allowed as thousands separators, a decimal separator rejected with `Forvaltningskostnad` a kroner cost, and make the form match the owner's field list exactly.
`ValueError`. Replace `ore_to_nok(ore)` with `kroner_whole(ore)`: whole kroner, halves rounded
up, grouped with spaces, no unit and no decimals. Delete `sats_to_btc()`. Keep `nok_to_ore`,
`group_int`, `SATS_PER_BTC`, `ORE_PER_NOK` and the rate functions untouched.
**Verify:** `parse_sats("1 500 000") == 1500000`, `parse_sats("1500000") == 1500000`,
`parse_sats("0,5")` raises, `kroner_whole(106037489) == "1 060 375"`.
### 29. `validation.py` ### 45. `validation.py`
`validate_sats` uses `rates.parse_sats` and its messages talk about sats: "Antal må fyllast ut.", A fee is sats only. `ORE_FIELDS` loses `fee_ore`, and `validate_transaction` still reads it but
"Antal må vere eit heiltal i sats.", "Antal må vere større enn null." `_ALLOWED_LEGS` for only to reject it: a non-blank `fee_ore` gives the error "Avgift må berre førast i sats." on
`admin_cost` becomes `("leg_out_sats",)` and `_REQUIRED["admin_cost"]` becomes `fee_sats`, and the stored value is always 0. Keep the rule that `gift_received` and `admin_cost`
`(("leg_out_sats", "Fyll ut kostnaden i sats."),)`. `_check_admin_cost` requires exactly one take no fee, and keep the check that a fee is smaller than the amount it belongs to.
`leg_out_sats` and rejects `leg_out_ore`. `validate_transaction` must not require an account for
`admin_cost` (store `market_id` as `None`), must still require one for every other type, must
reject a fee for `admin_cost` and `gift_received`, and must default the taxable flag to 1 for
`admin_cost` since there is no account to take it from.
**Verify:** a manual check that an `admin_cost` payload without `market_id` validates clean, and
that the same payload with `leg_out_ore` gives a Nynorsk error on `leg_out_sats`.
### 30. `ledger.py` `admin_cost` is a kroner cost now: `_ALLOWED_LEGS["admin_cost"] = ("leg_out_ore",)`,
Remove `admin_cost` from `CONSUMING_TYPES`. Rename the derived field of `_lot_view` from `_REQUIRED["admin_cost"] = (("leg_out_ore", "Fyll ut kostnaden i kroner."),)`, and
`nok_per_btc_ore` to `btc_price_ore` (`docs/spec.md` §8), keeping the arithmetic identical. `_check_admin_cost` accepts exactly one `leg_out_ore` and rejects `leg_out_sats`.
**Verify:** `python3 -m unittest discover -s tests -v`; an `admin_cost` row leaves every lot
untouched after `ledger.rebuild()`.
### 31. `tax.py` `loss` requires its price: add `("value_ore", "Fyll ut prisen i kroner.")` to
Add `btc_price_ore(tx)`: the bitcoin price of `docs/spec.md` §7.3 as øre per whole BTC, or `_REQUIRED["loss"]`.
`None`. The kroner amount is `leg_out_ore` or `leg_in_ore`; the sats amount is the sats leg; for **Verify:** an `admin_cost` payload with `leg_out_ore` validates clean, the same payload with
`income` and `gift_received` the kroner amount is `value_ore` with the incoming sats; for `leg_out_sats` gives a Nynorsk error on `leg_out_sats`, a payload with `fee_ore` gives the
`spend` and `loss` it is `value_ore` with the outgoing sats; `transfer_out`, `transfer_in`, "berre sats" error, and a `loss` without `value_ore` is rejected.
`gift_given` and `admin_cost` give `None`. Round halves up.
Handle `admin_cost` with no account: it is no longer looked up among the accounts, it is counted ### 46. `ledger.py`
when its own `taxable` flag is set, its sats are summed into a new totals field `FEE_ADDS_TO_CONSUMPTION` becomes `("trade", "spend", "transfer_out")` and its comment says that
`admin_cost_sats`, and `admin_cost_ore` becomes `admin_cost_sats × the year-end rate ÷ 10^8` a transfer's fee is taken on top of what is sent. In `create_lots_for`, drop the `fee_ore`
when `deduct_admin_costs` is on and `0` otherwise. Keep every other figure as it is. arithmetic: the cost of a buy is the kroner that left the account, and the cost of `income` and
**Verify:** the golden price case — a buy of 1 000 sats for 10 kr gives `gift_received` is `value_ore`.
`btc_price_ore == 100000000` (1 000 000 kr) — and `report(2024)` still returns every field of §6.
### 32. `export.py` Rewrite `_mirror_transfer`: read `leg_out_sats` from the source `transfer_out` as well as its id,
`JOIN markets m ON m.id = t.market_id` becomes `LEFT JOIN` in `transactions_csv`. Rename `_btc()` then mirror exactly that many sats across the consumed parts in order, using `_split_capped`.
to `_sats()` and use `rates.group_int`; make `_amount()` use `rates.kroner_whole`. Headings For each part the mirrored cost is the part's proportional share, `_cost_for(part cost, part
become `Antall inn (sats)`, `Antall ut (sats)`, `Avgift (sats)`, `Antall (sats)` and sats, mirrored sats)`, so the cost per sat is unchanged. The `fee_sats` and `fee_ore` of the
`Antall (sats)` for the TOT block. Add a `Pris (kr)` column to the transaction block, after `transfer_in` are not read at all. Delete `_split_even`, which nothing else uses.
`Til konto`, carrying `tax.btc_price_ore(row)`. Change the report line **Verify:** `python3 -m unittest discover -s tests -v`; then, by hand, a transfer of 100 000 sats
`Forvaltningskostnad (kr)` into `Forvaltningskostnad (sats)` from `admin_cost_sats`, and keep a with a 1 000 sats fee leaves the source 101 000 sats lighter, the destination 100 000 sats
`Forvaltningskostnad (kr)` line from `admin_cost_ore`. richer, and both sides' lots at the same price per sat.
**Verify:** download the CSV for a year with an `admin_cost` row and open it; the row is present,
the price column is filled for the trades, and no cell carries a decimal.
### 33. `app.py` ### 47. `tax.py`
Make the account join a `LEFT JOIN markets m ON m.id = t.market_id` in `_load_transaction` and `btc_price_ore` learns the transfer case: for a `transfer_out` it uses `cost_ore` and
in `transactions_list`, so a row with no account is not dropped. Add `btc_price_ore` to both `consumed_sats`, for a `transfer_in` it uses `lot_cost_ore` and `lot_sats`, and it still returns
payloads by calling `tax.btc_price_ore`. Confirm that `transactions_get` builds no candidate None for `gift_given` and `admin_cost`. Remove `fee_ore` from the income and proceeds arithmetic
lots for `admin_cost`, which step 30 should already have settled. in `report`, since it is always 0 now.
**Verify:** `GET /api/transactions` returns the `admin_cost` row with `market_id: null`,
`market_name: null` and `btc_price_ore: null`, and a buy returns the golden price.
### 34. `tests/test_ledger.py` `admin_cost` is kroner: sum `leg_out_ore` of the year's taxable `admin_cost` rows into
Update the fixtures to whole sats and the renamed lot field. Add: an `admin_cost` transaction `admin_cost_ore`, drop `admin_cost_sats` from the totals, and subtract the sum from `netto_ore`
consumes nothing and leaves `holdings_at` unchanged; a rebuild after it still produces the same only when `deduct_admin_costs` is on. Drop `fee_ore` from the `_year_rows` select.
lots. **Verify:** `python3 -m unittest discover -s tests -v`; a `transfer_out` and its `transfer_in`
report the same `btc_price_ore`, and a transfer with a fee still reports the same price on both
sides.
### 48. `app.py`
In `_sync_transfer_pair`, `arrived` becomes the sent amount itself, `tx["leg_out_sats"]`, and the
generated `transfer_in` is written with `fee_sats` and `fee_ore` of 0 on both the insert and the
update path.
In `_load_transaction` and `transactions_list`, add the three derived columns `btc_price_ore`
needs for a transfer: `COALESCE(SUM(c.sats), 0) AS consumed_sats`, and
`COALESCE((SELECT SUM(l.cost_ore_original) FROM lots l WHERE l.origin_tx_id = t.id), 0) AS
lot_cost_ore` with the same for `l.sats_original` as `lot_sats`.
**Verify:** save a transfer with a fee: `GET /api/transactions` shows the `transfer_out` with
`leg_out_sats` 100000 and `fee_sats` 1000, and the `transfer_in` with `leg_in_sats` 100000 and
`fee_sats` 0, and both with the same `btc_price_ore`.
### 49. `export.py`
Drop the `Avgift (kr)` column and rename `Pris (kr)` to `Bitcoin pris (kr)`. In the report block
keep one line, `Forvaltningskostnad (kr)` from `admin_cost_ore`. Add the same three derived
columns as step 48 to the transaction query, so the transfer price is filled in.
**Verify:** download a year with a transfer and an `admin_cost`; both sides of the transfer carry
the same price, the `admin_cost` row is present with its kroner amount, and there is no
`Avgift (kr)` column.
### 50. `tests/test_ledger.py`
Update the fixtures for the sats-only fee and the new transfer rules, and add: a transfer with a
fee leaves the destination with exactly the sent sats and the source with the sent sats plus the
fee gone; the destination lots keep the source's cost per sat; the fee's cost share is not
mirrored; `holdings_at` after a transfer is source − sent − fee and destination + sent.
**Verify:** `python3 -m unittest discover -s tests -v` — green. **Verify:** `python3 -m unittest discover -s tests -v` — green.
### 35. `tests/test_tax.py` ### 51. `tests/test_tax.py`
Update the fixtures and add: an `admin_cost` with `market_id` null and `taxable = 1` lands in Update the fixtures and add: `admin_cost` in kroner lands in `admin_cost_ore` and is subtracted
`admin_cost_sats` and leaves every account row untouched; `admin_cost_ore` is 0 with the setting only when the setting is on; a `loss` without a price is rejected by validation;
off, and the sats converted at the year-end rate with it on; `btc_price_ore` for the golden case `btc_price_ore` is the same for a `transfer_out` and its `transfer_in`, and is None for
(1 000 sats for 10 kr → 1 000 000 kr) and for a sale (sats out, kroner in); `btc_price_ore` is `gift_given` and `admin_cost`.
None for `transfer_out` and `admin_cost`.
**Verify:** `python3 -m unittest discover -s tests -v` — green. **Verify:** `python3 -m unittest discover -s tests -v` — green.
### 36. `static/app.js` ### 52. `static/transaction.html`
`formatSats(sats)` returns the grouped whole number of sats and nothing else, and its doc comment Give every currency slot a plain-text unit next to its amount: a `<span class="unit"
says so. `formatKroner(ore)` returns whole kroner with spaces and the unit, rounding halves up, data-unit="leg_in">`, the same for `leg_out`, `value` and `fee`. Keep the two `<select>`s for
with no decimals. `formatOre(ore)` stays exactly as it is and stays exported: it is what fills a `leg_in_currency` and `leg_out_currency`, with the options `sats` and `kr`, because those are the
form from a stored value. `parseSats(text)` parses whole sats with spaces allowed and returns only slots where the currency is a choice. Remove the `fee_currency` select: a fee is sats only.
null for anything carrying a decimal separator. Rewrite the Avgift hint to say that the fee is in sats, that it raises the cost basis of a buy,
**Verify:** in the browser console, `Skuld.formatSats(1500000)` is `"1 500 000"`, and that on a transfer it is taken on top of what you send. Add the `.field-currency .unit` rule
`Skuld.formatKroner(106037489)` is `"1 060 375 kr"`, `Skuld.formatOre(123450)` is to `static/style.css` if the plain text needs it.
`"1 234,50"`, and `Skuld.parseSats("1 500 000")` is `1500000`. **Verify:** open the form; the Avgift section has one amount field and the text `sats`, and no
currency selector.
### 37. `static/transactions.html` ### 53. `static/transaction.js`
Add `<th class="numeric">Pris</th>` between the `Til konto` and `Inn` headings. `TYPE_FIELDS` per `docs/spec.md` §7.3: `trade` gets `default: "sats"` on `in` and `default: "nok"`
**Verify:** the list renders with the new column in the right place. on `out`; `loss` loses `optional` on its `value`, so the price is required; `admin_cost` becomes
`out: {label: "Kostnad", currencies: ["nok"]}`; and `transfer_in` is added for display only, as
`{in: {label: "Motteke", currencies: ["sats"]}, consumes: false, market: true, fee: false}`.
### 38. `static/transactions.js` `applyType()` picks the currency for each slot: set the select to `settings.default ||
`amount()` returns `Skuld.formatSats(sats) + " sats"` instead of `" BTC"`. Add the `Pris` cell settings.currencies[0]` when the slot has a choice, otherwise hide the select and show the unit
between the `Til konto` and `Inn` cells, showing `Skuld.formatKroner(transaction.btc_price_ore)` span with `sats` or `kr`. The `value` slot always shows `kr` and the `fee` slot always shows
or an empty string. `sats`. `fillTypes()` adds the `transfer_in` option with `disabled = true`, so a generated
**Verify:** a buy shows its price, a transfer shows an empty cell, and every sats cell ends in transfer can be displayed while never being selectable.
`sats`.
### 39. `static/transaction.html` `FEE_TAKEN_ON_TOP` gains `transfer_out`, matching `ledger.FEE_ADDS_TO_CONSUMPTION`. `payload()`
Rename the lot table heading `Kostnad per BTC` to `Bitcoin pris`. Give the Marknad field a always sends `fee_sats` and never `fee_currency` or `fee_ore`. `fill()` drops its `fee_currency`
`data-group="market"` wrapper so it can be hidden, and do the same for the whole Avgift branch.
`fieldset` with `data-group="fee"`. **Verify:** walk through every type: each one shows exactly the fields of the owner's list, the
**Verify:** the form still renders, and nothing else moved. unit is plain text wherever there is only one choice, Handel opens with `sats` on Kjøp and `kr`
on Salg/kostnad, and a saved transfer shows `Sendt` and `INN` as the same number with no Avgift.
### 40. `static/transaction.js` ### 54. `static/transactions.html`
In `TYPE_FIELDS`: `admin_cost` becomes `out: {label: "Kostnad", currencies: ["sats"]}` with Rename the column heading `Pris` to `Bitcoin pris`.
`consumes: false`, `market: false` and `fee: false`; `gift_received` gets `fee: false`. Every **Verify:** the heading sits between `Til konto` and `Inn`.
other type gets `market: true, fee: true`. `applyType()` hides the market group and the fee
group when the type says so, sets the `market_id` select's `required` flag to match (a hidden
required field blocks the submit), and clears the value it hides. `payload()` sends
`market_id: null` for `admin_cost`. Keep `Skuld.formatOre` for the NOK inputs and use
`Skuld.parseSats` for the sats inputs and the lot amounts, which are now whole sats. Rename the
`nok_per_btc_ore` reads in `autoPick` and `buildLotRow` to `btc_price_ore`.
**Verify:** choose Forvaltningskostnad: the Marknad and Avgift sections disappear, the Valuta
selector is gone and fixed to sats, and saving writes a row with no account. Choose Gåve
(motteke): the Avgift section is gone.
### 41. `static/index.html` ### 55. `static/report.js`
Change the `Antall` heading to `Antall (sats)`. The `Forvaltningskostnad` figure shows kroner from `totals.admin_cost_ore`, and the sats line
**Verify:** the main sheet heading matches the values. goes away.
**Verify:** the report shows one Forvaltningskostnad figure, in kroner.
### 42. `static/report.html` ## Phase C — StartOS package (steps 56-71)
Change all three `Antall` headings to `Antall (sats)`.
**Verify:** the report headings match the values.
### 43. `static/report.js` ### 56. `package.json`, `tsconfig.json`, `.prettierrc`
The `Forvaltningskostnad` figure shows sats:
`Skuld.formatSats(totals.admin_cost_sats) + " sats"`, and when `totals.admin_cost_ore` is not
zero a second figure shows the kroner that were deducted. The year-end rate line keeps
`formatKroner`, which now prints whole kroner.
**Verify:** a year with an `admin_cost` shows it in sats; with the setting on, the kroner line
appears too.
### 44. `static/markets.html`
Change the `Antall` heading to `Antall (sats)`. `static/markets.js` needs no change: it already
calls `Skuld.formatSats`, which now prints sats.
**Verify:** the account table shows whole sats with spaces.
## Phase C — StartOS package (steps 45-60)
### 45. `package.json`, `tsconfig.json`, `.prettierrc`
The build tooling for the packaging TypeScript, copied in shape from the owner's VardKey The build tooling for the packaging TypeScript, copied in shape from the owner's VardKey
repository and the StartOS packaging guide. Start from the packaging workspace created by repository and the StartOS packaging guide. Start from the packaging workspace created by
`start-cli s9pk init-workspace` and read the recipe index before copying anything. `start-cli s9pk init-workspace` and read the recipe index before copying anything.
**Verify:** `npm install` succeeds and `npx tsc --noEmit` reports no errors. **Verify:** `npm install` succeeds and `npx tsc --noEmit` reports no errors.
### 46. `Dockerfile`, `.dockerignore` ### 57. `Dockerfile`, `.dockerignore`
Slim Python base; copy `app.py`, `auth.py`, `database.py`, `ledger.py`, `tax.py`, `rates.py`, Slim Python base; copy `app.py`, `auth.py`, `database.py`, `ledger.py`, `tax.py`, `rates.py`,
`export.py`, `validation.py`, `maintenance.py` and `schema.sql` into `/app`; copy `static/` into `export.py`, `validation.py`, `maintenance.py` and `schema.sql` into `/app`; copy `static/` into
`/app/static`. No `USER` line, because the `main` volume must be writable without a `chown`. `/app/static`. No `USER` line, because the `main` volume must be writable without a `chown`.
@@ -234,48 +220,48 @@ No packages installed: the app is standard library only.
`docker run --rm -e PORT=8080 -e DATABASE_PATH=/tmp/s.sqlite3 skuld-test python3 -c "import app"` `docker run --rm -e PORT=8080 -e DATABASE_PATH=/tmp/s.sqlite3 skuld-test python3 -c "import app"`
exits 0. exits 0.
### 47. `Makefile` ### 58. `Makefile`
The packaging targets of the StartOS template, pointing at `startos/index.ts`. The packaging targets of the StartOS template, pointing at `startos/index.ts`.
**Verify:** `make` produces `skuld.s9pk`. **Verify:** `make` produces `skuld.s9pk`.
### 48. `icon.svg` ### 59. `icon.svg`
The app icon, under 40 KiB, same artwork as any icon the app serves. A simple mark is enough; do The app icon, under 40 KiB, same artwork as any icon the app serves. A simple mark is enough; do
not add a second icon file. not add a second icon file.
**Verify:** the file is valid SVG and under the size limit. **Verify:** the file is valid SVG and under the size limit.
### 49. `startos/sdk.ts`, `startos/utils.ts` ### 60. `startos/sdk.ts`, `startos/utils.ts`
`sdk` built with the package id `skuld`; the constants `uiPort = 8080`, `volumeId = 'main'`, `sdk` built with the package id `skuld`; the constants `uiPort = 8080`, `volumeId = 'main'`,
`dataMountpoint = '/data'`, `databasePath = '/data/skuld.sqlite3'`, `imageId`, `subcontainerName`. `dataMountpoint = '/data'`, `databasePath = '/data/skuld.sqlite3'`, `imageId`, `subcontainerName`.
**Verify:** `npx tsc --noEmit` passes. **Verify:** `npx tsc --noEmit` passes.
### 50. `startos/manifest/index.ts`, `startos/manifest/i18n.ts` ### 61. `startos/manifest/index.ts`, `startos/manifest/i18n.ts`
The manifest: id `skuld`, Nynorsk title and description, `dockerBuild: {}`, architectures The manifest: id `skuld`, Nynorsk title and description, `dockerBuild: {}`, architectures
`x86_64` and `aarch64`, the `main` volume, the `ui` interface, no dependencies, the donation link `x86_64` and `aarch64`, the `main` volume, the `ui` interface, no dependencies, the donation link
if the owner wants one. if the owner wants one.
**Verify:** `make` still builds and the manifest text is Nynorsk. **Verify:** `make` still builds and the manifest text is Nynorsk.
### 51. `startos/versions/index.ts` ### 62. `startos/versions/index.ts`
The version graph with the first version and its `main` entry. The version graph with the first version and its `main` entry.
**Verify:** `npx tsc --noEmit` passes and `make` produces a package whose version matches. **Verify:** `npx tsc --noEmit` passes and `make` produces a package whose version matches.
### 52. `startos/interfaces.ts`, `startos/backups.ts`, `startos/dependencies.ts` ### 63. `startos/interfaces.ts`, `startos/backups.ts`, `startos/dependencies.ts`
The `ui` interface on port 8080 with `preferredExternalPort: 80`; The `ui` interface on port 8080 with `preferredExternalPort: 80`;
`sdk.Backups.ofVolumes('main')`; no dependencies. `sdk.Backups.ofVolumes('main')`; no dependencies.
**Verify:** `make` builds; the built package lists one interface and one volume. **Verify:** `make` builds; the built package lists one interface and one volume.
### 53. `startos/i18n/index.ts`, `startos/i18n/dictionaries/nb_NO.ts` ### 64. `startos/i18n/index.ts`, `startos/i18n/dictionaries/nb_NO.ts`
The i18n wrapper and the Nynorsk dictionary for everything StartOS displays: the readiness The i18n wrapper and the Nynorsk dictionary for everything StartOS displays: the readiness
messages, the action names and descriptions, the task text. messages, the action names and descriptions, the task text.
**Verify:** `make` builds and no user-facing string in `startos/` is English. **Verify:** `make` builds and no user-facing string in `startos/` is English.
### 54. `startos/actions/index.ts`, `startos/actions/setAdminPassword.ts`, `startos/actions/deleteAllData.ts` ### 65. `startos/actions/index.ts`, `startos/actions/setAdminPassword.ts`, `startos/actions/deleteAllData.ts`
The two actions of `docs/spec.md` §9, each running `maintenance.py` in a `withTemp` subcontainer The two actions of `docs/spec.md` §9, each running `maintenance.py` in a `withTemp` subcontainer
mounted on the main volume. `set-admin-password` shows the generated credentials once; mounted on the main volume. `set-admin-password` shows the generated credentials once;
`delete-all-data` refuses to run unless its confirmation box is ticked. `delete-all-data` refuses to run unless its confirmation box is ticked.
**Verify:** both actions appear under Actions & Config on a test box; the generated password **Verify:** both actions appear under Actions & Config on a test box; the generated password
signs in; the wipe returns the app to the empty state while the admin still works. signs in; the wipe returns the app to the empty state while the admin still works.
### 55. `startos/init/index.ts`, `startos/init/requireAdmin.ts` ### 66. `startos/init/index.ts`, `startos/init/requireAdmin.ts`
The init script registered in `sdk.setupInit()` after the actions, raising the recommended task The init script registered in `sdk.setupInit()` after the actions, raising the recommended task
"Set the admin password before Skuld can be used." while no admin exists and clearing it "Set the admin password before Skuld can be used." while no admin exists and clearing it
afterwards, with a stored replay id. The probe reads the SQLite database readonly in a `withTemp` afterwards, with a stored replay id. The probe reads the SQLite database readonly in a `withTemp`
@@ -283,18 +269,18 @@ subcontainer and fails open.
**Verify:** on a fresh install the task shows as recommended and the service still starts; after **Verify:** on a fresh install the task shows as recommended and the service still starts; after
setting the password the task disappears. setting the password the task disappears.
### 56. `startos/main.ts` ### 67. `startos/main.ts`
The single daemon `primary` in `skuld-sub`: image, the `main` volume mounted writable at `/data`, The single daemon `primary` in `skuld-sub`: image, the `main` volume mounted writable at `/data`,
`python3 app.py` with `PORT` and `DATABASE_PATH`, and the readiness check against `python3 app.py` with `PORT` and `DATABASE_PATH`, and the readiness check against
`http://127.0.0.1:8080/health` displayed as "Web Interface". The port must be the same number in `http://127.0.0.1:8080/health` displayed as "Web Interface". The port must be the same number in
`utils.ts`, `main.ts` and `interfaces.ts`. `utils.ts`, `main.ts` and `interfaces.ts`.
**Verify:** `make` builds and installing the package on a test box turns the health check green. **Verify:** `make` builds and installing the package on a test box turns the health check green.
### 57. `.github/workflows/build.yml` ### 68. `.github/workflows/build.yml`
The build workflow of the StartOS template: build and release the `.s9pk` on a tag. The build workflow of the StartOS template: build and release the `.s9pk` on a tag.
**Verify:** the workflow file is valid YAML and the lint job (if the template has one) passes. **Verify:** the workflow file is valid YAML and the lint job (if the template has one) passes.
### 58. `README.md` ### 69. `README.md`
The technical reference for an AI support agent or an administering agent, in the section order of The technical reference for an AI support agent or an administering agent, in the section order of
the owner's VardKey README: image and container runtime, volume and data layout, file models, the owner's VardKey README: image and container runtime, volume and data layout, file models,
dependencies, network access and interfaces, installation and first-run flow, actions, tasks, dependencies, network access and interfaces, installation and first-run flow, actions, tasks,
@@ -302,22 +288,24 @@ health checks, backups and restore, limitations and differences, and a quick ref
AI consumers. AI consumers.
**Verify:** every claim in it matches `startos/` and the Dockerfile. **Verify:** every claim in it matches `startos/` and the Dockerfile.
### 59. `instructions.md` ### 70. `instructions.md`
The end-user documentation, in Nynorsk: what Skuld does, how to set the admin password, how to The end-user documentation, in Nynorsk: what Skuld does, how to set the admin password, how to
create accounts, how to enter each transaction type, how to read the main sheet, how to get the create accounts, how to enter each transaction type, how to read the main sheet, how to get the
tax figures, and the limitations — including that the database is not encrypted, that amounts are tax figures, and the limitations — including that the database is not encrypted, that amounts are
shown in sats and whole kroner, and that Skuld gives figures, not tax advice. shown in sats and whole kroner, that a fee is in sats, and that Skuld gives figures, not tax
advice.
**Verify:** a reader who has never seen the app can go from install to a tax figure. **Verify:** a reader who has never seen the app can go from install to a tax figure.
### 60. `AGENTS.md` ### 71. `AGENTS.md`
The repository mechanics: that the code is English and the UI Nynorsk, that `schema.sql` is the The repository mechanics: that the code is English and the UI Nynorsk, that `schema.sql` is the
only DDL source, that the ledger is rebuilt rather than patched, that amounts are sats and whole only DDL source, that the ledger is rebuilt rather than patched, that amounts are sats and whole
kroner, that `docs/spec.md` outranks this plan, and the build and test invocations. kroner, that a fee is sats only, that `docs/spec.md` outranks this plan, and the build and test
invocations.
**Verify:** it contradicts nothing in `docs/spec.md`. **Verify:** it contradicts nothing in `docs/spec.md`.
## Phase D — verification ## Phase D — verification
### 61. Build, install and run through ### 72. Build, install and run through
1. `python3 -m unittest discover -s tests -v` — all green. 1. `python3 -m unittest discover -s tests -v` — all green.
2. `make` — builds `skuld.s9pk` without warnings. 2. `make` — builds `skuld.s9pk` without warnings.
3. Install on a StartOS box: the service starts, the health check goes green, the interface opens, 3. Install on a StartOS box: the service starts, the health check goes green, the interface opens,
@@ -325,16 +313,18 @@ kroner, that `docs/spec.md` outranks this plan, and the build and test invocatio
4. Enter the golden example of `docs/spec.md` §6.4 through the UI and compare every figure with 4. Enter the golden example of `docs/spec.md` §6.4 through the UI and compare every figure with
the spec, for all three methods. Every BTC quantity must read as whole sats with spaces, and the spec, for all three methods. Every BTC quantity must read as whole sats with spaces, and
every kroner figure as whole kroner. every kroner figure as whole kroner.
5. Enter a buy of 1 000 sats for 10 kr and confirm `Pris` reads `1 000 000 kr` on 5. Enter a buy of 1 000 sats for 10 kr and confirm `Bitcoin pris` reads `1 000 000 kr` on
`/transaksjonar`. `/transaksjonar`.
6. Enter a Forvaltningskostnad and confirm it has no account, no fee section, and its own line in 6. Make a transfer of 100 000 sats with a 1 000 sats fee: `Sendt` and `INN` are both 100 000, the
the report and the CSV. fee shows on the `transfer_out` only, and both rows carry the same `Bitcoin pris`.
7. Create a child account with the exchange as custodian and confirm the `TOT` row and the 7. Enter a Forvaltningskostnad: no account, no fee section, a kroner amount, its own line in the
report and the CSV.
8. Create a child account with the exchange as custodian and confirm the `TOT` row and the
exclusion from the totals. exclusion from the totals.
8. Do a transfer between two accounts, edit it, and delete it: the lots and the report must return 9. Edit a transfer and then delete it: the lots and the report must return to their earlier
to their earlier state. state.
9. Back up, restore, and confirm the figures are identical. 10. Back up, restore, and confirm the figures are identical.
10. Download the CSV and open it in a spreadsheet. 11. Download the CSV and open it in a spreadsheet.
## Verification commands ## Verification commands