Skip to content

Latest commit

 

History

History
82 lines (69 loc) · 4.65 KB

Traversal.md

File metadata and controls

82 lines (69 loc) · 4.65 KB

Exact traversal and explicit coverage

N1 adds many-node observation to the existing exact model. These three examples are compiled and executed as external Swift 6 modules in Debug and Release by Scripts/qualify_navigation.py. They assume explicit import JSON and import JSONNavigation; installing a public Navigation product remains gated.

Core access remains the appropriate interface for one node:

let root = try JSON.parse(#"{"items":[1,2],"note":null}"#)
let selected = try JSONPointer(parsing: "/items/0").resolve(in: root)
let absent = try root.presence(of: "missing")
let null = try root.presence(of: "note")
precondition(selected == 1 && absent == .absent && null == .null)

The structural visitor explores object insertion order and ascending array indices. Its paths remain absolute typed components; numeric keys remain keys. Root is [] and empty-key is [.key("")]; Pointer text should be produced by the core Pointer.

let root = try JSON.parse(#"{"items":[1,2]}"#)
var locations: [[JSONLocationComponent]] = []
let report = try JSONTraversal(document: .init(root: root)).visit { hit, _ in
    locations.append(hit.absoluteLocation)
    return .continue
}
precondition(locations == [[], [.key("items")], [.key("items"), .index(0)], [.key("items"), .index(1)]])
precondition(report.result.completion == .complete && report.statistics[.nodes] == 4)

Virtual scopes select existing source nodes without materializing a new JSON array. The default rejects duplicate and ancestor/descendant roots before any callback.

let root = try JSON.parse(#"{"items":[1,2],"tail":null}"#)
let selection = JSONTraversalScope.virtual(roots: [[.key("items")], [.key("tail")]])
let report = try JSONTraversal(document: .init(root: root)).collect(scope: selection, maximumRecords: 4)
precondition(report.result.nodes.count == 4 && report.result.summary.scopeRootCount == 2)
precondition(report.result.summary.completion == .complete)

.orderedOccurrences preserves repeated selections and their root index, occurrence ordinal and relative depth. .uniquePhysicalNodes deduplicates exact typed paths, including filtered/excluded roots: the first examined occurrence wins. Equal values at different paths remain different nodes. Revisited paths still explore descendants under their current relative depth; deduplication is never automatic subtree pruning.

Depth zero permits only a selected root. includeScopeRoot: false suppresses its emission; depthLimit: 1 then gives children-only traversal. Kind filtering suppresses emission, never descendant exploration. A filtered empty result can be complete; a missing scope throws. Pruning/depth omission is .restricted, explicit .stop is .visitorStopped; neither establishes absence outside observed coverage. Coverage is conservative per occurrence, not a proof that overlapping selections repaired an earlier pruned region. Only DFS is implemented; no BFS label or prefix-snapshot API.

Collection defaults to 100,000 records and throws on the next record; its bound is inclusive and zero is meaningful. Root/source admission, scope resolution, exact overlap comparisons, path creation, frontier, source-span lookup and records share one finite core ledger. Source spans are opt-in and come only from the captured coherent document. replacingRoot supplies none. No source text or subtree appears in a hit, and no read cursor crosses the synchronous visitor boundary.

Caller visitor computation and caller-retained copies are outside owned instruction and retention quotas. Reports account for logical ownership, not process RSS or allocator capacity. Unexpected quotas and cancellation throw and return no successful report, even if cancellation occurs during a callback returning .stop. Earlier callback effects cannot be recalled. Core access/resource errors retain their types; collection capacity and ambiguous roots use JSONTraversalFailure.

The initial overlap/dedup implementation uses metered linear comparisons rather than an unqualified hash index. Complete path copies are bounded by the existing read scope; deep frontiers can use quadratic path metadata. No EngineBench speed, linear total-time, zero-copy or fixed-memory claim is made. Classification, snapshots, projections, persistence, async actors, query syntax and rendering are later gates.

Full captured-source admission precedes validation of depth and collection options. An oversized source may therefore refuse admission before a negative option is reported. A valid small source with a negative option throws invalidLimits. The real external SwiftPM consumer resolves the JSONNavigation product in Debug and Release; package scopes and meters remain inaccessible.