nicweyand
e83f43d00f
All checks were successful
Standalone registry checks / check (push) Successful in 3m43s
61 lines
3.5 KiB
Markdown
61 lines
3.5 KiB
Markdown
# 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.
|