A governed operating system for expert work with AI

Request flow

Operating model

The Studio treats system ownership as a connected set of questions, not a collection of dashboards. Each question resolves to a governed record and an explicit place to act.

Candidate acceptance records only an immutable Studio review head and append-only decision. It does not replace canonical source or initialize later runs from the candidate. Git push or merge and production deployment remain separate explicit controls.

Trust boundaries

1. auth.categori.se authenticates with the existing categorise Cognito pool. The dedicated public SPA client uses authorization code flow with PKCE.
2. API Gateway validates the token issuer and this app client's audience. Lambda then requires the configured single-operator subject plus ProjectOwner or PlatformAdmin; administrative routes additionally require PlatformAdmin.
3. CloudFront is the only reader of the private web bucket. Source and data buckets block public access, use S3-managed encryption, and retain versions.
4. A private Fargate task receives only short-lived role credentials and the exact owner/session S3 boundary. It has no inbound endpoint or retained task volume.
5. The reviewed Bedrock adapter uses task identity; it has no browser credential or persistent provider-login cache. Retired experimental adapters are disconnected and cannot be enabled from the browser.
6. Agent behavior/context is a governed asset; the active provider/model is a separate revisioned next-turn route. No running turn silently falls through to another engine.

One shell, many engines

The editor owns the visible conversation, selected files, approvals, and handoff checkpoint. A reviewed adapter supplies inference: local Ollama/vLLM, subscription-backed Codex, Kiro ACP, or Groq behind the owned agent loop. Switching providers preserves user-visible goals, decisions, source revision, checks, and approved-context identity—not hidden vendor reasoning.

This keeps the vocabulary small: application, agent profile, route, run, evaluation, and promotion. The Developer page exposes the model shelf; Settings controls permission; provider login remains a separate local fact.

Progressive context, not uncontrolled self-modification

An agent reads approved context and produces run traces, evaluation evidence, and candidate memories. Candidates become active context only after review or an evaluation gate. This preserves a causal history: every behavior change can be tied to a source artifact, prompt/config revision, adapter, and evaluation result.

source data → immutable run trace → candidate memory → evaluation → approved context
                                ↘ rejected candidate (retained for diagnosis)

The S3 layout keeps those phases separate:

s3://ai.studio/projects/<slug>/source/
s3://ai.studio.data/projects/<slug>/datasets/
s3://ai.studio.data/agents/<slug>/context/candidates/
s3://ai.studio.data/agents/<slug>/context/approved/
s3://ai.studio.data/agents/<slug>/evaluations/
s3://ai.studio.data/agents/<slug>/models/adapters/
s3://ai.studio.data/projects/<application>/context/approved/
s3://ai.studio.data/projects/<application>/runs/<run-id>/

For source changes, the run's candidate tree and manifest live under the application's immutable revision prefix. An explicit approval records that review URI in head_source_uri and advances source_revision; it does not mutate canonical source, affect the next run's worktree, or deploy an application.

s3://ai.studio/projects/<slug>/source/                         immutable execution snapshot mirror
s3://ai.studio/projects/<slug>/revisions/<run-id>/source/      immutable candidate tree
s3://ai.studio/projects/<slug>/revisions/<run-id>/manifest.json candidate identity

Deployment layers

The default deployment creates only the control plane:

AWS_PROFILE=categorise scripts/deploy.sh

Execution input is staged only from a clean, reviewed Git main revision that exactly matches the private remote. The Projects panel renders the manifest-registered snapshot command; for Docs Repo it is:

AWS_PROFILE=categorise python3 scripts/stage-git-snapshot.py --project docs-repo --apply

The helper verifies repository identity, a clean local tree, exact local/remote main, safe paths and Git modes, and every file digest before registering the commit-addressed mirror. Check snapshot verifies that immutable execution input through the authenticated API. Browser saves open a private GitHub App draft pull request; the interface offers no local/S3 source pull, baseline, or push command. Until a reviewed snapshot is registered, application and deployment administration stay visible but file browsing and agent runs remain closed.

The reviewed private-session source uses one owner-scoped Fargate Spot task for multiple browser turns. Explicit close and page exit request shutdown; 15 minutes without completed work and a one-hour hard session deadline are independent bounds. The task has no retained volume, NAT gateway, load balancer, or always-on endpoint. The former retained EC2 workstation path has been removed from the application and deployment definitions. Deployment commands and live-proof gates are documented in the source repository's README.md.