From 7872bc82aedda8df6c192c9f2b8bcfdc54e314b5 Mon Sep 17 00:00:00 2001 From: fy59 Date: Mon, 10 Aug 2026 13:51:54 +0200 Subject: [PATCH] docs: freeze resource architecture boundary --- README.md | 9 +- docs/architecture/resource_boundary.md | 251 +++++++++++++++++++++++++ docs/concepts/scan_sets.md | 9 +- docs/roadmap/roadmap.md | 11 +- 4 files changed, 270 insertions(+), 10 deletions(-) create mode 100644 docs/architecture/resource_boundary.md diff --git a/README.md b/README.md index f8049d3..ab3f51b 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/docs/architecture/resource_boundary.md b/docs/architecture/resource_boundary.md new file mode 100644 index 0000000..90c54bc --- /dev/null +++ b/docs/architecture/resource_boundary.md @@ -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. diff --git a/docs/concepts/scan_sets.md b/docs/concepts/scan_sets.md index eff4942..667b000 100644 --- a/docs/concepts/scan_sets.md +++ b/docs/concepts/scan_sets.md @@ -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. diff --git a/docs/roadmap/roadmap.md b/docs/roadmap/roadmap.md index c341db6..7dda0fa 100644 --- a/docs/roadmap/roadmap.md +++ b/docs/roadmap/roadmap.md @@ -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