@braidhq/server 0.1.0 → 0.2.0

package/README.md

@@ -1,136 +1,164 @@
 # @braidhq/server
 
-REST + SSE server for Braid. Hono-based, with an OpenAPI 3 spec
-exposed at `GET /openapi.json` for any consumer that wants typed
-access to the graph operations.
+Braid keeps a product's intent and its code aligned in one knowledge graph. `@braidhq/server` is the process that runs it. It wires core's ports to real filesystem, git, and vendor adapters, exposes the graph over HTTP, and drives the agents that fill it.
 
-## openapi-mcp-gateway Integration
+## Role
 
-Skills shipped with `@braidhq/core` and `@braidhq/ontology-ddd` invoke
-the server through MCP tools, not curl. The wiring runs the gateway
-as a **per-skill stdio child of claude** — no long-running HTTP
-server, gateway lifecycle tracks the skill run automatically.
+Server is the composition root and the presentation layer. It turns the framework into a running application.
 
-```
-┌──────────────────┐   /openapi.json    ┌─────────────────────┐
-│ @braidhq/server  │ ◀───── HTTP ────── │ openapi-mcp-gateway │
-│ (this package)   │ ────── REST  ────▶ │ (uvx, stdio child)  │
-└──────────────────┘                    └─────────────────────┘
-                                                   ▲ stdin/stdout
-                                                   │ MCP
-                                        ┌─────────────────────┐
-                                        │ spawned claude      │
-                                        │ subprocess (skill)  │
-                                        └─────────────────────┘
-```
+- **The Wiring**: The composition root that binds core's ports to concrete adapters, the one place infrastructure is instantiated.
+- **The Adapters**: Filesystem and git implementations of core's repositories and history, plus the subprocess runner that executes skills.
+- **The API**: A REST and SSE surface built on Hono, one router per resource, with authentication, workspace scoping, and an OpenAPI 3 spec at `GET /openapi.json`.
 
-### 1. Install `uv` (one-time setup)
+## Positioning: framework kernel and worldview preset
 
-`openapi-mcp-gateway` is a Python package distributed via PyPI. The
-gateway is launched on demand by claude via `uvx` (UV's "run an
-ephemeral package" command), so the only thing you have to install
-locally is the `uv` runtime itself:
+Braid is worldview-agnostic. The intent-graph engine, workspaces, proposals, HITL review, the reactor, and the authorization policy, knows nothing about software. A worldview supplies the rest: an ontology plus the storage, source loaders, and agent that serve it. The software worldview, a DDD ontology whose sources split into `intent` and `code`, is the default, not a built-in.
 
-```bash
-# macOS
-brew install uv
-# linux / windows: see https://docs.astral.sh/uv/getting-started/installation/
-```
+Two layers share this package for now.
+
+- **Kernel**: `composeApp`, routes, middleware, policy, auth mode, and the generic filesystem infrastructure. Worldview-agnostic. `composeApp` registers no plugin, a caller hands it a `PluginRegistry`. Nothing here imports a concrete ontology, storage, loader, or agent.
+- **Coding preset**: `composeFsApp` assembles the default bundle, Kuzu storage, the DDD ontology, the git, github, and drive loaders, and the claude-code agent, over filesystem persistence. Its default identities live as `DEFAULT_*` constants at the head of the file.
+
+A future app, a story world or a research-notes base, reuses the kernel and swaps the preset for its own ontology and adapters. When that second worldview arrives, the coding preset extracts into its own package, `@braidhq/preset-code`, and this package drops its plugin dependencies. Until a second worldview exists that pressure is speculative, so both layers stay here at no cost. The seam is `composeApp`: whatever the kernel reaches without a concrete plugin already belongs to it.
+
+## Structure
 
-The Braid server **preflight-checks for `uv` at boot**. If it's not
-found, you'll see:
+The package layers outward from core. Infrastructure implements core's ports, routes expose them, and composition binds the two.
 
 ```
-[braid] `uv` not found on PATH; the built-in braid-core MCP gateway
-        will not be available. Install via `brew install uv` or
-        https://docs.astral.sh/uv/ to enable.
+src/
+├── server.ts          process entry, serves the app
+├── app.ts             builds the Hono app, mounts middleware and routes
+├── composeApp.ts      the worldview-agnostic kernel root
+├── composeFsApp.ts    the coding preset, filesystem and vendor adapters
+├── startup.ts         blocking per-workspace boot steps
+├── authMode.ts        AuthMode strategy, localTrust and authenticated
+├── routes/            one router per resource
+├── middleware/        auth, cors, error mapping, workspace scoping
+├── policy/            authorization rules
+└── infrastructure/   adapters behind core ports, one folder per domain concern
+    ├── hitl/         proposal and clarification stores
+    ├── workspace/    workspace repository, registry, discovery, PRODUCT.md writer
+    ├── skill/        skill registry, run store, subprocess runner and its event stream
+    ├── source/       source unit observations, digests, intent listing
+    ├── model/        graph serializer
+    ├── reactor/      reactor cycle store
+    ├── batch/        batch plan store
+    ├── history/      GitWorkspaceHistory, commit messages
+    ├── users/, auth/, secrets/, oauth/   host services, no core port
+    └── _shared/      cross-cutting fs plumbing, paths, json store, frontmatter
 ```
 
-Skills with `requiredMcpServers: ['braid-core']` will then surface
-as not-ready in Studio's sidebar. Other skills keep working.
-
-### 2. That's it
-
-No environment variables to set, no separate gateway process to run.
-When Braid spawns a skill, the skill's mcp-config gets a stdio entry:
-
-```jsonc
-{
-  "braid-core": {
-    "type": "stdio",
-    "command": "uvx",
-    "args": [
-      "openapi-mcp-gateway",
-      "--spec",
-      "http://127.0.0.1:4321/openapi.json",
-      "--transport",
-      "stdio",
-      "--name",
-      "braid-core"
-    ]
-  }
-}
-```
+- **composeApp / composeFsApp**: The kernel root and the coding preset. `composeApp` takes a deps object, registers no plugin, and defaults every unset port to an in-memory adapter. `composeFsApp` builds the filesystem, git, and vendor adapters, registers the default plugin bundle, then hands the result to `composeApp`. Production runs the latter. See Positioning above.
+- **startup**: The two boot passes, `startupBeforeServe` and `startupAfterServe`. See Startup below for the full order.
+- **infrastructure**: The real adapters behind core's ports, grouped by domain concern to mirror `core/domain`, never by storage technology. Each folder owns one aggregate's adapter, so a future SQLite or Postgres store lands beside the filesystem one instead of in a separate `sql/` tree. `hitl/` persists proposals and clarifications, `workspace/` the graph and workspace files, `history/` records every change as a git commit, `skill/` runs a skill as a subprocess and streams its events back. `_shared/` holds the cross-cutting fs plumbing, its underscore marking it as the one folder that is not a domain concern, matching `routes/_shared.ts`. `users/ auth/ secrets/ oauth/` are host services with no core port.
+- **routes**: One `createXxxRouter(deps)` per resource, each taking only the services it needs. Bodies validate through zod, path ids parse through their branded schema.
+- **middleware**: The cross-cutting edge. Auth resolves the user, workspace middleware scopes and authorizes the request, and the error middleware maps `BraidError` subclasses to problem+json status codes.
+
+## Startup
+
+The blocking phase runs inside `composeFsApp` before the server accepts a request, in two groups.
 
-claude spawns the gateway, the gateway pulls the spec from the
-running Braid server, and the REST surface becomes MCP tools for the
-duration of the skill run.
+Provision host identity, who may use this server:
 
-First-time runs take an extra ~1–2 seconds (uvx caches
-`openapi-mcp-gateway` under `~/.cache/uv/`). Subsequent runs hit the
-cache.
+1. `authMode.provision` seeds what the deployment's mode needs. Local trust seeds the `local-user` fallback account, authenticated mode syncs the login allowlist to the user roster. See Auth Mode below.
 
-### 3. Author skills against the MCP tools
+Reconcile workspaces, register then boot each:
 
-Skill prompts call MCP tools by their `operationId`:
+2. `discoverCanonicalWorkspaces` registers workspaces present on disk but absent from the registry.
+3. `ensureWorkspaceOwners` gives any ownerless workspace the auth mode's default principal, or throws under authenticated mode where every workspace must have an explicit owner.
+4. `startupBeforeServe` runs the per-workspace pass. Per workspace it provisions the git repo and store, recovers a batch left running by a killed process, subscribes the reactor when the workspace opts in, and fires a catch-up sync for each loader-backed source.
 
-- `braid_search_nodes(workspaceId, q, type?, status?, limit?, offset?)`
-- `braid_get_scope(workspaceId, nodeId, depth)`
-- `braid_get_ontology(workspaceId)`
-- `braid_submit_proposal(workspaceId, operations, generatedBy, rationale)`
-- `braid_submit_clarify(workspaceId, question, candidates)`
-- `braid_mark_clarify_applied(workspaceId, clarifyTicketId, status, userId, proposalId?)`
-- …and the rest, one per operation in `/openapi.json`.
+After `serve()`, the background phase runs cosmetic recovery that need not finish first, via `startupAfterServe`:
 
-Exact tool names depend on `openapi-mcp-gateway`'s naming convention
-(typically `<server-name>_<operationId>` with snake_case
-normalisation). Inspect the spec or the gateway's `tools/list`
-response to see live names.
+5. `reapOrphanRuns` marks runs left without a completion, from a killed process, as aborted so the UI does not show them active forever.
 
-### Pinning the uv binary
+Both passes live in `startup.ts`, `startupBeforeServe` before `serve()` and `startupAfterServe` after. A new blocking per-workspace step is added to `startupBeforeServe`, a new background step to `startupAfterServe`. Provisioning tied to one adapter stays next to that adapter's construction. Source loaders take part without a bespoke step, the sync in step 4 fires for any registered loader.
 
-For reproducibility (e.g. CI environments with multiple Python
-toolchains) you can pin a specific `uvx` binary via the
-`BRAID_UVX_BIN` env var. composeFs preflight-checks the pinned
-binary; if it's not executable, the gateway entry is skipped same as
-when `uv` is missing entirely.
+## Auth Mode
 
-```bash
-export BRAID_UVX_BIN=/opt/homebrew/bin/uvx
+One axis separates a trusted local install from an authenticated remote server, who the implicit user is. Rather than scatter that decision, an `AuthMode` strategy carries it, and the auth and ownership code reads the strategy, never a hardcoded `local-user`.
+
+```mermaid
+classDiagram
+    class AuthMode {
+        <<interface>>
+        +defaultPrincipal: UserId | null
+        +requiresAuth: boolean
+        +provision(context) Promise
+    }
+    class localTrust {
+        <<const>>
+        defaultPrincipal = local-user
+        requiresAuth = false
+        provision() seeds local-user
+    }
+    class authenticated {
+        <<const>>
+        defaultPrincipal = null
+        requiresAuth = true
+        provision() syncs allowlist
+    }
+    AuthMode <|.. localTrust
+    AuthMode <|.. authenticated
 ```
 
-### Forward compatibility (hosted Braid)
+Two consumers read the strategy, neither a hardcoded account. `authMiddleware` resolves the caller, applying the Bearer gate under `requiresAuth` and falling back to `defaultPrincipal` when one is present. `ensureWorkspaceOwners` gives an ownerless workspace the principal, or throws when there is none.
+
+`composeFsApp` picks the mode from `BRAID_LOCAL_TRUST`, local trust by default. Adding a mode, a service account or an SSO-only deployment, is a new `AuthMode`, with no change to the middleware, the ownership code, or boot.
+
+## Authorization
+
+Every gated action is a capability. The server is the authoritative check, and Studio mirrors the same list to grey out affordances it cannot use. The authoritative logic is `packages/server/src/policy/checks.ts`, the matrix below is a readable mirror of it.
+
+### Where the decision happens
+
+A request's permission is decided in three steps, all under `policy/`.
+
+1. `resolveViewer(user, member)` builds a `ViewerContext` once per request, the caller's `effectiveRole` in this workspace. It is the sole place a server admin short-circuits to an `owner` role.
+2. `workspaceAccessMiddleware` runs `resolveViewer`, stamps the viewer on the request, and rejects an outright outsider. `requirePermission(cap)` and the server-scope `requireServerCapability(cap)` are the route gates that read it.
+3. `PermissionRegistry.can(capability, viewer)` finds the capability's check and evaluates it against the viewer. An unregistered capability denies by default.
+
+Each capability owns one pure check in `checks.ts`, a stateless const object. Plugins register their own checks on the same registry, so adding a capability never edits an existing one.
+
+### Capability matrix
+
+Workspace roles resolve from membership. `admin` is the server role, which short-circuits to an `owner` effectiveRole in any workspace, so an admin holds every workspace capability below.
+
+| Capability | owner | maintainer | member | Notes |
+|---|:--:|:--:|:--:|---|
+| `server.admin` | n/a | n/a | n/a | Server role `admin` only. Gates `/admin`, read from the server role, not `effectiveRole`, since a workspace owner also resolves to `owner`. |
+| `workspace.create` | n/a | n/a | n/a | Server scope, resolved with no member, so only a server admin passes. |
+| `workspace.read` | yes | yes | yes | Any member. |
+| `workspace.write` | yes | | | Owner only. |
+| `proposal.read` | yes | yes | | Owner or maintainer. |
+| `proposal.write` | yes | yes | | Owner or maintainer. |
+| `clarification.read` | yes | yes | | Owner or maintainer. |
+| `clarification.write` | yes | yes | | Owner or maintainer. |
+| `history.write` | yes | | | Owner only. |
+| `skill.run` | yes | maybe | maybe | Owner always. Otherwise the skill's `allowedRoles`, overridden per member by `skillOverrides`. |
+
+## Boundaries
+
+These are the rules for anyone editing server. They are enforced in review rather than by tooling.
+
+- **Composition Only Here**: Infrastructure concretes are instantiated at the composition root, never inside a route or a service.
+- **Routes Stay Thin**: A route validates input, calls one service, and shapes the response. Business rules live in core, not in the handler.
+- **Adapters Implement Ports**: Every fs, git, or agent class satisfies an interface declared in core, so swapping one never touches the framework.
+- **Errors Map at the Edge**: Domain code throws a `BraidError`, and the error middleware is the only place that turns it into an HTTP status.
+- **Scope Through Middleware**: Workspace access is checked once in middleware, not re-derived inside each route.
+
+## Dependencies
 
-When Braid grows a hosted product where the server runs remotely:
+Server sits at the outer edge, above core and the plugin packages the coding preset bundles as defaults.
 
-- If claude runs locally (desktop spawns it): the stdio path above
-  still works. The local gateway just talks HTTPS to the remote
-  `/openapi.json` and REST endpoints, with auth headers passed
-  through workspace-level MCP server config.
-- If claude runs in the cloud (browser Studio): the stdio path runs
-  server-side, gateway loopbacks to the local server.
+- **Depends On**: `@braidhq/core` and `@braidhq/schema`, `hono` for HTTP, `simple-git` for history, and, only through the coding preset, the default plugin bundle of `storage-kuzu`, `agent-claude-code`, `ontology-ddd`, and `source-loader-*`. The kernel itself needs none of the plugin packages; they leave with the preset when it extracts. See Positioning.
+- **Consumed By**: `cli` and the `desktop` Tauri shell, which run it as their backend.
 
-The `streamable-http` MCP transport stays first-class in the schema
-so workspaces can declare any third-party HTTP MCP server (Redmine /
-Notion / Linear / …) alongside the stdio braid-core. The two
-transports are not mutually exclusive.
+## MCP Gateway
 
-## Routes That Are Not in the Spec
+Skills run as coding-agent subprocesses and reach this server's REST API as MCP tools, not by curl. An off-the-shelf translator, `openapi-mcp-gateway`, reads `/openapi.json` and re-exposes each operation as a tool named `braid-core`.
 
-- SSE streams (`/workspaces/{ws}/runs/{runId}/events`,
-  `/workspaces/{ws}/events`) — not invocable as one-shot MCP tools.
-- OAuth callbacks (`/oauth/google/callback`) — HTML response.
-- Workspace management (`/workspaces/*`) — admin surface for CLI
-  and Studio, not for skills.
+The gateway is spawned per skill run and torn down with it, so there is no long-lived gateway process, no open port, and no network auth to manage. The transport is an implementation detail of the runner.
 
-The `GET /openapi.json` test in `test/app.test.ts` pins this list.
+SSE streams, the OAuth HTML callback, and the workspace-admin routes are deliberately absent from the spec, they are not one-shot MCP tools. The `GET /openapi.json` test in `test/app.test.ts` pins that boundary.

package/dist/app.d.ts

@@ -1,24 +1,16 @@
-import type { AppDependencies } from './composition.js';
+import type { AppDependencies } from './composeApp.js';
 import { OpenAPIHono } from '@hono/zod-openapi';
 export interface AppOptions {
     readonly corsOrigins?: readonly string[];
     /**
-     * Base URL the OpenAPI spec advertises in its `servers[]` block. This
-     * is what downstream consumers (openapi-mcp-gateway, Swagger UI, code
-     * generators, …) use to dispatch REST calls. When unset, the spec is
-     * emitted without `servers[]`, which leaves the consumer to guess.
-     * composeFsApp threads its `apiUrl` through here so the gateway can
-     * route REST calls back to this server without an explicit
-     * `--base-url` flag.
+     * Base URL the OpenAPI spec advertises in its `servers[]` block.
+     * Downstream consumers use it to dispatch REST calls,
+     * openapi-mcp-gateway, Swagger UI, and code generators among them.
+     * When unset, the spec omits `servers[]` and leaves the consumer to guess.
+     * `composeFsApp` threads its `apiUrl` here,
+     * so the gateway routes calls back without an explicit base-url flag.
      */
     readonly apiUrl?: string;
-    /**
-     * When true (or `BRAID_LOCAL_TRUST=true`), the auth middleware lets
-     * every request through and the embedded `userIdMiddleware` falls
-     * back to `local-user`. Set by `composeFs` for the Tauri sidecar;
-     * production remote servers leave it `false`.
-     */
-    readonly localTrust?: boolean;
 }
 export declare function createApp(deps: AppDependencies, options?: AppOptions): OpenAPIHono;
 //# sourceMappingURL=app.d.ts.map

package/dist/app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AA8B/C,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACxC;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAC9B;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,GAAE,UAAe,GAAG,WAAW,CAwKtF"}
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AA8B/C,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACxC;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,GAAE,UAAe,GAAG,WAAW,CAqMtF"}

package/dist/app.js

@@ -2,14 +2,12 @@ import { OpenAPIHono } from '@hono/zod-openapi';
 import { authMiddleware } from './middleware/auth.js';
 import { corsMiddleware } from './middleware/cors.js';
 import { errorHandler } from './middleware/error.js';
-import { userIdMiddleware } from './middleware/userId.js';
 import { workspaceAccessMiddleware } from './middleware/workspaceAccess.js';
 import { workspaceIdMiddleware } from './middleware/workspaceId.js';
 import { createAdminRouter } from './routes/admin.js';
 import { createAuthRouter } from './routes/auth.js';
 import { createBatchRouter } from './routes/batch.js';
-import { createClarifyRouter } from './routes/clarify.js';
-import { createDecisionsRouter } from './routes/decisions.js';
+import { createClarificationRouter } from './routes/clarifications.js';
 import { createEdgesRouter } from './routes/edges.js';
 import { healthRouter } from './routes/health.js';
 import { createHistoryRouter } from './routes/history.js';
@@ -18,38 +16,33 @@ import { createNodesRouter } from './routes/nodes.js';
 import { createOAuthRouter } from './routes/oauth.js';
 import { createOntologyRouter } from './routes/ontology.js';
 import { createProposalsRouter } from './routes/proposals.js';
+import { createReactorCyclesRouter } from './routes/reactorCycles.js';
 import { createRunsRouter } from './routes/runs.js';
 import { createSkillInputOptionsRouter } from './routes/skillInputOptions.js';
 import { createSkillsRouter } from './routes/skills.js';
 import { createSourceLoadersRouter } from './routes/sourceLoaders.js';
-import { createSourceUnitStatesRouter } from './routes/sourceUnitStates.js';
+import { createSourceUnitObservationsRouter } from './routes/sourceUnitObservations.js';
+import { createGithubWebhookReceiver, createSourceWebhooksAdminRouter } from './routes/sourceWebhooks.js';
 import { createUsersRouter } from './routes/users.js';
 import { createWorkspaceEventsRouter } from './routes/workspaceEvents.js';
 import { createTransferOwnershipRouter, createWorkspaceMembersRouter } from './routes/workspaceMembers.js';
 import { createWorkspacesRouter } from './routes/workspaces.js';
 export function createApp(deps, options = {}) {
     const app = new OpenAPIHono();
+    // Global middleware, every request passes these in order.
     app.use('*', options.corsOrigins
         ? corsMiddleware({ allowedOrigins: options.corsOrigins })
         : corsMiddleware());
-    // Phase B auth gate. In local-trust mode it short-circuits and lets
-    // the unauthenticated request through; otherwise a Bearer token is
-    // required (Google OAuth-issued session). Public routes — `/auth/*`,
-    // `/health` — are excluded inside the middleware so the login flow
-    // itself isn't gated.
-    if (deps.sessionStore) {
-        const localTrust = options.localTrust ?? deps.localTrust;
-        app.use('*', authMiddleware({
-            sessionStore: deps.sessionStore,
-            localTrust,
-        }));
-    }
-    // Phase A identity. Stamps `c.set('userId', ...)` from `X-Braid-User`
-    // when the auth layer left it empty — i.e. local-trust mode, or any
-    // public route. Bearer-authenticated requests already have a userId
-    // by the time this runs and pass through untouched.
-    app.use('*', userIdMiddleware);
+    // Identity and auth gate. Resolves the caller's `userId` from a Bearer session
+    // when auth is enforced, else the `X-Braid-User` header or the default principal.
+    // Non-public routes that lack a required Bearer token are rejected.
+    app.use('*', authMiddleware({
+        ...(deps.sessionStore ? { sessionStore: deps.sessionStore } : {}),
+        requireAuth: deps.authMode.requiresAuth,
+        defaultPrincipal: deps.authMode.defaultPrincipal,
+    }));
     app.onError(errorHandler);
+    // Host-level routes, not scoped to a single workspace.
     app.route('/health', healthRouter);
     if (deps.sessionStore && deps.accessPolicy && deps.userRegistry) {
         app.route('/auth', createAuthRouter({
@@ -59,13 +52,12 @@ export function createApp(deps, options = {}) {
             userRegistry: deps.userRegistry,
             ...(deps.googleOAuth ? { googleOAuth: deps.googleOAuth } : {}),
             studioUrl: deps.studioUrl ?? 'http://localhost:5173',
-            localTrust: options.localTrust ?? deps.localTrust,
+            requiresAuth: deps.authMode.requiresAuth,
         }));
     }
     if (deps.userRegistry) {
         app.route('/users', createUsersRouter({
             userRegistry: deps.userRegistry,
-            clock: deps.clock,
         }));
     }
     if (deps.userRegistry && deps.accessPolicy && deps.workspaceRegistry) {
@@ -80,22 +72,37 @@ export function createApp(deps, options = {}) {
         workspaceService: deps.workspaceService,
         sourceLoaderRunner: deps.sourceLoaderRunner,
         workspacesRoot: deps.workspacesRoot,
+        pluginRegistry: deps.pluginRegistry,
         ...(deps.bootstrap ? { bootstrap: deps.bootstrap } : {}),
         ...(deps.workspaceRegistry ? { workspaceRegistry: deps.workspaceRegistry } : {}),
         ...(deps.userRegistry ? { userRegistry: deps.userRegistry } : {}),
+        ...(deps.historyService ? { historyService: deps.historyService } : {}),
     }));
     app.route('/workspaces', createWorkspaceEventsRouter({ eventBus: deps.eventBus }));
-    // Server-level plugin discovery: lets Studio render its loader dropdown
-    // from the active PluginRegistry rather than hardcoded strings. Not
-    // workspace-scoped because the answer is "what does this server have
-    // installed", which is identical across workspaces.
+    // Server-level plugin discovery for Studio's loader dropdown,
+    // sourced from the active PluginRegistry, not hardcoded strings.
+    // Installed loaders are identical across workspaces, not scoped to one.
     app.route('/source-loaders', createSourceLoadersRouter({ pluginRegistry: deps.pluginRegistry }));
+    // Public webhook receivers, authenticated by per-source HMAC secrets,
+    // inside the handler, not by a Bearer token.
+    // The auth middleware exempts the `/webhooks/` prefix.
+    // Mounted only when a SecretStore is wired,
+    // without one there is nowhere to read the secrets.
+    if (deps.secretStore) {
+        app.route('/webhooks', createGithubWebhookReceiver({
+            workspaceService: deps.workspaceService,
+            sourceLoaderRunner: deps.sourceLoaderRunner,
+            secretStore: deps.secretStore,
+            pluginRegistry: deps.pluginRegistry,
+        }));
+    }
+    // Workspace-scoped sub-app, mounted under `/workspaces/:workspaceId` below.
     const workspaceScoped = new OpenAPIHono();
     workspaceScoped.use('*', workspaceIdMiddleware);
-    // Workspace membership gate. Mounted only when both the workspace
-    // registry and user registry are present (i.e. composeFsApp);
-    // in-memory tests that compose without these stay open so existing
-    // routes keep behaving.
+    // Workspace membership gate, present only in composeFsApp,
+    // which wires both the workspace registry and the user registry.
+    // In-memory tests compose without these and stay open,
+    // so existing routes keep behaving.
     if (deps.workspaceRegistry && deps.userRegistry) {
         workspaceScoped.use('*', workspaceAccessMiddleware({
             registry: deps.workspaceRegistry,
@@ -110,17 +117,24 @@ export function createApp(deps, options = {}) {
         hitlService: deps.hitlService,
         proposalRepository: deps.proposalRepository,
         modelRepository: deps.modelRepository,
-        validationService: deps.validationService,
+        modelValidationService: deps.modelValidationService,
         workspaceService: deps.workspaceService,
     }));
-    workspaceScoped.route('/clarify', createClarifyRouter({
+    workspaceScoped.route('/clarifications', createClarificationRouter({
         hitlService: deps.hitlService,
-        clarifyRepository: deps.clarifyRepository,
-        decisionRepository: deps.decisionRepository,
+        clarificationRepository: deps.clarificationRepository,
     }));
-    workspaceScoped.route('/decisions', createDecisionsRouter({ decisionRepository: deps.decisionRepository }));
-    workspaceScoped.route('/source-unit-states', createSourceUnitStatesRouter({
-        sourceUnitStateService: deps.sourceUnitStateService,
+    workspaceScoped.route('/source-unit-states', createSourceUnitObservationsRouter({
+        sourceUnitObservationService: deps.sourceUnitObservationService,
+        ...(deps.intentLister && deps.sourceUnitDigest
+            ? {
+                diffSupport: {
+                    workspaceService: deps.workspaceService,
+                    intentLister: deps.intentLister,
+                    digest: deps.sourceUnitDigest,
+                },
+            }
+            : {}),
     }));
     workspaceScoped.route('/ontology', createOntologyRouter({
         workspaceRepository: deps.workspaceRepository,
@@ -131,6 +145,9 @@ export function createApp(deps, options = {}) {
             skillRegistry: deps.skillRegistry,
             skillRunner: deps.skillRunner,
             workspaceRepository: deps.workspaceRepository,
+            sourceUnitObservationService: deps.sourceUnitObservationService,
+            runRepository: deps.runRepository,
+            pluginRegistry: deps.pluginRegistry,
         }));
         workspaceScoped.route('/runs', createRunsRouter({
             runRepository: deps.runRepository,
@@ -144,9 +161,20 @@ export function createApp(deps, options = {}) {
     if (deps.batchService) {
         workspaceScoped.route('/batch', createBatchRouter({ batchService: deps.batchService }));
     }
+    workspaceScoped.route('/reactor-cycles', createReactorCyclesRouter({
+        reactorCycleRepository: deps.reactorCycleRepository,
+    }));
+    if (deps.secretStore) {
+        workspaceScoped.route('/source-webhooks', createSourceWebhooksAdminRouter({
+            workspaceService: deps.workspaceService,
+            secretStore: deps.secretStore,
+            pluginRegistry: deps.pluginRegistry,
+            ...(options.apiUrl ? { apiUrl: options.apiUrl } : {}),
+        }));
+    }
     workspaceScoped.route('/skill-input-options', createSkillInputOptionsRouter({
         modelRepository: deps.modelRepository,
-        clarifyRepository: deps.clarifyRepository,
+        clarificationRepository: deps.clarificationRepository,
         workspaceRepository: deps.workspaceRepository,
         pluginRegistry: deps.pluginRegistry,
     }));
@@ -169,12 +197,11 @@ export function createApp(deps, options = {}) {
             ...(deps.googleOAuth ? { google: deps.googleOAuth } : {}),
         }));
     }
-    // OpenAPI 3 spec; consumed by openapi-mcp-gateway to surface REST
-    // operations as MCP tools. SSE routes and the OAuth HTML callback
-    // are intentionally absent — they're mounted via app.route() with
-    // plain Hono sub-routers so they don't register with the OpenAPI
-    // registry. The `servers[]` block lets the gateway resolve the
-    // upstream API base URL without an explicit --base-url flag.
+    // OpenAPI 3 spec, consumed by openapi-mcp-gateway, to surface REST operations as MCP tools.
+    // SSE routes and the OAuth HTML callback are intentionally absent,
+    // they mount plain Hono sub-routers, so they never register with the doc.
+    // The `servers[]` block lets the gateway resolve the upstream base URL,
+    // without an explicit --base-url flag.
     app.doc('/openapi.json', {
         openapi: '3.0.0',
         info: {

package/dist/app.js.map

@@ -1 +1 @@
-{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"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"}

package/dist/authMode.d.ts

@@ -0,0 +1,39 @@
+import type { UserId } from '@braidhq/schema';
+import type { AccessPolicy } from './infrastructure/auth/AccessPolicy.js';
+import type { UserRegistryFile } from './infrastructure/users/UserRegistryFile.js';
+export declare const LOCAL_USER_ID: string & import("zod").$brand<"UserId">;
+export interface AuthContext {
+    readonly userRegistry: UserRegistryFile;
+    readonly accessPolicy: AccessPolicy;
+}
+/**
+ * How a deployment resolves identity.
+ * The one axis that separates a trusted local install,
+ * from an authenticated remote server.
+ *
+ * Two separate axes, not one nullable field.
+ * `defaultPrincipal` is the identity axis, the implicit user for an
+ * unauthenticated request, and the owner a workspace falls back to,
+ * or null when there is no implicit user.
+ * `requiresAuth` is the policy axis, whether a caller must present a valid
+ * Bearer token. The middleware reads this, never the principal's null-ness.
+ *
+ * Stateless behaviour behind an interface, so a const object per mode,
+ * the idiomatic strategy form when there is no constructor dependency.
+ */
+export interface AuthMode {
+    readonly defaultPrincipal: UserId | null;
+    readonly requiresAuth: boolean;
+    provision: (context: AuthContext) => Promise<void>;
+}
+/**
+ * A local desktop or sidecar. One implicit user owns everything,
+ * so provision seeds that `local-user` admin account, idempotently.
+ */
+export declare const localTrust: AuthMode;
+/**
+ * A remote server. Real users authenticate against an allowlist,
+ * so provision back-fills `approvedEmails` from the roster, idempotently.
+ */
+export declare const authenticated: AuthMode;
+//# sourceMappingURL=authMode.d.ts.map

package/dist/authMode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authMode.d.ts","sourceRoot":"","sources":["../src/authMode.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAa,MAAM,EAAE,MAAM,iBAAiB,CAAA;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAA;AACzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4CAA4C,CAAA;AAKlF,eAAO,MAAM,aAAa,yCAAmC,CAAA;AAE7D,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,YAAY,EAAE,gBAAgB,CAAA;IACvC,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAA;CACpC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAA;IACxC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;IAE9B,SAAS,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACnD;AAED;;;GAGG;AACH,eAAO,MAAM,UAAU,EAAE,QAaxB,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,QAS3B,CAAA"}