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:

• Mission Control routes:
• /uas-database
• /uas-database/companies/[id]
• Mission Control API routes:
• GET /api/uas-database/companies
• GET /api/uas-database/companies/[id]
• PUT /api/uas-database/companies/[id]
• File-backed dataset with four record types:
• companies
• products
• customer segments
• evidence
• Compatibility root logic that prefers data/uas-database/ and falls back to data/lantronix-uas-workbench-phase1/
• JSON schema-backed company model, with linked evidence traceability preserved through evidence.source_ids
• Company-first review UI inside Mission Control

What is missing:

• physical migration to data/uas-database/
• dataset manifest and migration versioning
• explicit staging area for proposed updates
• modular domain package under mission-control/lib/uas-database/
• automated tests for the UAS Database contract
• stable change-history behavior beyond ad hoc file edits

4. Platform Capabilities

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

Native or already-proven capabilities:

• local workspace file reads and writes
• artifact-based specs and handoffs
• Mission Control routes and API handlers built on Next.js Route Handlers
• JSON schema style data contracts using structured record files
• browser-driven validation of live UI changes
• task-driven workflow in Mission Control
• workspace git commits through existing scripts and shell access

What still requires custom implementation:

• dataset manifest and migration contract
• staged proposal format and promotion workflow
• dedicated UAS domain module split
• test coverage for data loading, validation, and save behavior
• lightweight history conventions for accepted canonical changes

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:

• a canonical data root with explicit version markers, common in static-site CMS and local-first content systems
• a manifest plus migrations model, which is the normal way to evolve structured local data safely
• a staging or inbox layer before promotion, common in content pipelines and review-driven data systems
• a thin service layer between UI and files, which is the standard way to keep route handlers and components from owning storage rules
• tests around the data contract, especially load, validation, relation resolution, and migrations

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

6. Options

Option A: Formalized local-first domain

Pros:

• keeps current source-of-truth model
• keeps agents and humans operating on inspectable files
• minimizes rewrite risk
• easiest path to shipping all six recommendations

Cons:

• still file-backed, so bulk analytics and concurrent editing remain limited
• requires discipline around manifests, migrations, and tests

Option B: Embedded DB now

Pros:

• cleaner queries and joins
• simpler future filtering and reporting
• less manual record traversal code over time

Cons:

• introduces schema migration machinery now
• weakens the inspectable-per-file workflow Pete already likes
• raises scope before the human review flow is fully mature

Option C: Hosted service

Pros:

• strongest long-term centralization
• can support richer multi-user features later

Cons:

• highest complexity
• highest maintenance burden
• least aligned with the current local-first OpenClaw setup

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:

• accidental canonical data corruption during migration
• staged updates bypassing review and writing directly into canonical records
• broken linked-record references if migration scripts drop or rewrite IDs incorrectly
• silent drift between schema version, manifest version, and live code expectations
• history noise if every tiny write creates messy commit output

Mitigations:

• migrate with copy-and-verify, not move-and-pray
• preserve record IDs exactly
• keep evidence.source_ids and linked-record validation intact
• require explicit promotion from staging into canonical records
• validate manifest version on load
• add smoke tests before and after migration
• keep history writes at meaningful checkpoints, not every keystroke

9. Implementation Scope

Phase A, foundation

Create or refactor:

• data/uas-database/
• data/uas-database/manifest.json
• data/uas-database/records/companies/
• data/uas-database/records/products/
• data/uas-database/records/customer-segments/
• data/uas-database/records/evidence/
• data/uas-database/schema/
• data/uas-database/migrations/
• mission-control/lib/uas-database/records.ts
• mission-control/lib/uas-database/validation.ts
• mission-control/lib/uas-database/relations.ts
• mission-control/lib/uas-database/queries.ts
• mission-control/lib/uas-database/service.ts
• compatibility shim so existing routes continue to work during the transition
• migration script to copy and verify the legacy dataset into the new root

Phase B, operations

Create:

• data/uas-database/staging/
• proposal file format for staged changes
• server helpers to promote staged changes into canonical records
• Mission Control UI or admin affordance for reviewing staged items
• consistent commit helper behavior for accepted canonical changes

Phase C, durability

Create:

• tests for load, validate, resolve, save conflict, and migration smoke cases
• developer docs for the UAS Database domain contract
• artifact documenting migration and operating rules

Expected code touch points

At minimum:

• mission-control/lib/uas-database-store.ts or its replacement modules
• mission-control/lib/uas-database-types.ts
• mission-control/app/api/uas-database/companies/route.ts
• mission-control/app/api/uas-database/companies/[id]/route.ts
• any save or relation helpers used by the current UAS Database pages
• workspace scripts for migration and validation

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:

• current legacy path: /Users/vinny/.openclaw/workspace/data/lantronix-uas-workbench-phase1/schema/company.schema.json
• target path after migration: /Users/vinny/.openclaw/workspace/data/uas-database/schema/company.schema.json

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

• Do not move to SQLite or a hosted DB in this implementation track.
• Do not weaken linked-evidence traceability.
• Do not break the current company-first review flow.
• Do not remove working legacy data until copy-and-verify migration succeeds.
• Do not let staging writes silently mutate canonical records.
• Do not build a generic dataset framework in this phase.
• Do not expand into multi-user workflow or permissions in this phase.

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

• create data/uas-database/ and migrate the canonical dataset into it
• add manifest.json
• split the existing store into first-class domain modules
• keep existing UAS routes working through the new service layer
• add at least one migration smoke test and one core load/save validation test

Tranche 2

• add staging/ and proposal format
• add promotion helpers and review surface
• wire commit-backed history for accepted canonical changes

Tranche 3

• expand tests
• add operator docs
• remove transitional fallback code once the new root is stable