# STEWARD Mission Control — Reference Architecture and Data Model

This is the preferred implementation path after Hermes inspects the bundled source and local environment. Hermes may propose a different architecture only in the read-only Activation Card, with migration cost, security implications, clean-install impact and a clear reason.

## Preserve the baseline design

The bundled baseline is a working static HTML/CSS/JavaScript application with a loopback read-only server. Preserve its visual system, accessibility patterns, role-aware navigation, five-stage mission loop, strict import validation, EDENA presentation and manual handoff behavior unless a change is required for the target functionality or security model.

Work from a new copy. Never modify `source/baseline-application/` or `source/steward-domain-pack/`.

## Recommended local architecture

Use a local full-stack web application bound to `127.0.0.1`:

```text
Browser UI
  │ authenticated same-origin requests + streamed events
  ▼
Local application server
  ├── authentication, sessions, CSRF, origin/rate/size controls
  ├── domain services and uniform governance policy engine
  ├── SQLite repositories + forward-only migrations
  ├── AIBackend interface
  │    ├── Hermes adapter
  │    └── OpenAI-compatible adapter
  ├── retrieval/citation validator
  ├── consent-controlled structured memory
  └── redacted diagnostics/audit receipts
       │
       ├── private local data directory
       └── configured loopback Hermes gateway
```

Prefer the existing Node/vanilla front-end path to avoid an unnecessary UI rewrite. Use a supported LTS Node runtime. If that runtime provides a production-suitable built-in SQLite interface, use it; otherwise select one locked, actively maintained SQLite dependency and document its cross-platform installation behavior. Do not add a framework merely for fashion.

## Source layout target

```text
app/
├── client/
│   ├── index.html
│   ├── assets/
│   └── modules/
├── server/
│   ├── main.*
│   ├── auth/
│   ├── api/
│   ├── ai/
│   │   ├── AIBackend.*
│   │   ├── hermes-adapter.*
│   │   └── openai-compatible-adapter.*
│   ├── governance/
│   ├── retrieval/
│   ├── memory/
│   ├── audit/
│   └── db/
│       ├── connection.*
│       ├── migrations/
│       └── repositories/
├── config/
├── tests/
├── scripts/
├── .env.example
├── package.json
└── lockfile
```

Exact file names may follow the inspected source convention. Separation of browser code, server secrets, policy, adapters, migrations and tests is required.

## Persistent model

Use opaque UUIDs, UTC timestamps, explicit versions and foreign keys. Every mutable user record carries `created_at`, `updated_at`, `revision`, `owner_user_id`, `workspace_id` and deletion/archival state where applicable.

Minimum tables or equivalent repositories:

1. `app_meta` — app/schema version, migration state, instance ID and installation timestamps.
2. `local_users` — local identity and password-verifier metadata; never plaintext credentials.
3. `sessions` — hashed session identifier, user, issue/expiry/revocation and safe client metadata.
4. `mission_profiles` — versioned approved derived profile; no raw Soul or raw quiz/interview answers.
5. `profile_field_provenance` — source type/ref, derived field, approval state, approved/updated time and uncertainty.
6. `role_workspaces` — setting/role/active-hat context, state, isolation and display preferences.
7. `authority_profiles` — exact title/entity/site/hat/scope/source/expiry and named human routes; unknown values remain explicit.
8. `missions` — workspace, title, outcome, status, EDENA, CHART state, retention, starter/adopted state and iteration lineage.
9. `mission_cycles` and `mission_stages` — iteration and five stage records with completion/review/invalidation metadata.
10. `goals`, `milestones`, `tasks`, `measures`, `reviews`, `notes`, `decisions`, `assumptions`, `risks`, `safeguards` and `references` — mission-owned entities with ordering and history.
11. `attachments` — metadata only until a separately validated local attachment store exists; enforce size/type and never accept prohibited data.
12. `evidence_sources`, `claims` and `claim_source_links` — provenance, URL/identifier, retrieval time, supported claim, appraisal and validation state.
13. `agent_definitions` — frozen versioned 10-agent catalog; not permission.
14. `agent_sessions`, `agent_routes`, `tool_events` and `approval_requests` — real session/routing/tool/approval metadata without secret or prohibited bodies.
15. `memory_items` — value, source, purpose, consent, retention, expiry and forget/delete state.
16. `capabilities`, `badge_criteria`, `activity_evidence`, `awards` and `award_corrections` — evidence-based development history.
17. `connection_capabilities` — backend, checked time, authenticated result, models/features and redacted error.
18. `governance_receipts` and `audit_events` — state changes, approvals, blocks, rollback and deletion without sensitive message bodies.
19. `starter_seed_versions` and `starter_records` — idempotent seed/adopt/clear/restore state.

The 18 administrator-owned domain schemas in the STEWARD corpus remain closed, versioned records. Compile them to JSON Schema Draft 2020-12 and validate create/import/update/export/migration paths. Do not flatten their partition, ACL, authority, source, expiry, correction or deletion fields into generic text.

## Migration and transaction rules

- Initialize with ordered, forward-only migrations inside transactions.
- Record migration checksum and execution result.
- Refuse startup on a modified applied migration.
- Back up the database before a destructive or compatibility-changing migration.
- Roll back the transaction on failure and leave the prior application/data usable.
- Seed by stable key and version; repeated seed commands are idempotent.
- Never overwrite adopted starter or real user records.
- Use foreign keys and explicit deletion semantics; do not rely on UI-only cleanup.
- Export from a consistent read transaction.

## Authentication and browser/server boundary

- Bind to loopback by default and refuse non-loopback binding unless a separately documented remote-security mode is configured.
- First run creates a user-chosen local credential; ship no universal password.
- Store a memory-hard password verifier or use a vetted authentication library.
- Use opaque, rotating `HttpOnly`, `SameSite=Strict` session cookies; add `Secure` when HTTPS applies.
- Enforce CSRF tokens on state-changing requests, strict Origin/Host validation, request-size limits and rate limits.
- Keep provider keys and application secrets in server process environment only.
- Return redacted structured errors. Never place secrets, raw Soul or prohibited content in logs.
- Add a restrictive CSP, no remote scripts/fonts/analytics, frame denial, MIME protection and referrer suppression.

## AIBackend contract

One provider-neutral interface supports:

- authenticated health and capability discovery;
- model discovery;
- session create/resume;
- incremental response events;
- tool start/progress/result/failure events;
- cancellation;
- conversation history references;
- structured errors and retryability; and
- usage metadata when available.

The server exposes only the minimum normalized interface to the browser. It must never relay a provider key. The Hermes adapter uses capabilities actually discovered from the active installation; it must not hardcode an endpoint merely because the master prompt lists an expected value. The OpenAI-compatible adapter is optional and requires explicit user configuration and consent.

Use a stream protocol with explicit event types such as `message_delta`, `tool_start`, `tool_progress`, `tool_result`, `approval_required`, `citation`, `warning`, `usage`, `done` and `error`. Store only approved history. `Stop` must propagate cancellation to the provider where supported and mark the local run truthfully when provider cancellation cannot be confirmed.

## Evidence and prompt-injection boundary

- Normalize only successfully retrieved source metadata.
- Permit `https` citations by default; loopback/local file identifiers require explicit safe handling.
- Validate URL syntax, retrieval result, redirect destination, title, publisher/author, date/status, retrieval time and supported claim.
- Store page content separately from control instructions and treat it as untrusted data.
- Never let a retrieved page, upload or tool result alter system governance, permissions, destinations or user authorization.
- Mark unsupported or unverified claims visibly; never synthesize a citation.

## Backup, restore and deletion

Provide an explicit encrypted-backup option where practical and a clearly labeled readable export for user inspection. A backup includes schema/app version and checksums. Restore validates size, schema, checksums, foreign keys, partitions, unsafe fields and migration compatibility in a temporary location before atomic replacement.

Application removal and data deletion are distinct. Document exact application, data, backup, configuration and log locations per OS. Complete deletion revokes sessions, closes the database, removes the user-selected local data and reports anything outside application control.

## Packaging

Ship:

- locked dependencies and reproducible build/start/test commands;
- migrations and safe seed command;
- `.env.example` with names only;
- loopback launchers for macOS, Windows and Linux;
- health/diagnostic command with redaction;
- user and technical guides;
- backup/update/rollback/uninstall instructions;
- source, tests, SBOM, release manifest and SHA-256 checksums.

Do not claim an OS is supported until a clean-machine installation or an explicitly documented equivalent test passes for that OS.

