tokenfabrikker/CLAUDE.md
Kjell Tore Guttormsen 078f6d9f9c
docs(rapport): appendix C as a one-page table of the changes to the pre-registration
The verbatim list of changes was the project's working log. The appendix now
shows what was changed, when, before or after the results, and the effect on
the test as each entry states it, and points to the full list in the
pre-registration. The generator for the verbatim list is removed.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-14 22:08:04 +01:00

26 KiB
Raw Permalink Blame History

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, 22–26 third round for the addition to the direction: fast start, stepwise build-up, on-device compute, avoided emissions and cooling water; 27a and 27b fourth round, what researchers and expert bodies say about series building, reactor size, timelines, power purchase agreements and the state's role, made after the freeze and feeding no parameter). 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–S54; chapter 17, the addition to the direction, is coded all the way: solution T through the build-out, the power system, the cash flow, the levelised cost, ownership, scale, M5 and the verdicts, and S48–S54). modell/parametere.json: the frozen parameters (value, range, distribution, source entries); its checksum is recorded in the pre-registration (version 1.1 after the one deviation of 2026-11-12, which added the quantities of chapter 17.8). 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; chapter 17.1: utbyggingsplan_trinnvis for solution T in modules, with the grid balance of the first stage, S49 and the two chip stocks of T-K; S50: tidslinje), 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. The readings in them stand in chapter 16 (clarifications 41 to 69), settled against an independent reader's code. Clarifications 62 to 66 correct the comparison of ownership forms (residual value, levies, private owners, the rate the state's cash flow is valued with, the cost of capital before tax), approved by the operator 2026-11-12; 67 lists what remains. Clarification 68 holds the sources' figures for M5 (i), mirrored in miljo.KILDEVERDIER_M5. Clarifications 70 to 75 hold the readings of chapter 17 made when its build-out was coded, and 76 to 81 those made when T was taken through the power system and the cash flow, and 82 to 87 those made when T and the loss of demand were taken through the levelised cost, ownership and scale, and 88 to 94 those made when M5 and the verdicts were coded for five solutions and three sensitivities of chapter 17.8 as switches, all settled against an independent reader's code. Clarifications 95 to 104 settle the run over the draws (the part of clarification 60 that concerns it); 98 (which paths the ownership forms are compared on), 102 (part II when no step can be built) and 104 (a single facility cannot be the 25 % step) were approved by the operator 2026-11-13 and are clarifications 20, 18 and 19 of the pre-registration (102 is superseded by 135). Clarification 93 (which conditions can be named when M5 holds under conditions) was approved by the operator 2026-11-13 and is clarification 17 of the pre-registration. Clarifications 105 to 113 settle the rest of clarification 60: the price threshold, the thresholds behind «holder under betingelser», the conditions of part I, the Sobol indices, the threshold surfaces, and how the sensitivities are read (on the main run's step, in «normalisering»). 109 (M6 needs no threshold) and 115 (a threshold counts only when the quantity demonstrably affects the outcome, and a threshold in rho_N must hold in both halves of rho_D) were approved by the operator 2026-11-13 and are clarifications 21 to 23 of the pre-registration. Clarifications 116 to 123 settle the sensitivity list line by line (42 rows from 37 lines), and 124 what the independent reader found in them; the operator approved the readings 2026-11-13 (125). Line 10 follows the frozen list and can favour A; the row says so (Rad.merknad). Solution T (Losning.T_F, Losning.T_K) goes through lag_plan (a Trinnvisplan) and regn_program with a module in the place of a facility (Programresultat.P_enhet): renewable modules have their own portfolio as in C, the nuclear modules of T-K share the programme's units as in B (paa_felles_kjernekraft), and S41 counts to the first unit. The factor of S51 enters the revenue and the disconnection arm of S47 through regn_program(..., bortfall=...) (Programresultat.mu_d; exactly one without a loss). miljo.py puts S53 (unngaatt_utslipp, utslipp_med_fradrag) and S54 (kjolevann) together over a programme for all solutions. nivaaisert.py, eierskap.py and skala.py take T per module (res.P_enhet, res.reaktoreffekt(k), res.antall_paa_felles(t, ...)) and carry the factor of S51 per vintage in S19, S27, S31 and S42. The ladder, part I and M7 in dommer.py cover the five solutions of DOMSLOSNINGER (A, B, C, T-F, T-K). M7 is a comparison on equal terms with no verdict (clarifications 135 and 137): per draw the best solutions, alone or sharing the place, or none; M5 in miljo.py holds by definition for T-F and judges T-K as nuclear power. Three sensitivities of chapter 17.8 are switches: regn_program(..., full_fortrengning_i_forste_trinn=True) (Programresultat.delta_V(inn, k) is then one for the first-stage modules), lag_plan(..., ny_kraft_fra=2031) for C and T, and inn.med({"P_m": 50.0}) for the module size. With the switches off every figure is unchanged to the last digit. miljo.kjolevann also gives the withdrawal with sea water only for the nuclear production the data centres themselves use (uttak_egen_bruk, clarification 92). Present values are exactly rounded sums (math.fsum), never numpy dot products: those are not repeatable to the last digit. Sums over technologies go in the plants' own order, never over a set of names: its order differs from run to run. kjoring.py is the run over the draws (clarifications 95 to 104): regn_trekning gives, for one set of values, every solution on every step of the ladder (STIGE) in the six scenarios (SCENARIOER) as a Bane (buildable or not, the timeline S50, and an Utfall per scenario: NNV, S42, M3, M4, M6); kjor does it for a sequence of sets, in the order of the draws and on prosesser processes with the same figures to the last digit; sett_dommer(kjoring, M5) puts the verdicts together (per target with the shares and the figures of clarification 69, the step from M6 in «normalisering» on the main path, part I as far as it follows from the targets; there is no part II, clarification 135); tidslinje_over_trekningene gives median, percentiles and shares per year; eierformer_paa_trinnet compares the ownership forms on the step in a second pass. The run takes the sets of values from the caller and reads neither the parameter file nor the stored draws; M5 is passed in (dommer_m5). terskler.py holds the search for the price threshold (pristerskel, for a function that gives the median for a price factor), the threshold in one drawn quantity (terskel, terskler_for_maal) and the surfaces over two quantities (flate); sobol.py the first-order indices from given draws (indeks, klasser). sett_dommer(kjoring, M5, storrelser=..., status=...) takes the drawn values and the status of the quantities, finds the thresholds on the step and decides part I (dommer.kan_navngis, Scenariodommer.betingelser); without them part I is given as far as it follows from the targets. kjoring.py also has ved_siden_av_m6, sobol_indekser, pristerskel_for_losning and prisflate (they run the model with regn_program(..., prisfaktor=k)), flate_over_trekningene and kraftprisflate. A threshold carries kilde, indeks, paavist and begge_halvdeler, and teller only when all hold (terskler.virkning, holder_i_begge_halvdeler); Betingelser.samtidig gives the conditions of a solution taken together (clarification 115). folsomheter.py is the sensitivity list through the run: RADER holds the 42 rows (which solutions a row applies to, where it is read, and what it changes: fixed values, the switches of the model code as kjoring.Brytere, or a change that depends on the draw), kjor_rad runs one row over the draws on the main run's step for the solutions it applies to, and tabell and hovedtabell give the fixed table per scenario (verdicts per target, the comparison M7, part I as far as it follows from the targets). The switches of the model code are keywords of kontantstrom.dimensjoner (minstelast, fritt_enhetsvalg, gamma_trinn, paaslag_kjernekraft, skaler_K_U, bare_over_dimensjonerende_feil, stored on Dimensjonering) and of regn_program (paaslag, diskontering, skattekostnad); with them off every figure is unchanged to the last digit. The four rows of the ownership forms go through kjoring.eierformer_paa_trinnet(..., rad=Eierrad...), which also gives the state's cash flow next to M6 (clarification 123). The low and the high path of the carbon price are passed in by the caller. The tools of chapter 12 (clarifications 126 to 133): grunnlag.py holds everything a run needs besides the model code (Grunnlag: the sets per draw, the drawn values and their status, M5, the EEA assessment, the carbon paths, the mark «frosset», «endret» or «oppdiktet»); fra_fil reads a made-up basis file, fra_frys builds it from the freeze with the EEA assessment of clarification 136 (EOS_VURDERING: «usikker» for all four ownership forms, approved by the operator 2026-11-14); it has no guard any more and is not called before part 6. datafiler.py builds and writes the six files of the main run (dommer.json, tidslinje.json, eierformer.json, terskler.json, folsomheter.json, innhold.json; fixed field order, no rounding, null for no value) and compares two folders (sammenlign_mapper: «identisk», «innenfor toleranse» at relative 1e-9, «endret»). verktoy.py is the command line: hovedkjoring, kontroll, scenario, folsomhet, terskel, sammenlign, arbeidskopi, tilleggsfiler; every command that computes takes --grunnlag FIL or --frys, with no default. kart.py generates modell/kart.md, the map from S-number to function (SAMMENSATT lists the numbers that are put together over the years or the draws). tilleggsfiler.py makes the two files next to the main run (clarifications 140 e, 141 and 142), with the command tilleggsfiler: fordelinger.json (percentiles 0 to 100 of NNV, S42, M3, M6 and c_snitt per scenario, step and solution, read off kjoring.kjor) and miljo.json (S32, S53 per estimate of u_alt and S54 per year and as the sum over the years: median, p10 and p90 over the draws where the path can be built; a pass of its own with the same build-out and programme as regn_bane), and their checksums in tillegg.json. It edits none of the modules behind the six files; a value that is not a finite number stops it, and so does a folder whose innhold.json has another head.
  • data/trekninger.npy and data/trekninger.json: the 10 000 draws of the 91 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/oppdiktet/: grunnlag.json (a made-up basis, 200 draws, written by lag_grunnlag.py) and fasit/, the six files the main run writes from it on the ladder 1, 2, 5. Committed; kontroll reproduces 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. test_trinnvis.py holds chapter 17: hand-computed build-outs for T-F and T-K, and S48 to S54. test_trinnvis_kontantstrom.py holds T through the power system and the cash flow, the loss of demand, and S53 and S54 over a programme. test_trinnvis_nivaaisert.py holds T and the loss of demand through the levelised cost, ownership and scale. test_trinnvis_dommer.py holds M5 and the verdicts for five solutions on invented outcomes, the three sensitivities that are switches (hand-computed build-outs), and the water for the data centres' own use. test_kjoring.py holds the run over the draws on made-up draws (variants of the made-up set) and on invented outcomes per draw: paths that cannot be built, the step and the scenarios, the timeline over the draws by hand, the same figures on several processes and in another order, and the thresholds, the conditions of part I, the indices and the price threshold through the run. test_terskler.py holds the search for the price threshold, the threshold in a quantity, the surfaces and the Sobol estimator, by hand. test_folsomheter.py holds the rows of the sensitivity list through the run and the table on invented outcomes; test_folsomheter_modell.py and test_folsomheter_naaverdi.py the switches of the model code. test_grunnlag.py, test_datafiler.py and test_verktoy.py hold the tools on the first draw of the made-up basis; test_kart.py holds the map against the specification and the code. test_tilleggsfiler.py holds the two extra files: percentiles and series by hand, the series against miljo on the made-up set, and the command on the first three draws of the made-up basis. A condition can only count with enough draws to show an effect (none can with ten), so the tests of the conditions use forty.
  • 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.
  • The hypothesis was changed by the operator 2026-11-13, before any result (pre-registration, «Endringer»): it is that AI data centres owned in principle by the state can become a source of income for Norway as oil has been. A dedicated nuclear plant per data centre is one of the power solutions, compared on equal terms: the report says how often each of the five comes out best, with no verdict of its own on A. M1 to M6 and the thresholds are unchanged. The specification (clarifications 135 and 137), the code and the data files follow this: M7 gives, for each of the five, the share of the draws in which it is best alone and in which it shares the place (T-K is T-F where no module gets nuclear power), and there is no part II. The operator approved the new wording of the pre-registration 2026-11-14, and it is entered there (the old wording is kept under «Endringer»; clarification 18 has lapsed; «del I» in the clarifications means the hypothesis). The words «the hypothesis» about A in chapters 0 to 17 of the specification no longer apply. A net present value that is not a number is rejected in M7 (clarification 139).
  • 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. Chapter 17 holds the addition to the direction (solution T in the versions T-F and T-K, on-device compute, avoided emissions, cooling water; S48–S54). Where it is silent, T follows the rules for C and B. Its new quantities (17.8) were frozen in the deviation of 2026-11-12 and stand last in the parameter file.
  • 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.
  • Part 6 has begun (2026-11-14): the main run on the frozen numbers was started from a separate copy of the code (private/kjoring-del6/kode, a git worktree on the commit the run is made from; never edit it while a run goes: the worker processes read the code from disk). It writes to data/resultater/. Clarification 140 fixes how: one command writes the five files one at a time, dommer.json first; a seventh and an eighth file, fordelinger.json and miljo.json, are made afterwards by the command tilleggsfiler (clarifications 141 and 142; coded and tested on made-up numbers). The six files and the two extra files (with tillegg.json) are committed in data/resultater/ (2026-11-14, checksums in review log parts 22 and 23), and kontroll --frys reproduced the six on the same machine (identisk); another machine remains. The frozen numbers go through the model only with the committed tools and --frys. Results are read against the pre-registration as they stand; nothing is adjusted after numbers exist. An error that stops a run is fixed and entered in the review log.
  • innspill/: the draft of the submission to the national AI strategy (deadline 2026-11-20, two pages); its wording was approved by the operator 2026-11-14; only the brackets (sender, links, attachments) remain. rapport/: the LaTeX report, summary and carousel (bygg.sh builds with a time limit per run). rapport/sammendrag.tex is the summary in the report: only the main run's verdicts («normalisering», the step the verdicts are read on), M7 without a verdict and the main known limitations, every measured number with \tall{key}. Chapter 7 builds on area 27 of the source bank and names no company; chapter 9 renders chapters 13 and 17.9 of the specification with the wording after the change of the hypothesis. Chapter 8 lists four things the specification says shall be reported that are not computed (build-out with stopping, the two terms of S19, what households and businesses pay, the split of A against B′), and two observations from area 27 outside the frozen ranges in favour of nuclear power (review log part 25). Chapters 3 to 5 were read against the specification by independent readers 2026-11-14. Appendix B (the 137 parameters and the 37 lines of the sensitivity list) and the reference list are generated by rapport/lag_vedlegg_parametere.py and lag_referanser.py into rapport/generert/ (run by bygg.sh, the reference list last; neither is edited by hand). Appendix C (rapport/vedlegg_endringer.tex) is hand-written: one table of what was changed after the first approval of the pre-registration, when, before or after the results, and the effect on the test as the entry itself states it; it quotes no reply of the operator and points to the full list in FORHANDSREGISTRERING.md (the operator's decision 2026-11-14; a new entry under «Endringer» needs a row). The reference list holds every entry cited with \kilde{...} or in the parameter file, with the entry's title and Kilde field; a cited entry without a confirmed Kontroll line stops the script. \kilde links each id to its item (ranges are written K27-008 til K27-011). rapport/notat.tex is the two-page summary and rapport/kap10-konklusjon.tex the conclusion chapter. They, sammendrag.tex, the opening of chapter 1 and README.md are written for a reader who does not know the project (the operator's requirement 2026-11-14): the answer first, the few numbers that carry it, what could change it and what was learned, after the approved wording of innspill/; the equations and the argument of chapters 2 to 9 stay as they are. Every measured number in them is still a \tall key (in the README typed as the key renders it). The built PDFs are copied to pdf/ (the report is marked «utkast»). The carousel is still a skeleton (after 2026-11-20, the operator's priority). The PDFs are not tagged for universal design (review log part 26).
  • Chapter 6 (the results) is generated from the result files. rapport/lag_resultater.py runs the modules in rapport/resultater/ (dommer, tidslinje, miljo, eierformer, terskler, folsomheter; felles.py holds Tall, fra_fil, avledet and the number format: decimal rounding from repr, ties away from zero) and writes tables, figure data and tall.tex/tall.json to rapport/generert/ (build output, ignored by git; bygg.sh makes it). The prose in rapport/kap6-*.tex reads every measured number with \tall{key}; none is typed by hand. Only the thresholds and fixed quantities of the pre-registration, the facts about the run and the values of the frozen sensitivity list are literals. tall.json gives file, path, raw value and conversion per number: a check looks each one up again with code of its own (review log part 24). A boxed quotation (ordrett) is verbatim from the pre-registration.
  • 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
  • Reproduction (made-up, about six minutes): PYTHONPATH=src .venv/bin/python -m tokenfabrikker.verktoy kontroll --grunnlag tests/oppdiktet/grunnlag.json --fasit tests/oppdiktet/fasit --prosesser 8 must print identisk. Map: PYTHONPATH=src .venv/bin/python -m tokenfabrikker.kart kontroll (lag rewrites modell/kart.md).
  • 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/open/tokenfabrikker), never GitHub. The repo is public since 2026-11-14 (the operator moved it to open/ himself; a session never moves, hides or removes a repository). The repo-standard gate has not judged it: it is not in the gate's register. Everything pushed is public at once. 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.