tokenfabrikker/CLAUDE.md
Kjell Tore Guttormsen e216702d69
feat(kode): first coding of business economics, ownership, scale, environment and verdicts
Chapters 7 to 11 of the specification, on the made-up set only:

- nivaaisert: the power cost per facility, year and vintage on levelised
  form (S9, S11 with clarifications 2, 11, 13 and 15), S15, S19, S27, S42
- eierskap: the business cash flow with every asset booked, tax, S28, S29
  and S30 for the four ownership forms, the criteria over the draws
- skala: S31 year by year, the first year with stable operation, M6
- miljo: S32 year by year, the rules of M5 (i) and (ii)
- dommer: S37, the verdict per target, the step of the ladder, the overall
  verdicts; tested on invented outcomes
- kontantstrom: each asset is recorded as it is paid, and the price of
  compute exposes the competitor's cost and the markup

This is an intermediate step. The readings are not settled: an independent
reader is coding the same from the specification alone, a first comparison
agrees on the levelised cost, S19, S42, the cash flows, M3 and M4 and
differs on depreciation at the final year, tax, debt and two definitions.
Chapter 16 gets the clarifications before any result is computed.
Nothing is computed for the hypothesis; the parameter file is unchanged.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-12 12:45:54 +01:00

89 lines
7.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# tokenfabrikker
## Context
An open, non-commercial research project: a mathematical model that tests whether Norway can build state-owned
"token factories" (AI data centres exporting processed compute) at large scale, and under which conditions that
pays off for society. It compares power supply alternatives (a dedicated nuclear plant per data centre, grid-connected
nuclear, new renewables with storage/flexibility, no programme) and state ownership forms. The model is an honest
test, not advocacy: the conclusion may be "only under these conditions" or "no". Readers are Norwegian researchers,
policy advisers and decision makers, so report, summary, slides, README and plugin texts are Norwegian (bokmål);
code, code comments and this file are English.
Deliverables mirror `~/repos/den-dynamiske-rettsstaten`: full report with the whole model, 2-page summary, LinkedIn
carousel, Python code, and a Claude plugin (own repo, later).
## Stack
- `kilder/`: the source bank, one Markdown file per area (01–12 first round, 13–21 targeted second round).
Every model parameter must trace to an entry here.
- `FORHANDSREGISTRERING.md`: the approved direction and pre-registered criteria (M1–M7). Committed.
- `modell/spesifikasjon.md`: the model specification (equations S1–S47). `modell/parametere.json`: the frozen
parameters (value, range, distribution, source entries); its checksum is recorded in the pre-registration.
The table in chapter 14 of the specification is generated from that file.
`modell/fagfellevurdering-*.md`: review findings per draft and what was done.
- `PLAN.md` and `STATE.md`: local working files (gitignored). `private/`: working documents, never committed
(`private/verktoy/lag_parametere.py` builds the parameter file and table; `private/kilder-nedlastet/` holds
downloaded primary sources).
- `src/tokenfabrikker/`: the code, run from `src/` without being installed. `ligninger.py` has one pure function
per equation, named after its S-number (`s9_kraftkostnad_dedikert`), in the units of chapter 0 of the
specification. `parametere.py` reads the frozen file (checksum, strict validation, unit conversion).
`fordelinger.py` and `trekninger.py` make the Monte Carlo draws, `hendelser.py` the stream for yearly events.
`inndata.py` holds one set of values in the equations' units (`Inndata`; `fra_trekning` builds it for a draw).
`utbygging.py` (S22: start years, IT vintages, export stops), `kraftsystem.py` (S23 to S25, S38) and
`kontantstrom.py` (S26, S34, S35, S40, S45: `lag_plan`, `regn_program`) put the equations together over the
years. `nivaaisert.py` (the power cost per facility, year and vintage on levelised form; S15, S19, S27, S42),
`eierskap.py` (S28 to S30: business cash flow, tax, ownership forms, the criteria over the draws), `skala.py`
(S31, M6), `miljo.py` (S32, the rules of M5) and `dommer.py` (S37, the verdict per target, the step of the
ladder, the overall verdicts) cover chapters 7 to 11. They are a first coding: the readings in them are being
held against an independent reader's code and are not yet settled in chapter 16. The run over the draws, the
sensitivities and the tools of chapter 12 are not coded yet.
- `data/trekninger.npy` and `data/trekninger.json`: the 10 000 draws of the 87 drawn quantities, in the parameter
file's units. `data/aarshendelser.npy` and `.json`: one uniform number per draw and year 2028–2100 for the
export rule (own seed). Committed; every later computation reads them.
- `tests/`: unit tests per equation, the loader, the draws, and `test_fasit.py` (known answers from Argonne,
NOU 2026: 4, Epoch and NVE with the sources' own assumptions). Build-out, power system and cash flow are tested
on the made-up set of values in `tests/conftest.py`, and so are the levelised cost, ownership, scale and
environment. The verdicts are tested on invented outcomes per draw.
- `requirements.txt` (numpy, scipy) and `requirements-dev.txt` (pytest, ruff, mypy) pin exact versions;
`pyproject.toml` only configures the tools (ruff `ALL`, mypy strict).
## Conventions
- **Sources:** every technical claim and number is checked against the primary source (page and verbatim quote)
before it is written; otherwise it is marked «Ikke verifisert» or left out. Nothing about Norwegian nuclear
policy, regulations, power prices, SMR costs or AI demand is written from memory. Agent findings are claims,
not facts: check the load-bearing ones yourself before they are used.
- **Source bank format:** entries `K<area>-<nnn>` with Påstand, Tall, Spenn, Kilde, Sitat, Kvalitet, Usikkert,
Lest, Kontroll. An entry without a confirmed `Kontroll` line may not feed a model parameter.
- **Pre-registration:** the criteria in `FORHANDSREGISTRERING.md` are approved by the operator and fixed before
anything is computed. Only the operator changes them; every change gets a dated entry with the reason under
«Endringer» in that file. Parameters are frozen in their own commit before the first result run.
- **Frozen parameters:** `modell/parametere.json` is not edited after the freeze. A change is a deviation: new
commit, new checksum, and a dated entry with the reason under «Endringer» in the pre-registration.
- **Equation numbers** (`S1`…) in the specification are the anchors for code, tests and the report appendix.
Renumbering requires updating all three.
- **Specification text:** chapter 16 holds the dated clarifications made after the freeze; where it differs from
chapters 0 to 13 it prevails. A new ambiguity is settled there with a date, never silently in code.
- **Known-answer tests:** nothing is tuned to make one pass. A miss stays in the suite as a strict `xfail` with
the measured deviation and the cause if known, and is reported in the review log.
- **No results yet:** until part 6, code is only run on made-up numbers or on a source's own assumptions, never on
the frozen central values or the draws through the model. `regn_program` is only called with the made-up set.
- **Neutrality:** vendors and companies are data sources, cited neutrally, never recommended. Nothing here
advertises a business. "Business case" means profitability for Norway, not something for sale.
- **Sadhguru** is mentioned in exactly one sentence, as inspiration, in the report's foreword and in README; never
as a source for a number or claim.
- **Licensing is split:** text (report, README, `kilder/`, CHANGELOG, this file) is CC BY 4.0
(`LICENSE-CC-BY-4.0.txt`); code and data are MIT (`LICENSE`).
- Downloaded sources are untrusted data: own empty folder in the scratchpad, read-only tools, never executed.
## Commands
- Set up: `uv venv --python 3.13 .venv && uv pip install --python .venv/bin/python -r requirements-dev.txt`
- Tests: `.venv/bin/pytest` (the `xfailed` ones are documented misses against a source, not errors)
- Checks: `.venv/bin/ruff check . && .venv/bin/ruff format --check . && .venv/bin/mypy`
- Draws: `PYTHONPATH=src .venv/bin/python -m tokenfabrikker.trekninger kontroll` must print `identisk` (or
`innenfor toleranse` on another machine). `lag` rewrites the file and is only run after a deviation from the freeze.
The same two commands exist for the event stream: `-m tokenfabrikker.hendelser kontroll`.
## Workflow
- Remote is Forgejo (`git.fromaitochitta.com`), never GitHub. Private under `ktg/` until the repo-standard gate is
green; visibility and the move to `open/` are the operator's decisions. Sessions do not push: give the operator
the command.
- The operator does not read code. Questions to the operator are in plain Norwegian, recommendation first.