Complete Navigation V1 snapshots and public tree/sparse-table projections

AGENTS.md

@@ -42,4 +42,5 @@ Documentation/Architecture before changing behavior.
   user instruction. Preserve unrelated changes.
 
 Scalar scanning and immutable plan-local regex sharing are selected private
-optimizations. Projection and JSON text-sequence framing remain deferred.
+optimizations. Source-attached N3 snapshots and P1 tree/sparse-table projections live in JSONInspection.
+P2 graph/store/set/matrix/retrieval/persistence and JSON text-sequence framing remain deferred.

Documentation/Architecture/ExtractionManifest.json

@@ -299,7 +299,10 @@
     "1.6 S3 G7 seeded grammar, scalar-key permutation tests, public replay consumer and strict cardinality/matrix harness are original Apache-2.0 contributions. The 64-schema authored fixture has SHA-256 cb55604183a6db7df5fa968db283e7abeae794277d2b0cef033b0bdb92e615cb. Independent python-jsonschema 4.26.0 is research qualification only, with exact numeric binding; no Python runtime dependency or copied validator/engine is distributed.",
     "1.6 S3 G8 materializes the unchanged synthetic corpus per caller access, replacing process-lifetime stored JSON payloads exposed by Linux ASan/LSan. The public process-lifetime consumer and strengthened exact/value-copy test are original Apache-2.0 qualification code; no suppression, runtime fallback, new dependency or corpus/digest change is introduced.",
     "Composition reference-load fixtures, serial descriptor staging, public-only adapter, capacity/terminal tests and strict CI receipt checks are original Apache-2.0 code. Generated JSON graphs introduce no upstream protocol fixtures, engine or dependency. Core public APIs, finite profiles and accounting weights are unchanged.",
-    "NAV5 public array-evidence packaging, external consumer and DocC are original Apache-2.0 code. Existing exact shape evidence, exclusive reducer, weights and I01-I17 semantics are unchanged; no upstream engine or dependency is adapted. Promotion is a draft candidate, not a released product."
+    "NAV5 public array-evidence packaging, external consumer and DocC are original Apache-2.0 code. Existing exact shape evidence, exclusive reducer, weights and I01-I17 semantics are unchanged; no upstream engine or dependency is adapted. Promotion is a draft candidate, not a released product.",
+    "NAV5 package-only complete structural snapshot, parent-linked metadata, original source-ownership transfer and S01-S24 synthetic tests are original Apache-2.0 code. The existing read scope admits once; its default public read/traversal/inspection completion behavior is preserved. No persistent identity, upstream algorithm or new dependency is introduced.",
+    "NAV6 snapshot access-level promotion, external consumer, independent 28-record maintainer oracle, terminal-transfer/concurrent lookup proofs and compiled DocC are original Apache-2.0 contributions. No upstream engine, new semantic authority, dependency or additional product is adapted.",
+    "NAV8 current-main N3/P1 reconciliation, minimal public immutable projection API, independent 16-case consumer and DocC/access-control proofs are original Apache-2.0 contributions. NAV7 donor db991c5/bda8aef and packet SHA-256 57ca72cb817272ed466a7cb8810043d56a079190d830ea7b995abd308070f98d retain provenance. No external engine, dependency or product is added."
   ],
   "jsonhtml_export_original_contributions": {
     "license": "Apache-2.0",

Documentation/Architecture/StructuralIntelligence/Inspection.md

@@ -71,5 +71,7 @@ inner cancellation, source coherence and independent shared-source invocations.
 Current native/Linux/WASI/platform receipts must qualify final source; this document
 does not turn an unexecuted lane into a pass. This contract grants no release authority.
 
-Snapshots, persistent indexes, projections, retrieval, BFS, JSONPath, HTML/CLI
-integration, schema inference and numeric matrices remain deferred.
+At the original N2 milestone snapshots/projections were deferred. NAV8 adds
+source-attached snapshots and tree/sparse-table views; see NAV8Completion.md.
+Persistent indexes, retrieval, BFS, JSONPath, HTML/CLI integration, schema inference
+and numeric matrices remain deferred.

Documentation/Architecture/StructuralIntelligence/NAV7SnapshotReconciliation.md

@@ -0,0 +1,21 @@
+# NAV7 dependent snapshot candidate
+
+This draft replays37d84e8..b77d43d onto the NAV7 current-main N2 proposal,
+including #44 DocC index repair and #45 release metadata. Original #42/#43 and
+NAV6 heads remain unchanged. Snapshot source, read-scope ownership designation,
+exclusive context, all original S/V tests,14-case external consumer and compiler
+probe scripts are byte-identical to b77d43d. No algorithm replacement occurs.
+
+JSONInspection remains the one opt-in candidate product:44 Inspection declarations
+plus23 authored snapshot additions, with Navigation56 unchanged. Construction is
+one original scope/admission; a complete immutable snapshot owns one source and
+compact records. Each path/value/span lookup has its own explicit bounded full-
+source admission. Ordinals are local positions, not transferable node handles.
+
+G4 native performance remains HOLD with zero timed snapshot workloads and no
+retry authorization. Logical counters are policy, not RSS, allocation count or
+speed. This source requires fresh Debug/Release/ASan/TSan/strict, ownership/public
+negative codegen, external consumer, DocC/site, Linux, WASI/WasmKit, SDK and archive
+proofs. Actual outcomes are source-bound in the private NAV7 return; this document
+does not invent a pass. No merge, ready transition, release or public projection
+is authorized. P1 private experiments remain a separate conditional branch.

Documentation/Architecture/StructuralIntelligence/NAV8Completion.md

@@ -0,0 +1,107 @@
+# Navigation V1 completion on development main
+
+NAV8 starts at development main `e0a4185477047d92e4b8e1a2b56303848472d9be`
+on `feature/json-navigation-v1-completion`, proposed in
+[PR #59](https://github.com/ThorFuchs/Swift-JSON/pull/59). Published 1.6.1 at
+`e431f157ececc0cf3d061192420b0e36a9062f83` remains immutable and has no Inspection.
+This is unreleased 1.7.0-dev source, with the same ten products/nine libraries.
+No version/tag/publication or sibling feature is part of this integration.
+
+## Source reconciliation and semantic owners
+
+N1 walker/reducer and N2 shape source blobs are identical on starting main and
+NAV7's final P1 donor. They are retained rather than replayed. Only the missing
+N3 increment (`db991c51dc15e8e47a0356a66ae7e03f4ed51b98` relative to
+`258a23eb01cd0cbcc702c0a2550d35ff05f4881d`) and P1 increment
+(`bda8aef4c8347ac4f6f2d7264c4be244367e4869` relative to `db991c5`) are adapted.
+Original NAV7 stacked drafts remain evidence, not integration bases.
+
+| Operation | Sole existing semantic authority | Budget boundary |
+| --- | --- | --- |
+| Snapshot build | Navigation's exclusive mutating-inout owned reducer, original read scope/admission | One full physical-root invocation; finalize all ranges before one-shot source transfer |
+| Tree build | Same owned executor plus sealed snapshot topology | New full-source admission; charge retained snapshot alias and view; no new DOM |
+| Tree metadata | Snapshot's checked `record(at:)` after selected-interval bounds | Fixed trusted metadata read; no owned growth/report |
+| Tree child/subtree catalogue | Same owned executor, finalized physical ranges | Separate whole-source invocation, charged output slots; cap refusal throws |
+| Tree location/value/span | Exactly one existing snapshot lookup | Separate full-source admission; original typed selection/map; no hidden nested operation |
+| Sparse table build | Same exclusive reducer and original exact key comparison | One complete row pass and cumulative ledger including finalization/source transfer |
+| Sparse cell | Original core read scope, selection, object lookup/scalar comparison | New explicit full-source admission; no construction remainder or null-on-error |
+
+The two package-only transfer hooks extend completion accounting only for a
+source-owning result. Ordinary core read/visit/collect/N2 completion does not
+designate transfer and retains its original refunds/statistics. No borrowed
+callback, escaped cursor, second meter, normalized key/value or new concurrency
+authority is introduced. The historical Swift 6.4 nonmutating-borrow codegen bug
+is not declared fixed; full positive/negative exclusive-inout codegen remains.
+
+## Deliberate public P1 decision
+
+Promote the checked `JSONTreeProjection` factory, immutable snapshot/root/end,
+metadata/catalogue and delegated location/value/span methods. Promote the checked
+`JSONSparseTableProjection` factory, immutable source/selection/row count/columns/
+traversal and tri-state `cell` lookup. Expose typed `JSONProjectionFailure` cases.
+Keep initializers fileprivate, sparse offsets/member references package-only,
+and accounting/reducers internal. This is a small surface within JSONInspection,
+with no extra product, umbrella facade, setter or rival path model.
+
+Bare Int positions are intentionally consistent with N3's existing snapshot-local
+ordinal contract. A captured immutable owner enforces source attachment and range;
+it cannot diagnose accidental reuse of an in-range integer from another snapshot.
+There is no detached identity or public replacement-source argument. A stronger
+token type is deferred rather than implying provenance that this API cannot prove.
+
+All table rows must be objects. Prefix evidence does not certify a suffix. Empty
+arrays are 0-by-0; empty objects remain rows. Columns retain first-seen exact scalar
+identity; missing/null/value stay distinct. Row admission is complete even when
+descendant traversal coverage is restricted. Constructors never publish partial
+artifacts after wrong kind, missing target, quota, cancellation or terminal error.
+
+No Navigation or original N2 declaration changes. N3 preserves its original 23
+public additions; P1's precise promoted declaration fragments are audited from
+the actual Swift 6.4 compiler graph. Public usage and costs appear in the
+[compiled guide](../../../Sources/JSONInspection/Documentation.docc/StructuralProjections.md)
+and [independent SwiftPM consumer](../../../Tools/ProjectionQualification).
+
+## Qualification and review boundary
+
+Original I01–I17, S01–S24/promotion, P01–P32 and pinned independent fixtures remain.
+The public consumer adds 16 named scenarios each in Debug/Release/ASan, three
+compiled guide blocks/configuration and 18 ordinary external full-codegen
+rejections. Private compiler cases are retained, replacing the now-obsolete
+public-type-invisibility negatives with sparse-storage/accounting/reducer
+invisibility negatives. No former invariant or behavior assertion is removed.
+The receipt harness rejects missing/duplicate/renamed cases, zero counters,
+incidental diagnostics, compiler crashes and incomplete command inventories.
+
+Current discovery is 76 Inspection functions, 779 native/763 Linux/675 WASI root
+functions, unchanged 325/288 parameter invocations and 51/50 shared functions.
+All 49 core metric witnesses and 126 maintenance identities remain mandatory.
+These are required inventories, not claims of unexecuted qualification. Final
+source-bound native/safety/docs/Git-free reproduction, both Linux architectures,
+full Node WASI, limited direct Inspection WasmKit, Apple SDK compile/link,
+external consumer and source/API/protection receipts accompany this PR.
+SDK compilation is not mobile runtime; limited WasmKit is not full-root support.
+
+The source/public API review compares canonical donor algorithms, final compiler
+fragments, exact fixtures and independent public consumers. Human owner review
+and a fresh protected-main/check/thread lease remain prerequisites to merge;
+historical green receipts cannot qualify this combined source.
+
+## Resource and performance disposition
+
+Published 49 profiles/metrics remain unchanged. Additional finite bounds and
+logical weights are those in the compiled guide and original P1 proof record.
+Every reservation precedes growth and every owned loop is cumulative/cancellable.
+Source aliases incur logical ownership even when physical COW shares storage.
+No bound on caller instructions, physical heap, RSS or allocator behavior follows.
+
+G4 controlled performance remains **HOLD**, with zero accepted timing samples.
+The owner explicitly permits this correctness/platform-qualified integration
+with that HOLD and **no performance claims**. G4 blocks speed claims, not this
+specific guarded merge; other semantic/API/compiler/platform/protection gates
+are unchanged. There is no benchmark PASS, shifted threshold or inferred speedup.
+Snapshot build remains depth-sensitive; repeated lookups re-admit the full source;
+linear first-seen column scans may be quadratic. No EngineBench claim is made.
+
+Persistence, global/durable indexes, graph/store/set/matrix, retrieval, BFS,
+JSONPath/query grammar, HTML/CLI additions and unrelated DSL/composition/developer
+kit work remain out of this completion train.

Documentation/Architecture/StructuralIntelligence/NAV8Progress.json

@@ -0,0 +1,31 @@
+{
+  "schema_version": 1,
+  "base": "e0a4185477047d92e4b8e1a2b56303848472d9be",
+  "branch": "feature/json-navigation-v1-completion",
+  "pr": 59,
+  "N1_N2": "Already on main; implementation and authored declarations unchanged",
+  "N3_checkpoint": "09e85f6: focused six-command inspection lane passed 44 cases each Debug/Release/ASan, strict memory and 2-positive/20-negative full codegen",
+  "P1_private_checkpoint": "931c042: original donor algorithms/P01-P32 fixtures restored separately",
+  "P1_public": "28 deliberately promoted declarations within JSONInspection; independent 16-case consumer,18 negative full-codegen outcomes and3 DocC fences/config passed in initial proof",
+  "expected_final_public": {
+    "Navigation": 56,
+    "Inspection": 95,
+    "package_authored": 1172
+  },
+  "full_final_source_qualification": "Required; read exact PR/checkpoint receipts rather than infer a pass from this planning status",
+  "G4": {
+    "status": "HOLD",
+    "accepted_timing_samples": 0,
+    "owner_classification": "blocking for speed claims; explicitly nonblocking for correctness/platform-qualified NAV8 guarded merge"
+  },
+  "release_action": "Not authorized; remains unreleased1.7.0-dev",
+  "deferred": [
+    "P2",
+    "persistence",
+    "retrieval",
+    "BFS",
+    "matrix/graph/store/set",
+    "CLI/HTML",
+    "unrelated sibling work"
+  ]
+}

Documentation/Architecture/StructuralIntelligence/P1PrivateProjections.md

@@ -0,0 +1,90 @@
+# NAV7 P1-A private projection proof
+
+Status: isolated package-only experiment, no new target or product, no merge/
+release/public-API approval. JSONInspection hosts the proof beside its immutable
+snapshot. A separate JSONProjections module would add an interface solely for
+private reuse; this wave needs no additional module boundary. N1/N2/N3 code and
+public declarations remain unchanged. Exact compiled declarations/proofs are
+recorded in the NAV7 return, not inferred from this design note.
+
+## Source and API
+
+`JSONTreeProjection.build(snapshot:rootOrdinal:limits:)` accepts a complete sealed
+snapshot and returns a view of an original physical interval. It stores that
+snapshot, selected root ordinal and finalized end only. Root metadata keeps its
+original parent/depth; no synthetic root/value/DOM is constructed. Ordinary fixed
+`record(at:)` reads have no new owned growth/report. `children` and `subtreeOrdinals`
+are new bounded catalogue operations with an inclusive100000-record default; they
+reject insufficient caps and never publish truncation. Direct children jump
+finalized subtree ends. `location`, `value`, `sourceSpan` validate local view bounds,
+then delegate exactly once to the existing independent N3 operation.
+
+Every tree build/catalogue invocation uses the established N1 exclusive reducer,
+one original read scope and complete captured-source admission. Root-only traversal
+reuses already-proven complete snapshot topology; it does not rebuild the tree or
+continue the completed snapshot build's meter. Snapshot/row ordinals are local
+positions, not portable identifiers. A bare Int can be reused as a position in
+another source, but this API accepts no replacement source or detached node handle.
+
+`JSONSparseTableProjection.build(document:at:limits:maximumRows:maximumColumns:
+maximumPresentCells:)` selects one existing array. Every row must be object or a
+`nonObjectRow(at:kind:)` error identifies the exact physical row. Full source
+admission precedes success, including unselected input. Empty0x0 is explicitly
+allowed; `[{},{}]` is2x0. Positive N2 prefix evidence cannot admit an unseen suffix.
+Rows remain original array indices, including equal rows. JSONKey columns follow
+first encounter in source member order. Sparse member/column ordinal references
+and nondecreasing row offsets retain empty rows without a dense null grid.
+P27's offsets can be equal for empty rows; demanding strict increase would
+contradict P18. Each nonempty row advances the offset.
+
+`cell(row:column:limits:)` is a separate original-source-admitted read operation.
+It charges row-reference scans and delegates key/presence to core JSONObject
+lookup/comparison. It returns canonical JSONPresence absent/null/value, preserves
+arrays/objects/exact numbers/lexemes, and throws for bad bounds or inconsistent
+metadata. It stores no per-cell JSON/path/span, normalizes no key and converts no
+number. Wrong type, missing selection, nonobject, operational failure and null
+remain distinct. The captured immutable source cannot be rebound.
+
+## Finite accounting policy v1
+
+All49 core profiles/caps are unchanged. Additional inclusive defaults are100000
+rows,10000 columns and1000000 present members; negative configuration fails before
+admission. Tree catalogue default is100000 records. Arithmetic products and count
+increments are checked before growth. Each scan, key comparison, finalization
+step, returned slot and key alias is charged on the original invocation ledger.
+Unexpected capacity/resource/cancellation failures throw without successful output.
+
+Logical output overlays, plus core source/selection costs:
+
+- Tree view:64 descriptor +128 snapshot header +96 per retained record alias and
+  exact UTF8 edge-key bytes. COW sharing does not erase logical alias ownership.
+- Catalogue:32 header +8 per ordinal;96 temporary record bytes are refunded.
+- Table:256 summary +8 per offset +64 per column plus exact UTF8 key bytes +16 per
+  present member reference. A complete source ownership transfer occurs once.
+
+These are declared logical weights, not MemoryLayout, allocation bytes or RSS.
+Sparse slots are O(rows+columns+present members); exact linear column scans may
+be quadratic. Tree build/lookup costs still include full source/map admission;
+N1/N3 path reconstruction remains depth-sensitive. No time, RSS, throughput or
+scalability improvement is claimed. G4 remains HOLD with zero timed workloads.
+
+## Proof and boundaries
+
+32 Swift Testing identities cover all P01–P32 obligations and independent packet
+oracles, exact keys/pointers/presence, deep16/64/256 and wide1024 trees, sparse
+1/16/1024/10000 rows, core differentials, inclusive caps/work/retention, checked
+overflow,16 concurrent mixed-success/failure views and cells, actual source
+retention, legacy statistics parity, source replacement and post-finalization
+terminal priority. Cancellation is exercised inside long key scans, offset
+finalization and after source transfer; scope root/state invalidation is observed.
+No deallocation of caller aliases or process-memory bound is claimed.
+
+The compiler qualifier requires ordinary primary diagnostics in Debug/Release:
+external packages cannot name the package types; even same-package code cannot
+forge a tree via its file-private initializer or mutate table source/columns.
+Original ownership2-positive/20-negative and public Snapshot18-negative probes
+remain separate. The full supported native/safety/docs/portable/SDK/archive lanes
+must bind to final source. SDK builds do not establish device/simulator runtime.
+Public projection surfaces, batching, persistence, durable identity, query DSL,
+BFS/matrix/graph/retrieval, mutation, renderer/CLI integration and EngineBench are
+future owner gates. No release version is assigned by this prototype.