70 lines
9.1 KiB
Plaintext
70 lines
9.1 KiB
Plaintext
# Isolated navigation oracle
|
|
|
|
Prepared against core commit `6520a89dc042dd433454f6cc63cb23b0e6df7911`. This local crate is not a production CLI feature or workspace member. It has not been compiled or executed by its author. The native Draw fixture generator is implemented, but no generated fixture/admission result is claimed yet. The prior `.local/populated-projection-regression.patch` is unchanged.
|
|
|
|
## Parent build and first admission
|
|
|
|
From `C:/ar-nav-01a0d717`, after the exclusive frozen compiler gate permits it:
|
|
|
|
```powershell
|
|
cargo build --offline --manifest-path .local/navigation-oracle/Cargo.toml --target-dir .local/navigation-oracle/target
|
|
```
|
|
|
|
The utility's Cargo.lock is initially an exact copy of the repository lock, used as a dependency seed. The first isolated build may update that local lock for this new package. Preserve its final bytes and the binary hash with the evidence. Subsequent reproducible builds should add `--locked --offline`. No Cargo command has been run in this task. Use Rust 1.90 or later, matching the repository's declared minimum. Dependencies are the repository path `oa-core` plus the same serde/serde_json major requirements already in the repository; no Python, shell helper, external server or additional runtime is required.
|
|
|
|
The `reviewed_core` field is a source-review pin, not an automatic runtime fingerprint. Record actual repository HEAD, tracked diff, utility hashes, final lock and executable hash when building. A later parent core change must not be attributed to this pin.
|
|
|
|
## Commands
|
|
|
|
```powershell
|
|
$oracle = 'C:/ar-nav-01a0d717/.local/navigation-oracle/target/debug/navigation-oracle.exe'
|
|
& $oracle fixture C:/ar-nav-01a0d717/.local/native-draw-fixture
|
|
& $oracle snapshot C:/path/to/saved/project.arcadia C:/path/to/new-baseline-snapshot
|
|
& $oracle snapshot C:/path/to/saved/project.arcadia C:/path/to/new-after-snapshot
|
|
& $oracle compare C:/path/to/new-baseline-snapshot C:/path/to/new-after-snapshot
|
|
& $oracle compare C:/path/to/new-baseline-snapshot C:/path/to/new-after-snapshot --projection 00000000-0038-4000-8000-000000000001 Allocation
|
|
```
|
|
|
|
Every output directory must be new, with an existing parent. Existing evidence is never overwritten. Fixture/snapshot writes that fail may leave partial output; preserve the failure, then choose another new directory. `compare` writes a JSON report to stdout and does not modify either snapshot. Exit 0 means that command completed successfully or comparison passed; 1 means a completed comparison failed; 2 means usage, loading, admission, IO or snapshot consistency failed. Capture stderr and the exit code as well as stdout.
|
|
|
|
For the projection trial: exact `compare` for selection/Properties; nominated-diagram `Allocation` comparison for switched state; exact baseline-versus-Undo, switched-versus-Redo and switched-versus-fresh-reopen comparisons. The utility does not infer which diagram changed. It never excuses unrelated fields, other diagrams, ID changes or reference changes.
|
|
|
|
## Snapshot contract
|
|
|
|
`snapshot` uses core `source_files::load_project` with the CLI's explicit policy: 64 MiB aggregate source, 256 files, include depth 32, 1024 include edges, 100000 graph objects, 250000 records and 500000 ordered references. It rejects discovery errors and returns full located compiler diagnostics on admission failure. Engineering warnings are retained in the report/snapshot. It compiles the reachable bundle with `source_project::compile_bundle` and exports the complete accepted Project to `project.json`.
|
|
|
|
`snapshot.json` contains the accepted Project, logical entry name and every reachable source path mapped to its exact raw captured disk bytes as an integer array. It preserves CR/LF, whitespace, comments and UTF-8 bytes; source is not regenerated or normalized. Disk expectations are checked against compiler input. Two complete source captures must match before evidence is written. This detects changes across the two observations but is not filesystem locking or an atomic multi-file snapshot; keep the saved project quiet.
|
|
|
|
The core loader rejects unsafe include paths, symlinks/junction escapes and invalid UTF-8. No snapshot logical path is used to write a file. Comparison revalidates logical paths, aggregate limits and UTF-8, recompiles all raw source, and requires that embedded Project exactly equal the compilation. Snapshot input itself is capped at 512 MiB. Source requiring UUID stabilization or migration is rejected so compiler-added text cannot be mistaken for original disk bytes: explicitly save the accepted current-version source first. Detached/unreachable editor buffers and unrelated disk files are outside this saved-project oracle.
|
|
|
|
## Comparison contract
|
|
|
|
Without an allowance, comparison requires complete Project equality, identical logical entry/path set and byte equality for every captured source file.
|
|
|
|
With `--projection DIAGRAM_UUID ProjectionKind`, clone the complete baseline Project and replace exactly the nominated diagram's projection. The after Project must equal that entire expected value. Accepted names are Overview, Decomposition, Allocation, FunctionalDataflow, Capabilities and Traceability; typed StateMachine/Scenario changes have no allowance.
|
|
|
|
Source still requires either exact bytes or exactly one changed source file whose complete prefix and suffix outside the compiler-indexed projection value match byte-for-byte. Both versions must have an explicit projection value in the same file and the same reachable path set. The JSON report includes both byte spans and original/replacement field text, plus whether outside-field bytes were exact. Omitted/defaulted projection declarations fail this narrow source allowance rather than broadening it silently. Project mismatches report up to 200 unexpected JSON paths; full snapshots remain available to inspect all differences. Matching counts alone never establishes conservation.
|
|
|
|
This is a saved-source oracle. It cannot inspect unsaved desktop state, prove GUI click ordering, prove exact in-memory source history, or establish native selection usability. Save/capture each relevant checkpoint and associate screenshots/action logs with it. Model-changing Draw actions deliberately fail this unchanged/projection-only comparator; inspect their precise creation delta separately instead of adding a broad allowance.
|
|
|
|
## Native Draw fixture contract
|
|
|
|
`fixture NEW_DIR` constructs typed records through `Project::add_element`, `ensure_diagram`, `place` and `reidentify`. It creates OA Activity source/target and SA Function source/target, with distinct labels and two Traceability diagrams declared OA and SA. Both diagrams contain all four work cards, placed in two uncluttered rows: OA at (60,60)/(520,60), SA at (60,300)/(520,300). Initially there are no relations or ports, allowing native Draw to create the Interaction or FunctionalExchange and its ports using the application's actual workflow.
|
|
|
|
UUIDv5 identities and aliases are deterministic; no random identity remains from the construction helpers. The generated `oracle.json` records exact element/view IDs and the source entry. The generator validates the complete Project, compiles the core `format_bundle` output, checks four projected cards per view, saves the bundle using `source_files::new_project`/`expect_new_file`/`save_project`, recompiles the saved source and requires full Project equality. It then writes Project JSON. Generated output is synthetic and must never be described as recovered user source or an already-run native acceptance result.
|
|
|
|
Use the SA mixed view to inspect/select OA work before invoking contextual Draw; use the OA mixed view for the SA work counterpart. Semantic source and target must follow the selected work layer even when the canvas perspective differs. Preserve the documented scope distinction: opening the contextual form retains the canvas; successful Apply may perform the existing explicit post-review navigation. The separate architecture palette limitation is not claimed repaired.
|
|
|
|
## Reviewed source identities and remaining checks
|
|
|
|
SHA-256 at preparation:
|
|
|
|
- `src/main.rs`: `4e9fcaea127e6654e5cd12d0bd18336c279f2f5885ea15d12fc31a36d7cd45f0`
|
|
- `Cargo.toml`: `ba95c25a04dbfd0d6d19bd59f466e4082f840723ebE8180e5061a4a157e139c8`
|
|
- Repository/seed Cargo.lock: `2aa80d113c5112b31c0767b874845d60f555e4e8ae7eb3ecd0b4b91954b55378`
|
|
- Core `source_files.rs`: `bb903f8c53456f69c5ac213a192a1eb0d19abf8344bd82a03be8e659ba7bc94f`
|
|
- Core `source_project.rs`: `d872f2a8f7c4add53f2708bf3fdaea1b4be715d4240f2d9b93baf4624d3f72a7`
|
|
- CLI limits source `crates/oa-cli/src/lib.rs`: `790f3bdef78025813262c9677d4db5813f32978a398f3b7fb4900427dc0c314e`
|
|
|
|
Parent review risks: uncompiled Rust/API compatibility; the isolated lock's initial adjustment; no atomic filesystem snapshot; snapshot memory grows with lossless byte arrays; strict stable-source/explicit-value requirements can reject otherwise valid but insufficiently prepared input. Useful oracle checks before trusting native results: identical snapshots pass, one allowed projection change passes only with the matching nominated view/value, an unrelated comment change fails exact bytes despite equal Project, and unrelated semantic/placement edits fail even under the projection allowance. Those checks are proposed, not executed.
|