# Change Albedo These project rules guide implementation changes. The linked feature pages describe current behavior and its limits. ## Choose the owning layer Add capabilities through typed [plugins](plugins.md). Keep HTTP admission and wire encoding in daemon adapters, composition and kernel lifecycle in the [runtime](runtime.md), and feature state with its owning extension. The interfaces are defined in [`extension.gleam`](../src/albedo/harness/sdk/extension.gleam). Use the command's `Context.state` operations, typed SDK session operations, or supplied session callbacks to reach session behavior. Do not mutate a session's state from an extension. Resolve cross-extension dependencies from the applicable active selection, using [`host.Context`](../src/albedo/harness/sdk/host.gleam) or `extension.Daemon` rather than a captured installation registry. Declare each context capability the extension reads in its `uses`, and only those, as [extension capabilities](extensions.md#extension-capabilities) describes. See [commands](commands.md) and [extensions](extensions.md). Add an actor when ordering, concurrency, or resource lifetime requires one. A plugin declaration alone does not require a process. ## Write Gleam and keep values typed Write new code in Gleam, including process state, monitoring, actors, validation, and binary operations. Use `gleam_erlang`, `gleam_otp`, and the SDK helpers. Keep Erlang only for what Gleam cannot express, such as catching exceptions, opening ports, or an OTP call with no Gleam library, and keep that Erlang a thin binding with its reason in a comment. Keep policy and orchestration in Gleam. When a change touches an Erlang module, move what Gleam can express in the same change. Keep typed values through internal operations and encode JSON at the wire boundary. Do not encode an observation to JSON and parse it again to add fields. See [`command.StateOp`](../src/albedo/harness/sdk/command.gleam). Carry a refusal as a typed value from the place that decides it. Daemon operations return a [`Refusal`](../src/albedo/daemon/refusal.gleam) variant, and `refusal.failure` is the only place that chooses its HTTP status, problem code and sentence. A storage or dependency failure that no caller treats specially travels as `Unavailable`. Do not branch on the text of an error, and do not build a `Failure` from a code string. Add a variant when a caller needs to tell the failure apart. The `albedo_text_decisions` [lint](gleam-lint.md#text-and-token-rules) refuses a search, a literal `case` arm, or a literal comparison on a value named like an error or a message. A module that decodes outside text once, such as a provider wire, is listed in the rule's `edges` with the reason. Keep unfinished-output projection policy in [`active_output.gleam`](../src/albedo/daemon/active_output.gleam). Its spill [store](../src/albedo/daemon/active_output_store.gleam) owns file operations. Do not reconstruct output by replaying events when a typed projection is available. ## Keep reusable code in workspace packages Code with no dependency on albedo that other projects could use, such as a wire protocol, can live in a [workspace package](workspace-packages.md) under `packages/`. A package never imports albedo. Keep albedo policy in the albedo module that calls it. ## Reuse runtime helpers For extension imports and native bindings, follow the [SDK import contract](extensions.md#sdk-imports-and-native-bindings). Keep shared extension helpers under `albedo/harness/sdk/` and call their Gleam APIs. Use [`albedo_clock`](../packages/albedo_clock/src/albedo_clock.gleam) for timestamps and deadlines. Use system time for durable timestamps and monotonic time for elapsed durations. Request an explicit native time unit. Keep a scaled test timer and the deadline it checks consistent. Use [`albedo_bytes/scalars`](../packages/albedo_bytes/src/albedo_bytes/scalars.gleam) for scalar-bounded previews and names. Do not allocate a codepoint list for the entire input just to truncate a prefix. Scalar limits and grapheme limits serve different purposes. Take a token estimate from [`size`](../src/albedo/harness/size.gleam). The `albedo_token_estimates` [lint](gleam-lint.md#text-and-token-rules) refuses a length divided by 3 or 4, and an `estimate_*` function, anywhere else. Use [`shared`](../src/albedo/shared.gleam) for long-lived immutable values shared across processes. Release a handle at the end of its owner's lifetime. Do not turn changing provider caches into repeatedly replaced compound persistent terms. Use [`albedo_process/memo`](../packages/albedo_process/src/albedo_process/memo.gleam) for changing per-key caches with expiry. Capture compact arguments in stored callbacks rather than the whole actor state. [`session_namespace.watch_kernel`](../src/albedo/daemon/session_namespace.gleam) demonstrates that pattern. Use [`albedo_process/actor_call.try_call`](../packages/albedo_process/src/albedo_process/actor_call.gleam) for finite monitored waits. A timeout does not cancel accepted work. Keep inner waits within their callers' deadlines so the inner failure can be returned. Use a lifetime protocol when the caller must wait for a definite outcome or owner death. Use [`within.within`](../src/albedo/within.gleam) for work that is not an actor call and whose time a slow disk, a hung mount, or a held lock can stretch. It runs the work on a helper and kills the helper at the deadline, which frees any lock it held; the system call it was blocked in still returns on its own. A daemon route that clients use to find a live daemon must not wait unboundedly on such work. `GET /server` leaves out the quota readings and the dismissed-notice filter when they take longer than a second and a half, and still fails at once on a real error. The workspace routes refuse a local folder read after thirty seconds. ## Preserve extension lifecycle boundaries Do not make core depend on extension internals. Daemon, harness, and SDK modules reach extension behavior through plugin contracts in the active composition. The kernel runtime under [`albedo/harness/kernel`](../src/albedo/harness/kernel) and the skills catalog under [`albedo/harness/skills/`](../src/albedo/harness/skills) are core-owned. Extensions import only the parts the [SDK import contract](extensions.md#sdk-imports-and-native-bindings) allows. Keep discovery read-only. A catalog read must not boot Python, allocate managed resources, execute commands, or contact providers. [`runtime/catalog.gleam`](../src/albedo/harness/runtime/catalog.gleam) owns discovery, and [`runtime/preparation.gleam`](../src/albedo/harness/runtime/preparation.gleam) owns preparation work. Distinguish installed extensions, saved selection, and loaded composition. Use installation for schema and deletion ownership, and the loaded composition for session capabilities. Do not leave callable contributions from a failed bundle. See [extensions](extensions.md). Give each allocated resource a cleanup owner. Use the owned preparation contract when a resource must survive handoff. A resource must establish its lifecycle monitors before reporting readiness, and adoption must finish before publication. Make close callbacks idempotent. [`sdk/worker.gleam`](../src/albedo/harness/sdk/worker.gleam) and [`composition.adopt`](../src/albedo/harness/extension/composition.gleam) implement these contracts. Legacy managed callbacks do not acquire them automatically. Keep kernel replacement in the runtime. When a caller owns a live session, use `runtime.apply_change` or `apply_desired` and reconcile the surviving session from either result. Do not add a separate snapshot-and-replace sequence in an HTTP handler. Preserve saved intent on apply failure. A database rollback cannot restore a process that has already stopped. Before changing reload behavior, identify the selection each handler uses, the owner that closes each resource, and the state retained after failure. ## Keep actor handlers responsive Keep lifecycle waits and slow work outside session actors. Command handlers must run outside the actor whose state operations they call. A handler that waits on its own actor deadlocks. See [commands](commands.md) and [`session.gleam`](../src/albedo/daemon/session.gleam). Use [`store.read` or `snapshot`](../src/albedo/harness/sdk/store.gleam) for pure observations. Keep mutations and read-modify-write work on the writer through `query`. Use `query_then` when an actor must remain responsive while a write commits. Publish the result after commit, not after enqueueing. Keep SDK mail insertion and stored-image writes on the connection supplied by the feature transaction. Notify clients after that transaction commits. Inside a snapshot, use the supplied connection for related reads. Do not write, retain the connection, or call Store-level APIs from the callback. Do not wait for capture-reader admission inside the session actor. The separate capture connection exists to avoid that ordering problem. Reserve runtime producer storage before sending payloads or creating completion relays. Use the public runtime entrypoints instead of sending request messages directly. Keep a request's reservation through deferred work and shared waiters, and tag completion with the applicable generation. Requester withdrawal must remove its waiter without cancelling another requester's shared work. Count runtime workers from monitored tickets, not session ownership maps. Keep cleanup capacity separate from public preparation and observation. Reserve cleanup bookkeeping before resource allocation. A stale generation still consumes computation capacity until its worker settles; an unconfirmed cleanup retains its resource callback and cleanup credit afterward. Preserve the runtime's failed-stop fencing and result acknowledgment protocol. See the [runtime admission contract](runtime.md#admission-and-worker-lifetime). Register `stop_before_close` for resources that read the store on their own schedule. The stop callback runs on the writer and must not call the store. Keep resource shutdown within the store's lifecycle. See [`store.gleam`](../src/albedo/harness/sdk/store.gleam). For schema changes, preserve the [foreign-key indexing rule](migrations.md#foreign-key-indexes). Unindexed child lookups can make deletion block the writer. Decide whether each migration is additive or breaking, and declare it. Prefer an additive change. A breaking migration makes every older build refuse the home, so users can roll back only by restoring a backup. Never rename a recorded migration or drop its name. See [downgrades](migrations.md#downgrades). ## Preserve client conventions For terminal screens, follow [Add or change a terminal screen](tui-contributing.md). Reuse the shared layout, filtering, confirmation, and request-generation contracts. Check the result visually using the repository's [UI review instructions](../AGENTS.md#inspect-ui-changes). ## Preserve provider and retry boundaries Keep `ModelProviderPlugin`, `ModelContext`, and `Upstream` as the provider boundary. Shared request and replay types belong under [`openai_api`](../src/albedo/openai_api.gleam). Provider identity, signing, file handling, and body repair remain provider-owned. Reuse shared codecs and transport where they fit. Keep credential recovery separate from request encoding. Preserve the error variants, cancellation behavior, usage, and account attribution used by recovery. Do not add another broad retry loop around the existing model-loop and transport retries. See [authentication](auth.md) and [provider requests](provider-requests.md). After an interrupted or uncertain operation, inspect its receipt or effects before retrying. A missing answer does not establish that the operation did nothing. Keep operation identity across retries where the [admission contract](operations.md) requires it. ## Handle uploaded files Treat client-side attachment checks as convenience. The daemon validates names, encoding, counts, and sizes again and decides admission. Build storage paths from daemon-owned identity, such as the session, input ID, and content hash. Do not use the uploaded filename as a path component. Record attachment metadata in the submission that owns the message. Do not infer that a message had an attachment from text that looks like a label. Do not resend changed attachments under an old input ID. A transcript can outlive the saved bytes, so do not promise that a file named in history is still readable. See [saved pastes and uploads](kernel-state.md#saved-pastes-and-uploads) and the [web client's attachment rules](web.md#chat-attachments). ## Test the observable change Use the shared real-daemon harness for externally visible behavior. Do not copy daemon startup plumbing into a test. Keep upgrade scenarios while their old formats remain supported. See [testing](testing.md), [migrations](migrations.md), and the repository's [test policy](../.agents/skills/writing-tests/SKILL.md). Use focused unit tests for cross-cutting invariants or bug-prone logic that an end-to-end scenario cannot exercise reliably. Do not add tests that only restate constants, copy, or record plumbing. Keep live-provider experiments under `test/manual`. Run the relevant checks before submitting a change. Keep generated audit and benchmark reports under `/tmp`. Retain a measurement in documentation only with its fixture, revision, environment, command, and result artifact. See [Gleam checks](gleam-lint.md) and [performance checks](perf.md). ## Related pages - [All topics](README.md) - [Extensions](extensions.md) - [Test execution](testing.md) - [Workspace packages](workspace-packages.md)