0pt/docs/12-edge-capability-api.md

# 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.