argand-site-registry/docs/TRUST.md

# Trust and evidence policy

Argand Site Registry is designed to fail closed. Imported assertions and crawler
observations become review evidence. Only policy-qualified votes can make a name
or destination resolvable, and only a separately authenticated generation should
reach consumers.

## What the implementation enforces

Source adapters accept only documented providers and formats. V3 manifests bind the
exact object, origin URL, source-native snapshot, license, retrieval time, byte
length, local digest, source-bound provider checksum where available, per-record
parser ceiling, typed coverage and declared lineage. Full, partition and delta graphs reject gaps,
cycles, overlap, cross-provider replacement and ambiguous active branches. Failed
or incomplete imports cannot replace complete evidence.

URL and domain normalization is deterministic and uses the complete retained
Public Suffix List, including PRIVATE rules. Names and hostnames never merge
entities. Source-specific popularity stays separate from identity. Every fact
keeps source, source identifier, selector, license, retrieval time, confidence and
raw evidence needed for audit.

Lineage declares the direct provider, known upstream datasets, provider
transformations and a conservative independence group. ROR location metadata, for
example, records GeoNames upstream. Unknown legacy lineage stays unknown. Source
assertion count is not reviewer quorum: the current policy grants authority only
to authenticated reviewer identities, independent groups and physical keys, so
two providers cannot manufacture approval by copying one upstream claim.

Names, entity-to-property edges and entity equivalences have independent material
fingerprints. Under the reference policy, `resolve` needs two independent votes
for the matched name and two for the selected edge. Reviewer groups and physical
SSH public keys are deduplicated, so aliases for one person or key do not satisfy
quorum. Regional roles require explicit locale or country scope.

A vote signs exact JSON in the `argand-site-registry-vote` namespace and binds the
current assertion, evidence bundle and policy epoch. The writer supplies
`accepted_at`; effective validity starts at the later of acceptance and the
reviewer's time and ends no later than 90 days after acceptance. Future, expired,
wrong-policy, stale-evidence, malformed, untrusted and altered votes do not count.

A retained authenticated revocation is sticky across policy epochs. It blocks
the exact subject until every member of a complete fresh quorum explicitly
supersedes every active revocation ID. Sequence order alone cannot restore a
route. Activation prevents rollback past retained legacy or vote revocations.

A cumulative emergency feed carries the same granular revocation identities under
a distinct publisher signature namespace. Compatible pinned consumers apply it
before name, equivalence, and edge selection. Replacement feeds cannot discard
previous subjects or vote IDs. Cross-generation feeds can only add blocks; a block
can be cleared only against the exact full generation containing the authenticated
superseding quorum. Feed artifacts expire after seven days and must be refreshed.

The observer accepts only an eligible imported edge. It uses public DNS pinning
for every hop, rejects credentials, private/link-local/reserved targets,
nondefault ports and HTTPS downgrade, and bounds time, redirects, response headers,
raw body bytes, bandwidth and extracted links. It rejects compressed bodies and
redirect loops. Capture replay checks the complete chain and
body digest without network access. HTTP, redirect, canonical, hreflang, JSON-LD,
sitemap, country-selector, DNS, TLS and failure records remain observations. They
cannot approve a name, ownership relationship or role.

The observation contract also accepts rights-reviewed domain-registration state
and malware-policy results without naming a vendor. No such provider is built in;
an operator must verify commercial-reuse terms and preserve its exact source and
rights declaration before importing those records.

Compact generations bind authenticated SQLite bytes, selected coverage, policy, reviewer
trust bytes, licenses, attribution, and decision-time rules into `COMPLETE.json`.
Readers verify the receipt pin and copy the database into a private unlinked file
before SQLite opens it. Release signing and activation reverify every stored
signature. The strict policy rejects a publisher identity or physical key used for
any reviewer vote.

Complete historical records and facts live in content-addressed cold bundles bound
by the same receipt. Their verifier hashes the exact no-follow file descriptor and
checks bytes, JSON order, source identity, selection state, counts, coverage and
attribution. Runtime lookup cannot weaken when cold storage is offline; audit
export and retention fail closed. A separately signed no-delete checkpoint makes
the retained object set explicit without adding deletion authority.

## What a publisher must establish

The software verifies evidence integrity and decision authorization. A publisher
still has to determine that the source and observation evidence support the exact
entity, URL, relationship and role. TLS, DNS control, a redirect, `sameAs`, ccTLD,
popularity or source confidence alone is insufficient.

Publishers should:

- keep acquisition, writer, reviewer and release authorities separate;
- protect reviewer and publisher keys outside the repository and CI;
- configure real organizational reviewer groups instead of relying only on unique
  identity strings;
- examine conflicts and current independent evidence in each review bundle;
- choose shorter expiries for volatile or high-risk routes;
- refresh observation evidence independently from source import cadence;
- review drift and produce signed emergency revocations promptly;
- run diff, evaluation, license and signature gates before release; and
- preserve source objects, generations, trust roots, pins and revocations for
  audit and recovery.

Changing policy or reviewer trust produces a different receipt. It does not
silently reinterpret old votes as decisions under the new policy. Removing a key
can also make retained signature verification fail; plan rotations with OpenSSH
validity epochs and immutable history.

## What consumers must preserve

Authenticate the publisher and reviewer trust roots independently, or obtain the
full receipt pin over a channel that is already trusted for the complete release
decision. A hash beside an untrusted download authenticates nothing.

Use `resolve` for navigation. `lookup`, exports, raw SQLite rows and observation
views are audit evidence and can include unreviewed, conflicting, superseded or
malicious claims. Preserve null destinations and typed abstention reasons. Apply
application-specific malware, content and destination policy because a legitimate
site can later be compromised.

Keep license and attribution artifacts with caches and derived datasets. Bound
cache lifetime by vote expiry and revocation delivery. A detached URL copied from
an earlier result no longer performs policy, freshness or rollback checks.

## Community submissions

Treat public issues, manifests, source files, captures and vote proposals as
untrusted input. They may suggest evidence but cannot write the protected store,
approve, publish or activate a generation. Unknown providers remain unsupported
until current commercial-reuse rights, format, lineage, attribution and tests are
reviewed. Public contribution does not imply production admission.