Consumer and compatibility contract

Use the policy-enforced reader

For a production generation, call release::verify_signed(generation, publisher_signers, publisher_identity, reviewer_signers) once and reuse the returned Registry. Registry::open is the lower-level API for deployments that already trust an exact COMPLETE.json SHA-256 for the whole publication decision.

lookup returns source evidence, candidates, ambiguity counts and attribution. resolve_explained returns either one policy-qualified destination or a typed abstention. It requires an approved name binding and approved edge under the receipt's policy. Preserve the full response, especially destination: null, status, counts, selected scope, evidence and attribution.

Reverse views cover entity IDs, exact URLs, hostnames, registrable domains, source-specific popularity, Curlie categories and observations. They are audit operations and do not imply ownership or admission.

CLI and other languages

Every CLI command emits one JSON value to stdout; typed export and diff commands write bounded JSONL files. A nonzero exit is an error. A successful resolution with a null destination is an intentional abstention, not an instruction to use the first lookup result.

The Python example passes an argument array directly to the native CLI and keeps its 60-second timeout and complete JSON response. Use the Rust reader for repeated low-latency queries. No hosted API, crates.io release or Python package is claimed.

Render all imported names, categories, URLs and evidence as untrusted data. Apply source attribution and application-specific malware/content policy.

Current contracts

Code version 0.5.0 uses writer schema 5 and argand.site-rules/v4. New compact COMPLETE.json files use argand.site-registry/v3 and bind:

authenticated registry.sqlite bytes;
the active source coverage graph and exact PSL source;
review policy and exact reviewer trust-root bytes;
decision-time policy;
source license and machine-readable attribution files; and
entity, property, edge and rejection counts.
every cold audit bundle's digest, size, counts, source, selection state, attribution digest and coverage digest.

Normal export uses argand.site-export/v2, contains selected active nonrejected facts, and marks every assertion active. export-audit uses the same schema with mode audit for v2 generations. Compact generations require their external audit store and emit argand.site-export/v3 after verifying every referenced bundle. Both include superseded/rejected states and rejection reasons. Neither contains a list of resolver-approved routes.

Keep the audit store separate from the runtime deployment, replicate it by exact object digest, and run verify-audit before retention attestations or audit export. Runtime resolution verifies the compact generation receipt and database without opening cold history. A missing audit object therefore does not silently change a query, but it is an audit/retention failure and blocks any claim of complete provenance. Retention checkpoints never authorize deletion.

Votes use argand.site-vote/v1 and the OpenSSH namespace argand-site-registry-vote. Consumers compile them under the exact receipt-bound policy and trusted query time. Unknown schema or rule versions fail closed.

Emergency feeds use argand.site-revocations/v1 and the separate argand-site-registry-revocations namespace. Call revocation::verify against the cached Registry and publisher trust root, then use resolve_explained_with_revocations. The CLI accepts the same four feed arguments on resolve. It blocks exact revoked names, edges, and equivalences before route selection and can choose another approved edge. Verify each replacement against the previously accepted feed to enforce cumulative continuity. Feeds expire after seven days. A feed from a newer compatible generation may add blocks to a cached generation, but reinstatement requires installing the exact full generation so the consumer can recompute the authenticated superseding quorum.

CLI consumers pass the last feed and signature as --previous-revocations and --previous-revocation-signature on subsequent resolve calls. The Rust API passes the last VerifiedRevocations to revocation::verify before resolution.

Distribute registry.sqlite, COMPLETE.json, LICENSE_SOURCES.md, ATTRIBUTION.json, and COMPLETE.json.sig together. Obtain publisher and reviewer trust roots independently. Raw SQL copies and JSONL extracts do not implement resolution policy, expiry, revocation continuity or signature verification.

Compatibility

V1 source manifests remain readable as isolated legacy provider/scope streams. A deliberate legacy-compatible build policy can replay v0.3 reviews, but strict 0.4 builds require votes and reviewer trust. Current readers accept v2 and compact v3 receipts; rollback checks may open pinned v1 receipts with rules v1-v3 only to compare revocation history.

Before upgrading, pin the source release by full signed Git revision, compile the consumer and replay fixed fixtures. Preserve import, vote, observation and revocation history. Never mutate a complete generation to migrate it. See MIGRATING-0.4.md and FORMATS.md.

Argand integration

UPSTREAM.json records the original Argand extraction baseline and file hashes. Argand pins signed v0.5.0 revision 3d3e08cdfd303df9fbd347a9bab2ba52ad575759. The public beta uses Site Registry as Navigate's authoritative auto-route catalog. Its native navigation-catalog/v2 file is only a collection- and content-policy-bound serving projection compiled from one exact registry generation; it is not a second independently curated destination catalog.

Argand source commit 564ee5fc2fa0974a7b0557a914f274bbd4ab654c records that boundary and the first public-beta activation. Changing the code dependency alone still does not activate a data generation or approve a destination. Every downstream must verify the signed generation, preserve abstentions, apply its own safety policy, and bind any serving projection to its own eligible corpus or directory policy.

6.1 KiB Raw Blame History