Integrate opt-in Navigation on composition-enabled main

AGENTS.md

@@ -4,10 +4,11 @@ Swift-JSON requires Swift tools/compiler 6.4+, Swift language mode 6 and
 macOS/SDK 27+. Read README.md, CONTRIBUTING.md and the relevant contracts in
 Documentation/Architecture before changing behavior.
 
-- Keep seven public products: JSON, JSONSchema, JSONStreaming, JSONPatch, JSONHTML,
-  JSONBridges and the swift-json executable. JSONFilterRuntime and JSONCLIEngine are package-private.
+- Keep eight public products: JSON, JSONSchema, JSONStreaming, JSONPatch, JSONHTML,
+  JSONBridges, JSONNavigation and the swift-json executable. JSONFilterRuntime and JSONCLIEngine are package-private.
   JSONHTML and opt-in JSONBridges depend on JSON only; core never re-exports the bridges.
   The approved CLI and E2 additions preserve historical product contracts.
+  JSONNavigation is an opt-in product candidate depending on JSON only; merge/release remain human-gated.
   JSONRegexRuntime is package-private. Root package dependencies remain empty.
 - Preserve exact bounded decimals, decoded Unicode scalar identity, ordered
   objects with order-independent equality, one strict UTF-8 grammar, native

CHANGELOG.md

@@ -170,3 +170,12 @@ remain unselected; projection and RFC 7464 framing remain deferred.
   timing sleeps; retain an invocation-local package-only checkpoint observer.
 - Qualify twenty frozen explicitly rooted downstream schema vectors and public
   cumulative budgets in a separate consumer; no protocol/runtime dependency added.
+
+## Unreleased Navigation candidate
+
+- Propose opt-in JSONNavigation as an eighth SwiftPM product, preserving its56
+  exact traversal declarations and cumulative resource semantics.
+- Qualify a real external Debug/Release SwiftPM consumer and preserve source-first
+  error precedence with two explicit regressions.
+- N2 inspection remains unimplemented: its separate borrowed-context compiler
+  proof is blocked. No version/tag/release or automatic merge is implied.

Documentation/Architecture/API.md

@@ -1,14 +1,15 @@
 # Public API contract
 
 This document describes the implemented public interface. Native compiler symbol
-graphs supply the complete declarations in the six DocC catalogs. Examples
+graphs supply the complete declarations in the seven DocC catalogs. Examples
 in the [README](../../README.md) are compiled and executed by the public consumer.
 
 ## Products and ownership
 
 | Product | Main entry points | Owned implementation boundary |
 | --- | --- | --- |
 | JSON | JSON, JSONNumber, JSONObject, JSONParser, JSONWriter, JSONValueEncoder, JSONValueDecoder, JSONPointer, JSONDocument | Shared strict codec, exact decimal model, bounded traversal and native coding |
+| JSONNavigation | JSONTraversal, JSONTraversalScope, JSONTraversalOptions | Exact many-node DFS, strict physical/virtual scopes, bounded metadata and explicit coverage; one core read-scope meter |
 | JSONBridges | BinaryInteger.jsonNumber, FixedWidthInteger/Double/Decimal.init(jsonNumber:), Double.jsonNumberFromRoundTripText | Optional one-delegate numeric conversions; explicit fidelity, no new authority |
 | JSONSchema | JSONSchemaDocument, JSONSchemaRegistry, JSONSchemaCompiler, CompiledJSONSchema, JSONSchemaValidator | Offline immutable plan, invocation-owned evaluation and private native regex |
 | JSONStreaming | JSONEventSequence, JSONValueSequence, NDJSONValueSequence, JSONTopLevelArraySequence, JSONAsyncWriter | Exclusive pull state, shared codec, strict framing and awaited handoffs |
@@ -17,7 +18,7 @@ in the [README](../../README.md) are compiled and executed by the public consume
 | JSONHTML | JSONHTMLRenderer, JSONHTMLRenderingOptions, JSONHTMLLimits, JSONHTMLRenderReport, JSONHTMLAnnotation, JSONExportDocument, JSONExportOptions, JSONExportReport | Structured forms/cards and bounded native previews, exact HTML, native Apple transfer, immutable prepared JSON/text/Markdown/static HTML/opt-in styled RTF and cumulative budgets |
 
 JSON imports no siblings. JSONSchema depends on JSON and package-private
-JSONRegexRuntime. Streaming, Patch, HTML and Bridges depend on JSON. There are seven public products: six libraries and the swift-json executable,
+JSONRegexRuntime. Streaming, Patch, HTML and Bridges depend on JSON. There are eight candidate public products: seven libraries and the swift-json executable,
 and no external root-package dependencies. No HTTP, MCP or documentation-tool dependency is introduced. JSONHTML conditionally
 uses Apple SDK frameworks for explicit native transfer/PDF preparation; the portable
 value, schema, Patch and streaming contracts do not acquire UI semantics.
@@ -244,3 +245,5 @@ includes `revisionKind: "source-sha256"` and `revision: "sha256:<hex>"`. This is
 SHA-256 of the ordered Package.swift plus Sources content manifest, excluding only
 the generated identity file itself. It is not a Git commit, binary digest or claim
 of publication. Generation/checking needs no Git, time, environment or network.
+
+JSONNavigation product promotion preserves all 56 N1 public declarations and resource semantics. Full-source admission precedes invalid depth/record-option validation, including oversized sources; N1Promotion.md records this preserved precedence. JSON imports no Navigation symbols implicitly.

Documentation/Architecture/CompositionQualification.md

@@ -3,7 +3,8 @@
 The synchronous borrowed composition API is described in
 [Compose native operations](../../Sources/JSON/Documentation.docc/Composition.md).
 Its public surface and default profiles are unchanged by this qualification work.
-The root dependency graph remains empty and the package retains seven products.
+The root dependency graph remains empty and the package retains the existing products and adds opt-in JSONNavigation after its
+separate public-product gate.
 
 The separate [qualification package](../../Tools/CompositionQualification) exercises
 source-backed parsing, exact Pointer targets, URI identity and explicitly charged
@@ -62,7 +63,7 @@ Run python3 Scripts/ci.py --lane composition on the supported native or Linux
 runner. The lane requires 12 core functions in each build mode, separate public
 consumers, five external Swift Testing functions in Debug/Release/ASan, all eight
 scale cells and 11 compiler rejection cases. Exact module/cardinality checks
-reject missing tests and misclassified resource failures. The 558 native / 542
+reject missing tests and misclassified resource failures. The reconciled 597 native / 581
 Linux root functions, 325 parameter invocations, restored identities and 49 public
 metric probes retain their existing contracts.
 

Documentation/Architecture/ExtractionManifest.json

@@ -261,7 +261,8 @@
     "Tests/Fixtures/CLI/NewCases.json is the byte-identical 111-case authored CLI briefing fixture, SHA-256 6f863f3e98d2dea12e59018e7cf3a074ae0ebee5f1ab950a651df72e5eb18a4c. Fixture expected JSON texts use native exact comparison, not a floating-point oracle. The query compiler/VM and lifetime ledger are original Apache-2.0 implementations; no legacy eager evaluator or jq implementation is copied.",
     "JSONHTML typed annotations, iterative exact-path binding, static/interactive attachment and coherent JSONDocument span presentation are original Apache-2.0 code. No schema engine, third-party renderer, source archive or new dependency is adapted.",
     "Structured forms/cards, finite prefix/preview staging, closed inline scanner, atomic mini-math MathML emitter, canonical PNG/JPEG header admission and line/media-bounded PDF pagination are original Apache-2.0 code. The approved structured concept informed the fixed CSS/JS; no demo Site content or external parser/renderer/codec engine is distributed.",
-    "Experimental synchronous composition facade and its monotone external reservations are original Apache-2.0 implementations reusing native meter, admission, codec, Pointer and URI helpers. Contract tests concretize a maintainer-provided research scaffold; private packet evidence is excluded from source distribution. No third-party semantic engine or dependency is adapted. Compiler substitution fixtures materialize maintainer-provided R1 public-interface review cases, including exact work, retention and caught-failure restoration probes."
+    "Experimental synchronous composition facade and its monotone external reservations are original Apache-2.0 implementations reusing native meter, admission, codec, Pointer and URI helpers. Contract tests concretize a maintainer-provided research scaffold; private packet evidence is excluded from source distribution. No third-party semantic engine or dependency is adapted. Compiler substitution fixtures materialize maintainer-provided R1 public-interface review cases, including exact work, retention and caught-failure restoration probes.",
+    "Experimental N0/N1 JSONNavigation is original Apache-2.0 Swift: iterative traversal and explicit overlap policy reuse unchanged core read-scope/admission/path/meter authorities. No historical navigation/query algorithm or additional dependency is adapted. Three maintainer-provided synthetic S1 JSON fixtures are copied unchanged; their packet and file SHA-256 pins are in Tests/JSONNavigationTests/Fixtures/Provenance.json. Public product promotion remains gated."
   ],
   "policy": "Record actual adaptations and retain applicable upstream copyrights and licenses. Reference inputs and comparison experiments are not distributed runtime dependencies.",
   "original_notes": [

Documentation/Architecture/Linux.md

@@ -1,3 +1,11 @@
+# N1 candidate platform scope
+
+This additive candidate proposes JSONNavigation as an eighth product (seven
+libraries plus CLI), with no external dependencies. Its public SwiftPM consumer
+and39 Navigation functions join the unchanged Linux lanes. Both actual ARM64 and
+x86_64 full/safety receipts are required for final qualification. The historical
+platform text below describes the original seven-product implementation.
+
 # Linux platform contract
 
 The six libraries and swift-json executable are qualified for 64-bit

Documentation/Architecture/StructuralIntelligence/API-DECISIONS.md

@@ -0,0 +1,112 @@
+# Historical N0/N1 decision record
+
+This records the experimental4403b9a anchor. The current public-product candidate
+is described in [N1Promotion.md](N1Promotion.md); the original decisions below
+retain their historical source context.
+
+# N1 exact traversal decisions
+
+Scope is N0/N1 only. JSONNavigation depends exclusively on JSON and currently has
+no public SwiftPM product. The seven existing products and empty external graph
+remain the manifest acceptance contract. Core, schema, Patch, streaming, bridge,
+filter/query and renderer behavior is unchanged. The generated CLI source-identity
+stamp must refresh when Package.swift/Sources change; this mechanical integration
+update adds no CLI behavior, command, language or version change.
+
+## Actual experimental declarations
+
+- `JSONTraversal(document:limits:)` captures one immutable JSONDocument.
+- `visit(scope:options:_:)` takes `(JSONTraversalHit, JSON) throws -> JSONTraversalAction`
+  and returns `JSONOperationReport<JSONTraversalSummary>`.
+- `collect(scope:options:maximumRecords:)` uses that same internal execution authority
+  and returns `JSONOperationReport<JSONTraversalCollection>`.
+- `JSONTraversalScope.subtree(at:)` and `.virtual(roots:overlap:)` select absolute
+  existing typed paths. Virtual defaults to `.rejectAmbiguous`.
+- `JSONScopeOverlapPolicy`: rejectAmbiguous, orderedOccurrences, uniquePhysicalNodes.
+- `JSONTraversalAction`: continue, skipDescendants, stop.
+- `JSONTraversalOptions`: depthLimit, includeScopeRoot, emitKinds, includeSourceSpans.
+- `JSONTraversalHit`: absoluteLocation, scopeRootIndex, occurrenceIndex, relativeDepth,
+  kind and optional coherent sourceSpan. It contains no JSON subtree or cursor.
+- `JSONTraversalSummary`: visitedCount, emittedCount, maximumDepthVisited,
+  scopeRootCount, deduplicatedCount, prunedSubtrees, depthLimitedSubtrees, completion.
+- `JSONTraversalCompletion`: complete, restricted, visitorStopped.
+- `JSONTraversalFailure`: collectionLimitExceeded(limit:), ambiguousRoots(first:second:).
+
+The [DocC guide](../../../Sources/JSONNavigation/Documentation.docc/Traversal.md)
+contains three externally compiled/executed before/after examples. The actual
+[consumer](../../../Tools/NavigationQualification/Consumer.swift) uses public JSON
+and Navigation declarations, not package meters. Its external-module compiler
+probes check core import isolation, hidden meters, non-Sendable cursor rejection
+and absence of a fabricated missing kind in both build configurations.
+
+## Exactness and coverage
+
+DFS preorder is the only order offered: object insertion and increasing array
+positions. Depth counts edges from each selected root. Full source admission is
+mandatory even for a scalar selection, depth zero, filtered-empty selection or
+early stop. Root omission/kind filtering changes emission only. Pruning/depth
+omission marks coverage restricted, and explicit stop marks visitorStopped. Errors
+and cancellation throw. Reports are conservative per-occurrence coverage, not a
+union-coverage proof or a global absence query.
+
+All virtual roots resolve before any callback. Reject mode then checks every pair
+for equal or ancestor/descendant typed prefixes. Ordered mode preserves root order,
+then each subtree's DFS, including repeats. Unique mode remembers **first examined**
+typed paths, even excluded/filtered roots, preserving their first depth/origin. It
+still explores revisited descendants under the current occurrence's depth policy.
+Two equal-valued siblings or scalar-distinct keys never merge. A virtual selection
+does not invent a new source root, array index, durable ID or revision fingerprint.
+
+Mapped spans are opt-in core lookups, never synthesized. An unchanged captured old
+document continues to describe its old root after another traversal captures a
+replacement. No record resolves against a caller-supplied newer root automatically.
+
+## Finite policy and implementation costs
+
+All 49 core metrics/profiles/weights remain unchanged. Existing core read-scope
+admission covers root, source bytes/label and source maps. Path records reuse its
+pointer, diagnostic and retention policies. The N1 logical overlay reserves 128
+bytes for summary/staging, 16 for root-list staging, 64 per planned root or frontier
+frame, 64 per ephemeral hit or collected record, and 16 per unique-path reference.
+Retained collected paths additionally charge the published 32-byte indexSlot per
+component and its key UTF-8 bytes. These are logical weights, not allocation/RSS
+measurements; caller-retained callback copies remain caller storage.
+
+Collection has an independent inclusive default of 100,000 records; zero prohibits
+emission but allows a genuinely empty result. Negative bounds/depth reject as
+configuration errors. Its next-record refusal throws a typed traversal capacity
+error and publishes no collection. Source admission uses existing node capacities;
+visits do not misleadingly re-charge source nodes, and work stays cumulative across
+roots, pair scans, dedup, emitted paths, source-span lookups, output and cleanup.
+
+Initial reject/unique modes use exact metered linear comparisons. Pair validation
+and unique-node scans can be quadratic. Core path snapshots along a deep frontier
+can also use quadratic path metadata. The prototype intentionally makes no
+linear-total-time, indexed-lookup, zero-copy or speed claim. Every owned comparison
+loop is cancellable/budgeted, so exhaustion is an operational error, never a partial
+success. A future compact representation/index needs its own measured review.
+
+The invocation and its synchronous scope never escape into a callback. JSONTraversal,
+metadata/options and collected values are checked Sendable; each simultaneous call
+creates its own scope. A package-only nil-by-default checkpoint observer supports
+owned-loop cancellation qualification; no public consumer can install it.
+
+## Qualification and promotion boundary
+
+The reviewed new inventory is 37 nonparameterized Navigation tests, including the
+three pinned synthetic packet documents. Existing function identities and all 325
+native/Linux parameter invocations remain; WASI retains its separate 288. Full roots
+become 583 native, 567 Linux and 479 WASI, and shared-state counts 42/41. All 126
+maintenance identities, corpus policies and 49 cap probes remain required.
+
+`Scripts/ci.py --lane navigation` checks exact focused discovery, Debug/Release,
+explicit strict-memory compilation and external compiler/consumer/DocC probes.
+Native/Linux run the new consumer and full existing suites; safety includes Navigation
+ASan plus its shared-root TSan function. WASI uses the updated exact root inventory.
+Current commands/receipts, failures and platform gaps accompany the return; this
+decision document does not assert a pending platform run passed. Full release-gate
+qualification and explicit product review precede promotion to an installable product.
+
+BFS, scalar-sorted order, prefix snapshots, JSONInspection, classifiers, snapshots,
+semantic/durable digests, projections, editing, retrieval, actors, rendering and CLI
+verbs are explicitly deferred. No EngineBench implementation or performance claim.