Certify alpha8 production and rollback tuples

docs/maintenance.md

@@ -29,6 +29,16 @@ Generated release snapshots, detached operational copies, editor locks, caches,
 and linked task worktrees are evidence or tooling. They are not additional
 consumers and must not be bulk-upgraded.
 
+Direct consumers still need immutable inputs even though they do not use the
+Ruby gems. A system service must execute a clean certified checkout or image,
+not whichever files happen to be in a mutable development worktree. Node and
+Bun plugins must be pinned through their package lock and tested against the
+same OpenCode digest; a globally cached, unversioned plugin is not release
+provenance. Generated OpenCode or MCP configuration needs both schema validation
+and a candidate-runtime smoke test. Keep OpenCode auto-update disabled in every
+certified lane so a process restart cannot silently change the server half of a
+previously passing tuple.
+
 ## Supported window
 
 Support the exact current and previous certified runtime tuples. Do not claim
@@ -65,6 +75,19 @@ state must record the annotated tag object and peeled commit. Tags or `latest`
 may be kept as human-readable provenance only; execution coordinates use full
 Git commits and `image@sha256:...` references.
 
+## Rollback
+
+Rollback restores the whole certified `previous` tuple. Do not roll back only
+the gem, only the consumer, or only the runtime image: the wire contract is the
+unit of compatibility.
+
+The deployment platform's immediately preceding application image is not
+automatically the certified OpenCode rollback. Keep it as emergency service
+provenance, but if it contains a client/runtime tuple known to fail the contract
+it must not occupy `previous`. In that case rollback means deploying the exact
+consumer commit and runtime coordinates recorded in the certified `previous`
+tuple, even if that is different from the platform's one-click rollback target.
+
 ## Custom images
 
 Record each provenance layer separately:
@@ -85,6 +108,10 @@ the labels. Do not relabel an already certified image: that changes its digest.
 Runner upgrades are a separate compatibility surface from OpenCode upgrades.
 Workflows must install their required Ruby/toolchain explicitly, declare Bash
 for scripts that use Bash syntax, and avoid relying on ambient runner packages.
+Browser suites must provision the reviewed Chrome/Selenium path explicitly;
+an absent browser is a runner failure, not product evidence. Keep a system-test
+suite serial when its harness shares an ephemeral server port instead of
+mistaking parallel `EADDRINUSE` failures for OpenCode regressions.
 
 GitHub and Gitea do not implement every Actions feature identically. Keep the
 same tests on both forges, but use forge-specific execution where necessary:
@@ -96,22 +123,36 @@ A runner-only workflow repair needs exact-head CI, not an application canary.
 A client, runtime image, event, persistence, or toolchain change needs the
 profile and consumer canaries described above.
 
+For a frozen rollback snapshot that is no longer a merge candidate, provide a
+default-branch audit workflow that accepts and checks out an explicit full SHA.
+That lets current runner plumbing test the immutable old application tree
+without adding a CI-only commit to the rollback coordinate or pretending a
+known runner-workflow failure is an application incompatibility.
+
 ## Expected breakages
 
 - Prompt submission before event subscription can miss a terminal event and
   hang a turn.
+- An SSE parser that recognizes only `\n\n` can stall on CRLF, bare-CR,
+  byte-order-mark, comment, or multiline-data framing that is valid on the
+  wire.
 - Changes to terminal or message-part events can duplicate or lose final text.
 - Usage events can undercount multi-step requests if totals are overwritten.
 - Reconnect logic can replay a prompt and create duplicate model requests.
+- A Bun/Node server close can wait forever on idle keep-alive sockets unless
+  idle connections are explicitly reaped after admissions stop; the resulting
+  orphan can exhaust a service cgroup's PID budget and block a safe upgrade.
 - Asset builds can fail when runtime configuration is evaluated without the
   image variables available only at deploy time.
 - A workflow can pass locally but fail under `sh` when it uses Bash arrays or
   `mapfile`.
 - Plugin hook names, provider schema, config/MCP schema, or CLI flags can break
   direct consumers even when the Ruby profile stays green.
+- `Opencode::Turn` is still an alpha-stage Rails composition seam; constructor,
+  observer, persistence, or finalization changes can break hosts even when the
+  lower-level Ruby wire client remains compatible.
 - A custom fork can silently lose its required ordering or permission patch if
   only an opaque output digest is retained.
 
 When one of these changes, update the owning profile and consumer evidence. Do
 not weaken a strict invariant to make a new upstream release pass.
-