@botiverse/k-carrier 0.1.7 → 0.2.0

package/core/src/upgrader.ts

@@ -4,6 +4,7 @@ import type { ConvergenceReport } from "./converge/predicates.js";
 import type { StatusReport } from "./status/report.js";
 import type { ReleaseSource } from "./artifact/source.js";
 import type { OperationDescriptor, OperationRead } from "./operation.js";
+import type { QuarantineOptions, QuarantineResult } from "./quarantine.ts";
 
 /**
  * Who drove a reconcile, recorded in the provenance journal (M6, L5).
@@ -18,11 +19,9 @@ export interface ProvenanceIdentity {
 }
 
 /**
- * Upgrader is the single facade an application calls. Every entrypoint the
- * app exposes (daemon-internal auto-update, `myapp self upgrade`, install
- * script, remote drive) constructs the SAME Upgrader — one canonical
- * executor, so there is no entrypoint that "swaps bytes but skips
- * convergence" (the class of bug this framework exists to kill).
+ * Upgrader is the transaction facade constructed by createRunner
+ * inside the disposable runner. Application entry points submit runner
+ * requests; they do not construct an in-process upgrade engine.
  */
 export interface Upgrader {
   /**
@@ -34,7 +33,7 @@ export interface Upgrader {
    * recorded by K. Hosts should run this from a coordinator that survives
    * service replacement, because recovery may stop and restart the service.
    */
-  recover(): Promise<void>;
+  recover(expected?: { id: string; targetVersion: string }): Promise<void>;
 
   /**
    * Ask the release source whether this install should move, without moving
@@ -104,8 +103,8 @@ export interface Upgrader {
   /** K's single durable operation receipt; hosts project it, never mirror it. */
   operation(): Promise<OperationRead>;
 
-  /** Mark one exact terminal operation delivered by the host transport. */
-  acknowledgeOperation(operationId: string): Promise<"acknowledged" | "not-terminal" | "not-found" | "changed">;
+  /** Atomically move quiesced K state to an audit-only fresh-install backup. */
+  quarantineState(options: QuarantineOptions): Promise<QuarantineResult>;
 }
 
 export type UpgradeOutcome =

package/docs/design.md

@@ -0,0 +1,173 @@
+# K design
+
+This document is the normative contract for K's execution model, transaction,
+supervision and controller boundary. It states obligations; it does not
+explain them. Read [how an upgrade works](guide.md) first for the narrative
+and vocabulary, and the [reference](reference.md) for wire formats, exit
+codes, budgets and file layout.
+
+## Execution and trust
+
+```mermaid
+flowchart LR
+  Entry[Bootstrap / CLI / remote control] --> Supervisor[Verify and launch runner]
+  Supervisor --> Worker[K + product adapter]
+  Worker --> State[Lock / journal / slots / receipts]
+  Worker --> Controller[Product lifecycle controller]
+  Controller --> App[Application]
+```
+
+- The runner and its runtime live outside the application slots and service
+  unit. Stopping the application must leave the worker alive. A child
+  process can still belong to a systemd cgroup or Windows job; the publisher
+  must arrange isolation.
+- The supervisor retains recovery code until settlement. Installation state
+  persists. An OS hook or operator must restart installation after reboot.
+- The adapter is fixed at build time. Requests select an action and a target
+  version, never code, commands or download URLs.
+- The publisher authenticates distribution metadata and caller authority. K
+  checks artifact SHA-256 and size; these checks do not establish publisher
+  identity. See [packaging](integration.md#distribute-a-built-installer).
+
+## Components
+
+Paths are relative to `core/src/`.
+
+| Component | Responsibility |
+|---|---|
+| `launcher/` | Acquire, verify, execute and clean runner code; supervise recovery |
+| `protocol/` | Validate the bounded request/response contract |
+| `runner/` | Serve stdin/stdout, execute requests and map outcomes to exit codes |
+| `createRunner.ts` | Assemble source, host, policy and transaction state |
+| `lifecycle/` | Stop/start/probe the application, including command-based control |
+| `artifact/`, `txn/`, `converge/` | Verified acquisition, durable transactions and readiness predicates |
+
+`createRunner(options)` constructs the transaction interface. `serveRunner(factory)`
+serves it in the runner process. `launchRunner({release, request, scratchDir,
+interpreter?})` verifies and supervises a worker, writes one final response and
+returns its exit code. `superviseRunner` returns the same result as data,
+including any retained `recoveryFile`. `resumeRunner(recoveryFile)` verifies
+that retained runner and performs operation-bound recovery without
+distribution access.
+
+## Transaction and recovery
+
+Each installation has one lock, stable and experiment executable slots, and a
+journal. K stages verified candidate bytes, quiesces work, stops the old
+service, starts the candidate and evaluates live readiness. Passing candidates
+are promoted; failed candidates restore stable. Application data belongs
+outside the slots.
+
+The phases are `idle`, `staged`, `handing-over`, `running-experiment`,
+`readback`, `promoted` and `rolled-back`. Intent is journaled before effects.
+Recovery takes the same lock and uses existing slot bytes without release
+lookup:
+
+- Before durable promote intent: restore stable.
+- After durable promote intent: replay commit idempotently.
+
+A running candidate alone does not authorize commit. Corrupt or unknown state,
+and another live lock owner, prevent conflicting operations. Filesystem
+durability and controller behavior determine the real platform guarantees.
+
+## Transaction completion
+
+**Required for the initial release.** Every started operation has an owner
+that waits for a durable terminal result or explicitly reports unresolved
+recovery. An installer invocation must first settle unfinished work before
+admitting a new upgrade. Recovering an interrupted operation does not retry
+its requested upgrade.
+
+The supervisor:
+
+- runs outside the application service unit;
+- retains the verified runner while the operation is active;
+- enforces execution and recovery budgets ([values](reference.md#supervisor-budgets));
+- starts a recovery worker after an abnormal exit;
+- stops supervising after completion or an explicit unresolved result.
+
+Recovery attempts and total elapsed time are bounded. Exhaustion preserves
+state and provides a recovery command rather than reporting success.
+
+Before starting a successor, the supervisor must observe the prior worker
+exit. The recovery worker then takes the lock and fences outstanding
+controller effects before replaying lifecycle actions. An expired deadline
+alone is insufficient; an unconfirmed exit forbids takeover.
+
+Recovery must bind to the original operation id under K's transaction lock.
+If another operation has since run, recovery inspects or replays the original
+result without modifying the newer operation. Recovery reuses the existing
+journal and receipts; supervision does not create another transaction log.
+
+Cleanup follows settlement: persist the outcome, release owned resources,
+then remove disposable code. Never delete slots, a live owner's lock, or
+recovery logs to make an interrupted operation appear complete. If recovery
+remains unresolved, preserve the evidence and a verified means to invoke it
+again. Installer startup handles leftover work; machine reboot still requires
+an OS hook or operator to start the installer.
+
+Every engine host call has a positive budget. Uncertain effects retain the
+worker's lock until it exits. Bundled workers exit after flushing their
+response; custom in-process callers must also exit on `HostCallUncertain`
+rather than reuse that worker.
+
+The lock is a local filesystem protocol requiring atomic creation and
+coherent directory reads ([details](reference.md#lock-protocol)). It is not a
+distributed or NFS lock. Operation ids, receipt archival and replay rules are
+in the [reference](reference.md#receipts-and-retries).
+
+## Host control contract
+
+`createRunner` requires a HostAdapter. Its operations and the controller's
+obligations:
+
+| Operation | Controller obligation |
+|---|---|
+| fence | Drain or fence previous controller effects; required when effects can outlive the worker |
+| quiesce | Stop admission and durably park promised workloads; repeated calls safe |
+| stop | Stop the specified slot's service and confirm termination |
+| start | Start the selected artifact idempotently, without creating duplicate residents |
+| healthProbe | Return version, pid and startId from one ready live instance |
+| resume | Restore parked work on either candidate or rolled-back stable |
+
+- The controller must work while the old application is down.
+- `start` returning does not establish readiness; the probe does.
+- K probes once before handover and records that incarnation's `startId`
+  with the handing-over intent. Readback evidence carrying the same
+  `startId` is refused and rolls back: the old service was not replaced.
+- `start` must not execute the artifact in place inside the slot on
+  Windows; promotion renames slot directories and a running executable locks
+  its directory. Copy or hard-link to a runtime path outside the slots.
+- A stateless service satisfies `quiesce` and `resume` by acknowledging. The
+  obligations apply to workloads the product promises to preserve.
+- Adapters with no effects surviving their worker may omit `fence`. All
+  other adapters must supply it and test it against their real service
+  manager. `createCommandHost` always delivers `fence`; a command controller
+  that queues nothing acknowledges it.
+- If OS lifecycle surfaces are declared, K also requires them to reference
+  the promoted artifact before retiring their previous manager. Undeclared
+  surfaces are not observed.
+
+`createCommandHost` runs an external controller via argv without a shell,
+records the controller pid durably before each call, and drains recorded
+controllers before `fence` during recovery. Wire format, bounds and pid
+handling are in the [reference](reference.md#command-controller-protocol).
+The recorded pid is never used to kill an arbitrary process. `fence`
+acknowledgement is a product contract, not something K infers from process
+exit. Fire-and-forget stop cannot establish termination.
+
+## Product responsibilities
+
+The adapter defines release lookup, installation ownership, consent,
+notification and compatibility policy. Package-manager-owned installations
+defer to their owner. K restores executables; products provide data-migration
+compatibility, backup and restore, and any promised workload continuity.
+Service upgrades can interrupt availability. Remote authorization,
+distribution channels and cloud reconnection belong to the product
+integration.
+
+Use the [integration guide](integration.md) and
+[service example](../examples/external-service/README.md) to build an
+installer. The [test plan](test-plan.md) describes framework and product
+acceptance; [prior art](prior-art/design-influences.md) records design
+influences.

package/docs/guide.md

@@ -0,0 +1,196 @@
+# How an upgrade works
+
+This is the narrative walkthrough of K's mechanism: which processes exist,
+what happens in what order, what breaks, and how to read the result. It is
+written to be read once, top to bottom. It is **not** the contract; where it
+and the [design](design.md) or [reference](reference.md) disagree, they win.
+
+For what K is for and whether you need it, read the [README](../README.md).
+For how to build and ship an installer, read the
+[integration guide](integration.md). Terms are defined where they first
+appear in bold; this document is the vocabulary the other documents use.
+
+## The pieces
+
+```mermaid
+flowchart LR
+  B[Bootstrap<br/>install.sh / self upgrade] -->|request| S[Supervisor<br/>launchRunner]
+  S -->|verify, spawn| W[Worker<br/>K + adapter]
+  W --> D[(State directory<br/>lock · journal · slots · receipts)]
+  W -->|fence · quiesce · stop<br/>start · probe · resume| C[Controller]
+  C --> A[Application]
+```
+
+- The **bootstrap** is your `install.sh`, or the `self upgrade` command inside
+  your application. It downloads and verifies the installer, launches it,
+  and relays the exit code. It contains no upgrade logic.
+- The **installer** is what you ship. It has two halves. The **supervisor**
+  is a temporary process that acquires and verifies the runner, executes it
+  and, if it dies, runs bounded recovery. The **runner** is K plus your
+  adapter bundled into one executable; it serves one request and exits. A
+  running runner is a **worker**.
+- The **adapter** is your trusted code, fixed at build time: where releases
+  come from, whether an upgrade may proceed, and how to reach the controller.
+- The **controller** is your program that actually stops, starts and probes
+  the application. The adapter can call it directly or through `createCommandHost`.
+- The **state directory** holds the lock, the journal, two **slots** and the
+  receipts. Recovery uses this state together with a compatible runner, its
+  runtime and the product controller; it does not need release distribution.
+
+The runner and the controller live outside the application's service unit.
+That is the whole point: stopping the application must not stop the thing
+that is upgrading it.
+
+The slots are **stable** and **experiment**; these are positions
+on disk, not release channels, so a product channel also called "stable" is
+unrelated. *Hands*, mentioned in the integration guide, is the release
+platform K's authors publish with; K does not depend on it.
+
+## One upgrade, start to finish
+
+```mermaid
+sequenceDiagram
+  participant B as Bootstrap
+  participant S as Supervisor
+  participant W as Worker
+  participant C as Controller
+  participant A as Application
+  B->>S: upgrade id=job-1 target=2.0.0
+  S->>S: download runner, check sha256 + size
+  S->>W: spawn, request on stdin
+  W->>W: take upgrade.lock, inspect operation identity
+  W->>C: fence previous controller effects
+  W->>W: settle leftovers, begin requested operation
+  W->>W: fetch release, verify bytes
+  Note over W: journal: staged intent
+  W->>W: write experiment slot
+  Note over W: journal: handing-over intent
+  W->>C: quiesce
+  C->>A: park work
+  W->>C: stop stable
+  C->>A: terminate, confirm exit
+  W->>C: start experiment
+  C->>A: launch candidate
+  W->>C: healthProbe
+  C-->>W: version 2.0.0, pid, startId
+  Note over W: journal: readback ok → promote intent
+  W->>W: experiment becomes stable
+  W->>C: resume
+  Note over W: persist promoted operation receipt
+  W-->>S: {result: promoted}, exit 0
+  S-->>B: exit 0
+```
+
+In words:
+
+1. The bootstrap asks the supervisor for one operation: an id and a target
+   version. The id is what everything else binds to.
+2. The supervisor downloads the runner, checks its hash and size, writes it
+   to scratch space and runs it with the request on stdin.
+3. The worker takes the installation lock. If an earlier operation was left
+   unfinished, it settles that first. The same id replays its result; a new
+   id may proceed only after recovery succeeds.
+4. It asks your release source for exactly the target version, verifies the
+   bytes, and writes them into the *experiment* slot. Nothing running has
+   changed yet.
+5. It asks the controller to quiesce (park in-flight work) and to stop the
+   current service, and waits for confirmation that the old process is gone.
+6. It asks the controller to start the candidate from the experiment slot,
+   then probes it. The probe must come from one live process and report the
+   expected version with a pid and a **startId**. K probed once before
+   stopping the old service and journaled that startId; if the same one
+   comes back now, the old process was never replaced and the upgrade rolls
+   back.
+7. Only now does the worker write **promote intent** to the journal. That
+   line is the point of no return: before it, the safe move is always to put
+   the old version back; after it, the safe move is always to finish the
+   promotion.
+8. Experiment becomes stable. The controller resumes parked work. The
+   receipt is persisted in `operation.json`; it is archived before a later
+   operation begins. The worker prints its response and exits 0.
+
+The transaction journal phases are, in order: `idle`,
+`staged`, `handing-over`, `running-experiment`, `readback`, and then either
+`promoted` or `rolled-back`. Operation receipts additionally track stages such as
+`downloading` and policy outcomes such as `held`.
+
+## When something goes wrong
+
+### The candidate is bad
+
+It does not start, it reports the wrong version, or it never passes the probe.
+The worker stops it, starts stable again, resumes parked work, and records
+`rolled-back`. Exit code 1. The stable bytes were never touched. This is the
+routine failure and the one K is built around.
+
+### The worker dies
+
+A crash, a kill, or a budget timeout. The supervisor:
+
+1. terminates a timed-out worker and waits for its observed exit; a deadline
+   alone does not permit takeover;
+2. starts a recovery worker bound to the same operation id;
+3. that worker takes the transaction lock, checks the operation identity,
+   and asks the controller to **fence** before replaying lifecycle effects.
+   Fencing ensures actions queued by the earlier worker cannot land later.
+   An already terminal original operation simply replays its receipt.
+
+Recovery does not need the network and does not guess. It reads the journal:
+
+```mermaid
+flowchart LR
+  idle --> staged --> ho[handing-over] --> re[running-experiment] --> rb[readback]
+  rb -->|promote intent| promoted
+  rb -.-> rolledback[rolled-back]
+  subgraph before [before promote intent: restore stable]
+    staged
+    ho
+    re
+    rb
+  end
+  subgraph after [after promote intent: replay commit]
+    promoted
+  end
+```
+
+Before promote intent, recovery restores stable. After it, recovery replays
+the commit. Both are idempotent, so a crash *during* recovery is handled the
+same way next time. Recovery never starts a new upgrade, even if the original
+request was an upgrade.
+
+Attempts and elapsed time are bounded. If recovery does not settle within
+those bounds, the supervisor exits 3, leaves the verified runner and a
+`recovery.json` in scratch space, and prints where. Later, `resumeRunner` on
+that file retries the same recovery offline.
+
+### Everything dies
+
+Power loss, reboot, or the whole invocation killed. The state directory
+survives. The next installer invocation, whether from `install.sh`, from
+`self upgrade`, or from an operator, settles the unfinished operation before
+it accepts new work. K does not install a permanent watchdog, so *something*
+has to run the installer again: your product's OS startup hook, or a person.
+
+## Reading the result
+
+Every run prints one JSON response on stdout and returns an exit code.
+Inspect both. The short version:
+
+| Exit | Meaning | What to do |
+|---|---|---|
+| 0 | Successful upgrade outcome; readable status or recovery with no recorded outcome | Check the action and receipt |
+| 1 | Rolled back, or failed before any change | Read `operation.operation.outcome` and the reason |
+| 2 | Held by policy, ownership or compatibility | Nothing changed; a new attempt needs a new id |
+| 3 | Unresolved | Keep the recovery file and run recovery |
+
+Two things surprise people. First, a `recover` action that successfully
+restored stable after a bad candidate exits **1**, because the recorded
+outcome is a rolled-back upgrade. That is the honest answer. Second, `status`
+reads the last receipt, not the live service; it can say `genesis` (no
+operation ever recorded) on a machine that is running fine.
+
+The exact response shape and every exit code are in the
+[reference](reference.md#protocol-v1).
+
+What each step asks of your controller, and how to package and ship the
+result, is the [integration guide](integration.md).