starred/orca
1
0
Fork 0
mirror of https://github.com/stablyai/orca.git synced 2026-10-02 00:02:05 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: record structured native-chat platform split

Browse Source
This commit is contained in:
Merge Sim
2026-08-31 17:44:31 -07:00
parent e95fb2cc86
commit 9249df5a61
1 changed files with 27 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture/structured-native-chat-platform-split.md
+27
View File
@@ -0,0 +1,27 @@
# Structured native-chat platform split
## Decision
Use one shared session contract and one routing decision, then keep execution-host adapters in focused changes. The shared contract owns durable records, journal/replay, mutation admission, publication compatibility, tab semantics, and legacy fallback. An adapter may create a structured session only when the execution host proves provider capability; otherwise the caller receives a truthful refusal and uses the existing terminal path.
Every entrypoint (workspace creation, quick command, new-tab launch, restore/resume, and remote activation) calls the same routing seam. The seam evaluates the toggle, Chat default, provider, workspace kind, execution host, and host capability. It never launches a provider on a different host and never retries a prompt whose delivery outcome is unknown.
## PR boundaries
1. **Provider adapters** — Claude stream-json and Codex lifecycle integration, provider-owned roots, identity, prompts, options, images, resume/fork, cancellation, and shutdown. This is reviewable without platform-specific process plumbing.
2. **Windows native** — Windows process identity/start-time proof, `runProcess`/`spawnProcess` launches, CmdOrCtrl behavior, and Windows fallback. WSL remains a separate host.
3. **WSL** — distro selection, guest paths and environment, `buildWslExecArgs`, captured-login-shell parsing, and WSL process fencing. Windows-host launches are never substituted for the distro provider.
4. **Native Linux/package** — provider lifecycle on Linux plus AppImage/native-module architecture contracts and the glibc 2.31 floor.
5. **SSH/Linux** — execution-host-owned provider and journal state, reconnect/restart reconciliation, and `live` / `unverifiable` / `exited` verdicts.
6. **Paired remote Orca** — capability negotiation, agent-session/session-tab publications, relay reconnect, old-client/new-host projection, and no-local-provider guarantees.
Each boundary starts from the latest `origin/main`, has its own child worktree and exact head, and lands only after focused tests, readiness/review scans, and topology-appropriate evidence. The boundaries avoid a second intertwined refactor while preserving a small shared contract and making unsupported hosts recoverable.
## Compatibility and safety
- Toggle off keeps the legacy terminal path byte-for-byte in routing behavior.
- New wire fields are optional; new stream opcodes require capability negotiation.
- Transport loss is not process death; SSH verdicts are exactly `live`, `unverifiable`, or `exited`.
- Folder workspaces and git worktrees use the same host-owned resolution.
- Windows child processes use the shared process wrapper, and WSL commands use the shared argv/captured-shell builders.
- Packaged Linux artifacts are checked against architecture and glibc floors before release.