api.coopoperator

Glossary

Every word on these screens that is not plain English, in a sentence or three. A word with a dotted underline anywhere in this view links here.

The basics

Commons
The shared, public set of event and place records that Beacon and any other app can read. Anyone can publish into it, and every record stays whole in its author's own repo.See also api.coop, Source, Curated record
api.coop
The service behind this view. It collects the commons into its own database, decides what is trusted each time it is read, and serves the result to apps and agents; operators also manage rules, scrapers and takedowns through it.See also AppView, Operator
AppView
A service that collects public records from the network into its own database, so apps can search and list them quickly. api.coop is the AppView for the commons; Beacon has its own.
Operator
A person or agent allowed to change things through api.coop: endorse rules, take records down, run scrapers. The commons root names each operator in a public record, so anyone can see who operates.See also Operator method, Read only
Operator method
One of the actions api.coop offers operators, such as taking a record down or endorsing a rule. Every button in this view calls exactly one, the same one an agent would call over the MCP door.
MCP door
The way AI agents talk to api.coop, through the standard Model Context Protocol. An agent can read the commons there and, if it is an operator, take the same actions a person takes here.
Read only
Without signing in you can see everything public, but every button that changes something stays off. Sign in as an operator to use them.
Staging
The test copy of the whole system, at beacon-staging.gitcoin.co. Changes run here before a release of them goes to production.

Accounts and who is who

DID
A decentralized identifier: an account's permanent ID, such as did:plc:abc123. It never changes, so this view links and matches every account by its DID.See also Handle
Handle
An account's readable name, such as alice.example.com. A handle can change at any time, so it is only shown, never used to decide who someone is: the DID is.
Repo
An account's own store of records, kept on its PDS. Every record lives in exactly one repo, and the repo's owner is the record's author.
PDS
A personal data server: the server that holds an account's repo and signs its changes. Operators sign in to this view with their PDS account.
App password
A separate password made for one app, so an account's main password is never typed here. This view uses it once to sign in and never stores it.
Source
Anyone who publishes records into the commons: a person, a collective, Beacon on behalf of a person, or a scraper. Each source publishes under its own account.See also Source record, Mirror
Commons root
The one account whose public endorsements decide which rules the commons trusts. Readers check its records every time they read, so deleting an endorsement untrusts that rule at once.
Adjudicator
api.coop's own account for decisions people make about pairs of records: whether two copies are the same thing or not. Its decisions count only while the commons root endorses it, like any rule.See also Decide
Shared operator token
A shared secret that also lets its holder act as an operator, for tools outside this view; this view signs in with the operator's own DID instead. Actions made with it are shown as made by the shared token.
Service-auth token
A short-lived note, signed by an operator's PDS, saying this DID is making this one call. api.coop checks it on every action and records the action under that DID.

Records

Record
One piece of data in an account's repo, such as one event or one place. Every record has a type and an address, its AT-URI.
Record type
What kind of thing a record is: an event, a place, a same-as claim. Each type has a name (its NSID) and a published schema (its lexicon); this view also calls it a kind or a collection.See also NSID, Lexicon
NSID
A record type's full name, written like a web address backwards: community.lexicon.calendar.event is the event type. This view shows the last part as its short name.
Lexicon
The published schema for a record type: which fields it has and what they mean. A record that does not fit its lexicon is refused.
AT-URI
A record's full address: at://, then its author's DID, its type and its key. Paste one into the search box to open that record.
Record key
The last part of a record's AT-URI, which tells it apart from its author's other records of the same type. Taking a record down asks you to type its key.
Sidecar
A record about another record, kept beside it instead of changing it: where it is, what it is the same as, where it came from. The original stays exactly as its author wrote it.See also Claim
Claim
A sidecar a rule or a person writes to say something about a record, such as its location or that it is the same as another. A claim counts only when its author is trusted; how it was made is a separate derivation.
Source record
A record as its source published it, before any merging. Several source records can describe one event; the curator folds them into one curated record.
Mirror
An account that copies public listings from elsewhere, such as a calendar website, into the commons. Today the mirrors are scrapers.
Upstream
Where a mirrored record came from: the web page or calendar a scraper read it from. Its source sidecar names that page and who to credit.See also Seen upstream, Missing upstream, Credit
Seen upstream
The upstream page still listed this item the last time its scraper looked. The time beside it says when that was.
Missing upstream
The upstream page no longer lists this item. The record is kept and marked missing rather than deleted, because nothing in the commons is overwritten.
Credit
Who to thank for a record and the licence it may be reused under, as the source's attribution record says.
Firehose
The live stream of every new, changed and deleted public record across the network. api.coop follows it, through Jetstream, to stay up to date.
Jetstream
A lighter form of the firehose that sends records as plain data. api.coop follows two: this system's own and the public network's.
Index
api.coop's own copy of the commons, kept in its database so it can answer quickly. Indexed means api.coop has stored a record, not that the record is trusted.See also Index now
Index now
Ask the rules to process a record now, then store what they made (the curated record and its provenance) in the index straight from the authors' repos, without waiting for the firehose to bring them.
Backfill
Reading the records that were published before api.coop started listening, by walking each server once. Backfilled records are left out of the latency figures.
createdAt
The time a record says it was made, as its author wrote it. Latency is measured from it, so a wrong clock can make a record look early or late.
Shared check
The test every reader of the commons runs on a record before storing it: does it fit its lexicon, and was it published somewhere it may be public. A record that fails is refused.
Rejection
A record api.coop refused when it arrived, because it failed the shared check. It is not served, and the reason is kept so its source can fix it.
Source space
A private store each scraper keeps beside its public records, for the raw pages it fetched, its crawl state and text it may not publish. It shares only what a rule needs, and only with that rule.
Cursor
A bookmark that says how far a reader has got, so it can pick up where it stopped: in a long list, in the label feed, or in a scraper's crawl.

Rules and the queue

Rule
A small program with its own account that reads records and writes claims about them: where an event is, which records are the same, whether something is spam. What it writes counts only while the commons root endorses it.See also Stage, Rules runner, Robot
Robot
This view's picture of a rule. Each rule gets its own robot, so it is easy to spot from screen to screen.
Rules runner
The service that runs most rules. It watches for new records, queues a job for each rule a record matters to, and publishes what the rules write.
Host
Who runs a rule: the rules runner, api.coop itself (for the adjudicator and takedowns), or nobody this view knows of, for a rule that is endorsed only.
Endorsed only
The commons root endorses this account, but no host says it runs it. It is listed so the endorsement can still be revoked.
Stage
Where in the chain a rule runs: before the merge, at the merge as the curator, or after the merge.
Before the merge
The rules that run on each source record: finding its coordinates, the place it is held at, and which other records are the same event or place. Their claims decide what the curator merges.
Curator
The rule that does the merge: it groups the records trusted rules call the same into a cluster and publishes one curated record for it, with its provenance.
After the merge
The rules that run once on each curated record, never on a source copy. Today that is the features rule, which answers questions about the record, may label it, and leaves a receipt.
Chain
The order a record meets the rules in: every before-the-merge rule, then the curator, then every after-the-merge rule.See also Sync chain
Sync chain
Running the whole chain for one record at once, on request, instead of waiting for the queue. Beacon asks for it when someone shares a public event, and an operator can ask for it with Index now, so the record shows up within seconds; an answer of pending means the chain did not finish in time.
Cluster lock
While the curator rewrites one cluster, it holds a lock so no other worker changes that cluster at the same time. The latency page shows how long the locks are held.
Job
One rule's work on one record. The queue holds a job for every rule and record that matter to each other.
Queue
The rules runner's list of jobs: what is waiting, what is done and what failed. Only operators see it, because job states can hint at private inputs.
Waiting
The job has not run yet, or is due to run again. A try number after it counts the attempts so far.
Done
The job ran and finished. It either wrote something about the record or had nothing to add.
Failed job
The job ran out of tries. Its error is shown beside it, and an operator can rerun it once the cause is fixed.
Record gone
The record the job was about has been deleted, so there is nothing left to run on.
Rerun
Queue a job, or all of one rule's jobs, to run again now with fresh tries. Use it after a fix, or after a rule's code or inputs changed.
Paused
A paused rule's jobs still queue, but none of them run until it is resumed. What it already published, and its endorsement, stay as they are.
Runs on
What a record must be like for a rule to work on it, such as an event that has a start time and has not ended. A record that does not qualify is skipped, not failed.
Reads and writes
The record types a rule takes in, and the ones it publishes. An endorsement trusts a rule only for the types it lists under writes.
Commit
One saved version of a program, named by a short code such as 5070ced. An endorsement names the exact commit it vouches for.
Runs newer code
The rule's host runs a different commit than the one the commons root endorsed. It stays trusted until an operator endorses the new commit or revokes the endorsement.
geocode
The rule that finds map coordinates for a place, or an event, that has an address but no coordinates, and writes them as a geo record.
venue
The rule that matches places to each other and events to the places they are held at, writing same-as, inside and held-at claims.
dedupe
The rule that spots copies of one event from different sources, and says which are the same and which only look alike.
migration
The rule that links records from the old Almanac account to their new copies, so old links keep working. It reads nothing and writes only when an operator imports a batch.
features
The rule that runs after the merge. It answers a fixed set of questions about each curated record (is it free, outdoors, family friendly), checks it for spam and obscene content, and leaves a receipt.See also Jev
takedowns
api.coop's own name as a labeler. When an operator takes a record down, api.coop publishes a !takedown label under this name, so other readers can honour it once the root endorses it.

Clusters and merging

Cluster
A group of source records that trusted rules say describe the same event or place, together with the one curated record made from them. A record no rule joined to another is a cluster of one.See also Merge, Readiness
Curated record
The one record the curator publishes for a whole cluster, in its own repo. Apps that want to show each event once read these.
Merge
Folding several copies of one event or place into one curated record, taking each field from the most reliable copy: a person's own record first, then live mirrors, then old copies.
Readiness
How far the merge got for a cluster: complete, partly merged or superseded. It lives on the provenance record, not on the curated record.See also Roll-up
Complete
Every rule the merge waits for had its say before the curator published. The curated record is as good as its inputs allow.
Partly merged
The curator waited two minutes for its rules and the places the event names, then published without what was missing. It rewrites the record when the rest arrives.
Superseded
Another curated record now covers these sources, usually because two clusters turned out to be one. Links to this one lead to the survivor.
Roll-up
One answer to whether a curated record is fully processed: its merge, plus a receipt for its current version from every endorsed after-the-merge rule.
Ready to read
Fully processed: merged, and every endorsed after-the-merge rule has processed the current version. Careful readers such as Beacon list only these.
Waiting on a rule
Merged, but at least one after-the-merge rule has not processed the current version yet. Done for an older version means the record changed since that rule last saw it.
Enrichment
What the rules add beside a record without changing it: map coordinates, the place an event is held at, answers about it.
Decide
An operator ruling that two records are the same thing, or not. The adjudicator publishes the decision, and the curator follows it while the commons root endorses the adjudicator.
Made by
Whether a claim came from a rule's fixed logic, from an AI model, or from a person. It is part of the claim's derivation.

Trust and moderation

Trusted
A record is trusted when the commons root endorses its author for that record type. Trust is decided again on every read, so revoking an endorsement untrusts past records too.
Endorsement
The commons root's public statement that it vouches for a rule: the code it runs, what it may write, its stage, and the labels it may give. Deleting it withdraws trust in everything that rule wrote.See also Revoke, Runs newer code
Revoke
Delete an endorsement or an operator's grant. Readers stop trusting that rule at once, or that operator's next call is refused.
Label
A short tag a rule puts on a record, such as spam. It counts only when its writer is endorsed to give that value; a trusted spam or obscene label hides the record.See also Labeler, Label feed
Labeler
An account that gives labels and publishes a key so readers can check its signature. Until it publishes that key, its labels are not taken and the records it would label wait.
Label feed
The stream of labels api.coop reads from the rules runner every few seconds. It checks each signature before storing a label.
spam
A label saying the record looks like spam. When its writer is trusted, api.coop and Beacon hide the record from every listing.
obscene
A label saying the record has obscene content. When its writer is trusted, api.coop and Beacon hide the record from every listing.
!takedown
The label api.coop publishes when an operator takes a record down, so other readers can hide it too. The leading exclamation mark marks a system label.
Taken back
Its labeler withdrew this label, so it no longer has any effect.
Takedown
An operator hiding a record from api.coop, with a reason. The record stays in its author's repo, and other readers decide for themselves.See also Restore, !takedown
Restore
Undo a takedown: api.coop serves the record again and withdraws its !takedown label.
Moderation
Checking records for spam and obscene content before they are listed. Listings with moderation wait for the after-the-merge rules; listings without it show a record as soon as it is curated.
Visible
A record an app reading api.coop can see: indexed, its account active, not taken down, and not hidden by a trusted label.

Running it

Scraper
A small program that reads one kind of outside source, such as a calendar platform, and publishes what it finds into the commons under its own account.See also Scraper runner, Source space
Scraper runner
The machine that runs the scrapers. It asks api.coop which are due, runs each at its pinned code, and reports how the run went.
Pinned code
The exact code a scraper runs: a commit of the scrapers repository, or a container image by its digest. A pin never moves, so a run is always the code that was registered.
Config
A scraper's settings, such as which calendars to read. They are set when the scraper is registered.
ok
The scraper run finished and reported success.
Running
The scraper run has started and has not reported back yet.
Failed run
The scraper run reported a failure, or could not start. Its log says why.
Lost
The scraper run never reported back within twelve hours. A lost run does not count against the schedule, so the scraper is due again.
Saw, published, missing, errors
What a scraper run counted: items it saw at the source, records it published or updated, items it marked missing, and errors on the way.
Release
A list of exact tested code versions and images, recorded so production can deploy exactly those. Recording one deploys nothing; promoting it to production is a separate human step.
Image digest
A fingerprint of one exact container image, starting sha256. Unlike a tag, it can never point at different code later.
Service health
Each service answers a health check with its state and the commit it runs. api.coop asks them when the staging page loads.
Setting
A value set where a service is deployed, written in capitals such as COMMONS_ROOT_DID. Changing one takes a redeploy, not a button here.
Jev
A paid question-answering model from TypeSafe that the features rule uses to answer questions about records. Each call costs money, so calls are capped each day.See also Daily cap, Grant
Daily cap
How many paid calls a budget may make each day. Past it, the rules wait for the next day or for an operator to grant more.
Grant
Extra paid calls an operator allows on top of the daily cap, for a stated reason and a set number of days.
Latency
How long something takes. Here, mostly: from when a source submits a record until readers can see its curated result.See also Median and 95th percentile
Median and 95th percentile
The median is the middle time: half are faster. The 95th percentile is the time that all but the slowest 5% beat.
Type to confirm
Every action with a consequence asks you to type its target, such as a rule's name or a record's key, before its button works. api.coop checks the typed value again.

Record types

Each opens a page about the type

Every record type this view can name. The ones marked private never reach the public commons, so api.coop never shows one.

The record schemas themselves are in the regenOS repository, under crates/regenos-lexicons/lexicons. Browse the records