Onur Özkan committed
1 parent
43347c1172
commit
6e15063502
122 files changed
+7848
-9828
No files matched your search
@@ -0,0 +1,46 @@
|
||||
# Architecture
|
||||
|
||||
## Boundary
|
||||
|
||||
```text
|
||||
FakeRealtimeSource now / KaptanDataSource later
|
||||
→ EventEnvelope validation
|
||||
→ stream ordering and event-ID deduplication
|
||||
→ bounded immutable DataPlane journal
|
||||
→ mission reducer
|
||||
→ projections and selectors
|
||||
→ useSyncExternalStore
|
||||
→ React presentation
|
||||
|
||||
React intent
|
||||
→ DataPlane.preview
|
||||
→ authority + safety checks
|
||||
→ operator confirmation
|
||||
→ DataPlane.submit
|
||||
→ DataSource.send
|
||||
→ receipt event
|
||||
→ journal and mission projection
|
||||
```
|
||||
|
||||
`main.tsx` is the composition root and the only presentation-side file that
|
||||
chooses the simulation runtime. UI features receive a `DataPlane`; they cannot
|
||||
import the fake source, transport, or virtual clock.
|
||||
|
||||
## State ownership
|
||||
|
||||
| Category | Owner | Persistence |
|
||||
| --- | --- | --- |
|
||||
| Mission truth | DataPlane projection | Source/replay service in a future release |
|
||||
| Derived fleet/task/selection views | Pure selectors | Never |
|
||||
| Local UI state | React feature state | Never unless promoted to preference |
|
||||
| Operator preferences | `PreferenceStore` schema v2 | Local storage |
|
||||
| Audit/event journal | DataPlane, bounded to 1,000 raw envelopes | Replaceable journal port |
|
||||
|
||||
Telemetry is updated in the data plane and subscriber notification is batched
|
||||
to a projection cadence. React does not own a second authoritative mission
|
||||
copy. The 50 markers use CSS transforms and the fake source uses scenario-level
|
||||
ticks instead of component timers.
|
||||
|
||||
The map is a local raster demonstration asset with DOM/SVG overlays. Spatial
|
||||
values are simulated percentages and must not be interpreted as surveyed
|
||||
coordinates, navigation truth, or a safe route.
|
||||
@@ -0,0 +1,25 @@
|
||||
# Data plane
|
||||
|
||||
`DataSource` exposes descriptor/capabilities, connect, disconnect, command
|
||||
submission, and optional replay controls. It contains no WebSocket, serial,
|
||||
MAVLink, or Cerebrum types.
|
||||
|
||||
Every `EventEnvelope` carries schema version, stable event and stream IDs,
|
||||
monotonic sequence, type, entity reference, source/receive timestamps,
|
||||
optional correlation/causation IDs, payload, and quality/staleness metadata.
|
||||
Unsupported schemas, invalid identity, sequence, timestamp, type, or quality
|
||||
metadata are rejected into observable source diagnostics. Duplicate event IDs
|
||||
and sequences at or below a stream high-water mark never mutate mission truth.
|
||||
The fake journal is bounded to 1,000 envelopes and activity projection to 500
|
||||
rows.
|
||||
|
||||
A snapshot replaces the projection. Telemetry updates known vehicles and
|
||||
never creates identities. Source-health events represent pause, loss,
|
||||
degradation, and recovery. An eventual live adapter must add unknown-reference
|
||||
quarantine, signed source identity, restart epochs, and durable replay storage.
|
||||
|
||||
Commands use explicit lifecycle names. This release exercises Draft →
|
||||
Validating → Validated → Dispatched → Acknowledged through preview and receipt
|
||||
events, and represents queued/executing/completed intents in the action queue.
|
||||
Rejected previews or source receipts include a human reason and remediation;
|
||||
they do not mutate mission truth.
|
||||
@@ -0,0 +1,37 @@
|
||||
# Kaptan Ground Suite — spatial design reset
|
||||
|
||||
This board is the implementation benchmark for the persistent operations scene. The supplied Kaptan images are treated as visual-language evidence, not as an information architecture.
|
||||
|
||||
## Evidence board
|
||||
|
||||
| Reference | Borrow | Avoid |
|
||||
| --- | --- | --- |
|
||||
| Company of Heroes 2 | Safe left-click selection, additive selection, numbered control groups, contextual command verbs, readable queued intent, tactical overview | Orders that fire from an ambiguous right-click; game-only pause semantics; selection implying command rights |
|
||||
| Total War battles | Formation footprints, drag-to-orient placement, compact unit cards, group framing, large-force distributions | Screen-filling unit-card chrome; hidden morale/state meanings; instant consequential placement |
|
||||
| QGroundControl setup | Capability coverage, explicit calibration state, parameter metadata, preflight blockers, geofence concepts | A separate page per subsystem, long forced setup wizard, scalar-only telemetry, forms that hide geography |
|
||||
| Supplied semantic-zoom image | Strategic → operational → tactical information density; selected/observed/planned separation | Three separate map instances or page transitions to represent zoom |
|
||||
| Supplied mission overview | Graphite/navy palette, compact status strip, authority/presence language, direct map labels | Top navigation, oversized attention columns, cards competing with the map |
|
||||
| Supplied task/recovery images | Spatial route preview, exact recommendation comparison, audit timeline | Full-screen recovery page; acceptance before a final revalidation |
|
||||
| Supplied design-system image | Cyan selection, violet planning, amber attention, red only for danger, non-color marker shapes | Color-only state, generic rectangular button walls, tiny low-contrast text |
|
||||
|
||||
## Interaction state boundary
|
||||
|
||||
`Select` is the only safe resting state. Map pointer input is routed through one typed interaction controller. A mode owns its cursor, valid targets, pointer/keyboard semantics, draft geometry, completion, cancellation, validation, and output. Space/middle pointer temporarily owns pan. Escape cancels segment → draft → mode. Draft undo/redo never alters observed mission truth.
|
||||
|
||||
Selection, local control groups, authoritative mission groups, and authority leases are independent state domains. A command draft captures an immutable target set and is revalidated before the simulated adapter can acknowledge it.
|
||||
|
||||
## Persistent compositions
|
||||
|
||||
All viewports use the same mounted scene and the same regions; only secondary density changes.
|
||||
|
||||
| Viewport | Map target | Composition |
|
||||
| --- | ---: | --- |
|
||||
| 1366×768 | ≥ 52% of useful body area | 42 px status strip; 48 px tool rail; 218 px roster; map center; 286 px inspector; 122 px unit deck; 32 px collapsed timeline |
|
||||
| 1920×1080 | ≥ 60% | 48 px rail; 238 px roster; 320 px inspector; expanded spatial labels and telemetry charts |
|
||||
| 3440×1440 | ≥ 68% | fixed secondary rails; map absorbs width; inspector becomes a two-column engineering surface; unit cards remain bounded |
|
||||
|
||||
Tools never replace the map. Fleet occupies the roster overlay; deployment and contextual abilities occupy the bottom deck; queue/events/telemetry expand upward; configuration and recovery dock from the right; settings is a compact drawer.
|
||||
|
||||
## Required high-fidelity states
|
||||
|
||||
The live implementation itself is the high-fidelity composition source. Deterministic state presets and screenshot tests cover: default tactical control, large multi-selection, route/formation drafting, task-area drawing, deployment/discovery, calibration, parameter diff, and degraded recovery. Screenshots are captured at 1366×768, 1920×1080, and 3440×1440; no preset is allowed to unmount `[data-testid="operational-map"]`.
|
||||
@@ -0,0 +1,20 @@
|
||||
# Deterministic fake scenarios
|
||||
|
||||
The default seed (`17`) creates Coastal Survey / ALPHA-17, five operators,
|
||||
five groups, fifty vehicles, six archetypes, tasks, queues, authority leases,
|
||||
and a common initial event history. Positions, energy, link quality, and
|
||||
headings are reproducible.
|
||||
|
||||
The virtual clock supports pause, resume, restart, 0.5×–4× UI speed, and
|
||||
manual stepping in tests. A 100 ms source cadence models 10 Hz vehicle input;
|
||||
the data plane batches subscriber notification. Deterministic tick windows
|
||||
exercise packet staleness, ALPHA navigation degradation and coverage loss,
|
||||
source degradation, and recovery. BRAVO starts near constraint R-210B.
|
||||
|
||||
Recovery ranks compatible reserve candidates from energy, link, distance, and
|
||||
capability. The recommendation remains a preview until the operator confirms;
|
||||
the alert is marked resolved only by the acknowledged simulated command event.
|
||||
Restart reconstitutes the exact seed and clears the data-plane ordering state.
|
||||
|
||||
Tests construct the source with automatic timers disabled and call `step`, so
|
||||
no assertion depends on wall-clock scheduling.
|
||||
@@ -0,0 +1,16 @@
|
||||
# Ground-station issue traceability
|
||||
|
||||
Firmware-dependent work is explicitly deferred. “Implemented” below means the
|
||||
Ground Suite simulation side, not a live-aircraft integration.
|
||||
|
||||
| Issue | Implemented scope | Deferred / firmware dependency | Modules and tests | Acceptance criteria |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| #24 `ground-station: add persistent app state` | Schema-v2 layers, panels, density, motion, viewport, hotkeys, last workspace, safe draft references; migration/reset/corruption recovery | Shared mission persistence and telemetry storage | `core/persistence/preferences.ts`, `preferences.test.ts`, Settings | Reload-safe preferences; invalid data resets; no mission truth persisted |
|
||||
| #23 `ground-station: support "jump to" on events` | Entity/position targets change selection, zoom, map highlight, inspector/context; alert and timeline paths | Distributed event provenance | `domain/model.ts`, `App.tsx`, `App.test.tsx` | Jump selects and identifies group/task/vehicle/constraint context |
|
||||
| #22 `ground-station: toggleable information layers` | Ten searchable/operational layers, all/none, legend, persistence, critical mandatory layers | Certified geodata and live coverage | `preferences.ts`, `LayerPanel`, component tests | Keyboard toggles persist; mandatory safety context remains visible |
|
||||
| #21 `ground-station: tactical selection (via configurable hotkeys)` | Click, Shift add/remove, marquee, group keys, double-frame, F/Esc/L/Q/Space, conflicts, accessible list alternatives | Policy-synchronized hotkeys and robust lasso | `App.tsx`, `preferences.test.ts`, `App.test.tsx` | Inputs never capture shortcuts; exact selection shown |
|
||||
| #20 `ground-station (+firmware): action queue` | Ordered intentions, dependency/owner/resource/duration/timeline, accessible reorder, preview, receipt audit | Firmware queue protocol, cancellation/reconciliation | `domain/model.ts`, Queue workspace, `DataPlane.test.ts` | Reorder remains draft until validated, confirmed, acknowledged |
|
||||
| #19 `ground-station (+firmware): cerebrum integration` | Port, discovery/outcome/result/error types, deterministic fake and contract tests | Real API, transport, concurrency, certification | `adapters/cerebrum/*` | Unsupported outcomes reject explicitly; no live claim |
|
||||
| #18 `ground-station: multi-operator support` | Five presences/cursors/roles/activity, observers, leases, explicit transfer preview and audit, read-only language | Shared server, arbitration, durable lease expiry | `scenario.ts`, mission inspector, preview tests | Selection and authority remain distinct; transfer is explicit |
|
||||
| #17 `ground-station: animated vehicle archetypes on vehicle catalog` | Six imagery-backed cards, capabilities/roles/simulated range, counts/status, restrained orientation | Reviewed build-manifest catalog generation | Catalog workspace/assets; reduced-motion CSS | Motion respects preference; placeholders say simulated |
|
||||
| #16 `ground-station: fleet management (multi vehicle management)` | Overview, membership/archetype/status/freshness/task/role/formation/filtering/reserve/bulk target preview/binding | Real source binding and server-side group transactions | Fleet workspace, selectors tests, preview tests | Every bulk operation exposes exact target set and validation |
|
||||
@@ -0,0 +1,29 @@
|
||||
# Future Kaptan and Cerebrum integration
|
||||
|
||||
`KaptanDataSource` is intentionally a rejecting skeleton. Current firmware is
|
||||
telemetry-only and the repository safety boundary rejects inbound authority.
|
||||
No reviewed command API, authenticated source binding, or capability exchange
|
||||
exists, so this release claims none.
|
||||
|
||||
A future adapter must define and review:
|
||||
|
||||
- authenticated source and vehicle identity, key provisioning/rotation, and
|
||||
persistent anti-replay state;
|
||||
- MAVLink 2 signing policy and exact Kaptan dialect/schema revision;
|
||||
- snapshot/restart epochs, sequence wrap, time synchronization, stale data,
|
||||
reconnect and partial-fleet behavior;
|
||||
- capability negotiation for vehicle/task/formation/action-queue behavior;
|
||||
- idempotent command IDs, exact target binding, authority leases,
|
||||
acknowledgement/rejection, cancellation, expiry, and reconciliation;
|
||||
- safe handling of unsupported or downgraded firmware.
|
||||
|
||||
`AutonomyCoordinatorPort` separately models capability discovery and exchange
|
||||
of desired outcomes, constraints, success criteria, proposals, explanations,
|
||||
and typed errors. `FakeCerebrumAdapter` is contract-tested. The real Cerebrum
|
||||
transport, concurrency semantics, conflict resolution, plan provenance,
|
||||
versioning, timeout policy, and safety certification remain unresolved. A
|
||||
wire protocol must not be inferred from the TypeScript interface.
|
||||
|
||||
The next integration step is a reviewed, read-only Kaptan telemetry adapter
|
||||
that validates signed source-to-vehicle bindings and event freshness without
|
||||
adding command authority.
|
||||
@@ -0,0 +1,21 @@
|
||||
# Safety model
|
||||
|
||||
Selection is local attention; authority is a mission-truth lease. Selected,
|
||||
observed, requested, authority-held, conflict, and unavailable states use text
|
||||
and symbols as well as color. No selection shortcut changes a lease.
|
||||
|
||||
Consequential commands always show what and where, the exact affected vehicle
|
||||
set, current holder, reason for allowance/rejection, next state, and failure
|
||||
effect. Validation covers simulated energy reserve, link quality, telemetry
|
||||
freshness, route/constraint warning, capability where applicable, authority,
|
||||
and source connectivity. A failed preview cannot be confirmed. Source
|
||||
rejections carry a remediation path and are journaled.
|
||||
|
||||
UI movement is presentation only. The event stream is telemetry truth. The
|
||||
persistent `SIMULATED DATA` badge and server warning distinguish every
|
||||
interaction from real aircraft control. Local storage contains no telemetry,
|
||||
lease, credential, receipt, or audit truth. Critical-state mandatory layers
|
||||
cannot be hidden.
|
||||
|
||||
This is an operator workflow prototype and simulation test surface, not a
|
||||
flight-safety approval or physical command system.
|
||||
Reference in new issue
Block a user