argand-site-registry/README.md

Argand Site Registry

Evidence-backed website identity and regional resolution, as a Rust library and CLI.

Look up an entity's names, aliases and websites; inspect each source assertion; resolve an explicitly reviewed primary or regional destination. Sources, conflicting claims, licenses and review history remain available for audit. Everything runs locally with SQLite. No search engine, hosted account or GPU is required.

facebook → Facebook → facebook.com is a name-to-entity-to-registrable-domain lookup. The retained real Wikidata Facebook record has www.facebook.com and m.facebook.com as distinct properties. Its Amazon record includes amazon.com, amazon.co.uk and amazon.de on the same entity. Similar hostname spelling never establishes common ownership. Imported links await review before resolve can return a destination; source confidence is not a malware-safety guarantee.

Build and try it

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. Get the public source, or use a verified source release:

git clone https://git.argand.org/nicweyand/argand-site-registry.git
cd argand-site-registry

From the root of the checkout or extracted release:

cargo fetch --locked
cargo build --release --locked --offline -p argand-site-registry
./target/release/argand-site-registry --help

If your Cargo configuration sets a different target directory, set CARGO_TARGET_DIR="$PWD/target" before these commands. To install the CLI:

cargo install --path crates/argand-site-registry --locked --offline
argand-site-registry --help

Run the native all-source example in a new directory outside the checkout:

ARGAND_REGISTRY_E2E_OUTPUT=/tmp/site-registry-example \
  cargo test -p argand-site-registry --test cli --locked --offline -- --nocapture

It imports synthetic Wikidata, Majestic, CrUX, Curlie and PSL fixtures, checks idempotency, joins explicitly reviewed identities, approves a destination, signs and activates it, revokes it, and rejects rollback past that revocation. Fixture signing keys and approvals are disposable test material. All production inputs belong in a configurable data/cache directory outside the source checkout.

Follow the operator guide for actual downloads, imports, regional reviews, signed datasets and weekly candidate updates. CrUX acquisition requires explicit credentials and a billing cap. No source downloads or scheduled jobs run during installation or tests.

Use it in another project

The Rust example opens a generation once with an externally trusted receipt hash and returns the full lookup envelope. The Python example calls the same native CLI; it does not implement a second resolver. Both preserve attribution and fact provenance.

cargo run --locked --offline -p argand-site-registry --example lookup -- \
  --generation /data/registry/generation --pin "$REGISTRY_TRUSTED_PIN" --query facebook

python3 examples/lookup.py --binary ./target/release/argand-site-registry \
  --generation /data/registry/generation --pin "$REGISTRY_TRUSTED_PIN" --query facebook

Obtain the pin from a trusted publisher channel or verify the release signature against an independently configured key. Reading a hash from the same untrusted download does not authenticate it. Never turn lookup.candidates[0] into an automatic destination: use the native resolve result and your application's own admission policy. A null destination is a meaningful abstention.

The consumer contract covers Rust dependencies, CLI JSON, SQLite/JSONL distribution, compatibility and Argand's eventual upstream cutover. Exact entity, URL/domain, source-separated popularity and redacted Curlie category queries support audit tools. resolve also reports a stable abstention reason and decision counts. The bounded evaluate command replays JSONL judgments and reports accuracy plus native p50/p95 latency for one pinned generation.

Sources and trust

Wikidata (CC0), Majestic Million (CC BY 3.0), CrUX (CC BY 4.0), Curlie (CC BY 3.0) and the Public Suffix List (MPL 2.0) remain logically separate. Read the exact source licenses and attribution rules before redistribution. Curlie attribution applies to names and categories as well as descriptions.

The trust policy explains enforced checks, publisher responsibilities, evidence standards, expiry and revocation. The publisher runbook covers authenticated reviewer decisions, candidate inspection and activation. CONTRIBUTING.md, GOVERNANCE.md and SECURITY.md cover contributions, decisions, disputes and incidents. Pull requests cannot directly approve destinations.

Development and releases

cargo fetch --locked
bash scripts/check.sh

The check runs formatting, all-target compilation, strict Clippy, Rust tests and documentation, Python release tests, and native Rust/Python consumer parity. RELEASING.md covers deterministic source archives, signature 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 reports independent builds and native acceptance. Hosted checks use the repository's isolated Forgejo runner label and have no dataset, review, signing or activation authority.

The code remains AGPL-3.0-or-later; the complete license is in LICENSE. Original attribution is retained. UPSTREAM.json records the signed Argand extraction revision and original file hashes. Version 0.2 advances the standalone database to schema version 2; the migration and consumer rules are documented in CONSUMERS.md. 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.