[ORESoftware]

Summary

Add finite exact-version circular dependency materialization, including:

A@1 -> B@1 -> A@2 -> B@0 -> A@2

A@1 and A@2 are distinct exact nodes. The closing B@0 -> A@2 edge points to the existing canonical A2 node through a symlink; it does not recursively copy another dependency subtree.

Linear: DEN-3488
Normal-install/lockfile-v2 follow-up: #330
Logger prerequisite: ores-otel/ores.otel.log#45

Implementation

• identify nodes by registry, organization, package, exact version, and immutable artifact digest
• verify canonical resolved-graph bytes and digests before filesystem mutation
• detect exact-node back-edges with deterministic iterative DFS
• keep repeated package names at different versions distinct without false cycle detection
• stage every exact payload once in a digest-addressed generation
• represent payload entries and dependency edges as symlinks to canonical nodes
• expose direct roots at the project zed_modules/ boundary
• verify and reuse completed generations on replay
• fail closed for cyclic or parallel-version copy mode before project mutation
• enforce bounded nodes, edges, and deterministic cycle witnesses

For the canonical fixture there are exactly four payload nodes and four dependency links. The closing B0→A2 link resolves to the first A2 node; no fifth payload or recursive tree is created.

Diagnostics

The CLI pins the Rust logger from github.com/ores-otel/ores.otel.log and enables console output. Each cycle emits zed.install.circular_dependency with cycle_id, exact path, closing nodes, target node key/digest, resolution=exact-node-symlink, and graph/materialization digests. The terminal message names the cycle and explains that the closing edge reuses the existing exact node through a symlink.

Public surface and tests

zed graph materialize accepts either a canonical digest-verified resolved graph backed by the immutable Zed store or a local exact-node source-binding plan.

Product tests cover the canonical fixture, self/two-node cycles, version skew, diamonds/shared completed nodes, deterministic witnesses, bounds, malformed graphs, exact back-edge reuse, no recursive copies, replay, copy-mode rejection, symlink/path containment, macOS path canonicalization, and ORE memory-transport plus terminal diagnostics.

Current-head validation

Product head: 86d499aff19807cee3500777ee4a9e48ea646821
Current main integrated as second parent: 5d0cbc0609703e7516e2185ea3c1749c9feda482

The branch is ahead-only on current main. Focused run 34060370621 is green on Ubuntu, macOS, and Windows for the applicable exact-node, parser, ORE logging, public-executable symlink, platform-safety, and focused-Clippy lanes:

https://github.com/zed-pkg/zed-cli/actions/runs/34060370621

Independent exact-head suites are green and merged:

• test(DEN-3488): certify current circular graph product head zed-pkg-test/version-solver-e2e#4 — merge 53e41714d99c1de5aee38fea95b552296e8baa8a
• test(DEN-3488): black-box exact-version circular dependency materialization zed-pkg-test/zed-pkg-e2e#179 — merge 06be3471fe4c460fdf4f751f3464b9005c29d4ea

The Linux/macOS black-box suite built the exact release binary, drove the public CLI, verified the four-node finite symlink graph and B0→A2 reuse, checked visible diagnostics and replay, rejected copy mode, and reran product regressions at the same SHA.

Scope boundary

This PR does not claim ordinary .zpkg.toml resolution and .zpkg.lock v1 can select multiple versions of one coordinate. Issue #330 tracks lockfile v2 plus normal install/prefetch/frozen-replay integration and must reuse this exact graph/materializer.

Promotion gate

/ores-review was requested on the current head. Do not merge until current-SHA ores-review/openai, ores-review/claude, and ores-review/gate results satisfy repository governance.

[linear-code]

DEN-3488

[ORESoftware]

2026-09-03 exact-head validation

The macOS ARM regression was a path-representation issue, not a store escape: the test canonicalized the node source through /private/var/... but compared it with the lexical store root under /var/.... Commit 1aa85862e897a79b084b2a1be908e6b7704f7664 now canonicalizes the expected store root before applying the containment assertion.

Focused workflow run 33791388236 is green on the corrected exact head:

• Ubuntu exact-node, parser, executable finite-cycle, and strict Clippy lanes: pass
• macOS exact-node, parser, and executable finite-cycle lanes: pass
• Windows exact-node and parser lanes: pass; symlink executable test remains intentionally Unix-only

This preserves the containment check rather than weakening or removing it. The PR is not being merged here: it still has no independent OpenAI/Claude reviews, and several repository-wide workflows remain red or in progress outside this focused graph lane.

[ORESoftware]

DEN-3488 current-main integration receipt

The exact circular-graph implementation is now semantically integrated with current main without rebasing or force-pushing.

• current base: 5d0cbc0609703e7516e2185ea3c1749c9feda482
• previous exact-graph head: 8c0537e404f424cb648bede22db4334e8c3afca2
• two-parent integration commit: 86d499aff19807cee3500777ee4a9e48ea646821
• compare result: ahead-only on current main (behind_by = 0)
• effective product delta remains nine files: the exact graph implementation, public command integration, focused workflow/tests, ORE logger dependency/lock changes, and documentation

The six newly integrated mainline commits touched only formal-review/source-policy files plus src/source_fallback.rs; none overlapped the DEN-3488 product paths. Their exact blobs were composed into the feature tree and recorded with both parents.

Current-head independent acceptance:

• zed-pkg-test/zed-pkg-e2e#179 now pins 86d499a… and runs the black-box executable/symlink/replay/copy-mode contract on Linux and macOS.
• zed-pkg-test/version-solver-e2e#4 now pins 86d499a… and runs the standalone exact-node model plus product unit/integration/format/Clippy contract.

Promotion remains blocked until the exact current-head product and both acceptance workflows are terminal and green. The scope boundary is unchanged: ordinary .zpkg.toml + .zpkg.lock v1 still use one version per coordinate; this PR implements the explicit exact resolved-graph contract and finite symlink materializer.

[ORESoftware]

/ores-review

[ORESoftware]

DEN-3488 final certification receipt

The exact product head remains 86d499aff19807cee3500777ee4a9e48ea646821, ahead-only on current main at 5d0cbc0609703e7516e2185ea3c1749c9feda482.

Current-head product validation

Focused run 34060370621 is green:

• Ubuntu: exact-node detection, ORE structured logging, public parser, finite public-executable symlink graph, strict focused Clippy
• macOS: exact-node detection, public parser, finite public-executable symlink graph
• Windows: exact-node detection, ORE fields, graph/parser/platform-safety tests; Unix symlink executable test intentionally skipped

Independent test-org certification

Both acceptance PRs pin this exact product SHA and are merged:

• zed-pkg-test/version-solver-e2e#4 → merge 53e41714d99c1de5aee38fea95b552296e8baa8a
  • independent exact-node model
  • deterministic cycle witness
  • real finite symlinks and idempotent replay
  • pinned product unit/integration tests, format, focused Clippy, generated-harness contract, Ores lint
• zed-pkg-test/zed-pkg-e2e#179 → merge 06be3471fe4c460fdf4f751f3464b9005c29d4ea
  • Linux and macOS both built the exact release binary
  • both passed the independent public-CLI A1→B1→A2→B0→A2 fixture
  • both passed the pinned product executable regressions
  • exactly four canonical payload nodes; closing B0→A2 link reuses the original A2 node; replay reuses the same generation; copy mode fails closed before recursive expansion

Remaining promotion gate

/ores-review was requested on the current head, but there are still no ores-review/openai, ores-review/claude, or ores-review/gate check runs and no submitted independent reviews. I am therefore leaving this product PR open rather than bypassing the repository's fail-closed review policy.

Explicit follow-up boundary

Ordinary .zpkg.toml / .zpkg.lock v1 still selects one version per coordinate. The versioned-lock/normal-install migration is now tracked in zed-pkg/zed-cli#330, with compatibility, frozen replay, exact-node identity, and test-org acceptance criteria. That follow-up must reuse this PR's exact graph and symlink materializer rather than duplicate the cycle logic.

[ORESoftware]

/ores-review

Re-requesting exact-head review for 86d499aff19807cee3500777ee4a9e48ea646821 after confirming the dedicated circular-dependency workflow is green. Please keep the review bound to this SHA and evaluate the remaining non-focused workflow failures separately from the finite exact-node graph implementation.