docs(env): record the macOS clang/Xcode link hazard and refresh Cargo.lock (#77)

OW
20d ago
+445-237

What

Closes out #77 (see the issue for the full analysis and the task ledger in tasks/issue-77-…md).

  • Docs: AGENTS.md and .github/instructions/rust.instructions.md now record the macOS link hazard — cc on PATH resolving to a Homebrew/mise clang older than the installed Xcode SDK, failing on the SDK's .tbd stubs — plus the workaround (RUSTFLAGS="-C linker=/usr/bin/cc"; CC does not help) and a link to #77.
  • Cargo.lock: folds in a lock-only refresh carried over from a local cargo update (103 packages bumped, 2 added, 0 removed, no major jumps). Manifests untouched.
  • Task ledger for #77 updated with the outcome of every task.

The interesting part: the fix turned out not to be needed

The issue's prescribed work was T002 — apply a linker fix (machine config or a committed .cargo/config.toml) so the workspace links with no per-command override. I drafted the committed .cargo/config.toml the maintainer picked, then verified it before committing, and found the failure no longer reproduces:

  • RUSTFLAGS/CC/CARGO_TARGET_*_LINKER unset → cargo build --workspace exit 0, cargo test --workspace 59 passed, and cc -o /tmp/x /tmp/x.c exit 0.
  • Counterfactual: with .cargo/config.toml removed, a cargo clean -p + rebuild still exits 0.
  • Cause: cc is mise-managed clang pinned latest in the global ~/.config/mise/config.toml, so mise updated it. The old clang failed against the same Xcode 27.0; clang 23.1.2 links fine.

So a committed pin — a machine-specific absolute path with no reproducible failure behind it — would not have survived review. Dropped it: git diff here is docs + lock only. The docs are written as a hazard that tracks the clang/SDK pairing, which is why nothing is pinned in the repo.

Also folded in: T004 was already completed by #79 (project rustfmt.toml + cargo fmt --check in CI and the gate), superseding the nightly-rustfmt route the task described, and T006's stray rust-toolchain.toml was resolved by #79 too.

Verification

Full six-step gate on the exact tree, with all override env vars unset:

stepresult
cargo fmt --checkclean
cargo build --workspaceexit 0
cargo build --workspace --features iklo-cli/tursoexit 0
cargo test --workspace59 passed, 0 failed
cargo test --workspace --features iklo-cli/turso90 passed, 0 failed
cargo clippy --workspace --all-targets --features iklo-cli/turso20 warnings, the same pre-existing set as main

cargo build --locked --workspace accepts the refreshed lock (release.yml runs --locked).

Closes #77

Note for reviewers

.gitignore lists Cargo.lock even though the file is tracked, so ignore rules don't apply to it. Untouched here — flagging it as a separate cleanup.

Summary by Sourcery

Document the macOS linker hazard, refresh dependency locks, and record the verified resolution of issue #77 without introducing a repository configuration change.

Enhancements:

  • Document the macOS clang/Xcode SDK linker compatibility hazard and its available workaround without adding a machine-specific repository linker pin.

Build:

  • Refresh Cargo.lock with updated dependency resolutions while leaving package manifests unchanged.

Documentation:

  • Add macOS linker troubleshooting guidance and issue references to the contributor and Rust development instructions.

Tests:

  • Record completion of the issue task ledger and the successful full workspace quality-gate verification.

Chores:

  • Capture the resolved outcomes of the issue's environment and toolchain tasks, including work superseded by earlier changes.

Summary by cubic

Documents a macOS build hazard where cc on PATH resolves to a Homebrew/mise clang older than the installed Xcode SDK, causing linking to fail on the SDK's .tbd stubs, and records the RUSTFLAGS="-C linker=/usr/bin/cc" workaround in AGENTS.md and .github/instructions/rust.instructions.md.

  • A committed .cargo/config.toml linker pin was dropped after the failure stopped reproducing — a mise-managed clang upgrade fixed it, so the docs treat this as a clang/SDK version-pairing hazard instead.
  • Cargo.lock only refreshes lockfile entries (103 transitive bumps, 2 added, no major jumps); manifests are untouched.
  • The tasks/issue-77-…md ledger records the outcome of every task, including T004 superseded by #79, and incorporates review notes (clearer clippy command, no absolute paths, no stale checklist references).

Summary by CodeRabbit

  • Documentation
    • Added macOS linker troubleshooting guidance, including a workaround and an explanation of why setting CC may not resolve the issue.
    • Documented how the installed compiler and Xcode SDK versions can affect linking.
    • Recorded the investigation and resolution of the linker issue.