Seraph Project Constitution

Document class: canonical product and architecture contract

Capability sequence: Guardian capability roadmap

Completed foundation: Epic #736

Shipped-state owner: Development Status

Seraph is a local-first proactive guardian: an operator-controlled system that understands the operator's goals, observes permitted context, proposes and executes useful work, remembers outcomes, and explains what it is doing. Seraph is not itself an AGI project. It adapts its behavior and capabilities to the operator's goals, which may include ambitious research goals.

This constitution defines the target architecture. It does not claim that every target capability is shipped. The current implementation is recorded in Development Status, while active work lives only in GitHub issues, pull requests, and the Seraph Execution project. This constitution is Seraph's sole product and accepted-target authority.

Product Promise

Seraph should help an operator make sustained progress without becoming an opaque autonomous process. It must:

maintain explicit goals, constraints, and success measures;
observe only paired, consented sources and show what was captured;
turn evidence into bounded proposals, queued work, reports, and actions;
request approval at declared trust boundaries;
preserve durable memory, artifacts, checkpoints, and audit receipts;
remain useful when a model or optional integration is unavailable; and
report the effective runtime path, not a configured or aspirational one.

Turn goals into prioritized plans, scheduled work, and evidence-backed progress reviews.
Monitor consented desktop context and produce searchable summaries that help the operator reflect and recover focus.
Continuously research operator-selected topics and connect material findings to active goals and decisions.
Execute bounded software-engineering and knowledge workflows with approvals, artifacts, checkpoints, and audit receipts.
Continue one trusted conversation across the cockpit, paired voice, and paired messaging surfaces.

A surface is not supported until its implementation ticket has shipped and the status page says so.

Public entry points: docs, contributing, support, security, and GitHub Discussions.

Four-Layer Architecture

Layer	Responsibility	Must not own
Guardian kernel	Goals, policy, planning, prioritization, intervention, memory coordination, audit, and operator-visible state	Provider-specific behavior or unbounded side effects
Capability runtime	Typed capabilities, durable jobs, checkpoints, artifacts, approvals, sandbox/policy enforcement, and bounded remote-inference admission	Product goals or hidden provider fallback
Model fabric	OpenRouter ordinary inference with explicit routing, consent, budgets and receipts; one dedicated optional NEAR HTTPS text capability under ADR-025	Agent identity, durable state, shell orchestration, or product policy
Interfaces and edges	Browser cockpit, API, consented local or paired desktop context, voice, and paired messaging adapters	Canonical memory, authority, or an independent agent runtime

The guardian kernel decides why and what. The capability runtime controls how work may execute. The model fabric supplies bounded inference. Interfaces and edges provide where the operator interacts and what consented context is available.

Locked Decisions

The following architecture decisions are normative:

ADR-023 defines evidence-bound Guardian opportunities and ADR-024 defines purpose-specific OpenRouter routes. ADR-025 permits one separate optional NEAR HTTPS text capability with explicit provider plaintext access. These accepted decisions retain the existing authority, serial admission and accounting boundaries. Development Status owns the implemented capability scope and its limits; acceptance alone does not establish live provider quality or availability.

Changing a locked decision requires a superseding ADR, a tracked issue, an independent Critic/Contrarian review, and updates to every affected active doc.

Capability Vocabulary

Use these terms consistently in APIs, UI copy, issues, and active docs:

capability: a Seraph-owned, typed unit of work with declared input, output, permissions, limits, and receipts;
job: a durable invocation of a capability;
artifact: addressable output produced or consumed by a job;
checkpoint: durable resumable job state that excludes unsafe secret data;
model route: an inference endpoint plus model and effective routing state;
edge: a paired, revocable source or interface outside the canonical core;
provider: an inference or advisory integration, never Seraph's authority;
guardian cycle: observe, assess, propose, approve when required, act, evaluate, and remember.

Capability Status Vocabulary

Capability inventory, APIs, and operator UI use this lifecycle vocabulary:

Shipped: present on develop, available to its declared audience, and supported by the named validation receipt.
Partial: usable behavior exists on develop, with named missing boundaries.
Experimental: runnable only as an opt-in canary; interfaces or persistence may change and the UI must say so.
Planned: accepted tracked work without a shipped implementation.
Deprecated: still present for migration, with its replacement and removal issue named.
Excluded: intentionally outside Seraph's product boundary; it must not be advertised or silently restored as fallback.

“Configured,” a deterministic fixture, or a branch-local change is not evidence of Shipped. A capability cannot be both Shipped and Planned. Experimental and Deprecated capabilities must remain visibly distinct from supported paths.

Document And Decision States

Material documents and decisions may use these states:

Target: accepted architecture or product intent, not yet shipped.
Research: evidence or option under evaluation, not a committed product contract.
Archived: historical context that may contradict the current contract.
Blocked: accepted work cannot proceed until a named condition changes.

Open branches describe intended post-merge truth and must be identified as such.

Runtime Invariants

Model providers are inference-only. Seraph does not depend on Codex CLI, Claude Code, or another coding-agent runtime to operate.
Ordinary model inference uses the governed OpenRouter HTTPS route; ADR-025 permits only the separate fixed optional NEAR HTTPS text capability. Exact model/modalities and upstream policy must be verified before dispatch; unsupported capabilities remain blocked or degraded rather than falling back silently.
Remote inference uses one shared bounded admission contract with owner, priority, deadline, cancellation, budget, idempotency, and reconciliation receipts. The initial in-flight limit is one; this is an API admission bound, not a claim about upstream hardware concurrency. The integrated runtime has durable jobs, provider cost reservations and witnessed reconciliation; contacted unknown costs remain liabilities. See the dated source/test baseline for the develop/main boundary and unresolved focused-test failures. The old process-local migration description is historical, not the current target.
Canonical goals, memory, jobs, artifacts, approvals, and audit records remain in Seraph-owned storage. Advisory memory providers may augment recall but do not become authoritative.
macOS and Linux are peer core-host targets under ADR-008. The operator chooses the canonical workspace host; jupyter is a historical deployment example. Consented context may originate locally or from a paired, revocable edge, without transferring authority. GPU hardware, local model weights, and a VLM wrapper are not active product prerequisites during the OpenRouter-only phase.
Effective model, queue, edge, and degraded state must be operator-visible. Silent fallback that makes the UI lie is a contract violation.

Safety And Authority

Observation, inference, and execution are different permissions. Pairing an edge does not grant execution authority. Supplying a provider key does not grant data-egress approval. A capability must declare filesystem, process, network, credential, and external-mutation boundaries, and Seraph must fail closed when required policy or approval is absent.

Definition Of Product Progress

Product progress is a user-visible capability with bounded failure behavior and evidence appropriate to its risk. Documentation, issue creation, proof-only fixtures, and model output are not substitutes for the capability itself. Completion requires the owning issue and project state, focused tests, live or mocked operator receipts as appropriate, and independent review to agree.

Documentation Ownership

docs/implementation/: shipped truth, this constitution, ADRs, and durable operator contracts.
docs/research/: evidence, alternatives, and dated comparisons; research cannot accept a target or claim shipping.
docs/docs/ (/legacy): archive; content may contradict the current system.
GitHub Project, issues, and PRs: execution state; docs never mirror the queue.

Start with Current App Guide to run the existing app, Development Status for shipped truth, and Documentation Contract before changing documentation.

Product Promise​

Four-Layer Architecture​

Locked Decisions​

Capability Vocabulary​

Capability Status Vocabulary​

Document And Decision States​

Runtime Invariants​

Safety And Authority​

Definition Of Product Progress​

Documentation Ownership​