Skip to content

Implement bidirectional sync v2 for SchLib, PcbLib, SchDoc, and PcbDoc - #10

Draft
akiselev wants to merge 7 commits into
masterfrom
agent/bidirectional-sync-v2
Draft

Implement bidirectional sync v2 for SchLib, PcbLib, SchDoc, and PcbDoc#10
akiselev wants to merge 7 commits into
masterfrom
agent/bidirectional-sync-v2

Conversation

@akiselev

Copy link
Copy Markdown
Owner

Summary

  • introduce the altium-spec-lang source/intent boundary with lossless source retention, source IDs, generic top-level resource discovery, and explicit inherit / set / clear / reset semantics
  • implement altium-sync as a three-way synchronization engine with durable bindings, versioned external baselines, conservative conflict classification, persisted self-contained plans, semantic ECO rendering, and transactional apply helpers
  • route SchLib, PcbLib, SchDoc, and PcbDoc plan/apply/dump through sync v2
  • make saved plans executable in both directions
  • materialize exact Altium document bytes at plan time; document apply stages/reopens/verifies/commits those exact bytes instead of re-running mutation logic
  • use exact source patches for dump plans
  • fix stale PR CI references to the removed altium-format-ops package

CLI

altium plan design.pcbdoc-spec --target design.PcbDoc --out-plan design.plan.json
altium apply --plan design.plan.json

altium dump design.PcbDoc --plan --out-plan design.dump-plan.json
altium apply --plan design.dump-plan.json

Plan drift now exits with status 2; errors remain status 1.

Safety properties

  • apply never re-plans
  • source/document/baseline preconditions reject stale plans, including file creation/deletion races
  • document-only drift blocks compile; source-only drift blocks dump
  • simultaneous drift conflicts instead of being guessed as the same change
  • no fuzzy identity matching
  • whole-file semantic coverage prevents syntax outside discovered resource blocks from escaping drift detection
  • document mutation is staged, reopened through altium-format, semantically verified, journaled, then committed
  • baselines advance only after successful apply

Validation

  • cargo fmt --all -- --check
  • cargo test -p altium-spec-lang -p altium-sync -p altium-cli
  • corpus-backed workspace tests with SchLib, PcbLib, SchDoc, PcbDoc, and IntLib fixture repositories mounted; seven pre-existing tests requiring the unavailable root fixture data/BlankSchlibComponent.SchLib were skipped
  • final head: warnings-as-errors Clippy for altium-spec-lang and altium-sync; normal no-deps Clippy for CLI integration (the CLI has pre-existing lint debt outside this change)

Scope / follow-ups

  • PrjPcb and IntLib remain on legacy orchestration
  • planning still uses the existing altium-format-spec semantic materializer behind the new planner boundary; apply correctness is independent of it because document plans carry the exact materialized CFB bytes
  • durable per-primitive bindings for every keyless PcbDoc/PcbLib primitive are represented by the identity model but remain conservative/aggregate in this PR where a trustworthy persistent mapping is not yet available
  • PcbDoc compile still requires an existing target
  • journaled commit/rollback exists; automated crash-recovery replay is not part of this PR

@akiselev
akiselev force-pushed the agent/bidirectional-sync-v2 branch from d08faec to d47cb90 Compare August 16, 2026 04:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant