Sorrel Hub
The collaboration layer: a zero-dependency Node API server that stores project metadata, transports content-addressed objects between machines, and administers Core policy — plus a shared SolidJS product UI and thin browser host.
Four packages, four roles
| Repo | Role |
|---|---|
sorrel-hub | The API server: JSON over HTTP, no UI. |
sorrel-hub-ui | The shared SolidJS product UI for browser and future native shells. |
sorrel-hub-web | The thin Vite browser host and development API proxy. |
sorrel-web | This site — public landing and docs, unrelated to the product UI. |
Sync transport
The Hub moves the engine's content-addressed objects with a small negotiated
protocol (specified in sorrel-protocol/docs/sync-transport.md):
| Endpoint | Purpose |
|---|---|
GET /{repoId}/refs | List ref names and snapshot ids. |
POST /{repoId}/objects/missing | Negotiate: given want/have, which objects are missing. |
POST /{repoId}/objects | Upload objects (id-verified; policy-gated by repo.object.write). |
GET /{repoId}/objects/{id} | Download raw object bytes. |
POST /{repoId}/refs/{name} | Advance a ref — closure-complete and fast-forward checked, policy-gated by repo.ref.write. |
GET /admin/sync-repos | List repositories known to the sync store with ref counts. |
Every object upload is digest-verified against its BLAKE3 id, and a ref can only advance when the full snapshot closure is present — a half-pushed history is never visible as the current state.
Persistence
Sync objects/refs and product metadata (projects, proposals, workflow runs, ...)
persist to disk with the same discipline as the engine: content-addressed fanout
layout, atomic temp-file-and-rename writes, digest-verified reads. A Hub restart
loses nothing. SORREL_HUB_DATA_DIR selects the location;
SORREL_HUB_SYNC_STORE=memory keeps everything ephemeral (the test
default).
Policy: Hub administers, Core decides
Mutating sync calls carry an acting principal and grantRefs; the Hub
hydrates those against grants it trusts and re-evaluates the Core policy decision
before writing. The Hub never invents its own permission language — signature
trust, rotation rules, and audit semantics remain Core's job.
Installation and authentication seams
GET /capabilities describes optional server features and
GET /session returns the current AuthAdapter identity. Development,
WorkOS, and OIDC/JWKS adapters exist, and unsafe development auth or bootstrap
grants cannot bind beyond loopback without an explicit override. WorkOS sealed
sessions, login UI, and production identity provisioning are not complete.
The filesystem remains authoritative for VCS objects. An optional Convex schema and mirror can provide metadata such as open-proposal counts; the UI falls back to the Hub API when that capability is unavailable.
The web interface
sorrel-hub-ui provides project-first navigation with Reviews, Sync,
and Actions nested under each project. It can create projects, proposals, and
review comments; transition proposal and workflow status; and resolve comments.
sorrel-hub-web builds that shared UI and proxies /api/*
during development. Sync remains read-only in the browser. This alpha has no
complete production login flow; do not expose it to an untrusted network.