From 8f4a03e52edf5e7d6f82aa70634a7af4ce7d611a Mon Sep 17 00:00:00 2001 From: Brian Ketelsen Date: Thu, 27 Aug 2026 21:43:50 -0400 Subject: [PATCH] docs(surface): describe createSurfaceApp's CLI-backed mutation boundary MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The createSurfaceApp doc comment still claimed "No route mutates the queue in this slice", which stopped being true once the surface grew its operator mutation routes (approve, reject, defer, requeue, cancel, note, prioritize, re-verify, and the board actions) — all attributed `operator:web`. Restate the boundary the way accepted ADR-0060 and docs/design/operator-surface.md do: the surface is read-first, its mutation routes are exactly the operator commands the CLI already has invoked through the same store methods, and it introduces no new state transition, no worker-facing route, and no rendered lease token. Also attach the comment to createSurfaceApp itself rather than to the SurfaceEnv type alias that had drifted between them. Comment-only; no runtime behavior changes. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01UigLsmd17TVDuaaSN4yfdU --- src/surface/app.ts | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/src/surface/app.ts b/src/surface/app.ts index 91e70e1..b10acec 100644 --- a/src/surface/app.ts +++ b/src/surface/app.ts @@ -68,13 +68,16 @@ export interface SurfaceOptions { stream?: StreamOptions; } -/** - * The read-first operator surface (ADR-0060): a cookie session over - * `SNOWCAT_APP_TOKEN`, then server-rendered pages over the same `QueueStore` - * methods the CLI uses. No route mutates the queue in this slice. - */ type SurfaceEnv = { Variables: { actor: string } }; +/** + * The read-first operator surface (ADR-0060): a session, then server-rendered + * pages over the same `QueueStore` and `ControlPlaneStore` methods the CLI + * uses. Its mutation routes are exactly the operator commands the CLI already + * has, invoked through those same CLI-backed store transitions and attributed + * to the web actor: the surface introduces no new state transition, no + * worker-facing route, and never renders a lease token. + */ export function createSurfaceApp(options: SurfaceOptions): Hono { const app = new Hono(); const accessMode = options.access !== undefined;