lardon3d/docs/architecture/overview.md

# Lardon3D Architecture Overview

## Purpose

Lardon3D is a persistent, incremental, resource-aware photogrammetry engine for Linux.

The TUI is the operational control center for projects, acquisition, Tasks, durable progress,
resource state, optical configuration and optional external-storage control. Rich visualization and
live acquisition remain separate product areas and must consume validated snapshots rather than
mutable worker buffers.

## Current authority

```text
CURRENT_PROJECT_DB_SCHEMA=v25
CURRENT_PRODUCTION_TASK_KINDS=16
RESOURCE_UTILIZATION_POLICY=MAXIMUM_SAFE_USEFUL_THROUGHPUT
SERIALISM_REQUIRES_PROOF=CANONICAL
REAL_S21_TRACKS=PASS/FROZEN
REAL_A6000_PRE_SFM=PASS/FROZEN
```

The current Project DB head is additive:

```text
v22  Selected scientific execution foundation
v23  Generic optical-context overlay
v24  raw.develop.batch/1 persistence
v25  features.extract.batch/1 persistence
```

Earlier schema versions remain valid historical contracts where their documentation says so. Current
documentation must not present an older version as the active head merely because that version owns a
specific historical scientific or persistence boundary.

## Global execution model

```text
TUI / Project
    |
    v
Task
    |
    v
immutable resource estimate / capability
    |
    v
bounded Task Queue
(one active callback)
    |
    v
Resource Governor
(admission + reservation)
    |
    v
admitted owner callback
    |
    +--> bounded internal participants when justified
    |
    v
deterministic owner publication
    |
    v
durable checkpoint / restart boundary
    |
    v
validated snapshot consumers
```

The Queue owns bounded dispatch and backpressure. The Governor owns production resource admission.
The active Task owns its execution state and any bounded internal participants. Scientific stores own
their own identities and artifact validation.

No layer may silently absorb another layer's authority.

## Canonical resource objective

Lardon3D first preserves the interactive host reserve required for normal workstation use. Safe and
useful capacity beyond that reserve belongs to the active workload.

The objective is:

```text
MAXIMUM_SAFE_USEFUL_THROUGHPUT
```

This does not mean maximizing utilization percentages for appearance. It means using the largest
currently safe and useful CPU, RAM, I/O and validated accelerator capability while preserving
scientific identity, deterministic publication, host responsiveness and pressure limits.

The companion rule is:

```text
SERIALISM_REQUIRES_PROOF
```

Per-item atomicity does not imply cross-item serialization. Ordered or owner-only durable publication
does not imply serial preparation. Independent work should expose bounded concurrency when exact
science and persistence semantics can be preserved.

A CPU1 or batch1 path may remain when serialism, a measured scaling knee, memory, I/O, GPU execution,
exclusive state or another concrete constraint justifies it. Historical conservative descriptors are
not portable performance ceilings.

On the current validation host, the normal observed outcome is approximately:

```text
16 logical CPUs total
4 logical CPUs reserved for interactive host use
12 logical CPUs available to the compute pool
~3 GiB MemAvailable hard reserve
Radeon 780M UMA available to validated and useful GPU backends
```

These values are reference-host observations, not product constants.

## Current components

### Project

Persistent project lifecycle, stable identity, directory layout and Project DB ownership.

**Status:** IMPLEMENTED

### Project Database

SQLite owns durable logical identities, relations, typed Task payloads, scientific metadata and
references to external immutable artifacts.

The current schema head is v25. The scientific meaning of historical rows remains owned by the
versioned contracts that created them.

**Status:** CURRENT / v25

### Import and ScanSets

Import materializes managed immutable assets and logical images under explicit ScanSets. Provenance
from external source paths remains distinct from managed asset identity.

**Status:** IMPLEMENTED

### Capture / Asset Provenance

Capture identity remains distinct from file, Asset, `image_id`, SHA-256, path, Task ID and campaign
group ID. RAW and JPEG siblings may belong to one physical Capture without becoming one file or one
scientific image identity.

**Status:** PASS / FROZEN

### Bounded acquisition discovery and campaign execution

Discovery and planning are bounded and deterministic. Automatic grouping requires the documented
strong evidence; otherwise explicit caller confirmation remains `CALLER_EXPLICIT`.

Durable campaign execution uses the existing Task, Queue, Governor and Project DB recovery model.

**Status:** PASS / FROZEN

### Photo Quality Triage

Quality analysis is an operational selection layer, not a scientific identity. It produces explicit
GOOD / SUSPECT / REJECT recommendations and keeps human overrides distinct.

**Status:** PASS / FROZEN

### Selected scientific execution

The selected-execution snapshot binds the retained acquisition groups to explicit scientific
representations without inferring identity from paths, filenames or metadata.

**Status:** PASS / FROZEN

### Optical profiles and calibration selection

Project DB v23 provides generic camera-body profiles, lens profiles, optical configurations,
campaign/Capture assignments, calibration profiles and explicit compatible calibration selection.

Electronic metadata aliases are exact. Manual lenses without EXIF are normal. Missing or ambiguous
identity remains unresolved rather than guessed.

**Status:** IMPLEMENTED / VALIDATED

### RAW development

The historical `raw.develop/1` path remains valid. Project DB v24 adds
`raw.develop.batch/1`, allowing bounded independent RAW preparation with deterministic owner-only
publication in selected-item order.

Per-Capture publication remains atomic while cross-Capture preparation may be concurrent.

**Status:** IMPLEMENTED / VALIDATED

### Feature Store

Feature Store publishes immutable content-addressed Feature Files and bounded typed readers for ORB,
SIFT and RootSIFT data.

The historical `features.extract/1` task remains valid. Project DB v25 adds
`features.extract.batch/1`, which prepares independent selected images with bounded participants and
publishes Feature Sets deterministically through the owner callback.

**Status:** IMPLEMENTED / VALIDATED

### Visual Index

The ORB LSH Visual Index is persistent and segmented. It indexes homogeneous Feature Sets in bounded
updates and retrieves candidate relationships without performing geometric validation.

**Status:** IMPLEMENTED

### Candidate Pair

Candidate Pair generation answers which image pairs are worth exploring. Scientific pair identity and
canonical ordering remain independent from the amount of execution parallelism used to prepare them.

Candidate currently uses a bounded coupled CPU/batch ladder because additional CPU cannot exercise
additional independent pair work while the admitted item window remains one.

**Status:** IMPLEMENTED

### Matcher

Matcher produces deterministic Match Results from Feature Sets.

ORB supports the validated Vulkan hot path with exact CPU fallback. SIFT and RootSIFT remain CPU
OpenCV L2 paths. GPU use is selected only when a backend is both validated and useful.

**Status:** IMPLEMENTED

### Geometric Verification

Geometric Verifier v3 performs Fundamental USAC/MAGSAC verification with bounded restartable Task
execution. Scientific solver parallelism remains controlled by its contract while cross-parent
preparation can use bounded Governor-admitted participants.

**Status:** IMPLEMENTED / VALIDATED

### Track Model and Track Builder

Track Model v1 and Track Builder publish immutable Track Sets with deterministic identity and bounded
recovery semantics.

Retained real-data evidence includes:

```text
REAL_S21_TRACKS=PASS/FROZEN
REAL_A6000_PRE_SFM=PASS/FROZEN
```

**Status:** PASS / FROZEN

### Sparse SfM

Calibrated Sparse SfM capability is implemented through Gates C-G:

- Gate C: calibrated geometric primitives;
- Gate D: incremental reconstruction core;
- Gate E: final per-component Bundle Adjustment;
- Gate F: durable Task orchestration and atomic Project DB publication;
- Gate G: Governor admission and resource integration.

Phase H v1 adds incremental enrichment from immutable predecessor snapshots without redefining Gate F
scientific identity.

**Status:** C-G PASS / FROZEN; PHASE H V1 PASS / FROZEN

Implemented capability must remain distinct from execution on a particular real campaign. The
historical S21 and A6000 Engine Bay campaigns remain `CALIBRATION_UNAVAILABLE` for known-calibration
Sparse SfM. The retained A6000 proof intentionally stopped before Sparse SfM and Dense/MVS.

### MVS boundary

MVS-M1 provides the validated bounded external OpenMVS boundary and deterministic COLMAP/PLY exchange
contracts.

Durable dense publication, full Dense/MVS orchestration, mesh refinement, texturing and export remain
future work.

**Status:** PASS / FROZEN boundary

### Task Runtime

Tasks own lifecycle state, progress, cooperative pause/cancel behavior, sequence boundaries,
checkpoints and typed durable reconstruction.

**Status:** IMPLEMENTED

### Task Queue

The Queue provides bounded FIFO dispatch with one active callback, stable scanning and resource-WAIT
bypass behavior. It does not own resource policy.

**Status:** IMPLEMENTED

### Task Kind Registry

The production registry currently contains 16 Task kinds. Historical documents may legitimately
record smaller inventories at their checkpoint.

**Status:** IMPLEMENTED

### Hardware Profile and Resource Snapshot

Hardware Profile detects static host capability. Resource Snapshot captures current observable
capacity and pressure signals required for admission.

Unavailable optional telemetry remains unknown; it must not be fabricated.

**Status:** IMPLEMENTED

### Resource Governor

The Governor is the sole production authority for CPU, RAM, GPU, I/O admission and process-local
scratch leases where explicitly supported.

Pressure may throttle future admission. When pressure clears, useful resources must be eligible to
ramp back up; throttling is not a permanent lower ceiling.

UMA GPU allocations are charged exactly once against host RAM. Swap, zram and external scratch never
become admitted RAM.

**Status:** IMPLEMENTED / VALIDATED

### Optional external SSD controller

The UDisks2/GDBus controller owns the reviewed physical lifecycle for the exact
`LARDON_SWAP` / `LARDON_SCRATCH` device contract. It is not a second scheduler or Governor.

The Governor remains the sole production entry for scratch leases. The current 16 production Task
kinds have zero authoritative scratch consumption; visible storage capacity is not fabricated usage.

**Status:** CURRENT / VALIDATED OPERATIONAL

### TUI observatory and control center

ncurses input and rendering remain on the main thread. Runtime observation is bounded and coalesced.
The TUI exposes project state, Tasks, durable progress, resource state, optical configuration and SSD
control.

Validated layout boundaries are:

```text
full layout        >= 100x30
reference compact  72x20
minimum supported  60x15
```

Below the minimum, only the bounded terminal-too-small fallback is rendered.

Opening, closing or switching a project is a Queue/DB lifetime boundary: destroy and join the sole
Queue first, including finished callbacks, then close Project DB, recreate one empty Queue and rebind
observers.

**Status:** CURRENT / VALIDATED OPERATIONAL

## Publication and restart model

Long-running processing follows bounded sequence boundaries:

```text
admit bounded work
-> prepare bounded items
-> join participants
-> publish deterministic atomic results
-> persist typed cursor/state
-> checkpoint generic Task progress
-> release transient buffers
-> sequence break / re-admission
```

The exact order varies by Task contract, but durable progress must never claim work that has not
reached its authoritative publication boundary.

A crash may leave generic Task progress behind an already durable immutable result where the
documented retry contract permits exact reuse. Recovery must converge from durable identity; it must
not guess identity from paths, timestamps, basenames or similar metadata.

## Viewer and live boundaries

Viewer, coverage analysis, live localization and capture guidance remain future product areas.

The architecture requirement is already clear: visual consumers use validated immutable snapshots.
They do not access mutable worker buffers, own scientific identity or become a second execution
runtime.

Device-specific acquisition transports such as A6000 HDMI/USB or S21/mobile integration belong at the
acquisition adapter boundary. Heavy reconstruction remains PC-side.

## Core invariants

- No Task callback executes without a valid active reservation.
- Queue/runtime do not own resource policy.
- The Resource Governor is the sole production resource authority.
- ncurses remains owned by the main thread.
- Scientific and operational identities remain distinct.
- Task estimates and installed sequence contracts remain immutable for their defined lifetime.
- Memory, buffers, queues, files, descriptors, processes, threads and internal participants are bounded.
- Per-item atomicity does not imply cross-item serialization.
- Owner-only publication does not imply serial preparation.
- Validated and useful GPU backends are preferred when eligible and Governor-safe.
- UMA GPU memory is charged exactly once against host RAM.
- Swap, zram and scratch do not enlarge RAM admission.
- Failure and cancellation clean operation-owned transient resources.
- Atomic scientific publication never exposes partial results as complete.
- FROZEN scientific decisions are not reopened by resource-policy evolution.

## Current limitations and future scope

The following remain outside the current implemented execution model:

- general dependency DAG scheduling;
- multiple active Task callbacks / inter-Task worker pools;
- general CPU/GPU/I/O worker-pool architecture;
- multi-GPU scheduling;
- global orphan-artifact reconciliation;
- Visual Index compaction / larger-index evolution;
- authoritative Task scratch consumers;
- durable dense / mesh publication;
- full Dense/MVS orchestration;
- mesh refinement, texturing and final export workflow;
- viewer;
- offline coverage analysis;
- suggested supplementary viewpoints;
- live camera localization;
- live coverage overlay;
- A6000/S21 live acquisition integration;
- capture guidance;
- video ingestion and deterministic keyframe extraction.

Deferring inter-Task parallelism does not authorize accidental serialization inside the one active
Task. Bounded internal concurrency remains the current mechanism for independent work under
`SERIALISM_REQUIRES_PROOF`.

## Current summary

```text
CURRENT_PROJECT_DB_SCHEMA=v25
CURRENT_PRODUCTION_TASK_KINDS=16

RESOURCE_UTILIZATION_POLICY=MAXIMUM_SAFE_USEFUL_THROUGHPUT
SERIALISM_REQUIRES_PROOF=CANONICAL

RAW_BATCH_PATH=raw.develop.batch/1
FEATURE_BATCH_PATH=features.extract.batch/1

REAL_S21_TRACKS=PASS/FROZEN
REAL_A6000_PRE_SFM=PASS/FROZEN

SPARSE_SFM_CAPABILITY=C_G_PASS_FROZEN
REAL_A6000_SPARSE_SFM_EXECUTED=NO
REAL_A6000_DENSE_MVS_EXECUTED=NO

TUI=CURRENT_VALIDATED_OPERATIONAL
VIEWER=FUTURE
LIVE_CAPTURE_GUIDANCE=FUTURE
```

Detailed contracts remain owned by the specialized architecture documents. This overview summarizes
current repository state and must not replace those normative documents.