feat(runtime): bind prepared Files work to the selected execution route

[dokterdok]

Accept shared files only on the route that will execute them

If a shared file is accepted for one Bot but credential selection or fallback sends the turn to another runtime, readiness and execution can disagree about where that file is allowed to go. Resolving the real route inside a database writer would also perform blocking, effectful work at the wrong boundary.

This public source-review prerequisite prepares the actual route outside writer fences, binds it to one owner/session/request/operation, and lets readiness and execution consume that same selection. Expired or displaced selections are released; unsupported transports are refused without changing provider preference or fallback order.

This is the Layer 2 execution contract supporting Layer 3 cross-gateway work and Layer 5 shared Files/Output work in #97681, not a complete Files receiver. It is based on #106742 (485d5f6848c25); the live Route owner #100016 is at 4c0088b999f64d2ee10d53da28fc8f0af0c0b31e (the 43e4d4e6 integration checkpoint below is historical, not a test of this current head). #116137 privacy, #116466 replay indexing and #111362 custody remain separate. Current-product Files #98072 and Output #99159 are now published, but that does not establish full feature or deployment acceptance. The evidence below remains tied to its recorded revisions.

Recorded results are 73 owner cases within 107 focused composed cases, not additive. Selections last at most 30 seconds, never promise inference success, and passive unbound probes remain unavailable. Native Files, named/standalone receivers, lifecycle recovery, large-index operability, hosted CI and live/deployment acceptance remain separate gates.

Technical scope, validation and source provenance

The evidence below records previously reported, revision-bound results; this editorial update adds no test, CI or deployment evidence.

Check the selected execution route before accepting shared files

A gateway configuration does not tell us which transport will actually execute a turn. Credential selection and the existing fallback chain can choose different runtimes from identical config bytes. Calling that resolver from a capability check or while holding a database writer would also introduce side effects and blocking work in the wrong place.

This runtime prerequisite separates effectful route preparation from read-only readiness and lets the actual execution path consume the same prepared selection. It supports the Files/RoomLink work in #97681 without changing provider preference, fallback order or ordinary text/native-image policy.

What changes

• Reuse the real selection ladder, but defer session/recovery-cache publication until its captured inputs still match. Coordinate with the actual model, reasoning, tier and reset writers.
• Bind prepared material to the exact owner, profile, session, request and operation. Readiness exposes only a small secret-free result; it does not resolve credentials or construct an agent.
• Bound each operation to a non-renewable lifetime of at most 30 seconds, shortened by applicable credential expiry. Supersession, cancellation, close and consumption release private validation snapshots.
• Check the real resulting transport before prepared Files execution. Unsupported native, external and virtual transports are refused—not silently skipped to force a different provider.
• Provide existing-connection read/write fences that do not reopen an owner. The writer preserves quarantine/generation checks and does not blame healthy session storage for an error from a dependent store.

These are operation snapshots, not long-lived account pins or a promise that inference will succeed. There is no positive readiness cache, background refresher or new wire credential field.

Separate ownership and dependencies

14 paths: 11 production files and three test files, +1,873/−83, based directly on #106742 at 485d5f6848c2598ca00fa7704e50e8ae66d0983a.

• fix(runtime): preserve private Files input and live session context #116137 owns private Files model-input/live-context/persistence behavior. Its implementation is not copied here.
• fix(groups): keep cross-gateway tasks on their intended route #100016 owns authenticated invitation/NEW callers and the canonical session-creation callback. The live fix(groups): keep cross-gateway tasks on their intended route #100016 head is 4c0088b999f64d2ee10d53da28fc8f0af0c0b31e. The earlier Route integration checkpoint 43e4d4e64a2ea06a84c1af426bb342abb8a63331 remains historical evidence; the 107-case composition below is not a test of the live Route head, nor proof of hosted CI, native/live acceptance or full Files/Output completion.
• feat(groups): share Group Chat files across gateways #98072/feat(runtime): keep shared inputs available for accepted work #111362 own Files staging and custody. The held-writer consumer remains separate.
• fix(runtime): retain canonical RoomLink attempt identity for bounded replay checks #116466 owns the logical-attempt index needed by Route replay; no index implementation is included here.
• feat(groups): let Bots hand off files in hosted Group Chats #99159 remains the separate Output owner. feat(groups): share Group Chat files across gateways #98072 Files and feat(groups): let Bots hand off files in hosted Group Chats #99159 Output are published as separate owners; their dependent compositions and native/live acceptance remain subject to their own delivery gates.

This PR is a source prerequisite, not a complete Files receiver. Passive probes without an operation binding remain unavailable. Native Files, named/standalone receiver parity, full lifecycle recovery and large-index migration operability remain separate gates. No deployment or live enablement is proposed.

Verification

73 lower selection cases passed directly on the historical eight-commit owner-only candidate. They exercise the real selection/control paths with inert external credential boundaries: same-config fallback, precedence, scope/drift, expiry, supersession, writer coordination and secret lifetime.

The earlier accepted-tree composition at 012315198757fb0e3f0d835c398630306698eff6 passed 107 distinct focused cases across six files, including actual Files ingress/session creation, owner-writer lifetime and cross-connection error controls. That historical proof is not an exact-current-#100016 composition. The 73 owner cases overlap that total. Later integration tests depend on their real separately owned consumers; they were not replaced with narrower fixtures to manufacture standalone coverage.

Canonical runner, two workers, zero retries and private test homes. No live provider, model, gateway, native process or migration ran. Existing bounded reviews and parent residual verification cover the source slices; this recut preserves their exact owned semantics, not a new whole-programme review.

Exact revisions, reconstruction and attribution

Historical eight-commit candidate: b43410e8c6accc9bc404efa3eced7ea126aa9887, tree eda3fdfafca902623311344e624212251f8e5484. Current nine-commit owner head: 8c36f8dd3130397c6388d7517d51a0ed8c700279, adding the bounded live external-writer lifetime correction in hermes_state.py. The recorded tests below are not a fresh run on this later head.

Eight source-preserving commits sit directly above the common base, without privacy/index ancestry. Original authors, author dates and complete messages are preserved with Source-Commit trails. Every intermediate tree and source message remained identical.

Bound proof: 012315198757fb0e3f0d835c398630306698eff6, tree 2dbcd4c02091ede120c7a811c06db57404a9de05, exactly the accepted local phase2B tree. It contains the declared separate Route/Files/Output/custody/index implementations and proof-only fixtures. The recorded eight-commit owner delta can be removed/reapplied to reconstruct that historical tree. This is not a claim that all public branches merge automatically without integration resolution.

Hosted CI is separate from the local results. That historical proof does not settle current Files/Output integration, live/native testing or deployment.