feat(5): overleveringspakke for eksterne — git archive HEAD + DEPLOY.md

Én zip en mottakende organisasjon deployer uten å klone repoet eller ha konto her. Arkivet er git archive HEAD (tracked files only), som er SAMME tre den målte docker-build-konteksten bruker — og grunnen til at STATE.md/*.local.md/.env ikke kan komme inn: de er gitignorert, ikke filtrert bort av et filter vi må vedlikeholde. DEPLOY.md svarer mottakerens tre første spørsmål: hvem gjør hva (plattform-operatør, bestiller, fagperson), prosessen ende-til-ende, og hvorfor det ikke finnes et chat-grensesnitt. Den navngir også deploy-kravet 4e målte men aldri skrev ned: pakket model_map.json bærer REPLACE-WITH-*, så uten PORTFOLIO_MODEL_MAP starter containeren, svarer på /readiness og feiler hver invocation. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SeW1LhH5TtXxKZPe9JkqL1
2026-08-14 10:43:28 +02:00 · 2026-08-14 10:43:28 +02:00 · a3300ab0f6
commit a3300ab0f6
parent 817bcf130f
5 changed files with 385 additions and 0 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -531,6 +531,25 @@ Python ≥3.10. MAF (`agent-framework-core` 1.9.0). Pakkehåndtering: `uv`. To b
  import), eksempelet er gyldig pipeline-input inkl. `FeedbackContract` (RØD på skjema-/kontrakt-drift,
  på en throwaway-kopi — aldri den git-tracked fixturen), og sim-ens markør følger artefakt-fila (RØD i
  det øyeblikk personaen re-inlines).
 - **Overleverings-pakka ER `git archive HEAD`, aldri en kuratert kopi (Fase 5):**
  `scripts/make-handover-package.sh` bygger én zip en ekstern organisasjon deployer uten å klone
  repoet. **Tracked files only er hele eksponerings-kontrollen** — `STATE.md`, `*.local.md` og
  `.env` er gitignorert, så de KAN ikke komme inn; et filter vedlikeholdt i skriptet ville vært den
  andre kopien av den regelen, og den andre kopien er den som drifter (kø-(p)). Det er dessuten
  SAMME tre som den målte docker-build-konteksten (Dockerfile-headeren), så mottakeren deployer det
  vi målte. Versjonen LESES fra `pyproject.toml` — et hardkodet tall her ville råtnet ved neste bump
  nøyaktig som README-ens wheel-filnavn gjorde (Fase 3). `DEPLOY.md` ligger i treet og blir dermed
  med i arkivet av seg selv; den bærer mottakerens tre første spørsmål — hvem gjør hva
  (plattform-operatør / bestiller / fagperson), prosessen ende-til-ende, og **hvorfor det ikke
  finnes et chat-grensesnitt** (flaten er `POST /invocations`, og `as_agent()` er bevisst vraket
  fordi validator, baseline-forankring, checker-gate og ledger ligger UTENFOR grafen — et chat-lag
  ville rutet forespørsler rundt nøyaktig det som gjør svaret etterprøvbart). Den navngir også det
  4e målte deploy-kravet som ingen rad hadde skrevet ned: pakket `model_map.json` bærer
  `REPLACE-WITH-*`, så uten `PORTFOLIO_MODEL_MAP` starter containeren, svarer på `/readiness` og
  feiler HVER invocation. Gaten er `tests/test_handover_package_loadbearing.py`, og
  DEPLOY.md-asserten er LINJEFORANKRET: `PORTFOLIO_FOUNDRY_PROJECT_ENDPOINT` INNEHOLDER
  `FOUNDRY_PROJECT_ENDPOINT`, så en delstreng-assert på det injiserte navnet ville vært oppfylt av
  vårt eget (repoets 08-09-klasse, femte gang).
 - **STATE.md er local-only** (gitignored). Voyage session-state er efemert; STATE.md er kanonisk kontinuitet.
 - Prosess: Voyage-plugin (`/trekbrief → /trekplan → /trekexecute → /trekreview`) per større fase.
--- a/DEPLOY.md
+++ b/DEPLOY.md
@ -0,0 +1,189 @@
 # Deploying and using this package
 This archive is a complete, self-contained copy of `portfolio-optimiser`. You do not need to clone
 anything or have an account anywhere to deploy it. Unzip it and follow this document.
 It is written in English because its readers are implementing developers and platform operators.
 The two documents that describe the *human* side of the loop are written in Norwegian and ship in
 this same archive: [`docs/bestille-en-kjoring.md`](docs/bestille-en-kjoring.md) (ordering a run) and
 [`docs/ekspert-svar.md`](docs/ekspert-svar.md) (giving the verdict).
 ---
 ## 1. What this is — and what it is not
 It finds cost savings **inside** a single project: agents propose candidate measures, a
 **deterministic validator** decides whether the numbers hold, a second agent (the "checker") gates
 the *reasoning*, and a domain expert gives the final verdict. The system learns from those verdicts.
 **There is no chat interface, and that is a design decision rather than a missing feature.**
 The hosted surface is a task API — `POST /invocations` with a JSON body, `GET /readiness` — not a
 conversation. The system is deliberately **not** exposed as a Microsoft Foundry agent via
 `as_agent()`, because the validator, the cost-baseline anchoring, the checker gate and the savings
 ledger all live *outside* the agent graph. Wrapping it as a chat agent would route requests around
 precisely the components that make an answer trustworthy, and you would get a fluent assistant
 instead of a validated result.
 The dialogue with humans happens in two places instead, both file-shaped and both auditable:
 - **before** a run, through a mandate file (what should be considered), and
 - **after** a run, through a verdict file (what a qualified person decided).
 If you want an interactive front end, build it on top of `POST /invocations` — but keep the verdict
 step human. An approval loop that a model can close by itself is not an approval loop.
 ---
 ## 2. Who does what
 The package has three distinct audiences. Only the first one is technical.
 | Role | What they do | Where it is documented |
 |---|---|---|
 | **Platform operator** | Deploys the container into Microsoft Foundry, sets two environment variables, verifies with the offline preflight. One-time work. | This document, sections 3–5. |
 | **Ordering domain expert** (*bestiller*) | Writes the mandate file: the objective, which approaches are worth trying, and why. The *why* is the part the system cannot read out of cost figures. | `docs/bestille-en-kjoring.md` |
 | **Reviewing domain expert** (*fagperson*) | Receives a validated proposal and answers `approved` or `rejected` with a written rationale. That verdict is what the system learns from. | `docs/ekspert-svar.md` |
 **The ordering expert steers what is *considered*, never what is *approved*.** If you ask for
 something the numbers do not support, the deterministic validator rejects it and the rejection comes
 back with its reason. That property is the point of the whole design; do not build around it.
 ---
 ## 3. The process, end to end
 1. **Prepare a knowledge base** for the project — cost documents, technical sources, prior
   experience — as a document bundle. A working five-document example ships in
   `shared/examples/bygg-energi-mikro`, and `docs/knowledge-base-recipe.md` describes how to build
   your own.
 2. **Order a run** with a mandate file (optional but recommended). See
   `docs/bestille-en-kjoring.md`.
 3. **Run it** — from the CLI, or by `POST /invocations` against the deployed container (section 5).
   The run navigates the knowledge base, debates candidate measures, validates the numbers against
   the project's actual cost baseline, and returns either a **validated proposal** or a
   **rejection with a reason**. A rejection is a successful run: the negative outcome belongs to the
   answer, not to the transport, and the API returns HTTP 200 for it.
 4. **A domain expert judges the outcome** and writes a verdict — either inline during the run, or as
   a JSON file dropped into an inbox directory afterwards, possibly days later. See
   `docs/ekspert-svar.md`.
 5. **Approved verdicts can be promoted into the knowledge base**, so the next run reads them as
   context and does not re-propose something the organisation has already rejected. Promotion is
   gated: only an approved verdict can be promoted, and raw agent output never enters the knowledge
   base on its own.
 Steps 4 and 5 are what make this a learning loop rather than a report generator.
 ---
 ## 4. Prerequisites in your own tenant
 You need, in Microsoft Foundry:
 1. A **Foundry resource** with project management enabled and a **project** inside it. A Foundry
   project is required — an Azure OpenAI resource (`kind: OpenAI`) is a different client surface and
   will not work.
 2. At least one **model deployment** (any current chat model; a small one is enough).
 3. The **Foundry User** role (role definition id `53ca6127-db72-4b80-b1b0-d745d6d5456d`) for the
   identity that will run it, assigned at project scope. Azure `Owner` and `Contributor` grant
   management permissions only, **not** the data-plane permissions this needs.
 ---
 ## 5. Configuration — the two variables that matter
 **5.1 The project endpoint.** Resolved as the first non-empty of:
 ```
 PORTFOLIO_FOUNDRY_PROJECT_ENDPOINT     # yours; wins if set
 FOUNDRY_PROJECT_ENDPOINT               # injected by the Foundry hosting platform
 ```
 Inside a hosted Foundry container the platform injects the second one and you need to set nothing.
 Outside it — a laptop, a pipeline, a container you run yourself — set the first. The value looks
 like `https://<resource>.services.ai.azure.com/api/projects/<project>`.
 **5.2 The model map — this is the one that catches people.** The packaged
 `src/portfolio_optimiser/data/model_map.json` ships **placeholders**:
 ```json
 "azure": { "default": "REPLACE-WITH-FOUNDRY-DEPLOYMENT", ... }
 ```
 Deployment names are tenant-specific, so they are deliberately never committed. The code
 **fail-fasts** on a `REPLACE-WITH-` value rather than guessing. Point `PORTFOLIO_MODEL_MAP` at your
 own file:
 ```json
 {
  "local":  { "default": "qwen3:4b",     "proposer": "qwen3:4b",     "checker": "qwen3:4b" },
  "azure":  { "default": "my-deployment", "proposer": "my-deployment", "checker": "my-deployment" }
 }
 ```
 ```bash
 export PORTFOLIO_MODEL_MAP=/path/to/model_map.json
 ```
 If you skip this, the container starts and answers `/readiness` — and fails every invocation. That
 is the single most likely first-deployment failure, which is why it has its own section.
 **5.3 Verify before you pay for a model call:**
 ```bash
 uv run python -m portfolio_optimiser.preflight --profile azure
 ```
 Exit code 0 means every offline-checkable precondition holds: endpoint shape, model-map structure,
 no placeholders left. It is **necessary but not sufficient** — RBAC (403), token or tenant problems
 (401) and a well-formed but non-existent deployment (404) can only surface at the live call.
 ---
 ## 6. Deploying
 The image must be built for x86_64 regardless of your workstation's architecture:
 ```bash
 git archive HEAD | docker build --platform linux/amd64 -t portfolio-optimiser -
 ```
 If you unzipped this package rather than cloning it, build from the directory instead:
 ```bash
 docker build --platform linux/amd64 -t portfolio-optimiser .
 ```
 `azure.yaml` describes the hosted-agent deployment (`azd`). The container serves port 8088 (override
 with `PORT`), answers `GET /readiness`, accepts `POST /invocations`, and shuts down cleanly on
 SIGTERM.
 **The invocations payload** is whitelisted against the run signature — unknown fields are refused by
 name with HTTP 400, never silently ignored:
 | Field | Required | Notes |
 |---|---|---|
 | `project_id` | yes | The project to analyse. |
 | `docs_dir` | yes | Source documents. |
 | `verdict_input` | yes | The expert verdict for this run. |
 | `bundle_dir` | no | Knowledge base to navigate. |
 | `profile` | no | Defaults to `azure` in the hosted container. |
 | `max_rounds` | no | Debate round cap. |
 | `max_tokens` | no | **Per-invocation token ceiling.** Set it. The built-in default is 100 000 tokens per run, which is a ceiling nobody chose for your workload. |
 | `top_k` | no | Retrieval breadth. |
 HTTP 400 means the request was malformed; 500 means the run itself failed, with `error_type` and
 `error` in the body. A rejected proposal is **200** — see section 3.
 ---
 ## 7. Honest limits
 - **This framework has never been run against a live model in our environment.** Everything above is
  measured against tests, an offline simulation and container builds. The first live run in *your*
  tenant is the first live run, full stop.
 - The system is a **technical framework**. Data protection assessments, lawful basis and risk
  ownership belong to whoever deploys it — see `README.md` and `SECURITY.md`.
 - Readiness does not respond during CPU-bound stretches of a run (the optimisation solve).
 - Chunked request bodies are not supported.
 - Verdict promotion writes to the knowledge base non-atomically; it assumes a single writing process.
--- a/README.md
+++ b/README.md
@ -490,6 +490,21 @@ and `top_k` optional. Unknown fields are refused by name (400), never silently d
 credential from the environment at call time, so the same image runs hosted (managed identity)
 and locally (`az login`) without rewiring.
 ### Handing it to someone else
 `scripts/make-handover-package.sh` builds one archive a receiving organisation can deploy without
 cloning this repository or having an account here:
 ```bash
 scripts/make-handover-package.sh          # → dist/portfolio-optimiser-foundry-<version>.zip
 ```
 The archive is `git archive HEAD` — tracked files only, which is the same tree the measured docker
 build context uses, and the reason local-only files cannot enter it. [`DEPLOY.md`](DEPLOY.md) rides
 along inside it and answers the receiver's first questions: what the three roles do, what the
 process is end to end, why there is no chat interface, and the two environment variables that decide
 whether the first deployment works. Gated by `tests/test_handover_package_loadbearing.py`.
 ## Docs
 - [Bestille en kjøring](docs/bestille-en-kjoring.md) *(norsk)* — for the domain expert who
--- a/scripts/make-handover-package.sh
+++ b/scripts/make-handover-package.sh
@ -0,0 +1,33 @@
 #!/usr/bin/env bash
 # Build the external handover package (Fase 5): one archive a receiver deploys into their own
 # Microsoft Foundry, without cloning this repository or having an account on our Forgejo.
 #
 # The archive is git's view of HEAD -- TRACKED FILES ONLY. That is deliberate and it is the whole
 # exposure control: STATE.md is gitignored, *.local.md is gitignored, .env is gitignored, so they
 # cannot enter the archive. A filter maintained here would be a second copy of that rule, and the
 # second copy is the one that drifts (kø-(p)).
 #
 # It is also the SAME tree the measured docker build context uses (see the Dockerfile header:
 # `git archive HEAD | docker build --platform linux/amd64 -`), so what the receiver deploys is what
 # we measured -- never a hand-curated selection.
 #
 # Usage:  scripts/make-handover-package.sh [dest-dir]      (default: dist/)
 # Gated by tests/test_handover_package_loadbearing.py.
 set -euo pipefail
 DEST="${1:-dist}"
 mkdir -p "$DEST"
 # Version from pyproject.toml -- the one place the build stamps it. Read, never hardcoded: a second
 # copy here would go stale at the next bump exactly like the README wheel filename did (Fase 3).
 VERSION=$(grep -m1 '^version = ' pyproject.toml | cut -d'"' -f2)
 if [ -z "$VERSION" ]; then
  echo "make-handover-package: could not read version from pyproject.toml" >&2
  exit 1
 fi
 OUT="$DEST/portfolio-optimiser-foundry-$VERSION.zip"
 git archive --format=zip --output "$OUT" HEAD
 echo "$OUT"
--- a/tests/test_handover_package_loadbearing.py
+++ b/tests/test_handover_package_loadbearing.py
@ -0,0 +1,129 @@
 """Fase 5 — the external handover package: one archive a stranger can deploy into their own
 Microsoft Foundry with minimal friction.
 **Why an archive and not "clone the repo".** The receiving party is not a contributor: they get a
 tree, set two environment variables and deploy it. The measured docker build context has always been
 ``git archive HEAD`` (Dockerfile header), so the package is that SAME tree — never a hand-curated
 copy, which would be the second copy that drifts (the kø-(p) rule applied to a deliverable).
 Three seams are gated here, and each one is a way the handover fails in the receiver's hands rather
 than in ours:
 1. **Completeness** — a tree missing ``uv.lock`` resolves different versions than every measurement
   in this repo ran against; missing ``shared/`` gives a container with no example knowledge base.
 2. **Exposure** — ``STATE.md``, ``*.local.md`` and ``.env`` must never leave this machine. The
   archive is built from tracked files only, so this is a property of the BUILDER; the control below
   proves the check looks for names that could actually appear.
 3. **The deploy contract is written down** — the packaged ``model_map.json`` ships
   ``REPLACE-WITH-*`` placeholders and ``backends.py`` fail-fasts on them, so a receiver who sets
   only an endpoint gets a container that answers ``/readiness`` and fails every ``/invocations``.
   4e measured that requirement and called it "et deploy-krav ingen rad hadde skrevet ned"; DEPLOY.md
   is that row, and this test is what keeps it written.
 """
 from __future__ import annotations
 import subprocess
 import zipfile
 from pathlib import Path
 import pytest
 _REPO_ROOT = Path(__file__).resolve().parents[1]
 _SCRIPT = _REPO_ROOT / "scripts" / "make-handover-package.sh"
 # Deploy-critical members. Each one is load-bearing for a receiver, not decoration:
 # the two manifests, the entry point, the locked resolution, the packaged data and the example base.
 _REQUIRED_MEMBERS = (
    "Dockerfile",
    "azure.yaml",
    "main.py",
    "pyproject.toml",
    "uv.lock",
    "DEPLOY.md",
    "src/portfolio_optimiser/hosting.py",
    "src/portfolio_optimiser/backends.py",
    "src/portfolio_optimiser/data/model_map.json",
    "shared/examples/bygg-energi-mikro/index.md",
 )
 # Names that must NEVER reach a stranger. Local-only continuity, operator config, secrets.
 _FORBIDDEN_SUFFIXES = (".local.md", ".env")
 _FORBIDDEN_NAMES = ("STATE.md",)
@pytest.fixture(scope="module")
 def package(tmp_path_factory: pytest.TempPathFactory) -> zipfile.ZipFile:
    """Build the real package by running the real script — the packaging config is itself a seam
    (the 4a precedent: an ``uv build`` in the fixture, never a simulated one)."""
    dest = tmp_path_factory.mktemp("handover")
    result = subprocess.run(
        [str(_SCRIPT), str(dest)],
        cwd=_REPO_ROOT,
        capture_output=True,
        text=True,
        check=False,
    )
    assert result.returncode == 0, f"builder failed: {result.stderr}"
    archives = sorted(dest.glob("*.zip"))
    assert len(archives) == 1, f"expected exactly one archive, got {archives}"
    return zipfile.ZipFile(archives[0])
 def test_package_carries_every_deploy_critical_file(package: zipfile.ZipFile) -> None:
    """Detach point: drop a member from the archive → RED. A receiver cannot supply what we omit."""
    names = set(package.namelist())
    missing = [m for m in _REQUIRED_MEMBERS if m not in names]
    assert not missing, f"handover package is missing {missing}"
 def test_package_leaks_no_local_or_secret_files(package: zipfile.ZipFile) -> None:
    """Detach point: build from the working tree instead of tracked files → RED (STATE.md appears).
    The control is the point: a filter that matched nothing would make this gate green forever, so
    we first prove the archive is populated and that the suffixes we forbid are ones the repo
    actually produces (``STATE.md`` exists on this machine, untracked-by-design)."""
    names = package.namelist()
    assert len(names) > 50, "archive suspiciously small — the check below would be vacuous"
    assert (_REPO_ROOT / "STATE.md").exists(), (
        "control: STATE.md must exist locally, else this gate cannot discriminate"
    )
    leaked = [
        n
        for n in names
        if Path(n).name in _FORBIDDEN_NAMES or n.endswith(_FORBIDDEN_SUFFIXES)
    ]
    assert not leaked, f"handover package leaks local-only files: {leaked}"
 def test_deploy_doc_names_both_required_env_vars(package: zipfile.ZipFile) -> None:
    """Detach point: remove either variable from DEPLOY.md → RED.
    Line-anchored, not substring: ``PORTFOLIO_FOUNDRY_PROJECT_ENDPOINT`` CONTAINS
    ``FOUNDRY_PROJECT_ENDPOINT``, so a naive substring assert on the platform-injected name is
    satisfied by our own (the 08-09 defect class, measured twice before in this repo)."""
    doc = package.read("DEPLOY.md").decode("utf-8")
    lines = doc.splitlines()
    assert any("PORTFOLIO_MODEL_MAP" in line for line in lines), (
        "DEPLOY.md must name PORTFOLIO_MODEL_MAP — without it the container fail-fasts on the "
        "REPLACE-WITH-* placeholders"
    )
    # The injected name must appear on a line that is NOT merely our own name.
    injected_lines = [
        line for line in lines if "FOUNDRY_PROJECT_ENDPOINT" in line.replace("PORTFOLIO_FOUNDRY_PROJECT_ENDPOINT", "")
    ]
    assert injected_lines, "DEPLOY.md must name the platform-injected FOUNDRY_PROJECT_ENDPOINT"
 def test_deploy_doc_states_the_placeholder_requirement(package: zipfile.ZipFile) -> None:
    """Detach point: drop the placeholder warning → RED. The packaged map ships REPLACE-WITH-*, so a
    receiver who is not told will deploy a container that fails every invocation."""
    doc = package.read("DEPLOY.md").decode("utf-8")
    packaged_map = package.read("src/portfolio_optimiser/data/model_map.json").decode("utf-8")
    # Control: the requirement is only real while the packaged map actually ships placeholders.
    assert "REPLACE-WITH-" in packaged_map, (
        "control: packaged model_map no longer has placeholders — this gate would be vacuous"
    )
    assert "REPLACE-WITH-" in doc, "DEPLOY.md must state that the packaged deployment ids are placeholders"