Expose the reviewed source-bound directed graph API

AGENTS.md

@@ -43,4 +43,7 @@ Documentation/Architecture before changing behavior.
 
 Scalar scanning and immutable plan-local regex sharing are selected private
 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.
+NAV11 directed simple graph has an owner-reviewed public candidate API inside JSONInspection; no new product or automatic merge.
+Store/set/matrix/retrieval/persistence and JSON text-sequence framing remain separate deferred trains.
+
+NAV11 public graph candidate adds only the approved immutable profile, checked source-bound graph and typed failures inside JSONInspection. CSR arrays, reducers and meters remain non-public; no new product or graph serialization/mutation. Future merge/release remain separately human-gated.

Documentation/Architecture/ExtractionManifest.json

@@ -271,6 +271,18 @@
       "attribution": "User-authored packet fixture input; original integration/tests Apache-2.0. Packet source/provenance retained separately.",
       "validation": "TypedConstructionTests.swift and public G3Acceptance consumer; strict native compiler/evaluator authority",
       "evidence": "Release1.6/G3 qualification and materialized per-case receipts"
+    },
+    {
+      "repository": "ThorFuchs/Swift-JSON",
+      "commit": "1a0306d076a08c8c43281f91412a11cd744ff3f6",
+      "destination": "Sources/JSONInspection/Graph",
+      "disposition": "Original Apache-2.0 NAV11 experimental source-backed directed simple graph; no upstream graph code adapted. Canonical Navigation/context and JSON comparison remain authorities. Independent packet fixtures retained with SHA-bound oracle.",
+      "validation": [
+        "Tests/JSONInspectionTests/GraphAcceptanceTests.swift",
+        "Scripts/qualify_graph_context.py",
+        "Scripts/qualify_graph.py"
+      ],
+      "evidence": "Scripts/ci.py source-bound native/Linux/safety/compiler receipts; private symbols only"
     }
   ],
   "original_implementation_notes": [
@@ -312,5 +324,20 @@
     "framework_boundary": "Conditional CoreTransferable/UniformTypeIdentifiers plus a narrow explicit main-actor Apple PDF boundary using WebKit, CoreText, CoreGraphics and AppKit/UIKit paragraph styles. Core JSON imports none of these; no new root dependency.",
     "rtf": "Original bounded strict-token emitter; AppKit/UIKit native decoding only in tests and qualification consumers, not generation.",
     "pdf": "Original invocation-owned lifecycle, finite adapter accounting and visible-range pagination using Apple SDK APIs. PDFKit is independent qualification only; no third-party renderer adapted."
-  }
+  },
+  "original_components": [
+    {
+      "component": "NAV11 owner-reviewed public graph candidate",
+      "license": "Apache-2.0",
+      "source": "Original Swift-JSON public access/documentation adapters over qualified NAV11 graph donor PR #67 / 81485930f859131d0802691ca6370f482ba62911",
+      "paths": [
+        "Sources/JSONInspection/Graph",
+        "Tools/GraphPublicQualification",
+        "Tests/JSONInspectionTests/GraphPublicAcceptanceTests.swift",
+        "Sources/JSONInspection/Documentation.docc/SourceBoundGraphs.md"
+      ],
+      "validation": "G01–G32 retained; GP01–GP16 plus Debug/Release/ASan public consumer, 26 codegen negatives and three DocC examples; execution receipts required",
+      "dependencies": "No external runtime dependencies; existing JSON and JSONNavigation authorities only"
+    }
+  ]
 }

Documentation/Architecture/StructuralIntelligence/NAV11/APICandidate.md

@@ -0,0 +1,48 @@
+# Graph API proposal for later owner review
+
+All NAV11 types and operations are **package-only**, not application API. Product
+count remains ten, dependencies remain empty, Navigation56/Inspection95 unchanged.
+The proposed future public subset, contingent on separate review, is:
+
+- Immutable `JSONGraphProfile(nodesAt:edgesAt:nodeIDKey:edgeSourceKey:edgeTargetKey:)`.
+- `JSONGraphProjection.build(document:profile:limits:maximumNodes:maximumEdges:)`
+  returning `JSONOperationReport<JSONGraphProjection>`, defaults 10000/50000.
+- Read-only captured document/profile/nodeCount/edgeCount and complete traversal
+  summary. IDs/CSR buffers are research metadata; promoting their raw arrays is
+  not proposed. Source-local node/edge ordinals have no cross-view identity.
+- `nodeValue(at:limits:)`, `edgeValue(at:limits:)`, `nodeSpan(at:limits:)` and
+  `outgoingEdges(of:limits:maximumResults:)` with independent finite whole-source
+  admissions. Returned JSON aliases receive additional owned-value accounting.
+- `breadthFirst(fromNode:limits:maximumFrontier:maximumVisited:maximumResults:)`
+  returning original node ordinals; defaults 10000 each, start included, complete
+  reachable component. Zero caps refuse a real start; an empty graph has no start.
+- Typed semantic errors with original row/field paths; core missing/kind/resource
+  and cancellation errors stay intact. No partial-success variant exists.
+
+BFS stores queue history as returned output; frontier means pending entries, while
+visited/result caps independently bound total enqueues/output. Graph metadata
+aliases, visited flags and queue entries share the query's original traversal
+ledger. Scalar-exact linear resolution and O(N²+NE+E²) construction are explicit
+costs, not optimized lookup claims. No new JSON identity/path or serialization.
+
+Actual compiled spelling is in Sources/JSONInspection/Graph. Constructors remain
+fileprivate. Compiler probes reject external type access, private initializers,
+mutation, internal reducers, and context escape. No public DocC examples imply
+these private declarations are available. No merge or promotion is authorized.
+
+## Public successor review
+
+The owner approved the compiler-derived 34-declaration public subset for the draft
+candidate, subject to qualification. The exact source spelling is authoritative:
+public JSONGraphProfile (immutable explicit paths/keys and initializer),
+JSONGraphProjection (checked factory, immutable document/profile/traversal/counts
+and five independent query operations), and JSONGraphFailure with fourteen typed cases.
+No existing public declaration changes. CSR buffers, ID staging, edge records,
+reducers and the noncopyable context remain inaccessible externally. The old
+public-type-invisibility negatives are replaced by internal builder/query/stage
+negatives; initializer, storage, mutation and ownership rejections remain.
+
+Sixteen public-only scenarios and a distinct-package consumer supplement all
+G01–G32 and 27 independently pinned fixtures. Three executable DocC examples and
+26 external full-codegen rejections are mandatory. This is signature approval
+for a draft, not merge/release approval or a claim of unexecuted platform passes.

Documentation/Architecture/StructuralIntelligence/NAV11/GraphADR.md

@@ -0,0 +1,57 @@
+# NAV11 directed simple graph experiment
+
+Package-only JSONInspection research, based on merged Navigation/Inspection;
+no NAV10, new product, public symbol or graph JSON model. One original
+`JSONTraversal.inspectOwned` invocation selects `[nodesAt, edgesAt]` with
+`.rejectAmbiguous` and depth one. All strict root selections and overlap checks
+precede callbacks; nodes are validated before edges, in their physical order.
+
+Negative capacities are configuration failures before admission. Existing core
+precedence is retained: complete source admission precedes strict selection,
+overlap and root-kind checks. No separate unmetered profile scan or second ledger
+is added to move those checks ahead of admission. Missing roots preserve core
+`missingMember`/`missingTarget`; wrong root kinds preserve typed core access errors.
+Paths and explicit keys are immutable. Reusing a field spelling across roles is
+intentional and valid (an edge's single field may explicitly name both ends of a
+self-edge); no field inference or silent repair occurs.
+
+The exclusive context adds mutating delegates only: direct string member selection,
+scalar-exact string comparison and matching alias release. JSONObject.lookup and
+JSONComparison.textEquals remain authorities. Missing, null and wrong kind are
+reported separately; strings own 32+UTF8 logical bytes until released or handed off.
+Profile keys are explicitly key-admitted on that meter even for empty arrays;
+the preexisting retainKey delegate gains an opt-in caller-input admission flag,
+with its original default behavior/counters preserved.
+No cursor, scope, ledger or noncopyable capability leaves the reducer. Original
+2-positive/20-negative codegen tests are unchanged; helper escape probes and runtime
+parity run separately in Debug and Release. A compiler crash blocks implementation.
+
+Graph metadata is source-local: first row ordinals, exact ID aliases, endpoint
+ordinals and CSR offsets/edge ordinals in original edge order. Original source is
+transferred once after complete validation/finalization. Defaults are 10,000 nodes,
+50,000 edges; each independently configurable finite cap is inclusive and still
+subject to all 49 core metrics. Linear exact scans may cost O(N²+NE+E²).
+
+Later value/span/catalogue/BFS calls start explicit independent full-source
+operations. BFS has a head-index queue, visited-at-enqueue and source-edge order.
+Defaults: 10,000 frontier entries, visited nodes and returned nodes. Queue history
+remains charged until handoff; frontier capacity means live pending entries.
+Results certify the complete reachable component including the start, not global
+reachability. Failure/cancellation returns no partial result.
+
+Logical policy V1: 256 fixed builder bytes, 32+UTF8 per node ID alias,
+16 per node record, 24 per edge record, 8 per offset and adjacency reference,
+plus exact profile keys/paths and the original source. Queries admit graph metadata
+aliases, queue/output slots (8 each), visited flags (1 each) and their source;
+returned JSON aliases additionally receive core owned-retention accounting.
+These are logical quotas, not allocator/RSS or caller-instruction guarantees.
+
+No public promotion, merge, release, timing or speed claim. Controlled performance
+remains HOLD. Store, persistence, graph editing, weights, algorithms other than BFS,
+query/CLI/HTML/network adapters and NAV10 batching remain separate work.
+
+BFS entry precedence is negative capacities, node bounds, whole source/metadata
+admission, then enqueue's frontier/visited/result ceilings. Work/cancellation that
+is observed first takes precedence. Edge rows validate source field then target
+field before resolving source then target IDs, then compare ordered pairs. All
+node rows precede all edge rows; a late duplicate node outranks a dangling edge.

Documentation/Architecture/StructuralIntelligence/NAV11/SourceAuthority.md

@@ -0,0 +1,22 @@
+# NAV11 source authority
+
+Base main: 1a0306d076a08c8c43281f91412a11cd744ff3f6. NAV10 PR66/d566f28 is
+independent and not a source dependency. Stable 1.6.1/e431f15 remains immutable.
+
+| Graph work | Existing delegate | Invocation boundary |
+| --- | --- | --- |
+| Complete root/source/map admission and failures | JSONReadScope, JSONAdmission, JSONWorkMeter | Original inspectOwned scope |
+| Physical/virtual roots and exact overlap | JSONTraversal.execute, rejectAmbiguous | Same original scope, before callbacks |
+| Row locations and bounded paths | JSONTraversalHit, JSONLocationComponent, context.appending | Same scope |
+| Direct string member/presence/kind | JSONObject.lookup through mutating context delegate | No reader/new ledger |
+| ID equality | JSONComparison.textEquals through context.equalStrings | Scalar-exact charged UTF8 comparison |
+| Owned alias accounting, cancellation, terminal health | context.perform + scope.run/check | Original state, no escape |
+| Adjacency and BFS | Package-only graph reducers | Checked work/retention in that invocation |
+| Completed source handoff | context.transferDocumentOwnership | Once after complete valid construction |
+| Later source value/span | JSONReadScope.select and sourceMap.span | Explicit new whole-source operation |
+| Returned value alias | JSONAdmission.value(owned:true) | Same later-read ledger, additional output cost |
+
+No JSON, Pointer, value equality, schema, stream, Patch, HTML or CLI semantic change.
+The new context methods are package-only and mutating; original ownership codegen
+fixtures are byte-identical. ExtractionManifest records original Apache-2.0 code
+and independent fixture provenance. Public symbol graphs must remain unchanged.

Documentation/CI/README.md

@@ -1,3 +1,16 @@
+# NAV11 experimental graph qualification
+
+The package graph/public API stays unchanged: nine libraries plus CLI; Navigation56
+and Inspection95. Graph symbols are package-only. Exact discovery is 108 Inspection
+functions including G01–G32, with five Inspection sharing functions. All previous
+identities, 49 core cap probes and 126 maintenance witnesses remain required. Native
+and Linux add the graph context and package-boundary codegen/runtime qualifiers;
+the original two-positive/twenty-negative ownership matrix is unchanged. Exact
+identities and genuine primary diagnostics are checked, including crash rejection.
+
+The current source-bound receipts establish outcomes; the dated sections below
+retain their original source scopes. Controlled performance remains HOLD.
+
 # NAV8 Navigation V1 integration
 
 Current required discovery retains 779 native /763 Linux /675 WASI functions,
@@ -295,3 +308,17 @@ The focused composition lane also runs on the Linux architecture jobs and Native
 Its separate-package discovery is additive; all root and 49-cap expectations remain intact.
 The qualification harness now has 15 regression functions, retaining its original 14.
 See [composition qualification](../Architecture/CompositionQualification.md) for finite capacity outcomes.
+
+## NAV11 public graph candidate
+
+The owner-reviewed successor keeps all 32 original graph identities and adds 16
+public scenarios (124 Inspection functions). Required roots become 827 native,
+811 Linux and 723 WASI, with unchanged 325/288 parameter invocations. Shared-state
+expectations become 53 native/52 Linux. The public graph qualifier executes 16
+consumer cases in Debug/Release/ASan, three guide blocks/configuration and 26
+ordinary external full-codegen rejections. The original graph boundary matrix
+retains 18 negatives, replacing only obsolete invisible-public-type cases with
+internal builder/query/stage access rejections. Reducer 2+/20-, helper 2+/8-, all
+49 core caps and 126 maintenance identities remain. Harness cardinality is 19.
+These are requirements; actual source-bound receipts establish results. No merge
+or release follows automatically. Controlled G4 remains HOLD without speed claims.

Documentation/Qualification/GraphCases.json

@@ -0,0 +1,80 @@
+{
+  "schema_version": 1,
+  "status": "public API candidate; owner review and full current-source qualification required",
+  "functions": [
+    "JSONInspectionTests.graphG01EmptySourceAndNoValidStart()",
+    "JSONInspectionTests.graphG02IndependentOracleAndSourceOrder()",
+    "JSONInspectionTests.graphG03ScalarDistinctIDs()",
+    "JSONInspectionTests.graphG04SpecialIDsAreNotPaths()",
+    "JSONInspectionTests.graphG05DuplicateNodeLocations()",
+    "JSONInspectionTests.graphG06EqualPayloadsPreserveRows()",
+    "JSONInspectionTests.graphG07MissingNodeID()",
+    "JSONInspectionTests.graphG08NullNodeID()",
+    "JSONInspectionTests.graphG09WrongNodeIDKinds()",
+    "JSONInspectionTests.graphG10NonobjectNode()",
+    "JSONInspectionTests.graphG11MissingEdgeSource()",
+    "JSONInspectionTests.graphG12NullEdgeTarget()",
+    "JSONInspectionTests.graphG13WrongEndpointKind()",
+    "JSONInspectionTests.graphG14NonobjectEdge()",
+    "JSONInspectionTests.graphG15DanglingAndEmpty()",
+    "JSONInspectionTests.graphG16DuplicateOrderedEdge()",
+    "JSONInspectionTests.graphG17ReverseEdgesAreDistinct()",
+    "JSONInspectionTests.graphG18SelfEdgeIsVisitedOnce()",
+    "JSONInspectionTests.graphG19CycleTerminates()",
+    "JSONInspectionTests.graphG20IsolatesRemainSourceNodes()",
+    "JSONInspectionTests.graphG21SourceEdgeNeighborOrder()",
+    "JSONInspectionTests.graphG22DiamondEnqueuesOnce()",
+    "JSONInspectionTests.graphG23TypedPathsAndPointerDifferential()",
+    "JSONInspectionTests.graphG24OverlapAndDuplicateRootsFailBeforeRows()",
+    "JSONInspectionTests.graphG25WholeSourceAdmissionAndFreshQueries()",
+    "JSONInspectionTests.graphG26InclusiveWorkAndRetention()",
+    "JSONInspectionTests.graphG27EveryCapacityAndCheckedOverflow()",
+    "JSONInspectionTests.graphG28CancellationStopsBuildAndBFS()",
+    "JSONInspectionTests.graphG29FailurePrecedenceAndTerminalLatch()",
+    "JSONInspectionTests.graphG30ConcurrentViewsHaveIndependentHealth()",
+    "JSONInspectionTests.graphG31CapturedRootAndSourceMapCoherence()",
+    "JSONInspectionTests.graphG32CheckedMetadataAndExistingPublicSemantics()"
+  ],
+  "fixture_cases": 27,
+  "context_positive_codegen": 2,
+  "context_negative_codegen": 8,
+  "graph_positive_codegen": 2,
+  "graph_negative_codegen": 18,
+  "public_functions": [
+    "JSONInspectionTests.graphGP01OptInSurface()",
+    "JSONInspectionTests.graphGP02TypedRootAndEmptyKeys()",
+    "JSONInspectionTests.graphGP03SourceOrderBFS()",
+    "JSONInspectionTests.graphGP04SelfLoopAndCycle()",
+    "JSONInspectionTests.graphGP05DuplicateIDPaths()",
+    "JSONInspectionTests.graphGP06ScalarDistinctIDs()",
+    "JSONInspectionTests.graphGP07OrderedPairs()",
+    "JSONInspectionTests.graphGP08DanglingEndpoint()",
+    "JSONInspectionTests.graphGP09MissingNullWrongKind()",
+    "JSONInspectionTests.graphGP10BoundsAndZeroCaps()",
+    "JSONInspectionTests.graphGP11IndependentWholeSourceBudget()",
+    "JSONInspectionTests.graphGP12OwnedValueAndSourceHandoff()",
+    "JSONInspectionTests.graphGP13CancellationAndHealth()",
+    "JSONInspectionTests.graphGP14ConcurrentQueries()",
+    "JSONInspectionTests.graphGP15SourceMapCoherence()",
+    "JSONInspectionTests.graphGP16UnselectedAdmission()"
+  ],
+  "public_consumer_checks": [
+    "GP01",
+    "GP02",
+    "GP03",
+    "GP04",
+    "GP05",
+    "GP06",
+    "GP07",
+    "GP08",
+    "GP09",
+    "GP10",
+    "GP11",
+    "GP12",
+    "GP13",
+    "GP14",
+    "GP15",
+    "GP16"
+  ],
+  "public_negative_codegen": 26
+}

Documentation/Qualification/TestDiscovery.json

@@ -12,7 +12,7 @@
     "JSONCLITests": 88,
     "JSONNavigationTests": 47,
     "JSONSchemaExamplesTests": 98,
-    "JSONInspectionTests": 76
+    "JSONInspectionTests": 124
   },
   "parameterized_invocations": 325,
   "composition_external_functions": 5,
@@ -35,7 +35,7 @@
     "JSONCLITests": 1,
     "JSONNavigationTests": 1,
     "JSONSchemaExamplesTests": 4,
-    "JSONInspectionTests": 4
+    "JSONInspectionTests": 6
   },
   "coverage_unmapped": {
     "Sources/JSON/Pointer/JSONLocationComponent.swift": "declaration-only enum",
@@ -76,7 +76,7 @@
     "JSONCLITests": 88,
     "JSONNavigationTests": 47,
     "JSONSchemaExamplesTests": 98,
-    "JSONInspectionTests": 76
+    "JSONInspectionTests": 124
   },
   "wasi_root_functions": {
     "JSONTests": 190,
@@ -89,7 +89,7 @@
     "JSONBridgesTests": 10,
     "JSONNavigationTests": 47,
     "JSONSchemaExamplesTests": 98,
-    "JSONInspectionTests": 76
+    "JSONInspectionTests": 124
   },
   "wasi_parameterized_invocations": 288,
   "portable_shared_state_functions": {
@@ -103,7 +103,7 @@
     "JSONCLITests": 1,
     "JSONNavigationTests": 1,
     "JSONSchemaExamplesTests": 4,
-    "JSONInspectionTests": 4
+    "JSONInspectionTests": 6
   },
   "export_functions": {
     "JSONSchemaTests": 1,

Package.swift

@@ -22,7 +22,7 @@ let package = Package(
         // Opt-in N1 product candidate; promotion does not change core navigation semantics.
         .target(name: "JSONNavigation", dependencies: ["JSON"]),
         .target(name: "JSONInspection", dependencies: ["JSON", "JSONNavigation"]),
-        .testTarget(name: "JSONInspectionTests", dependencies: ["JSONInspection", "JSONNavigation", "JSON"], resources: [.copy("ProjectionFixtures")]),
+        .testTarget(name: "JSONInspectionTests", dependencies: ["JSONInspection", "JSONNavigation", "JSON"], resources: [.copy("ProjectionFixtures"), .copy("GraphFixtures")]),
         .testTarget(name: "JSONNavigationTests", dependencies: ["JSONNavigation", "JSON"], exclude: ["Fixtures"]),
         .target(name: "JSONBridges", dependencies: ["JSON"]),
         .testTarget(name: "JSONIntegrationTests", dependencies: ["JSON", "JSONSchema", "JSONStreaming", "JSONPatch"]),