UAS Database First-Class Domain Tranche 2 Handoff

Implementation HandoffCompleteCreated Apr 27, 20264 min readFull screen ↗

Tranche 2 is now live. The UAS Database has a staging lane under data/uas-database/staging/, proposal records can be created and reviewed inside Mission Control, staged company proposals can be promoted into canonical company records, and accepted promotions now create git-backed history commits in the OpenClaw repo. The first end-to-end validation succeeded after fixing two real blockers: a staging UI type mismatch and a history helper that was resolving the wrong git root.

What changed

Staging data model

Created a first-class staging lane under the canonical UAS Database root:

data/uas-database/staging/

Proposal format supports:

staged company update intent
canonical target ID and target name
status (staged or promoted)
summary and rationale
creator metadata
base canonical updatedAtMs for conflict detection
full proposed company record snapshot
promotion review metadata
history metadata for commit-backed promotion

Service and API

Added server-side support for:

create proposal
list proposals
proposal detail
promote proposal to canonical company record
conflict detection if canonical company changed since staging
validation against existing segments and evidence before stage or promote
git-backed commit creation on successful promotion

Mission Control surface

Added a review surface at:

/uas-database/staging

That surface is enough for operator use in tranche 2:

browse staged and promoted proposals
inspect proposal detail
see conflict state
promote a proposal

Files changed

Mission Control routes and UI

mission-control/app/(app)/uas-database/staging/page.tsx
mission-control/components/uas-database/StagingWorkspace.tsx
mission-control/app/api/uas-database/staging/route.ts
mission-control/app/api/uas-database/staging/[id]/route.ts
mission-control/app/api/uas-database/staging/[id]/promote/route.ts

Mission Control domain logic

mission-control/lib/uas-database/staging.ts
mission-control/lib/uas-database/history.ts
mission-control/lib/uas-database/paths.ts
mission-control/lib/uas-database-types.ts

Data

data/uas-database/staging/
retained one promoted validation proposal as proof of the live flow
removed failed staged validation proposals so the queue is clean

Proposal format

Proposal records are stored as JSON under data/uas-database/staging/.

Key fields:

id
record_type: staged-company-proposal
entity_type: company
action: update
target_id
target_name
status
summary
rationale
created_at
created_by
base_updated_at_ms
proposed_record
review
history

This is enough to support staging, diff-style human review, conflict detection, and promotion history.

Promotion flow

Operator creates a staged proposal against a canonical company.
Proposal stores the base canonical updatedAtMs value.
Proposal detail view compares the stored base timestamp to the current canonical file timestamp.
If canonical changed, promotion is blocked with a conflict.
If canonical is unchanged and validation passes, promotion:

writes the proposed record into the canonical company file
marks the proposal as promoted
writes review metadata
creates a git-backed history commit for the accepted change

If promotion fails after file writes begin, the code rolls back the canonical company file and proposal file to their original raw contents.

History behavior

Accepted canonical promotions now create git commits in the parent OpenClaw repo, not the workspace subdirectory.

Live validation produced commit:

be53bf9298bd676ca84210ad413b39453350b00c

Commit message format:

mission-control(uas-db): promote <proposal-id> to <company-id>

This provides lightweight durable history without introducing a separate revision system.

Validation

Build and runtime

Commands run:

npm run build
npm run service:restart

Live checks passed:

/uas-database/staging → 200
GET /api/uas-database/staging → 200
create staged proposal via POST /api/uas-database/staging
read proposal detail via GET /api/uas-database/staging/:id
promote proposal via POST /api/uas-database/staging/:id/promote

Successful promotion validation:

proposal status moved to promoted
proposal detail reported no canonical conflict before promote
canonical write completed
history commit returned a real SHA
staging API meta now shows a clean queue with only the promoted validation record retained

Real blockers fixed during tranche 2

StagingWorkspace.tsx referenced the wrong proposal detail type name, which broke the build.
history.ts assumed the git repo lived at workspace/.git; the real repo root is one level up at /Users/vinny/.openclaw.

Both are fixed and validated.

Remaining gaps

Tranche 2 is complete, but a few things are intentionally still future work:

no richer diff visualization yet, beyond proposal vs canonical review context
no bulk promotion workflow
no operator docs yet for staging conventions
no tranche-3 expanded test coverage yet

Recommendation

Move JAM-49 to needs-review and assign Pete. Tranche 2 is ready for review.

Best next build target after review:

Tranche 3, expanded tests and operator documentation, plus removal of transitional rough edges where appropriate

Artifacts