nicweyand
16c740a98f
Some checks failed
Standalone registry checks / check (push) Has been cancelled
115 lines
6.1 KiB
Markdown
115 lines
6.1 KiB
Markdown
# 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](MIGRATING-0.4.md) and [FORMATS.md](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.
|