3. Server tier — @get-bb/plugin-sdk/server

The server tier is what dist/server.mjs exports: one definePlugin product. The loader calls activate(facade, config); the SDK wraps the loader facade in a PluginContext that is 02's Scope plus the namespaces the loader adds (storage, log, secrets, hostClient) and the ones the SDK adds (preferences, agents, realtime). Every member forwards; nothing in the SDK holds kernel state (packages/plugin-sdk/src/server/context.ts). This subpath also re-exports all of @get-bb/plugin-sdk/contracts; those values get one line each in 3.13 and are documented in §2.

Sources: packages/plugin-sdk/src/server/*.ts, packages/kernel-core/src/{scope,scope-impl,commands,events,activation,actor,services,contract,errors,handle}.ts, packages/kernel-loader/src/{ports,service,loader/facade,composition/service}.ts, packages/kernel-contract/src/catalog.ts. Spec: 02 §3–§7, 01 §5.4, 01 §9. As built: D1–D3, D10, D13, D15, D19 in docs/stage-2/04-kernel-as-built.md.

3.1 definePlugin and activation

Activation rules as built (activation.ts):

• activate() has a 30 s budget (activationTimeoutMs); time spent waiting on an earlier-ordered activation's publish gate is not charged. Throwing NeedsConfigurationError ends in needs-configuration with effects kept; any other throw or a timeout ends in failed with effects disposed.
• Registrations publish in composition order: a generation's provide/define/register/on calls queue until every earlier-ordered activation in the wave settles. The returned promise settles once the registration is visible, so await ctx.provide(...); await ctx.tryInject(...) works inside activate (D1).
• Registration conflicts that depend on other plugins (conflict, forbidden on a noun, reserved_name) are recorded as problems and return a no-op disposer; the row shows degraded and everything else keeps serving. invalid_facts, invalid_contract, unknown_command, and scope_disposed still throw (D1).
• A requires provider must be bound before activation starts (waiting {missing}); a uses provider does not block. Both re-run activate() on bind, rebind, or unbind (for multi, any candidate add or remove): the scope is disposed, a fresh scope is made, and activate runs again. More than 8 re-runs in 10 s parks the plugin in failed with activation_loop (02 §4.4). A plugin that wants to survive a uses change without re-running declares nothing and calls ctx.watch() instead.
• Noun ownership is composition order (lowest order, ties by plugin id); a later claimant of a manifest noun is degraded: noun X claimed by Y and its registrations under the noun are forbidden (D2).
• Every activation runs in-process in Stage 2 (base.yaml rows and path: installs). Worker-only gaps: declared input .transform() outputs do not reach a worker handler (D7; README deviation 3).

import { definePlugin, defineBackgroundService, sleep, NeedsConfigurationError } from "@get-bb/plugin-sdk/server";
export default definePlugin({
  config: z.object({ prefix: z.string().default("note") }),        // optional; omit for ActivationConfig
  async activate(ctx, config) {
    const db = await ctx.storage.openDatabase(MIGRATIONS);
    if (!(await ctx.secrets.resolve({ name: ctx.secrets.reference("token") }).catch(() => null)))
      throw new NeedsConfigurationError("set the token in Settings");  // effects kept; row shows needs-configuration
    await ctx.provide(notes, handlers(db, config.prefix));
  },
  background: { tick: defineBackgroundService(async (_scope, signal) => { while (!signal.aborted) await sleep(60_000, signal); }) },
});

3.2 PluginContext members

3.3 Services: provide, inject, watch, candidates, facts

• Provide. The container validates facts against contract.facts (invalid_facts throws). A second provide of a non-multi contract from the same generation is a conflict problem; a multi contract may be provided N times with a distinct contract.factsKey value per call. A kernel/… id from a plugin scope is a reserved_name problem. Every kind: "mutation" method derives one side: "server" command named method.command (default <pluginId>/<service>.<method>); a noun the plugin does not own is a forbidden problem, a taken name a conflict problem, and the other methods still register (02 §3.2; scope-impl.ts). A multi contract may not carry mutations (invalid_contract, D2).
• Handlers. A handler receives what the container validated: in-process the method's Standard Schema ran once, defaults and transforms applied. The second argument is the CallContext (callId, traceId, actor, session, scope, signal, command), extended by §2's fields for a defineService handler. Every call is timed, counted per plugin, and failure-isolated; a non-KernelError throw becomes plugin_error.
• Inject. inject binds by contract.id and satisfies(contract.version, range); a multi contract answers invalid_contract ("use candidates()"). The handle is built from the provider's registered contract; the SDK only types it as HandleOf<C>.
• Watch. In-process the listener fires synchronously with the current binding, then on a microtask after each registry flush (D3). In a worker, core answers invalid_contract {contractId} for an id nobody in the composition declares; the facade folds that into the in-process answer (service_unavailable / null / [] / null) and, for watch, fires unbound itself and registers the real watch on the first kernel/service.bound for that id, which fires bound (I14; README deviation 2). A throwing watcher is counted and reported as kernel/listener.failed; the others still fire.
• Arbitration. One provider is bound per single-provider id: replaces → user pin (kernel/pins map, target service:<id>, written by composition.pin) → manifest priority (loader fills 0; there is no runtime priority argument) → sorted plugin id (02 §3.4). Crash fallback rebinds to the next candidate and emits kernel/service.rebound; a needs-configuration plugin stays a candidate.
• Facts. Frozen for the generation; change a fact by reloading. Peers decide by facts, never by plugin id (02 §3.5).
• Handles. ServiceHandle<C> = { id, version, providerPluginId, generation, facts, alive } plus one method per contract method; CallOverrides = { signal?, actor? (system callers only, else forbidden), idempotencyKey? }. A handle binds one (providerPluginId, generation) and never rebinds; a mutation handle call is a commands.dispatch of method.command, so interceptors and actor stamping cannot be bypassed in-process (02 §3.2, §3.6).

withDefaults(def, handlers) (@get-bb/plugin-sdk/server, src/server/boundary.ts; added at dc07292bf): returns the same handler table with every non-custom method's input re-validated through the contract's own schema at the plugin boundary. In-process the container already validated and filled defaults, so this is a second pass; in a worker the input arrived through contract.json's JSON Schema and the schema's transforms run only here. Handlers see one shape in both placements. A rejected input throws invalid_input with issues; a stream handler that returns no async iterable throws invalid_output. Use it as await ctx.provide(def, withDefaults(def, { ... })).

Re-runs (at dc07292bf). When a uses binding changes, kernel-core tears the dependent down and re-activates it inside one registry batch, so a dependent compares the binding before and after (the same pluginId@generation) and never observes a gap. A handle follows a same-generation re-provide instead of answering stale_handle.

3.4 Commands

Names and ownership. CommandName = <noun>.<segment>(.<segment>)*; a plugin always owns nouns that start with <pluginId>/ and owns a bare manifest noun (contributes.commands.nouns) only as the earliest claimant in composition order (D2). Reserved server nouns: kernel, composition, plugin, host, preference, secret. Wildcards match on segment boundaries: thread.* covers thread.queue.create.

Dispatch sequence as built (commands.ts):

1. lookup (unknown_command).
2. resolve actor/session from the scope or the enclosing call (forbidden for a non-system override).
3. def.actors check (forbidden).
4. validate input (invalid_input).
5. depth cap 16 (dispatch_depth).
6. build CommandContext with deadline = now + deadlineMs (a nested dispatch takes min(own, parent's remaining)).
7. kernel/command.dispatched.
8. before chain.
9. executor (none.
10. service_unavailable).
11. validate output (invalid_output).
12. after listeners.
13. kernel/command.completed | .failed | .vetoed.

• Order. Hooks run priority desc → exact name before wildcard → composition order → registration order (D3).
• Veto. throw new KernelError({ code: "vetoed", message, data: { reason } }); the kernel fills data.by with the interceptor's plugin id when omitted. A veto reaches the dispatcher as {ok: false, error} and emits kernel/command.vetoed; it is never swallowed.
• Budgets. deadlineMs bounds the whole dispatch; §2's method() fills it from blocking.maxMs (1 ms..60 min) or 60 s for a mutation (kernel-contract/src/define.ts). Expiry aborts cmd.signal and answers timeout. Each interceptor also has a 10 s budget (interceptorTimeoutMs) for its own work before it calls next(); an overrun skips it, emits kernel/listener.failed, and cannot veto (D3).
• Actors. Actor = { kind: "human" \| "agent" \| "plugin" \| "system", id }; Session = { id, actor, client: {kind, surface, version}, createdAt, credentialId } (02 §7). A plugin scope dispatches as {kind: "plugin", id: pluginId}; an agent tool as {kind: "agent", id: threadId}; the CLI as human or agent. MethodDef.actors gates both handle calls and dispatches before any interceptor: kernel/secrets.put is ["human"], every kernel/plugins and kernel/composition mutation is ["human", "agent"], so a plugin calling them gets forbidden.

await ctx.commands.before("thread.send", async (cmd, next) => {
  const head = await threads.show({ threadId: cmd.input.threadId });
  if (head.providerId !== "claude-code") return next(cmd);
  if (cmd.actor.kind === "agent" && cmd.input.options.permissionMode === "bypass")
    throw new KernelError({ code: "vetoed", message: "agents may not bypass", data: { reason: "ceiling" } });
  return next({ ...cmd, input: { ...cmd.input, actions: armPlan(cmd.input) } });
}, { priority: 0 });
await ctx.commands.after("thread.stop", (cmd, outcome) => { if (outcome.ok) void settle(cmd.input.threadId); });

3.5 Events and realtime

Scope tagging: a listener on scope S sees a dispatch from S, a descendant of S, or root (inbound wire frames are re-emitted at root with meta.source.process set); global: true sees every dispatch. Same-priority listeners fire in composition order, then registration order. Emitting an undefined name throws unknown_event; a mode or process mismatch throws invalid_contract.

Kernel events a server tier may subscribe to (02 §5.5; events.ts KERNEL_EVENTS): kernel/service.bound | .rebound | .unbound {serviceId, pluginId, generation, previous}, kernel/activation.changed {pluginId, generation, state}, kernel/boot.settled, kernel/effect.failed | .late, kernel/listener.failed, kernel/wire.dropped, kernel/command.dispatched | .completed | .failed | .vetoed {command, durationMs, error}, kernel/catalog.changed, kernel/preferences.changed {key, scope, threadId, value, updatedAt}, kernel/secrets.changed {name}, kernel/ui.command | .result. kernel-store adds kernel/store.appended, kernel/store.changed, kernel/store.rows, kernel/<entity>.changed, kernel/thread.purged (D12); the threads server tier derives tail state from kernel/store.appended and reacts to kernel/thread.changed and kernel/activation.changed. Declare merged Events / Commands through @get-bb/plugin-sdk/contracts (§2).

3.6 Storage, kv, database, log

Every storage, secrets, and hostClient member checks ctx.signal.aborted first, so a promise leaked from generation N fails with scope_disposed instead of writing into generation N+1 (facade.ts).

// read one row: every column is a SqlParam and is narrowed by hand (hello-slot server.ts `valueOf`)
const row = await db.get("SELECT words, chars FROM totals WHERE id = ?", [1]);   // SqlResultRow | null
const words = row?.["words"];
if (typeof words !== "number") throw new KernelError({ code: "internal", message: "totals row missing" });

3.7 Preferences and secrets

The kernel/preferences handle is injected once per activation and reused; a rejected injection is retried on the next call. On set/clear core checks the owner: a plugin actor may write only <pluginId>/… keys, system only kernel/…, a human any key (forbidden otherwise). A settings save emits kernel/preferences.changed and never re-runs the plugin; as built a needs-configuration row re-runs only on a change to one of its own contributes.settings keys (D8).

3.8 Agents

The plugin must declare uses: { "threads/agent-config": "^1.0.0" }: that is also what re-runs activate() when the binding changes (02 §4.4), so a late-installed threads is seen either way. The contract object is the SDK's _pending copy of threads/agent-config (contribute and revoke only); the container binds by id, so a shape drift is type-level only. The threads server tier provides contribute/revoke/resolve keyed by the caller's call.scope and evicts by (pluginId, generation) on kernel/activation.changed (02 §3.8). Realistic usage: the fixture contributes instructions plus tools: { include: ["notes_fixture_notes_create"], exclude: [] } and keeps serving when threads is absent.

3.9 Host client

At 6f3d4592f the core → role rpc path from a server tier was not wired (see the wiring note below for dc07292bf): ctx.hostClient(...).call answers service_unavailable in the product; host tiers still run, and createTestPlugin wires a fake role per contributes.hostRoles row so the typed face is testable (D15, flippable; D5). The rejection is a KernelError instance with code service_unavailable (retryable: true), built by init.fail in packages/core/src/host-client.ts (no host worker, host tier not ready, or an undeclared role name) and rethrown unchanged by the typed face (server/host-client.ts); packages/core/src/core.ts now passes that factory to the loader, so whether D15 still holds in the product is an open question (§0.6).Until the kernel closes D15 on every host, try the host, then fall back in-process, and warn once:

let warned = false;
const countVia = async (text: string): Promise<Counts> => {
  try { return await echo.call("host-count", { text }); } catch (err) {
    if (!(err instanceof KernelError) || err.code !== "service_unavailable") throw err;
    if (!warned) { warned = true; ctx.log.warn("echo role unreachable; counting in-process", { code: err.code }); }
    return countText(text);                                    // the same function the role runs
  }
};

Wiring (at dc07292bf). Core passes createHostClients(...).clientFor (packages/core/src/host-client.ts) to the loader, so ctx.hostClient(contract, name).call(...) reaches the plugin's rpc role process over the same published host artifact. The service_unavailable answer described above is the 6f3d4592f state (D15); keep the fallback pattern for a host that is offline.

3.10 Background services and sleep

Rules (01 §5.4; kernel-loader/src/loader/background.ts): keys of background must equal contributes.background (a difference is an invalid_contract problem and the service does not run). A non-empty contributes.background starts a separate background worker; the server entry stays in-process (D10). Each service starts after the activation reaches running/degraded/needs-configuration. Resolve → stopped (not restarted). Throw → crashed → restart with min(1000 ms × 2^n, 60 s), n reset after 5 min healthy. Throw NeedsConfigurationError → needs-configuration for the service plus ctx.status.needsConfiguration(message) for the plugin. Stop aborts the signal and waits up to 5 s. There is no kernel schedule table or tick: run a timer inside start or depend on automations/schedules.

3.11 Kernel services a plugin may call

Inject the kernel-core three by the contract objects §2 exports (preferences, secrets, telemetry, plus secretsBackend / telemetrySink to provide a backend or sink) with range "^1", and list the id in the manifest's requires/uses. The loader-owned kernel/plugins and kernel/composition and kernel-contract's kernel/contract have no contract object in the SDK surface; a plugin injects them by declaring its own defineService copy of the id (the container binds by id and builds the handle from the provider's registered contract), as the Stage 2 threads plugin does for kernel/composition and kernel/catalog.

kernel/preferences 1.0.0 (kernel-core/src/services.ts; 02 §3.7):

• get {key, scope: PrefScope, threadId: string | null} (query) → {value: JsonValue | null, updatedAt: number | null}; threadId is non-null exactly for thread scope.
• set {key, scope, threadId, value, expectedUpdatedAt: number | null} (mutation preference.set) → {updatedAt}; owner check; CAS null = upsert, 0 = key must be unset, else must equal the stored stamp (conflict). Emits kernel/preferences.changed.
• clear {key, scope, threadId} (mutation preference.clear) → null; emits the change with value: null.
• list {prefix} (query) → {entries: {key, scope, threadId, value, updatedAt}[]}.

kernel/secrets 1.0.0:

• resolve {name} (query; container callers only) → {value}; not_found when unset.
• put {name, value} (mutation secret.set, actors: ["human"]) → null; emits kernel/secrets.changed.
• delete {name} (mutation secret.delete) → null.
• list {} (query) → {names, backend}; backend is the active backendId.

kernel/secrets.backend 1.0.0 (multi, factsKey: "backendId"; provide with provide(secretsBackend, impl: SecretsBackendImpl, {backendId}); the active backend is the first candidate, pin service:kernel/secrets.backend):

• get {name} → {value: string | null}; set {name, value} → null; delete {name} → null; list {} → {names}.

kernel/telemetry 1.0.0:

• record {name, props: Record<string, JsonValue>} (query-shaped, never intercepted) → null; fans out to every kernel/telemetry.sink candidate, failures dropped; a no-op without sinks. The kernel records kernel/command.completed|failed|vetoed and kernel/listener.failed itself.

kernel/telemetry.sink 1.0.0 (multi, factsKey: "sinkId"; provide with provide(telemetrySink, impl: TelemetrySinkImpl, {sinkId})):

• record {name, props} → null.

kernel/plugins 1.0.0 (kernel-loader/src/service.ts; noun plugin; every mutation actors: ["human", "agent"], so a plugin gets forbidden):

• list {} → {plugins: PluginStatusJson[]}.
• show {id} → {status, manifest, contract, appContributions, sourceDir, forkedFrom}.
• plan {source} → {packageName, pluginId, version, digest, resolution}; source is npm: | url: | path: | bundled:<id>.
• install {source, confirm: {name, version, digest} | null, force} (plugin.install) → PluginStatusJson.
• update {id: string | null, all, check, force} (plugin.update) → {reports: {id, current, available, refused}[]}; exactly one of id/all.
• rollback {id} (plugin.rollback) → PluginStatusJson.
• remove {id, purge} (plugin.remove, destructive) → null.
• reload {id} (plugin.reload) → PluginStatusJson.
• fork {id, as: string | null, detach} (plugin.fork) → {newId, sourceDir, next}.
• revert {id} (plugin.revert) → {forkId, originalId}.
• enable {id} / disable {id} (plugin.enable / plugin.disable) → PluginStatusJson.
• devStop {id} (plugin.dev.stop) → PluginStatusJson.
• logs {id, follow, since: number | null} (stream) → {time, level, message, fields} lines.

kernel/composition 1.0.0 (kernel-loader/src/composition/service.ts; noun composition; mutations actors: ["human", "agent"]):

• dump {row: string | null} → the dump ({version: 1, layers, rows, arbitration, error}); not_found for an unknown row.
• layer {layer: "user"} → {text: string | null, revision}.
• patch {ops, revision} (composition.patch) → {revision}.
• setRow {id, disabled, name, config, isolation, source} (composition.setRow; null leaves a field alone) → {status}.
• insertRow {row: {id, name, config}, after: string | null} (composition.insertRow) → {status}.
• pin {target, pluginId: string | null} (composition.pin; null clears) → {pins}; writes the kernel/pins profile preference through kernel/preferences.set.
• pins {} → {pins: {target, pluginId, live}[]}.
• experiments {} → {experiments: {id, summary, enabled}[]}.

kernel/contract 1.0.0 (kernel-contract/src/catalog.ts; all queries):

• manifest {} → the CLI manifest {serverId, generation, methods, services, groups, guide}.
• guide {chapter: string | null} → a guide chapter or the chapter list (no HTTP exposure).
• reference {pluginId} → reference docs for one plugin's services.
• skillReference {activeTools: string[]} → {text, docs} (no CLI exposure).

Added at dc07292bf (next/docs/status/stage-2-domain.md §5, §7):

3.12 Errors and stale handles

Closed kernel codes (KERNEL_ERROR_CODES): invalid_input, invalid_output, invalid_facts, invalid_contract, reserved_name, unknown_method, unknown_command, unknown_event, not_found, unauthenticated, forbidden, vetoed, conflict, precondition, service_unavailable, needs_configuration, stale_handle, scope_disposed, timeout, cancelled, dispatch_depth, activation_loop, plugin_error, internal. A plugin's own codes are <pluginId>/<code> with a declared HTTP status (default 500). Any non-KernelError thrown by a handler, interceptor, or listener becomes plugin_error {pluginId}; the stack never crosses a boundary.

Stale handles and disposal (02 §3.6, §4.3, §4.4; handle.ts, activation.ts, facade.ts):

• A handle call checks, in order: consumer scope disposed → scope_disposed; provider generation no longer live → stale_handle {serviceId, pluginId, generation}; unknown method → unknown_method; actor kind not in MethodDef.actors → forbidden; input → invalid_input. handle.alive is entry.alive && !consumer.disposed.
• Teardown of a generation marks its provider entries dead first (new calls answer stale_handle), drains in-flight calls up to 5 s (drainTimeoutMs; a timeout emits kernel/effect.failed), then disposes the scope: children (reverse creation order) → effects LIFO (5 s each; a throw or timeout emits kernel/effect.failed and disposal continues) → signal.abort(). A generation swap is one step: old unbound, new bound, dependents re-run once; consumers never observe "no provider" between two generations of one plugin.
• effect() on a disposed scope throws scope_disposed; an effect registered during disposal is disposed at once and emits kernel/effect.late. Queued publishes of a removed generation reject with scope_disposed.
• The facade's storage, secrets, and hostClient members throw scope_disposed once ctx.signal is aborted; a closed database handle answers stale_handle; log becomes a no-op. A preferences.define handle keeps working across the generation's life because the kernel/preferences provider is kernel-owned and never rebinds.
• A consumer that holds a handle across a provider reload must re-inject (or hold it through watch, which delivers rebound); a requires/uses declaration re-runs activate() instead.

3.13 Types index

Server-tier types not tabled above, one line each:

Re-exports of @get-bb/plugin-sdk/contracts (documented in §2; one line each here for the lock):