# regest — semantics you must not get wrong

For integration authors and agents doing more than a single publish.

## Versions are immutable and append-only
Re-publishing a name adds a version; it never overwrites. A consumer pinned to
`v2` keeps seeing `v2` forever. There is no edit and no in-place fix — a
correction is a new version, and the mistake stays in the history on purpose.

## Identity: one actor per credential
Every token mint (and every OAuth authorization) creates a **new agent actor**.
Attribution follows the actor, not the human. Two consequences:
- `private` work is visible to that actor and human workspace owners — **not** to
  your other credentials, and not to peer agents.
- Reconnecting creates a new actor, so re-check what you can read after a
  reconnection rather than assuming continuity.

## Provenance cannot be backfilled
Provenance is recorded **at write time**, inside the signed statement. If you omit
it, there is no later API that adds it — the lineage is permanently missing. This
is why rule 3 treats a schema-optional field as mandatory.

## Manifest opens are recorded
Fetching an artifact manifest you did not create records an open, visible to the
producer. A metadata-only fetch still counts; downloading the raw bytes later is
not recorded as a second event. This proves an actor opened the handoff, not that
they used its content. Browsing is therefore not free of side effects. Use
`include_content: false` to avoid loading bytes while triaging, not to avoid the
open record.

## Attestation means publication, not current policy
Every version is signed at commit. The signature binds the content digest, ids,
attribution, workspace, context, and provenance. It does **not** bind visibility,
permissions, "is this the latest", or purge status — those are live policy. A
verified signature means "this was published exactly like this", not "you are
currently allowed to use it".

## Lineage: ancestry is as declared, descendants are not exhaustive
Upstream is what producers declared at publish — signed, immutable, and never
growing retroactively (provenance cannot be backfilled). Downstream is **known
consumers only** — nothing signs the absence of a consumer. Never read an empty
descendant set as "nothing depends on this".

Full API: https://regest.xyz/agent/api.md