Give CORA's own background work a real door, not the shrug that names no one

[xmap]

Item 2 from the deferred list on #759: give CORA's own background work a real, nameable door, so it stops being lumped in with "unspecified" the same way an unclassified caller would be.

The gap

Every real HTTP route and MCP tool resolves a proper surface_id, the Authorize port's answer to "which door did this arrive through." But roughly ten places in CORA's own composition-root code call a handler directly, in-process, with no surface_id at all, so it silently falls through to the nil sentinel. That makes internal work indistinguishable from any other unclassified caller, and there was no way to write a Policy rule that treats "a person clicking a button" differently from "CORA's own RunWitness agent doing routine background work," because both arrived through the same unlabeled door.

What ships

A new closed-enum SurfaceKind.IN_PROCESS, a fourth seeded Surface alongside the existing three, and every identified in-process call site wired to it unconditionally:

• RunWitnessRecorder's four handler calls (record_witnessed_run, truncate_run, record_witnessed_run_outcome, the list_runs inside its open-capture rebuild)
• The two capture readers it constructs (CaptureBaselineReader, CaptureProgressFeeder)
• CaptureScanIngestor
• DelegatingInferenceRecorder (the production InferenceRecorder port implementor — fixing it here covers every caller that goes through the port, including two agent subscribers that call the port interface and never touch surface_id themselves)
• SimObservationFeeder (the shipped reference feeder deployments copy for their real EPICS/tomoStream feeders — not wired into the live app today, but worth wiring correctly since it's the example other code follows)
• promote_seeded_fleet (a one-time operator CLI entrypoint — still the same door as an agent tick loop, just a different principal on the other side; Surface answers "which door," not "who")

No new Settings knob, unlike the Conduit change in #759 that this is the sibling of. That one added an opt-in because redirecting which conduit governs is a behavior change worth gating. This one is a factual correction: these calls always originated in-process, so naming that fact isn't something a deployment would want to opt out of.

A naming correction along the way

I designed this with SurfaceKind.INTERNAL. A naming reviewer caught two real problems before it shipped: read aloud inside a transport enum, "internal" suggests "internal network," not "no transport" — and it collides with an unrelated existing domain value, Operation.acquisitions.trigger_mode's "Internal" camera-trigger source. The fix, IN_PROCESS, also happens to be the phrase this codebase already uses for the same referent in roughly twenty other places. Renamed everywhere before committing: the enum member, the SYSTEM_IN_PROCESS_SURFACE_ID constant, the migration (file and content), the new test file, and every reference across production and test code.

What this changes and doesn't, for an already-shadowed deployment

Under the starter Policy currently shadowing at 2-BM (bound to the HTTP surface), this changes the shadow log's recorded near-miss reason from "surface: nil vs HTTP" to "surface: in_process vs HTTP" — still a mismatch, so the Allow/Deny outcome for every existing deployment is unchanged. What changes is that internal work becomes a distinct, nameable category a future Policy can actually govern, instead of being lumped in with every other unspecified caller.

Deliberately excluded from _SURFACE_KIND_BY_UUID (the map the observability layer uses to resolve a Surface's kind for HTTP-arriving requests) — the same reasoning that already excludes MCP_STDIO: in-process work is by definition never reachable through the HTTP middleware.

Process note

Designed by Opus, implemented by a Sonnet subagent working from a fully-specified brief (exact call sites, naming decisions, migration pattern, testing bar). The subagent's own naming-review pass caught the INTERNAL → IN_PROCESS issue above; I applied that rename and ran the full independent verification pass myself before this went anywhere.

Verification

Unit + architecture: 49,102 passed. Contract: 3,436 passed. Full integration tier: 1,367 passed, including a new test that applies the migration against a real Postgres testcontainer and confirms the Surface folds to SurfaceKind.IN_PROCESS. Mutation-verified in both directions myself: reverting one wired call site to omitted, and reverting the HTTP-reachability exclusion, each turns exactly its paired test red. ruff, pyright, tach, make docs-build all clean. OpenAPI snapshot regenerated (the kind enum and its description text both changed).

Also swept the rest of the codebase for any handler call passing principal_id without surface_id that the original brief might have missed: found none. Everything that looked like a candidate on a broader grep turned out to already be either a surface-transparent pass-through (conductor.py, which threads a real surface_id parameter), a call through the InferenceRecorder port interface (correctly needs no surface_id of its own now that the implementor is fixed), or a genuinely unwired/dead code path (_experiment_steerer.py's steer_experiment, which has no caller anywhere in src/ or tests/ today and will need its own surface_id threading whenever it's actually wired to something — noted here for whoever does that, out of scope for this PR).

🤖 Generated with Claude Code

[github-actions]

Coverage report

Click to see where and how coverage changed

File	Statements	Missing	Coverage	Coverage (new stmts)	Lines missing
apps/api/src/cora/agent
promote_seeded_fleet.py
apps/api/src/cora/api
_capture_baseline_reader.py					196
_capture_progress_feeder.py					228
_capture_scan_ingestor.py
_inference_recorder.py
_run_witness.py					981, 1136, 1186
apps/api/src/cora/infrastructure
routing.py
schema_version.py
apps/api/src/cora/run/adapters
sim_observation_feeder.py
apps/api/src/cora/trust
__init__.py
_bootstrap.py
apps/api/src/cora/trust/aggregates/surface
surface_kind.py
Project Total

This report was generated by python-coverage-comment-action