lardon3d/docs

Lardon3D Documentation Index

Status

DOCUMENTATION_INDEX=CURRENT
CURRENT_PROJECT_DB_SCHEMA=v25
CURRENT_PRODUCTION_TASK_KINDS=16

REAL_S21_TRACKS=PASS/FROZEN
REAL_A6000_PRE_SFM=PASS/FROZEN
PRODUCT_DEFINITION_V1=PASS/FROZEN
PROMPT_TREE=CURRENT
CURRENT_NEXT=CALIBRATION_WORKFLOW_COORDINATOR

This index separates current authority, historical evidence and future product-definition work.

Repository documentation is read in context: an older schema number, Task count or resource measurement inside a historical checkpoint is not stale merely because the current repository has moved forward.

Authority order

When current-state prose disagrees, use this order:

1. AGENTS.md for repository-wide engineering/agent obligations and protected boundaries.
2. Specialized architecture documents for the subsystem contract they own.
3. docs/roadmap/roadmap.md for current lifecycle / next work.
4. README.md and architecture overview for concise summaries.
5. Historical audits only for the checkpoint they explicitly record.

Executable source and schema implementation remain authoritative when a documentation excerpt claims to quote an exact API, DDL or constant.

Current repository state

Project DB head          v25
Production Task kinds    16

v22 selected scientific execution foundation
v23 generic optical-context overlay
v24 raw.develop.batch/1 persistence
v25 features.extract.batch/1 persistence

Canonical resource objective:

MAXIMUM_SAFE_USEFUL_THROUGHPUT
SERIALISM_REQUIRES_PROOF

Reference-host values are measurements, not portable constants.

Current real-data checkpoints

S21

REAL_S21_TRACKS=PASS/FROZEN

The retained S21 proof reaches Tracks.

A6000

real-a6000-pre-sfm-2026-09-02
REAL_A6000_PRE_SFM=PASS/FROZEN

Retained A6000 counts:

Feature Sets        689
Candidate Pairs     38,420
Match Results       38,420
Applicable GVRs     37,805
Verified GVRs       10,952
Rejected GVRs       26,853
Track Sets          1
Tracks              130,714
Track observations  318,944

The A6000 checkpoint stops before real Sparse SfM and Dense/MVS.

Sparse SfM capability exists through frozen Gates C-G. Real Sparse SfM on the historical S21/A6000 campaigns remains blocked by known-calibration data.

Current architecture

Start here:

• Architecture overview
• Reconstruction pipeline
• Runtime
• Persistence
• Project Database

Task / resource execution

• Task System
• Task Queue
• Task Kind Registry
• Resource Governor
• Resource Boundary
• Resource-aware Pipeline
• Internal Parallelism
• Scheduler / Resource Integration

Resource authority split:

resource_governor.md   runtime policy
AGENTS.md              engineering / agent obligations
target_hardware.md     reference-host evidence
other documents        scoped summaries and links

Scientific pipeline

• Photo Quality Triage
• Feature Store
• Precision Feature Pipeline
• Visual Index
• Candidate Pair
• Match Result
• Matcher
• Geometric Verification Model
• Geometric Verifier
• Track Model
• Track Builder
• Sparse SfM
• Vulkan ORB Matcher

Current production Geometric Verifier lineage:

Fundamental v1  historical valid identity
Fundamental v2  historical valid identity
Fundamental v3  current production identity

Historical verifier results are never relabelled.

Calibration

• Calibration Science v1
• Calibration Tooling v1
• Calibration Bootstrap v1
• Calibration Solver Preflight v1

Historical S21/A6000 geometry evidence must not be retroactively given invented calibration.

Development

• Build
• Testing
• Concurrency
• Target Hardware

Build/test parallelism is host-aware. Fixed historical -j8, -j12 or serialized-suite evidence does not become a portable default.

TSan/OpenCV/TBB qualifications and Vulkan validation remain separate evidence boundaries.

Roadmap

• Roadmap

The roadmap owns the current lifecycle / next-work cursor.

Historical progress cursors inside other records do not override it.

Audits

• Documentation Inventory Audit
• Global Maintenance Audit
• Foundation Review

Historical audit rule

global_maintenance_audit.md and foundation_review.md are historical evidence.

Do not mechanically modernize their old:

• schema version;
• Task count;
• compiler/build count;
• resource measurement;
• checkpoint status.

The later A6000 checkpoint adds new operational evidence; it does not erase the maintenance checkpoint.

Concepts

• Scan Sets
• Visual Index concept
• Matching and Tracks
• Reconstruction Layers
• Geometric Constraints

Concept documents may be historical or explanatory. They do not outrank the current specialized architecture contract.

Product definition

Canonical target-product authority:

• Product Definition v1

PRODUCT_DEFINITION_V1=PASS/FROZEN
IMPLEMENTATION_AUTHORIZATION=NO
PROMPT_TREE=CURRENT

The product definition freezes desired end-product behavior without reopening existing FROZEN scientific contracts. Future implementation is authorized only by the subsequent execution-contract phase under explicit human authority.

Repository language

Canonical target:

DOCUMENTATION_LANGUAGE=ENGLISH
SOURCE_COMMENT_LANGUAGE=ENGLISH
AGENT_CONTRACT_LANGUAGE=ENGLISH
USER_INTERFACE_LANGUAGE=ENGLISH

The current-state documentation findings have been remediated in English.

Some untouched historical/current documents may still require a mechanical language-only normalization pass. Such translation must preserve historical facts and must not silently modernize scientific or lifecycle state.

Executable UI strings are changed only in an explicitly scoped UI-language implementation pass.

Navigation rule for future agents

Before implementation:

read AGENTS.md
-> read README.md
-> read this index
-> read the specialized architecture contract
-> read the current roadmap
-> inspect historical audits only when their evidence is relevant

Never use an older historical checkpoint as a substitute for current authority.