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. Keep HTTP admission and
wire encoding in daemon adapters, composition and kernel lifecycle in the
runtime, and feature state with its owning extension. The
interfaces are defined in
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 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 describes. See
commands and extensions.
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.
Carry a refusal as a typed value from the place that decides it. Daemon
operations return a Refusal 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 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. Its spill
store 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 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. Keep
shared extension helpers under albedo/harness/sdk/ and call their Gleam APIs.
Use albedo_clock 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
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. The
albedo_token_estimates lint refuses a
length divided by 3 or 4, and an estimate_* function, anywhere else.
Use shared 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
for changing per-key caches with expiry. Capture compact arguments in stored
callbacks rather than the whole actor state.
session_namespace.watch_kernel
demonstrates that pattern.
Use
albedo_process/actor_call.try_call
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 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 and
the skills catalog under
albedo/harness/skills/ are core-owned.
Extensions import only the parts the
SDK import contract allows.
Keep discovery read-only. A catalog read must not boot Python, allocate managed
resources, execute commands, or contact providers.
runtime/catalog.gleam owns
discovery, and
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.
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 and
composition.adopt
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 and
session.gleam.
Use store.read or snapshot 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.
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.
For schema changes, preserve the foreign-key indexing rule. 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.
Preserve client conventions #
For terminal screens, follow Add or change a terminal screen. Reuse the shared layout, filtering, confirmation, and request-generation contracts. Check the result visually using the repository's UI review instructions.
Preserve provider and retry boundaries #
Keep ModelProviderPlugin, ModelContext, and Upstream as the provider
boundary. Shared request and replay types belong under
openai_api. 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 and provider requests.
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 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 and the web client's attachment rules.
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, migrations, and the repository's test policy.
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 and performance checks.