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:

```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
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:

```bash
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**:

```bash
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](crates/argand-site-registry/README.md) 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](crates/argand-site-registry/examples/lookup.rs) opens a generation
once with an externally trusted receipt hash and returns the full lookup envelope.
The [Python example](examples/lookup.py) calls the same native CLI; it does not
implement a second resolver. Both preserve attribution and fact provenance.

```bash
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](docs/CONSUMERS.md) 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](LICENSE_SOURCES.md) before redistribution.
Curlie attribution applies to names and categories as well as descriptions.

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

## Development and releases

```bash
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](docs/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](docs/VALIDATION.md) 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](LICENSE).
Original attribution is retained. [UPSTREAM.json](UPSTREAM.json) records the signed
Argand extraction revision and original file hashes. Version 0.3 advances the
standalone database to schema version 3; the migration and consumer rules are
documented in [CONSUMERS.md](docs/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.