Stable IDs
link-id names a thing by what never changes, <kind>:<id>, with one
generic every kind of ID rides. Who acts, what runs and one run of it
are three IDs of one grammar, so a module that measures, places or
grants never needs to know which program made them.
Three IDs
One agent is all three:
- Principal: who acts, or may: a user or a service, never
anything else. An agent acts as the service with its own ID,
service:<its ID>, which holds roles. Principal owns those two kinds on this generic, so callers share their grammar. - Workload: what runs, kept across its runs. The workload
agent:<its ID>is what's measured and what a box carries. A workload's kind is open: the module that keeps it names it, such asagentorjob, so this package names none. - Execution: one run of a workload,
<workload>@<run>, such asagent:a1b2c3d4e5f6@k3m4n5p6q7r8. Its run is allocated before the run starts and kept with its outcome, never a process's pid, which is reused.
Resources
A resource is what's acted on, such as a box, a bucket, a team or a
machine: Resource, whose kind is open like a workload's, named by the
module that keeps it. A box is box:<its machine ID> and a team's
group group:<its ID>. A resource is a grant's target, never who acts.
The generic
Id<K> is <kind>:<id>, a kind of K's, then an id Link minted:
src/limits.toml's candidate_length, 12, of its lowercase letters and
digits (is_id). A thing whose own ID comes from outside Link gets a
minted ID, with its outside ID a field beside it. Id::kind and
Id::id give back each part.
Closed and Open Kinds
A set of kinds implements Kind, which parses a kind, writes it back
and says what an ID of them is called in an error. A principal's kinds
are a closed list, user and service, which the account service's
API fixes. A workload's and a resource's are open: any name of lowercase letters, digits and -, from a letter,
at most KIND_MAX, 30, bytes (is_kind_name).
Made only by parsing
An ID is made only by parsing or by Id::new from a kind and an id
checked alike, so every one is well formed. What isn't one is NotOne,
saying why. Each is written as its string, in JSON and TOML alike.
An execution's run
An execution's run is 1 to RUN_MAX, 64, bytes: ASCII letters, digits
and RUN_PUNCTUATION, ._-. Neither a run nor an id holds @, so
<workload>@<run> splits only one way.
Parents
An execution's parent is the execution that started it, such as an
agent's start for each tool it runs. Lineage keeps an execution with
its parent and its depth, the number of parents above it. The parent is
a field beside the execution, never part of its ID, so nesting a run
changes no ID. An execution is never its own parent, and a chain ends at
parent_depth, 16 parents, from src/limits.toml. A lineage read from
JSON or TOML is checked the same way.
Minting
An ID is minted once, by the module that owns its kind, and never names another thing, even after what it named is deleted. A grant, a log line or a measure naming it never comes to mean something else. Why IDs work this way has the reasons.
Candidates
candidate draws a new ID's id at random: 12 lowercase letters and
digits, each as likely as another, which fit a file name, a service
name, a cloud label and a bucket name. Its length and alphabet are in
src/limits.toml. is_candidate says whether an id has that shape. A
candidate is only a proposal, since two draws may meet.
Reservations
An owner keeps a ledger of the IDs it gave, through the Ledger trait.
Each ID is live while what it names exists and retired once that is
deleted.
Reserve and Retire
Holding its own lock, the owner calls reserve, which draws
candidates until one is neither live nor retired and holds it. On delete
the owner retires the ID, which then stays out of reach of anything new.
Table::revive takes it back only for the very thing it named, brought
back whole, such as an agent restored from its backup. A
ledger that refuses reserve_attempts, 32, candidates in a row is
broken, and reserve says so rather than drawing forever.
Arrivals
An ID that arrives from elsewhere, such as a copy from another machine,
goes through admit, which refuses one that is live or retired and
holds any other. Table is a ledger as two sets, live and retired,
which an owner keeps in its own state.
In Output
Every --json field and log line writes an ID as <kind>:<id>, under
a field naming its axis: principal, workload, execution,
parent or resource, from src/output.toml
(axes, is_axis). A list inherits its field's name, so an agent's
teams are "teams": [{"resource": "group:<id>"}], never a bare ID or
one under id. A reader takes an ID back with candidate_of, which
answers only for the kind it expects. The testing kit's
ids::assert_named holds every command's output to this.