# 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 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.