swift-secp256k1: Instructions file for Codex

AGENTS.md (swift-secp256k1)

A Swift 6.1 wrapper around libsecp256k1 for the Bitcoin and Nostr ecosystems. Supports macOS 15+, iOS 18+, watchOS 11+, tvOS 18+, and visionOS 2+. Uses Swift 6 strict concurrency (swiftLanguageModes: [.v6]).

Commands

• Build: swift build
• Test: swift test
• Format: swift package swiftformat . (dev checkout only)
• Lint: swift package swiftlint (dev checkout only)
• Install Lefthook hooks (one-time, dev checkout only): lefthook install
• Install vendir (needed only to re-sync vendored sources): brew install carvel-dev/carvel/vendir — it tracks latest, so check vendir version against the pinned version named in "Extraction flow" below (exact binaries live on the vendir GitHub releases page)
• Vendored-tree freshness gate: Scripts/vendir-check.sh [check ...] (bare run = all checks; needs vendir + yq). allowlist fails vendir.yml on keys or values outside the declared set (vendir drops unknown keys silently); resolve asserts each committed ref: resolves upstream to the lock's SHA (an unsynced ref: edit fails named); sync runs vendir sync --locked in a throwaway worktree of HEAD, then asserts a clean porcelain over the managed paths; locksha fails when entries sharing a git.url record different lock SHAs — the backstop for a literal typed in place of the shared &secp256k1-ref alias; ignorepaths probes raw.githubusercontent.com at each locked SHA and fails when a declared ignorePaths path exists upstream — the tripwire for a future upstream file being silently shadowed by a preserved shim (entries probe under newRootPath/ when the contents entry re-roots; exact-404-only pass, and only after an "anchor" file committed outside the ignore list answers 2xx — a dead pin 404s identically to an absent file; an entry naming a committed directory is a local finding; 429/5xx and transport trouble retried via curl's own backoff, then reported couldn't-verify). All five assert committed state (HEAD, not the working tree) — safe on a dirty working tree, but useless as a pre-commit hook. Exit 0 clean / 1 any drift found (dominates) / 2 nothing found but a check couldn't run.
• Vendored-tree gate self-test: Scripts/vendir-check-test.sh [substring] — exercises vendir-check.sh against committed mktemp git fixtures (a PATH-stubbed spy curl covers the ignorepaths verdict branches hermetically; file:// fixture remotes run under a per-case VENDIR_CHECK_ALLOW_PROTOCOLS=file:https widening), then asserts the gate passes on the real tree. VENDIR_CHECK_TEST_OFFLINE=1 shrinks the real-tree leg to allowlist locksha for networkless runs.