Integrate exact array inspection on current main

AGENTS.md

@@ -4,13 +4,14 @@ 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 nine public products: JSON, JSONSchema, JSONSchemaExamples, JSONStreaming,
-  JSONPatch, JSONHTML, JSONBridges, JSONNavigation and the swift-json executable.
+- Keep ten candidate products: JSON, JSONSchema, JSONSchemaExamples, JSONStreaming,
+  JSONPatch, JSONHTML, JSONBridges, JSONNavigation, JSONInspection and the swift-json executable.
   JSONSchemaExamples is opt-in and depends on JSON and JSONSchema only.
   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.
+  JSONNavigation depends on JSON only. Opt-in JSONInspection depends on JSON and
+  JSONNavigation; its candidate promotion remains human-gated. Core re-exports neither.
   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

Documentation/Architecture/ExtractionManifest.json

@@ -17,7 +17,7 @@
       "blob_sha": "25cb8eab982ed0fc41e5f1dde5abeab18113f55e",
       "destination": "Sources/JSON/Value/JSON.swift",
       "disposition": "Six enum case concepts selectively adapted; equality/hash traversal and exact object/key storage rewritten.",
-      "attribution": "Original Thor Fuchs 2024\u20132026 header retained; Reference LICENSE and NOTICE preserved.",
+      "attribution": "Original Thor Fuchs 2024–2026 header retained; Reference LICENSE and NOTICE preserved.",
       "validation": [
         "Tests/JSONTests/ValueTests.swift",
         "Tests/JSONTests/PresenceTests.swift"
@@ -163,7 +163,7 @@
       "blob_sha": null,
       "destination": "Sources/JSONRegexRuntime/RegexUnicodeTables.swift",
       "disposition": "407 immutable tables generated by original deterministic Python generator from fixed Unicode data; no generated Regress table copied. Regeneration compares bytes and provenance.",
-      "attribution": "\u00a9 2020 Unicode, Inc.; Unicode-3.0 copyright/permission notice retained in Licenses/Unicode-3.0.txt.",
+      "attribution": "© 2020 Unicode, Inc.; Unicode-3.0 copyright/permission notice retained in Licenses/Unicode-3.0.txt.",
       "validation": "Byte-equal regeneration and native exact-alias/GC/binary/Script/Script_Extensions/IdentifierName vectors",
       "evidence": "Scripts/ci.py: current native, safety and documentation receipts"
     },
@@ -174,7 +174,7 @@
       "blob_sha": null,
       "destination": "Sources/JSONSchema/Formats/JSONIDNAData.swift and Tests/Fixtures/Unicode/NormalizationTest-13.0.0.txt",
       "disposition": "Original generator derives RFC5892/5893, NFC and UTS46 nontransitional STD3 tables; normalization fixture copied byte-for-byte. No external engine or system Unicode authority.",
-      "attribution": "\u00a9 2019\u20132020 Unicode, Inc.; Unicode-3.0 notice preserved in Licenses/Unicode-3.0.txt.",
+      "attribution": "© 2019–2020 Unicode, Inc.; Unicode-3.0 notice preserved in Licenses/Unicode-3.0.txt.",
       "validation": "18853 normalization cases (94265 native comparisons); 874 independent optional format cases; byte-equal regeneration",
       "evidence": "Scripts/ci.py: current native, safety and documentation receipts"
     },
@@ -284,7 +284,8 @@
     "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 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."
+    "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.",
+    "Experimental exclusive traversal reducer, evidence-only array inspector and I01-I17 synthetic tests are original Apache-2.0 Swift. They reuse the original core read scope, exact key comparison and one cumulative meter; no additional semantic engine, upstream code or dependency is adapted. JSONInspection has no public product and is isolated from Navigation promotion."
   ],
   "policy": "Record actual adaptations and retain applicable upstream copyrights and licenses. Reference inputs and comparison experiments are not distributed runtime dependencies.",
   "original_notes": [
@@ -297,7 +298,8 @@
     "1.5.1 restores 126 original Apache-2.0 test functions and qualification tools from Swift-JSON 1.2.1 (e8b687f822c577311156b13bf1d15c2d5620b84e), with file hashes and stable function identities in Qualification/Release1.5.1/Restoration.json. The diagnostic omission and Git-free provenance repairs are restored original code; current seven-product harness reconciliation and deterministic CLI identity are original contributions. No new upstream adaptation or dependency.",
     "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."
+    "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."
   ],
   "jsonhtml_export_original_contributions": {
     "license": "Apache-2.0",

Documentation/Architecture/StructuralIntelligence/A0Recovery.md

@@ -0,0 +1,54 @@
+# Experimental exclusive traversal reducer
+
+The original borrowed noncopyable callback at e11f93f is blocked: an escaping
+capture aborts Swift 6.4 code generation in SILGenCleanup in Debug and Release.
+Type checking alone accepts it and cannot establish ownership safety.
+
+The isolated recovery first tried an inout capability and Copyable reducer.
+Explicit closure capture, consuming return, storage and copying
+were rejected normally, but returning a bound nonmutating method still aborted.
+That form is rejected. A standard-library-only reduced reproducer preserves the
+failure. Nonescapable lifetime attributes also require experimental features on
+the supported compiler; no flags or unsupported lifetime attributes are adopted.
+
+The selected experiment uses a package-only `JSONTraversalOwnedReducer` with
+mutating observation/finalization and an `inout JSONTraversalContext`. All exposed
+capability operations are mutating: they require exclusive access to the one
+invocation's mutable ledger, and Swift forbids turning them into bound method
+values. The scope field is private; initialization is internal to Navigation.
+Reducer state and Result remain Copyable, so neither can own the noncopyable
+capability. No general borrowed owned-callback entry point is exposed.
+
+`JSONTraversal.inspectOwned(scope:options:reducer:)` calls the existing traversal
+executor, which creates exactly one original JSONReadScope and admission. The
+context only delegates to that scope. No meter, admission, limit default, cursor
+or mutable scope reference is returned. Owned errors latch on the original
+health; finalization preserves the original failure even after a caught error
+or attempted replacement. Scope invalidation runs on every exit.
+
+At the isolated 31879e8 checkpoint, actual full Debug/Release `swiftc -c` passed
+two positives and eighteen qualified ordinary negative diagnostics: return,
+escaping closure, Sendable capture, forge, long-lived storage, bound method,
+global storage, copy and external-package access per configuration. Final review
+found that the two additional Task cases had stopped on an unused-throwing-task
+warning, not the required ownership diagnostic. That evidence gap is preserved.
+The corrected probe explicitly discards the Task handle and requires an actual
+escaping-inout primary diagnostic. Every negative now matches the primary error
+text, never echoed source or an unrelated warning. The complete matrix remains
+two positive and twenty negative code-generation cases. All 47
+Navigation functions passed Debug/Release, strict compilation and the public
+consumer/DocC lane. The eight new functions prove every-counter no-op parity,
+same-ledger work/finalization, inclusive quotas, output retention, terminal error
+priority, cancellation, exact paths/spans and post-invalidation root/state release.
+These are architecture-specific proofs, not a claim that the compiler bug is fixed.
+
+The new capability is experimental and absent from the independent public
+Navigation integration. Subsequent inspection work must reuse it without adding
+an inner composition scope. All actual command/source/toolchain receipts remain
+bound to their own checkpoint; later source needs its own applicable qualification.
+
+Qualification provenance follows the established checkout_head helper: source
+archives and Git-ownership refusals record null Git identity, with exact source
+input hashes. They still execute the complete positive/negative codegen matrix.
+No global safe.directory or repository-trust setting is changed. The initial
+archive/container harness failures are preserved as failures in the return.

Documentation/Architecture/StructuralIntelligence/Inspection.md

@@ -0,0 +1,73 @@
+# Array evidence public-product candidate
+
+JSONInspection is an opt-in library depending on JSON and JSONNavigation. Core
+never re-exports it. This isolated promotion candidate is unmerged and unreleased.
+It reports observations rather than table/schema admission. Navigation public
+declarations and semantics are unchanged. See [public surface review](N2Promotion.md)
+and the [DocC guide](../../../Sources/JSONInspection/Documentation.docc/ArrayEvidence.md).
+
+`JSONShapeInspector(document:limits:)` captures one canonical source.
+`inspectArray(at:sampling:maximumColumns:includeSourceSpan:)` selects an existing
+array using exact JSONLocationComponent keys/indices and returns the existing
+JSONOperationReport envelope. JSONShapeSampling supports complete rows or
+`prefix(maximumRows:)`. The column bound defaults to 100,000, inclusive. Negative
+sampling or column configuration fails before admission, a deliberate new-API
+precedence contract. Valid operations always admit the full captured root/source/map
+once, even for a zero prefix, scalar selection error or unseen suffix.
+
+The [exclusive reducer](A0Recovery.md) runs observation and finalization inside
+Navigation's original read scope and meter. No nested public operation, new
+resource context, parsing, default reset or additional root admission occurs.
+Selection and wrong-kind failures use core access errors. Column capacity,
+resource exhaustion and cancellation throw and cannot publish partial evidence.
+
+## Evidence and coverage
+
+Row coverage and traversal coverage are independent. The walker explores the
+selected array root and rows at depth one, and the reducer inspects object cells
+directly. Row descendants are pruned; complete row evidence can therefore have
+restricted traversal coverage. An incomplete positive prefix intentionally stops
+at its final observed row. A zero prefix has no positive traits. A prefix reaching
+the final row has complete **row** coverage, without certifying descendant shape.
+
+Reports retain source selection, optional coherent selected-array span, full-source
+admission completion, total/examined row counts, six exact row kinds and deterministic
+first-seen columns. Column present includes explicit null; explicitNull is separate;
+missing uses observed object rows only. Nonobject rows contribute no missing cells.
+Decoded scalar-distinct keys stay distinct and retain source insertion order.
+No String hash/set, normalization, numeric projection or replacement JSON is used.
+
+Observed-all-objects and uniform-kind traits describe examined rows only. Empty
+evidence yields nil traits. Array length range describes observed array rows;
+rectangular width requires all examined rows to be arrays of that length. It says
+nothing about numeric cells, a matrix, schema validity or an unexamined suffix.
+Numbers remain canonical JSONNumber values in the unchanged source. Replacement
+documents retain no stale original span.
+
+## Finite work and ownership
+
+All 49 core profiles and metric definitions remain unchanged. The inspector uses
+their source, path, work, key, retention and cancellation limits. Its additional
+inclusive column bound is finite by default. Logical overlay version 1 reserves
+256 bytes for report/reducer summary, 192 per returned column, exact UTF-8 key
+bytes, and core path-slot/key weights for returned selection. Reservations precede
+collection growth. Output slots transfer from reducer to report; they remain
+charged at handoff. These are declared logical weights requiring calibration,
+not heap layout, allocation count or process RSS guarantees.
+
+Every row/member/column scan and finalization step charges the original meter;
+key comparisons delegate to core scalar comparison, including inner cancellation.
+Counters are bounded by admitted row/member counts and work before increments.
+Column lookup can be quadratic. No indexing or speed claim is made.
+
+The seventeen I01–I17 Swift Testing functions cover empty, wrong-kind, missing,
+complete/mixed/late-counterexample/zero-prefix rows, permutations, scalar key identity,
+typed numeric paths, null/absence denominators, exact numbers/lexemes, ragged and
+nonnumeric arrays, full-source admission, inclusive work/retention/column limits,
+inner cancellation, source coherence and independent shared-source invocations.
+`Scripts/ci.py --lane inspection` enforces exact discovery and compiler outcomes.
+Current native/Linux/WASI/platform receipts must qualify final source; this document
+does not turn an unexecuted lane into a pass. No N2 merge or release is authorized.
+
+Snapshots, persistent indexes, projections, retrieval, BFS, JSONPath, HTML/CLI
+integration, schema inference and numeric matrices remain deferred.