docs: freeze resource architecture boundary
This commit is contained in:
parent
67529791c4
commit
7872bc82ae
4 changed files with 270 additions and 10 deletions
|
|
@ -29,7 +29,7 @@ persistante, enrichissable et versionnable.
|
||||||
- **Image View** : vues triées et filtrées pour la TUI
|
- **Image View** : vues triées et filtrées pour la TUI
|
||||||
- **Task** : moteur de tâches avec pause/reprise, annulation et séquences
|
- **Task** : moteur de tâches avec pause/reprise, annulation et séquences
|
||||||
- **Task Checkpoint v1** : snapshot durable, fichier atomique et reprise sûre
|
- **Task Checkpoint v1** : snapshot durable, fichier atomique et reprise sûre
|
||||||
- **Project Database v14** : résultats géométriques, tâche Geometric Verifier durable et Track Model v1
|
- **Project Database v16** : résultats géométriques, Track Model v1 et persistance Sparse SfM
|
||||||
- **Geometric Verification Model v1** : identité, masque d'inliers et modèle 3×3 persistants
|
- **Geometric Verification Model v1** : identité, masque d'inliers et modèle 3×3 persistants
|
||||||
- **Geometric Verifier v1** : Fundamental USAC/MAGSAC, reprise et lots resource-aware
|
- **Geometric Verifier v1** : Fundamental USAC/MAGSAC, reprise et lots resource-aware
|
||||||
- **Task Kind Registry** : identité métier durable et reconstruction runtime explicite
|
- **Task Kind Registry** : identité métier durable et reconstruction runtime explicite
|
||||||
|
|
@ -121,6 +121,7 @@ Acquisitions
|
||||||
- [Sparse SfM / Triangulation — Gate A](docs/architecture/sparse_sfm.md)
|
- [Sparse SfM / Triangulation — Gate A](docs/architecture/sparse_sfm.md)
|
||||||
- [Backend Vulkan ORB](docs/architecture/vulkan_matcher.md)
|
- [Backend Vulkan ORB](docs/architecture/vulkan_matcher.md)
|
||||||
- [Viewer](docs/architecture/viewer.md)
|
- [Viewer](docs/architecture/viewer.md)
|
||||||
|
- [Resource Boundary — No New Resource Subsystem](docs/architecture/resource_boundary.md)
|
||||||
- [Revue des fondations](docs/architecture/foundation_review.md)
|
- [Revue des fondations](docs/architecture/foundation_review.md)
|
||||||
|
|
||||||
### Concepts
|
### Concepts
|
||||||
|
|
@ -164,8 +165,10 @@ Matcher v1, Geometric Verification Model v1 et Geometric Verifier Fundamental v1
|
||||||
sont implémentés. Le runtime Feature + Matcher + Verifier emploie des tâches durables,
|
sont implémentés. Le runtime Feature + Matcher + Verifier emploie des tâches durables,
|
||||||
de petits lots, le Resource Governor interactif et un hot path Vulkan ORB exact avec
|
de petits lots, le Resource Governor interactif et un hot path Vulkan ORB exact avec
|
||||||
fallback CPU. La feasibility Vulkan SIFT/RootSIFT a été rejetée ; ces deux matchers
|
fallback CPU. La feasibility Vulkan SIFT/RootSIFT a été rejetée ; ces deux matchers
|
||||||
restent sur OpenCV L2. DAG générique, Tracks, SfM et viewer restent des tickets
|
restent sur OpenCV L2. Track Model/Builder et les primitives géométriques Sparse
|
||||||
séparés planifiés.
|
SfM sont implémentés ; le solveur Sparse SfM complet, le DAG, le viewer et les
|
||||||
|
étapes denses restent des tickets séparés planifiés. Le Resource Governor ne
|
||||||
|
constitue pas un Resource System générique : voir la décision d’architecture.
|
||||||
|
|
||||||
## Licence
|
## Licence
|
||||||
|
|
||||||
|
|
|
||||||
251
docs/architecture/resource_boundary.md
Normal file
251
docs/architecture/resource_boundary.md
Normal file
|
|
@ -0,0 +1,251 @@
|
||||||
|
# Lardon3D Resource Boundary — No New Resource Subsystem
|
||||||
|
|
||||||
|
## Status
|
||||||
|
|
||||||
|
**ACCEPTED** — architecture decision for the post-Gate C documentation freeze.
|
||||||
|
|
||||||
|
Current gates: Gate A **PASS**, Gate B **PASS / FROZEN**, Gate C **PASS**.
|
||||||
|
Project Database: **v16**.
|
||||||
|
|
||||||
|
This record is normative for the current architecture. It does not introduce
|
||||||
|
an implementation, a public API, a persistence format or a roadmap commitment.
|
||||||
|
|
||||||
|
## Context
|
||||||
|
|
||||||
|
Lardon3D contains a Resource Governor and persistent stores for images,
|
||||||
|
features, matches, geometric results, tracks and Sparse SfM data. The term
|
||||||
|
“resource” in the Governor denotes an execution budget, not a loadable runtime
|
||||||
|
object.
|
||||||
|
|
||||||
|
The repository does not define a generic Resource System, generic artifact
|
||||||
|
resolver, runtime cache, resource handle or runtime dependency graph.
|
||||||
|
|
||||||
|
## Current system
|
||||||
|
|
||||||
|
### 1. Persistent identity and metadata
|
||||||
|
|
||||||
|
Project Database v16 owns logical identities and relations. SQLite IDs identify
|
||||||
|
projects, ScanSets, images, assets, Feature Sets, results, tracks and Sparse
|
||||||
|
SfM records. SHA-256 values identify published file contents. Metadata stores
|
||||||
|
sizes, states, provenance and project-relative artifact paths.
|
||||||
|
|
||||||
|
Logical identity and physical content identity are distinct: two logical
|
||||||
|
images or Feature Sets may share one immutable physical asset.
|
||||||
|
|
||||||
|
### 2. Artifact resolution and validation
|
||||||
|
|
||||||
|
Resolution is specialized by each store. Readers derive project-relative paths,
|
||||||
|
validate content-addressed layouts, verify sizes and SHA-256 values, then
|
||||||
|
validate file formats and metadata. Feature, Match and Sparse SfM readers are
|
||||||
|
bounded and do not constitute a generic Resource System.
|
||||||
|
|
||||||
|
External import sources are persisted as provenance. After a successful import,
|
||||||
|
the managed asset is canonical and no longer depends on the source path. A
|
||||||
|
moved project does not make an absolute external source portable.
|
||||||
|
|
||||||
|
### 3. Runtime residency and ownership
|
||||||
|
|
||||||
|
Tasks and processing backends own their working buffers. Readers and temporary
|
||||||
|
objects have explicit local lifetimes. Vulkan ORB has its own bounded backend
|
||||||
|
state. There is no shared runtime resource cache, generic loaded-object handle,
|
||||||
|
generic unload operation or generic dependency lifetime.
|
||||||
|
|
||||||
|
### 4. Resource governance
|
||||||
|
|
||||||
|
The Resource Governor owns policy decisions for RAM, GPU, CPU and IO budgets.
|
||||||
|
It consumes immutable task estimates, samples system pressure, chooses bounded
|
||||||
|
lots and creates opaque transient reservations. A task must hold an active
|
||||||
|
reservation before executing its callback and releases it exactly once.
|
||||||
|
|
||||||
|
The Governor does not own persistent IDs, resolve paths, validate file formats,
|
||||||
|
load application objects, cache data or manage semantic dependencies.
|
||||||
|
|
||||||
|
## Problem statement
|
||||||
|
|
||||||
|
No current or clearly-next requirement demonstrates the need for a generic
|
||||||
|
runtime Resource System or a cross-store artifact resolver. Existing stores
|
||||||
|
already provide the identity, path and validation behavior required by their
|
||||||
|
contracts, while the Governor already provides resource admission.
|
||||||
|
|
||||||
|
Adding another layer now would invent ownership, syntax, persistence and
|
||||||
|
lifetime rules without a consumer and could contaminate frozen Gate B
|
||||||
|
persistence.
|
||||||
|
|
||||||
|
## Four-layer model
|
||||||
|
|
||||||
|
```text
|
||||||
|
identity / metadata
|
||||||
|
↓
|
||||||
|
specialized artifact resolution and validation
|
||||||
|
↓
|
||||||
|
task-owned runtime buffers and lifetimes
|
||||||
|
↓
|
||||||
|
Governor admission, reservation and bounded execution
|
||||||
|
```
|
||||||
|
|
||||||
|
The layers remain separate. No layer is promoted into a generic Resource
|
||||||
|
System by this decision.
|
||||||
|
|
||||||
|
## Resource Governor boundary
|
||||||
|
|
||||||
|
The Governor remains resource-type agnostic. It answers whether an operation
|
||||||
|
fits current budgets; it does not answer what an asset is or where it lives.
|
||||||
|
Tasks create estimates, request reservations, execute bounded work and release
|
||||||
|
reservations. The Governor owns only policy, budgets, pressure, lots and
|
||||||
|
reservations.
|
||||||
|
|
||||||
|
## Project DB v16 boundary
|
||||||
|
|
||||||
|
Project DB v16 remains unchanged and frozen. It already stores the current
|
||||||
|
logical IDs, content hashes, sizes, states, relations and artifact paths needed
|
||||||
|
by implemented stores. No resource table, handle table, cache table,
|
||||||
|
dependency table, schema field or migration is required by this decision.
|
||||||
|
|
||||||
|
No Project DB v17, bundle redesign, Track Model change, Track Builder change or
|
||||||
|
persistence API redesign is part of this scope.
|
||||||
|
|
||||||
|
## Options considered
|
||||||
|
|
||||||
|
### A. Governor evolution
|
||||||
|
|
||||||
|
Rejected for the current ticket. The Governor is already the correct owner of
|
||||||
|
budgets, estimates, pressure, lots and reservations. Extending it toward
|
||||||
|
identity or artifact ownership would violate the current boundary.
|
||||||
|
|
||||||
|
### B. Internal artifact resolver
|
||||||
|
|
||||||
|
Deferred as a possible future refactoring, not a current subsystem. It may be
|
||||||
|
reconsidered if concrete duplication appears in path resolution,
|
||||||
|
canonicalization, artifact validation or moved-project handling.
|
||||||
|
|
||||||
|
### C. Generic Resource System
|
||||||
|
|
||||||
|
Rejected for the current ticket. No demonstrated requirement needs shared
|
||||||
|
runtime residency, cache eviction, explicit unload, stable handles, stale-handle
|
||||||
|
protection, runtime dependency graphs, asynchronous loading, streaming or
|
||||||
|
CPU/GPU dual residency.
|
||||||
|
|
||||||
|
### D. No new subsystem
|
||||||
|
|
||||||
|
Accepted. Existing stores and the Governor cover current requirements while
|
||||||
|
preserving independent ownership and bounded execution.
|
||||||
|
|
||||||
|
## Decision
|
||||||
|
|
||||||
|
**NO_NEW_SUBSYSTEM**
|
||||||
|
|
||||||
|
The repository must not add a generic Resource System, generic artifact
|
||||||
|
resolver or Governor asset integration as part of the current architecture.
|
||||||
|
|
||||||
|
## Rationale
|
||||||
|
|
||||||
|
- Existing persistent identities are sufficient.
|
||||||
|
- Existing stores already validate their own artifacts.
|
||||||
|
- Existing task and backend ownership is explicit and bounded.
|
||||||
|
- Existing Governor policy is sufficient for resource admission.
|
||||||
|
- No new public syntax or ABI is required.
|
||||||
|
- Gate B v16 remains untouched.
|
||||||
|
- The decision is reversible if a concrete future requirement appears.
|
||||||
|
|
||||||
|
## Current scope
|
||||||
|
|
||||||
|
- Preserve the four-layer separation above.
|
||||||
|
- Continue using specialized readers and stores.
|
||||||
|
- Keep the Governor policy-oriented and independent of asset identity.
|
||||||
|
- Treat Gate A, Gate B and Gate C as closed at their verified boundaries.
|
||||||
|
- Correct factual documentation drift without turning future designs into
|
||||||
|
current contracts.
|
||||||
|
|
||||||
|
## Explicit non-goals
|
||||||
|
|
||||||
|
- Resource manager or generic loader.
|
||||||
|
- Global runtime cache or eviction policy.
|
||||||
|
- Generic resource handles or stale-handle protection.
|
||||||
|
- Generic dependency graph or cycle management.
|
||||||
|
- Streaming or asynchronous resource loading.
|
||||||
|
- CPU/GPU dual-residency manager.
|
||||||
|
- Project DB v17 or schema migration.
|
||||||
|
- Bundle redesign.
|
||||||
|
- Governor integration with persistent asset identity.
|
||||||
|
- BA, new orchestration, Task Runtime redesign or renderer redesign.
|
||||||
|
|
||||||
|
## Syntax impact
|
||||||
|
|
||||||
|
No new syntax is required. Do not introduce `resource://`, `asset://`, UUID,
|
||||||
|
manifest or handle syntax without a later concrete requirement and decision.
|
||||||
|
Existing SQLite, Feature File, Match File, checkpoint and specialized path
|
||||||
|
contracts remain authoritative in their own domains.
|
||||||
|
|
||||||
|
## Persistence impact
|
||||||
|
|
||||||
|
None. Project DB remains v16. Existing IDs, hashes, metadata and relative paths
|
||||||
|
are not renamed, generalized or duplicated.
|
||||||
|
|
||||||
|
## Memory / resource impact
|
||||||
|
|
||||||
|
None beyond existing task estimates and Governor reservations. No new cache or
|
||||||
|
resident object ownership is introduced. Existing bounded readers and backend
|
||||||
|
buffers remain responsible for their own memory.
|
||||||
|
|
||||||
|
## Concurrency impact
|
||||||
|
|
||||||
|
None. No new shared mutable state, worker, callback, lock or lifetime protocol
|
||||||
|
is introduced. Existing Governor mutex/condition ownership remains unchanged.
|
||||||
|
|
||||||
|
## Security impact
|
||||||
|
|
||||||
|
No new path-resolution surface is introduced. Existing specialized validation,
|
||||||
|
content hashing, bounded input handling and protected file opening remain in
|
||||||
|
force. No generic external-file access is added.
|
||||||
|
|
||||||
|
## Testing requirements for future changes
|
||||||
|
|
||||||
|
Future store changes must retain their own path, hash, size, format,
|
||||||
|
publication and corruption tests. Future Governor changes must retain admission,
|
||||||
|
reservation, pressure, bounds and concurrency tests.
|
||||||
|
|
||||||
|
Only if a future requirement creates a shared resolver or runtime residency
|
||||||
|
layer should new syntax, ownership, lifetime, cache, dependency and resource
|
||||||
|
scale tests be designed.
|
||||||
|
|
||||||
|
## Future extension triggers
|
||||||
|
|
||||||
|
A resolver may be reconsidered only after concrete cross-store duplication in:
|
||||||
|
|
||||||
|
- path resolution;
|
||||||
|
- canonicalization;
|
||||||
|
- artifact validation; or
|
||||||
|
- moved-project handling.
|
||||||
|
|
||||||
|
A generic Resource System may be reconsidered only after multiple real
|
||||||
|
requirements emerge among:
|
||||||
|
|
||||||
|
- shared runtime residency;
|
||||||
|
- cache and eviction;
|
||||||
|
- explicit unload;
|
||||||
|
- stable handles and stale-handle protection;
|
||||||
|
- runtime dependency graphs;
|
||||||
|
- asynchronous loading;
|
||||||
|
- streaming;
|
||||||
|
- CPU/GPU dual residency; or
|
||||||
|
- invalidation.
|
||||||
|
|
||||||
|
These are trigger conditions, not current requirements or roadmap commitments.
|
||||||
|
|
||||||
|
## Gate B freeze proof
|
||||||
|
|
||||||
|
- No schema or persistence code is changed by this decision.
|
||||||
|
- No new persistent identity is introduced.
|
||||||
|
- No Track Model or Track Builder contract is changed.
|
||||||
|
- No bundle or migration is introduced.
|
||||||
|
- Governor ownership remains limited to execution budgets.
|
||||||
|
- Project DB remains v16.
|
||||||
|
|
||||||
|
Therefore Gate B remains **PASS / FROZEN**.
|
||||||
|
|
||||||
|
## Open questions
|
||||||
|
|
||||||
|
None block the current decision. Future viewer, dense reconstruction, artifact
|
||||||
|
reconciliation or GPU residency requirements must be evaluated independently
|
||||||
|
when their implementations become concrete. Future questions do not create
|
||||||
|
current implementation requirements.
|
||||||
|
|
@ -119,5 +119,10 @@ orphelins.
|
||||||
**IMPLEMENTED** — Feature Store et Visual Index peuvent relier visuellement
|
**IMPLEMENTED** — Feature Store et Visual Index peuvent relier visuellement
|
||||||
des images de ScanSets différents sans dépendre de leur nom ou ordre.
|
des images de ScanSets différents sans dépendre de leur nom ou ordre.
|
||||||
|
|
||||||
**PLANNED** — paires candidates, matching, tracks, SfM, MVS et relations
|
**IMPLEMENTED** — paires candidates, matching, vérification géométrique et
|
||||||
géométriques entre ScanSets.
|
Track Model / Track Builder v1 peuvent consommer le catalogue et ses assets.
|
||||||
|
Les primitives géométriques Sparse SfM sont implémentées par Gate C.
|
||||||
|
|
||||||
|
**PLANNED** — solveur Sparse SfM complet, MVS et relations géométriques entre
|
||||||
|
ScanSets. La vérification/scrub des assets et la réconciliation globale restent
|
||||||
|
également NOT_YET_WIRED.
|
||||||
|
|
|
||||||
|
|
@ -4,7 +4,7 @@
|
||||||
|
|
||||||
- **IMPLEMENTED v1A** : ORB coarse stable, SIFT/RootSIFT OpenCV 5, Feature File
|
- **IMPLEMENTED v1A** : ORB coarse stable, SIFT/RootSIFT OpenCV 5, Feature File
|
||||||
v2 F32×128, grille/coverage, tâches récupérables et consolidation intra-image.
|
v2 F32×128, grille/coverage, tâches récupérables et consolidation intra-image.
|
||||||
- **PLANNED** : Candidate Pair Generator et matching précis.
|
- **IMPLEMENTED** : Candidate Pair Generator, matching précis et vérification géométrique.
|
||||||
- **PLANNED / BLOCKED** : ALIKED, en attente de provenance modèle et d'un export
|
- **PLANNED / BLOCKED** : ALIKED, en attente de provenance modèle et d'un export
|
||||||
ONNX reproductible validé contre un oracle upstream.
|
ONNX reproductible validé contre un oracle upstream.
|
||||||
|
|
||||||
|
|
@ -47,11 +47,12 @@ Lardon3D suit une feuille de route ordonnée qui privilégie la stabilité et la
|
||||||
### Phase 4 : Pipeline avancé
|
### Phase 4 : Pipeline avancé
|
||||||
- ✅ Feature Store v1/v2, ORB, SIFT/RootSIFT et consolidation intra-image
|
- ✅ Feature Store v1/v2, ORB, SIFT/RootSIFT et consolidation intra-image
|
||||||
- ✅ Visual Index v1 segmenté et persistant
|
- ✅ Visual Index v1 segmenté et persistant
|
||||||
- 📋 Candidate Pair Generator
|
- ✅ Candidate Pair Generator
|
||||||
- 📋 Matching et vérification géométrique
|
- ✅ Matching et vérification géométrique
|
||||||
- 📋 Tracks et SfM
|
- ✅ Track Model / Track Builder v1
|
||||||
|
- 🔄 Sparse SfM : primitives géométriques Gate C implémentées ; solveur complet planifié
|
||||||
|
|
||||||
### Phase 5 : Reconstruction
|
### Phase 5 : Reconstruction (PLANNED)
|
||||||
- 📋 Reconstruction incrémentale
|
- 📋 Reconstruction incrémentale
|
||||||
- 📋 MVS / dense
|
- 📋 MVS / dense
|
||||||
- 📋 Mesh
|
- 📋 Mesh
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue