Native execution. Governed context. Verifiable work.

Architecture overview

Samōsya has its own runtime. OpenCode is used to develop Samōsya; it is not a dependency of the product at run time.

The interface, as it runs

A real capture of the Workbench, not a rendering. It shows what the runtime actually writes into the shell: thread context revisions, a completed run with usage, and the inspector that reports context and budget.

What the capture demonstrates

• Threads carry context revisions. Each conversation shows the revision it was pinned to (ctx r1), which is what the context builder is supposed to receive.
• A run has totals, not a spinner. Input, output, reasoning, cache hit and cache miss are recorded for the round, with the run marked completed.
• Unknown is not zero. Cost, allowance and list price read Unknown when no reliable price is attached, instead of inventing a number.
• The inspector is project state. Selected model, context capacity, headroom, provenance and the budget guard live in the right panel, next to the work.

Status and evidence

Every state on this site is one of seven values. The label is a claim about evidence, not enthusiasm. The product site uses the shorter buyer-facing set: Available maps to verified or implemented, Preview is unchanged, In development maps to planned work that is next.

What a verified claim must carry

For any feature described as verified, the release record must name the release, the commit, the image digest, the kind of test, the date, whether it was a real or mocked run, the scenario and the known limits. For "available" wording, it must also name the distribution address or the actual start procedure.

# evidence record shape used at release time
release:      0.7.0
commit:       <sha>
image_digest: <sha256:...>
test:         live provider run · approval · resume
date:         2026-10-XX
real:         true
limits:       single provider, single project

This portal does not reproduce screenshots as proof. A screenshot shows an interface, not a runtime behaviour; the evidence record is the source.

Current matrix

Run lifecycle

A run is the unit of governed execution. It is created from a mission contract, executed server-side and persisted at every transition.

request
  → effective configuration        (project · agent · model · effort)
  → context builder                 (L0–L4, pinned sources)
  → provider call
  → tool proposal
  → permission guard                (allowed · denied · approval required)
  → executor
  → result persisted
  → next call … or a terminal state

States

Waiting is a state, not a loop

Questions and approvals persist as waiting states. The engine does not poll a model to keep the run alive: an answer, a denial, an expiry, a cancel and a resume are separate recorded events. That is what makes a ten-minute decision cost nothing in tokens.

Recovery rules

• Checkpoints and persistence bound how much work a reconnect can repeat.
• Answer and approval handling is idempotent; a repeated submission does not double-apply.
• Continuation is claimed with a lease, so two workers do not resume the same run.
• When the outcome of a non-idempotent tool is unknown, recovery fails closed and asks. No exactly-once guarantee is claimed for arbitrary side effects.

Object model

One chain carries the work, and the surrounding objects are references to it rather than copies.

Organization → Project → Thread → Session/Conversation → Run → Step
                                                            ├─ Model Call
                                                            └─ Tool Call

related: Guild · Agent · Mission · Task · Release · Decision
         Knowledge Item · Skill · Integration · Credential · Grant
         Artifact · Review · Budget · Approval · Checkpoint · Trace Event

Identifiers are stable across the interface and the runtime. A "task" in the Project tab and a "task" referenced by a run are the same object; separate copies for display would make the ledger lie.

Model gateway

The gateway selects a concrete provider offering, not a marketing model name. Two selectors are coupled: the model and the thinking effort that the offering actually supports.

providerId         deepseek
providerModelId    deepseek-chat
offeringId         pay_per_use · direct
billingMode        pay_per_use | subscription
protocol           chat-completions | responses | other
capabilities       tools · streaming · vision · json
reasoning          off | low | medium | high | extra_high | fixed | unsupported
contextCapacity    128k
pricingSource      provider price list, dated
availability       live | degraded | unavailable
credentials        reference only, never the secret

Illustrative field shape. Values vary per offering and are read from the provider catalogue at run time.

Effort is mapped, not forwarded

"Off" is not the same as "no parameter" when the API distinguishes them. A universal reasoning field is not sent to every provider; the gateway maps the requested effort onto each protocol and records the effective value in the trace.

Billing modes are separate

A subscription allowance, a pay-per-use charge, a list-price equivalent and a local estimate are four different numbers. They are reported separately, and a missing price is shown as unknown. External inference through OpenCode Go is one offering among others; it is not the runtime and there is no automatic paid fallback.

Tools, skills and permissions

A tool is an atomic, versioned operation with a schema, a risk class, a timeout and a budget. A skill is a versioned procedure that uses tools. An agent is an executor with a mandate, a model, tools, skills and a budget.

Available today

Designed, not shipped

Write and patch operations, terminal and SSH sessions, browser automation, media analysis, document extraction, task and release operations, knowledge and Canon proposals, skill discovery and integration calls. The catalogue is a target, not an inventory. Nothing in it is callable today unless it appears in the list above or in the current release record.

Permission guard

tool_call
  → identity        (user · agent · project)
  → grant lookup    (scope · resource · risk)
  → decision        allowed | denied | approval_required
  → execution       only after the decision is persisted

Least privilege applies at user, project, guild, agent, tool and resource level. A model cannot widen its own grant, extend its budget or approve its own operation. Denied and expired are not consent.

Context and provenance

Context is assembled in layers, with explicit provenance and a bounded window.

Provenance labels

A generated summary is not a canonical fact. A model hypothesis does not become policy. Canon changes are proposed and accepted explicitly, with the revision and the approver recorded. Contradictions are surfaced rather than blended into a confident paragraph.

Execution trace

Three views of the same events, with different purposes.

model_call   provider · model · offering · effective effort
             tokens in/out · cache hit/miss · TTFT · latency
tool_call    name · version · risk · decision · duration
span         wall time · active time · waiting time
state        queued · running · waiting_* · completed
links        approval · checkpoint · artifact · error

Timestamps are UTC. Exports redact credentials; the trace is a record of what the process did, not evidence that the rule behind it was correct.

Approvals and security

Approval is an object with scope and an immutable fingerprint: it authorises a specific operation or artifact version, not "whatever the agent does next".

• Approvals record who, when and for which fingerprint; a changed operation invalidates the old approval.
• Tenant boundaries are enforced before execution, not by prompt instruction.
• Secrets are referenced, never rendered to the model or written into the trace.
• Agent environments are isolated; there is no default host socket and no unrestricted shell on a production host.
• The owner's own shell is not an agent grant. The two are different subjects.

Files, Git and Consoles

Surfaces are not the same domain. Files manages resources independently of Git; Code understands the repository; Consoles is the operator's terminal. The agent's execution trace is not the owner's console, and neither is a substitute for the other.

Integrations and MCP

Integrations give an agent an authorised capability in another system. A project sees only the connections and grants assigned to it; it does not inherit every secret in the organisation.

Designed scope for stage 013: Git and Forgejo, Google Workspace through OAuth, generic HTTP, MCP client and server, mail and calendars, external task systems, infrastructure, registered tools, connection tests, grant scopes and usage history.

Deployment and backup

The reference deployment is one container, one durable volume and a web interface. It is running that way on the project's own storage host; public distribution is later work.

Shape

Single OCI/Docker container, Linux

Data

/data mounted from the host, persistent

Database

SQLite with additive migrations

Upgrade

New image, migration, verification; rollback restores the matching data snapshot

Backup

Filesystem snapshot of /data, not only the database

Distribution

Planned: OCI image, Unraid template, installer and diagnostics (016)

What a release record contains

Commit, branch, image digest, schema version, migration evidence, test results, backup reference and rollback boundary. A deployment from an uncommitted tree without independent review does not meet the intended discipline.

Roadmap

Stages end at an owner acceptance gate. There are no public dates.

1. 001–007Foundation, runtime, human boundary

   Bootstrap, Workbench reset, run engine, gateway, trace, approvals, persistence, live acceptance.

2. 008Files, editing, Git

   Guarded write operations and repository flows.

3. 009Console and shell

   PTY, remote sessions, long-running processes.

4. 010Research and browser

   Fetching, automation and citations.

5. 011Project, knowledge, skills, Designer

   The planning and knowledge surfaces, with the full composer.

6. 012Guild runtime

   Delegation, parallel work, review at scale.

7. 013–016Vault, multimodal, distribution

   Grants and MCP, voice and vision, global administration and installation.

Design system

Two palettes, one geometry. Farm is the material language, not the interface theme: no farm decoration, no blue, cyan or violet in authored UI.

Daylight — Linen & Sage

Soil — Loam & Olive

Type and spacing

Neutral sans for the interface, readable monospace for code, JSON and identifiers. Reference sizes: prose 14.5–15 px, composer 14 px, code and forensic 12.5–13 px, metadata 11.5–12 px, sidebar 12.5–13 px. Contrast targets: 4.5:1 for body text and 3:1 for large text, measured on the rendered surface rather than assumed from tokens.

Logo rules

Dodecahedron: olive outer planes and one ochre face, transparent alpha. Minimum clearance of 0.20 of the symbol width. No stretch, rotation, glow, shadow, texture or added scenery. The production vector master and micro icon remain open items; the current symbol is the approved direction, not a final technical master.