Qualify opt-in JSONNavigation public product candidate

AGENTS.md

@@ -4,11 +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 experimental without a public product until its N1 release gate.
+  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/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

@@ -1,3 +1,9 @@
+# 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

Documentation/Architecture/StructuralIntelligence/N1Promotion.md

@@ -0,0 +1,32 @@
+# N1 public-product candidate decision
+
+Approved for implementation: preserve all 56 existing public declarations, now
+resolvable as the opt-in JSONNavigation library product. N1PublicAudit.json lists
+the source-aware per-declaration decisions. New visibility is additive; this is
+not a package version, merge approval or a published release.
+
+The immutable traversal captures its source; paths describe that source, not a
+replacement. Mutable options configure each independent invocation. Selection
+indices and occurrence ordinals retain their zero-based, first-examined semantics.
+Filters affect emission; coverage is per occurrence rather than a union proof.
+Errors/cancellation throw; callback computation and retained copies are caller work.
+Package read scopes, state, meters and qualification observers remain hidden.
+
+P07 decision: keep the existing source-admission-before-depth/record-validation
+precedence. An oversized source can therefore report its admission resource error
+before an invalid option. Small-source invalid options report configuration errors.
+No error precedence is changed during promotion. N2 sampling configuration has a
+separate pre-admission check because it is a new contract.
+
+Public SwiftPM consumer Debug/Release, isolation negatives, docs, all platform
+lanes and Git-free reproduction must qualify the final source before recommending
+release readiness. Actual outcomes accompany the return; this document is an API
+review decision, not a claim that unfinished qualification has passed. Draft #34
+and the immutable N1 anchor remain untouched. No PR-ready/merge/release transition.
+
+A0 is independently blocked in the separate e11f93f borrowing spike: Apple Swift6.4
+accepts an escaping borrowed capture at type checking and aborts in SILGenCleanup
+during full compilation. A compiler crash is not a valid negative proof. No borrowed
+context or JSONInspection code is included in this product candidate. Its executor
+is byte-identical to the reviewed N1 anchor. The return preserves exact reproducer
+commands, positive/runtime results and failed diagnostic outcomes.