argand-site-registry/docs/CONSUMERS.md

Consumer and compatibility contract

Rust library

Use argand_site_registry::query::Registry::open(generation, trusted_pin) once per immutable generation and reuse the reader. 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.2.0 uses schema version 2 and argand.site-rules/v2. It adds authenticated reviewer proofs, exact immutable SQLite opening, typed diffs and audit/evaluation APIs. 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 transition

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 currently consumes its embedded workspace crate; this package does not silently redirect that dependency.

At cutover, coordinate with the Argand source/build owner, compare both trees with the recorded baseline, carry any subsequent fixes forward, replace the embedded dependency with a reviewed standalone revision, and run Argand's complete engine and navigation-compiler gates. Preserve existing registry receipts and public navigation admission. After cutover, develop the library upstream and update Argand through explicit pinned dependency changes, avoiding permanent dual copies.