argand-site-registry/docs/CONSUMERS.md

Consumer and compatibility contract

Rust library

Use release::verify_signed(generation, publisher_signers, publisher_identity, reviewer_signers) once per production generation and reuse the returned reader. Registry::open(generation, trusted_pin) is the lower-level path when the pin distributor is also trusted for the complete review decision. lookup(query, limit) returns evidence and complete ambiguity counts; resolve_explained returns a reviewed candidate or a typed abstention reason with counts. Exact reverse views cover entity IDs, URLs/domains, popularity and Curlie categories. Check the compiled example and API docs for exact types. selection_context binds the full alternative set for downstream query review. Preserve returned provenance, scopes, counts and attribution.

For local integration, point a Cargo dependency at crates/argand-site-registry inside an extracted standalone source tree. Once an upstream repository is published, use its actual Git URL and a full reviewed rev pin. Do not invent a crates.io version or track a mutable branch in production. Both crates remain in this workspace; the atomic helper is a relative dependency.

CLI and other languages

lookup, resolve, entity, lookup-web, popularity, category, stats, evaluate, verify and the other commands emit JSON. The Python example passes arguments directly to the native executable, preserving query text and the entire response. A nonzero exit is an error. destination: null is a successful abstention, not a request to pick the first lookup candidate. Render source names as untrusted text and satisfy their source-specific attribution requirements.

Use a bounded process or service wrapper appropriate to your workload. The Python example has a 60-second timeout and invokes a fresh reader per request; for repeated low-latency queries, use the reusable Rust reader. No hosted API or Python package registry publication is claimed by this repository.

SQLite, JSONL and license scope

Distribute registry.sqlite, COMPLETE.json, LICENSE_SOURCES.md and ATTRIBUTION.json together, plus the publisher signature when applicable. The database contains audit records and source descriptions. Default JSONL export omits descriptions and includes fact provenance plus an attribution envelope. It is an assertion export, not a self-contained signed list of admitted routes. Raw SQL inspection is useful for audit; it does not implement resolution policy.

Code version 0.3.0 uses schema version 3 and argand.site-rules/v3. It adds reviewer-trust enforcement for consumers, private authenticated SQLite snapshots, exact-stream import checks, bounded outputs and metadata-bound identity decisions. Schema/rule contracts remain versioned independently in receipts. Unsupported contracts fail closed. Pin source releases, compile consumers and replay fixed fixtures before upgrades. Preserve import and review history; never mutate complete generations to migrate them.

Argand integration

UPSTREAM.json pins the exact Argand source baseline, including the beta agent's selection-context API. The first standalone extraction preserves runtime Rust and migration bytes. Argand main commit d9dfd1585ce21d9c4136bcc24fa01fe3bfb8ed6e replaced its embedded workspace crate with this signed v0.3.0 release at full Git revision ac8282093d8a815c6227cff86e1f40714d510bcd.

Develop the library here and update Argand through explicit reviewed revision-pin changes. Each update must compare the old and new contracts and rerun Argand's navigation compiler and API gates. Preserve existing registry receipts and public navigation admission; a source dependency change does not activate a registry generation or approve a destination.