From 0bcd4a2fc9aa4e27ee2c401f9ed44cd851127ca8 Mon Sep 17 00:00:00 2001 From: nicweyand Date: Sat, 12 Sep 2026 21:47:36 -0400 Subject: [PATCH] docs: record standalone validation and publication policy --- README.md | 19 +++++-- docs/INDEX.md | 1 + docs/VALIDATION.md | 55 +++++++++++++++++++ .../plans/2026-09-12-standalone.md | 30 +++++----- 4 files changed, 88 insertions(+), 17 deletions(-) create mode 100644 docs/VALIDATION.md diff --git a/README.md b/README.md index 7344c2e..df82cde 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,14 @@ return a destination; source confidence is not a malware-safety guarantee. Linux is the currently validated platform. Install Rust (tested with 1.98.1; the inherited minimum is 1.97), a C compiler, CMake, Perl and OpenSSH (`ssh-keygen`). Python 3.11+ is needed for release tooling and the Python example. SQLite is built -with the binary. From the root of this source checkout or extracted release: +with the binary. Get the public source, or use a verified source release: + +```bash +git clone https://git.argand.org/nicweyand/argand-site-registry.git +cd argand-site-registry +``` + +From the root of the checkout or extracted release: ```bash cargo fetch --locked @@ -102,9 +109,13 @@ documentation, Python release tests, and native Rust/Python consumer parity. verification and rebuilding outside the checkout. The Forgejo workflow requires a dedicated isolated runner; it has no signing or dataset-promotion authority. +The [validation record](docs/VALIDATION.md) reports the initial independent builds +and native acceptance. Hosted CI requires runner provisioning; the workflow is +included and Actions remains disabled until an isolated runner is ready. + The code remains **AGPL-3.0-or-later**; the complete license is in [LICENSE](LICENSE). Original attribution is retained. [UPSTREAM.json](UPSTREAM.json) records the signed Argand extraction revision and original file hashes. This initial independent -package preserves the existing registry runtime and schema. Hosted publication, -runner provisioning and changing Argand's dependency require separate completion; -the initial extraction does not itself establish any of those states. +package preserves the existing registry runtime and schema. Argand still uses its +embedded copy; its switch to a pinned upstream release is a coordinated downstream +change. This repository does not operate a public approved-link dataset. diff --git a/docs/INDEX.md b/docs/INDEX.md index 0a3571e..59f353f 100644 --- a/docs/INDEX.md +++ b/docs/INDEX.md @@ -7,6 +7,7 @@ - [Consumers](CONSUMERS.md): Rust, Python/CLI, data distribution and Argand transition. - [Trust](TRUST.md): enforced checks and publisher/consumer responsibilities. - [Releasing](RELEASING.md): CI, source signing and archive verification. +- [Validation](VALIDATION.md): independent builds and native acceptance evidence. - [Contributing](../CONTRIBUTING.md), [governance](../GOVERNANCE.md), [security](../SECURITY.md): proposals, decisions and incidents. - [Extraction design](superpowers/specs/2026-09-12-standalone-design.md) and diff --git a/docs/VALIDATION.md b/docs/VALIDATION.md new file mode 100644 index 0000000..a49e814 --- /dev/null +++ b/docs/VALIDATION.md @@ -0,0 +1,55 @@ +# Initial standalone validation, 2026-09-12 + +Implementation commit: `2a0fe1714b8ffb2e80203722bcb7987c630f432d`, signed by Nic Weyand. +The subsequent completion documentation changes no runtime or packaging code. + +The baseline is Argand commit `47911062b00d87f215ba61c41965faf8a7f4b7f7`. +All extracted Rust, migration and provider-license bytes match UPSTREAM.json. +The extracted operator README changes only its working-directory instruction. +New files provide independent build metadata, examples, policy and release tooling. +The lockfile shrank from 642 packages to 246 with no new dependency versions. + +## Acceptance + +Linux x86_64, Rust/Cargo 1.98.1, Python 3.14, two Cargo build jobs. Passed: + +- Rust formatting, all-target compilation and Clippy with warnings denied. +- All 23 Rust tests, zero failures or ignored tests; strict API documentation. +- Eight Python source-release tests, Python syntax checks, shell syntax and + ShellCheck for the check script and every workflow shell step. +- Native all-five-source fixture import, idempotency, alias lookup, explicit + identity joining, signed approval/activation, revocation and rollback refusal. +- Identical native CLI, Rust library example and Python example lookup envelopes, + including provenance, attribution and multiple regional properties. Every + consumer refused an incorrect generation pin. +- Two source archives and receipts from the implementation commit were byte-for-byte + identical. Receipt pin: `811af8fe2fd1e747b7745a44dba24e2397c01b43381e11846753e284caf6a275`. +- Full acceptance rerun from the verified archive outside the Git checkout, then + from `/tmp` to exclude the developer's ancestor Cargo configuration. Neither + extracted copy had a `.git` directory or accessed Argand's source tree. + +The primary check took 28.24 seconds with 566,388 KiB peak process RSS after the +initial compiler check. A separate optimized build took 84.15 seconds with +602,340 KiB peak RSS. The archive check under `/tmp` took 101.64 seconds with +569,228 KiB peak RSS, including recompilation. These are local single-run toolchain +measurements, not serving-latency or full-provider capacity claims. Build output, +fixtures, disposable keys and detailed logs were retained outside the repository. + +The final initial inventory was reviewed for credentials, private paths, datasets, +unrelated files and provenance loss. Source archives exclude private-key and dataset +extensions, symlinks, submodules, traversal paths and uncommitted changes. Tests +exercise receipt/archive tampering, duplicate JSON keys, unsafe members and +no-clobber output. All documentation links resolve locally. + +## Operational state + +The code is independently buildable. The public Forgejo repository requires +signed commits and restricts direct pushes and merges to the maintainer; review +rules apply to administrators. CI workflow commands were validated locally. +Actions is disabled pending a dedicated isolated runner, so there is no hosted CI +run or automatically produced remote artifact claim. + +No provider dataset was newly acquired, no production approval was fabricated, +and no dataset timer, public Navigate route or registry generation was promoted. +Argand's live source/build window remained with its beta agent. Its embedded +registry dependency has not been replaced; docs/CONSUMERS.md describes cutover. diff --git a/docs/superpowers/plans/2026-09-12-standalone.md b/docs/superpowers/plans/2026-09-12-standalone.md index 42fd6d5..93c1ef9 100644 --- a/docs/superpowers/plans/2026-09-12-standalone.md +++ b/docs/superpowers/plans/2026-09-12-standalone.md @@ -14,24 +14,28 @@ around their existing APIs. Use an isolated build directory. - [x] Verify signed Argand commit 47911062b00d87f215ba61c41965faf8a7f4b7f7. - [x] Export only `engine/crates/argand-site-registry` and `engine/crates/argand-atomic`. - [x] Write `UPSTREAM.json` with original path/blob/hash evidence and a two-crate `Cargo.toml`. -- [ ] Prune the inherited lock with `cargo metadata --offline --format-version 1`; retain exact dependency versions. +- [x] Prune the inherited lock with `cargo metadata --offline --format-version 1`; retain exact dependency versions. ### Task 2: Make standalone use and trust policy concrete -- [ ] Add root README, LICENSE, source-license entrypoint, CONTRIBUTING, SECURITY and governance docs. -- [ ] Add Rust `examples/lookup.rs` and Python `examples/lookup.py` consumers of existing query contracts. -- [ ] Run both consumers on the native fixture and compare full lookup outputs, including attribution. +- [x] Add root README, LICENSE, source-license entrypoint, CONTRIBUTING, SECURITY and governance docs. +- [x] Add Rust `examples/lookup.rs` and Python `examples/lookup.py` consumers of existing query contracts. +- [x] Run both consumers on the native fixture and compare full lookup outputs, including attribution. ### Task 3: Package and verify source releases -- [ ] Add deterministic source archive and verification commands in `scripts/source_release.py`. -- [ ] Test determinism, dirty-tree refusal, no-clobber, tampering and unsafe archive members in `tests/test_source_release.py`. -- [ ] Add `scripts/check.sh` and `.forgejo/workflows/ci.yml` using an isolated runner without release secrets. -- [ ] Document explicit release signing, downstream pins and incident response in `docs/RELEASING.md` and `docs/TRUST.md`. +- [x] Add deterministic source archive and verification commands in `scripts/source_release.py`. +- [x] Test determinism, dirty-tree refusal, no-clobber, tampering and unsafe archive members in `tests/test_source_release.py`. +- [x] Add `scripts/check.sh` and `.forgejo/workflows/ci.yml` using an isolated runner without release secrets. +- [x] Document explicit release signing, downstream pins and incident response in `docs/RELEASING.md` and `docs/TRUST.md`. ### Task 4: Validate and land the bounded task -- [ ] Run `cargo fmt --all -- --check`, `cargo check --workspace --all-targets --locked --offline`, +- [x] Run `cargo fmt --all -- --check`, `cargo check --workspace --all-targets --locked --offline`, `cargo clippy --workspace --all-targets --locked --offline -- -D warnings`, `cargo test --workspace --locked --offline` and strict `cargo doc`. -- [ ] Build the native executable and retain the all-five-source CLI fixture outside the repo. -- [ ] Rebuild/run tests from the release archive outside the original workspace. -- [ ] Review every initial tracked file and dependency change, sign the local commit and release receipt. -- [ ] Record exact validation, publication and Argand cutover state; release any coordination window. +- [x] Build the native executable and retain the all-five-source CLI fixture outside the repo. +- [x] Rebuild/run tests from the release archive outside the original workspace. +- [x] Review every initial tracked file and dependency change, sign the local commit and release receipt. +- [x] Record exact validation, publication and Argand cutover state; release any coordination window. + +Acceptance and operational limits are recorded in `docs/VALIDATION.md`. +The public repository is created with Actions disabled until an isolated runner +is provisioned. Argand remains on its embedded dependency; no shared window was taken.