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
|
||||
- **Task** : moteur de tâches avec pause/reprise, annulation et séquences
|
||||
- **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 Verifier v1** : Fundamental USAC/MAGSAC, reprise et lots resource-aware
|
||||
- **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)
|
||||
- [Backend Vulkan ORB](docs/architecture/vulkan_matcher.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)
|
||||
|
||||
### 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,
|
||||
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
|
||||
restent sur OpenCV L2. DAG générique, Tracks, SfM et viewer restent des tickets
|
||||
séparés planifiés.
|
||||
restent sur OpenCV L2. Track Model/Builder et les primitives géométriques Sparse
|
||||
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
|
||||
|
||||
|
|
|
|||
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
|
||||
des images de ScanSets différents sans dépendre de leur nom ou ordre.
|
||||
|
||||
**PLANNED** — paires candidates, matching, tracks, SfM, MVS et relations
|
||||
géométriques entre ScanSets.
|
||||
**IMPLEMENTED** — paires candidates, matching, vérification géométrique et
|
||||
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
|
||||
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
|
||||
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é
|
||||
- ✅ Feature Store v1/v2, ORB, SIFT/RootSIFT et consolidation intra-image
|
||||
- ✅ Visual Index v1 segmenté et persistant
|
||||
- 📋 Candidate Pair Generator
|
||||
- 📋 Matching et vérification géométrique
|
||||
- 📋 Tracks et SfM
|
||||
- ✅ Candidate Pair Generator
|
||||
- ✅ Matching et vérification géométrique
|
||||
- ✅ 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
|
||||
- 📋 MVS / dense
|
||||
- 📋 Mesh
|
||||
|
|
|
|||
Loading…
Reference in a new issue