# Harness runtime The harness runtime owns the extension installation, ledger, session compositions, and Python kernels used by the daemon. The daemon's [session actor](sessions.md) coordinates turns with this runtime. ## Startup and ownership [`runtime.start_with_config`](../src/albedo/harness/runtime.gleam) opens the store, creates the [kernel's tables](kernel.md#ownership), installs extensions, and starts the runtime actor. The initializer has a 60-second deadline. If installation fails, it closes the store. Extensions that fail installation can be quarantined. The runtime records and reports them. A runtime session belongs to the store that created it. `execute` and `invoke` reject a session owned by another runtime. The runtime exposes installed and quarantined extensions and the underlying ledger through its public functions. ## Preparation and kernels [`runtime.prepare_session_async`](../src/albedo/harness/runtime.gleam) prepares a session composition without starting a kernel. `open_session_async` requests a kernel and calls its answer function when startup succeeds or fails. The synchronous `open_session` waits up to 180 seconds and returns `python.Unavailable` on timeout. Both paths validate the session ID. `reattach_session` asks the runtime to recover a recorded kernel without starting a replacement. A dead bridge handle does not prove the detached Python process has stopped. The runtime drops that stale handle before attempting reattachment, so callers can save the surviving namespace before cleanup. `prepared` extracts the kernel-free composition, instructions, and context from an open session. The runtime can inspect commands from a prepared composition without opening a kernel. The [session actor](sessions.md) decides when to request and release a kernel. ## Admission and worker lifetime [`runtime/admission`](../src/albedo/harness/runtime/admission.gleam) and its [native owner](../src/albedo/harness/runtime/albedo_runtime_admission.erl) reserve producer storage before forwarding requests to the runtime mailbox. Each runtime has separate lanes for preparation, observation, lifecycle waiters, and control calls. Each lane admits at most 64 requesters. A producer's captured arguments and failure callback must fit a conservative 256 KiB retained-byte budget, including backing binaries. Oversized requests and full lanes return `PayloadTooLarge` or `Overloaded`; async compatibility entrypoints deliver these as their existing unavailable/error outcome. Invalid session IDs remain invalid. The four lanes allow at most 64 MiB of budgeted producer captures. This is not a process RSS limit: forwarding copies, computed results, published compositions, kernels, and extension resources have their own lifetimes. A ticket identifies the runtime incarnation, request reference, and class. Its reservation records the generation it joins. Deferred requests, command waiters, observations and retries retain that reservation rather than entering an unbounded second queue. Per-producer request order survives forwarding. `prepare_session_request` and `open_session_request` return cancellation handles. `cancel_request_ticket` and requester death withdraw queued waiters. A sole preparation worker is stopped when no requester or required lifecycle action needs it. Other waiters keep shared preparation alive. An already-running kernel launch finishes reporting its process identity before a withdrawn generation is retired; killing the launcher early can lose cleanup authority. Active cancellation holds its reservation until monitored settlement. Cancellation can race adoption; work already committed to publishing or reconciling ownership finishes that transition. A reload already applying its saved selection, upgrade, and accepted stop actions settle ownership even when their requester stops waiting. A deferred reload can still be withdrawn before it saves or applies the selection. Cancellation does not undo saved intent or stop external jobs independently of those existing lifecycle operations. A reservation has one terminal delivery gate shared by completion, cancellation and runtime death. Finite calls retire their reply aliases and withdraw on timeout. Required reset/forget cleanup survives that withdrawal. Session actors retain their preparation/kernel ticket and tag replies with a local generation, so a late reply cannot settle a newer turn's request. See [session cancellation](sessions.md#submissions-and-cancellation). [`runtime/boot`](../src/albedo/harness/runtime/boot.gleam) still schedules preparation and observation across four workers. Each class leaves one slot for the other. Kernel stops have two separate worker slots; spare stops use preparation slots. The scheduler preserves the oldest eligible request within each class. Monitored `Work` tickets count active workers, including obsolete generations. Results require acknowledgment, and worker exits run the existing abandonment handlers. ## Cleanup reservations Before resource work starts, admission reserves one of 64 generation cleanup credits. Publication releases the credit after responsibility for all new resources transfers to retained owners. Publishing a reload candidate does not release the credit while its previous kernel still needs uncertain-outcome reconciliation. A late result or abandoned kernel operation transfers its credit to retirement. Successful cleanup releases it; failed cleanup retains both its callback and credit for an explicit later stop. Exhausted cleanup credits refuse new resource work while reads and stop workers can still run. This prevents repeated cancellation from growing unpublished retirement work without bound. If a preparation worker dies before returning resource handles, its credit stays explicitly unconfirmed until runtime exit. Requester and computation tickets still settle, while that uncertain cleanup budget remains fenced. `admission_snapshot` reports these credits. This does not impose a new limit on published sessions or kernel memory. Recorded-kernel recovery reserves one background producer before spawning; its reattach calls use ordinary admission. Command and reload-observation relays also reserve before spawning. Required async reset/forget intents have separate, resource-backed reservations. An intent linked to an admitted preparation holds that preparation's public slot until cleanup settles, even if its requester has withdrawn. Equivalent intents coalesce within that preparation epoch. Cleanup with no live preparation coalesces per retained resource and operation. This bounds pending epoch records by preparation slots while preserving required cleanup for retained resources; repeated preparation/reset/cancellation cannot recycle admission into an unbounded cleanup queue. Spare demand notifications coalesce, and quiet timers replace their predecessor. A spare reserved by a boot worker is retired if that worker dies. [`runtime/kernels`](../src/albedo/harness/runtime/kernels.gleam) retains every pending stop generation for a session. A successful stop clears only failures it undertook to reconcile. An unrelated late success cannot clear another generation's failure fence. Cleanup failures keep concrete retry callbacks when no published owner retains the resource. These are runtime-lifetime records, not durable job survival. Extension preparation still requires the project's owned-resource and idempotent-close contracts. See [shared lifecycle rules](contributing.md#preserve-extension-lifecycle-boundaries) and [admission measurements](perf.md#runtime-admission-measurements). ## Execution and tools [`runtime.execute`](../src/albedo/harness/runtime.gleam) begins a journal cell, executes saved Python code with the supplied timeout, and settles the cell with its outcome. A journal failure is returned separately from the Python outcome. `runtime.invoke` finds a tool in the session composition. An unknown tool or an extension refusal becomes a failed tool output. An extension `Fatal` error ends the invocation with an error. Image limits are passed to the tool context. [Hooks](hooks.md) can observe or refuse calls. ## Lifecycle [`runtime.delete_session`](../src/albedo/harness/runtime.gleam) asks the runtime owner to delete a session and returns an error if the owner stops or does not confirm within 30 seconds. The module also exposes asynchronous reset and forget operations, kernel detach and resume operations, and extension reload operations. These are distinct from deleting the daemon's durable session record. See [sessions](sessions.md). ## Extension reload ownership [`reload.gleam`](../src/albedo/harness/runtime/reload.gleam) prepares and adopts a candidate composition before applying it to the kernel. The runtime retains the candidate, previous session, and reply recipient in a `ReloadApplication` through its queued or monitored work. The worker borrows these handles and closes neither composition. The worker reports a typed `ReloadOutcome`: rebound routes, a replacement kernel, no live kernel, or a reported rejection. A worker that exits without a result produces an uncertain outcome through the existing admission monitor. Both paths reach `reload.settle`, which checks the session generation before deciding publication, retention, or reconciliation. Successful application installs the candidate and retires the old composition. A reported rejection closes the candidate and retains the previous session only if its kernel still lives. If work ended without reporting, the adopted candidate becomes loaded and kernel ownership is reconciled through the stop owner. Do not restore the previous routes when the worker may already have changed them. An unconfirmed stop keeps the session fenced. A result for an obsolete generation queues its resources for retirement rather than publishing them. If the runtime dies before acknowledging a result, the reporting worker cleans up the orphaned application. Keep slow kernel cleanup in [`kernels.reconcile` and `retire`](../src/albedo/harness/runtime/kernels.gleam) so the actor stays responsive. The existing `Origin` and `handed_out` contract in [`state.gleam`](../src/albedo/harness/runtime/state.gleam) governs first-handoff namespace notices. Settlement preserves that origin for the caller and retains the handed-out session for later opens. Notice publication remains in [`session_namespace.adopt`](../src/albedo/daemon/session_namespace.gleam). ## Clocks Use [`albedo/clock`](../src/albedo/clock.gleam) for Gleam clock access. Use `system_ms` or `system_seconds` for stored timestamps and `monotonic_ms` for elapsed time and deadlines. Do not add local clock externals. The [`albedo_clock` lint rule](../tools/lint/src/albedo_lint/rules/clock.gleam) checks this boundary. See [runtime-helper guidance](contributing.md#reuse-runtime-helpers) for timer and deadline rules. ## Unicode scalar limits Use [`text_scalars.length`, `take`, `drop`, and `tail`](../src/albedo/text_scalars.gleam) for scalar-bounded names and previews. These functions scan UTF-8 and copy retained slices. Do not build a list for the entire input merely to truncate it. The [`albedo_text_scalars` rule](../tools/lint/src/albedo_lint/rules/text_scalars.gleam) checks uses of the prohibited alternatives. The [API architecture](../docs/http-api-architecture.md) explains how runtime application relates to persisted intent. [Daemon lifecycle](../docs/daemon-lifecycle.md) covers process attachment and native service ownership. ## Related pages - [All topics](README.md) - [Change guidance](contributing.md) - [Session attachment](sessions.md) - [Extensions](extensions.md) - [The detached kernel](kernel.md)