2026-08-09 09:31:05 +00:00
57 changed files with 2736 additions and 600 deletions
@@ -1,38 +1,64 @@
 # =============================================================================
-# 0pt web console -- example environment
+# 0pt (edge plane) -- environment inventory / example environment
 # =============================================================================
-# Copy to `.env` (gitignored) and fill in real values. Every key below is
-# actually referenced by the code (derived from `process.env.*` usage); nothing
-# here is invented. All secrets are placeholders -- do NOT commit real values.
+# Copy to `.env` (gitignored) and fill in real values. Never commit real values.
+# Vercel env for the edge app; VPS .env (git-ignored) for infra/docker-compose.yml.
+# See docs/08-infrastructure.md for the canonical description of each integration.
 #
-# The app is designed to build and boot with these UNSET: lib/db.ts and
-# lib/stripe.ts are lazy + env-guarded, and the storage/payment/doc routes
-# return HTTP 501 ("not configured") until the relevant keys are provided.
+# Two provenance markers are used below and they mean different things:
+#   * "wired in code today"             -- read via a `process.env.*` somewhere in
+#                                          this repo right now (grep-verified).
+#   * "documented target, not yet read" -- named in docs/08-infrastructure.md /
+#                                          docs/02-architecture.md but with no
+#                                          `process.env.*` read yet. Filling it in
+#                                          unblocks the integration; it does not by
+#                                          itself change behaviour.
+#
+# The app is designed to build and boot with all of these UNSET: lib/db.ts and
+# lib/stripe.ts are lazy + env-guarded, and the storage/payment/doc routes return
+# HTTP 501 ("not configured") until the relevant keys are provided.

-# ---- Core -------------------------------------------------------------------
+# ---------------------------------------------------------------------------
+# Core / public
+# ---------------------------------------------------------------------------
 # Public base URL of this app (used for absolute links / callbacks).
 NEXT_PUBLIC_APP_URL=http://localhost:3000
+# Documented target (docs/08); no call site found reading it in this pass.
+NEXT_PUBLIC_API_URL=https://api.0pt.app

-# ---- Database (Postgres) ----------------------------------------------------
-# First one set wins: DATABASE_URL -> POSTGRES_URL -> POSTGRES_PRISMA_URL.
+# ---------------------------------------------------------------------------
+# Database (Postgres) -- wired in code today: lib/db.ts, app/api/health
+# ---------------------------------------------------------------------------
+# Vercel Postgres sets POSTGRES_URL / POSTGRES_PRISMA_URL automatically when the
+# integration is attached. First one set wins, in this order (lib/db.ts):
+#   DATABASE_URL -> POSTGRES_URL -> POSTGRES_PRISMA_URL.
 DATABASE_URL=postgres://user:password@localhost:5432/opt
 POSTGRES_URL=
 POSTGRES_PRISMA_URL=

-# ---- Queue / cache (Redis) --------------------------------------------------
+# ---------------------------------------------------------------------------
+# Cache / queue (Redis) -- app/api/health only checks presence; no other call
+# site found reading it in this pass (worker queue usage, if any, lives in
+# services/api, outside this repo's scope).
+# ---------------------------------------------------------------------------
 REDIS_URL=redis://localhost:6379

-# ---- Auth -------------------------------------------------------------------
+# ---------------------------------------------------------------------------
+# Auth -- session / dev-login / service-token secrets (wired in code today)
+# ---------------------------------------------------------------------------
 # Session-signing secret (generate a long random string).
 AUTH_SECRET=change-me-long-random-string
-# Optional dev-only login shortcut key (leave unset in production).
+# AUTH_URL is documented (docs/08) but not yet read by any route in this pass.
+AUTH_URL=https://0pt.app
+# Optional dev-only login shortcut key (leave UNSET in production).
 DEV_LOGIN_KEY=
-# Encryption key for stored DB-connection grants (/api/connections/db-grant).
-GRANT_ENC_KEY=change-me-32-byte-key
-# Shared token for internal/service-to-service calls.
+# Shared token for internal/service-to-service calls; sent as X-Internal-Token
+# on every engineFetch() call (lib/engine.ts).
 INTERNAL_TOKEN=change-me-internal-token

-# ---- Zitadel / OIDC Bearer verification (Wave 2 hardening) ------------------
+# ---------------------------------------------------------------------------
+# Zitadel / OIDC Bearer verification (Wave 2 hardening) -- wired in code today
+# ---------------------------------------------------------------------------
 # 0pt verifies inbound Bearer tokens against the fleet Zitadel IdP
 # (src/auth/zitadel.ts, wired via middleware.ts). JWKS are discovered from
 # <issuer>/.well-known/openid-configuration, falling back to <issuer>/oauth/v2/keys.
@@ -51,30 +77,98 @@ AUTH_ENFORCE=true
 # urn:zitadel:iam:org:id -> urn:zitadel:iam:user:resourceowner:id -> tenant_id -> tenant.
 ZITADEL_TENANT_CLAIM=

-# ---- Payments (Stripe) ------------------------------------------------------
+# ---------------------------------------------------------------------------
+# Data engine bridge -- wired in code today: lib/engine.ts
+# ---------------------------------------------------------------------------
+# When set, edge route handlers defer to the FastAPI engine (services/api) as the
+# single source of truth (orders/estimates/catalog/ai-parse). When unset, the edge
+# computes locally / falls back to an honest heuristic -- see lib/engine.ts and
+# app/api/ai/parse.
+ENGINE_URL=http://localhost:8000
+
+# ---------------------------------------------------------------------------
+# SIAX platform clients
+# ---------------------------------------------------------------------------
+# src/clients/{cl0ud,n0d,aud0}-client.ts currently only accept an optional
+# constructor baseUrl and fall back to an in-memory mock / no-op -- none of these
+# three vars is read via process.env yet (grep-verified). Setting them does
+# nothing until those clients are wired to read them; a future pass should add
+# that. See docs/ICEBERG_WRITE_BOUNDARY.md.
+CL0UD_URL=
+N0D_URL=
+AUD0_URL=
+# ST0RE_URL is the convention name for src/clients/st0re-client.ts /
+# st0re-lakehouse-client.ts and is read by the real-infra test suite
+# (tests/p0/*.realinfra.test.ts). The lakehouse write path was live-verified
+# against ST0RE on 2026-07-13 with this set; unset, the clients fall back to
+# their deterministic in-memory mocks.
+ST0RE_URL=
+
+# ---------------------------------------------------------------------------
+# Payments (Stripe) -- wired in code today: app/api/payments/*,
+# app/api/webhooks/stripe
+# ---------------------------------------------------------------------------
 STRIPE_SECRET_KEY=sk_test_xxx
 STRIPE_WEBHOOK_SECRET=whsec_xxx
+# Documented target (docs/08); not yet read by any route in this pass.
+NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=

-# ---- Object storage (Cloudflare R2 / S3-compatible) -------------------------
-# All three required to enable /api/uploads; otherwise it returns 501.
+# ---------------------------------------------------------------------------
+# Object storage -- Cloudflare R2 / S3-compatible
+# ---------------------------------------------------------------------------
+# R2_ENDPOINT / R2_BUCKET / R2_ACCESS_KEY_ID are read in code today; all three
+# are required to enable /api/uploads, otherwise it returns 501.
+# R2_ACCOUNT_ID and R2_SECRET_ACCESS_KEY are documented in docs/08 but were NOT
+# found via a process.env.* read in this pass -- verify before assuming the R2
+# client is fully wired.
 R2_ENDPOINT=https://<accountid>.r2.cloudflarestorage.com
 R2_BUCKET=opt-uploads
 R2_ACCESS_KEY_ID=change-me
-# Optional local blob dir fallback used when R2 is not configured.
+R2_ACCOUNT_ID=
+R2_SECRET_ACCESS_KEY=
+# Fallback local artifact store used when no object storage is configured
+# (src/adapters/local-blob-store.ts). Leave unset in production.
 OPT_LOCAL_BLOB_DIR=./.opt-blobs

-# ---- Document intelligence (Azure) ------------------------------------------
-# Powers document extraction routes; unset => extraction "not configured".
+# ---------------------------------------------------------------------------
+# Document intelligence / OCR (Azure) -- wired in code today:
+# src/services/document-extraction-service.ts. Unset => extraction
+# "not configured".
+# ---------------------------------------------------------------------------
 DOC_INTELLIGENCE_ENDPOINT=https://<resource>.cognitiveservices.azure.com
 DOC_INTELLIGENCE_KEY=change-me
 DOC_INTELLIGENCE_API_VERSION=2024-11-30

-# ---- Engine / integrations --------------------------------------------------
-# URL of the 0pt data engine (services/api orchestrator).
-ENGINE_URL=http://localhost:8000
+# ---------------------------------------------------------------------------
+# Customer DB-grant encryption -- wired in code today:
+# /api/connections/db-grant
+# ---------------------------------------------------------------------------
+# 32-byte key, AES-GCM. Encrypts customer-supplied read-only connection strings
+# at rest.
+GRANT_ENC_KEY=change-me-32-byte-key
+
+# ---------------------------------------------------------------------------
+# External write-back targets
+# ---------------------------------------------------------------------------
 # Odoo base URL for the bills/write-back adapter.
 ODOO_BASE_URL=https://<your-odoo-host>

-# ---- Test-only (tests/p0 real-infra suite; not needed to run the app) --------
-# ST0RE_URL=
+# ---------------------------------------------------------------------------
+# Email -- Resend (documented target, docs/08; no Resend call site found in
+# this pass -- treat as not-yet-implemented, not just unconfigured)
+# ---------------------------------------------------------------------------
+RESEND_API_KEY=
+
+# ---------------------------------------------------------------------------
+# Embedded analytics (documented target, docs/08; no call site found in this
+# pass)
+# ---------------------------------------------------------------------------
+METABASE_SITE_URL=
+METABASE_SECRET_KEY=
+NOCODB_BASE_URL=
+NOCODB_API_TOKEN=
+
+# ---------------------------------------------------------------------------
+# Test-only (tests/p0 real-infra suite; not needed to run the app)
+# ---------------------------------------------------------------------------
 # ST0RE_TEST_TENANT_ID=
@@ -0,0 +1,59 @@
+name: CI
+
+# Quality gate: typecheck + test on every PR and non-main push.
+# 0pt previously relied solely on the Vercel build with no pre-merge gate.
+# Build is intentionally NOT run here because it needs runtime secrets
+# (POSTGRES_URL, ENGINE_URL, STRIPE, RESEND) — Vercel owns the build; CI owns
+# the static gate.
+#
+# Updated by the GitHub<->Gitea unification merge (2026-07-28). The note that
+# used to sit here — "lint is not a step because this repo has no eslint
+# dependency or config wired" — is no longer true: the Gitea line's Wave 2
+# hardening added eslint + typescript-eslint + a flat config and repointed the
+# "lint" script at `eslint src tests`. Lint now runs, ADVISORY
+# (continue-on-error), matching .gitea/workflows/ci.yml: the v0-generated
+# legacy tree carries pre-existing lint noise, so it must not block merges.
+#
+# `typecheck` (BLOCKING) is tsc over tsconfig.check.json = src/ + tests/.
+# `typecheck:app` (ADVISORY) is the whole-repo tsc this workflow used to run as
+# its blocking step. It was green on the GitHub line alone but reports 9
+# pre-existing errors on the unified tree (app/api/0pt/* route handlers, where
+# the Wave 2 Zod schemas type fields as plain `string` while the services want
+# narrower unions). It is kept running, and kept visible, rather than deleted —
+# see package.json's "//scripts" note. Flip it back to blocking once those 9
+# are cleared.
+#
+# Python engine (services/api) is gated separately if/when a Python workflow
+# is added.
+on:
+  pull_request:
+  push:
+    branches-ignore: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  gate:
+    name: Typecheck + test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+      - name: Enable corepack (pnpm)
+        run: corepack enable
+      - name: Install (frozen lockfile)
+        run: pnpm install --frozen-lockfile
+      - name: Typecheck (tsc over src/ + tests/ -- blocking)
+        run: pnpm run typecheck
+      - name: Test (vitest -- blocking)
+        run: pnpm run test
+      - name: Typecheck whole repo (advisory -- 9 pre-existing app/ errors)
+        continue-on-error: true
+        run: pnpm run typecheck:app
+      - name: Lint (eslint -- advisory; legacy tree has pre-existing noise)
+        continue-on-error: true
+        run: pnpm run lint
@@ -18,6 +18,7 @@ yarn-error.log*

 # env files
 .env*
+!.env.example

 # vercel
 .vercel
@@ -16,7 +16,7 @@ Owned by SIAX Technology AB. Feeds internal products too (Protosell/FiveCRM, Veh

 1. **Legal sourcing only.** The data engine uses, in strict priority: official APIs/bulk → authorized scraping of clearly public pages (respect `robots.txt` + rate limits) → licensed partner data → otherwise the field is delivered as **"not available / licensed only"**. We never invent values.
   - **Do NOT build, keep, or extend**: WAF/bot-detection bypass (incl. FlareSolverr, "stealth" browsers, undetected-* used to defeat detection), fingerprint/proxy rotation to evade bans, scraping behind login walls, or automated fake-account creation (Apollo etc.).
-   - If existing code (e.g. `src/workers/browser_worker.py`) contains a FlareSolverr/bypass path, **remove or disable it** and replace with compliant fetching. This is a product-positioning + compliance requirement, not a preference. "Honest accuracy" is the whole moat.
+   - **Path corrected this pass:** no `src/workers/browser_worker.py` exists anywhere in this checkout (verified via full-repo search) — the engine's actual workers live under `services/api/workers/` (`adaptive_router.py`, `pipeline.py`, `queue.py`, `resolve.py`, `run.py`), none of which contain a FlareSolverr/bypass path today. The precedent for this concern is real and, **as of this GitHub<->Gitea unification merge, it is in this tree**: Gitea's `git.siax.io/sax3l/0pt` `main` independently accumulated a WAF-bypass/proxy-rotation/fake-identity scraper stack (`services/scrapers/*` — `curl_cffi`, `cloudscraper`, Tor circuit rotation) in three 2026-07-13 commits, and this branch inherits it because it branches from Gitea `main`. **The deletion PR (`feature/0pt-remove-noncompliant-scrapers`) is open, NOT merged** — an earlier version of this paragraph claimed it was "since removed", which was false. That removal is deliberately left to its own PR and was *not* folded into this merge; nothing in this merge resurrects, extends, or re-wires any of it. If new code (from either remote) reintroduces a bypass path anywhere, **remove or disable it** and replace with compliant fetching. This is a product-positioning + compliance requirement, not a preference. "Honest accuracy" is the whole moat.
 2. **Postgres is the backbone.** One Postgres is the source of truth. Catalog, portal, NocoDB views, Metabase dashboards, workers, exports all read/write the *same* DB. A tool may only enter the stack if it (a) reads that Postgres and (b) sits behind the same auth.
 3. **Provenance per field.** Every fact carries source, freshness, confidence (`bridge_provenance`). This drives the UI signature too.
 4. **One tool per job.** Do not add overlapping tools. The approved stack is in `docs/02-architecture.md` and `docs/07-dependencies.md`. Anything not listed needs a documented reason.
@@ -25,7 +25,11 @@ Owned by SIAX Technology AB. Feeds internal products too (Protosell/FiveCRM, Veh

 ## Build on existing code

-A working repo already exists (~145 files): FastAPI orchestrator (`src/orchestrator/main.py`, 25+ endpoints), workers (`src/workers/`: adaptive_router, browser_worker, ocr_worker, db), and country data for 20 markets. **Reconcile with it, don't blindly replace.** Where this documentation defines a target contract, migrate the existing code toward it. Flag conflicts instead of guessing.
+A working engine repo already exists. **Corrected this pass — the previous description of it was wrong on every specific:** the FastAPI orchestrator lives at `services/api/orchestrator/main.py` (not `src/orchestrator/main.py`) and registers **12** route handlers (not "25+"); the workers directory is `services/api/workers/` and contains `adaptive_router.py`, `pipeline.py`, `queue.py`, `resolve.py`, and `run.py` (not `browser_worker`/`ocr_worker`/`db` — none of those three files exist anywhere in this repo); and `services/api/sources/sources.yaml` currently covers **7** markets (`SE`, `NO`, `DK`, `FI`, `GB`, `NL`, plus `global`), not 20. `services/api/` holds 11 Python source files total (excluding `__pycache__`). **Reconcile with the code as it actually is, not this description's prior claims.** Where this documentation defines a target contract, migrate the existing code toward it. Flag conflicts instead of guessing.
+
+**Two remotes claim to be this repo, and it's unresolved which is authoritative.** `origin` here is `github.com/sax3l/0pt`. A separate Gitea remote, `git.siax.io/sax3l/0pt`, shares at least part of the same history but has independently diverged (see README "Known issues" for specifics). Do not assume `origin` is the only copy of this codebase, and do not silently resolve the question of which is canonical — that is Simon's decision.
+
+**Before trusting any status claim in this doc corpus, read README's "Known issues" section.** It covers the auth/tenant-scoping gap, the platform-client mock-only status, and the underlying fact that 0pt's quality-check/QA enforcement code was never built despite once being described as real. **Corrected this pass:** `docs/ICEBERG_WRITE_BOUNDARY.md`, `docs/11-lakehouse-write-plan.md`, and `docs/P0_QUERY_SOURCE_FLOW.md` are now all consistently corrected — each carries its own "fabricated, not built" callout and none asserts `quality-check-service.ts`/`quality-report-service.ts`/etc. as real or tested anywhere in its current body (verified this pass by reading all three in full). `docs/P0_DATASET_QUALITY_FLOW.md` remains the explicit target-spec replacement for what that stage should look like once built. Treat any *other* doc claiming the QA stage already exists as wrong.

 ## How to work

@@ -49,11 +53,14 @@ A working repo already exists (~145 files): FastAPI orchestrator (`src/orchestra
 | `docs/07-dependencies.md` | Repos/libraries to import (+ explicit exclusions) |
 | `docs/08-infrastructure.md` | Hosting, docker-compose, env, security, CI/CD |
 | `docs/09-build-plan.md` | Phased milestones with acceptance criteria |
-| `docs/design/0pt-v0-build-brief.md` | Per-component v0 prompts (design reference) |
-| `docs/design/0pt-design-coverage-and-visuals.md` | Full page/component inventory + visual system |
-| `docs/10-lakehouse-decision.md` | Pointer: Apache Iceberg = canonical SIAX lakehouse format (ADR-0030, `n0d` repo); 0pt = write-path owner |
-| `docs/11-lakehouse-write-plan.md` | 0pt's concrete lakehouse write to-do list, schema/event names for a future implementation session |
-| `docs/ICEBERG_WRITE_BOUNDARY.md` | Implementation record: dataset<->Iceberg-table mapping + source-rate-policy contracts, ST0RE lakehouse client, live-verified write path (real namespace/table/snapshot IDs), what's real vs. contract-only |
+| `docs/10-lakehouse-decision.md` | Pointer to an ecosystem-wide lakehouse ADR made outside this repo (Apache Iceberg = canonical SIAX lakehouse format, ADR-0030 in the `n0d` repo; 0pt = write-path owner). Does not change `docs/02`/`docs/03` |
+| `docs/11-lakehouse-write-plan.md` | 0pt's own follow-up task list for the Iceberg write boundary — schema/event names for the implementation. **Corrected**: item 4 (quality rules) is explicitly labeled NOT BUILT, and the old fabricated `quality-check-service.ts`/`quality-report-service.ts` claim is quoted only inside its own "Correction" callout, never asserted as fact |
+| `docs/12-edge-capability-api.md` | Edge-native TypeScript P0 capability API contract (`app/api/0pt/*`, `/api/screen`, `/api/ai/parse`) — distinct from `docs/04-api.md`'s FastAPI-engine contract; documents several confirmed always-fails-over-HTTP routes and the tenant_id/in-memory gaps |
+| `docs/ICEBERG_WRITE_BOUNDARY.md` | Implementation record + "real vs. contract-only" verification status: dataset<->Iceberg-table mapping and source-rate-policy contracts, ST0RE lakehouse client, and the 2026-07-13 **live-verified** write path (real namespace/table/snapshot IDs). **Corrected**: its "Data quality: not yet built" section explicitly quotes and retracts the old fabricated claim rather than repeating it as fact |
+| `docs/P0_QUERY_SOURCE_FLOW.md` | `0pt.query_source` bounded source-query flow — **corrected**: no longer claims `quality-check-service.ts` exists, now points at the real precedent (`iceberg-write-service.ts`) instead |
+| `docs/P0_DATASET_QUALITY_FLOW.md` | An explicit **target-spec-only, not-yet-built** replacement for the fabricated quality-check/QA claims — read it as "should", never "does" |
+
+**Corrected:** this table previously listed `docs/design/0pt-v0-build-brief.md` and `docs/design/0pt-design-coverage-and-visuals.md` as if they existed. They do not — confirmed via a full-repo search, including after this unification merge; there is no `docs/design/` directory at all. No `docs/` design-brief content is fabricated here to fill the gap. Either write those two docs or stop referencing them; until one of those happens, treat any prior claim that they exist as false.

 ## Definition of done (every screen, before real data)

@@ -42,9 +42,37 @@ Out of scope:
 - Automated scanning that generates excessive load against production
  systems without prior coordination.

-Some known findings (for example authentication gaps on specific internal
-API routes) are already tracked internally and pending an intentional,
-reviewed fix; reporting them is still welcome and helps confirm priority.
+Note: `github.com/sax3l/0pt` (this checkout's `origin`) and
+`git.siax.io/sax3l/0pt` (Gitea) are two diverged remotes that share part of
+this codebase's history — see README "Known issues" for what's known and
+what isn't about the relationship between them. Which one is deployed to
+0pt.app is currently unconfirmed; if your finding is remote-specific, say
+which remote/branch you tested against.
+
+## Known, already-tracked gaps
+
+The following are **not** news to us — they are open, named gaps as of this
+pass, not secrets, and reporting them again mainly helps confirm priority
+rather than surfacing something new:
+
+- **No authentication or tenant-isolation system exists in this repo yet.**
+  The only gate in front of any route is a `DEV_LOGIN_KEY` dev-login scaffold
+  (`app/api/auth/login/route.ts`) — there is no session-to-tenant binding.
+  `app/api/orders/route.ts`'s `GET` handler carries the literal comment
+  `// GET /api/orders — list (org scoping added with auth).`, confirming this
+  directly. As a consequence, the P0 data-platform routes under `/api/0pt/*`
+  (`lakehouse/mappings`, `sources/rate-policies`, `sources/[sourceId]/query`)
+  and `src/services/document-capture-service.ts` accept `tenant_id`/
+  `project_id` **from the client-supplied request body or query string**
+  rather than from a server-bound session — a violation of this platform's
+  own tenant-isolation rule (tenant_id must never be trusted from client
+  input). This is an open, prioritized gap pending real auth (Phase 3,
+  `docs/09-build-plan.md`), not an intentional design. Do not treat this repo
+  as tenant-isolated until that lands.
+- Beyond that specific item, other authentication gaps on internal API
+  routes may still exist and are tracked internally pending an intentional,
+  reviewed fix; reporting any you find is still welcome and helps confirm
+  priority.

 ## Disclosure

@@ -42,10 +42,13 @@ export default function AdminPage() {
  const load = useCallback(async () => {
    setError(false);
    try {
-      const [o, m] = await Promise.all([
-        fetch("/api/orders", { cache: "no-store" }).then((r) => r.json()),
-        fetch("/api/admin/metrics", { cache: "no-store" }).then((r) => r.json()),
+      const [oRes, mRes] = await Promise.all([
+        fetch("/api/orders", { cache: "no-store" }),
+        fetch("/api/admin/metrics", { cache: "no-store" }),
      ]);
+      if (!oRes.ok || !mRes.ok) throw new Error("fetch failed");
+      const [o, m] = await Promise.all([oRes.json(), mRes.json()]);
+      if (!m || typeof m.total !== "number") throw new Error("bad metrics shape");
      setOrders(mergeOrders(Array.isArray(o) ? o : []) as Order[]);
      setMetrics(m);
    } catch {
@@ -21,7 +21,17 @@ export async function POST(request: NextRequest, { params }: { params: Promise<{
    return NextResponse.json(result, { status: 201 });
  } catch (error: unknown) {
    const message = error instanceof Error ? error.message : "Unknown error";
-    return NextResponse.json({ error: message }, { status: 400 });
+    if (/not configured/i.test(message)) {
+      return NextResponse.json({ error: message }, { status: 501 });
+    }
+    if (/^Policy denied/i.test(message)) {
+      return NextResponse.json({ error: message }, { status: 403 });
+    }
+    if (/^Policy requires approval/i.test(message)) {
+      return NextResponse.json({ error: message }, { status: 409 });
+    }
+    const status = /not found/i.test(message) ? 404 : 400;
+    return NextResponse.json({ error: message }, { status });
  }
 }

@@ -1,7 +1,5 @@
 import { NextResponse } from "next/server";
-import { DatasetIcebergMappingService } from "@/src/services/dataset-iceberg-mapping-service";
-
-const mappingService = new DatasetIcebergMappingService();
+import { mappingService } from "@/src/services/lakehouse-mapping-registry";

 export async function GET(_request: Request, { params }: { params: Promise<{ mappingId: string }> }) {
  try {
@@ -1,11 +1,18 @@
 import { NextRequest, NextResponse } from "next/server";
 import { parseBody, requestIcebergWriteSchema } from "@/src/validation/0pt-schemas";
-import { IcebergWriteService } from "@/src/services/iceberg-write-service";
-
-const writeService = new IcebergWriteService();
+import { writeService } from "@/src/services/lakehouse-mapping-registry";

 // Registers a new Iceberg snapshot (a write) through ST0RE's table registry
 // for an already-mapped dataset. See docs/ICEBERG_WRITE_BOUNDARY.md.
+//
+// `writeService` is the SHARED instance from
+// src/services/lakehouse-mapping-registry.ts -- this route used to construct
+// its own `new IcebergWriteService()`, which held a private in-memory mapping
+// registry, so a mapping created via POST /lakehouse/mappings was never
+// visible here and every write failed with "mapping not found".
+//
+// The body is validated against requestIcebergWriteSchema before it reaches
+// the service (Wave 2 hardening).
 export async function POST(request: NextRequest, { params }: { params: Promise<{ mappingId: string }> }) {
  try {
    const { mappingId } = await params;
@@ -1,20 +1,25 @@
 import { NextRequest, NextResponse } from "next/server";
 import { parseBody, mapDatasetToIcebergTableSchema } from "@/src/validation/0pt-schemas";
-import { IcebergWriteService } from "@/src/services/iceberg-write-service";
-import { DatasetIcebergMappingService } from "@/src/services/dataset-iceberg-mapping-service";
+import { mappingService, writeService } from "@/src/services/lakehouse-mapping-registry";

-// Shared instances so a mapping created via POST is visible to a later GET
-// within the same server process, matching the in-memory-per-module
-// convention already used by app/api/0pt/datasets and app/api/0pt/quality
-// (Postgres persistence exists in sql/ but is not wired into route handlers
-// in this pass -- same limitation those routes already have).
-const mappingService = new DatasetIcebergMappingService();
-const writeService = new IcebergWriteService({ mappingService });
+// Shared instances come from src/services/lakehouse-mapping-registry.ts so a
+// mapping created via POST is visible to a later GET, AND to the sibling
+// /{mappingId}/writes route, within the same server process. (Each route file
+// previously constructed its own DatasetIcebergMappingService/
+// IcebergWriteService, so a mapping created here was invisible to the writes
+// route -- every write failed with "mapping not found".) This still matches the
+// in-memory-per-module convention app/api/0pt/datasets and app/api/0pt/quality
+// use; Postgres persistence exists in sql/ but is not wired into route handlers
+// in this pass -- same limitation those routes already have.

 // POST registers a NEW Iceberg table in ST0RE's table registry (via
 // IcebergWriteService.mapDatasetToIcebergTable) and records the
 // dataset_iceberg_mapping row that points at it -- this is 0pt's write-path
 // entrypoint, see docs/ICEBERG_WRITE_BOUNDARY.md.
+//
+// The body is validated against mapDatasetToIcebergTableSchema BEFORE it
+// reaches the service (Wave 2 hardening): an unvalidated request body used to
+// be passed straight into the capability call.
 export async function POST(request: NextRequest) {
  try {
    const __raw = await request.json();
@@ -10,8 +10,13 @@
 * is not shared across route modules yet — see the "Singleton note" in
 * src/services/document-capture-service.ts for prior art on this same repo
 * limitation). A source registered via POST /api/0pt/sources will not be
- * resolvable here until SourceService is backed by shared persistence
- * (sql/002_p0_dataset_quality.sql already defines `opt_sources` for that).
+ * resolvable here until SourceService is backed by shared persistence.
+ * Correction: this comment previously claimed `sql/002_p0_dataset_quality.sql`
+ * already defined an `opt_sources` table for that. That file does not exist
+ * and never has (git log --all: zero commits, any branch, ever). sql/ today
+ * has only 001_init.sql and 004_iceberg_write_boundary.sql. The real fix —
+ * backing SourceService with real persistence — is still open; no migration
+ * for it exists yet.
 * Details: docs/P0_QUERY_SOURCE_FLOW.md.
 */
 import { NextRequest, NextResponse } from "next/server";
@@ -24,7 +24,9 @@ const DEST: [RegExp, string][] = [
 ];

 export async function POST(req: NextRequest) {
-  const { text } = await req.json().catch(() => ({ text: "" }));
+  const parsed = await req.json().catch(() => ({ text: "" }));
+  const body = parsed && typeof parsed === "object" ? parsed : { text: "" };
+  const { text } = body as { text?: string };
  if (!text) return NextResponse.json({ error: { code: "bad_request", message: "text krävs" } }, { status: 400 });

  const eng = await engineFetch("/ai/parse", { method: "POST", body: JSON.stringify({ text }) });
@@ -1,3 +1,4 @@
+import { timingSafeEqual } from "node:crypto";
 import { NextRequest, NextResponse } from "next/server";
 import { signSession, SESSION_COOKIE } from "@/lib/auth";

@@ -9,7 +10,13 @@ export async function POST(req: NextRequest) {
    return NextResponse.json({ error: { code: "auth_not_configured", message: "AUTH_SECRET saknas" } }, { status: 501 });
  }
  const devKey = process.env.DEV_LOGIN_KEY;
-  if (!devKey || key !== devKey) {
+  // Constant-time compare: a plain !== leaks the number of matching leading
+  // bytes via response timing, letting an attacker recover DEV_LOGIN_KEY
+  // byte-by-byte instead of it being an all-or-nothing guess.
+  const keyBuf = Buffer.from(typeof key === "string" ? key : "");
+  const devKeyBuf = Buffer.from(devKey ?? "");
+  const keysMatch = Boolean(devKey) && keyBuf.length === devKeyBuf.length && timingSafeEqual(keyBuf, devKeyBuf);
+  if (!keysMatch) {
    return NextResponse.json({ error: { code: "forbidden", message: "Dev-login kräver giltig nyckel" } }, { status: 403 });
  }
  if (!email) {
@@ -11,6 +11,9 @@ export async function POST(req: NextRequest) {
  } catch {
    return NextResponse.json({ error: { code: "bad_json", message: "Invalid JSON body" } }, { status: 400 });
  }
+  if (!body || typeof body !== "object") {
+    return NextResponse.json({ error: { code: "bad_json", message: "Invalid JSON body" } }, { status: 400 });
+  }

  // Defer to the FastAPI data engine when it's running; fall back to local math.
  const eng = await engineFetch("/estimates", { method: "POST", body: JSON.stringify(body) });
@@ -19,6 +19,9 @@ export async function PATCH(req: NextRequest, ctx: { params: Promise<{ id: strin
  } catch {
    return NextResponse.json({ error: { code: "bad_json", message: "Invalid JSON" } }, { status: 400 });
  }
+  if (!body || typeof body !== "object") {
+    return NextResponse.json({ error: { code: "bad_json", message: "Invalid JSON body" } }, { status: 400 });
+  }
  const allowed = ["draft", "quoted", "deposit_pending", "in_production", "review", "revision", "accepted", "delivered"];
  if (!body.status || !allowed.includes(body.status)) {
    return NextResponse.json({ error: { code: "bad_status", message: "Ogiltig status" } }, { status: 400 });
@@ -9,6 +9,9 @@ export async function POST(req: NextRequest) {
  } catch {
    return NextResponse.json({ error: { code: "bad_json", message: "Invalid JSON" } }, { status: 400 });
  }
+  if (!body || typeof body !== "object") {
+    return NextResponse.json({ error: { code: "bad_json", message: "Invalid JSON body" } }, { status: 400 });
+  }
  const flow = body.flow || "custom";
  const config = body.config || {};
  const order = await createOrder(flow, config);
@@ -1,4 +1,5 @@
 import { NextRequest, NextResponse } from "next/server";
+import { getOrder } from "@/lib/orders-store";

 // POST /api/payments/[order_id]/deposit
 // Returns { url } for Stripe Checkout. Returns 501 when STRIPE_SECRET_KEY is absent.
@@ -13,19 +14,15 @@ export async function POST(
    return NextResponse.json({ error: "payment_not_configured" }, { status: 501 });
  }

-  const origin =
-    request.headers.get("origin") ??
-    process.env.NEXT_PUBLIC_APP_URL ??
-    "http://localhost:3000";
+  // Never derive from the client-supplied Origin header (SSRF + open-redirect vector) —
+  // request.nextUrl.origin reflects the actual request URL, not attacker-controlled input.
+  const origin = request.nextUrl.origin;

-  let depositOre = 44750;
-  try {
-    const orderRes = await fetch(`${origin}/api/orders/${order_id}`);
-    if (orderRes.ok) {
-      const order = (await orderRes.json()) as { deposit_ore?: number; total_ore?: number };
-      depositOre = order.deposit_ore ?? Math.round((order.total_ore ?? 89500) / 2);
-    }
-  } catch {}
+  const order = await getOrder(order_id);
+  if (!order) {
+    return NextResponse.json({ error: { code: "not_found", message: "Order saknas" } }, { status: 404 });
+  }
+  const depositOre = order.deposit_ore ?? Math.round((order.total_ore ?? 89500) / 2);

  const body = new URLSearchParams({
    "payment_method_types[0]": "card",
@@ -7,7 +7,8 @@ export async function GET() {
 }

 export async function POST(req: NextRequest) {
-  const body = await req.json().catch(() => ({}));
+  const parsed = await req.json().catch(() => ({}));
+  const body = parsed && typeof parsed === "object" ? parsed : {};
  if (!body.order_id) {
    return NextResponse.json({ error: { code: "bad_request", message: "order_id krävs" } }, { status: 400 });
  }
@@ -1,4 +1,4 @@
-import { NextRequest, NextResponse } from "next/server";
+import { NextResponse } from "next/server";

 // GET /api/uploads — list uploaded files. Returns 501 until storage is configured.
 export async function GET() {
@@ -10,9 +10,10 @@ export async function GET() {
 }

 // POST /api/uploads (docs/04) — issue a presigned R2 PUT URL. Env-guarded:
-// returns 501 until R2 storage is configured. Client then PUTs the file directly.
-export async function POST(req: NextRequest) {
-  const body = await req.json().catch(() => ({}));
+// returns 501 until R2 storage is configured, and until presign generation
+// is implemented — a configured-but-unimplemented state must not report
+// success. Client then PUTs the file directly.
+export async function POST() {
  const haveR2 = process.env.R2_ACCESS_KEY_ID && process.env.R2_BUCKET && process.env.R2_ENDPOINT;
  if (!haveR2) {
    return NextResponse.json(
@@ -20,6 +21,10 @@ export async function POST(req: NextRequest) {
      { status: 501 },
    );
  }
-  // With R2 configured: build a presigned PUT (S3-compatible) and return it.
-  return NextResponse.json({ file_id: crypto.randomUUID(), put_url: null, name: body?.name ?? null });
+  // TODO: presigned PUT generation not implemented yet — keep returning 501
+  // instead of a fake 200/null success shape until real R2 presign wiring exists.
+  return NextResponse.json(
+    { error: { code: "storage_not_configured", message: "Presignerad uppladdning är inte implementerad än" } },
+    { status: 501 },
+  );
 }
@@ -4,14 +4,14 @@ import { engineFetch } from "@/lib/engine";
 // GET /api/vehicles?plate=XX-99-YY — RDW (NL) open vehicle data (technical/fleet
 // only, no owner PII). Defers to the engine when running; else calls RDW directly.
 export async function GET(req: NextRequest) {
-  const plate = (req.nextUrl.searchParams.get("plate") ?? "").toUpperCase().replace(/[-\s]/g, "");
+  const plate = (req.nextUrl.searchParams.get("plate") ?? "").toUpperCase().replace(/[-\s]/g, "").replace(/[^A-Z0-9]/g, "");
  if (!plate) return NextResponse.json({ error: { code: "bad_request", message: "plate krävs" } }, { status: 400 });

  const eng = await engineFetch(`/vehicles/${plate}`);
  if (eng && eng.ok) return NextResponse.json(await eng.json());

  try {
-    const r = await fetch(`https://opendata.rdw.nl/resource/m9d7-ebf2.json?kenteken=${plate}`, {
+    const r = await fetch(`https://opendata.rdw.nl/resource/m9d7-ebf2.json?kenteken=${encodeURIComponent(plate)}`, {
      headers: { "User-Agent": "0pt/0.1 (+https://0pt.app; SIAX)" },
      cache: "no-store",
    });
@@ -65,6 +65,10 @@ export default function ProductionPage() {
  }, [id]);

  const finish = () => {
+    if (timer.current) {
+      clearInterval(timer.current);
+      timer.current = null;
+    }
    setProgress([100, 100, 100, 100, 100]);
    setMarkets([100, 100, 100, 100]);
    setConf(94);
@@ -6,7 +6,9 @@

 ## The three flows (everything reduces to these)

-Every service maps to one of three intake/delivery flows. The nine "categories" (scraping, structuring, datasets, ICP/leads, BI, ML, documents, subscriptions, custom) are **tags/filters within these flows**, not separate machinery.
+Every service maps to one of three intake/delivery flows (`Flow` in `lib/services.ts`: `catalog` | `custom` | `subscription`).
+
+*Correction: this section previously said "nine categories (scraping, structuring, datasets, ICP/leads, BI, ML, documents, subscriptions, custom)" — that list doesn't match `lib/services.ts`'s actual catalog and never did (no `structuring`, `datasets`, `subscriptions`, or `custom` service id exists there). The real catalog today (`lib/services.ts`, `SERVICES`) has 11 entries: data delivery, web scraping, mapping & matching, normalization, consolidation → CRM/ERP, documents & OCR, enrichment, ICP & leads, ML jobs, BI & market analysis, feeds & monitoring.* These are **tags/filters within the three flows**, not separate machinery — each entry carries a `flow` field pointing back to `catalog` / `custom` / `subscription`.

 1. **Catalog product** — ready-made, browse → sample → buy → deliver. Exists in Postgres or produced fast from the pipeline. Margin + scale.
 2. **Custom job** — does not exist yet; must be scoped. `configure (AI-assist) → estimate → manual scope/quote confirm → produce → QA → validate → deliver`. The hero flow. Consulting in a portal.
@@ -29,12 +31,14 @@ DRAFT → QUOTED → DEPOSIT_PENDING → IN_PRODUCTION → REVIEW
 - **DELIVERED**: exports + destinations unlocked; provenance log + quality report attached.
 - **SUBSCRIPTION_ACTIVE**: if converted to a feed.

+This is real, working code today, not just a spec: `app/api/orders/[id]/route.ts`'s `PATCH` handler enforces exactly this sequence (lowercase: `draft`, `quoted`, `deposit_pending`, `in_production`, `review`, `revision`, `accepted`, `delivered`) as its allowed-status list. One gap: `SUBSCRIPTION_ACTIVE` is **not** in that allowed list yet — feed conversion (Phase 7, `docs/09-build-plan.md`) isn't wired into the order status machine.
+
 ## Business / escrow model

 - **50 / 50.** Deposit (50 %) captured to start production. Balance (50 %) **held** and only captured/released on **ACCEPTED**. Revision never moves the held amount.
 - Pricing models: pay-per-job, volume, subscription (monthly), custom quote.
 - Estimate is a function of: selected field weights × markets × volume × entity multiplier × confidence-target multiplier + enrichment. Custom jobs get a manual scope/quote gate before DEPOSIT_PENDING.
- Stripe: deposit = capture now; balance = either a held authorization released on accept, or a second invoice on accept (implement as a second Checkout/invoice keyed to the order; see `docs/04-api.md`).
+- Stripe: deposit = capture now (`app/api/payments/[order_id]/deposit/route.ts`); balance = **a second Stripe Checkout session created on accept**, keyed to the order (`app/api/payments/[order_id]/release/route.ts`). *Correction: earlier drafts of this doc left the balance mechanism open ("either a held authorization … or a second invoice"). The second-Checkout-session approach is what's actually implemented — there is no held-PaymentIntent-capture path in the code.* Both routes are env-guarded on `STRIPE_SECRET_KEY` and return `501` until it's configured (`lib/stripe.ts`).

 ## Customer DB access (designed, not a checkbox)

@@ -46,4 +50,4 @@ SaaS-Martin (RevOps, wants clean ICP/leads), Bilhandlar-Bengt (vehicle + company

 ## First-launch scope (de-risked)

-Do **not** ship "20 markets × 9 categories." Ship the thinnest sellable slice: **Nordic company data** (the open stuff — GLEIF + Brreg + verified sources) + **vehicle data** (VehIQ synergy) as a couple of catalog datasets, **plus the custom-job intake**, Stripe, and delivery to download + into FiveCRM/Data Loader. First customers are Protosell internally + existing dealer relationships — services you already deliver, productized. Then expand markets as the sourcing map fills in.
+Do **not** ship "20 markets × 11 categories." Ship the thinnest sellable slice: **Nordic company data** (the open stuff — GLEIF + Brreg + verified sources) + **vehicle data** (VehIQ synergy) as a couple of catalog datasets, **plus the custom-job intake**, Stripe, and delivery to download + into FiveCRM/Data Loader. First customers are Protosell internally + existing dealer relationships — services you already deliver, productized. Then expand markets as the sourcing map fills in.
@@ -1,9 +1,20 @@
 # 02 · Architecture

+> **Known issues affecting this doc, in brief** — full detail + evidence in [`README.md`](../README.md)'s
+> "Known issues" section: (1) no auth/session system exists yet, so several newer routes trust
+> client-supplied `tenant_id` (see "Known gaps" below); (2) the CL0UD/N0D/AUD0/ST0RE platform clients are
+> real code but mock-only in this repo; (3) `docs/ICEBERG_WRITE_BOUNDARY.md` / `docs/11-lakehouse-write-plan.md`
+> / `docs/P0_QUERY_SOURCE_FLOW.md` reference several `src/services/quality-*` and `sql/002`/`sql/003` files
+> that were never actually committed to this repo (out of this doc's file scope to fix — flagged here so it
+> isn't silently repeated); (4) two git remotes (`github.com/sax3l/0pt` and `git.siax.io/sax3l/0pt`) have
+> diverged and it is unresolved which is authoritative — Simon's call, not assumed here.
+
 ## Principle: one database, many lenses

 Postgres is the source of truth. Everything else is a **lens** on it. A tool enters the stack only if it (a) reads that Postgres and (b) sits behind the same auth. This is the difference between an app and a pile of separate logins.

+This principle describes — and is largely realized by — the **original edge + engine plane**: marketing, catalog, order lifecycle, and the FastAPI engine. It does **not** describe the newer **P0 data-platform surface** (`app/api/0pt/*`), which is real, additive, and deliberately does not go through this same path. See "Two API surfaces" below.
+
 ```
                 ┌──────────────────────────────────────────────┐
   COLLECTION    │                  POSTGRES                     │   LENSES (customer + admin)
@@ -16,37 +27,128 @@ Postgres is the source of truth. Everything else is a **lens** on it. A tool ent
  Customer upload│                                               │   Export: CSV/Parquet/JSON/API/FiveCRM
                 └───────────────────▲──────────────────────────┘
                                     │
-                          FastAPI orchestrator + workers
+                        services/api — FastAPI orchestrator + workers
              (estimates, orders, jobs, AI-assist, webhooks, pipeline)
 ```

 ## Components & responsibilities

- **Next.js (Vercel)** — all customer/admin UI: marketing site, catalog, configurator, checkout, production tracker, validation, portal, admin. Calls FastAPI over an internal token. Embeds NocoDB/Metabase via signed URLs (no separate login shown).
- **FastAPI orchestrator** (`src/orchestrator`) — REST contract in `docs/04-api.md`: estimates, orders, AI-assist, uploads, deliveries, webhooks, catalog, sources, job status/SSE. **Not on Vercel** (serverless timeouts kill long jobs).
- **Workers** (`src/workers`) — adaptive router + pipeline stages (sourcing → extraction/OCR → structuring → enrichment/fusion → QA). Write to Postgres with provenance. See `docs/06-data-engine.md`.
- **Postgres** — backbone (`docs/03-data-model.md`) incl. `pgvector` for matching/embeddings.
- **NocoDB** — Airtable-style views over existing tables (no data duplication). Embedded into portal as "Min data".
- **Metabase** — customer-facing dashboards. Embedded.
- **Cloudflare R2** — file storage (uploads + deliverables) via presigned URLs.
- **Stripe** — deposit capture + escrow balance release.
- **Resend** — transactional email (order confirmation, "din data är klar", feedback).
- **Auth.js** (NextAuth) with a Postgres adapter — single auth for the whole app; NocoDB/Metabase hidden behind it.
+- **Next.js (Vercel)** — all customer/admin UI: marketing site, catalog, configurator, checkout, production tracker, validation, portal, admin. It also hosts **two distinct families** of API route handlers under `app/api/`: the original order/catalog/estimate surface (some of which defer to the FastAPI engine), and the newer P0 data-platform surface under `app/api/0pt/*` (does not defer to the engine at all — see below).
+- **FastAPI orchestrator** (`services/api/orchestrator/main.py`) — REST contract in `docs/04-api.md`: estimates, orders, sources, vehicle lookup, sanctions screening, job run/status. **Not on Vercel** (serverless timeouts kill long jobs). *Correction: earlier drafts of this doc pointed at `src/orchestrator`; that was the pre-migration location. `docs/09-build-plan.md` Phase 0 called for moving it into `services/api`, and that move has happened — the code lives at `services/api/orchestrator` today.*
+- **Workers** (`services/api/workers/`) — adaptive router (`adaptive_router.py`, verified: chooses only among compliant methods — official API → bulk → authorized web → licensed, no bypass/stealth/proxy-rotation tier exists in it, by design) + pipeline stages (`pipeline.py`, `queue.py`, `resolve.py`, `run.py`). See `docs/06-data-engine.md`.
+- **Postgres** — backbone (`docs/03-data-model.md`) incl. `pgvector` for matching/embeddings, for the original edge + engine plane. Wired via `lib/db.ts` (env-guarded: `DATABASE_URL`/`POSTGRES_URL`; falls back to an in-memory, non-durable store when unset, e.g. `lib/orders-store.ts`).
+- **NocoDB / Metabase** — both are defined as services in `infra/docker-compose.yml`; embedding them into the portal as "Min data" / customer dashboards is the target, not yet confirmed wired into a portal page in this pass.
+- **Cloudflare R2** — file storage (uploads + deliverables) via presigned URLs. Env-guarded (`app/api/uploads/route.ts` checks `R2_ACCESS_KEY_ID`/`R2_BUCKET`/`R2_ENDPOINT` and returns `501` until set); the presign call itself is still a stub (`put_url: null`) even when the env vars are present — not wired end-to-end yet.
+- **Stripe** — deposit capture + escrow balance release. This one **is** wired: `app/api/payments/[order_id]/deposit/route.ts` and `.../release/route.ts` are real Stripe Checkout calls (env-guarded on `STRIPE_SECRET_KEY`, `501` until configured). See the correction in `docs/01-product.md`'s business model section for exactly which escrow mechanism is implemented.
+- **Resend** — documented as the transactional-email provider (`docs/08-infrastructure.md`) but has no call site anywhere in this repo yet. Treat "+ email" as not-yet-implemented, not merely unconfigured.
+- **Auth.js (NextAuth) with a Postgres adapter** — this is the **target**, listed here as a stack decision, not a built component. What exists today is a lightweight signed-session scaffold (`lib/auth.ts`: HMAC-SHA256 via Web Crypto, no external deps) behind a guarded dev-only login gate (`DEV_LOGIN_KEY`). There is **no** real session-to-org/tenant binding anywhere in this repo. Full Auth.js + OAuth is Phase 3 of `docs/09-build-plan.md` and has not been built. This matters directly for the tenant-scoping gap described below.
+
+## Two API surfaces
+
+This repo currently contains **two real, distinct API surfaces**, not one. Earlier versions of this doc described the edge as a uniform thin proxy to the FastAPI engine — that was true for part of the original surface and remains true for that part, but a second, newer surface was added that is a deliberate, ADR-documented exception to it. Conflating the two is the single biggest way to misread this codebase's architecture.
+
+### 1. The original edge → engine surface
+
+A subset of the original `app/api/*` route handlers defer to the FastAPI engine (`services/api`) via `lib/engine.ts`'s `engineFetch()`/`hasEngine()` bridge when `ENGINE_URL` is set, and fall back to local computation when it isn't:
+
+- `app/api/estimates/route.ts` — defers to `POST {ENGINE_URL}/estimates`, falls back to `lib/data.ts`'s `computeEstimate`.
+- `app/api/vehicles/route.ts`, `app/api/screen/route.ts`, `app/api/ai/parse/route.ts` — same pattern.
+
+Other original routes are **not** engine-backed at all today: `app/api/orders/*` reads/writes `lib/orders-store.ts` directly (Postgres when configured, else in-memory); `app/api/catalog/route.ts` returns a hardcoded static array. Both of these are entirely edge-local — there is no engine call in either path currently, not "thin proxy with a local fallback."
+
+This surface is documented in full in `docs/04-api.md` and matches the "one Postgres, many lenses" principle above (once `DATABASE_URL` is set).
+
+### 2. The P0 data-platform surface (`app/api/0pt/*`)
+
+A second, newer surface implements dataset registration, Iceberg lakehouse table mapping/writes, per-source rate-policy management, bounded synchronous source querying, and mailbox-based document capture — **directly in the edge app**, backed by `src/services/*` and `src/clients/*`. It does **not** call `lib/engine.ts`/`ENGINE_URL` and does **not** go through the FastAPI engine at all. This is deliberate: it is the concrete implementation of **ADR-0030** (Apache Iceberg as SIAX's canonical lakehouse table format, authored in the `n0d` repo) and the ownership split it defines. See `docs/10-lakehouse-decision.md` (the pointer to the ecosystem decision), `docs/11-lakehouse-write-plan.md` (the plan), and `docs/ICEBERG_WRITE_BOUNDARY.md` (the implementation record) for the full boundary — this doc only summarizes it.
+
+Real, existing routes today (verified against the filesystem, not against `app/api/0pt/route.ts`'s own advertised list — see the note below):
+
+| Route | Backed by |
+|---|---|
+| `GET /api/0pt` | static index (see note below) |
+| `POST/GET /api/0pt/documents/capture` | `src/services/document-capture-service.ts` |
+| `.../documents/{documentId}/extraction` | `src/services/document-extraction-service.ts` |
+| `POST/GET /api/0pt/lakehouse/mappings` | `src/services/dataset-iceberg-mapping-service.ts`, `iceberg-write-service.ts` |
+| `.../lakehouse/mappings/{mappingId}` | same |
+| `POST .../lakehouse/mappings/{mappingId}/writes` | `src/services/iceberg-write-service.ts#requestIcebergWrite` |
+| `POST/GET /api/0pt/sources/rate-policies` | `src/services/source-rate-policy-service.ts` |
+| `.../sources/rate-policies/{sourceRatePolicyId}` | same |
+| `POST /api/0pt/sources/{sourceId}/query` | `src/services/source-query-service.ts` (bounded, timeout-guarded ad-hoc SQL against a registered `database` source — see `docs/P0_QUERY_SOURCE_FLOW.md`) |
+
+**Code-level inconsistency worth knowing about**: `app/api/0pt/route.ts`'s own `GET` handler advertises an `endpoints` list including `/api/0pt/sources`, `/api/0pt/datasets`, `/api/0pt/data-contracts`, `/api/0pt/quality/checks`, `/api/0pt/quality/reports`, `/api/0pt/features/views` — **none of these exist as routes** (confirmed by listing `app/api/0pt/` on disk); the lakehouse-mapping and rate-policy routes that *do* exist aren't listed there either. This is the same "described but never built" pattern as the `quality-check-service.ts` fabrication flagged below — this doc's route table above reflects what is actually on disk, not what the index endpoint claims.
+
+**In-memory scope**: every P0 service (`DatasetService`, `SourceService`, `DatasetIcebergMappingService`, `SourceRatePolicyService`, `DocumentCaptureService`, …) holds its state in a plain `Map` inside the Next.js route module that instantiates it. Most route modules construct a fresh instance per module, so a record created via one route is not visible to a different route module in the same running process (each file's own header comment documents this; `document-capture-service.ts` worked around it for its own two routes with a shared singleton export). A Postgres migration exists (`sql/004_iceberg_write_boundary.sql`) but is not wired into any route handler yet. So the "one database, many lenses" principle above does not yet hold for this surface.
+
+## Six-surface capability model & 0pt's current coverage
+
+SIAX Cloud's target model (defined in `cl0ud`, `docs/architecture/SIAX_CLOUD_UNIFIED_ARCHITECTURE.md`) is that one capability can expose up to **six surfaces**: REST **api**, **cli** (`siax 0pt ...`), **mcp** (an agent tool), **ui** (a page/panel), **job** (an async N0D job type), and **sdk** (a generated client method). The capability registry's own `Surface` type (`cl0ud` `packages/capability-registry/src/types.ts`) currently encodes five of those six as a declarative field (`'api' | 'cli' | 'mcp' | 'ui' | 'job'`); `sdk` is generated separately, not yet a registry field.
+
+**0pt's actual coverage today** (verified against `cl0ud packages/capability-registry/src/registry.ts`): 14 distinct `0pt.*` capabilities are registered —
+
+`0pt.query_source`, `0pt.document_ocr`, `0pt.write_external_record`, `0pt.lakehouse_mapping_manage`, `0pt.lakehouse_write`, `0pt.source_rate_policy_manage`, `0pt.screen_sanctions`, `0pt.estimate_compute`, `0pt.vehicle_lookup`, `0pt.catalog_list`, `0pt.source_registry_list`, `0pt.order_create`, `0pt.order_payment`, `0pt.write_iceberg_table`
+
+— and, checked entry by entry:
+
+- **11** declare `surfaces: ['api']` only.
+- **2** (`0pt.lakehouse_write`, `0pt.write_iceberg_table`) declare `surfaces: ['api', 'job']`.
+- **1** (`0pt.write_external_record`) declares `surfaces: ['job']` **only** — `apiEnabled: false`, and its own comment states it has "NO dedicated HTTP route in the 0pt app yet"; it exists as a tested TS service (`src/services/external-writeback-service.ts`) invoked only via direct import today, not a live callable path.
+- **Every single one** has `cliEnabled: false` and `mcpEnabled: false`. None has a `ui` surface entry either.
+
+In plain terms: **0pt is API-only today** (plus two job-backed writes, and one job-only capability with no live route at all). If any doc — inside or outside this repo — describes a live `siax 0pt ...` CLI command or an `0pt.*` MCP tool, it is describing a target, not current reality; correct it on sight.
+
+## Platform clients: CL0UD / N0D / AUD0 / ST0RE
+
+`src/clients/{cl0ud,n0d,aud0,st0re,st0re-lakehouse}-client.ts` are real, typechecked TypeScript with accompanying tests (`tests/p0/*`), each following the same shape: a thin interface, an HTTP implementation written against the target service's real, committed route contract, and a deterministic in-memory mock used whenever no `baseUrl` is supplied to the constructor.
+
+**Verified this pass**: none of the five client files, and none of their call sites in `src/services/*`, read `CL0UD_URL`, `N0D_URL`, `AUD0_URL`, or `ST0RE_URL` from `process.env` anywhere (`grep -rn "process.env" src/clients src/services` turns up nothing for any of those four names outside comments/TODOs). Every constructor call in this repo (`createCl0udClient(opts?.cl0udBaseUrl)`, etc.) is invoked with no `baseUrl` argument, so **every one of these clients runs against its in-memory mock today, in every code path that exists in this repo.** Read this as "real code, mock-only, not live-verified" — not "integrated" or "connected" — wherever platform-client status comes up.
+
+What each client is for, concretely:
+
+- **CL0UD** — policy evaluation (`evaluatePolicy`). `iceberg-write-service.ts` and `external-writeback-service.ts` call it before acting; the mock always returns `"allow"`.
+- **N0D** — job requests (`createJob`). `document-capture-service.ts` requests document-extraction jobs; `iceberg-write-service.ts` requests heavy-write/compaction jobs. 0pt only *requests* N0D jobs — it never executes them, per `docs/ICEBERG_WRITE_BOUNDARY.md`'s "N0D executes" boundary. **No evidence supports a claim that N0D has a dedicated-node ("`t_0pt`") auth pattern already built for this**: `n0d`'s repository was searched in full (all branches, all commits, all files) and contains zero references to `t_0pt`. Treat any such claim as unconfirmed until proven otherwise.
+- **AUD0** — audit/lineage events (`ingestEvent`, `ingestLineageEvent`). Every mutating P0 service emits these; the mock is a true no-op, matching AUD0's own documented stance that it has no live ingestion endpoint yet.
+- **ST0RE / ST0RE-lakehouse** — artifact-metadata registration and Iceberg table/namespace/snapshot registration, respectively. `st0re-lakehouse-client.ts`'s HTTP path is written against `sax3l/st0re`'s actual shipped route contract (commit `9ea0abb`, read directly during a prior pass) — real code, but not executed against a running ST0RE in this repo's test environment either.
+
+## Known gaps
+
+### tenant_id is not server-bound anywhere in the P0 surface
+
+The platform-wide rule is that `tenant_id` must be bound to an authenticated session server-side and never trusted from client input. This repo violates that rule today, and it is **not** a deliberate two-tier design — it's a direct consequence of there being no auth/session system at all yet (see the Auth.js note above; `app/api/orders/route.ts`'s own `GET` handler literally comments `// org scoping added with auth`, i.e. not yet).
+
+Concretely: `tenant_id`/`project_id` are accepted straight from the client-supplied request body (or query string) at every P0 mutation entry point —
+
+- `app/api/0pt/lakehouse/mappings/route.ts` (POST)
+- `app/api/0pt/sources/rate-policies/route.ts` (POST)
+- `app/api/0pt/sources/[sourceId]/query/route.ts` (POST)
+- `app/api/0pt/documents/capture/route.ts` → `src/services/document-capture-service.ts#captureFromMailbox`
+
+`app/api/0pt/lakehouse/mappings/[mappingId]/writes/route.ts` doesn't read `tenant_id` from its own body — but it resolves the tenant by looking up `mapping.tenant_id` from a mapping that was itself created via one of the unauthenticated routes above, so the trust boundary problem is inherited, not avoided.
+
+Do not expose any of these routes to untrusted callers before Phase 3 of `docs/09-build-plan.md` (Auth.js + org/session binding) lands. This is Simon's call on sequencing, not something to silently patch in a docs pass.
+
+### 0pt's data-quality/QA stage is a fabrication in sibling docs, not built
+
+Flagged so it is not repeated: `src/services/quality-check-service.ts`, `src/services/quality-report-service.ts`, `src/types/quality-check.ts`, `src/types/quality-report.ts`, `src/data-platform/services/catalog-service.ts`, `sql/002_p0_dataset_quality.sql`, and `sql/003_*.sql` were at one point referenced in `docs/ICEBERG_WRITE_BOUNDARY.md`, `docs/11-lakehouse-write-plan.md`, and `docs/P0_QUERY_SOURCE_FLOW.md` as if already built and tested. Verified this pass: `git log --all` for every one of those paths returns zero commits, on any branch, ever — `sql/` on disk today contains only `001_init.sql` and `004_iceberg_write_boundary.sql`. Those files have never existed in this repository. 0pt's data-quality/QA enforcement is **spec/target only** — a real, open build gap, not a doc typo. **All three of the docs above have since been corrected** (verified this pass by reading each in full) — none currently asserts those files as real; each carries its own explicit "fabricated, not built" callout, and `docs/P0_DATASET_QUALITY_FLOW.md` is the honest target-spec replacement.
+
+### Two diverged git remotes
+
+`origin` in local checkouts of this repo is `github.com/sax3l/0pt`. A separate Gitea remote, `git.siax.io/sax3l/0pt`, shares at least part of the same history (`services/api/workers/adaptive_router.py` is byte-for-byte identical between GitHub's current `main` and a Gitea post-fix PR branch) but independently accumulated commits GitHub's `main` never received — including, at one point, a WAF-bypass/proxy-rotation/fake-identity scraper stack that directly violated the CLAUDE.md §1 sourcing rule (since removed on Gitea via a separate PR). **Which remote is authoritative, which is actually deployed to `0pt.app`, and whether the two should be kept in sync is unresolved and is Simon's decision** — do not assume `origin`/GitHub is the sole copy of this codebase, here or in any other doc.

 ## Stack decisions — IN

 | Concern | Choice | Why |
 |---|---|---|
 | Frontend | Next.js App Router + TS + Tailwind + shadcn/ui | Vercel-native, matches existing skills |
-| Backend/jobs | FastAPI + workers (existing) | already built; long-running jobs |
+| Backend/jobs | FastAPI + workers (`services/api`) | already built; long-running jobs |
 | DB | Postgres (+ pgvector) | backbone; Neon free tier or on-VPS |
 | Airtable layer | **NocoDB** | sits on existing tables, no duplication |
 | BI | **Metabase** | customer-facing embedding, simple |
 | Files | Cloudflare R2 + presigned URLs | cheapest S3-compatible |
-| Payments | Stripe Checkout + webhook → FastAPI | ~1 day, no SaaS boilerplate needed |
-| Auth | Auth.js + Postgres adapter | one system |
-| Email | Resend | best Next.js integration, free tier |
-| Quality | Great Expectations / checks **inside workers** | scores shipped with each order |
+| Payments | Stripe Checkout + webhook → Next.js API | ~1 day, no SaaS boilerplate needed |
+| Auth | Auth.js + Postgres adapter | one system — **target, not yet built** (see Components above) |
+| Email | Resend | best Next.js integration, free tier — **not yet wired** (no call site in this repo) |
+| Quality | Great Expectations / checks **inside workers** | scores shipped with each order — **not yet built** for the P0 surface (see "Known gaps" above) |

 ## Stack decisions — OUT (do not add)

@@ -58,13 +160,13 @@ Postgres is the source of truth. Everything else is a **lens** on it. A tool ent
 | Meilisearch (v1) | Postgres full-text suffices to a few thousand rows; add later |
 | Delta Sharing (v1) | unnecessary; customer pull via scoped role + exports |
 | Trigger.dev | the existing queue already schedules jobs; Resend covers mail |
-| FlareSolverr / stealth browsers / undetected-* / proxy-fingerprint rotation / fake-account creation | **prohibited** — see CLAUDE.md §1. Replace with compliant fetching |
+| FlareSolverr / stealth browsers / undetected-* / proxy-fingerprint rotation / fake-account creation | **prohibited** — see CLAUDE.md §1. Replace with compliant fetching. (The Gitea-only scraper stack described under "Two diverged git remotes" above is exactly this — removed there, never present on GitHub `main`.) |

 ## Hosting (cheapest coherent)

 - **Vercel** (Hobby/free) — Next.js + custom domain `0pt.app`.
- **One small VPS** (e.g. Hetzner ~€5/mo) running `docker-compose`: FastAPI, workers, NocoDB, Metabase, (Postgres or use Neon), optional Meilisearch later. Per-service managed platforms (Railway) get expensive once you have 4–5 always-on services; a single VPS + Vercel + R2 lands ≈ <€10/mo to start.
- **Cloudflare R2** — object storage.
+- **One small VPS** (e.g. Hetzner ~€5/mo) running `docker-compose` (`infra/docker-compose.yml`): FastAPI, workers, NocoDB, Metabase, (Postgres or use Neon), optional Meilisearch later. Per-service managed platforms (Railway) get expensive once you have 4–5 always-on services; a single VPS + Vercel + R2 lands ≈ <€10/mo to start.
+- **Cloudflare R2** — object storage (env-guarded, presign not yet wired — see Components above).
 - **Postgres** — on the VPS, or **Neon** free tier if you want it managed.

-Full config, env, security, CI/CD: `docs/08-infrastructure.md`.
+Full config, env, security, CI/CD: `docs/08-infrastructure.md`. Env var inventory: `.env.example` exists on branch/PR [`feature/0pt-env-example`](https://github.com/sax3l/0pt/pull/3) (unmerged as of this pass) — until it merges to `main`, `docs/08-infrastructure.md` is the source of truth for env var names.
@@ -1,6 +1,10 @@
 # 03 · Data model

-Postgres is the backbone. Two halves: **data entities** (what we sell) and **platform tables** (orders, users, jobs). Every fact links to `bridge_provenance`. Migrations via Alembic (Python) or `sql/` migrations checked into the repo — pick one and be consistent; align with existing `src/workers/db.py`.
+Postgres is the backbone. Two halves: **data entities** (what we sell) and **platform tables** (orders, users, jobs). Every fact links to `bridge_provenance`.
+
+**Migrations are plain SQL files in `sql/`, applied in filename order.** There is no Alembic (or any other Python migration tool) anywhere in this repo, and no `src/workers/db.py` — that file does not exist (the Python engine's workers live in `services/api/workers/` — `adaptive_router.py`, `pipeline.py`, `queue.py`, `resolve.py`, `run.py` — none of them named `db.py`, and there is no TypeScript `src/workers/` directory either; `src/` only has `adapters/`, `clients/`, `services/`, `types/`). `infra/docker-compose.yml` mounts `../sql` as `/docker-entrypoint-initdb.d` on the `postgres` service, so Postgres auto-applies every `.sql` file in that directory, in name order, the first time that container initializes its data volume.
+
+**Only two migration files exist in this repo, ever:** `sql/001_init.sql` and `sql/004_iceberg_write_boundary.sql` (verified via `find sql/` — no `002` or `003`). Three other docs in this repo (`docs/ICEBERG_WRITE_BOUNDARY.md`, `docs/11-lakehouse-write-plan.md`, `docs/P0_QUERY_SOURCE_FLOW.md`) mention `sql/002_p0_dataset_quality.sql` and `sql/003_*.sql` by name — they don't exist, on any branch, ever (git history checked) — but all three have been corrected to say exactly that (each carries its own "never existed" callout, none claims the files are real as of this pass). This file only asserts what's true of `sql/001` and `sql/004`, which are real.

 ## Conventions

@@ -11,6 +15,8 @@ Postgres is the backbone. Two halves: **data entities** (what we sell) and **pla

 ## Data entities

+Mirrors `sql/001_init.sql` (verified against the file this pass; the migration additionally wraps every statement in `CREATE TABLE IF NOT EXISTS` for idempotent re-runs, and enables `pgcrypto` alongside `vector` — needed for `gen_random_uuid()`):
+
 ```sql
 -- A company (the core registry entity)
 CREATE TABLE dim_company (
@@ -98,8 +104,12 @@ CREATE INDEX ON bridge_provenance (entity_type, entity_key);

 > Rule: **no value ships without a `bridge_provenance` row.** Level 0 = delivered as "not available / licensed", never a guessed value.

+`dim_source` is a **different, older entity** than the per-tenant `Source` registry described below (`src/types/source.ts`) that `0pt.query_source` acts against — same name-ish concept, two separate schemas. `src/types/source.ts`'s own doc comment calls this out, but its "~9-row list of national registries served today by `GET /api/sources`" phrasing is easy to misread: `dim_source` itself, as a Postgres table, has **zero rows** — `sql/001_init.sql` only creates the table, there is no seed/`INSERT` statement anywhere in this repo's SQL or Python (grep-verified for `INSERT INTO dim_source`). The actual 9-entry national-registry list that comment is pointing at lives in a third, distinct artifact: the edge-native `GET /api/sources` route (`app/api/sources/route.ts`), a hardcoded array with a `confidence` field. That's different again from the FastAPI engine's `sources.yaml` (8 entries, no `confidence` field — see `docs/04-api.md`'s Sources section). So there are three separate "source list" artifacts in this repo — the empty `dim_source` SQL table, `sources.yaml` (8), and `app/api/sources/route.ts` (9) — none of which currently share data with each other; see "TypeScript-side P0 entities" below for the fourth, per-tenant `Source` type.
+
 ## Platform tables

+Mirrors `sql/001_init.sql` (verified this pass — same tables, same columns):
+
 ```sql
 CREATE TABLE orgs (
  org_id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
@@ -191,11 +201,71 @@ CREATE TABLE payments (
 );
 ```

+> **Gap, verified this pass:** `sql/001_init.sql` does **not** contain `order_items`. It is documented here (and was already documented before this pass) as part of the target platform-table set, but there is no `CREATE TABLE order_items` in the migration file — check before relying on it existing in any real database.
+
+> **Gap, verified this pass:** this schema is real and (if `infra/docker-compose.yml`'s `postgres` service is actually run) gets created — but the FastAPI engine's own code never connects to it. `services/api/orchestrator/main.py` has no `asyncpg`/`psycopg`/`sqlalchemy` import anywhere (grep-verified across `services/api/`), and its `orders`/`jobs` state lives entirely in two module-level Python dicts (`_ORDERS`, `_JOBS`) that reset on every process restart and are never written to Postgres. The one `DATABASE_URL` reference in `main.py` (`GET /health`) only reports whether the env var is *set* — it never opens a connection. See `docs/04-api.md`'s implementation-status section for the full picture. Until that wiring lands, this table set is schema-only, not a live system of record.
+
+## P0 registry tables (`sql/004_iceberg_write_boundary.sql`)
+
+A second, newer migration adds two tables for the lakehouse write-path and crawl-compliance capabilities (`0pt.write_iceberg_table`, `0pt.source_rate_policy_manage` — see the new edge-API doc, `docs/12-edge-capability-api.md`). Verified against the file this pass:
+
+```sql
+CREATE TABLE opt_dataset_iceberg_mappings (
+  dataset_iceberg_mapping_id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  project_id TEXT NOT NULL,
+  dataset_id TEXT NOT NULL REFERENCES opt_datasets (dataset_id),
+  iceberg_table_id TEXT NOT NULL,        -- reference into ST0RE's table registry, NOT a foreign key
+  namespace TEXT,
+  table_name TEXT,
+  mapping_status TEXT NOT NULL DEFAULT 'active',
+  mapped_by TEXT,
+  correlation_id TEXT,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ
+);
+
+CREATE TABLE opt_source_rate_policies (
+  source_rate_policy_id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  project_id TEXT NOT NULL,
+  source_id TEXT NOT NULL REFERENCES opt_sources (source_id),
+  rate_limit_per_minute NUMERIC NOT NULL,
+  crawl_budget NUMERIC NOT NULL,
+  compliance_notes TEXT,
+  domain TEXT,
+  robots_ok BOOLEAN,
+  access TEXT,
+  status TEXT NOT NULL DEFAULT 'active',
+  correlation_id TEXT,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ,
+  created_by TEXT
+);
+```
+
+`iceberg_table_id` is deliberately **not** a foreign key — it references ST0RE's own `st0re_iceberg_tables.table_id`, a different service's database. 0pt holds only the reference, never a copy of ST0RE's table/catalog/snapshot state (see the module doc comment on `src/clients/st0re-lakehouse-client.ts`, and `docs/ICEBERG_WRITE_BOUNDARY.md` for the full ownership boundary — that doc is outside this file's scope to otherwise correct).
+
+> **Confirmed bug, found this pass — flagging plainly, not silently fixing it:** both `CREATE TABLE` statements above have a `REFERENCES` clause pointing at tables that **do not exist anywhere in this repo's SQL**: `opt_dataset_iceberg_mappings.dataset_id REFERENCES opt_datasets (dataset_id)` and `opt_source_rate_policies.source_id REFERENCES opt_sources (source_id)`. Neither `opt_datasets` nor `opt_sources` is created by `sql/001_init.sql`, `sql/004_iceberg_write_boundary.sql`, or any other file in `sql/` (grep-verified — there are only two migration files, full stop). If `sql/004_iceberg_write_boundary.sql` is ever actually run against a fresh database (e.g. via `infra/docker-compose.yml`'s `docker-entrypoint-initdb.d` mount), **it will fail** with `relation "opt_datasets" does not exist`. This is not a naming coincidence: `src/types/dataset.ts` and `src/types/source.ts` define exactly the `Dataset`/`Source` shapes those table names imply, and `DatasetService`/`SourceService` (`src/services/`) are their in-memory-only implementations — but no migration ever creates the SQL tables to back them. **Open question for Simon:** either author a migration that creates `opt_datasets`/`opt_sources` before `sql/004` (so the FK resolves), or drop those two `REFERENCES` clauses and enforce the dataset/source-exists check purely in the TypeScript service layer (which already does the check today, redundantly, in `DatasetIcebergMappingService.createMapping` and `SourceRatePolicyService.createSourceRatePolicy`) — this file does not choose between those for you.
+
+## TypeScript-side P0 entities without SQL backing
+
+Newer P0 capabilities (`docs/12-edge-capability-api.md`) introduced their own typed entities under `src/types/`, each with an in-memory-only service under `src/services/`. Only two of these (above) have a real migration. The rest have **no SQL table at all** — every instance of the owning service starts with an empty in-memory `Map` and loses all state on restart (or even between two `new XService()` calls in the same process — see `docs/12-edge-capability-api.md`'s "in-memory isolation" findings for exactly how badly this bites in practice today):
+
+| Type | File | Service (in-memory only) | SQL table |
+|---|---|---|---|
+| `Source` | `src/types/source.ts` | `src/services/source-service.ts` | none |
+| `Dataset` | `src/types/dataset.ts` | `src/services/dataset-service.ts` | none |
+| `DocumentRecord` | `src/types/document.ts` | `src/services/document-capture-service.ts` | none |
+| `DocumentExtractionRecord` | `src/types/document-extraction.ts` | `src/services/document-extraction-service.ts` | none |
+| `ExternalWriteRecord` | `src/types/external-writeback.ts` | `src/services/external-writeback-service.ts` | none |
+| `DatasetIcebergMapping` | `src/types/dataset-iceberg-mapping.ts` | `src/services/dataset-iceberg-mapping-service.ts` | `opt_dataset_iceberg_mappings` (`sql/004`) |
+| `SourceRatePolicy` | `src/types/source-rate-policy.ts` | `src/services/source-rate-policy-service.ts` | `opt_source_rate_policies` (`sql/004`) |
+
 ## pgvector

-`CREATE EXTENSION vector;` Use for entity matching/dedup and for the AI-assist (semantic match of NL request → catalog/config). Store embeddings in a `embeddings` table keyed by `(entity_type, entity_key)` or alongside catalog rows.
+`CREATE EXTENSION vector;` — this is real (`sql/001_init.sql` line 3, along with `pgcrypto`). **Everything past the extension is target only:** there is no `embeddings` table, or any other table using the `vector` type, anywhere in `sql/001_init.sql` or `sql/004_iceberg_write_boundary.sql`. The intended use (entity matching/dedup, AI-assist semantic match of NL request → catalog/config) is a real design goal, not yet a real table.

 ## Row-level security & catalog

- Catalog products: a `catalog` table (or view) over curated datasets with sample rows, counts, coverage, price.
- Per-customer data isolation enforced by `org_id` filtering in the API and (where exposed via NocoDB/Metabase) by scoped views/connection params, plus Postgres RLS where practical.
+**Target only — none of this exists in `sql/` today**, verified by grep for `ROW LEVEL SECURITY`, `CREATE POLICY`, and `catalog` across both migration files (no matches beyond a comment). There is no `catalog` table or view, and no Postgres RLS policy anywhere in this repo's SQL. Per-customer isolation is intended to be `org_id` filtering in the API plus RLS where practical — but as of this pass the FastAPI engine (`services/api/orchestrator/main.py`) has **no `org_id` concept in any request or response at all** (see `docs/04-api.md`'s implementation-status section: `GET /orders` returns every order in the process, unfiltered). This is the same platform-wide "no auth/session system exists yet" gap noted across this doc corpus — not a data-model-specific problem to solve here, but the schema above cannot be considered tenant-isolated until it is.
@@ -1,25 +1,46 @@
 # 04 · API contract (FastAPI)

-Canonical REST contract. Reconcile the existing 25+ endpoints in `src/orchestrator/main.py` toward this. JSON in/out, `snake_case`. All amounts in **öre**. Auth: Next.js → FastAPI over a shared internal token (`X-Internal-Token`); customer identity passed as `org_id`/`user_id` resolved from the Auth.js session server-side.
+Canonical REST contract for the **Python data engine** — `services/api/orchestrator/main.py`, run on a VPS/worker host, not on Vercel. JSON in/out, `snake_case`. All amounts in **öre**.

-## Conventions
- Errors: `{ "error": { "code", "message" } }`, proper HTTP status. Interface-voice messages (Swedish) are produced in the frontend, not here.
- Idempotency: accept `Idempotency-Key` on POSTs that create orders/payments.
- Pagination: `?limit=&cursor=`.
+**Scope note:** this doc covers *only* the FastAPI engine. The newer edge-native TypeScript P0 capability surface (`app/api/0pt/*`, `/api/screen`, `/api/ai/parse` — Next.js Route Handlers that run on Vercel) is a separate, additive layer with its own contract: see `docs/12-edge-capability-api.md`. The two are not the same service and, as of this pass, are not fully wired together (see "Existing-code reconciliation" below for a concrete case where the edge layer expects an engine route that doesn't exist).
+
+## Implementation status (verified this pass — read before trusting any endpoint below)
+
+The engine file is `services/api/orchestrator/main.py` (162 lines) — not `src/orchestrator/main.py`, which does not exist in this repo (older doc text, including CLAUDE.md's "Build on existing code" section, still uses that stale path). It implements **exactly 12 endpoints**, all listed below — not "25+" as CLAUDE.md and the previous version of this doc claimed. That number does not match anything in the current codebase; flagging it here since it's this doc's own error to fix (CLAUDE.md's copy of the same claim is outside this file's scope).
+
+Endpoints that exist in `main.py` today: `GET /health`, `GET /sources`, `GET /sources/{market}`, `GET /vehicles/{plate}`, `GET /screen`, `POST /estimates`, `POST /orders`, `GET /orders`, `GET /orders/{oid}`, `PATCH /orders/{oid}`, `POST /orders/{oid}/run`, `GET /orders/{oid}/status`.
+
+Everything else in this document — payments/escrow, uploads, customer DB-grant, deliveries, subscriptions, outbound webhooks, `/orders/{id}/events` (SSE), `/orders/{id}/scope|accept|revise` — is a **target contract for the engine**, not yet implemented in `main.py`. Some of it already exists as a *separate* Next.js edge route instead (payments, orders, catalog, estimates, vehicles, sources all have edge-layer counterparts under `app/api/` — not read in detail for this pass, since they're outside this doc's FastAPI scope; noted only so you don't assume they don't exist anywhere).
+
+Three structural gaps apply to **every** endpoint below that main.py does implement:
+
+- **No persistence.** `main.py` has no `asyncpg`/`psycopg`/`sqlalchemy` import anywhere. `_ORDERS` and `_JOBS` are plain module-level Python `dict`s — state is lost on every restart, and never touches the `orders`/`jobs` tables `docs/03-data-model.md` documents. `GET /health`'s `db` field only reports whether the `DATABASE_URL` env var is *set* (`bool(os.getenv(...))`) — it never opens a connection, so it does not indicate the database is actually reachable or in use.
+- **No authentication, no tenant scoping.** `main.py` never reads any request header (no `X-Internal-Token` check, despite the edge layer sending one — see `lib/engine.ts`), and no request/response model anywhere carries `org_id` or `user_id`. Concretely: **`GET /orders` returns every order held by the process, for every org, with no filtering at all.** The "Auth: … customer identity passed as `org_id`/`user_id` resolved from the Auth.js session server-side" framing below is the target design, not current behavior — this is the same platform-wide "no auth/session system exists yet" gap noted across this doc corpus (see `docs/09-build-plan.md` Phase 3), not something specific to fix in this file.
+- **No idempotency, no pagination.** Neither is implemented by any endpoint in `main.py` today, despite being listed as target conventions below.
+
+## Conventions (target contract — see gaps above for current reality)
+
+- Errors: `{ "error": { "code", "message" } }`, proper HTTP status. *(Not implemented in `main.py`: it raises plain FastAPI `HTTPException(status, "message")`, which serializes as `{"detail": "message"}`, not the `{error:{code,message}}` shape below.)* Interface-voice messages (Swedish) are produced in the frontend, not here.
+- Idempotency: accept `Idempotency-Key` on POSTs that create orders/payments. *(Target only — not implemented.)*
+- Pagination: `?limit=&cursor=`. *(Target only — not implemented; `GET /orders` returns the full unfiltered list.)*
+- Auth: Next.js → FastAPI over a shared internal token (`X-Internal-Token`, `lib/engine.ts` sends it via `INTERNAL_TOKEN`) — the edge side of this is real, but `main.py` never validates the header, so today it has no effect. Customer identity as `org_id`/`user_id` resolved from an Auth.js session is target design; no such session system exists in this repo yet.

 ## Catalog
+
 ```
 GET  /catalog                      -> [{id,title,markets,entity_type,count,updated,price_ore,confidence}]
 GET  /catalog/{id}                 -> full dataset (overview, coverage, schema, quality summary)
 GET  /catalog/{id}/sample?n=10     -> sample rows WITH per-field provenance
 ```
+**Status: target only.** No `/catalog` route exists in `main.py`. A separate `GET /api/catalog` exists at the edge (`app/api/catalog/route.ts`, registered in CL0UD's capability registry as `0pt.catalog_list`) — not read in detail for this pass; out of scope here.

 ## Estimate (configurator → price/time/confidence)
 ```
 POST /estimates
-  body: { flow, markets[], entity_type, fields[], enrichment[], volume, frequency, confidence_target, formats[] }
-  -> { total_ore, deposit_ore, balance_ore, est_days, est_confidence, breakdown[] }
+  body: { markets[], entity_type, fields[], enrichment[], volume, frequency, confidence_target }
+  -> { total_ore, deposit_ore, balance_ore, est_days, est_confidence, recurring }
 ```
+**Status: implemented**, but the shape differs from the previous version of this doc: the request body has **no `flow` field**, and the response has **no `breakdown[]` field** — `main.py`'s `EstimateIn` model is exactly `{markets, entity_type, fields, enrichment, volume, frequency, confidence_target}` (defaults: `entity_type="Bolag"`, `volume=1000`, `frequency="Engångs"`, `confidence_target=92`), and `compute_estimate()` returns exactly `{total_ore, deposit_ore, balance_ore, est_days, est_confidence, recurring}` — `recurring` is a bool (`frequency != "Engångs"`), not a `breakdown[]` array. There is also no `formats[]` field on the request.

 ## AI-assist (NL → config)
 ```
@@ -27,16 +48,18 @@ POST /ai/parse
  body: { text }                   -- "5000 svenska SaaS-bolag med e-post och omsättning"
  -> { config: <estimate body>, rationale }   -- prefilled configurator; uses pgvector match to catalog/fields
 ```
+**Status: not implemented — confirmed contract mismatch.** `main.py` has no `/ai/parse` route at all (grep-verified: only the 12 endpoints listed in "Implementation status" exist). This matters beyond "target only": the edge route `app/api/ai/parse/route.ts` **actively calls** `engineFetch("/ai/parse", {method:"POST", ...})` expecting the engine to have this route, checks `if (eng && eng.ok)`, and — because the engine 404s — silently falls through to a local keyword-heuristic parser every time, even when `ENGINE_URL` is configured and the engine is reachable. See `docs/12-edge-capability-api.md` for the edge side of this route. There is also no pgvector usage anywhere in `main.py` (no `embeddings` table exists either — see `docs/03-data-model.md`).

 ## Orders (lifecycle)
 ```
-POST /orders                       body: { flow, config }            -> { order_id, status:'draft'|'quoted' }
-GET  /orders                       -> [orders for org]
-GET  /orders/{id}                  -> order + current job + delivery (if any)
-POST /orders/{id}/scope            (custom flow) body:{ notes }      -> status:'quoted' (manual quote step)
-POST /orders/{id}/accept           customer approves delivery        -> triggers balance release; status:'accepted'
-POST /orders/{id}/revise           body:{ notes }                    -> status:'revision'; escrow untouched
+POST /orders                       body: { flow, config }            -> { order_id, status:'draft', deposit_ore, total_ore }
+GET  /orders                       -> [orders]  -- NOT filtered by org; returns every order in the process (no auth)
+GET  /orders/{id}                  -> { ...order, job }               -- job is null if none exists yet; no "delivery" field (deliveries aren't implemented)
+PATCH /orders/{id}                 body: { status }                  -> updates order.status to any caller-supplied string, no validation against a lifecycle enum
+POST /orders/{id}/run              -> runs the pipeline SYNCHRONOUSLY (awaits workers/pipeline.py:run_job), sets status "in_production" then "review", returns the job record
+GET  /orders/{id}/status           -> the job record, or {stage:"queued", pct:0, state:"queued"} if none exists (never 404s)
 ```
+**Status: partially implemented, but shaped differently from the target below.** What actually exists: `POST /orders`, `GET /orders`, `GET /orders/{oid}`, `PATCH /orders/{oid}`, `POST /orders/{oid}/run`, `GET /orders/{oid}/status` — six endpoints, listed above with their real behavior. What the original target contract described — `POST /orders/{id}/scope` (manual quote step), `POST /orders/{id}/accept` (triggers balance release), `POST /orders/{id}/revise` — **do not exist in `main.py` at all.** Order-status transitions today happen only through the generic `PATCH /orders/{oid}` (accepts any string, no state-machine enforcement) or implicitly through `POST /orders/{oid}/run`. `POST /orders/{oid}/run` itself is undocumented in any prior version of this doc despite being the only way to actually trigger the sourcing pipeline — it has no payment/escrow gate of any kind (see Payments below).

 ## Payments (50/50 escrow)
 ```
@@ -44,19 +67,21 @@ POST /payments/{order_id}/deposit  -> { checkout_url }   (Stripe Checkout for 50
 POST /payments/{order_id}/release  -> captures/charges the held balance (called on accept)
 POST /webhooks/stripe              (Stripe → here) verify signature; update payments + order status
 ```
-> Implement balance as either a manual capture on a held PaymentIntent, or a second Checkout/invoice keyed to `order_id`. Never charge balance before `accept`.
+**Status: not implemented in the engine at all.** There is no Stripe reference anywhere in `services/api/` (grep-verified). `POST /orders/{oid}/run` — the engine's only way to start production — has no payment dependency whatsoever; nothing in `main.py` checks that a deposit was paid before running a job. If Stripe/escrow exists anywhere in this repo, it's at the edge (`app/api/payments/[order_id]/deposit`, `app/api/payments/[order_id]/release`, `app/api/webhooks/stripe` — registered in CL0UD's capability registry as `0pt.order_payment`, evidence comment notes both routes 501 when `STRIPE_SECRET_KEY` is unset) — not read in detail this pass, out of scope here. **Open question:** whether escrow/payment gating is meant to live in the FastAPI engine (as this doc's original framing implies) or stay purely at the edge is unresolved; this doc doesn't decide it for you.

 ## Jobs / live status
 ```
 GET  /orders/{id}/status           -> { stage, pct, per_market[], confidence, eta, rows }
 GET  /orders/{id}/events           -> Server-Sent Events stream (preferred for the production tracker)
 ```
+**Status: `GET /orders/{id}/status` exists but returns a different, smaller shape** — the actual dict returned by `workers/pipeline.py:run_job()` is exactly `{stage, pct, state, metrics, records}` (verified by reading its `return` statement) — **not** `{stage, pct, per_market[], confidence, eta, rows}` as previously documented, and **not** `started_at`/`finished_at` either (those two column names exist only on the unused `jobs` SQL table in `docs/03-data-model.md` — the in-memory job dict `run_job` actually returns has no timestamps at all). `metrics` itself is `{rows, dropped_below_threshold, per_market, avg_confidence}`; `records` holds the delivered rows. `GET /orders/{id}/events` (SSE) **does not exist** — target only.

 ## Uploads (R2 presigned)
 ```
 POST /uploads                      body:{ order_id, name, mime, bytes } -> { file_id, put_url }  (client PUTs to R2)
 GET  /orders/{id}/files            -> [files]
 ```
+**Status: target only.** Neither route exists in `main.py`.

 ## Customer DB access (read-only grant)
 ```
@@ -65,18 +90,28 @@ POST /connections/db-grant
  -> { grant_id, status:'pending'|'verified' }
 DELETE /connections/db-grant/{id}  -> revoke
 ```
+**Status: target only.** Neither route exists in `main.py`. The `db_grants` table exists in `sql/001_init.sql` (see `docs/03-data-model.md`) but nothing writes to it.

 ## Deliveries
 ```
 GET  /orders/{id}/delivery         -> { formats, destinations, record_count, avg_confidence, quality_report, files[], provenance_export_url }
 POST /orders/{id}/delivery/destinations  body:{ destinations[] }    -> updates targets (CSV/Parquet/JSON/API/NocoDB/Metabase/FiveCRM/Sheets/webhook)
 ```
+**Status: target only.** Neither route exists in `main.py`. Note also that a "delivery" concept and a "quality_report" are described here as if built — per this doc corpus's broader honesty pass, the underlying quality/QA-check logic these would report on (`quality-check-service.ts`, `quality-report-service.ts` and friends) does not exist in this repo at all (see CLAUDE.md's pointer to README's "Known issues"). This section is aspirational on two levels: the route, and the quality data it would need to serve.

 ## Sources (the transparency moat)
 ```
-GET  /sources                      -> [{source_id,name,market,access,licence,cadence,confidence}]
-GET  /sources/{market}             -> sources + freshness for a market
+GET  /sources                      -> [{source_id,name,market,access,licence,cadence}]
+GET  /sources/{market}             -> full sources.yaml entries (source_id,name,market,access,licence,cadence,url,entities,fields,base_url,robots_ok,notes) filtered to that market + 'global'
 ```
+**Status: implemented, with two shape corrections.** `GET /sources` does **not** return a `confidence` field — `main.py` explicitly projects only `source_id,name,market,access,licence,cadence` from `sources.yaml` (verified: `{k: s.get(k) for k in (...)}` with no `confidence` key). `GET /sources/{market}` returns the *entire* raw `sources.yaml` entry for each match (richer than `/sources` — includes `base_url`, `robots_ok`, `entities`, `fields`, `notes`), not a "sources + freshness" shape; there is no `freshness` field anywhere in `sources.yaml` or added by this endpoint. Both read from `services/api/sources/sources.yaml` (**8** entries as of this pass — verified by count: `gleif`, `brreg`, `companies_house`, `prh`, `cvr`, `bolagsverket`, `rdw`, `opensanctions`; no `traficom` entry exists in this file, unlike the edge-native `GET /api/sources` route below) — an entirely separate, static list from the per-tenant `Source` registry (`src/types/source.ts`) the edge-native `0pt.query_source`/`0pt.source_rate_policy_manage` capabilities act against; see `docs/03-data-model.md` and `docs/12-edge-capability-api.md`. **A third, separate static list exists too:** `app/api/sources/route.ts` is a hardcoded, `GET`-only Next.js route with its own 9-entry array (the same 8 markets plus `traficom`/FI, each with a `confidence` field sources.yaml does not have) — not part of this FastAPI contract, not wired to sources.yaml in any way, and not itself documented in detail here (out of this doc's FastAPI scope; see `docs/12-edge-capability-api.md`).
+
+## Vehicles & sanctions screening (implemented, previously undocumented)
+```
+GET  /vehicles/{plate}             -> RDW (NL) lookup result, or { vehicle: null } if not found
+GET  /screen?q=                    -> { source: "opensanctions", matches: [{name, score, schema}] }
+```
+These two endpoints exist in `main.py` today but were missing from every prior version of this doc. `GET /vehicles/{plate}` proxies `sources/connectors.py:rdw_vehicle()` (Dutch open vehicle data, technical/fleet fields only, no owner PII, per the connector's own comment). `GET /screen` proxies `sources/connectors.py:opensanctions_screen()` against `api.opensanctions.org` — the edge route `app/api/screen/route.ts` calls this same path via `engineFetch('/screen?q=...')` first and falls back to calling OpenSanctions directly if the engine isn't reachable, which is a working (not broken) reconciliation, unlike `/ai/parse` above.

 ## Subscriptions / feeds
 ```
@@ -84,14 +119,41 @@ POST /subscriptions                body:{ order_id, cadence, webhook_url } -> {
 GET  /subscriptions                -> [subs]
 POST /subscriptions/{id}/pause | /resume
 ```
+**Status: target only.** No route exists in `main.py`. The `subscriptions` table exists in `sql/001_init.sql` but nothing writes to it from the engine.

 ## Webhooks out (to customers)
 - On delivery / feed update: POST to `subscriptions.webhook_url` with `{ order_id, delta_url, summary }`.

+**Status: target only** — depends on Deliveries and Subscriptions above, neither of which exist yet.
+
 ## Health
 ```
-GET  /health                       -> { ok, db, workers, queue }
+GET  /health                       -> { ok, service, db, sources }
 ```
+**Status: implemented**, with a corrected shape: the real response is `{ok: true, service: "0pt-data-engine", db: bool(DATABASE_URL is set), sources: len(_SOURCES)}` — not `{ok, db, workers, queue}` as previously documented. There is no `workers` or `queue` field, and `db` is a presence check on an env var, not a live connectivity probe (see "Implementation status" above).

 ## Existing-code reconciliation
-Map current endpoints (orders, estimates, ai-assistent, catalog, webhooks, health) onto the names above; rename for consistency, keep behavior. Add: `/orders/{id}/events` (SSE), `/payments/*` escrow split, `/connections/db-grant`, `/sources`, `/subscriptions`. Remove any endpoint that drives a bypass/stealth fetch path.
+
+| This doc's target | `main.py` reality | Status |
+|---|---|---|
+| `GET/POST /catalog*` | — | not implemented (edge-only, unverified) |
+| `POST /estimates` | `POST /estimates` | implemented, different request/response fields (see above) |
+| `POST /ai/parse` | — | not implemented; edge layer calls it anyway and silently falls back |
+| `POST /orders`, `GET /orders`, `GET /orders/{id}` | same paths, exist | implemented, no auth/org filtering, in-memory only |
+| `POST /orders/{id}/scope\|accept\|revise` | `PATCH /orders/{oid}`, `POST /orders/{oid}/run` | different shape: generic status PATCH + a synchronous run trigger, no escrow gate |
+| `POST /payments/*`, `POST /webhooks/stripe` | — | not implemented in engine (may exist at the edge — unverified this pass) |
+| `GET /orders/{id}/status` | `GET /orders/{oid}/status` | implemented, smaller/different shape |
+| `GET /orders/{id}/events` (SSE) | — | not implemented |
+| `POST /uploads`, `GET /orders/{id}/files` | — | not implemented |
+| `POST/DELETE /connections/db-grant*` | — | not implemented |
+| `GET/POST /orders/{id}/delivery*` | — | not implemented; underlying quality data doesn't exist either |
+| `GET /sources`, `GET /sources/{market}` | same paths, exist | implemented, different projected fields (no `confidence`/`freshness`) |
+| `POST/GET /subscriptions*` | — | not implemented |
+| `GET /health` | `GET /health` | implemented, different shape (no `workers`/`queue`) |
+| — | `GET /vehicles/{plate}`, `GET /screen` | implemented, previously undocumented |
+
+Remove any endpoint that drives a bypass/stealth fetch path (CLAUDE.md §1) — none of the 12 real endpoints in `main.py` do; the WAF-bypass concern in this repo's history is in `services/scrapers/*` on the Gitea remote, not here (see CLAUDE.md's note on the two diverged remotes — an open question for Simon, not resolved by this pass).
+
+## Related: the edge-native TypeScript capability surface
+
+`app/api/0pt/*`, `app/api/screen/route.ts`, and `app/api/ai/parse/route.ts` are **not** part of the FastAPI contract above — they're Next.js Route Handlers, run on Vercel, and implement several of the newer P0 capabilities registered in CL0UD's capability registry (`0pt.query_source`, `0pt.document_ocr`, `0pt.lakehouse_mapping_manage`, `0pt.lakehouse_write`, `0pt.source_rate_policy_manage`). Full route-by-route documentation, including several confirmed always-fails-over-HTTP bugs, lives in **`docs/12-edge-capability-api.md`**.
@@ -1,27 +1,42 @@
 # 05 · Design system (mono)

-Self-contained spec. Component-level v0 prompts live in `docs/design/0pt-v0-build-brief.md`; the full page/component inventory + visual rules in `docs/design/0pt-design-coverage-and-visuals.md`. This file is the source of truth for tokens + motion; build them once and reuse.
+Self-contained spec. This file is the source of truth for tokens + motion; the
+tokens and CSS below are **already implemented** in `app/globals.css` and
+consumed across `components/` and `app/` — this is not aspirational, it's a
+description of what ships today, kept here so new screens stay on-brand.

-Derived from the **mono / EVASION** template (itself v0-generated). Light, editorial, monochrome, sharp, with a single red accent and animated grain + scroll-reveal motion. **No photography** — imagery is rendered data.
+Derived from the **mono / EVASION** template (itself v0-generated). Light, editorial, monochrome, sharp, with a single red accent and animated grain + scroll-reveal motion. **No photography** — imagery is rendered data. (Verified: no `<img>` or `next/image` usage anywhere in `app/` or `components/` except a single unused leftover component, see "Vestigial component, not on the 'no photography' path" further down.)
+
+> **Doc-index gap:** `CLAUDE.md`'s documentation index lists two files this doc used to point to — `docs/design/0pt-v0-build-brief.md` (per-component v0 prompts) and `docs/design/0pt-design-coverage-and-visuals.md` (full page/component inventory + visual rules). **Neither file exists anywhere in this repo** (confirmed via full-repo search). They are referenced but were never written. This doc no longer treats them as available references — anything they were supposed to cover (per-component prompts, the full visual-mapping table) is not documented anywhere right now. Whoever owns design docs next should either write them or remove the rows from `CLAUDE.md`'s index; not resolved in this pass.

 ## Tokens

+Verified against `app/globals.css` (the file actually imported by `app/layout.tsx`):
+
 ```
 THEME (light, default):
  --background #ffffff   --foreground #0a0a0a   --muted-foreground #737373
  --border #e5e5e5       --card #ffffff         --input #f5f5f5
-THEME (dark sections — footer, one editorial block):
+THEME (dark sections — footer, editorial/manifesto block, technology/engine block):
  --background #0a0a0a   --foreground #fafafa   --muted-foreground #a3a3a3   --border #262626
-ACCENT (single, sparing): red --accent #e40014   (one CTA / one number / one marker per screen)
+ACCENT (single, sparing): red --accent-red #e40014   (one CTA / one number / one marker per screen)
 PROVENANCE squares (ONLY non-mono color besides the red CTA):
  level 0 #737373 (unavailable/licensed) · 1 #143aff (single source) · 2 #fcbb00 (partial) · 3 #00d294 (corroborated)
-RADIUS: 0 everywhere (max 2px on tiny chips). No drop shadows; structure via 1px hairlines.
-TYPE: Inter (everything; headlines weight 500–600, letter-spacing -0.02em, large) · JetBrains Mono (eyebrows, labels, numbers, codes, table headers — UPPERCASE, letter-spacing 0.12em, ~11px, #737373)
+RADIUS: 0 everywhere (`--radius: 0rem` in app/globals.css; shadcn/ui components inherit --radius-sm/md/lg/xl derived from it, so they render square too).
+TYPE: Inter (everything; headlines weight 500–600, letter-spacing -0.02em, large) · JetBrains Mono (eyebrows, labels, numbers, codes, table headers — UPPERCASE, letter-spacing mostly 0.08–0.22em but ranging down to 0.02em on some labels/table headers (e.g. `provenance-badge.tsx`, the source table headers in `app/kallor/page.tsx`), ~10–12px, #737373). Loaded via `next/font/google` in `app/layout.tsx` as CSS vars `--font-inter` / `--font-jetbrains-mono`.
 GRID: 8px base; graph-paper hairlines; generous whitespace; left-aligned headlines.
-SECTION SPINE: real ordered indices 00–NN as mono eyebrows.
+SECTION SPINE: real ordered indices 00–06 as mono eyebrows (hero=00, philosophy=01, catalog=02, [03 unused/reserved], collection/coverage=04, testimonials=05, pricing=06). The two dark sections (editorial "Manifesto", technology "The engine") intentionally break the numbered spine — they carry a text eyebrow instead of a number.
 ```

-## globals.css (add verbatim — guarantees identical motion + grain)
+**Correction — a third section also breaks the spine, and it isn't dark:** verified render order in `app/page.tsx` is Hero(00) → Philosophy(01) → FeaturedProducts/Catalog(02) → **Technology (dark, no number)** → **GallerySection (no number)** → Collection(04) → **Editorial (dark, no number)** → Testimonials(05) → Pricing(06) → Footer(dark). `components/sections/gallery-section.tsx` sits exactly where a "03" would fall but carries a text eyebrow (`"— Visualizations"`) like the dark sections, plus its own unrelated local `01`–`05` indices on its five tiles (a per-tile counter, not a continuation of the page's section spine — don't confuse the two). So "03 unused/reserved" is accurate in that no section ever shows the numeral 03, but three sections break the numbered spine, not two — only two of those three happen to be dark-themed.
+
+**Correction vs. previous version of this doc:** the dark theme was previously described as appearing on "footer, one editorial block" (2 places). Verified in `components/sections/`: **three** sections actually use the dark theme — `footer-section.tsx`, `editorial-section.tsx` (the "Manifesto" block), and `technology-section.tsx` (the "#motorn" / "The engine" block, `id="motorn"`). All three set `className="dark ..." ` and a `bg-[#0a0a0a] text-[#fafafa]` pairing.
+
+**Implementation note (not yet reconciled in code):** `editorial-section.tsx` and `technology-section.tsx` use the documented dark border `#262626` consistently. `footer-section.tsx` instead hardcodes `#1f1f1f` for its borders — a different, undocumented shade. All three sections hardcode hex literals (`#0a0a0a`, `#fafafa`, `#737373`, `#a3a3a3`, plus the two different border shades) rather than referencing the `.dark` CSS-variable overrides that already exist in `app/globals.css`'s `--border`/`--foreground`/`--muted-foreground` tokens. This works today because the values happen to match (except the footer border), but it means the dark sections don't actually pick up `.dark`-scoped custom-property overrides — they're hand-pinned. Flagging as a small cleanup opportunity, not fixing here (out of scope for a docs pass).
+
+## globals.css (already live in `app/globals.css` — do not re-add elsewhere)
+
+The block below is the actual motion + grain CSS, condensed for reference. It ships today in `app/globals.css` (with the keyframes/classes spelled out at full length rather than this compact form — functionally identical):

 ```css
@keyframes reveal-up{0%{opacity:0;transform:translateY(60px)}to{opacity:1;transform:translateY(0)}}
@@ -44,44 +59,73 @@ SECTION SPINE: real ordered indices 00–NN as mono eyebrows.
@media(prefers-reduced-motion:reduce){.reveal,.reveal-left,.reveal-right,.reveal-scale,.reveal-fade{opacity:1;animation:none}.animate-float,.grain-overlay::before{animation:none}}
 ```

-## useReveal hook
+The provenance colors and `--accent-red` also live in `app/globals.css` as CSS custom properties (`--accent-red`, `--prov-0..3`), exposed to Tailwind via `@theme inline` as `--color-accent-red`, `--color-prov-0..3`.

-```tsx
-"use client";
-import { useEffect, useRef } from "react";
-export function useReveal<T extends HTMLElement = HTMLElement>() {
-  const ref = useRef<T>(null);
-  useEffect(() => {
-    const el = ref.current; if (!el) return;
-    const io = new IntersectionObserver((es) => es.forEach((e) => {
-      if (e.isIntersecting) {
-        el.querySelectorAll(".reveal,.reveal-left,.reveal-right,.reveal-scale,.reveal-fade")
-          .forEach((n) => n.classList.add("in-view"));
-        io.unobserve(el);
-      }
-    }), { threshold: 0.15, rootMargin: "0px 0px -10% 0px" });
-    io.observe(el); return () => io.disconnect();
-  }, []);
-  return ref;
-}
-```
-Every section wraps in a tag using `useReveal()`; children get `reveal[/-left/-right/-scale/-fade]` + `delay-N`.
+**Known leftover, unused file:** `styles/globals.css` also exists in this repo and is **not** imported anywhere (`app/layout.tsx` imports `./globals.css`, i.e. `app/globals.css`, only). `styles/globals.css` is a stray copy of the original shadcn/v0 scaffold — it uses `oklch()` colors, Geist/Geist Mono fonts, and `--radius: 0.625rem`, none of which match this design system. It is dead code. Don't edit it expecting it to affect the app, and consider deleting it in a future cleanup (not done in this pass — out of scope).
+
+## Reveal / motion system
+
+Three pieces work together; the doc previously only described one of them:
+
+1. **`useReveal()` hook** — `hooks/use-reveal.ts`. Wire a section's ref with it; descendants carrying `.reveal` (+ optional `.reveal-left/-right/-scale/-fade` and `.delay-N`) animate to `.in-view` via `IntersectionObserver` (`threshold: 0.15`, `rootMargin: "0px 0px -10% 0px"`) when the section scrolls into view. **Difference from a naive IntersectionObserver:** if the section's top edge is already inside the viewport on mount (e.g. direct navigation to a page whose hero is already visible), the hook applies `.in-view` immediately via `requestAnimationFrame` instead of waiting for a scroll event — this avoids a flash of invisible content on first paint.
+   ```tsx
+   "use client";
+   import { useEffect, useRef } from "react";
+   export function useReveal<T extends HTMLElement = HTMLElement>() {
+     const ref = useRef<T>(null);
+     useEffect(() => {
+       const el = ref.current;
+       if (!el) return;
+       const applyReveal = () => {
+         el.querySelectorAll(".reveal, .reveal-left, .reveal-right, .reveal-scale, .reveal-fade")
+           .forEach((n) => n.classList.add("in-view"));
+       };
+       const rect = el.getBoundingClientRect();
+       if (rect.top < window.innerHeight * 0.9) {
+         requestAnimationFrame(applyReveal);
+         return;
+       }
+       const io = new IntersectionObserver((entries) => entries.forEach((e) => {
+         if (e.isIntersecting) { applyReveal(); io.unobserve(el); }
+       }), { threshold: 0.15, rootMargin: "0px 0px -10% 0px" });
+       io.observe(el);
+       return () => io.disconnect();
+     }, []);
+     return ref;
+   }
+   ```
+2. **`<RouteReveal />`** — `components/route-reveal.tsx`, mounted once, globally, in `app/layout.tsx` inside the providers. On every client-side route change (via `usePathname()`), it force-applies `.in-view` to any `.reveal*` element whose top edge is already within 95% of the viewport height — covering standalone pages (e.g. `/bestall`, `/katalog/[id]`) that render fully visible on load, where per-section `IntersectionObserver`s might not fire before paint. Runs on an immediate pass, a `requestAnimationFrame` pass, and a 600ms-delayed pass (for async-loaded content). **This component was not documented in the previous version of this file** — it's load-bearing for anything not covered by `useReveal()`'s own "already visible" check (e.g. content that becomes visible slightly after mount).
+3. **CSS keyframes/classes** in `app/globals.css` (above) define the actual animation.
+
+Every section wraps in a tag using `useReveal()`; children get `reveal[/-left/-right/-scale/-fade]` + `delay-N`. This pattern is used consistently across `components/sections/*.tsx`.

 ## Buttons & labels
- Primary: solid `#0a0a0a` bg, white text, square, mono uppercase 12px / spacing 0.1em, padding 14px 26px; hover → bg `#e40014`.
- Secondary: transparent, 1px `#0a0a0a` border; hover → bg `#0a0a0a`, white text.
- Eyebrow: mono uppercase 11px, spacing 0.14em, `#737373`, with a 2-digit index ("01 — KATALOG").
+
+- Primary: solid `#0a0a0a` (`--foreground`) bg, `--background` text, square, mono uppercase ~12px, padding varies by placement (header CTA and hero CTAs use `px-5..7 py-2.5..4`, i.e. roughly 10–16px vertical / 20–28px horizontal — treat the doc's original "14px 26px" as an approximate baseline, not an exact contract); hover → bg `var(--accent-red)`.
+- Secondary: transparent, 1px `border-foreground`; hover → bg `--foreground`, `--background` text.
+- Eyebrow: mono uppercase 11px, spacing ~0.14–0.18em, `--muted-foreground`, with a 2-digit index where the section spine applies (e.g. `"01 — Philosophy"`).
 - Headlines: sentence case, never uppercase.
+- **Implementation note:** there is no shared `Button`/`MonoButton` component implementing this pattern — `components/ui/button.tsx` is the generic, unmodified shadcn/ui button (rounded via `--radius-*` tokens, which happen to resolve to 0 here, but otherwise a stock `cva` variant set: default/destructive/outline/secondary/ghost/link). The mono square CTA look described above is hand-rolled per call site as inline Tailwind classes on raw `<Link>`/`<button>` elements (see `components/header.tsx`, `components/sections/hero-section.tsx`). It's applied consistently in practice, but it's a repeated pattern, not a reusable component — worth extracting if more CTAs are added.

 ## Visual system — no photos (`DataArtifact`)
-Build one generative primitive; every "image" surface uses it, animating with the effect it replaces:
- `table` (rows cascade in, provenance square per fact cell) — hero/cards.
- `map` (country-code cells, fill bars animate width on view) — coverage.
- `schema` (ER mini-diagram, key boxes red border) — schema previews.
- `chart` (black bars/lines, exactly ONE red series, grow on view) — dashboards.
- `grid` (hairline graph-paper + faint oversized numeral + one floating red square) — pure texture.

-Mapping of template image elements → replacement + effect kept is in the coverage doc. Rules: code-only (CSS/SVG/canvas), color discipline inside visuals (mono + provenance squares + one red series), grain over any "image" surface, `prefers-reduced-motion` settles to static. Optional: add **Lenis** smooth scroll on top — preserves all effects.
+`components/data-artifact.tsx` is the one generative primitive; every "image" surface uses it, animating with the effect it replaces. Confirmed implemented variants (`variant` prop): `"table" | "map" | "schema" | "chart" | "grid"`.
+- `table` (rows cascade in via `.reveal-left`, provenance square per fact cell) — used in `components/sections/gallery-section.tsx` (showcase tile) and `app/katalog/[id]/page.tsx` (`SampleTab`, plus `OverviewTab` for datasets whose `artifact` field is `"table"`). Real fields used: `dim_company`-style rows with company name, source label, provenance level. **Correction:** the previous version of this doc said this variant is used on "hero/cards" — verified false. `components/sections/hero-section.tsx` does not import or render `DataArtifact` at all; it has its own hand-rolled `ROWS`/`PROV` mini-table that visually mimics the same pattern independently (same provenance-square styling, separately maintained). `components/sections/featured-products-section.tsx` (the dataset "cards" grid) doesn't use `DataArtifact` either — it renders `ProvenanceBadge` per list row instead. Flagging the hero duplication as the same kind of repeated-pattern-not-a-shared-component issue already noted below for buttons.
+- `map` (country-code cells in a grid, coverage-% fill bar animates width on view) — coverage. Sample cells: SE/NO/DK/FI (populated) and IS/NL/DE/FR (0%, i.e. not yet sourced).
+- `schema` (mini ER diagram over a graph-paper background; key entities get a red top border) — schema previews. Sample entities: `dim_company`, `fact_financials`, `bridge_provenance`.
+- `chart` (black bars, exactly ONE red bar — the last one — grow on view) — dashboards, labeled "coverage" with a large faint "06" numeral watermark.
+- `grid` (hairline graph-paper + faint oversized "0pt" wordmark + one floating red square using `.animate-float`) — pure texture.
+
+Rules, verified in the component: code-only (Tailwind + inline styles + CSS background-image, no images/canvas/SVG assets), color discipline inside visuals (mono + provenance CSS vars `--prov-0..3` + one red `--accent-red`), `grain-overlay` class applied to the outer wrapper, `prefers-reduced-motion` settles to static (handled globally in `app/globals.css`, not per-component).
+
+**Gap:** the previous version of this doc pointed to "the coverage doc" for the full mapping of template image elements → replacement + effect kept. That doc (`docs/design/0pt-design-coverage-and-visuals.md`) does not exist (see callout at top of this file), so that mapping is not written down anywhere beyond the five variants and their usage sites listed above.
+
+**Optional, not implemented:** Lenis smooth scroll is mentioned as an optional layer on top of this motion system. Verified: `lenis` is not a dependency in `package.json` and is not referenced anywhere in the codebase. If added later, it should not require changing any of the reveal/grain classes above.
+
+**Vestigial component, not on the "no photography" path:** `components/fade-image.tsx` (`FadeImage`, wrapping `next/image` with an intersection-triggered fade/scale-in) exists in the repo but is not imported or used anywhere (verified via repo-wide search). It predates the "no photography" rule or was left over from the source template. Harmless dead code; flagging in case someone reaches for it assuming it's wired in.

 ## The signature (carry everywhere)
+
 Provenance + confidence is the identity: the provenance square on every fact, one red, mono numerals as texture, section spine, identical motion. A screen that lacks these is off-brand.
+
+Confirmed carried through beyond the marketing pages: `components/provenance-badge.tsx` (`ProvenanceBadge`, `CellProvenance`, `PROVENANCE_LEGEND`) implements the provenance square + label pattern for reuse in data-bearing UI (portal, admin), and `components/order-stepper.tsx` / `components/portal-shell.tsx` / `components/states.tsx` (loading/empty/error states) all follow the same mono-hairline-square-radius-0 chrome — the design system is not marketing-page-only, it extends into `/portal` and `/admin`.
@@ -1,6 +1,25 @@
 # 06 · Data engine

-The engine turns sources into delivered, provenance-tagged data. It is the legal motor — the whole product positioning depends on it. Build on existing `src/workers/` (`adaptive_router`, `browser_worker`, `ocr_worker`, `db`) but enforce the sourcing boundary below.
+The engine turns sources into delivered, provenance-tagged data. It is the legal motor — the whole product positioning depends on it. The real code lives in `services/api/` (FastAPI orchestrator + workers), **not** at the `src/workers/` path this doc used to point to — the "Pipeline stages" section below states plainly, stage by stage, what's built vs. still spec.
+
+> ### Known issue — two diverged git remotes for this repo (unresolved, Simon's call)
+> This doc describes the compliant-only sourcing chain as *the law*. That law was briefly violated on one
+> of this repo's two remotes, so anyone reading this doc needs to know both exist:
+> - `github.com/sax3l/0pt` (this session's `origin`) — the remote this documentation pass was verified against.
+> - `git.siax.io/sax3l/0pt` (Gitea) — a **separate, diverged** remote that shares origin history with GitHub for
+>   at least part of the codebase (`services/api/workers/adaptive_router.py` is byte-for-byte identical between
+>   GitHub's current `main` and Gitea's post-fix PR branch, so they were once the same commit lineage).
+>
+> Gitea's `main` independently accumulated three commits on 2026-07-13 that added a real WAF-bypass /
+> proxy-rotation / fake-identity scraper stack (`services/scrapers/*`) — exactly the category of code
+> §"Prohibited" below and CLAUDE.md §1 forbid. Those commits never touched GitHub's `main`. The stack was
+> since removed on Gitea via PR #1, but:
+> - **Which remote is authoritative / deployed to `0pt.app` is unknown** — not resolved this session.
+> - **Whether the two remotes are supposed to be kept in sync is unknown** — not resolved this session.
+>
+> This pass does not resolve either question. Simon: decide which remote is canonical, confirm the other has
+> no lingering bypass code, and either merge or retire the loser before treating "the 0pt repo" as singular
+> in any future doc pass.

 ## Sourcing chain (strict priority — this is the law)

@@ -11,10 +30,25 @@ For each field × market, acquire in this order; stop at the first that works:
 3. **Licensed partner data** — contractually obtained.
 4. **Otherwise → "not available / licensed only"** — delivered honestly as level 0. **Never guessed.**

+**Current implementation covers tier 1 only.** All five working connectors in `services/api/sources/connectors.py`
+(`gleif_by_lei`, `brreg_by_orgnr`, `companies_house_by_number`, `prh_by_businessid`, `cvr_by_number`) call
+official JSON APIs over `httpx`, nothing else. There is no HTML-scraping/parsing library anywhere in
+`services/api` (no `bs4`/`lxml`/`selectolax`, no `playwright`, no `scrapy`/`crawlee` — checked against
+`requirements.txt` and the source tree), so tier 2 (authorized public web) has no code path yet. Tier 3
+(licensed partner) also has no connector — `sources.yaml`'s `bolagsverket` entry is `access: licensed` with
+no matching function in `connectors.py`; it correctly falls through to level 0 today. Both tiers remain
+target design, not built.
+
 ### Prohibited (do not build, keep, or extend)
 - WAF/bot-detection bypass — **including FlareSolverr**, "stealth"/patched browsers, undetected-* used to defeat detection.
 - Proxy/fingerprint rotation to evade bans; scraping behind login walls; automated fake-account creation (Apollo etc.).
- **Reconciliation:** if `browser_worker.py` has an `HTTP → FlareSolverr → Playwright` chain, **drop the FlareSolverr stage** and keep only: polite HTTP fetch (identifies itself, obeys robots + rate limits) → optional Playwright for genuinely public JS-rendered pages (same politeness). The `adaptive_router` then chooses among **compliant** methods only (API > bulk > authorized fetch), not bypass tiers.
+- **Reconciliation note (stale — kept for history):** this section used to say "if `browser_worker.py` has an
+  `HTTP → FlareSolverr → Playwright` chain, drop the FlareSolverr stage." **`browser_worker.py` does not exist
+  anywhere in this repository** (verified this pass — no file of that name on GitHub's `main`). There is
+  nothing to reconcile in the current Python engine. The bypass code that *did* exist, briefly, lived in
+  `services/scrapers/*` on the Gitea remote only (see the Known Issue callout above) and has since been
+  removed there via PR #1. `adaptive_router.py` (below) has never contained a bypass tier on either remote —
+  it chooses among **compliant** methods only (API > bulk > authorized fetch > licensed), by design.

 ## Pipeline stages (per job)

@@ -22,19 +56,93 @@ For each field × market, acquire in this order; stop at the first that works:
 sourcing → extraction/OCR → structuring → enrichment/fusion → QA
 ```

-1. **Sourcing** — `adaptive_router` picks the compliant method per source; "source-racing" = query several *authorized* sources and take the fastest/freshest. Writes raw payloads + which source answered.
-2. **Extraction / OCR** — API JSON parsed directly; documents (PDF/HTML/images) via **Unstructured** + OCR cascade (PaddleOCR → Tesseract → LLM fallback) in `ocr_worker`. Output: candidate fields.
-3. **Structuring** — NER + entity resolution (spaCy / transformers, sv/no/da/fi/de/fr), normalize to schema, link entities across markets via **LEI** (GLEIF golden key). Dedup with **RapidFuzz**.
-4. **Enrichment / fusion** — combine fields from multiple sources; compute **multi-source agreement** → confidence + level; append optional enrichment (NACE/SNI, sanctions/PEP flag from official lists, website/tech).
-5. **QA** — quality checks (**Great Expectations** or equivalent, run inside the worker): validity (format/range), completeness, freshness, uniqueness (post-dedup), corroboration. Drop rows below the order's `confidence_target` (deliver fewer, never fabricate). Emit the quality report stored on `deliveries`.
+The stage names below are the target architecture. `services/api/workers/pipeline.py::run_job` is the one
+function that actually runs today, and it implements a much smaller slice of this than the stage list
+implies — see the "built vs. not built" status called out under each stage below.

-Each stage updates `jobs` (`stage`, `pct`, `metrics` incl. per-market progress, running counts, climbing confidence) so the production tracker / SSE can render it live.
+1. **Sourcing** — `adaptive_router.plan_for_market(market)` returns a hardcoded, ordered list of compliant
+   `source_id`s per market (see table below); `pipeline.py` tries each in order for a given key and **stops at
+   the first one that returns a result** (`break` after first hit). This is sequential fallback, not
+   concurrent racing — the phrase "source-racing = query several authorized sources and take the
+   fastest/freshest" describes a target behavior that isn't implemented; today only one source is ever queried
+   per key unless the first fails. Writes raw payload fields directly into the record dict (no separate
+   raw-payload store).
+2. **Extraction / OCR — not built.** There is no `ocr_worker`, no `unstructured`, no `paddleocr`/`pytesseract`
+   anywhere in this repo (checked `services/api/requirements.txt` and the full source tree — none present).
+   "Extraction" today is just each connector in `connectors.py` parsing the JSON response of its own API call
+   into a `CompanyResult`. Document/PDF/image ingestion and the OCR cascade described here are spec only.
+3. **Structuring — partially built.** `services/api/workers/resolve.py::resolve()` does real, deterministic
+   entity resolution: block by `(market, name[:1].upper())`, then `rapidfuzz.fuzz.token_sort_ratio(...) >= 92`
+   to merge duplicates, bumping `confidence` by +0.1 per corroborating match (capped 0.99) and incrementing
+   `agreed_sources`. That part is real and unit-testable. What's **not** built: no spaCy/transformers, no NER,
+   no multilingual normalization (`sv/no/da/fi/de/fr` from the original text), and no explicit LEI-based
+   cross-market entity linking — matching is name-string-similarity only, within the same market. `spacy` and
+   `transformers` are not in `requirements.txt`.
+4. **Enrichment / fusion — partially built, not fully wired into the job.** The confidence/agreement bump
+   described above happens inside `resolve()`. Separately, `opensanctions_screen()` (sanctions/PEP) and
+   `rdw_vehicle()` (NL vehicle data) are real, working connectors in `connectors.py` — but `pipeline.py` never
+   imports or calls either one. They're only reachable as their own standalone endpoints
+   (`GET /screen`, `GET /vehicles/{plate}` in `orchestrator/main.py`), not as an automatic enrichment step on
+   an order's records. NACE/SNI classification and "website/tech" enrichment have no code anywhere.
+5. **QA — not built beyond a single threshold filter.** The entire QA stage in `pipeline.py` is:
+   `delivered = [r for r in deduped if r["confidence"] >= threshold]`. That's real and does drop
+   below-threshold rows (deliver fewer, never fabricate — that principle holds). But there is no
+   Great Expectations (not in `requirements.txt`, not imported anywhere), no separate validity/format,
+   completeness, freshness, or post-dedup-uniqueness checks beyond the confidence number already computed in
+   structuring, and no quality-report object emitted or stored anywhere — `deliveries` (the SQL table defined
+   in `sql/001_init.sql`) is never written to by this service. This mirrors a confirmed, broader finding this
+   session: 0pt's data-quality/QA layer was at one point documented elsewhere (TypeScript side,
+   `src/services/quality-check-service.ts` etc.) as if built and tested, but those files **do not exist** in
+   this repo's history at all (zero commits, any branch — see `docs/07-dependencies.md` note). `docs/ICEBERG_WRITE_BOUNDARY.md`,
+   `docs/11-lakehouse-write-plan.md`, and `docs/P0_QUERY_SOURCE_FLOW.md` have all since been corrected — each
+   now carries its own explicit "fabricated, not built" callout rather than asserting those files as real —
+   and `docs/P0_DATASET_QUALITY_FLOW.md` documents this gap as target-spec-only. The Python engine
+   independently confirms the same gap: **no real quality-check enforcement exists in this codebase today**,
+   in either language.
+
+**"Each stage updates `jobs` ... so the production tracker / SSE can render it live" is not what happens.**
+`run_job` runs synchronously start-to-finish and returns one final dict (`stage: "qa", pct: 100, state: "done",
+metrics, records`). `orchestrator/main.py`'s `POST /orders/{oid}/run` awaits the whole thing and stores that one
+result in an in-memory `_JOBS` dict; `GET /orders/{oid}/status` just returns whatever's there, or a static
+`{"stage": "queued", "pct": 0, "state": "queued"}` placeholder before it's run. There is no per-stage
+incremental progress, no `pct` that climbs, and **no SSE endpoint exists anywhere in `orchestrator/main.py`**
+(grepped — none). Live progress rendering is target design, not current behavior.
+
+### `adaptive_router` — actual market coverage (verified against `services/api/workers/adaptive_router.py`)
+
+`MARKET_SOURCES` currently has real entries for exactly five markets, each a short compliant list — not the
+"elaborate multi-source lists" an earlier version of this router may have implied:
+
+| Market | Ordered plan | Note |
+|---|---|---|
+| NO | `brreg`, `gleif` | |
+| GB | `companies_house`, `gleif` | |
+| FI | `prh`, `gleif` | |
+| DK | `cvr`, `gleif` | |
+| SE | `gleif` only | Bolagsverket bulk is licensed (see above); SE company core relies on GLEIF + a not-yet-built licensed/partner route |
+| anything else | `["gleif"]` | fallback in `plan_for_market()` |
+
+`ACCESS_RANK` (`api=0, bulk=1, authorized_web=2, licensed=3`) is defined in the same file but is **not
+actually used** by `plan_for_market()` to sort anything — the lists above are hand-ordered constants already
+in the desired priority, and the rank dict is currently dead code (documentation-as-code, not logic).

 ## Confidence & provenance scoring

- Per field, write a `bridge_provenance` row: `source_id`, `freshness`, `confidence` (0–1), `level` (0–3), `agreed_sources`.
+- Per field, `connectors.py`'s `Provenance` dataclass carries: `field_name`, `source_id`, `confidence` (0–1),
+  `level` (0–3), `freshness`. **`agreed_sources` is not a field on `Provenance`** — it's tracked separately, at
+  the merged-record level, by `resolve()` (`match["agreed_sources"] = ... + 1`). If a doc or downstream
+  consumer expects `agreed_sources` inside each `bridge_provenance` row, that's a mismatch to reconcile against
+  the actual dataclass shape, not a fact to assume.
 - Level: 0 = unavailable/licensed; 1 = single source; 2 = partial corroboration; 3 = ≥2 independent sources agree.
- `est_confidence` on the order = aggregate target; delivered `avg_confidence` = actual.
+- `est_confidence` on the order = aggregate target (computed in `orchestrator/main.py::compute_estimate`);
+  delivered `avg_confidence` = actual, computed in `pipeline.py` as the mean confidence of delivered rows.
+- **None of this is persisted to Postgres by the current service.** `sql/001_init.sql` defines the
+  `bridge_provenance` table (plus `dim_company`, `dim_source`, `fact_financials`, `deliveries`, etc.), and
+  `asyncpg` is a listed dependency — but nothing in `services/api` actually calls `asyncpg` or issues a query.
+  `DATABASE_URL` is read exactly once, in `orchestrator/main.py`'s `/health` handler, purely to report a
+  boolean (`"db": bool(os.getenv("DATABASE_URL"))`). `orchestrator/main.py` stores orders and jobs in
+  in-memory dicts (`_ORDERS`, `_JOBS`) that reset on every restart. The schema exists; the wiring from
+  pipeline output → Postgres rows does not yet.

 ### Network-layer provenance: `1p` (not yet in use)

@@ -69,7 +177,10 @@ provenance 0pt writes. Adopting it is a later, separate step.

 ## `sources.yaml` (machine-readable registry)

-Single registry that drives the router, the `/sources` API, and the public sourcing-map page. Schema per entry:
+Single registry that drives the router, the `/sources` API, and the (still-to-be-built) public sourcing-map
+page. `services/api/sources/sources.yaml` currently has **8 entries**: `gleif`, `brreg`, `companies_house`,
+`prh`, `cvr`, `bolagsverket`, `rdw`, `opensanctions`. Schema per entry (as actually used, confirmed against the
+file — no `entities`/`fields` mismatch found):

 ```yaml
 - source_id: gleif
@@ -79,23 +190,55 @@ Single registry that drives the router, the `/sources` API, and the public sourc
  cadence: daily
  licence: "open (CC0) — VERIFY current terms"
  entities: [company]
-  fields: [lei, legal_name, address]
+  fields: [lei, legal_name, address, status]
  base_url: https://api.gleif.org
  robots_ok: true        # for authorized_web only; must be honored
-  rate_limit: "per provider terms"
  notes: "cross-border key"
 ```

-### Starter set (VERIFY current access/licence per source before relying — terms change)
- **GLEIF / LEI** — typically open; cross-border key. *(verify)*
- **Brønnøysund (Brreg, NO)** — typically open API. *(verify)*
- **Companies House (UK)** — free API (key required). *(verify)*
- **CVR / Virk (DK)** — API access with terms. *(verify)*
- **PRH (FI)** — varies. *(verify)*
- **Bolagsverket (SE)** — more restricted for bulk; plan licensed/partner route. *(verify)*
- Vehicle: **RDW (NL)** open-ish, **Traficom (FI)**, **Transportstyrelsen (SE)**, **DVLA (UK)** — *(verify each; vehicle/PII rules differ)*
+`orchestrator/main.py` loads this file once at import time (`yaml.safe_load(...)`) and serves it through
+`GET /sources` (id/name/market/access/licence/cadence only) and `GET /sources/{market}`. It is genuinely the
+live registry behind those two endpoints — that part of the doc's original claim holds.

-> Do not hardcode access terms as fact. When building each connector, confirm the current API/licence/robots status and record it in `sources.yaml`. If unclear or disallowed for bulk, route to licensed/partner or mark fields level 0.
+### Starter set (VERIFY current access/licence per source before relying — terms change)
+- **GLEIF / LEI** — typically open; cross-border key. Connector: `gleif_by_lei` — real, working.
+- **Brønnøysund (Brreg, NO)** — typically open API. Connector: `brreg_by_orgnr` — real, working.
+- **Companies House (UK)** — free API (key required, `COMPANIES_HOUSE_API_KEY`). Connector:
+  `companies_house_by_number` — real; degrades honestly to level-0 unavailable if the key is unset (does not
+  fabricate).
+- **PRH (FI)** — Connector: `prh_by_businessid` — real, working.
+- **CVR / Virk (DK)** — connector actually calls `cvrapi.dk` (a third-party aggregator), **not** Virk's own API
+  directly, despite the registry entry's `base_url: https://datacvr.virk.dk`. `sources.yaml`'s `base_url` for
+  `cvr` does not match what `connectors.py::cvr_by_number` actually calls — flag for reconciliation (either
+  update `base_url` to `cvrapi.dk` or switch the connector to call Virk directly; not resolved this pass).
+- **Bolagsverket (SE)** — restricted for bulk; `sources.yaml` marks it `access: licensed`; **no connector
+  exists** for it in `connectors.py`. Consistent with the doc's own "plan licensed/partner route" framing —
+  not a false claim, just confirming it's still unbuilt.
+- **RDW (NL)** vehicle data — open, Socrata-backed. Connector: `rdw_vehicle` — real, working, but **not called
+  by the job pipeline** (only reachable via `GET /vehicles/{plate}`).
+- **OpenSanctions** — global sanctions/PEP screening. Connector: `opensanctions_screen` — real, working, same
+  caveat: reachable only via `GET /screen`, not part of `run_job`.
+- Vehicle beyond RDW (**Traficom FI**, **Transportstyrelsen SE**, **DVLA UK**) — no connectors exist yet;
+  *(verify each before building; vehicle/PII rules differ)*.
+
+> Do not hardcode access terms as fact. When building each connector, confirm the current API/licence/robots
+> status and record it in `sources.yaml`. If unclear or disallowed for bulk, route to licensed/partner or mark
+> fields level 0.
+
+## Structured financials (XBRL) — real but unwired
+
+`services/api/sources/financials.py::companies_house_filings()` is a real, working function: given a
+Companies House number and `COMPANIES_HOUSE_API_KEY`, it fetches the accounts filing history and returns up to
+10 filings. It is **not imported or called anywhere else in the codebase** (grepped `services/api` — only
+`financials.py` itself references the function name). The file's closing comment describes a further XBRL
+extraction step ("with `arelle` installed, download each accounts filing's iXBRL document and pull tagged
+facts...") that has no code at all — `arelle` is not in `requirements.txt`. Treat the whole file as a real but
+disconnected building block, not a wired pipeline stage.

 ## Libraries used here
-Crawlee or Scrapy (orchestration of **authorized** fetches) · Playwright (public JS pages, politely) · Unstructured (document parsing) · PaddleOCR/Tesseract (OCR) · spaCy / HF transformers (NER, multilingual) · Polars (fast tabular) · RapidFuzz (dedup/matching) · Great Expectations (quality) · dbt (optional transform layer). Versions/install: `docs/07-dependencies.md`.
+
+Target list only — see `docs/07-dependencies.md` for what's actually installed today vs. still to be added,
+with an explicit install-status callout per package. As of this pass, the *only* Python packages installed for
+this engine are `fastapi`, `uvicorn`, `pydantic`, `httpx`, `asyncpg` (unused), `python-dotenv`, `pyyaml`,
+`rapidfuzz`, `tenacity` — i.e. the API-only tier 1 sourcing + structuring-by-fuzzy-match slice described above,
+nothing from the extraction/OCR/NER/quality layers this section used to list as if already in place.
@@ -2,62 +2,76 @@

 Curated. Each entry: what it is, where it slots in, how to install. **Do not import on reputation/star-count** — several items in earlier brainstorming were unverified or hallucinated (see Exclusions). Verify each repo exists and is maintained before adopting.

+> **This is a plan, not a status report.** Every table below lists what *should* be imported for the target
+> architecture in `docs/06-data-engine.md`. A **Status** column has been added to each table (verified this
+> pass against `services/api/requirements.txt` and root `package.json` — the actual, current dependency
+> manifests, read in full). Read the status column before assuming a package is already wired in; most of the
+> data-engine tier (OCR, NER, quality checks, orchestration) is still **not installed**.
+
 ## Frontend (Next.js on Vercel)
-| Package | Purpose | Install |
-|---|---|---|
-| next, react, typescript | App Router base | `npx create-next-app@latest --ts` |
-| tailwindcss | styling (mono tokens) | per Next setup |
-| shadcn/ui | base components | `npx shadcn@latest init` |
-| @tanstack/react-table **or** ag-grid-react | data tables / catalog grid | `npm i @tanstack/react-table` |
-| @uppy/core @uppy/react @uppy/dashboard @uppy/aws-s3 | file upload → R2 (presigned) | `npm i @uppy/core @uppy/react @uppy/dashboard @uppy/aws-s3` |
-| next-auth (Auth.js) + @auth/pg-adapter | single auth, Postgres-backed | `npm i next-auth @auth/pg-adapter` |
-| stripe / @stripe/stripe-js | checkout + portal | `npm i stripe @stripe/stripe-js` |
-| resend / react-email | transactional email | `npm i resend @react-email/components` |
-| lenis *(optional)* | smooth scroll (keeps all effects) | `npm i lenis` |
-| recharts *(only if needed)* | charts inside DataArtifact/dashboards | `npm i recharts` |
+| Package | Purpose | Install | Status |
+|---|---|---|---|
+| next, react, typescript | App Router base | `npx create-next-app@latest --ts` | **Installed** — `next@16.0.10`, `react@19.2.0`, `typescript@^5` in `package.json` |
+| tailwindcss | styling (mono tokens) | per Next setup | **Installed** — `tailwindcss@^4.1.9` |
+| shadcn/ui | base components | `npx shadcn@latest init` | **Installed via copy-in, not as a runtime dep** — no `shadcn` package in `package.json` (expected: the shadcn CLI copies component source into `components/ui/`); the underlying `@radix-ui/react-*` primitives it generates against are installed individually and present |
+| @tanstack/react-table **or** ag-grid-react | data tables / catalog grid | `npm i @tanstack/react-table` | **Not installed** — neither package present |
+| @uppy/core @uppy/react @uppy/dashboard @uppy/aws-s3 | file upload → R2 (presigned) | `npm i @uppy/core @uppy/react @uppy/dashboard @uppy/aws-s3` | **Not installed** |
+| next-auth (Auth.js) + @auth/pg-adapter | single auth, Postgres-backed | `npm i next-auth @auth/pg-adapter` | **Not installed.** Matches a broader, confirmed gap: there is no auth/session system anywhere in this repo yet (`app/api/orders/route.ts`'s own `GET` handler has the literal comment "org scoping added with auth" — i.e. not yet). Several `app/api/0pt/*` routes currently read `tenant_id`/`project_id` straight from the request body as a result — a real, open security gap, not a deliberate design; see `docs/09-build-plan.md` Phase 3 for the planned fix (not built anywhere yet, Simon's call on design). |
+| stripe / @stripe/stripe-js | checkout + portal | `npm i stripe @stripe/stripe-js` | **Partially installed** — `stripe@^22.2.3` (server SDK) is present; `@stripe/stripe-js` (client SDK) is not |
+| resend / react-email | transactional email | `npm i resend @react-email/components` | **Not installed** |
+| lenis *(optional)* | smooth scroll (keeps all effects) | `npm i lenis` | **Not installed** |
+| recharts *(only if needed)* | charts inside DataArtifact/dashboards | `npm i recharts` | **Installed** — `recharts@2.15.4` |

 > Catalog/search in v1 = Postgres full-text. Add Meilisearch later only past a few thousand rows.

 ## Backend / workers (Python, FastAPI — existing)
-| Package | Purpose | Install |
-|---|---|---|
-| fastapi, uvicorn, pydantic | API (existing) | `pip install fastapi uvicorn pydantic` |
-| sqlalchemy / asyncpg | Postgres access (align `db.py`) | `pip install sqlalchemy asyncpg` |
-| alembic | migrations | `pip install alembic` |
-| celery + redis **or** existing adaptive_router/queue | job queue/concurrency | `pip install celery redis` |
-| httpx | polite HTTP fetch (identifies itself, obeys rate limits) | `pip install httpx` |
-| scrapy **or** crawlee | orchestrate **authorized** fetches | `pip install scrapy` |
-| playwright | public JS-rendered pages, politely | `pip install playwright && playwright install chromium` |
-| unstructured | parse PDF/HTML/DOCX/images → elements | `pip install "unstructured[all-docs]"` |
-| paddleocr / pytesseract | OCR cascade | `pip install paddleocr pytesseract` (+ tesseract bin) |
-| spacy (+ models) / transformers | NER, entity resolution (multilingual) | `pip install spacy transformers` |
-| polars | fast tabular processing | `pip install polars` |
-| rapidfuzz | dedup / fuzzy matching | `pip install rapidfuzz` |
-| great-expectations | data quality checks in pipeline | `pip install great-expectations` |
-| dbt-postgres *(optional)* | transform layer | `pip install dbt-postgres` |
-| pgvector (Postgres ext) | embeddings/matching | `CREATE EXTENSION vector;` |
-| boto3 *(or aioboto3)* | R2 (S3-compatible) | `pip install boto3` |
-| stripe (python) | webhook handling | `pip install stripe` |
+
+`services/api/requirements.txt` currently pins exactly 9 packages. Everything else in this table is still to
+be added — this is the single biggest gap between this doc's plan and the running code (see
+`docs/06-data-engine.md`'s "Pipeline stages" section for what that means stage-by-stage: only official-API
+sourcing and rapidfuzz-based dedup are real today; extraction/OCR, NER, and quality-checking have no code at all).
+
+| Package | Purpose | Install | Status |
+|---|---|---|---|
+| fastapi, uvicorn, pydantic | API (existing) | `pip install fastapi uvicorn pydantic` | **Installed** — `fastapi==0.115.6`, `uvicorn[standard]==0.34.0`, `pydantic==2.10.4` |
+| httpx | polite HTTP fetch (identifies itself, obeys rate limits) | `pip install httpx` | **Installed and actively used** — `httpx==0.28.1`, every connector in `sources/connectors.py` and `sources/financials.py` goes through it |
+| pyyaml | parse `sources.yaml` | `pip install pyyaml` | **Installed and used** — `pyyaml==6.0.2`, loaded once in `orchestrator/main.py` |
+| rapidfuzz | dedup / fuzzy matching | `pip install rapidfuzz` | **Installed and used** — `rapidfuzz==3.11.0`, the only matching engine in `workers/resolve.py` |
+| python-dotenv, tenacity | env loading, retry helper | — | **Installed**, `python-dotenv==1.0.1` / `tenacity==9.0.0` — present in `requirements.txt` but not yet visibly imported in the worker/orchestrator/sources files read this pass; not confirmed wired up |
+| sqlalchemy / asyncpg | Postgres access (align `db.py`) | `pip install sqlalchemy asyncpg` | **`asyncpg==0.30.0` is installed but unused.** No file in `services/api` imports it or issues a query — confirmed by grep. `orchestrator/main.py` reads `DATABASE_URL` once, only to report a boolean in `/health`. Orders/jobs live in in-memory dicts that reset on restart. `sqlalchemy` is **not installed** at all. There is also no `db.py` anywhere in this repo — an older doc reference to `src/workers/db.py` is stale; that path does not exist. |
+| alembic | migrations | `pip install alembic` | **Not installed.** Migrations currently ship as plain numbered SQL files in `sql/` (`001_init.sql`, `004_iceberg_write_boundary.sql`), applied ad hoc, not via Alembic. |
+| celery + redis **or** existing adaptive_router/queue | job queue/concurrency | `pip install celery redis` | **Neither Celery nor a Python Redis client is installed.** `workers/queue.py` is a small in-process `asyncio.Queue` wrapper (single-worker dev only, by its own docstring). `infra/docker-compose.yml` does run a `redis` *container*, but nothing in `services/api` currently talks to it. |
+| scrapy **or** crawlee | orchestrate **authorized** fetches | `pip install scrapy` | **Not installed.** No HTML-scraping library of any kind (also no `bs4`/`lxml`) exists in this codebase — confirmed by grep. Tier-2 "authorized public web" sourcing (docs/06) has no code path yet; only tier-1 official-API connectors exist. |
+| playwright | public JS-rendered pages, politely | `pip install playwright && playwright install chromium` | **Not installed.** No `browser_worker.py` file exists anywhere in this repo either — an older doc reference to reconciling a FlareSolverr stage inside it is moot; there's nothing to reconcile in the current Python engine (see `docs/06-data-engine.md`'s Known Issue callout for where a bypass stack *did* briefly exist, on a different git remote). |
+| unstructured | parse PDF/HTML/DOCX/images → elements | `pip install "unstructured[all-docs]"` | **Not installed.** |
+| paddleocr / pytesseract | OCR cascade | `pip install paddleocr pytesseract` (+ tesseract bin) | **Not installed.** No OCR code or `ocr_worker` module exists anywhere in this repo. |
+| spacy (+ models) / transformers | NER, entity resolution (multilingual) | `pip install spacy transformers` | **Not installed.** `workers/resolve.py`'s entity resolution is rapidfuzz string-similarity only — no NER, no multilingual normalization. |
+| polars | fast tabular processing | `pip install polars` | **Not installed.** |
+| great-expectations | data quality checks in pipeline | `pip install great-expectations` | **Not installed, and nothing equivalent exists either.** The entire QA stage in `workers/pipeline.py` is a single confidence-threshold filter (`r["confidence"] >= threshold`) — no validity/completeness/freshness/uniqueness checks, no quality report emitted or stored. This is a real, currently-open gap, not a doc typo: a broader, confirmed finding this session is that 0pt's data-quality/QA layer, once described elsewhere in this doc corpus as already built and tested (`src/services/quality-check-service.ts` etc.), does not exist in code at all — zero commits in this repo's history, any branch, for any of those files. Every doc that used to make that claim (`docs/ICEBERG_WRITE_BOUNDARY.md`, `docs/11-lakehouse-write-plan.md`, `docs/P0_QUERY_SOURCE_FLOW.md`) has since been corrected. The Python engine independently confirms the same absence. |
+| dbt-postgres *(optional)* | transform layer | `pip install dbt-postgres` | **Not installed.** |
+| pgvector (Postgres ext) | embeddings/matching | `CREATE EXTENSION vector;` | The `pgvector/pgvector:pg16` image is used in `infra/docker-compose.yml`, so the extension is available in the container, but no code in `services/api` runs a vector query — not exercised by any of the files read this pass |
+| boto3 *(or aioboto3)* | R2 (S3-compatible) | `pip install boto3` | **Not installed.** No R2/S3 upload code found in `services/api` this pass. |
+| stripe (python) | webhook handling | `pip install stripe` | **Not installed** in `services/api/requirements.txt` (the JS `stripe` package in root `package.json` is separate and unrelated to this table) |

 ## Self-hosted services (docker-compose on the VPS)
-| Service | Purpose | Image |
-|---|---|---|
-| **NocoDB** | Airtable-style views over existing Postgres tables; embedded "Min data" | `nocodb/nocodb` |
-| **Metabase** | customer-facing dashboards; embedded | `metabase/metabase` |
-| **Postgres** *(or Neon managed)* | backbone (+ pgvector) | `pgvector/pgvector:pg16` |
-| **Redis** *(if Celery)* | queue | `redis` |
-| **Meilisearch** *(later)* | catalog search at scale | `getmeili/meilisearch` |
+| Service | Purpose | Image | Status |
+|---|---|---|---|
+| **NocoDB** | Airtable-style views over existing Postgres tables; embedded "Min data" | `nocodb/nocodb` | **Wired in `infra/docker-compose.yml`** (`nocodb/nocodb:latest`, points at the same `postgres` service) — not independently verified running/reachable this pass |
+| **Metabase** | customer-facing dashboards; embedded | `metabase/metabase` | **Wired in `infra/docker-compose.yml`** (`metabase/metabase:latest`, same Postgres backend) — not independently verified running/reachable this pass |
+| **Postgres** *(or Neon managed)* | backbone (+ pgvector) | `pgvector/pgvector:pg16` | **Wired in `infra/docker-compose.yml`** — but see the backend table above: the FastAPI service that should write to it currently does not (in-memory only) |
+| **Redis** *(if Celery)* | queue | `redis` | **Container is wired in `infra/docker-compose.yml`**, but no Python code in `services/api` currently connects to it (no Celery, no `redis` client installed) |
+| **Meilisearch** *(later)* | catalog search at scale | `getmeili/meilisearch` | Not in `infra/docker-compose.yml` yet — consistent with this doc's own "later" framing, not a gap |

 ## External managed (free/cheap tiers)
 - **Vercel** — Next.js hosting.
- **Cloudflare R2** — object storage (presigned URLs).
- **Stripe** — payments (test mode first).
- **Resend** — email.
- **Neon** *(optional)* — managed Postgres.
+- **Cloudflare R2** — object storage (presigned URLs). No R2 client code found in this pass (`boto3` not installed; no `@uppy/aws-s3` in `package.json`) — treat as not yet wired regardless of account status.
+- **Stripe** — payments (test mode first). Server SDK (`stripe` npm package) is installed; whether a live/test key is actually configured was not verified this pass (no secret material read).
+- **Resend** — email. Not installed (see frontend table).
+- **Neon** *(optional)* — managed Postgres. `infra/docker-compose.yml` runs its own Postgres container instead; no evidence either way of a Neon instance actually in use.

 ## EXCLUSIONS — do not import

- **Bypass/stealth/evasion**: FlareSolverr, "CloakBrowser", undetected-chromedriver/undetected-playwright (as bypass), proxy/fingerprint-rotation engines, any "WAF bypass" repo. Prohibited by CLAUDE.md §1 — they destroy the honest-accuracy positioning and create legal exposure.
+- **Bypass/stealth/evasion**: FlareSolverr, "CloakBrowser", undetected-chromedriver/undetected-playwright (as bypass), proxy/fingerprint-rotation engines, any "WAF bypass" repo. Prohibited by CLAUDE.md §1 — they destroy the honest-accuracy positioning and create legal exposure. **This is not hypothetical**: a real WAF-bypass/proxy-rotation/fake-identity scraper stack (`services/scrapers/*`) briefly existed on this repo's Gitea remote (`git.siax.io/sax3l/0pt`, three commits dated 2026-07-13) and has since been removed there via PR #1. It never touched `origin` (`github.com/sax3l/0pt`), which this doc corpus was verified against. See `docs/06-data-engine.md`'s Known Issue callout for the full, unresolved detail — which remote is canonical is Simon's call, not decided this pass.
 - **Fake-account automation** on Apollo/Cognism/etc.
 - **Unverified / likely-hallucinated** from earlier brainstorming: "CloakBrowser/CloakHQ", "Rota proxy engine", "OpenClaw". Do not adopt unless you confirm a real, maintained project — and even then, not if it falls in the bypass category.
 - **Overlapping tools** already decided against (Superset, DataHub/OpenMetadata, Baserow/Teable, Trigger.dev, Delta Sharing in v1) — see `docs/02-architecture.md`.
@@ -1,118 +1,278 @@
 # 08 · Infrastructure

-## Repo structure (monorepo)
+> Verified against actual repo state 2026-07-19 (branch `main`, plus `.env.example` read from
+> `feature/0pt-env-example`). Where this doc previously described a target that doesn't match
+> what's committed, that's called out explicitly rather than silently corrected — see the repo's
+> honesty convention in `docs/ICEBERG_WRITE_BOUNDARY.md`.
+
+## Repo structure (actual, not the original `apps/web` sketch)
+
+The monorepo did **not** converge on the `apps/web/` + `packages/shared/` layout this doc originally
+sketched. What's actually on `main` today:

 ```
 0pt/
 ├─ CLAUDE.md
+├─ README.md · SECURITY.md
 ├─ docs/                      # this documentation set
-├─ apps/
-│  └─ web/                    # Next.js (Vercel): marketing, catalog, portal, admin
-├─ services/
-│  └─ api/                    # FastAPI orchestrator + workers (existing src/* migrates here)
-│     ├─ orchestrator/        # main.py + routers (docs/04-api.md)
-│     ├─ workers/             # adaptive_router, fetch_worker, ocr_worker, pipeline, db
-│     └─ sources/             # sources.yaml + connectors (docs/06)
-├─ packages/
-│  └─ shared/                 # shared TS types (mirror API contract), design tokens
-├─ sql/  (or services/api/alembic/)   # migrations (docs/03)
+├─ app/                       # Next.js App Router (Vercel) — the "edge" plane, AT THE REPO ROOT
+│  ├─ api/                    # route handlers: orders, auth, admin, catalog, connections,
+│  │                          #   vehicles, subscriptions, sources, estimates, health, uploads,
+│  │                          #   payments, 0pt/*, screen, webhooks, ai
+│  ├─ bestall/ katalog/ kallor/ order/ portal/ admin/ tjanster/   # pages
+├─ lib/                       # edge-side helpers: db.ts, engine.ts, auth.ts, stripe.ts,
+│  │                          #   orders-store.ts, subscriptions-store.ts, data.ts, services.ts
+├─ src/                       # SIAX-platform-facing TS layer (NOT under app/ or lib/)
+│  ├─ clients/                # cl0ud-, n0d-, aud0-, st0re-, st0re-lakehouse-client.ts
+│  ├─ services/                # dataset-, source-, source-query-, iceberg-write-,
+│  │                          #   document-capture-, document-extraction-, external-writeback-,
+│  │                          #   source-rate-policy-, dataset-iceberg-mapping-service.ts
+│  ├─ adapters/                # local-blob-store.ts, odoo-bills-adapter.ts, graph-mailbox-adapter, ...
+│  └─ types/
+├─ components/ hooks/ styles/  # design system in code (docs/05) — data-artifact.tsx,
+│  │                          #   provenance-badge.tsx, embed.tsx, use-reveal.ts, globals.css
+├─ packages/schemas/           # JSON Schemas for 0pt.* event/entity contracts (not a pnpm workspace
+│  │                          #   package today — pnpm-workspace.yaml has no `packages:` list)
+├─ services/api/               # FastAPI orchestrator + workers (the "engine" plane, on a VPS)
+│  ├─ orchestrator/main.py
+│  ├─ workers/                 # adaptive_router.py, pipeline.py, resolve.py, queue.py, run.py
+│  ├─ sources/                 # sources.yaml + connectors.py (docs/06)
+│  └─ Dockerfile · requirements.txt
+├─ sql/                        # migrations — see "Schema state" below
 ├─ infra/
-│  ├─ docker-compose.yml      # VPS always-on services
-│  └─ Caddyfile               # reverse proxy + TLS
-└─ .github/workflows/         # CI/CD
+│  ├─ docker-compose.yml       # real, committed (not a sketch — see below)
+│  └─ Caddyfile                # real, committed
+├─ tests/p0/                   # vitest, TS-side (services/clients/adapters)
+└─ (no .github/workflows/ directory exists — see "CI/CD" below)
 ```

+**Known open question (not resolved this pass, Simon's call):** `CLAUDE.md` and `README.md` both
+now note that `github.com/sax3l/0pt` (this checkout's `origin`) and `git.siax.io/sax3l/0pt` (Gitea)
+are two remotes that share part of the same history but have independently diverged — Gitea's `main`
+picked up a WAF-bypass/proxy-rotation scraper stack (since removed via a Gitea PR) that never touched
+GitHub's `main`. Which remote is authoritative/deployed, and whether they should be kept in sync, is
+undecided. This doc describes what's on **this** checkout's `main` only.
+
+### Schema state (sql/)
+
+Only two migration files exist in the repo's history, on any branch: `sql/001_init.sql` (the core
+schema — `dim_company`, `dim_contact`, `fact_financials`, `orders`, etc., per `docs/03-data-model.md`)
+and `sql/004_iceberg_write_boundary.sql` (`opt_dataset_iceberg_mappings` + source-rate-policy tables,
+per `docs/ICEBERG_WRITE_BOUNDARY.md`). **There is no `sql/002_*` or `sql/003_*` anywhere in this
+repo's git history** (`git log --all` for those paths returns zero commits) — despite
+`docs/ICEBERG_WRITE_BOUNDARY.md`, `docs/11-lakehouse-write-plan.md`, and `docs/P0_QUERY_SOURCE_FLOW.md`
+citing `sql/002_p0_dataset_quality.sql` and a `sql/003_*` as if they were already-applied migrations.
+They are not real. See "Security & compliance" below for what this means for QA/quality-check claims.
+
 ## Hosting topology

- **Vercel** — `apps/web` → `0pt.app`. Free Hobby until paying customers.
- **One VPS** (Hetzner ~€5/mo) — `docker-compose`: FastAPI, workers, NocoDB, Metabase, Postgres (or Neon), Redis (if Celery), Caddy. Caddy terminates TLS and proxies `api.0pt.app`, `data.0pt.app` (NocoDB), `dash.0pt.app` (Metabase).
- **Cloudflare R2** — files.
- **Postgres** — on VPS (`pgvector/pgvector:pg16`) or **Neon** managed.
+- **Vercel** — `app/` (this repo's root, not a separate `apps/web`) → `0pt.app`. **Verified this pass**
+  (network check performed): `https://0pt.app` returns HTTP 200, serves a Next.js/Turbopack app titled
+  "0pt — your data" with SIAX branding, and `GET https://0pt.app/api/health` returns
+  `{"ok":true,"service":"0pt-web","db":"not_configured","queue":"not_configured",...}` — an exact shape
+  match for this repo's own `app/api/health/route.ts`. So README's "Live: https://0pt.app" is confirmed
+  accurate, and the live deployment confirms `DATABASE_URL`/`REDIS_URL` are **not** set in production —
+  i.e. the live site is running on the in-memory order/subscription stores described throughout this
+  doc, not against a real Postgres. This does not confirm which git remote/commit is deployed, or that
+  every route behaves as documented — only that the deployment exists and matches this repo's shape.
+- **One VPS** (Hetzner, per `docs/02`) — `infra/docker-compose.yml` (see below) runs FastAPI, worker,
+  NocoDB, Metabase, Postgres, Redis, Caddy. This compose file and its `Caddyfile` are real, committed
+  files — not a sketch — but this pass found no evidence (no CI/CD, no deploy log, no accessible host)
+  that they have ever actually been run against a live VPS. Treat as "written, unexecuted."
+- **Cloudflare R2** — documented target for file storage. `app/api/uploads/route.ts` checks for
+  `R2_ACCESS_KEY_ID`/`R2_BUCKET`/`R2_ENDPOINT` and returns `501 storage_not_configured` when absent;
+  when "present" it still returns a **hardcoded `put_url: null`** — there is no actual presigned-URL
+  generation implemented yet. R2 upload is an env-guarded stub, not a working integration.
+- **Postgres** — `lib/db.ts` resolves `DATABASE_URL || POSTGRES_URL || POSTGRES_PRISMA_URL` (Vercel
+  Postgres integration sets the latter two automatically) and falls back to `null` (in-memory stores)
+  when none is set. This part is real and wired.

-## docker-compose (infra/docker-compose.yml — sketch)
+## docker-compose (`infra/docker-compose.yml` — real file, reproduced here for reference)

 ```yaml
 services:
  postgres:
    image: pgvector/pgvector:pg16
    environment: { POSTGRES_USER: opt, POSTGRES_PASSWORD: ${PG_PASSWORD}, POSTGRES_DB: opt }
-    volumes: ["pgdata:/var/lib/postgresql/data"]
+    volumes: ["pgdata:/var/lib/postgresql/data", "../sql:/docker-entrypoint-initdb.d:ro"]
  redis:
    image: redis:7
  api:
    build: ../services/api
    command: uvicorn orchestrator.main:app --host 0.0.0.0 --port 8000
-    environment: [DATABASE_URL, R2_*, STRIPE_*, RESEND_API_KEY, INTERNAL_TOKEN]
+    environment: { DATABASE_URL: "postgres://opt:${PG_PASSWORD}@postgres:5432/opt", COMPANIES_HOUSE_API_KEY: "${COMPANIES_HOUSE_API_KEY:-}", INTERNAL_TOKEN: "${INTERNAL_TOKEN}" }
    depends_on: [postgres, redis]
  worker:
    build: ../services/api
-    command: python -m workers.run            # or celery -A workers worker
-    environment: [DATABASE_URL, R2_*]
+    command: python -m workers.run
+    environment: { DATABASE_URL: "postgres://opt:${PG_PASSWORD}@postgres:5432/opt", COMPANIES_HOUSE_API_KEY: "${COMPANIES_HOUSE_API_KEY:-}" }
    depends_on: [postgres, redis]
  nocodb:
-    image: nocodb/nocodb
+    image: nocodb/nocodb:latest
    environment: { NC_DB: "pg://postgres:5432?u=opt&p=${PG_PASSWORD}&d=opt", NC_PUBLIC_URL: "https://data.0pt.app" }
    depends_on: [postgres]
  metabase:
-    image: metabase/metabase
-    environment: { MB_DB_TYPE: postgres, MB_DB_HOST: postgres, MB_DB_USER: opt, MB_DB_PASS: ${PG_PASSWORD}, MB_DB_DBNAME: opt }
+    image: metabase/metabase:latest
+    environment: { MB_DB_TYPE: postgres, MB_DB_HOST: postgres, MB_DB_PORT: "5432", MB_DB_USER: opt, MB_DB_PASS: "${PG_PASSWORD}", MB_DB_DBNAME: opt }
    depends_on: [postgres]
  caddy:
    image: caddy:2
-    ports: ["80:80","443:443"]
+    ports: ["80:80", "443:443"]
    volumes: ["./Caddyfile:/etc/caddy/Caddyfile", "caddydata:/data"]
+    depends_on: [api, nocodb, metabase]
 volumes: { pgdata: {}, caddydata: {} }
 ```

-## Environment variables (full inventory)
+Note vs. an earlier draft of this doc: the `api`/`worker` containers here only receive
+`DATABASE_URL`, `COMPANIES_HOUSE_API_KEY`, and `INTERNAL_TOKEN` — **not** `STRIPE_*`, `RESEND_API_KEY`,
+or `R2_*`. That's correct as written: Stripe, R2, and (a documented but unbuilt) Resend integration
+are all called from `app/api/*` route handlers, which run on Vercel, not inside this compose stack.

+**`Caddyfile` (real, committed):**
 ```
-# Postgres
-DATABASE_URL=postgres://opt:***@host:5432/opt
-PG_PASSWORD=***
-# Internal auth (Next ↔ FastAPI)
-INTERNAL_TOKEN=***                 # sent as X-Internal-Token
-# Auth.js
-AUTH_SECRET=***
-AUTH_URL=https://0pt.app
-# Stripe
-STRIPE_SECRET_KEY=sk_***
-STRIPE_WEBHOOK_SECRET=whsec_***
-NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_***
-# Cloudflare R2 (S3-compatible)
-R2_ACCOUNT_ID=***  R2_ACCESS_KEY_ID=***  R2_SECRET_ACCESS_KEY=***  R2_BUCKET=opt-files  R2_ENDPOINT=https://<acct>.r2.cloudflarestorage.com
-# Email
-RESEND_API_KEY=re_***
-# Embeds (signed URLs)
-METABASE_SITE_URL=https://dash.0pt.app  METABASE_SECRET_KEY=***
-NOCODB_BASE_URL=https://data.0pt.app    NOCODB_API_TOKEN=***
-# Encryption for db_grants
-GRANT_ENC_KEY=***                  # 32-byte key, AES-GCM
-# App
-NEXT_PUBLIC_API_URL=https://api.0pt.app
+api.0pt.app { reverse_proxy api:8000 }
+data.0pt.app { reverse_proxy nocodb:8080 }
+dash.0pt.app { reverse_proxy metabase:3000 }
 ```

-Never hardcode. Vercel env for `apps/web`; VPS `.env` (git-ignored) for compose. Provide `.env.example` with empty values.
+## Environment variables

-## Security & compliance (build in, not bolt on)
+**`.env.example` now exists** — added on branch `feature/0pt-env-example`
+(`github.com/sax3l/0pt/pull/3`, **not yet merged to `main`** as of this pass). It was previously
+impossible to commit: `.gitignore`'s blanket `.env*` rule silently matched `.env.example` too, so it
+was never added despite `docs/09-build-plan.md` Phase 0 requiring it since day one. The same PR adds
+`!.env.example` to `.gitignore` to fix that. README's "Env inventory: `.env.example`" link is
+therefore currently a broken/future reference on `main` until that PR merges.

- **Customer DB grants**: customer creates a read-only, table-scoped, time-boxed DB role; we store the connection string **AES-GCM encrypted** (`GRANT_ENC_KEY`), validate it's read-only, and **delete after the job**. IP-allowlist; prefer a replica. Log access in `audit_log`.
- **File delivery**: short-lived **presigned R2 URLs**; never public buckets.
- **Isolation**: API filters by `org_id`; Postgres **RLS** where practical; NocoDB/Metabase exposed only via **signed embed URLs** scoped per customer/order (no separate login surfaced).
- **PII (contacts/UBO)**: lawful basis recorded per delivery; honor deletion; minimize retention.
- **DPA**: ship a Data Processing Agreement; provenance log + audit log are part of the offering.
- **Secrets**: rotate; least privilege; no secrets in client bundles (only `NEXT_PUBLIC_*`).
+The table below is grep-verified against `main` this pass, not transcribed from `.env.example`'s own
+comments — in one case (`ST0RE_URL`, see note) that turned up a discrepancy worth flagging.

-## Embedding NocoDB / Metabase (so it feels like one app)
- Generate a **signed embed URL** server-side (Metabase signed embedding with `METABASE_SECRET_KEY`; NocoDB shared/locked view + token) scoped to the customer's data, and render it in an iframe inside the mono chrome. The customer never sees a NocoDB/Metabase login.
+| Var | Status on `main` | Where |
+|---|---|---|
+| `DATABASE_URL` / `POSTGRES_URL` / `POSTGRES_PRISMA_URL` | **Wired** — priority-ordered fallback | `lib/db.ts` |
+| `ENGINE_URL` | **Wired** — edge defers to FastAPI engine when set, else computes locally | `lib/engine.ts` |
+| `INTERNAL_TOKEN` | **Wired** — sent as `X-Internal-Token` on every `engineFetch()` call | `lib/engine.ts` |
+| `AUTH_SECRET` | **Wired**, but only for a lightweight HMAC session scaffold — **not Auth.js**. `lib/auth.ts`'s own comment: "Production auth = Auth.js + Postgres adapter... wired once the database is provisioned" | `lib/auth.ts`, `app/api/auth/login/route.ts` |
+| `DEV_LOGIN_KEY` | **Wired** — gates the dev-only login route (403 without a match); not a real auth system | `app/api/auth/login/route.ts` |
+| `AUTH_URL` | Documented target — no read found | — |
+| `STRIPE_SECRET_KEY` | **Wired** — real Stripe Checkout session creation (test or live key both work; not test-mode-locked in code) | `app/api/payments/[order_id]/deposit/route.ts` |
+| `STRIPE_WEBHOOK_SECRET` | **Wired** — real signature verification, advances order status | `app/api/webhooks/stripe/route.ts` |
+| `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` | Documented target — no read found | — |
+| `R2_ACCESS_KEY_ID`, `R2_BUCKET`, `R2_ENDPOINT` | **Presence-checked only** — gates a `501` vs stub `200`; no actual R2 client/presign call exists yet | `app/api/uploads/route.ts` |
+| `R2_ACCOUNT_ID`, `R2_SECRET_ACCESS_KEY` | Documented target — no read found (even the stub above doesn't check these) | — |
+| `OPT_LOCAL_BLOB_DIR` | **Wired** — local-disk fallback artifact store, used when no object storage is configured | `src/adapters/local-blob-store.ts` |
+| `RESEND_API_KEY` | Documented target — **no Resend call site anywhere in this repo**; not "unconfigured", genuinely not implemented | — |
+| `METABASE_SITE_URL`, `METABASE_SECRET_KEY`, `NOCODB_BASE_URL`, `NOCODB_API_TOKEN` | Documented target — no read found. `components/embed.tsx` renders an iframe from a `src` prop the *caller* must supply; no server-side signed-URL generator exists to produce that `src` | — |
+| `DOC_INTELLIGENCE_ENDPOINT`, `DOC_INTELLIGENCE_KEY`, `DOC_INTELLIGENCE_API_VERSION` | **Wired** | `src/services/document-extraction-service.ts` |
+| `GRANT_ENC_KEY` | **Presence-checked only** — gates `501` vs a stub `201` that returns `{ grant_id, status: "pending" }`. No AES-GCM encryption, no read-only validation, no actual storage happens yet despite the route's own comment describing that flow | `app/api/connections/db-grant/route.ts` |
+| `NEXT_PUBLIC_APP_URL` | **Wired** — used as a fallback origin for building Stripe redirect URLs | `app/api/payments/[order_id]/deposit/route.ts` |
+| `NEXT_PUBLIC_API_URL` | Documented target — no read found | — |
+| `REDIS_URL` | **Presence-checked only**, in `/api/health` — no queue code in this repo reads it (Celery/queue usage, if any, is `services/api`'s own concern, out of this repo's TS surface) | `app/api/health/route.ts` |
+| `COMPANIES_HOUSE_API_KEY` | Real key referenced by `services/api` (Python engine, `sources.yaml`/`connectors.py`) and passed through by `infra/docker-compose.yml` — not part of the Next.js edge app's own env surface | `services/api/` |

-## CI/CD (.github/workflows)
- **web**: lint + typecheck + build → deploy to Vercel on push to `main` (Vercel Git integration).
- **api**: lint (ruff) + tests (pytest) → build Docker image → deploy to VPS (SSH `docker compose pull && up -d`, or a small runner).
- Run DB migrations as a deploy step.
+### Platform-client URLs — corrected from a stronger claim

-## Monitoring (cheap)
- Vercel Analytics + Speed Insights (web).
- **Sentry** free tier (web + api).
- Uptime ping on `/health`.
- Worker/job health visible in admin (reads `jobs`).
+`CL0UD_URL`, `N0D_URL`, `AUD0_URL`, and **`ST0RE_URL`** are all **documented targets only — none of
+the four is read via `process.env.*` anywhere in this repo's committed code**, grep-verified this
+pass (`grep -rn "process\.env\.\(ST0RE_URL\|CL0UD_URL\|N0D_URL\|AUD0_URL\)"` returns zero matches
+outside comments and one `it.todo(...)` placeholder in `tests/p0/iceberg-write-service.test.ts`).
+
+This corrects a claim that appears in `.env.example` itself (on `feature/0pt-env-example`) and was
+carried into an earlier version of this doc: that comment states "`ST0RE_URL` **IS** read
+(`src/clients/st0re-client.ts`, `src/clients/st0re-lakehouse-client.ts`)". That is not accurate as of
+this verification. Both of those client files — like `cl0ud-client.ts`, `n0d-client.ts`, and
+`aud0-client.ts` — only export a `create*Client(baseUrl?: string)` factory that falls back to an
+in-memory mock when no `baseUrl` argument is passed. Every call site in this repo (`app/api/0pt/**`
+routes, `src/services/*.ts`) either passes no `baseUrl` at all or forwards an `opts?.st0reBaseUrl`-style
+constructor option that nothing upstream ever populates from `process.env.ST0RE_URL`. This matches
+`docs/ICEBERG_WRITE_BOUNDARY.md`'s own "Verification status" section, which lists wiring
+`ST0RE_URL` → `IcebergWriteService({ st0reBaseUrl: process.env.ST0RE_URL })` as **future work**, not
+something already done.
+
+**Net effect:** setting any of `CL0UD_URL`/`N0D_URL`/`AUD0_URL`/`ST0RE_URL` in a deployed environment
+today does nothing by itself. A future pass has to wire each route/service to actually read its
+corresponding env var before the value has any effect. Until then, every 0pt→platform call in this
+repo runs against the deterministic in-memory mock built into each client file — real, tested TS, but
+never exercised against a live CL0UD/N0D/AUD0/ST0RE instance from this codebase.
+
+## Security & compliance — corrected against actual code, not the target design
+
+The items below were previously described as already-built behavior. Grep/read-verified this pass,
+several are **env-guarded stubs that return a plausible-shaped response without doing the described
+work**. Stating this plainly, per this repo's own honesty convention:
+
+- **Customer DB grants** — `app/api/connections/db-grant/route.ts` returns `501` when `GRANT_ENC_KEY`
+  is unset, and a stub `201 { grant_id, status: "pending" }` when it is set. **There is no AES-GCM
+  encryption, no read-only-role validation, and no persistence implemented yet** — the route's own
+  comment describes the target behavior ("validate read-only, AES-GCM encrypt conn_string, store,
+  audit") but the code doesn't do it. This is a real gap, not a doc typo.
+- **File delivery / presigned R2 URLs** — same pattern: `app/api/uploads/route.ts` is a `501` stub
+  with a hardcoded `put_url: null`. No presigned URL is ever actually generated in this repo today.
+- **Tenant/org isolation — OPEN SECURITY GAP, not a deliberate two-tier design.** Several `app/api/0pt/*`
+  routes read `tenant_id`/`project_id` directly from the request body instead of from a server-bound
+  session:
+  - `app/api/0pt/lakehouse/mappings/route.ts`
+  - `app/api/0pt/lakehouse/mappings/[mappingId]/writes/route.ts`
+  - `app/api/0pt/sources/rate-policies/route.ts`
+  - `app/api/0pt/sources/[sourceId]/query/route.ts`
+  - `src/services/document-capture-service.ts`
+
+  This is not a defensible internal-vs-external boundary — **it's because no auth/session system
+  exists anywhere in this repo yet.** `app/api/orders/route.ts`'s own `GET` handler carries the
+  literal comment `// org scoping added with auth` — i.e., not yet. `lib/auth.ts` is a lightweight
+  HMAC session scaffold gated by a dev-only login key, unconnected to any of the `0pt/*` routes above.
+  Any caller can currently claim any `tenant_id` for these endpoints. Fixing this is Phase 3 of
+  `docs/09-build-plan.md` (Auth & portal shell) — it is Simon's call how that auth design binds
+  `tenant_id` server-side; it is not built anywhere in this repo today.
+- **PII (contacts/UBO) / DPA** — no code found in this pass implementing lawful-basis recording,
+  deletion-on-request, or a published DPA. Treat as target design, per `CLAUDE.md` §5, not shipped.
+- **Secrets rotation / least privilege** — no rotation tooling found in this repo (expected — that's
+  an operational practice, not application code — but noting it's unverified either way).
+- **Quality/QA gate on delivered data** — `src/services/quality-check-service.ts`,
+  `src/services/quality-report-service.ts`, `src/types/quality-check.ts`, `src/types/quality-report.ts`,
+  `src/data-platform/services/catalog-service.ts`, and `sql/002_p0_dataset_quality.sql`/`sql/003_*.sql`
+  were at one point referenced in `docs/ICEBERG_WRITE_BOUNDARY.md`, `docs/11-lakehouse-write-plan.md`,
+  and `docs/P0_QUERY_SOURCE_FLOW.md` as if built and tested. **None of these files has ever existed in
+  this repo's git history, on any branch** (`git log --all` confirms zero commits for every one of
+  those paths). **All three of those docs have since been corrected** (verified this pass) — each now
+  carries its own "fabricated, not built" callout and none currently asserts those files as real; this
+  section restates the underlying fact because it directly bears on the "Security & compliance" claims
+  below: **there is no lakehouse-side data-quality/QA enforcement built in this repo today**. (The
+  Python engine's `services/api/workers/pipeline.py` does have a real, working confidence-threshold
+  drop — `delivered = [r for r in deduped if r["confidence"] >= threshold]` — but that's a separate,
+  narrower mechanism inside the FastAPI pipeline, not the TS/lakehouse quality-check layer those three
+  docs describe.)
+
+## Embedding NocoDB / Metabase
+
+`components/embed.tsx` (`EmbeddedView`) is real, committed code — a sandboxed `<iframe>` that renders
+whatever `src` URL its caller passes, with a placeholder state when `src` is `null`. **What's missing:
+the server-side code that generates a signed Metabase/NocoDB embed URL from `METABASE_SECRET_KEY` /
+`NOCODB_API_TOKEN`.** No such generator was found in this pass. So the embed *shell* exists; the
+signed-URL *plumbing* that would make it show real customer data does not yet.
+
+## CI/CD
+
+**There is no `.github/workflows/` directory anywhere in this repo.** No lint/typecheck/build/test
+pipeline runs in CI today. On the TS side, `pnpm lint`, `pnpm typecheck`, and `pnpm test` (vitest,
+`tests/p0/*.test.ts`) exist as local scripts in `package.json`, but nothing invokes them automatically
+on push/PR. **On the Python side there is no lint/test tooling at all** — grep-verified this pass:
+`ruff` and `pytest` appear nowhere in `services/api/requirements.txt` or anywhere else in this repo
+(no `pyproject.toml`, no `pytest.ini`, no test files). `services/api/README.md`'s own "Run locally"
+section only lists `pip install -r requirements.txt` + `uvicorn`/`python -m workers.run` — no lint or
+test step. An earlier version of this doc claimed `ruff`/`pytest` "exist as local scripts" for
+`services/api`; that was unverified and is corrected here. This is a real gap against
+`docs/09-build-plan.md` Phase 0's "CI skeleton" deliverable — not yet built, not a doc omission.
+
+## Monitoring
+
+- **Vercel Analytics** — genuinely wired: `app/layout.tsx` imports and renders `<Analytics />` from
+  `@vercel/analytics/next` (`package.json` dependency `@vercel/analytics@1.3.1`).
+- **Sentry** — not found. No `sentry` package in `package.json`, no Sentry init/config file anywhere
+  in the repo. This is a documented target only, not shipped.
+- **Uptime ping on `/health`** — `app/api/health/route.ts` exists and returns `{ ok, db, queue, ts }`
+  based on env presence checks; no external uptime monitor wired to it was found in this repo (that
+  would live outside this codebase regardless, e.g. an external pinger — unverified either way).
+- **Worker/job health in admin** — `app/admin/jobs/page.tsx` exists as a page; this pass did not trace
+  whether it reads real job state or placeholder data (out of this doc's grounding scope — flagged for
+  whoever owns `docs/01-product.md`/admin-portal docs to verify).
@@ -2,28 +2,103 @@

 Phased, in dependency order. **Finish a phase to its acceptance criteria before the next.** Each phase = small, reviewable commits. Reconcile with existing code rather than rewriting wholesale.

+> **Status callouts added 2026-07-19.** Each phase below now carries a `Status:` line, grep/read-verified
+> against `main` this pass. These are conservative on purpose: a phase is only called **Done** when this
+> pass found real, working code satisfying its Accept criteria; anything else is **Partial** (with the
+> specific evidence and gap named) or **Not started**. No phase is upgraded to Done without a code
+> citation. Where a referenced doc (e.g. `docs/design/...`) doesn't exist, that's flagged rather than
+> silently worked around. See `docs/08-infrastructure.md` for the full env/security grounding these
+> statuses draw on.
+
 ## Phase 0 — Foundation & repo
 - Monorepo structure (`docs/08`). Migrate existing `src/orchestrator` + `src/workers` into `services/api`.
 - Postgres schema + migrations (`docs/03`); `pgvector` enabled. `.env.example`.
 - `docker-compose` up (postgres, redis, api, worker, nocodb, metabase, caddy). `/health` green.
 - CI skeleton (lint/typecheck/build).
 - **Accept:** `docker compose up` runs the whole stack locally; migrations apply; `/health` returns ok for db + queue.
+- **Status: Partial.**
+  - Repo structure exists but diverged from the `apps/web`/`packages/shared` layout `docs/08` originally
+    sketched — it settled on `app/` (Next.js, repo root), `lib/`, `src/` (platform clients/services), and
+    `services/api/` (FastAPI). `docs/08-infrastructure.md` now documents the structure as-built.
+  - Migration to `services/api/orchestrator` + `services/api/workers` is **done** (verified: those
+    directories exist and contain `main.py`/`adaptive_router.py`/`pipeline.py`/etc.; no `src/orchestrator`
+    or `src/workers` remain at the old paths).
+  - Postgres schema is real: `sql/001_init.sql` (`CREATE EXTENSION vector`, `CREATE EXTENSION pgcrypto`,
+    17 tables incl. `orgs`, `users`, `orders`, `jobs`, `audit_log`, `bridge_provenance`, `db_grants`,
+    `payments`) + `sql/004_iceberg_write_boundary.sql`.
+    **No `sql/002_*` or `sql/003_*` exists anywhere in this repo's history** — some other docs
+    (`docs/ICEBERG_WRITE_BOUNDARY.md` etc.) cite a `sql/002_p0_dataset_quality.sql` that was never built;
+    see `docs/08-infrastructure.md`'s "Schema state" section.
+  - `.env.example` — **now exists**, on branch `feature/0pt-env-example`
+    (`github.com/sax3l/0pt/pull/3`), **not yet merged to `main`**. It was blocked for the life of this
+    project by `.gitignore`'s blanket `.env*` rule silently matching it too; the same PR fixes that
+    with `!.env.example`. Until that PR merges, `main` still has no `.env.example`.
+  - `infra/docker-compose.yml` and `infra/Caddyfile` are real, committed files (not sketches) covering
+    exactly the services listed. **This pass found no evidence they've ever actually been run** — no
+    CI, no deploy log, no reachable host checked. "File exists and looks correct" ≠ "verified to run";
+    treat the Accept criterion ("docker compose up runs... /health returns ok") as unverified.
+  - CI skeleton — **not built.** There is no `.github/workflows/` directory in this repo at all. `pnpm
+    lint`/`typecheck`/`test` exist as local scripts only.

 ## Phase 1 — Design system in code
 - Tailwind + shadcn; `globals.css` (grain + reveal keyframes) and `useReveal` verbatim (`docs/05`).
 - Build **DataArtifact** primitive (table/map/schema/chart/grid) and **ProvenanceBadge** (`docs/design` prompts 5.1, 2.11).
 - **Accept:** a sample page renders mono tokens, a DataArtifact animates on scroll, reduced-motion respected, focus rings visible.
+- **Status: Partial — real components exist; scroll-motion/reduced-motion/focus-ring behavior not
+  independently exercised this pass.**
+  - Tailwind + shadcn/radix stack: confirmed real in `package.json` (`tailwindcss`, `@radix-ui/*`,
+    `class-variance-authority`, `tailwind-merge`, `tailwindcss-animate`).
+  - `hooks/use-reveal.ts`, `components/data-artifact.tsx`, `components/provenance-badge.tsx` all exist
+    and are used across `app/katalog`, `app/kallor`, `app/bestall`, `app/order/[id]`, and most
+    `components/sections/*` files (grep-confirmed).
+  - `docs/design/0pt-v0-build-brief.md` and `docs/design/0pt-design-coverage-and-visuals.md` (the
+    "prompts 5.1, 2.11" this bullet references) **do not exist anywhere in this repo** — confirmed via
+    full-repo search; there is no `docs/design/` directory at all. `CLAUDE.md`'s own doc index has
+    already been corrected to flag this as a gap rather than list them as real. Treat any reference to
+    specific numbered "build-brief prompts" in this build plan as pointing at a doc that was never
+    written — not this file's scope to author that content.
+  - Reduced-motion handling, focus-ring visibility, and actual scroll-triggered animation behavior were
+    not executed/verified in this pass (no browser run performed) — code presence is confirmed, runtime
+    behavior is not.

 ## Phase 2 — Marketing + catalog (placeholder data)
 - Landing components top-to-bottom (build-brief 2.1–2.10): Header, Hero, Philosophy, Catalog teaser, Engine, Visualisation gallery, Coverage, Editorial, Proof, Footer.
 - Full **Catalog** page + **Dataset detail** + **Sourcing-map** page (coverage doc 5.4). Postgres full-text search.
 - All with loading/empty/error states + mobile.
 - **Accept:** marketing site + catalog browse work end-to-end on placeholder catalog rows; one continuous scroll reads well; DoD met per screen.
+- **Status: Partial.**
+  - Landing section components are real: `components/sections/{hero,philosophy,gallery,editorial,
+    pricing,technology,testimonials,footer,featured-products,collection}-section.tsx` all exist.
+  - `app/katalog/page.tsx`, `app/katalog/[id]/page.tsx`, `app/kallor/page.tsx` all exist.
+  - **Postgres full-text search was not found** — grepped for `to_tsvector`/`websearch_to_tsquery`
+    across the whole repo, zero matches. Catalog browsing today reads from `lib/data.ts` placeholder
+    data, not a full-text query against Postgres. This Accept criterion's "catalog browse... on
+    placeholder catalog rows" half is plausible; the Postgres full-text search half is not built.
+  - Loading/empty/error states + mobile + DoD-per-screen were not independently audited screen-by-screen
+    this pass — `components/states.tsx` (`LoadingSkeleton`, `ErrorState`) exists and is imported widely,
+    which is evidence toward this but not a full verification.

 ## Phase 3 — Auth & portal shell
 - Auth.js + Postgres adapter; sign in/up/verify/forgot. `orgs`/`users`.
 - Portal shell + Dashboard ("Mina beställningar") with empty state.
 - **Accept:** a user can sign up, land in an empty dashboard, sign out; routes protected.
+- **Status: Not done — this is the most consequential gap in the whole repo, not a minor loose end.**
+  - **There is no Auth.js integration.** `lib/auth.ts` is a from-scratch, ~40-line HMAC-SHA256 session
+    scaffold (Web Crypto, no dependency) whose own comment states: "Production auth = Auth.js + Postgres
+    adapter + OAuth (docs/02) — wired once the database is provisioned." `app/api/auth/login/route.ts`
+    is a **dev-only** login gated by a shared `DEV_LOGIN_KEY`, not sign-up/verify/forgot.
+  - `orgs` and `users` tables exist in `sql/001_init.sql` (schema is ready), but nothing in the app
+    reads/writes them for real session-bound identity today.
+  - `app/portal/page.tsx` and sibling portal pages exist (shell is real), but routes are **not**
+    protected by any real session check tied to that schema.
+  - **Concretely, this means the tenant/org isolation several `0pt.*` API routes assume does not exist
+    yet.** `app/api/0pt/lakehouse/mappings/route.ts`, `.../writes/route.ts`,
+    `app/api/0pt/sources/rate-policies/route.ts`, `app/api/0pt/sources/[sourceId]/query/route.ts`, and
+    `src/services/document-capture-service.ts` all read `tenant_id`/`project_id` straight from the
+    request body — anyone can claim any tenant. `app/api/orders/route.ts`'s own `GET` handler carries
+    the literal comment `// org scoping added with auth`. This is an open security gap, not a
+    two-tier design choice — see `docs/08-infrastructure.md`'s "Security & compliance" section for the
+    full list. **Do not build any doc or feature that assumes tenant-scoped auth already exists.**

 ## Phase 4 — Order lifecycle end-to-end (test mode)
 - **Configurator** (2.12) wired to `POST /estimates` (real estimate math in FastAPI).
@@ -32,12 +107,53 @@ Phased, in dependency order. **Finish a phase to its acceptance criteria before
 - **Validation & delivery** (2.15): tabs render from a sample delivery; **accept** → `POST /payments/release` (test) → `DELIVERED`; **revise** leaves escrow untouched.
 - AI-assist (`POST /ai/parse`) prefilling the configurator.
 - **Accept:** a full custom order can be configured, deposit paid (test), watched, validated, accepted, and "delivered" — state machine in `docs/01` traversed; escrow split correct.
+- **Status: Partial — the payment/escrow spine is genuinely real; the SSE tracker is not.**
+  - `app/api/estimates/route.ts` exists.
+  - Deposit checkout is **real, working code**: `app/api/payments/[order_id]/deposit/route.ts` calls
+    Stripe's Checkout Sessions API directly (not a stub) and `app/api/webhooks/stripe/route.ts` verifies
+    the webhook signature and advances order status via `setStatus`.
+  - `app/api/payments/[order_id]/release/route.ts` is also real: it enforces the escrow rule in code —
+    balance release is rejected with `409 not_accepted` unless `order.status === "accepted"` — matching
+    the "escrow split correct" accept criterion's intent.
+  - **`GET /api/orders/{id}/events` (SSE) does not exist.** Only `GET`/`PATCH /api/orders/{id}` were
+    found (`app/api/orders/[id]/route.ts`); no `/events` sub-route, and no `EventSource`/
+    `text/event-stream`/`ReadableStream` usage anywhere in `app/` (grep-verified). If a production
+    tracker is live today, it's polling `GET /api/orders/{id}`, not the SSE stream this bullet describes
+    — or it hasn't been built. Either way, the SSE contract as written is not implemented.
+  - `app/api/ai/parse/route.ts` is real: a genuine (non-fabricated) keyword/regex heuristic that
+    prefills a config object, with a documented fallback to `engineFetch("/ai/parse", ...)` when
+    `ENGINE_URL` is set. This one holds up as described.

 ## Phase 5 — Real data engine (Nordic slice)
 - Compliant connectors first: **GLEIF + Brreg + Companies House** (verify access terms; record in `sources.yaml`). Remove any FlareSolverr/bypass path (`docs/06`).
 - Pipeline stages produce real `dim_company` + `fact_financials` with `bridge_provenance`; QA threshold drops low-confidence rows.
 - Production tracker now reflects **real** job metrics.
 - **Accept:** a Nordic company dataset is produced for a real order, every field has provenance, quality report generated, level-0 fields shown honestly (not fabricated).
+- **Status: Partial.**
+  - `services/api/sources/sources.yaml` and `connectors.py` are real: GLEIF, Brreg, Companies House,
+    PRH, and CVR are all registered, each with an explicit `licence: "... — VERIFY"` tag rather than an
+    assumed-clean claim — matches the "verify access terms" instruction.
+  - `services/api/workers/adaptive_router.py`'s own comment confirms: "There are NO bypass/stealth/
+    proxy-rotation tiers here, by design (CLAUDE.md §1)" — the FlareSolverr/bypass removal is done, at
+    least on this repo's `main` (see `docs/08-infrastructure.md`'s "Known open question" about the
+    diverged Gitea remote, which independently added such a stack on its own `main` — unresolved which
+    remote is canonical).
+  - `services/api/workers/pipeline.py` has a real, working confidence-threshold QA drop: `delivered =
+    [r for r in deduped if r["confidence"] >= threshold]`, plus an `avg_confidence` figure in its output.
+    This is a genuine, narrow QA mechanism inside the Python engine.
+  - **This is not the same thing as the "quality report" / quality-check layer once described in
+    `docs/ICEBERG_WRITE_BOUNDARY.md`, `docs/11-lakehouse-write-plan.md`, and
+    `docs/P0_QUERY_SOURCE_FLOW.md`.** Those three docs used to cite `src/services/quality-check-service.ts`,
+    `src/services/quality-report-service.ts`, `src/types/quality-{check,report}.ts`, and
+    `src/data-platform/services/catalog-service.ts` as already-built and tested. **None of those files
+    has ever existed in this repo's git history, on any branch** — and all three docs have since been
+    corrected to say so explicitly (verified this pass), rather than repeating the original claim. So:
+    the narrow Python-side confidence filter is real; the broader TS/lakehouse "quality report" this
+    Accept criterion likely also intends is not built (see `docs/P0_DATASET_QUALITY_FLOW.md` for the
+    honest target spec). Whether `pipeline.py`'s `avg_confidence` output satisfies "quality report
+    generated" is a judgment call for whoever runs this phase — flagging rather than deciding it here.
+  - Whether an actual Nordic dataset has been produced end-to-end for a real order was not verified
+    this pass (would require running the stack).

 ## Phase 6 — Delivery surfaces & integrations
 - Exports: CSV / Parquet / JSON via R2 presigned URLs.
@@ -45,11 +161,34 @@ Phased, in dependency order. **Finish a phase to its acceptance criteria before
 - Integrations: **FiveCRM push**, webhooks, Google Sheets.
 - File **uploads** (Uppy → R2) for matching/enrichment.
 - **Accept:** a delivered dataset is downloadable, viewable in embedded NocoDB + Metabase (no separate login), and pushable to FiveCRM; uploads work.
+- **Status: Not done — this phase is UI-shell-only today.**
+  - CSV/Parquet/JSON exports via R2 presigned URLs: not found. `app/api/uploads/route.ts` (the closest
+    R2-touching code) is a `501` stub with a hardcoded `put_url: null` — no presign logic exists yet,
+    for uploads or exports.
+  - `components/embed.tsx` (`EmbeddedView`) is real — a sandboxed iframe shell — but the server-side
+    signed-URL generator for Metabase/NocoDB (`METABASE_SECRET_KEY`/`NOCODB_API_TOKEN`) that would feed
+    it a real `src` was not found anywhere in this pass.
+  - "FiveCRM" appears only as a **destination label string** in `lib/data.ts`, `lib/services.ts`,
+    `app/portal/integrationer/page.tsx` (explicitly described in that file's own comment as
+    "presentationella toggles" — i.e. presentational, not wired), and as one of several regex-matched
+    destination names in `app/api/ai/parse/route.ts`'s heuristic. **No actual FiveCRM API push exists.**
+  - `uppy` is not a dependency in `package.json` (checked directly) — the Uppy → R2 upload flow this
+    bullet describes has no corresponding package installed, let alone implemented.

 ## Phase 7 — Subscriptions / feeds
 - `subscriptions`; recurring jobs (weekly/daily) delivering **deltas**; webhooks on change.
 - Freshness monitoring; Resend emails (confirmation, "din data är klar", feedback).
 - **Accept:** an order converts to a feed; a scheduled run produces a delta + fires a webhook + email.
+- **Status: Partial — data layer real, scheduling and email are not.**
+  - `lib/subscriptions-store.ts` is real CRUD against the `subscriptions` table (with an in-memory
+    fallback when no DB is configured) — `createSubscription`/`listSubscriptions` genuinely insert/read.
+  - No recurring-job scheduler (cron, queue consumer producing deltas, etc.) was found on the TS side of
+    this repo. `services/api/workers/queue.py` exists on the Python side but this pass did not trace
+    whether it implements actual delta-producing scheduled runs — flagged as unverified rather than
+    assumed either way.
+  - **Resend is not wired at all** — grepped for `resend`/`Resend` across the whole repo, zero matches
+    outside `RESEND_API_KEY` being listed as an env var. No confirmation/"din data är klar"/feedback
+    email has been implemented.

 ## Phase 8 — Admin, hardening, compliance
 - Admin: order queue + scope/quote + escrow release; **source registry & freshness** monitoring; worker/job monitoring; customer + catalog management.
@@ -57,19 +196,50 @@ Phased, in dependency order. **Finish a phase to its acceptance criteria before
 - Security pass: RLS, presigned-only files, signed embeds, secret rotation, `audit_log` everywhere; **DPA** published; legal pages.
 - Finalize all loading/empty/error states + mobile across the app.
 - **Accept:** admin can run the business; DB-grant flow works and self-revokes; security checklist passes; DoD met app-wide.
+- **Status: Partial — UI shell real, the security substance is not.**
+  - Admin pages exist: `app/admin/{page,jobs/page,sources/page,customers/page,verktyg/page}.tsx`. This
+    pass did not verify whether they read real backend data or placeholders.
+  - `sql/001_init.sql` defines `audit_log`, `db_grants`, and `payments` tables — schema is ready.
+  - **The DB-access grant flow is a stub, not a working feature.**
+    `app/api/connections/db-grant/route.ts` returns `501` without `GRANT_ENC_KEY`, and with it set
+    returns a hardcoded `201 { grant_id, status: "pending" }` — **no AES-GCM encryption, no read-only
+    validation, and no self-revoke logic exist in code today**, despite the route's own comment
+    describing that target behavior. See `docs/08-infrastructure.md`'s "Security & compliance" section.
+  - RLS enforcement, presigned-only files (blocked on the Phase 6 R2 gap above), signed embeds (blocked
+    on the Phase 6 NocoDB/Metabase gap above), and a published DPA were not found as implemented in this
+    pass. Treat the "security checklist passes" accept criterion as not met.

 ## Phase 9 — Launch
 - Domain `0pt.app` (Vercel) + subdomains (api/data/dash via Caddy). Sentry + uptime live.
 - Soft launch: Protosell internally + a handful of existing dealer relationships.
 - **Accept:** a real external customer completes an order start→delivery in production; feedback loop running.
+- **Status: Domain is live; soft-launch/customer criterion not verified.**
+  - **Verified this pass** (network check performed): `https://0pt.app` returns HTTP 200 and serves this
+    repo's own Next.js app (title "0pt — your data", SIAX branding); `GET /api/health` returns
+    `{"ok":true,"service":"0pt-web","db":"not_configured","queue":"not_configured",...}`, an exact shape
+    match for `app/api/health/route.ts`. README's "Live: https://0pt.app" is confirmed, and the response
+    confirms the live deployment has no `DATABASE_URL`/`REDIS_URL` set — see `docs/08-infrastructure.md`'s
+    "Hosting topology" section. This does not confirm which git remote/commit is deployed (see the
+    diverged-remotes note elsewhere in this doc), or that api/data/dash subdomains or Caddy are live —
+    only the root Vercel deployment was checked.
+  - **Sentry is not wired** — no `sentry` package in `package.json`, no Sentry config file anywhere in
+    the repo (grep-confirmed). `@vercel/analytics` **is** genuinely wired (`app/layout.tsx` renders
+    `<Analytics />`), which is a real but much smaller piece of the "Sentry + uptime live" bullet.
+  - No evidence either way on the soft-launch/external-customer criterion — out of this doc's ability to
+    verify from code alone.

 ---

 ## Working conventions (for Claude Code)
 - Tech docs + identifiers **English**; UI copy **Swedish**.
 - Conventional Commits; one concern per PR; keep diffs reviewable.
- No secrets in code; update `.env.example` when adding env.
+- No secrets in code; update `.env.example` when adding env. (`.env.example` itself currently lives on
+  `feature/0pt-env-example` / PR #3 — merge that first, or this instruction has nothing to update yet.)
 - Add/extend tests for engine logic (estimate math, fusion/confidence, dedup) and API contract.
 - When a source's access/licence is unclear, **verify and record in `sources.yaml`** before relying; if disallowed for bulk, route to licensed/partner or mark level 0 — never bypass, never fabricate.
 - Touch the design tokens/motion only via `docs/05`; keep red ≤ once per screen; no photography.
 - If anything here conflicts with existing code, **flag it** in the PR description and propose the reconciliation rather than guessing.
+- **Two git remotes claim to be this repo** (`github.com/sax3l/0pt` and `git.siax.io/sax3l/0pt`), and
+  they have independently diverged (see `CLAUDE.md`, `README.md`). Don't assume the checkout you're in
+  is the only copy, and don't silently pick one as canonical — that's Simon's decision, flag it if it
+  becomes relevant to the phase you're working on.
@@ -6,12 +6,27 @@ outside this repo and states what it means for 0pt specifically. It does not cha
 0pt's platform tables and current data entities (`docs/03`). Read this alongside those docs, not
 instead of them.

+> **Status update.** Since this pointer doc was first written, a follow-up implementation pass
+> turned most of 0pt's side of this plan into real TypeScript — see
+> `docs/11-lakehouse-write-plan.md`'s "what the implementation pass closed" section and
+> `docs/ICEBERG_WRITE_BOUNDARY.md` for the current, corrected status. Two things to know before
+> reading the rest of this doc: (1) that write-path code is **real and unit-tested against a mock
+> ST0RE client, not verified against a running ST0RE deployment**; (2) an earlier version of
+> `docs/11` and `docs/ICEBERG_WRITE_BOUNDARY.md` also claimed 0pt's data-quality/QA stage had a
+> dedicated, tested `quality-check-service.ts`/`quality-report-service.ts` implementation — that
+> claim was **fabricated**. `git log --all` for those paths (and `sql/002_p0_dataset_quality.sql`,
+> `sql/003_*.sql`) returns zero commits, on any branch, ever. Both docs have been corrected; see
+> them for the full account. This doc's own references to "QA" below point only to the *spec* in
+> `docs/06-data-engine.md`, not to any implemented service.
+
 ## The decision (made elsewhere — do not re-litigate here)

 **Apache Iceberg is the canonical SIAX lakehouse table format**, per **ADR-0030**, authored in the
-`n0d` (Compute OS) repo. Delta Lake is explicitly rejected as the canonical P0/P1 format across
-SIAX Technology; it may only ever be used later as an import/export bridge, never as the format
-0pt writes natively.
+`n0d` (Compute OS) repo (a dated copy also lives in `cl0ud`'s `docs/architecture/`, since the
+boundary audit that motivated it originated in n0d but the ADR itself is recorded as SIAX-wide;
+both copies describe the same accepted decision — verified by reading both this pass). Delta Lake
+is explicitly rejected as the canonical P0/P1 format across SIAX Technology; it may only ever be
+used later as an import/export bridge, never as the format 0pt writes natively.

 Rationale (from the ecosystem ADR, summarized): SIAX needs one vendor-neutral, multi-engine,
 catalog-first open table format for the MinIO/ST0RE lakehouse, because several products need to
@@ -29,17 +44,37 @@ work from many engines (Trino/Spark/Flink/DuckDB/etc.), not one.
 | AUD0 | Lineage |
 | CL0UD | Policy |

+This table condenses ADR-0030 §2.1/§2.4's ownership split for 0pt's purposes — it is a paraphrase,
+not a verbatim quote (corrected this verification pass; re-checked against `cl0ud`'s copy of the
+ADR). The ADR's §2.4 table also names **INF0** (model registry/experiment tracking, MLflow as an
+adapter) and its §2.1 also names **API0** (schema/docs exposure); both rows are omitted here
+because neither changes anything for 0pt specifically. One paraphrase is deliberate, not
+accidental: the ADR's own 0pt row reads "Dataset production, **quality**, data contracts, writes"
+— the word "quality" is intentionally dropped from this table's 0pt row above, because 0pt's
+quality/QA stage is not yet built (see the status callout at the top of this doc). See ADR-0030
+§2.4 directly (`cl0ud`'s or `n0d`'s copy) for its own exact wording of every row.
+
 ## What this means for 0pt

 0pt is the **write-path owner** for the datasets it produces: 0pt runs sourcing → extraction →
-structuring → enrichment → QA (`docs/06-data-engine.md`) as it does today, and — once ST0RE's
-table registry exists — writes the resulting datasets as **Iceberg tables through that registry**.
-0pt does **not** talk to N0D's catalog or any lakehouse storage directly; it goes through ST0RE.
+structuring → enrichment → QA (`docs/06-data-engine.md` — a design spec, not yet a built service;
+see the status callout above) as it does today, and writes the resulting datasets as **Iceberg
+tables through ST0RE's table registry**. 0pt does **not** talk to N0D's catalog or any lakehouse
+storage directly; it goes through ST0RE.
+
+ST0RE's table registry is real, committed code (`sax3l/st0re`, `/v1/st0re/lakehouse/*`), and 0pt
+has a real client and services that target it — `src/clients/st0re-lakehouse-client.ts`,
+`src/services/iceberg-write-service.ts`, `src/services/dataset-iceberg-mapping-service.ts`. None of
+this has been exercised against a *running* ST0RE instance from this repo: every test to date runs
+against that client's deterministic in-memory mock (no `ST0RE_URL` was reachable from this
+environment). Treat "0pt writes Iceberg tables through ST0RE" as **real code, mock-tested, not
+live-verified** — see `docs/ICEBERG_WRITE_BOUNDARY.md`'s "Verification status" section for the full
+detail, including what is and isn't wired end-to-end.

 This does not replace Postgres as the platform backbone (orders, users, jobs, billing — `docs/03`
 — stay exactly as they are). It is additive: dataset **output** (the delivered data product, today
 exported as CSV/Parquet/JSON per `docs/04-api.md`) gains an additional, canonical Iceberg
-write-path once ST0RE's registry ships. Concrete to-dos and required schema/event names are in
+write-path. Concrete to-dos, current build status, and required schema/event names are in
 `docs/11-lakehouse-write-plan.md`.

 ## Also relevant: the `sourceRatePolicy` deprecation in N0D
@@ -47,14 +82,23 @@ write-path once ST0RE's registry ships. Concrete to-dos and required schema/even
 The same ecosystem audit that produced ADR-0030 found N0D's `ComputePolicy` type carrying a
 `sourceRatePolicy` field (per-source-domain crawl rate limits, e.g.
 `{'allabolag.se': 1, 'ratsit.se': 1}`) hardcoded into N0D's policy defaults. That is 0pt's own
-crawl-domain knowledge — it has been deprecated/removed from N0D's seed data. 0pt does not rely on
-N0D for source-rate/crawl-compliance policy; 0pt already owns the sourcing chain and its rate
-limits today (`sources.yaml`, `docs/06-data-engine.md` §`rate_limit`), and will formalize its own
-model rather than depend on anything in N0D for this. See `docs/11-lakehouse-write-plan.md`.
+crawl-domain knowledge — it has been deprecated in N0D (the field is still present on the type for
+backward compatibility, but N0D's own boundary-repair tests assert it now has **zero effect** on
+any allow/deny decision; verified by reading `n0d`'s `src/policy.ts` and
+`src/__tests__/boundary-repair.test.ts` this pass). 0pt does not rely on N0D for source-rate/
+crawl-compliance policy; 0pt already owns the sourcing chain and its rate limits today
+(`sources.yaml`, `docs/06-data-engine.md` §`rate_limit`), and has since formalized its own model —
+`src/services/source-rate-policy-service.ts`, real and tested, see `docs/11-lakehouse-write-plan.md`
+and `docs/ICEBERG_WRITE_BOUNDARY.md`.

 ## Non-goals of this doc

- Does not implement Iceberg writes today.
+- Does not itself implement Iceberg writes — see `docs/11-lakehouse-write-plan.md` /
+  `docs/ICEBERG_WRITE_BOUNDARY.md` for what a later pass actually built (real, mock-tested code;
+  not live-verified; data-quality/QA enforcement specifically is **not built** — see the status
+  callout above).
 - Does not modify `docs/03-data-model.md`'s Postgres schema.
- Does not require ST0RE's table registry to exist yet — this doc is the pointer; the plan doc
-  lists what's blocked on ST0RE vs. what 0pt can define now.
+- Does not require ST0RE's table registry to exist — as of this pass it does exist as real,
+  committed code in `sax3l/st0re`, though this repo has not confirmed it live/reachable. This doc
+  remains the pointer; `docs/11` lists what's still blocked on a *live, reachable* ST0RE vs. what
+  0pt has already built against the mock.
@@ -2,8 +2,23 @@

 Concrete follow-up to `docs/10-lakehouse-decision.md`. This is a planning doc for a **future**
 implementation session — it names the schemas/events precisely so that session doesn't have to
-guess, but it does not build the full pipeline today. Some items are already true today (quality
-rules) and this doc just confirms 0pt intends to keep them that way.
+guess, but it does not build the full pipeline today.
+
+> **Correction (documentation-accuracy pass).** This doc previously stated that item 4 (quality
+> rules staying in 0pt) was "already true today" and, in the update section below, that
+> `src/services/quality-check-service.ts` and `src/services/quality-report-service.ts` were real,
+> tested files that a later pass left "untouched." **That was fabricated.** `git log --all` for
+> `src/services/quality-check-service.ts`, `src/services/quality-report-service.ts`,
+> `src/types/quality-check.ts`, `src/types/quality-report.ts`, `sql/002_p0_dataset_quality.sql`,
+> and `sql/003_*.sql` returns zero commits, on any branch (`main`, `feature/0pt-env-example`,
+> `ci/add-quality-gate`), ever — these files have never existed in this repository. 0pt's
+> data-quality/QA stage is a **design spec only** (`docs/06-data-engine.md` §QA — Great
+> Expectations-style checks, intended to run inside the Python worker pipeline in `services/api`)
+> and is **not yet implemented** as any dedicated service in this repo, TypeScript or otherwise.
+> This is a real, currently open build gap, not a doc typo — see item 4's corrected entry below
+> and `docs/ICEBERG_WRITE_BOUNDARY.md`'s "Data quality: not yet built" section for the full
+> account. Everything else on this page (items 1, 2, 3, 5, 6, 7, 8) was independently re-verified
+> against the actual service/client/test files this pass and remains accurate.

 ## 2026-07-13 update: live verification + field-level gap closure

@@ -16,8 +31,9 @@ below, which is the original (2026-07-12) status record and is otherwise unchang

 ## 2026-07-12 update: what the 0pt write-boundary implementation pass closed

-This pass (the "future implementation session" this doc was written for) turned most items below
-into real, tested code. Full detail in `docs/ICEBERG_WRITE_BOUNDARY.md`; short version:
+This pass turned most items below into real, tested code. Full detail in
+`docs/ICEBERG_WRITE_BOUNDARY.md`; short version (re-verified this documentation-accuracy pass
+against the actual files):

 - Item 2 (`0pt.dataset_iceberg_mapping`): CLOSED as real code -- `src/types/dataset-iceberg-mapping.ts`,
  `src/services/dataset-iceberg-mapping-service.ts`, `packages/schemas/0pt.dataset_iceberg_mapping.schema.json`,
@@ -33,8 +49,12 @@ into real, tested code. Full detail in `docs/ICEBERG_WRITE_BOUNDARY.md`; short v
  against that client's mock implementation (same mock/HTTP convention as `cl0ud-client.ts` etc).
  NOT verified against a running ST0RE deployment in this pass -- see the boundary doc's
  "Verification status" section and the `it.todo` in that test file.
- Item 4 (quality rules stay in 0pt): CONFIRMED, untouched -- `src/services/quality-check-service.ts`
-  and `src/services/quality-report-service.ts` were not modified by this pass.
+- Item 4 (quality rules stay in 0pt): **NOT BUILT.** `src/services/quality-check-service.ts` and
+  `src/services/quality-report-service.ts` do not exist and never have (see the correction callout
+  above) -- there was nothing for this pass to leave "untouched." The *intent* (0pt owns QA logic,
+  N0D never does) is still the correct target and nothing since has contradicted it, but it is not
+  yet backed by any code. This is an open gap for a future implementation session, not a closed
+  item.
 - Item 5 (`0pt.source_rate_policy`): CLOSED as real code -- `src/types/source-rate-policy.ts`,
  `src/services/source-rate-policy-service.ts`, `packages/schemas/0pt.source_rate_policy.schema.json`,
  `sql/004_iceberg_write_boundary.sql` (`opt_source_rate_policies`), tested in
@@ -77,21 +97,32 @@ into real, tested code. Full detail in `docs/ICEBERG_WRITE_BOUNDARY.md`; short v
   - `entity_type`, `market` — for routing/filtering.
   - `mapped_at`, `mapped_by`.

-3. **Write a first test dataset to Iceberg** through ST0RE's (future) table registry, once that
-   registry exists. Pick a small, low-risk dataset (e.g. a single-market `dim_company` slice) as
-   the pilot. This validates the write path end-to-end before any production order relies on it.
+3. **Write a first test dataset to Iceberg** through ST0RE's table registry. *(Status: CLOSED per
+   the update above — `tests/p0/iceberg-write-service.test.ts` exercises exactly this pilot flow,
+   but only against `St0reLakehouseClient`'s mock; not yet run against a live ST0RE. Treat this
+   item as "code exists," not "validated end-to-end against a real deployment.")* Original plan:
+   pick a small, low-risk dataset (e.g. a single-market `dim_company` slice) as the pilot, to
+   validate the write path end-to-end before any production order relies on it — that live-ST0RE
+   validation still has not happened.

-4. **Keep data quality rules in 0pt.** This is already correct today (per the `n0d` audit): 0pt's
-   QA stage (`docs/06-data-engine.md` §QA — Great Expectations checks for validity, completeness,
-   freshness, uniqueness, corroboration) is caller-supplied logic that 0pt owns and hands to
-   whichever engine executes a job; it is not, and must not become, logic owned or embedded by
-   N0D. This doc confirms 0pt intends to keep authoring/owning quality rules itself even after
-   N0D executes heavy writes/compactions on 0pt's behalf (see item 7).
+4. **Keep data quality rules in 0pt.** This is the correct *target* per the `n0d` audit, and
+   remains a spec-level design in `docs/06-data-engine.md` §QA (Great Expectations-style checks
+   for validity, completeness, freshness, uniqueness, corroboration), but **it is not built** —
+   there is no dedicated quality-check/quality-report service in this repo as of this writing (see
+   the correction callout at the top of this doc). Once it is built, the design intent stands:
+   quality logic must be caller-supplied logic that 0pt owns and hands to whichever engine executes
+   a job; it must not become logic owned or embedded by N0D, even after N0D executes heavy
+   writes/compactions on 0pt's behalf (see item 7). This item stays open until that service exists
+   and is tested.

 5. **Keep source-rate/crawl-compliance policy logic in 0pt** — build a real model here, do not
-   rely on N0D for this. Context: N0D's `ComputePolicy.sourceRatePolicy` (per-domain crawl rate
-   limits) has been deprecated/removed from N0D's seed data as part of the same audit — that field
-   never belonged to N0D. 0pt already has the raw material for this in `sources.yaml`
+   rely on N0D for this. *(Status: CLOSED per the update above — `SourceRatePolicyService` is real
+   and tested.)* Context: N0D's `ComputePolicy.sourceRatePolicy` (per-domain crawl rate limits) has
+   been deprecated in N0D as part of the same audit (the field is still present on N0D's type for
+   backward compatibility, but N0D's own boundary-repair tests assert it now has zero effect on any
+   allow/deny decision — verified by reading `n0d`'s `src/policy.ts` and
+   `src/__tests__/boundary-repair.test.ts`) — that field never belonged to N0D. 0pt already has the
+   raw material for this in `sources.yaml`
   (`docs/06-data-engine.md`, the `rate_limit` / `robots_ok` fields per source), but that's
   currently free-text/per-entry, not a first-class policy object. Formalize it as
   **`0pt.source_rate_policy.schema.v1`**. Suggested shape, following the same conventions:
@@ -104,8 +135,11 @@ into real, tested code. Full detail in `docs/ICEBERG_WRITE_BOUNDARY.md`; short v
   This model belongs entirely to 0pt's sourcing/compliance domain (`docs/06`) — it must not be
   reintroduced into N0D, CL0UD, or any other product's policy defaults.

-6. **Emit lineage for dataset → Iceberg table → snapshot**, to AUD0, once AUD0 exists as a real
-   evented product (it does not yet — do not build a lineage sink against it prematurely). Plan
+6. **Emit lineage for dataset → Iceberg table → snapshot**, to AUD0. *(Status: CLOSED per the
+   update above — all four events below are wired and fire through the existing `Aud0Client`,
+   which is mock/no-op by default because AUD0 still has no live ingestion endpoint. This did not
+   mean standing up a bespoke lineage sink prematurely — it means calling the same shared,
+   already-mocked AUD0 client interface every other 0pt event in this repo already calls.)* Plan
   for three events, emitted by 0pt at the corresponding step:
   - **`0pt.dataset_iceberg_table_mapped`** — fired when step 2's mapping is created/updated.
   - **`0pt.iceberg_write_requested`** — fired when 0pt requests a write of a produced dataset
@@ -120,16 +154,19 @@ into real, tested code. Full detail in `docs/ICEBERG_WRITE_BOUNDARY.md`; short v
     crawl-compliance posture without needing to poll 0pt's DB.

 7. **Request N0D jobs for heavy writes/compactions if/when needed, rather than 0pt executing
-   them itself.** 0pt produces and owns the dataset; if a write or compaction is heavy enough to
-   warrant dedicated compute (large backfills, table maintenance), 0pt should submit that as a job
-   request to N0D's execution layer rather than running it in-process in `services/api` workers.
-   N0D executes; it does not own the data, the schema, or the decision of *what* to write.
+   them itself.** *(Status: CLOSED per the update above — `IcebergWriteService.requestIcebergWrite`
+   requests an N0D job only when `heavy: true`, tested.)* 0pt produces and owns the dataset; if a
+   write or compaction is heavy enough to warrant dedicated compute (large backfills, table
+   maintenance), 0pt should submit that as a job request to N0D's execution layer rather than
+   running it in-process in `services/api` workers. N0D executes; it does not own the data, the
+   schema, or the decision of *what* to write.

-8. **Do not persist lakehouse table state outside ST0RE** once ST0RE's registry exists. Until
-   then, 0pt has no lakehouse table state to persist at all — Postgres (`docs/03`) remains the
-   only store. Once ST0RE ships its registry, 0pt must not stand up a parallel
-   catalog/metadata store of its own (that would repeat the exact mistake this plan is repairing:
-   N0D building its own Iceberg catalog because nothing else had one yet).
+8. **Do not persist lakehouse table state outside ST0RE.** *(Status: CLOSED as a design property
+   per the update above — `IcebergWriteService`/`DatasetIcebergMappingService` hold zero table or
+   snapshot state; the only thing 0pt persists is a reference `iceberg_table_id`.)* ST0RE's table
+   registry now exists as real code (not yet confirmed live/reachable from this repo). 0pt must not
+   stand up a parallel catalog/metadata store of its own (that would repeat the exact mistake this
+   plan is repairing: N0D building its own Iceberg catalog because nothing else had one yet).

 ## Required schema names (for the future implementation session)

@@ -145,12 +182,30 @@ into real, tested code. Full detail in `docs/ICEBERG_WRITE_BOUNDARY.md`; short v

 ## Sequencing / dependencies

- Items 2, 4, 5 have no hard dependency on another product and can be defined/built inside 0pt
-  today (this repo already owns `sources.yaml` and the QA stage).
- Items 1, 3, 8 are blocked on **ST0RE's table registry** existing.
- Item 6 is blocked on **AUD0** existing as a real evented product.
+*(Status note: this section described the original plan's dependencies. As of the 2026-07-12
+update above, items 1, 2, 3, 5, 6, 7, 8 are built — mock-tested, not live-verified. Item 4
+(data-quality/QA service) is the one item that remains genuinely not-started; see the correction
+callout at the top of this doc. The dependency shape below is kept for the record and because
+"mock-tested" is not the same as "the dependency is resolved" — see each item's status note above
+for what's still actually pending.)*
+
+- Items 2, 4, 5 have no hard dependency on another product and can be defined/built inside 0pt —
+  2 and 5 now are; 4 (the QA service) still is not.
+- Items 1, 3, 8 depended on **ST0RE's table registry** existing. It now exists as real code in
+  `sax3l/st0re`; what remains outstanding is a *live, reachable* `ST0RE_URL` to verify against —
+  no code path in this repo reads `ST0RE_URL` from the environment automatically (same as
+  `CL0UD_URL`/`N0D_URL`/`AUD0_URL` — none of the platform clients have an env fallback wired; a
+  base URL must be passed in explicitly via each service's constructor options). Wiring `ST0RE_URL`
+  alone would not be enough, either: `sax3l/st0re`'s current `main` enforces `X-Tenant-Id`/
+  `X-Actor-Id` headers on the `getTable`/`createSnapshot` routes this write path calls, and this
+  repo's `St0reLakehouseClient` does not send them yet — see `docs/ICEBERG_WRITE_BOUNDARY.md`'s
+  "Real code, not live-verified" section for the full account (found during this verification pass).
+- Item 6 depended on **AUD0** existing as a real evented product; it still does not have a live
+  ingestion endpoint, so the four events fire through `Aud0Client`'s mock/no-op path, same as every
+  other AUD0 emission in this repo.
 - Item 7 assumes N0D's job-request surface (see `n0d` repo) is reachable from 0pt's orchestrator;
-  no such integration exists yet in `services/api` and none is being added by this doc.
+  `IcebergWriteService` calls `N0dClient.createJob`, which — like the other platform clients — has
+  no live `N0D_URL` wired from this repo's environment either.

 ## Explicitly out of scope for 0pt (do not build here)

@@ -0,0 +1,202 @@
+# 12 · Edge-native P0 capability API (Next.js / TypeScript)
+
+This doc did not exist before this pass. It covers the **edge-native TypeScript API surface** — Next.js Route Handlers under `app/api/0pt/*`, plus `app/api/screen/route.ts` and `app/api/ai/parse/route.ts` — as a contract distinct from `docs/04-api.md`'s FastAPI engine (`services/api/orchestrator/main.py`, runs on a VPS). Everything here runs on Vercel. The two layers are **not** the same service, and as of this pass are only partially wired together (`docs/04-api.md` documents one confirmed case where the edge layer calls an engine route that doesn't exist).
+
+Every route below was read directly from source this pass (`app/api/0pt/**/route.ts`, `app/api/screen/route.ts`, `app/api/ai/parse/route.ts`, and their backing `src/services/*.ts` / `src/types/*.ts`). Where a claim below is about *runtime behavior* rather than just the shape of the code (e.g. "this call always fails"), it's derived by tracing the actual code path, not by running it — flagged as such.
+
+## Capability-registry status (verified against `packages/capability-registry/src/registry.ts` in sax3l/cl0ud)
+
+14 distinct `0pt.*` capabilities are registered today. **Every single one has `surfaces` containing only `'api'`** (plus `'job'` for the two heaviest writes), and **`mcpEnabled`/`cliEnabled` are `false` on all 14, with no exception.** Any doc, comment, or assumption that a `siax 0pt ...` CLI or an MCP tool for 0pt already exists is describing a *target*, not current reality.
+
+| Capability | Surfaces | Route(s) below | Notes |
+|---|---|---|---|
+| `0pt.query_source` | `api` | `POST /api/0pt/sources/{sourceId}/query` | riskLevel L2, piiLevel high |
+| `0pt.document_ocr` | `api` | `POST/GET /api/0pt/documents/capture`, `POST/GET /api/0pt/documents/{documentId}/extraction` | riskLevel L2, piiLevel high |
+| `0pt.write_external_record` | `job` **(not `api`)** | none — no HTTP route exists | see "Capabilities with no route" below |
+| `0pt.lakehouse_mapping_manage` | `api` | `POST/GET /api/0pt/lakehouse/mappings`, `GET .../{mappingId}` | riskLevel L2 |
+| `0pt.lakehouse_write` | `api`, `job` | `POST /api/0pt/lakehouse/mappings/{mappingId}/writes` | riskLevel L3 |
+| `0pt.source_rate_policy_manage` | `api` | `POST/GET /api/0pt/sources/rate-policies`, `GET .../{id}` | riskLevel L1 |
+| `0pt.screen_sanctions` | `api` | `GET /api/screen` | riskLevel L2 |
+| `0pt.write_iceberg_table` | `api`, `job` | (invoked internally by `0pt.lakehouse_mapping_manage`/`0pt.lakehouse_write` routes via `IcebergWriteService`) | riskLevel L3, piiLevel high |
+| `0pt.estimate_compute`, `0pt.vehicle_lookup`, `0pt.catalog_list`, `0pt.source_registry_list`, `0pt.order_create`, `0pt.order_payment` | `api` | `app/api/estimates`, `app/api/vehicles`, `app/api/catalog`, `app/api/sources`, `app/api/orders`, `app/api/payments/*` | **not** under `app/api/0pt/` — out of this doc's assigned scope, not read in detail this pass |
+
+`POST /api/ai/parse` has **no entry at all** in the capability registry (grep-verified: no `ai/parse` or `ai_parse` or `ai.parse` string anywhere in `registry.ts`). It is real, working code, but sits entirely outside the capability model — no declared risk level, no audit requirement, no policy gate.
+
+## Routes
+
+### `0pt.document_ocr` — document capture + extraction
+
+**`POST /api/0pt/documents/capture`** — `app/api/0pt/documents/capture/route.ts` → `DocumentCaptureService.captureFromMailbox`
+```
+body: {
+  mailbox: { tenant_id, client_id, client_secret, mailbox_address, folder },  -- Microsoft Graph / Entra creds for the mailbox itself
+  since_iso?, top?, max_pages?,
+  tenant_id, project_id, actor_id, correlation_id                            -- SIAX platform scoping (unrelated to mailbox.tenant_id above)
+}
+-> 201 { scanned_messages, captured_documents: DocumentRecord[], errors: string[] }
+-> 400 { error } on missing/invalid mailbox creds or missing tenant_id/project_id/actor_id
+```
+Note the naming collision: `body.mailbox.tenant_id` is the **Microsoft 365 / Entra tenant** the mailbox lives in; `body.tenant_id` is the **SIAX platform tenant**. Same field name, two unrelated identifiers, both required, both plain strings in the request body.
+
+Polls the mailbox via Microsoft Graph (app-only), downloads PDF attachments, writes bytes to `LocalBlobStore` (`src/adapters/local-blob-store.ts` — an explicitly-marked **interim local-disk store**, because `st0re-client.ts` only registers artifact *metadata* today and has no real bytes-upload endpoint yet), registers the artifact with ST0RE (mock client — see "Mock-only platform clients" below), and enqueues an N0D job placeholder for extraction.
+
+**`GET /api/0pt/documents/capture`** — same file → `DocumentCaptureService.listDocuments`
+```
+query: ?tenant_id=&project_id=  (both optional filters)
+-> 200 DocumentRecord[]
+```
+
+**`POST /api/0pt/documents/{documentId}/extraction`** — `app/api/0pt/documents/[documentId]/extraction/route.ts` → `DocumentExtractionService.extractDocument`
+```
+body: { tenant_id, project_id, actor_id, correlation_id, model_id }
+-> 201 DocumentExtractionRecord
+-> 501 { error } if Document Intelligence is not configured (missing DOC_INTELLIGENCE_ENDPOINT/DOC_INTELLIGENCE_KEY) — "refusing to fabricate a result"
+-> 403 { error } if CL0UD policy denies
+-> 409 { error } if CL0UD policy requires approval
+-> 404 { error } if the document doesn't exist
+-> 400 { error } for any other failure (e.g. missing model_id)
+```
+Corrected in `fix/0pt-full-bug-hunt` (PR #5, merged separately): previously every one of the above collapsed into a blanket 400, which made "not configured" indistinguishable from "bad request" from the caller's side. Now status-mapped, matching the convention already used by `app/api/0pt/sources/[sourceId]/query/route.ts`.
+Every field in the response is evidence-based: a field is only populated when Azure Document Intelligence actually returned it, always carrying DI's own confidence; not-found fields are `{value: null, confidence: ..., found: false}`, never guessed. This is enforced twice (adapter + service layer) per the file's own doc comment.
+
+**`GET /api/0pt/documents/{documentId}/extraction`** — same file → `DocumentExtractionService.listExtractionsForDocument`
+```
+-> 200 DocumentExtractionRecord[]
+-> 404 { error } on any thrown error (including errors unrelated to "not found" — the route maps every exception here to 404)
+```
+
+**This pair actually works end-to-end**, unlike the routes below — `documentCaptureService` and `documentExtractionService` are both exported as **module-level singletons** (`src/services/document-capture-service.ts` / `document-extraction-service.ts`) specifically so the extraction route can see documents the capture route created in the same process. This is the one place in `app/api/0pt/*` that got the shared-instance pattern right.
+
+### `0pt.lakehouse_mapping_manage` / `0pt.lakehouse_write` — Iceberg write path
+
+**`POST /api/0pt/lakehouse/mappings`** — `app/api/0pt/lakehouse/mappings/route.ts` → `IcebergWriteService.mapDatasetToIcebergTable`
+```
+body: { tenant_id, project_id, dataset_id, dataset_iceberg_mapping_id, namespace, table_name, storage_uri, catalog_ref, table_format?, actor_id, correlation_id }
+-> 201 { mapping: DatasetIcebergMapping, iceberg_table_id, policy_decision_id }
+-> 400 { error }
+```
+**`GET /api/0pt/lakehouse/mappings`** — same file → `DatasetIcebergMappingService.listMappings`
+```
+query: ?tenant_id=&project_id=&dataset_id=
+-> 200 DatasetIcebergMapping[]
+```
+**`GET /api/0pt/lakehouse/mappings/{mappingId}`** — separate file, `.../[mappingId]/route.ts` → `DatasetIcebergMappingService.getMapping`
+```
+-> 200 DatasetIcebergMapping
+-> 404 { error }
+```
+**`POST /api/0pt/lakehouse/mappings/{mappingId}/writes`** — separate file, `.../[mappingId]/writes/route.ts` → `IcebergWriteService.requestIcebergWrite`
+```
+body: { actor_id, correlation_id, snapshot_type?, schema_version, manifest_uri, record_count?, size_bytes?, heavy? }
+-> 202 { snapshot_id, iceberg_table_id, policy_decision_id, n0d_job_id? }
+-> 400 { error }
+```
+
+> **Confirmed this pass — the POST above still always fails, though one of its two root causes is now fixed:**
+> `mapDatasetToIcebergTable`'s first line is `await this.datasetService.getDataset(input.dataset_id)`, which throws `Dataset {id} not found` unless the dataset was already registered. `DatasetService.registerDataset` is **never called from any route in this repo** (grep-verified across `app/` and `src/`) — there is no `POST /api/0pt/datasets` route, despite `app/api/0pt/route.ts`'s own index claiming `/api/0pt/datasets` exists (it doesn't — see "The `/api/0pt` index is wrong" below). So **every call to `POST /api/0pt/lakehouse/mappings` throws `Dataset {id} not found`, unconditionally, regardless of input**, because no HTTP path can ever get a dataset into the registry first. This half is still open — whether to add `POST /api/0pt/datasets`/`POST /api/0pt/sources` routes is a scope decision, not a mechanical fix.
+>
+> **Fixed in `fix/0pt-full-bug-hunt` (PR #5, merged separately):** the three route files above previously each constructed their own separate instance of the relevant service — `.../[mappingId]/route.ts` had a second, independent `DatasetIcebergMappingService`, and `.../[mappingId]/writes/route.ts` had a third `IcebergWriteService` with its own fresh internal `DatasetIcebergMappingService`, so a mapping created via `POST /api/0pt/lakehouse/mappings` was invisible to both sibling routes even setting the dataset-registration issue aside. All three route files now import shared `datasetService`/`mappingService`/`writeService` singletons from `src/services/lakehouse-mapping-registry.ts` instead. This alone does not make the write path succeed end-to-end — the dataset-registration gap above still blocks it — but it removes a second, independent failure mode.
+
+### `0pt.source_rate_policy_manage` — source rate policies
+
+**`POST /api/0pt/sources/rate-policies`** — `app/api/0pt/sources/rate-policies/route.ts` → `SourceRatePolicyService.createSourceRatePolicy`
+```
+body: CreateSourceRatePolicyInput { source_rate_policy_id, tenant_id, project_id, source_id, rate_limit_per_minute, crawl_budget, compliance_notes?, domain?, robots_ok?, access?, status?, correlation_id?, created_by? }
+-> 201 SourceRatePolicy
+-> 400 { error }
+```
+**`GET /api/0pt/sources/rate-policies`** — same file → `SourceRatePolicyService.listSourceRatePolicies`
+```
+query: ?tenant_id=&project_id=&source_id=
+-> 200 SourceRatePolicy[]
+```
+**`GET /api/0pt/sources/rate-policies/{sourceRatePolicyId}`** — separate file → `SourceRatePolicyService.getSourceRatePolicy`
+```
+-> 200 SourceRatePolicy
+-> 404 { error }
+```
+
+> **Confirmed this pass — the POST above always fails too, same root cause as lakehouse mappings:** `createSourceRatePolicy` checks `sourceService.getSource(input.source_id)` before creating the policy, and throws `Source {id} not found` otherwise. `SourceService.createSource` is **never called from any route in this repo** — there is no `POST /api/0pt/sources` route (see next section). **Every call to `POST /api/0pt/sources/rate-policies` throws `Source {id} not found`, unconditionally.** The `.../{sourceRatePolicyId}` GET route also constructs its own separate `SourceRatePolicyService` instance, independent of `.../rate-policies/route.ts`'s — so even a hypothetically-successful create wouldn't be visible there either.
+
+### `0pt.query_source` — bounded synchronous query
+
+**`POST /api/0pt/sources/{sourceId}/query`** — `app/api/0pt/sources/[sourceId]/query/route.ts` → `SourceQueryService.querySource`
+```
+body: { query (required, non-empty string), params?, tenant_id (required), project_id (required), actor_id?, correlation_id?, max_rows?, timeout_ms?, connection_config (required — FabricOneLakeConnectionConfig: {credentials:{tenantId,clientId,clientSecret}, sqlEndpoint, database, scope?, requestTimeoutMs?}) }
+-> 200 { source_id, rows, row_count, truncated, duration_ms, bounds:{max_rows,timeout_ms} }
+-> 400 { error } (missing query/tenant_id/project_id/connection_config)
+-> 404 { error } (source not found)
+-> 422 { error } (SourceQueryUnsupportedError — wrong source_type or adapter_id)
+-> 504 { error } (SourceQueryTimeoutError)
+```
+The route's **own inline comment already documents the in-memory-isolation gap** for this route: *"a source registered via `POST /api/0pt/sources` will not be resolvable here until `SourceService` is backed by shared persistence."*
+
+> **Two things worth adding to what that comment says:**
+> 1. **There is no `POST /api/0pt/sources` route in this repo at all.** The comment describes a route that does not exist as a file anywhere under `app/api/` (verified — only `sources/rate-policies*` and `sources/[sourceId]/query` exist under `app/api/0pt/sources/`; the *non*-`0pt`-prefixed `app/api/sources/route.ts` is a completely different, `GET`-only, hardcoded 9-entry list — the `dim_source` transparency-moat catalog described in `docs/03-data-model.md` and `docs/04-api.md`, not a per-tenant `Source` registry). So this isn't "not yet resolvable across processes" — it's "there is currently no way, via any HTTP endpoint, to create a `Source` at all." `SourceService.createSource` is only ever called from tests.
+> 2. Even with a `Source` registered directly in code, the only supported adapter (`adapter_id: "fabric_onelake_sql"`) depends on the `mssql` npm package, which **is not in `package.json`** as of this pass (`src/adapters/fabric-onelake-adapter.ts`'s own header comment: deliberately not added yet to avoid colliding with a separate in-flight session's `package.json` changes). `query()` throws a clear, explicit error until `mssql` is installed — by design, not silently.
+>
+> Net effect: **`POST /api/0pt/sources/{sourceId}/query` cannot succeed against any HTTP-only workflow today**, for two independent, stacked reasons — no way to register a `Source`, and no query driver installed even if one existed.
+
+### `0pt.write_external_record` — no route exists
+
+`src/services/external-writeback-service.ts` is real, tested TypeScript (`tests/p0/external-writeback-service.test.ts`) implementing "POST a validated, already-approved structured record to a registered external-system adapter" (worked example: Odoo Vendor Bill via `src/adapters/odoo-bills-adapter.ts`). The capability registry itself documents this plainly: `surfaces: ['job']`, `apiEnabled: false`, with a comment noting it's "invoked today only via direct import, not yet wired to a live surface." There is no `app/api/0pt/*` route for it. Not part of this doc's route list because there is no route to document.
+
+### The `/api/0pt` index is materially wrong
+
+`GET /api/0pt` (`app/api/0pt/route.ts`) returns a static `endpoints` array as self-documentation:
+```
+["/api/0pt/sources", "/api/0pt/datasets", "/api/0pt/data-contracts",
+ "/api/0pt/quality/checks", "/api/0pt/quality/reports", "/api/0pt/features/views",
+ "/api/0pt/documents/capture", "/api/0pt/documents/{documentId}/extraction"]
+```
+**Of these 8 listed paths, only 2 exist** (`documents/capture`, `documents/{documentId}/extraction`). The other 6 — `sources`, `datasets`, `data-contracts`, `quality/checks`, `quality/reports`, `features/views` — have no corresponding route file anywhere in this repo. `quality/checks` and `quality/reports` in particular line up exactly with the confirmed-fabricated quality-check-service work described elsewhere in this doc corpus (CLAUDE.md → README "Known issues") — this index was apparently written against a planned surface, not the real one. Conversely, **6 routes that do exist are missing from this list entirely**: `lakehouse/mappings` (×3) and `sources/rate-policies` (×2), plus `sources/{sourceId}/query`. This file is outside this doc's assigned scope to edit (not one of `docs/03-data-model.md`/`docs/04-api.md`) — flagging it here since it's the most visible, single-request way a caller would discover this API's shape, and it's currently misleading.
+
+### `0pt.screen_sanctions` — `GET /api/screen`
+
+```
+GET /api/screen?q=<name>
+-> 200 { matches: [] }                                    if q is empty
+-> 200 (engine response, verbatim)                          if ENGINE_URL is set and reachable and engine returns ok
+-> 200 { source: "opensanctions", matches: [{name, score, schema}] }   direct OpenSanctions fallback
+-> 200 { matches: [], source: "opensanctions" }             on fetch failure or non-2xx
+```
+Calls `engineFetch('/screen?q=...')` first (`services/api/orchestrator/main.py`'s real `GET /screen` route — see `docs/04-api.md`), falls back to `api.opensanctions.org` directly otherwise. Unlike `/api/ai/parse` below, this fallback path is a **working** reconciliation between the edge and engine layers, not a silent bug — both paths return the same shape. Comment in the route itself: "VERIFY commercial terms before production volume" — not verified by this pass either.
+
+### `POST /api/ai/parse` — no capability mapping, engine call silently no-ops
+
+```
+body: { text }
+-> 200 (engine response, verbatim)          if ENGINE_URL set, reachable, and engine returns ok
+-> 200 { config: {...}, rationale, heuristic: true }   local keyword-heuristic fallback otherwise
+-> 400 { error } if text is empty
+```
+As documented in `docs/04-api.md`: `services/api/orchestrator/main.py` **has no `/ai/parse` route at all**, so `engineFetch("/ai/parse", ...)` always 404s and this route always falls through to its local heuristic (`MARKETS`/`SERVICE`/`FIELDS`/`DEST` regex tables in the route file itself), even when the engine is up and configured. Not a crash — just a permanently-dark code path (`if (eng && eng.ok)` is never true for this one route). Has no entry in the capability registry (see top of this doc) — no declared risk level, audit requirement, or policy gate, unlike every other route documented above.
+
+## Cross-cutting gap 1: tenant_id read from the request body, not a session
+
+**Hard platform rule (per this doc corpus's platform-wide conventions): `tenant_id` must be server-bound to an authenticated session, never read from client request body/query/header.** This is violated, today, in:
+
+- `app/api/0pt/lakehouse/mappings/route.ts` (POST body `tenant_id`/`project_id`)
+- `app/api/0pt/lakehouse/mappings/[mappingId]/writes/route.ts` (indirectly — `actor_id`/`correlation_id` from body feed into a call keyed off a mapping whose own `tenant_id` was set by the equally-unauthenticated POST above)
+- `app/api/0pt/sources/rate-policies/route.ts` (POST body `tenant_id`/`project_id`)
+- `app/api/0pt/sources/[sourceId]/query/route.ts` (POST body `tenant_id`/`project_id`, explicitly required — 400 if missing)
+- `src/services/document-capture-service.ts` (`captureFromMailbox`'s `ctx.tenant_id` comes straight from `app/api/0pt/documents/capture/route.ts`'s request body; the sibling `GET` route also takes `tenant_id`/`project_id` as **query-string filters**, which is a softer version of the same problem — it doesn't enforce isolation, it just optionally filters an already-unscoped in-memory list)
+
+This is **not** a deliberate two-tier design choice — it exists because **no authentication or session system exists anywhere in this repo yet** (see `app/api/orders/route.ts`'s own `GET` handler, which has the literal comment "org scoping added with auth" — i.e., not yet; and `docs/09-build-plan.md` Phase 3, which is where auth is planned, not built). Building that auth design is explicitly Simon's call — this doc doesn't invent one. Until it lands, any caller can claim to be any `tenant_id` on every route above.
+
+## Cross-cutting gap 2: in-memory-only persistence, and worse
+
+Every service backing `app/api/0pt/*` (`SourceService`, `DatasetService`, `DatasetIcebergMappingService`, `SourceRatePolicyService`, `DocumentCaptureService`, `DocumentExtractionService`) stores state in a plain in-memory `Map` — nothing survives a process restart, and (per the findings above) in most cases nothing is even shared *across route files within the same running process*, because each route file constructs its own fresh service instance rather than importing a shared singleton. The one exception is `documentCaptureService`/`documentExtractionService`, which are correctly exported as module-level singletons for exactly this reason.
+
+Two SQL tables exist for two of these seven types (`opt_dataset_iceberg_mappings`, `opt_source_rate_policies` — `sql/004_iceberg_write_boundary.sql`), but nothing in `app/api/0pt/*` reads or writes through Postgres — the routes only ever touch the in-memory `Map`s. See `docs/03-data-model.md` for the full SQL-side picture, including a confirmed broken foreign-key reference in that same migration file.
+
+## Mock-only platform clients
+
+`SourceService`, `DocumentCaptureService`, `DocumentExtractionService`, `IcebergWriteService`, and `DatasetIcebergMappingService` all construct CL0UD/N0D/AUD0/ST0RE clients (`src/clients/{cl0ud,n0d,aud0,st0re,st0re-lakehouse}-client.ts`) via `createXClient(baseUrl?)` with no `baseUrl` ever passed by any route in this repo. `createXClient` returns a deterministic in-memory mock whenever `baseUrl` is falsy (verified in each client file), and **no route or service anywhere reads `CL0UD_URL`/`N0D_URL`/`AUD0_URL`/`ST0RE_URL` from `process.env`** (grep-verified this pass, zero hits outside comments and the `it.todo` in `tests/p0/iceberg-write-service.test.ts` — this corrects an earlier version of this section, which claimed `ST0RE_URL` *is* read by the two ST0RE clients; it is not, matching README's "Known issues" #2, `docs/02-architecture.md`'s "Platform clients" section, `docs/08-infrastructure.md`'s "Platform-client URLs" section, and `docs/ICEBERG_WRITE_BOUNDARY.md`'s "Verification status" section, all independently verified against the same grep). None of the five clients has an env fallback wired at all — every one requires an explicit `baseUrl`/`st0reBaseUrl` constructor argument that nothing in this repo ever supplies. Practically: every policy check (`cl0ud.evaluatePolicy`) always returns whatever the mock's canned decision is, and every audit event (`aud0.ingestEvent`) is a no-op that never leaves the process. This is real, typechecked, tested code — not a stub file — but it has never been exercised against a live CL0UD/N0D/AUD0/ST0RE instance from this repo.
+
+## Open questions for Simon
+
+- Should `app/api/0pt/route.ts`'s index be fixed to list real routes, or is a stale/aspirational index acceptable short-term? (Not this doc's file to edit.)
+- Should a `POST /api/0pt/sources` (and `POST /api/0pt/datasets`) route be added so `Source`/`Dataset` registration is reachable at all over HTTP — this is the blocking prerequisite for `0pt.query_source`, `0pt.source_rate_policy_manage`, and `0pt.lakehouse_mapping_manage` to ever succeed via the API as currently wired?
+- Should the in-memory registry services (`SourceService`, `DatasetService`, etc.) move to shared singletons (like `documentCaptureService`) as an interim fix, or wait for real Postgres-backed persistence?
+- Whether/when `mssql` gets added to `package.json` so the `fabric_onelake_sql` adapter can actually run.
@@ -6,6 +6,24 @@ says exactly what in this pass is real code vs. contract-only, matching the hone
 already used across this SIAX effort (e.g. sax3l/act0's own client docs, sax3l/st0re's
 PRODUCTION_READINESS.md).

+> **Correction (documentation-accuracy pass).** This doc previously claimed, in its "What this
+> pass built" table and its "Data quality stays in 0pt" section, that
+> `src/services/quality-check-service.ts`, `src/services/quality-report-service.ts`,
+> `src/types/quality-check.ts`, and `src/types/quality-report.ts` were real, tested files that this
+> pass "did not modify." **That was fabricated.** `git log --all` for every one of those paths,
+> plus `sql/002_p0_dataset_quality.sql` and `sql/003_*.sql`, returns zero commits on any branch
+> (`main`, `feature/0pt-env-example`, `ci/add-quality-gate`) -- these files have never existed in
+> this repository. 0pt's data-quality/QA stage is a **design spec only**
+> (`docs/06-data-engine.md` §QA), not a built service. See "Data quality: not yet built" below for
+> the corrected account. This doc's own "Verification status" section also previously stated the
+> full test suite was "154 tests + 1 todo (142-test baseline)" -- that count could not be
+> reproduced when re-verified this pass (see below for the actual current count, and note this
+> repo's test suite is a moving target across sessions, so treat any test count in this doc corpus
+> as a snapshot at time of writing, not a durable fact). Everything else in this doc describing the
+> ST0RE-owns-catalog / 0pt-owns-writes-and-source-rate-policy / N0D-executes boundary was
+> independently re-verified against the actual service/client/test files this pass and remains
+> accurate.
+
 ## The boundary, plainly

 - **ST0RE owns table/catalog/artifact metadata for the lakehouse.** The Iceberg catalog, table
@@ -13,10 +31,12 @@ PRODUCTION_READINESS.md).
  `src/api/routes/lakehouse.ts`, `/v1/st0re/lakehouse/*`). 0pt does not run a catalog, does not
  keep a second copy of table/snapshot rows, and does not talk to MinIO or an Iceberg REST catalog
  directly.
- **0pt owns dataset production, quality, data contracts, and writes.** 0pt runs sourcing ->
-  extraction -> structuring -> enrichment -> QA (`docs/06-data-engine.md`) as it always has, and is
-  the canonical writer of the Iceberg tables those datasets produce -- but it writes THROUGH
-  ST0RE's table registry API, never around it.
+- **0pt owns dataset production, quality, data contracts, and writes.** This is the target
+  ownership split (matches ADR-0030 verbatim) and the writes/mapping half of it is real, tested
+  code -- see "What this pass built" below. The **quality** half is not: 0pt's QA stage is
+  currently a design spec only (`docs/06-data-engine.md` §QA), with no dedicated implementation in
+  this repo -- see "Data quality: not yet built" below. 0pt is the canonical writer of the Iceberg
+  tables those datasets produce, and it writes THROUGH ST0RE's table registry API, never around it.
 - **0pt owns source-rate/crawl-compliance policy.** This is the genuine ownership repair this pass
  makes concrete: `0pt.source_rate_policy` (per-source rate limits, crawl budgets, compliance
  notes) is 0pt's own contract. It does not exist in, and must not be reintroduced into, N0D's
@@ -44,9 +64,10 @@ PRODUCTION_READINESS.md).
 | ST0RE lakehouse HTTP/mock client | `src/clients/st0re-lakehouse-client.ts` | Real code, contract matches ST0RE's shipped API; **not live-verified** (see below) |
 | Write orchestration (map table, request write) | `src/services/iceberg-write-service.ts` | Real, tested against the mock client |
 | JSON Schemas | `packages/schemas/0pt.dataset_iceberg_mapping.schema.json`, `packages/schemas/0pt.source_rate_policy.schema.json` | Real |
-| Postgres migration | `sql/004_iceberg_write_boundary.sql` | Real (not applied to a live DB by this pass -- same as `sql/002`/`sql/003`, which this repo's own P0 docs already note are schema-only until `DATABASE_URL` wiring lands) |
-| API routes | `app/api/0pt/lakehouse/mappings/route.ts` (+`[mappingId]`, `+writes`), `app/api/0pt/sources/rate-policies/route.ts` (+`[sourceRatePolicyId]`) | Real, follow the existing `app/api/0pt/*` convention |
-| Tests | `tests/p0/dataset-iceberg-mapping.test.ts`, `tests/p0/source-rate-policy.test.ts`, `tests/p0/iceberg-write-service.test.ts` | Real, all passing (`pnpm test`); one explicit `it.todo` for the live-ST0RE case |
+| Postgres migration | `sql/004_iceberg_write_boundary.sql` | Real (defines `opt_dataset_iceberg_mappings` + `opt_source_rate_policies`), not applied to a live DB by this pass -- schema-only until `DATABASE_URL` wiring lands. **Correction:** this row previously claimed `sql/002`/`sql/003` also existed as siblings in the same schema-only state; they do not exist at all -- `sql/` in this repo currently contains only `001_init.sql` and `004_iceberg_write_boundary.sql` (verified this pass). `sql/002_p0_dataset_quality.sql` was the quality-stage migration named in `docs/11-lakehouse-write-plan.md`'s original (fabricated) claim; it was never written. |
+| API routes | `app/api/0pt/lakehouse/mappings/route.ts` (+`[mappingId]`, `+writes`), `app/api/0pt/sources/rate-policies/route.ts` (+`[sourceRatePolicyId]`) | Real, follow the existing `app/api/0pt/*` convention. **Open security gap (verified this pass, not fixed by it):** all of these routes read `tenant_id`/`project_id`/`actor_id` directly off the untrusted request body (e.g. `mappings/route.ts`'s `POST`, `rate-policies/route.ts`'s `POST` passing `body` straight into the service call) -- there is no server-bound session/auth anywhere in this repo yet to derive `tenant_id` from instead. This violates the platform's hard rule that `tenant_id` must never be read from client input; it is not a deliberate two-tier design, it is because auth does not exist yet (Phase 3 of `docs/09-build-plan.md`, not built). Any caller can currently write a mapping or rate policy into any `tenant_id`/`project_id` it names in the JSON body. |
+| Data quality / QA service | -- (does not exist) | **NOT BUILT.** See "Data quality: not yet built" below. |
+| Tests | `tests/p0/dataset-iceberg-mapping.test.ts`, `tests/p0/source-rate-policy.test.ts`, `tests/p0/iceberg-write-service.test.ts` | Real, all passing (`npx vitest run`; 4 + 4 + 5-with-1-todo tests respectively) |

 ## 2026-07-13 update: live verification + field-level gap closure

@@ -98,22 +119,63 @@ end to end against production ST0RE, then closed every gap that surfaced:

 ## Verification status (real vs. contract-only -- read this before trusting any claim above)

- **Real and tested**: every TypeScript file above typechecks (except the one pre-existing,
-  unrelated `quality-report-service.ts` error noted above) and its behavior is exercised by a
-  passing vitest test in `tests/p0/`. The full suite (`pnpm test`) passed at 154 tests + 1 todo
-  after the first pass, up from a 142-test baseline before it, with 0 failures; the 2026-07-13 pass
-  above brought it to 155 passed, 0 failed, 0 todo, with the live ST0RE path now actually exercised.
- **Live-verified as of 2026-07-13** (supersedes the "not live-verified" note the first pass left
-  here): `src/clients/st0re-lakehouse-client.ts`'s HTTP path was executed against a running,
-  reachable ST0RE instance (`api.st0re.siax.io`) by a later pass -- not just written against the
-  documented contract. Real IDs it created are listed in the "2026-07-13 update" section above. Unit
-  tests still exercise the deterministic in-memory mock for speed/hermeticity (same convention
+- **Real and tested**: every TypeScript file above typechecks and its behaviour is exercised by a
+  passing vitest test in `tests/p0/`.
+
+  **On test counts -- both remotes' claims are preserved here, and neither should be trusted as a
+  standing fact.** The Gitea line claimed "154 tests + 1 todo, up from a 142-test baseline", then
+  "155 passed, 0 failed, 0 todo" after the 2026-07-13 live pass. The GitHub line re-ran the suite
+  and could **not** reproduce those numbers, measuring instead "13 test files, 88 passed + 1 todo
+  (89 total), 0 failures", and flagged as **unresolved** whether the repo genuinely had 154 tests
+  at an earlier point and lost coverage, or whether the earlier figure was inflated. The two lines
+  were measuring two genuinely different trees (Gitea's carried the P0/live-infra work GitHub's did
+  not, and vice versa), which is enough on its own to explain a large part of the gap -- but it does
+  not retire the open question. Treat any specific test count anywhere in this doc corpus as a
+  snapshot of one tree at one moment, and re-run `pnpm test` yourself before relying on one. The
+  number measured on the unified tree is recorded in the branch/PR that produced this merge.
+
+- **Live-verified as of 2026-07-13, and this supersedes the "would 400 outright" finding below**:
+  `src/clients/st0re-lakehouse-client.ts`'s HTTP path was executed against a running, reachable
+  ST0RE instance (`api.st0re.siax.io`) -- not just written against the documented contract. Real IDs
+  it created are listed in the "2026-07-13 update" section above. Unit tests still exercise the
+  deterministic in-memory mock for speed/hermeticity (same convention
  `cl0ud-client.ts`/`n0d-client.ts`/`aud0-client.ts`/`st0re-client.ts` use); only
  `tests/p0/iceberg-write-service.realinfra.test.ts` hits the real HTTP path, and only when ST0RE is
  reachable (honest skip otherwise).
+
+  **Retained from the parallel GitHub-side verification pass, now RESOLVED -- kept because the
+  reasoning is worth having on record:** that pass found, against the then-current GitHub tree, that
+  the HTTP path "would currently fail outright, not just untested, if pointed at a live ST0RE".
+  `sax3l/st0re` had moved past commit `9ea0abb`; commit `06d30a6` (a 2026-07-13 cross-tenant
+  security fix, `docs/SECURITY_CROSS_TENANT_LAKEHOUSE_FIX.md` in that repo) made
+  `GET /v1/st0re/lakehouse/tables/:tableId` and
+  `POST /v1/st0re/lakehouse/tables/:tableId/snapshots` call `requireRequestContext`
+  (`src/api/context.ts`), which throws a 400 `ST0RE_VALIDATION_ERROR` unless the caller sends both
+  `X-Tenant-Id` and `X-Actor-Id`. That tree's `HttpSt0reLakehouseClient.getTable`/`.createSnapshot`
+  sent only `Content-Type`. **The Gitea-side 2026-07-13 pass had already fixed exactly this**, by
+  threading a `St0reRequestContext` (both headers) through every client method -- and that fix is
+  the version present after this unification merge. Verify with a grep for `X-Tenant-Id` in
+  `src/clients/st0re-lakehouse-client.ts` before trusting either statement again.
+
+  **Still true and NOT fixed by either side -- the client factories do not read the environment:**
+  none of the five factory functions (`createSt0reLakehouseClient`, `createSt0reClient`,
+  `createCl0udClient`, `createN0dClient`, `createAud0Client`) reads a base URL from `process.env`
+  itself -- grep-verified, zero hits for `process.env.ST0RE_URL`/`CL0UD_URL`/`N0D_URL`/`AUD0_URL` in
+  any client or service file. Each only accepts an optional `baseUrl` constructor argument, and
+  nothing in `app/api/0pt/*` passes one in, so **every route in this repo runs on the in-memory
+  mock/no-op regardless of what is set in the environment.** `.env.example` naming `ST0RE_URL` etc.
+  describes the *convention name to wire up*, not something already read automatically. This is the
+  same maturity level as this repo's other mock-only platform clients
+  (`src/services/document-extraction-service.ts`, `src/services/external-writeback-service.ts` are
+  accurate examples); an earlier version of this paragraph pointed at
+  `src/services/quality-check-service.ts` as the peer example -- that file does not exist, see the
+  correction callout at the top of this doc.
+
 - **No longer an open TODO**: the `it.todo(...)` line this section used to point to
  (`tests/p0/iceberg-write-service.test.ts`) has been replaced by the real
-  `tests/p0/iceberg-write-service.realinfra.test.ts` described above.
+  `tests/p0/iceberg-write-service.realinfra.test.ts` described above, which constructs
+  `IcebergWriteService({ st0reBaseUrl: process.env.ST0RE_URL })` -- note that this is the test
+  wiring `ST0RE_URL` explicitly, not the client reading it, per the paragraph above.
 - **Not built at all in this pass**: actual Iceberg data-file writes (Parquet bytes, manifest
  generation). `IcebergWriteService.requestIcebergWrite` registers a snapshot POINTER through
  ST0RE (`manifestUri`, `recordCount`, `sizeBytes` supplied by the caller) -- it does not produce
@@ -126,28 +188,41 @@ end to end against production ST0RE, then closed every gap that surfaced:

 ## A test collision this pass found and fixed

-`tests/p0/enterprise-data-os-expansion.test.ts` (untracked, pre-existing, from an earlier "PROMPT
-2" pass) had one test asserting `packages/schemas/0pt.source_rate_policy.schema.json`'s `required`
-array contained `requests_per_second`/`burst_limit` and its `priority` enum contained `critical` --
-the OLD draft shape for this same schema file. This pass's canonical fields
+`tests/p0/enterprise-data-os-expansion.test.ts` (from an earlier "PROMPT 2" pass; both this file
+and `packages/schemas/0pt.iceberg_table.schema.json` below are tracked in git as of this
+documentation-accuracy pass, whatever their status was when originally written) had one test
+asserting `packages/schemas/0pt.source_rate_policy.schema.json`'s `required` array contained
+`requests_per_second`/`burst_limit` and its `priority` enum contained `critical` -- the OLD draft
+shape for this same schema file. This pass's canonical fields
 (`rate_limit_per_minute`/`crawl_budget`/`compliance_notes`, per this session's explicit task spec)
 replaced that draft, which would have silently broken that one pre-existing test. Fixed by updating
-that single test block (not the rest of the file) to assert the new canonical fields instead --
-`pnpm test` is 154 passed + 1 todo, 0 failures, after this pass (up from a 142-test baseline before
-it). See that test file's inline comment for the same note.
+that single test block (not the rest of the file) to assert the new canonical fields instead. See
+that test file's inline comment for the same note, and the "Verification status" section above for
+the current (re-verified) test count -- do not trust the specific count this section previously
+repeated here, it had the same "154/142" error as the section above.

-## A pre-existing artifact this pass did not touch
+## A pre-existing artifact -- update: since documented, not still untouched

-`packages/schemas/0pt.iceberg_table.schema.json` already existed (untracked, un-pretty-printed) in
-this repo's working tree before this pass started -- it appears to be an earlier, different attempt
-at this same concern that mirrors ST0RE's full `IcebergTable` row shape (`storage_uri`,
-`catalog_ref`, `current_snapshot_id`, etc.) rather than a lightweight reference. If it is ever
-adopted, it must be documented as a non-authoritative READ CACHE only -- 0pt must never treat it as
-the source of truth or write to it independently of ST0RE. This pass's actual, owned contract is
-`0pt.dataset_iceberg_mapping.schema.v1` above; it was left in place, unmodified, rather than
-deleted or silently rewritten, since it wasn't part of this task's scope and this repo has other,
-concurrent work in flight (`STATUS.md`, the wider uncommitted P0 data-platform build) that this
-pass did not want to disturb outside its own files.
+`packages/schemas/0pt.iceberg_table.schema.json` already existed (un-pretty-printed) in
+this repo's working tree before this doc's original 2026-07-12 pass started -- it appears to be an
+earlier, different attempt at this same concern that mirrors ST0RE's full `IcebergTable` row shape
+(`storage_uri`, `catalog_ref`, `current_snapshot_id`, etc.) rather than a lightweight reference.
+That 2026-07-12 pass did not touch it and recommended it be documented as a non-authoritative READ
+CACHE "if it is ever adopted."
+
+**Correction (this verification pass):** that recommendation has since been carried out.
+`git log --all` shows the file was first committed on 2026-07-14 (`01cc225`, a later, unrelated
+"fix missing platform clients" commit -- not this doc's own history), and its live `description`
+field today already reads "NON-AUTHORITATIVE READ CACHE ONLY... 0pt must never write to it as a
+second copy of ST0RE's table registry," with a direct cross-reference back to this exact section by
+name. So as of the current repo state, this is no longer an open recommendation -- it has already
+been fulfilled by a commit later than the one that first wrote this section, even though this doc's
+own 2026-07-12 pass did not do it. This pass's actual, owned contract remains
+`0pt.dataset_iceberg_mapping.schema.v1` above -- `0pt.iceberg_table.schema.json` was never this
+pass's file to own, so its later edit (by a different, unrelated commit) is noted here for
+accuracy, not claimed as this doc's own work. This repo has other, concurrent work in flight
+(`STATUS.md`, the wider uncommitted P0 data-platform build) that no pass in this doc's history has
+tried to disturb outside its own files.

 ## Event names (all four wired, docs/11 item 6)

@@ -161,11 +236,48 @@ pass did not want to disturb outside its own files.
 All four go through the existing `Aud0Client` (`src/clients/aud0-client.ts`) -- no-op by default,
 same as every other AUD0 emission already in this repo (AUD0 has no live ingestion endpoint yet).

-## Data quality stays in 0pt (confirmed, not moved)
+## Data quality: not yet built (corrected -- previously misstated as real and tested)

-This pass did not modify `src/services/quality-check-service.ts`, `src/services/quality-report-service.ts`,
-`src/types/quality-check.ts`, or `src/types/quality-report.ts`. 0pt's QA stage
-(`docs/06-data-engine.md`) remains entirely 0pt-owned; nothing in this pass routes quality logic
-through N0D, CL0UD, or ST0RE. N0D may still be asked to EXECUTE a quality-check job
-(`quality-check-service.ts`'s existing `n0d.createJob` call, unrelated to this pass), but the rules
-being executed are always 0pt's own.
+**This section previously read "Data quality stays in 0pt (confirmed, not moved)" and stated that
+this pass "did not modify `src/services/quality-check-service.ts`,
+`src/services/quality-report-service.ts`, `src/types/quality-check.ts`, or
+`src/types/quality-report.ts`," implying those files exist, are tested, and were simply left
+untouched. That was a fabrication.**
+
+Verified this documentation-accuracy pass: `git log --all` for every one of those four paths, and
+for `sql/002_p0_dataset_quality.sql` / `sql/003_*.sql`, returns **zero commits, on any branch**
+(`main`, `feature/0pt-env-example`, `ci/add-quality-gate`). None of these files have ever existed
+in this repository's history. There is no `src/services/quality-check-service.ts`, no
+`src/services/quality-report-service.ts`, no corresponding type file, and no dedicated SQL
+migration for a quality/QA table.
+
+What actually exists:
+
+- **A design spec only**, in `docs/06-data-engine.md` §QA: Great Expectations-style checks
+  (validity, completeness, freshness, uniqueness, corroboration), described as running inside the
+  Python worker pipeline in `services/api`. This is a target description, not implemented code.
+- **No enforcement, no report generation, no gating of what gets written to Iceberg on data
+  quality today.** `IcebergWriteService.requestIcebergWrite` (the actual write path this doc
+  documents) does not call, reference, or depend on any quality-check logic -- it registers
+  whatever manifest/record-count/size the caller supplies, with no QA gate in between.
+- **Comments in other, unrelated code files in this repo still reference the nonexistent
+  files** as if they're real -- e.g. `src/services/source-query-service.ts` ("`quality-check-service.ts`
+  uses for quality checks"), `src/services/external-writeback-service.ts` ("quality-check-service.ts/
+  document-extraction-service.ts already follow"), and `tests/p0/iceberg-write-service.test.ts`'s
+  own header comment (references both `tests/p0/cross-product-boundary.test.ts` and
+  `quality-check-service.ts`, neither of which exists). Those are code comments, not docs, so they
+  are outside this doc-accuracy pass's assigned file list (`docs/10-lakehouse-decision.md`,
+  `docs/11-lakehouse-write-plan.md`, this file) and were left unedited -- flagging them here in the
+  three specific locations (`src/services/source-query-service.ts`,
+  `src/services/external-writeback-service.ts`,
+  `tests/p0/iceberg-write-service.test.ts`) so whoever picks this up next doesn't have to
+  re-discover them.
+
+**This is a real, currently open product gap, not a documentation typo.** 0pt's own house rule
+(`CLAUDE.md`: "If anything here conflicts with existing code, flag it ... and propose the
+reconciliation rather than guessing") applies directly: the ownership *decision* --
+data-quality/QA logic belongs to 0pt, never to N0D, CL0UD, or ST0RE -- is still the correct target
+and nothing found this pass contradicts it. But until a `quality-check-service.ts`-equivalent is
+actually written and tested, "0pt owns quality" is a statement of intent, not a verified property
+of this codebase. Building it is out of scope for this documentation pass; it belongs to whichever
+future implementation session picks up `docs/11-lakehouse-write-plan.md` item 4.
@@ -0,0 +1,180 @@
+# 0pt Dataset Quality / QA Flow — TARGET SPEC ONLY, NOT YET BUILT
+
+> **This document describes what does not exist yet.** Every file, service,
+> type, and schema named below is a proposal, not a fact. Read this doc with
+> "should"/"would need to"/"is intended to" — never "does" or "is." If any
+> other doc in this repo states or implies that dataset-level quality
+> enforcement is already built, real, and tested, that statement is wrong;
+> see "Why this doc exists" below.
+
+## Why this doc exists
+
+Several docs in this repo — `docs/P0_QUERY_SOURCE_FLOW.md` (before this
+pass's correction), `docs/ICEBERG_WRITE_BOUNDARY.md`, and
+`docs/11-lakehouse-write-plan.md` — reference the following as if they are
+real, already-built, already-tested files in this repo:
+
+- `src/services/quality-check-service.ts`
+- `src/services/quality-report-service.ts`
+- `src/types/quality-check.ts`
+- `src/types/quality-report.ts`
+- `src/data-platform/services/catalog-service.ts`
+- `sql/002_p0_dataset_quality.sql`
+- `sql/003_*.sql` (unspecified third migration)
+
+**Verified this pass:** `git log --all` for every one of those paths returns
+**zero commits, ever, on any branch** (`main`, `feature/0pt-env-example`,
+`ci/add-quality-gate` all checked). A full-repo `find` for each filename
+also returns nothing. These files have never existed in this repository's
+history. `docs/ICEBERG_WRITE_BOUNDARY.md` even states outright that "0pt's
+QA stage... remains entirely 0pt-owned" and cites `quality-check-service.ts`
+as the thing that wasn't touched by that pass — implying it exists to not
+touch. It doesn't exist to begin with.
+
+This means: **0pt's dataset-level data-quality/QA enforcement stage does
+not exist in code at all**, despite being described elsewhere as complete.
+This is a real, currently-open gap — not a doc typo. This document replaces
+those false claims with an honest target specification: what this stage
+*should* look like if/when it gets built, grounded in the parts of this
+repo's design that *are* real today.
+
+`docs/P0_QUERY_SOURCE_FLOW.md`'s "Known gaps" section has the fuller list of
+exactly which files make the false claim and where; this doc does not
+repeat that inventory, only the target design.
+
+## What already exists that this would build on (real, verified)
+
+- **The provenance/confidence model** — `docs/06-data-engine.md`'s pipeline
+  stage 5 ("QA") already specifies the *rules* this stage should enforce,
+  even though no code implements them yet:
+  - Per-field `bridge_provenance`: `source_id`, `freshness`, `confidence`
+    (0–1), `level` (0–3), `agreed_sources`.
+  - Level semantics: 0 = unavailable/licensed, 1 = single source, 2 =
+    partial corroboration, 3 = ≥2 independent sources agree.
+  - The QA rule: **drop rows below the order's `confidence_target`** —
+    deliver fewer rows, never fabricate a value to hit a target.
+  - `est_confidence` (order-level target) vs. `avg_confidence` (delivered,
+    actual) as the two numbers this stage would need to reconcile.
+- **The Dataset registry** — `src/services/dataset-service.ts` /
+  `src/types/dataset.ts` are real, in-memory, tested code. `Dataset` already
+  has `dataset_type: "raw" | "structured" | "enriched" | "curated"` and
+  `status: "active" | "archived" | "deprecated"` — a quality stage would
+  need to decide whether a failed QA pass changes `status`, or whether
+  quality state lives entirely in a separate table/type instead (see
+  "Open questions" below).
+- **The N0D job pattern** — `src/services/iceberg-write-service.ts` is real,
+  tested code showing the actual "sync path vs. N0D job" split this
+  codebase already uses elsewhere: an `input.heavy` flag routes to
+  `this.n0d.createJob(...)` instead of running inline. A quality-check
+  service would plausibly reuse this same shape (small samples checked
+  inline; a real run against a full dataset dispatched as an N0D job) —
+  but nothing today wires that up for quality checks specifically.
+- **The CL0UD-policy-before-execution pattern** — `src/services/external-writeback-service.ts`
+  (`0pt.write_external_record`, real, tested) calls
+  `Cl0udClient.evaluatePolicy()` before performing its write. If a quality
+  service is meant to policy-gate before running (as
+  `docs/ICEBERG_WRITE_BOUNDARY.md` implies with its "CL0UD is always
+  re-consulted" framing), this is the real precedent to follow, not
+  something already done by the nonexistent `quality-check-service.ts`.
+- **The AUD0 event pattern** — every real service in this repo
+  (`source-service.ts`, `dataset-service.ts`, `source-query-service.ts`,
+  `external-writeback-service.ts`, `iceberg-write-service.ts`) emits AUD0
+  events via `createAud0Client()` against an in-memory mock (no live AUD0
+  endpoint reachable from this repo). A quality service would follow the
+  same convention.
+
+## What this stage should do (target design — none of this is built)
+
+1. **Trigger.** A quality check would need to run after the enrichment/
+   fusion stage (`docs/06-data-engine.md` stage 4) and before a dataset is
+   marked ready for delivery or written to Iceberg via
+   `IcebergWriteService`. Whether this is a synchronous call, an
+   automatically-triggered N0D job, or an explicit caller action is
+   undecided.
+2. **Checks to run**, per `docs/06-data-engine.md`'s stage 5 language
+   (originally scoped as "Great Expectations or equivalent, run inside the
+   worker"):
+   - **Validity** — field format/range checks against the schema for that
+     `dataset_type`.
+   - **Completeness** — required-field coverage.
+   - **Freshness** — age of each `bridge_provenance.freshness` against a
+     staleness threshold.
+   - **Uniqueness** — post-dedup uniqueness (RapidFuzz dedup already
+     happens upstream per `docs/06-data-engine.md` stage 3; this would be a
+     verification pass, not the dedup itself).
+   - **Corroboration** — cross-check `bridge_provenance.level`/`agreed_sources`
+     against the order's declared `confidence_target`; rows below target
+     get dropped, never backfilled with a guess.
+3. **Output: a quality report.** Would need a `QualityReport` shape
+   (proposed home: `src/types/quality-report.ts`, not yet created) capturing
+   at minimum: `dataset_id`, `check_run_id`, per-check pass/fail counts,
+   `rows_dropped_below_confidence_target`, `avg_confidence` (delivered,
+   actual — per `docs/06-data-engine.md`), and a timestamp. This is the
+   thing `docs/06-data-engine.md` calls "the quality report stored on
+   `deliveries`" — that storage location (a `deliveries` table) does not
+   exist in this repo's `sql/` directory either; `sql/001_init.sql` would
+   need to be checked/extended for it, or a new migration written.
+4. **Gate, not silent pass-through.** Per CLAUDE.md's non-negotiable
+   constraint #1 ("we never invent values") and #3 ("provenance per field"),
+   a dataset that fails its quality gate should not silently ship — the
+   order's delivery flow (`docs/01-product.md`'s order lifecycle) would need
+   to surface a failed/partial QA result to the customer, not swallow it.
+
+## What would need to be created (none of this exists)
+
+| Proposed file | Would contain |
+|---|---|
+| `src/types/quality-check.ts` | `QualityCheckRequest`/`QualityCheckResult` shapes: which checks to run, thresholds, dataset/source refs |
+| `src/types/quality-report.ts` | `QualityReport` shape described above |
+| `src/services/quality-check-service.ts` | Orchestrates the checks (validity/completeness/freshness/uniqueness/corroboration), CL0UD policy check, N0D job dispatch for heavy runs (same `input.heavy` shape as `iceberg-write-service.ts`), AUD0 emission |
+| `src/services/quality-report-service.ts` | Persists/retrieves `QualityReport`s; registry pattern matching `DatasetService`/`SourceService` (in-memory today, same known "not shared across route modules" limitation until real persistence lands) |
+| A new SQL migration | Schema for quality-check runs and reports. **Numbering note:** this repo's `sql/` directory today contains only `001_init.sql` and `004_iceberg_write_boundary.sql` — `002` and `003` were referenced in other docs but never created, so there is a numbering gap. Whether a new migration should fill `002`/`003` or continue from `005` is an open question — do not assume `002_p0_dataset_quality.sql` is the correct filename just because other docs guessed it. |
+
+`src/data-platform/services/catalog-service.ts` is referenced elsewhere in
+this repo's docs (as the source of an "`L4` = restricted sensitivity"
+precedent) but was also confirmed this pass to not exist anywhere in this
+repo — it is a separate fabrication from the quality-check one, not
+something this quality stage specifically depends on. If a dataset-level
+catalog/listing capability is needed as part of this work, the registered
+`0pt.catalog_list` and `0pt.source_registry_list` capabilities
+(`cl0ud`'s `packages/capability-registry/src/registry.ts`, both real
+registry entries, `surfaces: ['api']`) are the closest existing hooks — but
+whether either is meant to serve this purpose, or a new capability is
+needed, is undecided.
+
+## No capability registered for this yet
+
+`cl0ud`'s `packages/capability-registry/src/registry.ts` was checked this
+pass for anything quality-related: no `0pt.quality_check`,
+`0pt.run_quality_checks`, or similarly-named capability exists. The
+registry does have a `qualityGateRequired` boolean flag used by *other*
+capabilities (e.g. one INF0 capability sets it `true`), but nothing wires
+`0pt`'s own dataset QA into that flag or into any capability of its own.
+Building this stage would need a new capability entry, decided surfaces
+(`api` at minimum, per the six-surface model; `job` likely for a
+full-dataset run), a `riskLevel`, and a `piiLevel`.
+
+## Open questions for Simon
+
+- Does quality-check execution belong entirely in 0pt (as
+  `docs/ICEBERG_WRITE_BOUNDARY.md` asserts should be true, even though the
+  code backing that assertion doesn't exist), or should the actual
+  check-running compute move to N0D as a job type, with 0pt only owning the
+  *rules*?
+- Where does a `QualityReport` get persisted — a new `sql/00X_*.sql` table
+  in 0pt's own Postgres, or through ST0RE (matching the "ST0RE owns
+  metadata, 0pt owns production" boundary `docs/ICEBERG_WRITE_BOUNDARY.md`
+  draws for Iceberg tables)?
+- Does a dataset that fails QA change `Dataset.status`
+  (`src/types/dataset.ts`), or does quality state live entirely outside the
+  `Dataset` record?
+- What migration number should the new schema use, given the `002`/`003`
+  gap described above?
+- Should this become its own registered `0pt.*` capability, and if so what
+  `riskLevel`/`piiLevel` — quality checks read dataset content, which per
+  the reasoning already used for `0pt.query_source` (`piiLevel: 'high'`
+  because "can return any column, including PII") would plausibly need the
+  same `piiLevel`.
+
+None of the above is decided by this document. It exists to give a future
+build pass an honest starting point instead of a fabricated one.
@@ -1,8 +1,18 @@
 # 0pt.query_source — Bounded Source Query Flow

-Additive companion to `docs/P0_DATASET_QUALITY_FLOW.md`. Adds the capability
-to actually **read data** from a registered Source, not just register its
-metadata.
+> **Companion-doc note (corrected):** this doc originally called itself an
+> "additive companion to `docs/P0_DATASET_QUALITY_FLOW.md`." That file did
+> not exist anywhere in this repository at the time — `git log --all` for it
+> returns zero commits, on any branch, ever. This pass adds
+> `docs/P0_DATASET_QUALITY_FLOW.md` as a clearly-labeled **target spec, not
+> yet built** (see that file). Treat the two docs as siblings: this one
+> covers the real, working `0pt.query_source` read path; the other covers
+> the *intended, unbuilt* dataset-quality/QA path that several other docs in
+> this repo (wrongly) describe as already implemented. See "Known gaps"
+> below for the details of that wider mixup.
+
+Adds the capability to actually **read data** from a registered Source, not
+just register its metadata.

 ## What this is

@@ -12,11 +22,23 @@ caller-supplied SQL query against the customer's own Azure Fabric / OneLake
 SQL analytics endpoint and return rows — synchronously, bounded by a max-row
 and max-time ceiling.

+> Note: `0pt.create_source` (the capability id `source-service.ts` emits in
+> its AUD0 events) is **not** one of the 14 `0pt.*` capabilities currently
+> registered in `cl0ud`'s `packages/capability-registry/src/registry.ts` —
+> only `0pt.source_registry_list` (a read/list capability) is registered for
+> the Source domain. `0pt.query_source` itself *is* registered (see
+> "Capability registration" below). Whether `0pt.create_source` needs its own
+> registry entry, or was meant to be folded into an existing one, is unresolved
+> — flagging for Simon rather than guessing.
+
 **Tenant-agnostic by construction.** Any SIAX customer registers their own
 Fabric/OneLake warehouse (their own Entra tenant, their own service
 principal, their own SQL endpoint). Nothing in the adapter or service layer
 is hardcoded to one customer — every credential and endpoint is a parameter
-supplied per call, never an env var fallback.
+supplied per call, never an env var fallback. (This is orthogonal to the
+`tenant_id`/`project_id` handling gap described below — the *warehouse*
+credentials are correctly never defaulted from env; the *platform* tenant_id
+used for scoping/audit is a separate, unresolved problem.)

 ## Why bounded + synchronous, not just "run any query"

@@ -31,9 +53,15 @@ is reachable, sample a table, preview a query before scheduling it). It is
  `SOURCE_QUERY_HARD_MAX_TIMEOUT_MS`). A caller-requested value above the
  ceiling is clamped down, not rejected.
 - Anything heavier — large exports, long scans, scheduled/recurring pulls —
-  must go through **N0D as a job** instead, the same split
-  `quality-check-service.ts` already uses (`runQualityChecks` → CL0UD policy
-  → N0D job, not an inline synchronous call).
+  is meant to go through **N0D as a job** instead. The real, working
+  precedent for that "synchronous path vs. N0D job" split in this codebase
+  is `src/services/iceberg-write-service.ts`: it takes an `input.heavy`
+  flag and, when set, calls `this.n0d.createJob(...)` instead of doing the
+  work inline. (An earlier version of this doc cited `quality-check-service.ts`
+  for this same pattern — that file does not exist; see "Known gaps.")
+  `SourceQueryService` does not itself request an N0D job for anything today
+  — there is no "heavy" variant of `0pt.query_source` yet, only the bounded
+  synchronous path described here.

 ## Architecture

@@ -64,19 +92,91 @@ Route:    app/api/0pt/sources/[sourceId]/query/route.ts
  - 422 (SourceQueryUnsupportedError) when source_type != "database" or
    adapter_id != "fabric_onelake_sql"
  - 504 (SourceQueryTimeoutError) on timeout
-
-AUD0:     event_type "0pt.source_queried", capability_id "0pt.query_source",
-  resource_type "source", risk_level "L4" (live external data access with a
-  tenant's own credentials — one level above the "L3" used for Source/
-  Dataset/QualityCheck metadata writes, matching the "L4 = restricted
-  sensitivity" precedent in src/data-platform/services/catalog-service.ts).
-  Emitted on both success (ok:true, row_count, truncated, duration_ms) and
-  failure (ok:false, error) via the same `Aud0Client` pattern as
-  source-service.ts / quality-check-service.ts.
 ```

+## Capability registration (CL0UD registry — verified this pass)
+
+`0pt.query_source` is registered in `cl0ud`'s
+`packages/capability-registry/src/registry.ts`:
+
+| Field | Value |
+|---|---|
+| `surfaces` | `['api']` only — no `cli`/`mcp`/`job` surface is enabled |
+| `sync` | `true` |
+| `requiresJob` | `false` |
+| `piiLevel` | `'high'` — "ad-hoc SQL against an arbitrary registered source can return any column, including PII" (registry's own comment) |
+| `riskLevel` | `'L2'` |
+| `mcpEnabled` / `cliEnabled` | both `false` |
+| `auditRequired` | `true` (comment: "emits `0pt.source_queried`") |
+| `approvalRequired` | `false` |
+
+This matches the platform-wide six-surface capability model: every `0pt.*`
+capability registered today exposes `api` only (plus `job` for a couple of
+the heaviest write paths) — none has a live CLI or MCP tool yet. Any claim
+of a working `siax 0pt query-source ...` CLI command or an MCP tool for this
+capability would be describing a target, not current reality.
+
+**Discrepancy found this pass:** the registry declares `riskLevel: 'L2'` for
+`0pt.query_source`, but `source-query-service.ts`'s own AUD0 emission (see
+AUD0 section below) uses `risk_level: "L4"` on every `0pt.source_queried`
+event — a two-level gap between what the capability is registered as and
+what it actually reports. Unresolved; needs a decision on which is correct
+(or whether the registry entry should simply be updated to `L4` to match
+the live code, given "external read with a tenant's own credentials" is
+arguably closer to `L4` than `L2`).
+
+## AUD0 event
+
+`event_type: "0pt.source_queried"`, `capability_id: "0pt.query_source"`,
+`resource_type: "source"`, `risk_level: "L4"` in the code as written today
+(see the registry discrepancy noted above). For comparison, other real,
+verified `risk_level` usages elsewhere in this repo's services: `source-service.ts`
+and `dataset-service.ts` use `"L2"` for their own metadata-write events;
+`document-capture-service.ts` and `document-extraction-service.ts` use
+`"L3"`; `external-writeback-service.ts` (`0pt.write_external_record`, a real,
+tested service) uses `"L4"` for live writes to an external system with a
+tenant's credentials — that is the closest real precedent for this
+capability's choice of `"L4"`, not the `src/data-platform/services/catalog-service.ts`
+citation an earlier version of this doc made up (that path does not exist
+anywhere in this repo — confirmed via `find`).
+
+Emitted on both success (`ok:true, row_count, truncated, duration_ms`) and
+failure (`ok:false, error`) via the same `Aud0Client` pattern as
+`source-service.ts` / `external-writeback-service.ts`. Like every other
+`Aud0Client` use in this repo, this runs against the in-memory mock client —
+no live AUD0 ingestion endpoint is reachable from this codebase today (no
+`AUD0_URL` is read via `process.env` anywhere in the code). Treat this as
+"real code, mock-only, not live-verified," not as "integrated."
+
 ## Known gaps / deliberately left out

+- **`tenant_id`/`project_id` are read straight from the request body, not
+  bound to an authenticated session.** `app/api/0pt/sources/[sourceId]/query/route.ts`
+  requires `body.tenant_id` and `body.project_id` as plain JSON fields (see
+  the route's own 400-check) and passes them straight through to
+  `SourceQueryService.querySource()`, which uses them unchecked for AUD0
+  scoping. This is **not** a deliberate two-tier trust design — it is
+  because **no auth/session system exists anywhere in this repo yet**
+  (`app/api/orders/route.ts`'s own `GET` handler has the literal comment
+  "org scoping added with auth" — i.e., not yet). Any caller can currently
+  claim to be any tenant simply by putting a different `tenant_id` in the
+  request body. This is one of several routes in this repo with the same
+  gap: `lakehouse/mappings/route.ts` and `sources/rate-policies/route.ts`
+  read `tenant_id`/`project_id` directly off the request body exactly like
+  this route does (verified by reading both files); `document-capture-service.ts`'s
+  own route (`app/api/0pt/documents/capture/route.ts`) does the same
+  (`body.tenant_id`/`body.project_id`). `lakehouse/mappings/[mappingId]/writes/route.ts`
+  is one hop removed — it takes no `tenant_id` field on its own POST body at
+  all; `IcebergWriteService.requestIcebergWrite()` instead pulls `tenant_id`/
+  `project_id` off the previously-stored mapping record (looked up by
+  `mappingId`), whose `tenant_id` was itself set, unauthenticated, via
+  `lakehouse/mappings/route.ts`'s POST body. Same underlying trust-chain
+  problem, one indirection further away — worth keeping the distinction
+  precise rather than implying all five routes share identical code shape.
+  The fix is an auth/session layer that server-binds `tenant_id` — that is
+  Simon's call, tracked as Phase 3 of `docs/09-build-plan.md`, not built
+  anywhere in this repo yet. Do not treat this route as tenant-isolated
+  until that lands.
 - **`mssql` is not a declared dependency yet.** package.json and
  pnpm-lock.yaml already have unrelated uncommitted changes from a separate
  in-flight session at the time this capability was built, so adding a new
@@ -85,8 +185,12 @@ AUD0:     event_type "0pt.source_queried", capability_id "0pt.query_source",
  typecheck without the package installed) and throws a clear, actionable
  error if it's missing. Once package.json is settled, `pnpm add mssql` is
  the only change needed to make `query()` hit a real Fabric endpoint — no
-  code changes required.
- **In-memory SourceService is not shared across API route modules.**
+  code changes required. As of this pass, this means `0pt.query_source`
+  cannot actually execute a live query against Fabric/OneLake yet — the
+  whole path up to the driver load is real and typechecks, but `query()`
+  will throw the "mssql package is not installed/resolvable" error on any
+  real invocation until the dependency is added.
+- **In-memory `SourceService` is not shared across API route modules.**
  Same pre-existing limitation as `sources/route.ts` /
  `sources/[sourceId]/route.ts` (each Next.js route module instantiates its
  own `SourceService`, so a Source created via `POST /api/0pt/sources` is not
@@ -95,16 +199,79 @@ AUD0:     event_type "0pt.source_queried", capability_id "0pt.query_source",
  shared singleton for its own two routes; doing the same for Source would
  mean editing `source-service.ts` and/or the two existing `sources/route.ts`
  files, which was out of scope here to avoid touching that flagged area.
-  The real fix is the same one already pointed at by `sql/002_p0_dataset_quality.sql`
-  (`opt_sources` table) — back `SourceService` with real persistence.
- **No CL0UD policy check before executing a query.** `quality-check-service.ts`
-  calls `Cl0udClient.evaluatePolicy()` before creating a N0D job; this
-  synchronous path does not, since it is scoped as a bounded preview read, not
-  a governed job. Worth revisiting once policy-gating on `0pt.query_source`
-  is defined.
+  **Correction:** an earlier version of this doc, and the route file's own
+  header comment, said the real fix is "already pointed at by
+  `sql/002_p0_dataset_quality.sql` (`opt_sources` table)." That file does
+  not exist and never has — `git log --all` returns zero commits for it, on
+  any branch. The `sql/` directory in this repo today contains only
+  `001_init.sql` and `004_iceberg_write_boundary.sql`; no `002` or `003`
+  migration has ever been created. The real fix is still "back
+  `SourceService` with real persistence" — just not via a file that exists.
+  (`app/api/0pt/sources/[sourceId]/query/route.ts`'s own header comment
+  still makes this same broken reference; that is a code comment, not a doc,
+  so it's out of scope for this pass to edit, but it should be fixed
+  alongside whichever pass builds real persistence.)
+- **No CL0UD policy check before executing a query.** Unlike
+  `external-writeback-service.ts` (`0pt.write_external_record`), which calls
+  `Cl0udClient.evaluatePolicy()` before executing a write, `source-query-service.ts`
+  has no `cl0ud` import and performs no policy check at all — confirmed by
+  reading the file in full. This synchronous read path is scoped as a
+  bounded preview read, not a governed job, but that's a design choice that
+  has not been written down or reviewed, not an enforced policy. Worth
+  revisiting once policy-gating on `0pt.query_source` is defined — and note
+  the CL0UD registry already declares `piiLevel: 'high'` for this
+  capability, which makes the absence of any policy check more notable, not
+  less.
 - **No SQL rewriting/injection of `TOP`/`LIMIT`.** Row bounding is applied to
  whatever the adapter returns, not pushed into the query itself (arbitrary
  caller SQL can't be safely rewritten). A query that itself returns far more
  rows than `max_rows` still executes in full on the warehouse before being
  truncated client-side — only the *response* is bounded, not warehouse-side
  compute. Documented, not silently hidden.
+- **Cross-file fabrication this pass found and corrected here, but could not
+  fix everywhere it appears.** Several files in this repo (some in this
+  doc's own former text, some in code comments this pass does not own)
+  reference `src/services/quality-check-service.ts`,
+  `src/services/quality-report-service.ts`, `src/types/quality-check.ts`,
+  `src/types/quality-report.ts`, `src/data-platform/services/catalog-service.ts`,
+  `sql/002_p0_dataset_quality.sql`, and `sql/003_*.sql` as if they are real,
+  already-built, already-tested files. `git log --all` for every one of
+  those paths returns **zero commits, ever, on any branch** (`main`,
+  `feature/0pt-env-example`, `ci/add-quality-gate` all checked). These files
+  have never existed in this repository. This doc's own text used to make
+  this same false claim in three places; all are corrected above.
+  **Re-checked this pass:** `docs/11-lakehouse-write-plan.md` has since been
+  corrected by a parallel pass — it now carries its own "Correction
+  (documentation-accuracy pass)" callout and its item 4 explicitly reads
+  "**NOT BUILT** ... there is no dedicated quality-check/quality-report
+  service in this repo as of this writing," so it no longer needs the same
+  fix. **`docs/ICEBERG_WRITE_BOUNDARY.md` has *also* since been fully
+  corrected** (re-verified this pass, reading the current file end to end):
+  its former internal contradiction — a top-of-file correction callout next
+  to a body that still asserted the fabricated files as real two sections
+  down — has been resolved. Its "Verification status" section now reads
+  "this section previously pointed at `src/services/quality-check-service.ts`
+  as a peer example ... that file does not exist," and its data-quality
+  section (retitled "Data quality: not yet built (corrected)") now quotes
+  its own old wording only inside a "this section previously read..."
+  framing before stating plainly that those files don't exist and were
+  never built. Neither section currently asserts the fabricated files as
+  fact. Code comments in `app/api/0pt/sources/[sourceId]/query/route.ts`
+  (line 14: "`sql/002_p0_dataset_quality.sql` already defines `opt_sources`")
+  and `src/services/external-writeback-service.ts` (line 21: "...
+  `quality-check-service.ts`/`document-extraction-service.ts` already
+  follow") still carry the same false reference — confirmed still present
+  as of this pass — and remain outside any of these docs' scope to fix
+  (code, not docs; flagging for whoever next touches those two files). See
+  `docs/P0_DATASET_QUALITY_FLOW.md` (added this pass) for the honest,
+  target-spec-only replacement for what those files were supposed to do.
+
+## Known issue: which 0pt repo is authoritative
+
+This repo has two remotes with diverged history — `github.com/sax3l/0pt` and
+`git.siax.io/sax3l/0pt` (Gitea) — that share origin lineage for at least
+part of the codebase but have each accumulated commits the other doesn't
+have. Which one is deployed to `0pt.app`, and whether they're meant to stay
+in sync, is unresolved and is Simon's call, not something this pass
+attempted to resolve. Noting it here since this doc describes code that
+lives in "the 0pt repo" as if there's exactly one.
@@ -30,6 +30,21 @@ export interface Order {
 // Non-durable fallback used only until a database is provisioned.
 const mem = new Map<string, Order>();

+// postgres.js (pinned v3.4.9) returns bigint (total_ore/deposit_ore/balance_ore)
+// and numeric (est_confidence) columns as strings by default, not JS numbers.
+// Coerce only these four fields on rows read back from SQL -- not the shared
+// `sql` client's global type map, which would silently affect every other
+// table's bigint/numeric columns too (e.g. jobs.pct, deliveries.avg_confidence).
+function coerceOrder(row: Order): Order {
+  return {
+    ...row,
+    total_ore: Number(row.total_ore),
+    deposit_ore: Number(row.deposit_ore),
+    balance_ore: Number(row.balance_ore),
+    est_confidence: Number(row.est_confidence),
+  };
+}
+
 function estimateFor(config: OrderConfig) {
  return computeEstimate({
    markets: config.markets ?? [],
@@ -74,7 +89,7 @@ export async function getOrder(id: string): Promise<Order | null> {
    const rows = await sql<Order[]>`
      SELECT order_id, flow, status, config, total_ore, deposit_ore, balance_ore, est_days, est_confidence, created_at
      FROM orders WHERE order_id::text = ${id} LIMIT 1`;
-    return rows[0] ?? null;
+    return rows[0] ? coerceOrder(rows[0]) : null;
  }
  return mem.get(id) ?? null;
 }
@@ -82,9 +97,10 @@ export async function getOrder(id: string): Promise<Order | null> {
 export async function listOrders(): Promise<Order[]> {
  const sql = getSql();
  if (sql) {
-    return sql<Order[]>`
+    const rows = await sql<Order[]>`
      SELECT order_id, flow, status, config, total_ore, deposit_ore, balance_ore, est_days, est_confidence, created_at
      FROM orders ORDER BY created_at DESC LIMIT 100`;
+    return rows.map(coerceOrder);
  }
  return [...mem.values()].sort((a, b) => b.created_at.localeCompare(a.created_at));
 }
@@ -95,7 +111,7 @@ export async function setStatus(id: string, status: string): Promise<Order | nul
    const rows = await sql<Order[]>`
      UPDATE orders SET status = ${status}, updated_at = now() WHERE order_id::text = ${id}
      RETURNING order_id, flow, status, config, total_ore, deposit_ore, balance_ore, est_days, est_confidence, created_at`;
-    return rows[0] ?? null;
+    return rows[0] ? coerceOrder(rows[0]) : null;
  }
  const o = mem.get(id);
  if (o) { o.status = status; mem.set(id, o); }
@@ -32,5 +32,5 @@ export async function listSubscriptions(): Promise<Subscription[]> {
  if (sql) {
    return sql<Subscription[]>`SELECT sub_id, order_id, cadence, webhook_url, status, next_run_at, created_at FROM subscriptions ORDER BY created_at DESC LIMIT 100`;
  }
-  return [...mem.values()];
+  return [...mem.values()].sort((a, b) => b.created_at.localeCompare(a.created_at));
 }
@@ -3,6 +3,7 @@
  "version": "0.1.0",
  "private": true,
  "packageManager": "pnpm@9.15.9",
+  "//scripts": "`typecheck` is the BLOCKING gate both CI workflows run (.github/workflows/ci.yml and .gitea/workflows/ci.yml): tsc over tsconfig.check.json, i.e. src/ + tests/ -- the capability layer that is the actual deliverable. `typecheck:app` is the whole-repo check (tsconfig.json, incl. the v0-generated app/ + components/ UI that next.config.mjs suppresses via typescript.ignoreBuildErrors). It is ADVISORY, not blocking: it currently reports 9 pre-existing errors in app/api/0pt/* route handlers where the Wave 2 Zod schemas type fields as plain `string` while the services want narrower unions. Those 9 predate the GitHub<->Gitea unification merge (identical set on Gitea main before it); tightening the Zod schemas would change which request bodies are accepted, so it is deliberately left to its own change.",
  "scripts": {
    "build": "next build",
    "dev": "next dev",
@@ -12,7 +13,8 @@
    "test": "vitest run",
    "test:watch": "vitest",
    "format": "prettier --check .",
-    "format:write": "prettier --write ."
+    "format:write": "prettier --write .",
+    "typecheck:app": "tsc --noEmit -p tsconfig.json"
  },
  "dependencies": {
    "@hookform/resolvers": "^3.10.0",
@@ -82,7 +84,7 @@
    "tw-animate-css": "1.3.3",
    "typescript": "^5",
    "typescript-eslint": "^8.15.0",
-    "vitest": "^3.2.0"
+    "vitest": "^3.2.7"
  },
  "pnpm": {
    "onlyBuiltDependencies": [
@@ -1,5 +1,6 @@
 {
  "$id": "0pt.iceberg_table.schema.v1",
+  "description": "NON-AUTHORITATIVE READ CACHE ONLY. ST0RE owns Iceberg table/catalog/snapshot state (docs/ICEBERG_WRITE_BOUNDARY.md, src/clients/st0re-lakehouse-client.ts's St0reIcebergTable). This schema mirrors that shape for tests/p0/enterprise-data-os-expansion.test.ts's contract assertions from an earlier pass; 0pt must never write to it as a second copy of ST0RE's table registry -- see docs/ICEBERG_WRITE_BOUNDARY.md's 'A pre-existing artifact' section.",
  "type": "object",
  "required": [
    "table_id",
@@ -8,6 +9,7 @@
    "table_name",
    "namespace",
    "storage_uri",
+    "catalog_ref",
    "table_format",
    "status",
    "created_at"
@@ -20,6 +22,7 @@
    "namespace": { "type": "string", "description": "ST0RE lakehouse namespace name." },
    "storage_uri": { "type": "string", "description": "Object-store URI for the table's data/metadata, e.g. s3://siax-tenants/.../table." },
    "catalog_ref": { "type": "string", "description": "Opaque reference into the external Iceberg catalog — ST0RE does not resolve it." },
+    "dataset_id": { "type": "string", "description": "ST0RE's OWN dataset foreign key as mirrored from its table row — NOT 0pt's dataset_id. 0pt must never send its own dataset_id here (it 400s with a Postgres FK violation); the 0pt-side dataset<->table link lives in DatasetIcebergMapping.iceberg_table_id. See docs/ICEBERG_WRITE_BOUNDARY.md." },
    "table_format": { "type": "string", "enum": ["iceberg", "delta", "hudi"] },
    "current_snapshot_id": { "type": "string" },
    "schema_version": { "type": "string" },
@@ -1,5 +1,6 @@
 {
  "$id": "0pt.lineage_event.schema.v1",
+  "description": "CONTRACT-ONLY -- 0pt's real lineage emissions today go through Aud0Client.ingestLineageEvent (src/clients/aud0-client.ts), whose Aud0LineageEvent shape is source_type/source_id -> target_type/target_id, not input_assets/output_assets. This wider multi-asset shape exists so tests/p0/enterprise-data-os-expansion.test.ts's contract assertions (from an earlier 'PROMPT 2' pass) have a real file to check; it documents an intended future generalization (multi-input/multi-output lineage), not a built/wired capability. NOTE (GitHub<->Gitea unification merge): the two remotes disagreed on `producer` -- one modelled it as an object {app_id, capability_id}, the other as a string plus flat top-level app_id/capability_id. The structured object is kept as canonical here because it names both parts unambiguously; `event_type`, `app_id` and `capability_id` are retained as optional top-level properties so the flat draft's fields are not lost. Nothing in this repo reads or validates against this file, so neither choice changes behaviour.",
  "type": "object",
  "required": [
    "lineage_event_id",
@@ -14,6 +15,9 @@
    "lineage_event_id": { "type": "string" },
    "tenant_id": { "type": "string" },
    "project_id": { "type": "string" },
+    "event_type": { "type": "string", "description": "e.g. 0pt.lineage_emitted. From the flat draft; optional." },
+    "app_id": { "type": "string", "description": "Flat-draft alternative to producer.app_id; optional." },
+    "capability_id": { "type": "string", "description": "Flat-draft alternative to producer.capability_id; optional." },
    "producer": {
      "type": "object",
      "description": "The capability/app that produced this lineage edge.",
@@ -1,5 +1,6 @@
 {
  "$id": "0pt.signal.schema.v1",
+  "description": "CONTRACT-ONLY -- no service in this repo produces or reads 0pt.signal rows yet. This schema exists so tests/p0/enterprise-data-os-expansion.test.ts's contract assertions (from an earlier 'PROMPT 2' pass) have a real file to check; it is documentation of an intended shape for future ICP/signal-intelligence work, not a built capability. Do not treat it as evidence that signal detection is implemented. NOTE (GitHub<->Gitea unification merge): the two remotes named several fields differently (entity_id/entity_key, observed_at/detected_at, confidence_level/confidence). Both names are retained below as optional properties rather than dropping either draft's vocabulary; a future pass that actually builds signal detection must pick one pair and delete the other.",
  "type": "object",
  "required": [
    "signal_id",
@@ -16,15 +17,19 @@
    "signal_id": { "type": "string" },
    "tenant_id": { "type": "string" },
    "project_id": { "type": "string" },
-    "signal_type": { "type": "string", "description": "e.g. hiring_growth, funding_round, tech_adoption, leadership_change." },
+    "signal_type": { "type": "string", "description": "e.g. hiring_growth, funding_round, funding_event, tech_adoption, leadership_change." },
    "signal_strength": { "type": "number", "description": "Normalized 0..1 confidence/intensity of the signal.", "minimum": 0, "maximum": 1 },
-    "entity_type": { "type": "string", "enum": ["company", "person", "domain", "vehicle"] },
+    "entity_type": { "type": "string", "enum": ["company", "person", "contact", "domain", "vehicle"] },
    "entity_id": { "type": "string" },
+    "entity_key": { "type": "string", "description": "Alternative name for entity_id from the other draft; optional." },
    "value": { "description": "Signal payload value (type depends on signal_type)." },
    "unit": { "type": "string" },
+    "metadata": { "type": "object" },
    "source_id": { "type": "string", "description": "References 0pt.source.schema.v1's source_id." },
    "confidence_level": { "type": "string", "enum": ["low", "medium", "high"] },
+    "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Numeric alternative to confidence_level from the other draft; optional." },
    "observed_at": { "type": "string" },
+    "detected_at": { "type": "string", "description": "Alternative name for observed_at from the other draft; optional." },
    "correlation_id": { "type": "string" },
    "created_at": { "type": "string" }
  }
@@ -205,7 +205,7 @@ importers:
        specifier: ^8.15.0
        version: 8.65.0(eslint@9.39.5(jiti@2.7.0))(typescript@5.9.3)
      vitest:
-        specifier: ^3.2.0
+        specifier: ^3.2.7
        version: 3.2.7(@types/node@22.20.0)(jiti@2.7.0)(lightningcss@1.32.0)

 packages:
@@ -26,6 +26,16 @@ app.add_middleware(

 _SOURCES = yaml.safe_load((Path(__file__).resolve().parent.parent / "sources" / "sources.yaml").read_text(encoding="utf-8"))["sources"]

+
+def _coerce_int(v: Any, default: int) -> int:
+    """int(v) raises on decimal-formatted strings/floats; coerce via float() first
+    and fall back to `default` on any unparseable, client-controlled input instead
+    of a 500."""
+    try:
+        return int(float(v))
+    except (TypeError, ValueError):
+        return default
+
 # ── estimate model (mirrors apps/web lib/data.computeEstimate) ───────────────
 FIELD_RATE = 240
 ENTITY_MULT = {"Bolag": 1.0, "Beslutsfattare": 1.4, "Fordon": 1.2}
@@ -90,13 +100,19 @@ async def sources_for(market: str):

@app.get("/vehicles/{plate}")
 async def vehicle(plate: str):
-    v = await rdw_vehicle(plate)
+    try:
+        v = await rdw_vehicle(plate)
+    except Exception:
+        v = None
    return v or {"vehicle": None}


@app.get("/screen")
 async def screen(q: str):
-    return await opensanctions_screen(q)
+    try:
+        return await opensanctions_screen(q)
+    except Exception:
+        return {"matches": [], "source": "opensanctions"}


@app.post("/estimates")
@@ -111,9 +127,9 @@ async def create_order(body: OrderIn):
        entity_type=body.config.get("type", "Bolag"),
        fields=body.config.get("fieldIds", []),
        enrichment=body.config.get("enrichmentIds", []),
-        volume=int(body.config.get("volume", 1000)),
+        volume=_coerce_int(body.config.get("volume", 1000), 1000),
        frequency=body.config.get("frequency", "Engångs"),
-        confidence_target=int(body.config.get("confidence", 92)),
+        confidence_target=_coerce_int(body.config.get("confidence", 92), 92),
    ))
    oid = str(uuid.uuid4())
    _ORDERS[oid] = {"order_id": oid, "flow": body.flow, "status": "draft", "config": body.config, **est}
@@ -43,7 +43,12 @@ async def _fetch(source_id: str, key: str) -> CompanyResult | None:
 async def run_job(order_id: str, config: dict[str, Any]) -> dict[str, Any]:
    markets: list[str] = config.get("markets", []) or ["NO"]
    threshold = float(config.get("confidence", 92)) / 100.0
-    seeds: dict[str, list[str]] = config.get("seeds") or DEMO_SEEDS
+    # Use caller-supplied seeds when present (an explicit empty {} is honoured so a
+    # real job is never silently backfilled with DEMO_SEEDS), but treat an explicit
+    # null the same as "missing" -- `config.get("seeds") is not None` avoids a 500
+    # (None.get) on client-controlled `{"seeds": null}`, which the old `... or ...`
+    # idiom tolerated and the `"seeds" in config` form regressed.
+    seeds: dict[str, list[str]] = config["seeds"] if config.get("seeds") is not None else DEMO_SEEDS

    records: list[dict[str, Any]] = []
    per_market: dict[str, int] = {}
@@ -24,10 +24,28 @@ def resolve(records: list[dict[str, Any]], threshold: int = 92) -> list[dict[str
                match = o
                break
        if match:
-            # corroboration: independent source agreeing bumps confidence + level
-            match["confidence"] = min(0.99, match.get("confidence", 0.0) + 0.1)
-            match["agreed_sources"] = match.get("agreed_sources", 1) + 1
            match.setdefault("merged_from", []).append(r.get("source"))
+            # Merge the losing record's per-field provenance regardless of source
+            # novelty below, so the surviving record's provenance always reflects
+            # every contributing record's fields.
+            existing_provenance = match.setdefault("provenance", [])
+            seen_provenance = {(p.get("field_name"), p.get("source_id")) for p in existing_provenance}
+            for p in r.get("provenance", []):
+                key = (p.get("field_name"), p.get("source_id"))
+                if key not in seen_provenance:
+                    existing_provenance.append(p)
+                    seen_provenance.add(key)
+            # Corroboration (confidence/agreed_sources bump) requires an
+            # *independent* source — two hits from the same connector must not
+            # count as two agreeing sources.
+            seen_sources = match.setdefault("_sources_seen", {match.get("source")} - {None})
+            src = r.get("source")
+            if src is not None and src not in seen_sources:
+                match["confidence"] = min(0.99, match.get("confidence", 0.0) + 0.1)
+                match["agreed_sources"] = match.get("agreed_sources", 1) + 1
+                seen_sources.add(src)
        else:
-            out.append({**r, "agreed_sources": 1})
+            out.append({**r, "agreed_sources": 1, "_sources_seen": {r.get("source")} - {None}})
+    for o in out:
+        o.pop("_sources_seen", None)
    return out
@@ -162,6 +162,10 @@ export class DocumentIntelligenceAdapter {
    for (let i = 0; i < maxPollAttempts; i++) {
      await sleep(pollIntervalMs);
      const pollRes = await fetch(operationLocation, { headers: { "Ocp-Apim-Subscription-Key": this.config.apiKey } });
+      if (!pollRes.ok) {
+        const text = await pollRes.text().catch(() => "");
+        throw new Error(`Document Intelligence poll request failed: ${pollRes.status} ${text.slice(0, 300)}`);
+      }
      const json = (await pollRes.json()) as Record<string, unknown>;
      if (json.status === "succeeded") {
        payload = json;
@@ -1,18 +1,28 @@
 /**
 * src/clients/aud0-client.ts
 * ===========================
- * 0pt's thin client for emitting append-only events + lineage edges to AUD0
- * (the SIAX Cloud system of record). Two methods:
+ * 0pt's ONLY path for recording "what happened" to AUD0, the SIAX Cloud
+ * append-only system of record. Every mutating capability in this repo emits
+ * a plain event (`ingestEvent`) and, where the mutation produced or
+ * transformed something, a lineage edge (`ingestLineageEvent`) -- see
+ * docs/ICEBERG_WRITE_BOUNDARY.md's "Event names" table for the full list this
+ * client backs. Two endpoints:
 *   - ingestEvent        -> POST {baseUrl}/v1/aud0/events
 *   - ingestLineageEvent -> POST {baseUrl}/v1/aud0/lineage/events
 *
 * Convention (identical to cl0ud-client.ts / n0d-client.ts / st0re-client.ts
 * / st0re-lakehouse-client.ts): when no base URL is configured the client is
- * a NO-OP — it does not attempt any network call. AUD0 is a best-effort,
- * out-of-band audit sink for 0pt; a missing AUD0_URL (unit tests, local dev)
- * must not turn every capability call into a failed fetch to `undefined`.
- * When a base URL IS configured, events are POSTed as-is (the event object is
- * the wire body) with `Content-Type: application/json`.
+ * a NO-OP -- it does not attempt any network call, it never throws, and it
+ * never blocks a caller. AUD0 is a best-effort, out-of-band audit sink for
+ * 0pt; a missing AUD0_URL (unit tests, local dev) must not turn every
+ * capability call into a failed fetch to `undefined`. That matches AUD0's own
+ * documented stance that an audit emission is a record of what already
+ * happened, not a gate the action waits on.
+ *
+ * HONESTY NOTE: no AUD0_URL has been available to probe in any pass so far --
+ * AUD0 has no live ingestion endpoint wired for 0pt yet. A real deployment
+ * must be pointed at via `aud0BaseUrl`/`AUD0_URL` before events emitted
+ * through this client are durable anywhere.
 */

 export interface Aud0Event {
@@ -27,7 +37,12 @@ export interface Aud0Event {
  resource_id: string;
  /** Risk level L0–L5 per the SIAX Cloud risk taxonomy. */
  risk_level: string;
-  payload: Record<string, unknown>;
+  /**
+   * Free-form event body. Optional and `unknown`-typed so every call site in
+   * this repo type-checks: most emit a structured `Record<string, unknown>`,
+   * some emit nothing at all.
+   */
+  payload?: unknown;
  created_at: string;
  correlation_id?: string;
 }
@@ -44,14 +59,19 @@ export interface Aud0LineageEvent {
  target_id: string;
  /** e.g. "produced" | "derived_from" | "stored_as". */
  lineage_type: string;
-  metadata: Record<string, unknown>;
+  metadata?: unknown;
  created_at: string;
  correlation_id?: string;
 }

+/** Alias so both historical import names resolve to the same shape. */
+export type Aud0EventInput = Aud0Event;
+/** Alias so both historical import names resolve to the same shape. */
+export type Aud0LineageEventInput = Aud0LineageEvent;
+
 export interface Aud0Client {
-  ingestEvent(event: Aud0Event): Promise<void>;
-  ingestLineageEvent(event: Aud0LineageEvent): Promise<void>;
+  ingestEvent(event: Aud0Event): Promise<Aud0Event>;
+  ingestLineageEvent(event: Aud0LineageEvent): Promise<Aud0LineageEvent>;
 }

 export function createAud0Client(baseUrl?: string): Aud0Client {
@@ -59,13 +79,17 @@ export function createAud0Client(baseUrl?: string): Aud0Client {
  return new HttpAud0Client(baseUrl);
 }

-/** No AUD0_URL configured: audit emission is a no-op (see module doc comment). */
+/**
+ * No AUD0_URL configured: audit emission is a no-op (see module doc comment).
+ * Echoes the event back so callers that want the emitted record get the same
+ * value shape they would from the HTTP client.
+ */
 class NoopAud0Client implements Aud0Client {
-  async ingestEvent(_event: Aud0Event): Promise<void> {
-    /* intentional no-op */
+  async ingestEvent(event: Aud0Event): Promise<Aud0Event> {
+    return event;
  }
-  async ingestLineageEvent(_event: Aud0LineageEvent): Promise<void> {
-    /* intentional no-op */
+  async ingestLineageEvent(event: Aud0LineageEvent): Promise<Aud0LineageEvent> {
+    return event;
  }
 }

@@ -77,15 +101,15 @@ class HttpAud0Client implements Aud0Client {
    this.baseUrl = baseUrl.replace(/\/+$/, "");
  }

-  async ingestEvent(event: Aud0Event): Promise<void> {
-    await this.post("/v1/aud0/events", event);
+  async ingestEvent(event: Aud0Event): Promise<Aud0Event> {
+    return this.post("/v1/aud0/events", event);
  }

-  async ingestLineageEvent(event: Aud0LineageEvent): Promise<void> {
-    await this.post("/v1/aud0/lineage/events", event);
+  async ingestLineageEvent(event: Aud0LineageEvent): Promise<Aud0LineageEvent> {
+    return this.post("/v1/aud0/lineage/events", event);
  }

-  private async post(path: string, body: unknown): Promise<void> {
+  private async post<T>(path: string, body: T): Promise<T> {
    const res = await fetch(`${this.baseUrl}${path}`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
@@ -94,5 +118,9 @@ class HttpAud0Client implements Aud0Client {
    if (!res.ok) {
      throw new Error(`AUD0 ${path} error: ${res.status} ${await res.text().catch(() => "")}`);
    }
+    // AUD0 is not guaranteed to echo a JSON body on ingest. Prefer the
+    // server's canonical record when there is one, otherwise fall back to what
+    // we sent -- never fail an already-successful POST on an empty body.
+    return (await res.json().catch(() => body)) as T;
  }
 }
@@ -1,23 +1,37 @@
 /**
 * src/clients/cl0ud-client.ts
 * ============================
- * 0pt's client for the CL0UD control-plane policy decision point:
+ * 0pt's ONLY path to the CL0UD control-plane policy decision point:
 *   evaluatePolicy -> POST {baseUrl}/v1/cl0ud/policies/evaluate
 *
 * Every side-effecting 0pt capability re-consults CL0UD before acting (per
- * docs/PRODUCT_PLAN.md §4.1), so this is the single choke point for that.
+ * docs/PRODUCT_PLAN.md §4.1) -- document-extraction-service.ts,
+ * iceberg-write-service.ts, external-writeback-service.ts -- so this is the
+ * single choke point for that. Never bypassed: a `deny` or
+ * `approval_required` decision always aborts the caller, even when an
+ * upstream gate (e.g. ACT0's own Approval Engine) already ran; see
+ * external-writeback-service.ts's module doc comment for why that specific
+ * re-check matters.
 *
 * Convention (identical to aud0-client.ts / n0d-client.ts / st0re-client.ts):
- * when no base URL is configured the client runs in LOCAL PASS-THROUGH mode —
+ * when no base URL is configured the client runs in LOCAL PASS-THROUGH mode --
 * it returns a deterministic `allow` decision WITHOUT any network call, so
- * unit tests and local dev are hermetic. This is a dev-mode default only; any
- * real deployment MUST set CL0UD_URL so decisions come from the real policy
- * engine. The pass-through never invents a `deny`/`approval_required` — it
- * only ever allows, and it stamps a clearly local-looking decision id.
+ * unit tests and local dev are hermetic. Every 0pt service that calls
+ * evaluatePolicy() treats anything other than "allow" as fatal, so a mock that
+ * defaulted to "deny" would make every unconfigured-CL0UD path unusable;
+ * tests/p0/external-writeback-service.test.ts exercises "deny" and
+ * "approval_required" explicitly via its own fetch stub against an HTTP client
+ * instance, not this pass-through.
+ *
+ * This is a dev-mode default, NOT a security control. Any real deployment MUST
+ * set CL0UD_URL so decisions come from the real policy engine. The pass-through
+ * never invents a `deny`/`approval_required` -- it only ever allows, and it
+ * stamps a clearly local-looking decision id.
 */
 import crypto from "crypto";

-export type PolicyDecision = "allow" | "deny" | "approval_required";
+/** The decision vocabulary itself. */
+export type PolicyDecisionValue = "allow" | "deny" | "approval_required";

 export interface EvaluatePolicyInput {
  tenant_id: string;
@@ -31,14 +45,18 @@ export interface EvaluatePolicyInput {
  correlation_id?: string;
 }

-export interface PolicyResult {
-  decision: PolicyDecision;
+/** The decision record CL0UD returns. */
+export interface PolicyDecision {
+  decision: PolicyDecisionValue;
  decision_id: string;
  reason?: string;
 }

+/** Alias so both historical import names resolve to the same shape. */
+export type PolicyResult = PolicyDecision;
+
 export interface Cl0udClient {
-  evaluatePolicy(input: EvaluatePolicyInput): Promise<PolicyResult>;
+  evaluatePolicy(input: EvaluatePolicyInput): Promise<PolicyDecision>;
 }

 export function createCl0udClient(baseUrl?: string): Cl0udClient {
@@ -48,7 +66,7 @@ export function createCl0udClient(baseUrl?: string): Cl0udClient {

 /** No CL0UD_URL configured: allow-only local pass-through (see module doc comment). */
 class LocalAllowCl0udClient implements Cl0udClient {
-  async evaluatePolicy(_input: EvaluatePolicyInput): Promise<PolicyResult> {
+  async evaluatePolicy(_input: EvaluatePolicyInput): Promise<PolicyDecision> {
    return { decision: "allow", decision_id: `pdec_local_${crypto.randomUUID()}` };
  }
 }
@@ -60,7 +78,7 @@ class HttpCl0udClient implements Cl0udClient {
    this.baseUrl = baseUrl.replace(/\/+$/, "");
  }

-  async evaluatePolicy(input: EvaluatePolicyInput): Promise<PolicyResult> {
+  async evaluatePolicy(input: EvaluatePolicyInput): Promise<PolicyDecision> {
    const res = await fetch(`${this.baseUrl}/v1/cl0ud/policies/evaluate`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
@@ -69,9 +87,13 @@ class HttpCl0udClient implements Cl0udClient {
    if (!res.ok) {
      throw new Error(`CL0UD policy evaluate error: ${res.status} ${await res.text().catch(() => "")}`);
    }
-    const body = (await res.json()) as Partial<PolicyResult>;
+    const body = (await res.json()) as Partial<PolicyDecision>;
+    // FAIL CLOSED. A configured CL0UD that answers 200 with a body missing
+    // `decision` must not be read as an allow -- callers only special-case
+    // "deny"/"approval_required", so an `undefined` decision would slip
+    // through as if it had been permitted.
    return {
-      decision: (body.decision ?? "deny") as PolicyDecision,
+      decision: (body.decision ?? "deny") as PolicyDecisionValue,
      decision_id: body.decision_id ?? `pdec_${crypto.randomUUID()}`,
      reason: body.reason,
    };
@@ -1,21 +1,26 @@
 /**
 * src/clients/n0d-client.ts
 * ==========================
- * 0pt's client for REQUESTING heavy compute jobs from N0D (the Compute OS).
- * 0pt never executes heavy work in-process — it submits an N0D job and holds
- * only the returned `job_id` (docs/11-lakehouse-write-plan.md item 7,
- * docs/P0_QUERY_SOURCE_FLOW.md):
+ * 0pt's ONLY path for REQUESTING heavy compute jobs from N0D (the Compute OS).
+ * 0pt REQUESTS jobs; it never executes heavy work in-process and never owns
+ * N0D's scheduling/node/GPU decisions -- it submits a job and holds only the
+ * returned `job_id` (docs/11-lakehouse-write-plan.md item 7,
+ * docs/P0_QUERY_SOURCE_FLOW.md, and see
+ * `IcebergWriteService.requestIcebergWrite({ heavy: true })` for the concrete
+ * example this client backs):
 *   createJob -> POST {baseUrl}/v1/n0d/jobs
 *
 * Convention (identical to aud0-client.ts / cl0ud-client.ts / st0re-client.ts
 * / st0re-lakehouse-client.ts): when no base URL is configured the client
- * returns a deterministic in-memory MOCK job (id prefixed "mock_job_") with
- * NO network call, so unit tests stay hermetic. A real deployment sets
- * N0D_URL to submit against the live scheduler.
+ * returns a deterministic in-memory MOCK job (id prefixed "mock_job_", the
+ * prefix tests/p0/iceberg-write-service.test.ts and
+ * tests/p0/document-capture-mailbox.test.ts already assert on) with NO network
+ * call, so unit tests stay hermetic. The mock never actually runs anything; a
+ * real deployment sets N0D_URL to submit against the live scheduler.
 */
 import crypto from "crypto";

-export interface CreateJobInput {
+export interface N0dCreateJobInput {
  tenant_id: string;
  project_id: string;
  job_type: string;
@@ -34,16 +39,46 @@ export interface CreateJobInput {
  correlation_id?: string;
 }

-export type N0dJobState = "queued" | "running" | "succeeded" | "failed" | "cancelled";
+/** Alias so both historical import names resolve to the same shape. */
+export type CreateJobInput = N0dCreateJobInput;

-export interface N0dJob extends CreateJobInput {
+/**
+ * N0D's real job lifecycle, taken verbatim from sax3l/n0d's own wire contract
+ * (`packages/schemas/n0d.job.schema.json`, which mirrors
+ * `src/contracts/job.contract.ts`). That schema names the field `status`, not
+ * `state`, and says explicitly: "Do not add 'succeeded' -- that is 'completed'
+ * under a different name." An earlier draft of this client used a five-value
+ * `state` field with `succeeded`; it was wrong against the real contract.
+ */
+export type N0dJobStatus =
+  | "created"
+  | "validated"
+  | "queued"
+  | "scheduled"
+  | "running"
+  | "retrying"
+  | "waiting_for_capacity"
+  | "waiting_for_approval"
+  | "completed"
+  | "completed_with_warnings"
+  | "failed"
+  | "cancelled"
+  | "expired";
+
+/** Alias kept for the older name used elsewhere in this repo's history. */
+export type N0dJobState = N0dJobStatus;
+
+export interface N0dJob extends Partial<N0dCreateJobInput> {
  job_id: string;
-  state: N0dJobState;
+  job_type: string;
+  tenant_id: string;
+  project_id: string;
+  status: N0dJobStatus;
  created_at: string;
 }

 export interface N0dClient {
-  createJob(input: CreateJobInput): Promise<N0dJob>;
+  createJob(input: N0dCreateJobInput): Promise<N0dJob>;
 }

 export function createN0dClient(baseUrl?: string): N0dClient {
@@ -53,11 +88,11 @@ export function createN0dClient(baseUrl?: string): N0dClient {

 /** No N0D_URL configured: returns a deterministic mock job (see module doc comment). */
 class MockN0dClient implements N0dClient {
-  async createJob(input: CreateJobInput): Promise<N0dJob> {
+  async createJob(input: N0dCreateJobInput): Promise<N0dJob> {
    return {
      ...input,
      job_id: `mock_job_${crypto.randomUUID()}`,
-      state: "queued",
+      status: "queued",
      created_at: new Date().toISOString(),
    };
  }
@@ -70,7 +105,7 @@ class HttpN0dClient implements N0dClient {
    this.baseUrl = baseUrl.replace(/\/+$/, "");
  }

-  async createJob(input: CreateJobInput): Promise<N0dJob> {
+  async createJob(input: N0dCreateJobInput): Promise<N0dJob> {
    const res = await fetch(`${this.baseUrl}/v1/n0d/jobs`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
@@ -2,22 +2,35 @@
 * src/clients/st0re-client.ts
 * ============================
 * 0pt's client for the generic ST0RE Artifact registry (snake_case wire
- * shape), distinct from `./st0re-lakehouse-client.ts` (the camelCase
- * /v1/st0re/lakehouse/* table registry). This one registers an artifact's
- * METADATA — a pointer to where the bytes live (provider/bucket/key/region)
- * plus content-type/size/checksum/retention/PII/residency:
- *   createArtifact -> POST {baseUrl}/v1/st0re/artifacts
+ * shape), used by document-capture-service.ts and
+ * document-extraction-service.ts to record what they produced. Distinct from
+ * `./st0re-lakehouse-client.ts` (the camelCase /v1/st0re/lakehouse/* table
+ * registry -- see that file's own doc comment for why the two are kept
+ * separate). This one registers an artifact's METADATA: a pointer to where the
+ * bytes live (provider/bucket/key/region) plus content-type/size/checksum/
+ * retention/PII/residency:
+ *   createArtifact -> POST {baseUrl}/v1/st0re/artifacts/register
 *
- * KNOWN GAP (documented in src/adapters/local-blob-store.ts): ST0RE does not
- * yet expose a raw-bytes upload endpoint for 0pt to call, so the actual bytes
- * are persisted by LocalBlobStore (interim) and only the resulting location
- * is registered here as metadata.
+ * The route is `/v1/st0re/artifacts/register`, NOT `/v1/st0re/artifacts`.
+ * Verified against sax3l/st0re `src/api/routes/artifacts.ts`, where
+ * `/v1/st0re/artifacts` is registered as a GET-only list route and the POST
+ * handler lives on `.../register`. An earlier draft of this client POSTed to
+ * the bare collection path and would not have registered anything.
+ *
+ * KNOWN GAP (documented in src/adapters/local-blob-store.ts and
+ * src/services/document-capture-service.ts's own header): ST0RE does not yet
+ * expose a raw-bytes upload endpoint for 0pt to call, so the actual bytes are
+ * persisted by LocalBlobStore (interim) and only the resulting location is
+ * registered here as metadata.
 *
 * Convention (identical to aud0-client.ts / cl0ud-client.ts / n0d-client.ts /
 * st0re-lakehouse-client.ts): when no base URL is configured the client
 * returns a deterministic in-memory MOCK artifact (id prefixed
- * "mock_artifact_") with NO network call, so unit tests stay hermetic. A real
- * deployment sets ST0RE_URL to register against the live artifact registry.
+ * "mock_artifact_", the prefix tests/p0/document-capture-mailbox.test.ts and
+ * tests/p0/document-extraction-never-fabricates.test.ts assert on) with NO
+ * network call, so unit tests stay hermetic -- but it persists nothing beyond
+ * the current process. A real deployment sets ST0RE_URL to register against
+ * the live artifact registry.
 */
 import crypto from "crypto";

@@ -28,7 +41,7 @@ export interface St0reObjectLocation {
  region?: string;
 }

-export interface CreateArtifactInput {
+export interface St0reArtifactInput {
  tenant_id: string;
  project_id: string;
  artifact_type: string;
@@ -38,8 +51,7 @@ export interface CreateArtifactInput {
  content_type: string;
  size_bytes: number;
  checksum_sha256: string;
-  /** "none" | "low" | "medium" | "high" — kept as string to stay tolerant of ST0RE's own vocabulary. */
-  pii_level: string;
+  pii_level: "none" | "low" | "medium" | "high";
  retention_policy: string;
  data_residency: string;
  /** Risk level L0–L5 per the SIAX Cloud risk taxonomy. */
@@ -47,13 +59,16 @@ export interface CreateArtifactInput {
  correlation_id?: string;
 }

-export interface St0reArtifact extends CreateArtifactInput {
+/** Alias so both historical import names resolve to the same shape. */
+export type CreateArtifactInput = St0reArtifactInput;
+
+export interface St0reArtifact extends St0reArtifactInput {
  artifact_id: string;
  created_at: string;
 }

 export interface St0reClient {
-  createArtifact(input: CreateArtifactInput): Promise<St0reArtifact>;
+  createArtifact(input: St0reArtifactInput): Promise<St0reArtifact>;
 }

 export function createSt0reClient(baseUrl?: string): St0reClient {
@@ -63,7 +78,7 @@ export function createSt0reClient(baseUrl?: string): St0reClient {

 /** No ST0RE_URL configured: returns a deterministic mock artifact (see module doc comment). */
 class MockSt0reClient implements St0reClient {
-  async createArtifact(input: CreateArtifactInput): Promise<St0reArtifact> {
+  async createArtifact(input: St0reArtifactInput): Promise<St0reArtifact> {
    return {
      ...input,
      artifact_id: `mock_artifact_${crypto.randomUUID()}`,
@@ -79,14 +94,14 @@ class HttpSt0reClient implements St0reClient {
    this.baseUrl = baseUrl.replace(/\/+$/, "");
  }

-  async createArtifact(input: CreateArtifactInput): Promise<St0reArtifact> {
-    const res = await fetch(`${this.baseUrl}/v1/st0re/artifacts`, {
+  async createArtifact(input: St0reArtifactInput): Promise<St0reArtifact> {
+    const res = await fetch(`${this.baseUrl}/v1/st0re/artifacts/register`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(input),
    });
    if (!res.ok) {
-      throw new Error(`ST0RE create-artifact error: ${res.status} ${await res.text().catch(() => "")}`);
+      throw new Error(`ST0RE artifact registration error: ${res.status} ${await res.text().catch(() => "")}`);
    }
    return (await res.json()) as St0reArtifact;
  }
@@ -1,60 +1,67 @@
 /**
 * src/services/dataset-service.ts
 * ================================
- * Owns 0pt.dataset.schema.v1 — the registry of 0pt datasets (raw / enriched /
- * curated / feature outputs). In-memory reference implementation (same
- * convention as the other 0pt services in this repo; a real deployment backs
- * this with `opt_datasets`).
+ * Owns 0pt.dataset.schema.v1 — the registry of 0pt datasets (raw / structured
+ * / enriched / curated / feature / derived outputs). This is the thing
+ * `DatasetIcebergMappingService` (src/services/dataset-iceberg-mapping-service.ts)
+ * and `IcebergWriteService` (src/services/iceberg-write-service.ts) look a
+ * `dataset_id` up against before pointing an Iceberg table mapping or a write
+ * at it.
 *
- * Consumed by:
- *   - dataset-iceberg-mapping-service.ts (getDataset -> does the dataset exist
- *     before we map it to an Iceberg table?)
- *   - iceberg-write-service.ts           (getDataset -> guard the write path)
+ * Deliberately small: it is a reference/registry entry, NOT dataset content,
+ * schema, or quality state — see docs/ICEBERG_WRITE_BOUNDARY.md for that
+ * boundary. In-memory reference implementation (same convention as the other
+ * 0pt services in this repo; a real deployment backs this with `opt_datasets`).
+ *
+ * In-memory scope: each `new DatasetService()` owns its own registry, the same
+ * pre-existing limitation source-service.ts and every other P0 registry
+ * service documents (docs/P0_QUERY_SOURCE_FLOW.md's "Known gaps"). Callers
+ * that need a shared view across API routes pass an existing instance in via
+ * the `datasetService` constructor option — see
+ * src/services/lakehouse-mapping-registry.ts, which does exactly that for the
+ * whole app/api/0pt/lakehouse/mappings route group.
 *
 * Registering a dataset emits a best-effort AUD0 `0pt.dataset_registered`
 * event; with no AUD0_URL configured that emission is a no-op (see
 * aud0-client.ts), so this stays hermetic in tests and local dev.
 */
 import { createAud0Client, type Aud0Client } from "../clients/aud0-client";
+import type { Dataset, DatasetStatus, DatasetType, CreateDatasetInput } from "../types/dataset";

-export type DatasetType = "raw" | "enriched" | "curated" | "feature" | "derived";
-export type DatasetStatus = "active" | "deprecated" | "archived";
+// Re-exported so the historical `import { Dataset, DatasetType, ... } from
+// "./dataset-service"` call shape keeps working alongside the canonical
+// `../types/dataset` module.
+export type { Dataset, DatasetStatus, DatasetType, CreateDatasetInput };
+/** Alias so both historical input-type names resolve to the same shape. */
+export type RegisterDatasetInput = CreateDatasetInput;

-export interface Dataset {
+/**
+ * Storage shape: nullable columns, exactly as the eventual `opt_datasets`
+ * table would hold them. `toDataset()` converts back to the `Dataset` DTO.
+ */
+interface DatasetRecord {
  dataset_id: string;
  tenant_id: string;
  project_id: string;
  name: string;
-  dataset_type: DatasetType;
-  description?: string;
-  status: DatasetStatus;
-  correlation_id?: string;
+  dataset_type: string;
+  status: string;
+  description: string | null;
+  correlation_id: string | null;
  created_at: string;
-  updated_at?: string;
-  created_by?: string;
-}
-
-export interface RegisterDatasetInput {
-  dataset_id: string;
-  tenant_id: string;
-  project_id: string;
-  name: string;
-  dataset_type: DatasetType;
-  description?: string;
-  status?: DatasetStatus;
-  correlation_id?: string;
-  created_by?: string;
+  updated_at: string | null;
+  created_by: string | null;
 }

 export class DatasetService {
-  private datasets: Map<string, Dataset> = new Map();
+  private datasets: Map<string, DatasetRecord> = new Map();
  private aud0: Aud0Client;

  constructor(aud0BaseUrl?: string) {
    this.aud0 = createAud0Client(aud0BaseUrl);
  }

-  async registerDataset(input: RegisterDatasetInput): Promise<Dataset> {
+  async registerDataset(input: CreateDatasetInput): Promise<Dataset> {
    if (this.datasets.has(input.dataset_id)) {
      throw new Error(`Dataset ${input.dataset_id} already exists`);
    }
@@ -63,50 +70,76 @@ export class DatasetService {
    }

    const now = new Date().toISOString();
-    const dataset: Dataset = {
+    const record: DatasetRecord = {
      dataset_id: input.dataset_id,
      tenant_id: input.tenant_id,
      project_id: input.project_id,
      name: input.name,
      dataset_type: input.dataset_type,
-      description: input.description,
      status: input.status ?? "active",
-      correlation_id: input.correlation_id,
+      description: input.description ?? null,
+      correlation_id: input.correlation_id ?? null,
      created_at: now,
-      created_by: input.created_by,
+      updated_at: null,
+      created_by: input.created_by ?? null,
    };
-    this.datasets.set(dataset.dataset_id, dataset);
+    this.datasets.set(record.dataset_id, record);

+    // 0pt.dataset_registered -- same "no mutation without an evented trail"
+    // doctrine every other P0 registry service in this repo follows
+    // (SourceService.createSource, SourceRatePolicyService.createSourceRatePolicy).
    await this.aud0.ingestEvent({
-      event_id: `evt_0pt_dataset_registered_${dataset.dataset_id}`,
+      event_id: `evt_0pt_dataset_registered_${record.dataset_id}`,
      event_type: "0pt.dataset_registered",
-      tenant_id: dataset.tenant_id,
-      project_id: dataset.project_id,
-      actor_id: dataset.created_by ?? "system",
+      tenant_id: record.tenant_id,
+      project_id: record.project_id,
+      actor_id: record.created_by ?? "system",
      app_id: "0pt",
      capability_id: "0pt.register_dataset",
      resource_type: "dataset",
-      resource_id: dataset.dataset_id,
+      resource_id: record.dataset_id,
      risk_level: "L2",
-      payload: { dataset_type: dataset.dataset_type, name: dataset.name },
+      payload: { name: record.name, dataset_type: record.dataset_type },
      created_at: now,
-      correlation_id: dataset.correlation_id,
+      correlation_id: record.correlation_id ?? undefined,
    });

-    return dataset;
+    return this.toDataset(record);
  }

  async getDataset(datasetId: string): Promise<Dataset> {
-    const dataset = this.datasets.get(datasetId);
-    if (!dataset) throw new Error(`Dataset ${datasetId} not found`);
-    return dataset;
+    const record = this.datasets.get(datasetId);
+    if (!record) throw new Error(`Dataset ${datasetId} not found`);
+    return this.toDataset(record);
  }

-  async listDatasets(filter?: { tenant_id?: string; project_id?: string; dataset_type?: DatasetType }): Promise<Dataset[]> {
+  async listDatasets(filter?: {
+    tenant_id?: string;
+    project_id?: string;
+    dataset_type?: DatasetType;
+    status?: DatasetStatus;
+  }): Promise<Dataset[]> {
    let results = Array.from(this.datasets.values());
-    if (filter?.tenant_id) results = results.filter((d) => d.tenant_id === filter.tenant_id);
-    if (filter?.project_id) results = results.filter((d) => d.project_id === filter.project_id);
-    if (filter?.dataset_type) results = results.filter((d) => d.dataset_type === filter.dataset_type);
-    return results;
+    if (filter?.tenant_id) results = results.filter((r) => r.tenant_id === filter.tenant_id);
+    if (filter?.project_id) results = results.filter((r) => r.project_id === filter.project_id);
+    if (filter?.dataset_type) results = results.filter((r) => r.dataset_type === filter.dataset_type);
+    if (filter?.status) results = results.filter((r) => r.status === filter.status);
+    return results.map((r) => this.toDataset(r));
+  }
+
+  private toDataset(r: DatasetRecord): Dataset {
+    return {
+      dataset_id: r.dataset_id,
+      tenant_id: r.tenant_id,
+      project_id: r.project_id,
+      name: r.name,
+      dataset_type: r.dataset_type as DatasetType,
+      status: r.status as DatasetStatus,
+      description: r.description ?? undefined,
+      correlation_id: r.correlation_id ?? undefined,
+      created_at: r.created_at,
+      updated_at: r.updated_at ?? undefined,
+      created_by: r.created_by ?? undefined,
+    };
  }
 }
@@ -18,7 +18,11 @@
 * `writeExternalRecord` runs, a human has already approved the write -- this
 * service still re-checks CL0UD policy (per docs/PRODUCT_PLAN.md section
 * 4.1's hard rule that CL0UD is always re-consulted, the same rule
- * quality-check-service.ts/document-extraction-service.ts already follow),
+ * document-extraction-service.ts already follows -- confirmed by grepping
+ * this repo's src/services/ for evaluatePolicy()/Cl0udClient usage; the
+ * only other real service that does the same is iceberg-write-service.ts.
+ * An earlier version of this comment also cited `quality-check-service.ts`
+ * here; that file does not exist anywhere in this repo),
 * but does not itself re-verify the upstream Approval record (ACT0 owns
 * approvals; 0pt's own capability boundary is "did CL0UD say yes for THIS
 * call", same separation of concerns every other 0pt service in this repo
@@ -0,0 +1,19 @@
+import { DatasetService } from "./dataset-service";
+import { DatasetIcebergMappingService } from "./dataset-iceberg-mapping-service";
+import { IcebergWriteService } from "./iceberg-write-service";
+
+/**
+ * Shared singleton instances for the lakehouse-mapping route group
+ * (app/api/0pt/lakehouse/mappings/*). Previously each route file in that
+ * group instantiated its own DatasetService/DatasetIcebergMappingService/
+ * IcebergWriteService, so a mapping created via POST /mappings was invisible
+ * to GET /mappings/{id} and to POST /mappings/{id}/writes within the same
+ * server process (each held a distinct in-memory Map). Constructing all
+ * three here once, wired together, and importing them everywhere fixes that
+ * -- matching the in-memory-per-module convention this repo already uses
+ * elsewhere (see document-capture-service.ts's own singleton note), just
+ * applied consistently across this route group instead of per-file.
+ */
+export const datasetService = new DatasetService();
+export const mappingService = new DatasetIcebergMappingService({ datasetService });
+export const writeService = new IcebergWriteService({ datasetService, mappingService });
@@ -1,25 +1,53 @@
 /**
 * src/services/source-service.ts
 * ===============================
- * Owns 0pt.source.schema.v1 — the registry of upstream data sources
- * (databases, crawl domains, APIs, file drops). In-memory reference
- * implementation (same convention as the other 0pt services in this repo:
- * each API route file constructs its own instance; a real deployment backs
- * this with `opt_sources` — sql/002_p0_dataset_quality.sql).
+ * Owns 0pt.source.schema.v1 — the per-tenant registry of upstream data
+ * sources (databases, crawl domains, APIs, file drops). This is the registry
+ * `SourceQueryService.querySource()` (src/services/source-query-service.ts)
+ * and `SourceRatePolicyService` (src/services/source-rate-policy-service.ts)
+ * both look a `source_id` up against — see docs/P0_QUERY_SOURCE_FLOW.md.
 *
- * Consumed by:
- *   - source-query-service.ts     (getSource -> is this source queryable?)
- *   - source-rate-policy-service.ts (getSource -> does the source exist?)
+ * Deliberately small and in-memory, same "pure core, thin registry" shape
+ * every other P0 service in this repo already uses; a real deployment backs
+ * this with `opt_sources`. In-memory scope: each `new SourceService()` owns
+ * its own registry — the pre-existing limitation docs/P0_QUERY_SOURCE_FLOW.md's
+ * "Known gaps" section documents (a Source registered via one API route module
+ * is not yet visible to another route module in the same running process).
+ * Callers that need a shared view pass an existing instance in via the
+ * `sourceService` constructor option, exactly like SourceQueryService and
+ * SourceRatePolicyService already do.
 *
- * Registering a source emits a best-effort AUD0 `0pt.source_registered`
- * event; with no AUD0_URL configured that emission is a no-op (see
- * aud0-client.ts), so this stays hermetic in tests and local dev.
+ * Registering a source emits a best-effort AUD0 `0pt.source_created` event —
+ * the same "no mutation without an evented trail" doctrine every other P0
+ * registry service follows. With no AUD0_URL configured that emission is a
+ * no-op (see aud0-client.ts), so this stays hermetic in tests and local dev.
 */
 import { createAud0Client, type Aud0Client } from "../clients/aud0-client";
-import type { CreateSourceInput, Source } from "../types/source";
+import type { CreateSourceInput, Source, SourceStatus, SourceType } from "../types/source";
+
+/**
+ * Storage shape: nullable columns, exactly as the eventual `opt_sources` table
+ * would hold them. `toSource()` converts back to the `Source` DTO (undefined
+ * rather than null) so callers never have to handle both.
+ */
+interface SourceRecord {
+  source_id: string;
+  tenant_id: string;
+  project_id: string;
+  source_type: string;
+  name: string;
+  adapter_id: string | null;
+  access: string | null;
+  description: string | null;
+  status: string;
+  correlation_id: string | null;
+  created_at: string;
+  updated_at: string | null;
+  created_by: string | null;
+}

 export class SourceService {
-  private sources: Map<string, Source> = new Map();
+  private sources: Map<string, SourceRecord> = new Map();
  private aud0: Aud0Client;

  constructor(aud0BaseUrl?: string) {
@@ -35,51 +63,82 @@ export class SourceService {
    }

    const now = new Date().toISOString();
-    const source: Source = {
+    const record: SourceRecord = {
      source_id: input.source_id,
      tenant_id: input.tenant_id,
      project_id: input.project_id,
      source_type: input.source_type,
      name: input.name,
-      adapter_id: input.adapter_id,
-      description: input.description,
+      adapter_id: input.adapter_id ?? null,
+      access: input.access ?? null,
+      description: input.description ?? null,
      status: input.status ?? "active",
-      correlation_id: input.correlation_id,
+      correlation_id: input.correlation_id ?? null,
      created_at: now,
-      created_by: input.created_by,
+      updated_at: null,
+      created_by: input.created_by ?? null,
    };
-    this.sources.set(source.source_id, source);
+    this.sources.set(record.source_id, record);

    await this.aud0.ingestEvent({
-      event_id: `evt_0pt_source_registered_${source.source_id}`,
-      event_type: "0pt.source_registered",
-      tenant_id: source.tenant_id,
-      project_id: source.project_id,
-      actor_id: source.created_by ?? "system",
+      event_id: `evt_0pt_source_created_${record.source_id}`,
+      event_type: "0pt.source_created",
+      tenant_id: record.tenant_id,
+      project_id: record.project_id,
+      actor_id: record.created_by ?? "system",
      app_id: "0pt",
-      capability_id: "0pt.register_source",
+      capability_id: "0pt.create_source",
      resource_type: "source",
-      resource_id: source.source_id,
+      resource_id: record.source_id,
      risk_level: "L2",
-      payload: { source_type: source.source_type, adapter_id: source.adapter_id ?? null, name: source.name },
+      payload: {
+        source_type: record.source_type,
+        name: record.name,
+        adapter_id: record.adapter_id,
+        access: record.access,
+      },
      created_at: now,
-      correlation_id: source.correlation_id,
+      correlation_id: record.correlation_id ?? undefined,
    });

-    return source;
+    return this.toSource(record);
  }

  async getSource(sourceId: string): Promise<Source> {
-    const source = this.sources.get(sourceId);
-    if (!source) throw new Error(`Source ${sourceId} not found`);
-    return source;
+    const record = this.sources.get(sourceId);
+    if (!record) throw new Error(`Source ${sourceId} not found`);
+    return this.toSource(record);
  }

-  async listSources(filter?: { tenant_id?: string; project_id?: string; source_type?: Source["source_type"] }): Promise<Source[]> {
+  async listSources(filter?: {
+    tenant_id?: string;
+    project_id?: string;
+    source_type?: SourceType;
+    status?: SourceStatus;
+  }): Promise<Source[]> {
    let results = Array.from(this.sources.values());
-    if (filter?.tenant_id) results = results.filter((s) => s.tenant_id === filter.tenant_id);
-    if (filter?.project_id) results = results.filter((s) => s.project_id === filter.project_id);
-    if (filter?.source_type) results = results.filter((s) => s.source_type === filter.source_type);
-    return results;
+    if (filter?.tenant_id) results = results.filter((r) => r.tenant_id === filter.tenant_id);
+    if (filter?.project_id) results = results.filter((r) => r.project_id === filter.project_id);
+    if (filter?.source_type) results = results.filter((r) => r.source_type === filter.source_type);
+    if (filter?.status) results = results.filter((r) => r.status === filter.status);
+    return results.map((r) => this.toSource(r));
+  }
+
+  private toSource(r: SourceRecord): Source {
+    return {
+      source_id: r.source_id,
+      tenant_id: r.tenant_id,
+      project_id: r.project_id,
+      source_type: r.source_type as SourceType,
+      name: r.name,
+      adapter_id: r.adapter_id ?? undefined,
+      access: (r.access as Source["access"]) ?? undefined,
+      description: r.description ?? undefined,
+      status: r.status as SourceStatus,
+      correlation_id: r.correlation_id ?? undefined,
+      created_at: r.created_at,
+      updated_at: r.updated_at ?? undefined,
+      created_by: r.created_by ?? undefined,
+    };
  }
 }
@@ -0,0 +1,44 @@
+// 0pt.dataset.schema.v1
+//
+// A dataset 0pt produces or manages -- the thing `dataset_iceberg_mapping`
+// (src/types/dataset-iceberg-mapping.ts) points at, and the thing
+// IcebergWriteService (src/services/iceberg-write-service.ts) writes through
+// ST0RE's table registry on behalf of. This type intentionally stays small:
+// it is a reference/registry entry, not a copy of dataset content, schema,
+// or quality state (that boundary is documented in
+// docs/ICEBERG_WRITE_BOUNDARY.md -- 0pt owns dataset production, but this
+// specific type is only what DatasetIcebergMappingService/IcebergWriteService
+// need to confirm a dataset_id is real before pointing a table at it).
+
+// Union of both dataset-type vocabularies that existed in this repo's two
+// remotes ("structured" from one, "feature"/"derived" from the other);
+// nothing is dropped by the GitHub<->Gitea unification merge.
+export type DatasetType = "raw" | "structured" | "enriched" | "curated" | "feature" | "derived";
+
+export type DatasetStatus = "active" | "archived" | "deprecated";
+
+export interface Dataset {
+  dataset_id: string;
+  tenant_id: string;
+  project_id: string;
+  name: string;
+  dataset_type: DatasetType;
+  status: DatasetStatus;
+  description?: string;
+  correlation_id?: string;
+  created_at: string;
+  updated_at?: string;
+  created_by?: string;
+}
+
+export interface CreateDatasetInput {
+  dataset_id: string;
+  tenant_id: string;
+  project_id: string;
+  name: string;
+  dataset_type: DatasetType;
+  description?: string;
+  status?: DatasetStatus;
+  correlation_id?: string;
+  created_by?: string;
+}
@@ -8,12 +8,37 @@
 * (src/services/source-query-service.ts), which reads `source_type` +
 * `adapter_id` to decide whether a Source is queryable.
 *
+ * This is a DIFFERENT, newer entity than the static provenance catalog in
+ * docs/03-data-model.md's `dim_source` table (the ~9-row list of national
+ * registries served today by GET /api/sources) -- this Source is a per-tenant
+ * registration of something 0pt can actually connect to. See
+ * docs/P0_QUERY_SOURCE_FLOW.md and src/services/source-query-service.ts, the
+ * first real consumer.
+ *
 * `adapter_id` is the seam that lets a "database" source name the concrete
 * driver 0pt should use for it (today only "fabric_onelake_sql" is wired on
 * the synchronous path — see source-query-service.ts).
+ *
+ * `access` mirrors dim_source.access (docs/03-data-model.md) so a Source
+ * registered here can still be reported against the same legal-sourcing
+ * vocabulary CLAUDE.md §1 requires everywhere in this repo.
+ */
+
+/**
+ * Union of both source-type vocabularies that existed in this repo's two
+ * remotes; nothing is dropped by the unification merge.
 */
 export type SourceType = "database" | "file" | "web" | "api" | "stream" | "manual";
-export type SourceStatus = "active" | "paused" | "archived";
+
+/**
+ * Union of both status vocabularies. "archived" and "deprecated" both survive
+ * the unification merge -- they were introduced independently and no code
+ * treats either as canonical.
+ */
+export type SourceStatus = "active" | "paused" | "archived" | "deprecated";
+
+/** Legal-sourcing vocabulary, mirroring dim_source.access. */
+export type SourceAccess = "api" | "bulk" | "authorized_web" | "licensed";

 export interface Source {
  source_id: string;
@@ -21,8 +46,15 @@ export interface Source {
  project_id: string;
  source_type: SourceType;
  name: string;
-  /** Concrete driver id for this source, e.g. "fabric_onelake_sql". Optional: not every source is directly queryable. */
+  /**
+   * Identifies which concrete adapter implementation this source is queried
+   * through (e.g. "fabric_onelake_sql" -- src/adapters/fabric-onelake-adapter.ts).
+   * Required in practice for source_type "database"; optional/unused for other
+   * types until they grow a synchronous query path of their own.
+   */
  adapter_id?: string;
+  /** Mirrors dim_source.access (docs/03-data-model.md). */
+  access?: SourceAccess;
  description?: string;
  status: SourceStatus;
  correlation_id?: string;
@@ -38,6 +70,7 @@ export interface CreateSourceInput {
  source_type: SourceType;
  name: string;
  adapter_id?: string;
+  access?: SourceAccess;
  description?: string;
  status?: SourceStatus;
  correlation_id?: string;