Merge pull request #4 from A3S-Lab/docs/streaming-exec-adr-20260719

docs: decide interactive streaming exec boundary

Author: ZhiXiao-Lin

README.md

@@ -110,7 +110,7 @@ The `RuntimeClient` contract exposes:
 | `stop` | Stop the active generation without deleting durable identity |
 | `remove` | Remove the provider resource and persist an absence tombstone |
 | `logs` | Read strictly ordered, cursor-addressed log chunks or return a typed permanent discontinuity |
-| `exec` | Execute a bounded command against the exact active generation |
+| `exec` | Execute one bounded, buffered command against the exact active generation |
 
 Each mutating request carries its own request ID and optional absolute deadline.
 An exact retry returns or reconstructs the same logical result. Reusing a
@@ -123,6 +123,13 @@ optional caller deadline. `RuntimeDriver::exec` receives that effective
 absolute deadline in `deadline_at_ms`, and every pending replay receives the
 same value, so retrying cannot restart or extend the execution window.
 
+`exec` is a unary, non-interactive operation. Its single result contains an
+exit code, separate buffered stdout and stderr of at most 16 MiB each, and a
+truncation indicator. `RuntimeFeature::Exec` does not advertise stdin, PTY,
+terminal resize, signals, incremental output, or reconnectable sessions.
+Interactive streaming must not be emulated with log cursors or repeated unary
+requests.
+
 Log transport or provider availability failures remain retryable errors. A
 provider that can prove the requested cursor was lost, or that the durable unit
 survives after its log source disappeared, instead returns
@@ -255,7 +262,9 @@ provider driver and external runtime
 
 See [ADR 0001](docs/adr/0001-general-runtime-contract.md) for the general
 ownership model, [ADR 0002](docs/adr/0002-complete-protocol-and-operation-semantics.md)
-for the completed protocol and operation semantics, and the
+for the completed protocol and operation semantics,
+[ADR 0003](docs/adr/0003-keep-interactive-streaming-exec-outside-v0.2-core.md)
+for the bounded unary exec boundary, and the
 [implementation plan](docs/implementation-plan.md) for the dependency-ordered
 delivery tasks.
 

docs/adr/0003-keep-interactive-streaming-exec-outside-v0.2-core.md

@@ -0,0 +1,108 @@
+# ADR 0003: Keep Interactive Streaming Exec Outside the v0.2 Core
+
+- Status: Accepted
+- Date: 2026-07-19
+- Decision owners: A3S Runtime maintainers
+
+## Context
+
+Runtime v0.2 exposes a provider-neutral `exec` operation for a command against
+the exact running unit generation. The operation is deliberately unary:
+
+- one validated request contains the command and an execution deadline;
+- one durable request receipt binds retry and provider reattachment;
+- one result contains the exit code, separate buffered stdout and stderr, and
+  a truncation indicator;
+- stdout and stderr are each limited to 16 MiB; and
+- the completed result is replayable without executing the command again.
+
+The contract has no stdin stream, PTY mode, terminal resize, signal stream,
+cross-stream ordering, or reconnectable session. `RuntimeFeature::Exec`
+advertises only the bounded unary operation.
+
+A bidirectional interactive protocol has materially different lifecycle and
+durability requirements. A connection can disappear while input is buffered,
+output is unacknowledged, or the provider is exiting. Without an explicit
+owner and bounded flow control, a caller retry can duplicate input, lose
+output, leak a provider session, or publish two different terminal outcomes.
+Those failures cannot be made safe by treating logs as stdout or by issuing
+repeated unary exec requests.
+
+## Decision
+
+Bidirectional or interactive streaming exec is not part of the Runtime v0.2
+core contract. The existing unary `RuntimeClient::exec`,
+`RuntimeDriver::exec`, `RuntimeExecRequest`, `RuntimeExecResult`, and
+`RuntimeFeature::Exec` remain unchanged.
+
+In particular:
+
+- `Exec` does not imply stdin, PTY, resize, signals, incremental output, or
+  stream resume;
+- log cursors are not exec-session cursors and may not be used to emulate an
+  interactive command;
+- splitting one interactive command into repeated unary exec requests does not
+  create a conformant stream; and
+- Cloud must not bypass Runtime through direct node or provider access and
+  present that path as Runtime-compatible terminal or exec behavior.
+
+A future interactive protocol may be proposed only as a distinct, optional,
+separately versioned capability. It must not extend the meaning of the existing
+`Exec` feature or reuse the v1 unary wire schemas.
+
+Before that capability can be published, its ADR, wire contract, and
+conformance profile must define and test all of the following:
+
+1. A generation-bound session identity, durable request identity, and exactly
+   one authority for the terminal exit result.
+2. Bounded queues in both directions, explicit flow-control credits or
+   acknowledgements, and deterministic behavior when either peer applies
+   backpressure.
+3. stdin half-close and EOF semantics, stdout/stderr ordering, frame size
+   limits, and any PTY, resize, or signal behavior.
+4. Cancellation, caller disconnect, provider disconnect, and absolute deadline
+   behavior, including which event wins a race with process exit.
+5. Reconnect and resume rules, acknowledged offsets, replay bounds, and
+   duplicate-input prevention, or an explicit non-resumable contract.
+6. Ownership and cleanup after caller, Runtime, or provider restart, including
+   retention limits for detached sessions and unacknowledged output.
+7. Capability discovery, unsupported-capability errors, authorization
+   boundaries, and fault tests that prove no unbounded memory, duplicate
+   process, conflicting terminal result, or leaked session.
+
+Until those requirements are accepted and implemented, a caller that needs an
+interactive terminal does not have that capability through Runtime.
+
+## Consequences
+
+- Runtime v0.2 keeps one bounded, durable, provider-neutral exec semantic that
+  can be tested without a long-lived transport.
+- Existing providers and consumers do not acquire hidden streaming obligations
+  when they advertise `RuntimeFeature::Exec`.
+- Unary exec cannot provide a live shell, interactive stdin, PTY behavior, or
+  real-time output. The separate log operation remains suitable only for
+  observing unit logs.
+- A future streaming design requires a new compatibility review and
+  conformance gate instead of an additive method that silently weakens retry,
+  cancellation, or resource-ownership guarantees.
+
+## Rejected alternatives
+
+### Add bidirectional streaming to `Exec` now
+
+Rejected because the current request receipt stores one terminal result and
+does not define frame acknowledgement, half-close, disconnect, or resume
+semantics. Adding a transport stream before those rules would publish
+provider-dependent behavior as a core guarantee.
+
+### Emulate a stream with unary exec and logs
+
+Rejected because independent requests cannot preserve stdin identity or
+exactly-once delivery, while log cursors do not bind command output or a
+terminal exit result.
+
+### Let each provider expose an untyped streaming extension
+
+Rejected because Cloud could no longer discover or test one provider-neutral
+capability and provider-specific session fields would escape the driver
+boundary.

docs/deep-test-plan.md

@@ -107,13 +107,14 @@ These invariants are the basis of every test oracle.
 - A successful suite leaves no provider resources, state roots, ports, mounts,
   processes, or test volumes outside its declared retention policy.
 
-## 5. Contract Decisions Required Before P0 Closes
+## 5. Contract Decisions and P0 Oracles
 
-Tests must not encode accidental behavior. The maintainers must resolve and
-record the following decisions in an ADR or contract documentation before the
-corresponding release gate is enabled.
+Tests must not encode accidental behavior. ADR 0002 resolves the lifecycle and
+operation decisions below, and ADR 0003 resolves the interactive streaming
+exec boundary. The table retains the motivating risks and required release
+oracles.
 
-| Decision | Current risk | Required test oracle |
+| Decision | Motivating risk | Required test oracle |
 | --- | --- | --- |
 | Wire schema boundary | Top-level log, exec, and inspection types do not all carry schema identifiers although the README says all wire records do | Define which types cross a versioned boundary; require a schema on each top-level wire record or narrow the compatibility claim |
 | Provider identity binding | Capabilities carry a string validated differently from `ProviderId`, and the managed client does not bind it to a selected factory | Use one grammar and prove reported, registered, and observed provider identities cannot disagree |
@@ -124,6 +125,7 @@ corresponding release gate is enabled.
 | Task output fulfillment | A Task may request outputs, but capabilities do not express output collection and the current Docker driver returns none | Make output support mandatory or capability-gated; prove every requested output is collected, bounded, and digest-bound before convergence |
 | Logs by state | Current-generation logs may be useful after Task completion or Service stop | Define allowed states, removal behavior, cursor retention, and provider-loss behavior |
 | Exec by state | Generation matching alone does not prove a runnable unit | Require `running`, or explicitly delegate a narrower rule to providers |
+| Bidirectional streaming exec | A disconnected stream can leave unbounded buffers, duplicate stdin, unacknowledged output, leaked sessions, or conflicting terminal owners | Runtime v0.2 exposes only bounded unary exec; a distinct versioned optional capability must prove backpressure, ordering, half-close, cancellation, deadline, reconnect, terminal ownership, and restart cleanup before publication |
 | Stop after loss | A provider may be absent while durable state is `unknown` | Define whether stop returns `unknown`, is idempotent success, or requires recovery |
 | Receipt retention | Records reject more than 10,000 receipts but have no retention/compaction policy | Define bounded retention without breaking exact replay guarantees |
 | Deadline semantics | Deadlines are checked only before dispatch | Define whether drivers receive remaining budget and how late results are persisted |
@@ -328,7 +330,7 @@ fixtures and destructive cleanup.
 | Health | Every advertised probe kind, threshold transitions, timeout, start period, unhealthy exit |
 | Resources | Every advertised control verified by provider configuration and workload behavior |
 | Logs | Stream filtering, total order, cursor resume, same-timestamp records, limit, rotation gap, retention, large records |
-| Exec | State policy, timeout, exit code, output bounds, truncation, identity and generation binding |
+| Exec | Bounded unary state policy, timeout, exit code, output bounds, truncation, identity and generation binding |
 | Security | Digest pinning, label/metadata tamper, namespace separation, secret handling, least privilege, hostile input |
 | Evidence | Usage, evidence claims, profile binding, attestation validity for each advertised optional feature |
 

docs/implementation-plan.md

@@ -2,10 +2,11 @@
 
 ## Goal
 
-Implement the complete contract accepted by ADR 0001 and ADR 0002, certify all
-advertised provider capabilities, and satisfy the release gates in the deep
-test plan. Work is ordered by dependency; a later task cannot claim completion
-from mocks when its required real-provider evidence is absent.
+Implement the complete contract accepted by ADR 0001 and ADR 0002, preserve
+the bounded unary exec boundary accepted by ADR 0003, certify all advertised
+provider capabilities, and satisfy the release gates in the deep test plan.
+Work is ordered by dependency; a later task cannot claim completion from mocks
+when its required real-provider evidence is absent.
 
 ## Working rules
 
@@ -30,7 +31,7 @@ from mocks when its required real-provider evidence is absent.
 | R05 | Bound deadlines across queue and dispatch | R04 | Deterministic clock tests for pre-lock, post-lock, provider timeout, and pending replay |
 | R06 | Add per-unit cross-process operation leases | R04 | Same-unit race serialization and different-unit parallelism in independent processes |
 | R07 | Replace embedded receipts with request journal v2 | R06 | Atomic receipt tests, restart replay, 10,001 requests, permissions, corruption handling |
-| R08 | Make exec durably idempotent | R07 | Exact replay executes once; conflict, cancellation, timeout, and large-output tests |
+| R08 | Make bounded unary exec durably idempotent | R07 | Exact replay executes once; conflict, cancellation, timeout, and large-output tests |
 | R09 | Enforce generation reconciliation | R06 | N to N+1 success/failure/crash tests with exactly one final provider resource |
 | R10 | Build deterministic fault driver and transition generator | R01-R09 | Every state edge and provider boundary has a stable case ID and oracle |
 | R11 | Split shared conformance into capability profiles | R10 | Base/Recovery mandatory; optional advertised profiles auto-run and cannot silently skip |
@@ -71,7 +72,7 @@ Deliverables:
 
 - independent operation and record locks;
 - v2 unit directory and request journal;
-- durable exec receipts;
+- durable bounded unary exec receipts;
 - generation reconciliation contract and deterministic provider model;
 - process-level crash/failpoint harness;
 - transition matrix and race matrix;
@@ -81,6 +82,11 @@ Deliverables:
 Exit gate: every mutating crash point can replay after a new process starts,
 with valid state and no untracked provider resource.
 
+ADR 0003 excludes interactive stdin, PTY, terminal resize, signals,
+incremental output, and reconnectable exec sessions from this plan. A future
+interactive protocol requires a distinct versioned capability and its own
+dependency-ordered implementation and conformance work.
+
 ### Package C: Shared certification (`R11`-`R12`)
 
 Deliverables: