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. The last recorded downstream integration replaced Argand's embedded crate with signed v0.3.0 revision ac8282093d8a815c6227cff86e1f40714d510bcd at Argand commit d9dfd1585ce21d9c4136bcc24fa01fe3bfb8ed6e.

Version 0.5 is handed off as a signed standalone revision. Argand should update its full Git rev in a separate coordinated source/build window, compare contract changes, and rerun navigation compiler, native resolver, API, abstention, revocation and clean-process gates. Changing the code dependency does not activate a registry generation or approve a public destination.

5.9 KiB Raw Permalink Blame History