spec

UAS Database First-Class Domain Plan

2026-04-27

The UAS Database should stay inside Mission Control, but it needs to stop behaving like a phase-1 project folder. The right end state is a first-class Mission Control domain with a permanent data/uas-database/ root, a modular service layer, explicit schema and dataset versioning, a staging-to-canonical promotion flow, lightweight history, and tests around the data contract. This keeps the current local-first, JSON-backed model that already works, while removing the temporary naming, hidden coupling, and maintenance risk that will get worse as the dataset and workflows grow.

1. Problem Statement and Goal

The current UAS Database works, but it is still wearing prototype clothes.

Today, the Mission Control UI is branded as UAS Database, while the data still physically lives under data/lantronix-uas-workbench-phase1/. The read/write logic sits in a single dense store file, the dataset has no formal manifest or migration contract, enrichment and canonical truth are too close together, and there is no explicit test layer protecting core read/write behavior. That is fine for a fast phase-1 build, but it is weak as a permanent operating surface.

The goal is to make the UAS Database a durable Mission Control domain without turning it into a separate product or a heavyweight database project.

2. Success Metric

This work is successful when all of the following are true:

  1. Mission Control reads and writes the canonical dataset from data/uas-database/.
  2. The dataset has a manifest with explicit schema version and migration version.
  3. Read/write, validation, relation resolution, and query logic are split into domain modules instead of living in one store file.
  4. New agent or script-driven updates can land in a staging area before promotion into canonical records.
  5. Canonical changes produce durable history through repeatable workspace commits.
  6. A test suite covers load, validation, linked-record resolution, save conflicts, and migration smoke tests.

Pete should be able to verify this by opening Mission Control, editing a company, reviewing staged changes, and seeing the dataset survive rebuilds and future schema changes without brittle manual cleanup.

3. Current State

The current product and implementation baseline is defined by the approved Mission Control UAS Database spec and the shipped phase 1 implementation handoff.

What exists today:

What is missing:

4. Platform Capabilities

OpenClaw and Mission Control already support most of the operating model we need.

Native or already-proven capabilities:

What still requires custom implementation:

This is a good fit for OpenClaw because the platform is already local-first, artifact-heavy, and comfortable with file-backed truth.

5. Community Patterns

The strongest proven pattern for internal tools like this is not “jump to a hosted database now.” It is “formalize the file-backed system until it behaves like a real domain module.”

The patterns worth copying are:

That points toward “formalized local-first domain module,” not “premature platform rewrite.”

6. Options

OptionDescriptionComplexityToken CostReliabilityMaintenance BurdenTradeoffs
AKeep JSON files, promote UAS Database to a first-class Mission Control domain with manifest, migrations, staging, history, and testsMediumLowHighMediumBest fit for current scale and existing workflows
BMove canonical storage to SQLite while keeping Mission Control UI and local-first behaviorMedium-HighMediumHighMedium-HighCleaner querying, but migration overhead and more moving parts now
CMove to a hosted DB or separate serviceHighHighMediumHighStronger centralization later, but overbuilt for one primary operator and current volume

Option A: Formalized local-first domain

Pros:

Cons:

Option B: Embedded DB now

Pros:

Cons:

Option C: Hosted service

Pros:

Cons:

7. Recommendation

Choose Option A.

Make the UAS Database a first-class Mission Control domain while keeping file-backed JSON as canonical truth. That gives us the permanence we need without paying the cost of a database rewrite before the workflow earns it.

Implement the six recommendations in this order:

  1. migrate the physical data root to data/uas-database/
  2. split the service layer into domain modules
  3. add manifest and migration metadata
  4. add staging and promotion flow
  5. add lightweight commit-backed history
  6. add tests around the domain contract

This order matters. Root migration and service modularization reduce hidden coupling first. Manifest and migration metadata make future changes safer. Staging and history improve operating discipline. Tests stop future cleanup work from becoming a recurring tax.

8. Security Considerations

Main risks:

Mitigations:

9. Implementation Scope

Phase A, foundation

Create or refactor:

Phase B, operations

Create:

Phase C, durability

Create:

Expected code touch points

At minimum:

10. Validation Criteria

Pete should be able to verify the finished implementation with these checks:

  1. data/uas-database/manifest.json exists and reflects the live schema version.
  2. Mission Control loads /uas-database from the new canonical root.
  3. Opening and saving a company still works after the root migration.
  4. Breaking a linked segment or evidence ID produces a clear validation failure.
  5. A staged proposal can be created without touching the canonical record.
  6. Promoting a staged proposal updates the canonical record and leaves a durable history trace.
  7. Automated tests pass for the UAS Database module.
  8. Rebuild and restart of Mission Control does not require any legacy-root fallback for normal operation.

11. Category

Tool

12. Context Loading

For any future work on this feature, load these files in this order:

  1. Always load the active product spec: /Users/vinny/.openclaw/workspace/artifacts/spec_mission_control_uas_database.md
  2. Always load this foundation spec: /Users/vinny/.openclaw/workspace/artifacts/spec_uas_database_first_class_domain.md
  3. Load the last implementation handoff when touching existing routes or UI behavior: /Users/vinny/.openclaw/workspace/artifacts/uas_database_phase1_mission_control_handoff_2026-04-24.md
  4. Load the active company schema when changing the data contract:
  1. Load mission-control/lib/uas-database-types.ts and the active UAS service modules whenever changing read/write behavior.
  2. Load mission-control/data/tasks.json only when updating task state or linking artifacts.

13. Guardrails

14. Handoff

The final result should be delivered in three layers:

  1. a spec artifact in artifacts/ for review
  2. a Mission Control implementation task linked to that spec
  3. an implementation handoff artifact after each completed build tranche, with live validation results and any remaining gaps

Phased Build Plan

Tranche 1, start now

Tranche 2

Tranche 3